Batch API في Claude: قلّل تكلفة الطلبات الجماعية 50% بدون تعديل كود

مستوى المقال: محترف — يفترض إنك بنيت تطبيق فعلي على Claude API وعندك حجم طلبات يومي ≥ 1000 طلب، وعارف ازاي تتعامل مع async jobs.

لو بتعالج آلاف الطلبات اليومية على Claude (تلخيص مستندات، classification، توليد embeddings، تنظيف بيانات) وفاتورتك بتقترب من الـ 1000 دولار شهريًا، Batch API بينزّل التكلفة 50% بدون ما تغيّر سطر واحد في الـ business logic. الشرط الوحيد: قابل تستنى الردود لحد 24 ساعة.

المشكلة باختصار

الـ Messages API العادي بيتعامل مع كل طلب على حدة، بيرجّع الرد في ثوانٍ، ودي خدمة real-time. لكن مش كل workload محتاج رد فوري. لو عندك nightly job بيلخّص 5000 مستند، أو script بيولّد metadata لـ 50000 منتج كل أسبوع، إنت بتدفع تسعير real-time على شغل أساسه offline. ده تبذير حقيقي مش تحسين هامشي.

اللي بيحصل فعلاً في معظم تطبيقات الـ AI الناضجة: 60% من الطلبات بتيجي من background jobs، و40% بس من user-facing flows. ومع ذلك الفريق بيدفع نفس السعر على الاتنين.

تخيّل المشهد ده — مثال للي مش متعود على API pricing

تخيّل إنك صاحب مطعم. عندك زبون بيطلب delivery دلوقتي (عايزه ساخن خلال 30 دقيقة)، وزبون تاني بيحجز catering لمؤتمر بكرة الصبح (المهم النتيجة، مش الوقت). لو أنت ذكي، هتخصم 50% للزبون التاني، لإنك تقدر تحضّر طلبه بالليل ساعة المطبخ ما بيكونش مزحوم.

ده بالظبط الفرق بين Messages API و Batch API. الأول delivery فوري، التاني catering مجدول. شغل أساسه نتيجة، مش وقت رد.

التعريف العلمي الدقيق

Batch API هو endpoint منفصل (/v1/messages/batches) بيستقبل لحد 100,000 طلب في batch واحد، وبيرجّع كل النتائج خلال نافذة قصوى 24 ساعة (في الواقع غالبًا أقل من ساعة). كل طلب جوّه الـ batch بيتحاسب بسعر 0.5x من سعر الـ standard tier على نفس الموديل، input و output الاتنين. السقف الأقصى لحجم الـ batch المنفرد: 256 MB.

الافتراض المهم: الـ batch مش بيدّيك ضمان زمني أقل من الـ 24 ساعة. لو وصلتك النتيجة في 12 دقيقة، خد بالك إن ده صدفة وليس SLA.

إزاي تشغّله — كود Python شغّال على Anthropic SDK

import anthropic
import time

client = anthropic.Anthropic()

# 1. ابني الطلبات
documents = [...]  # 1000 مستند

requests = [
    {
        "custom_id": f"doc-{i}",
        "params": {
            "model": "claude-sonnet-4-6",
            "max_tokens": 1024,
            "messages": [
                {"role": "user", "content": f"لخّص المستند ده في 3 نقاط: {doc}"}
            ]
        }
    }
    for i, doc in enumerate(documents)
]

# 2. ابعت الـ batch
batch = client.messages.batches.create(requests=requests)
print(f"Batch ID: {batch.id}, status: {batch.processing_status}")

# 3. polling كل دقيقة
while True:
    status = client.messages.batches.retrieve(batch.id)
    if status.processing_status == "ended":
        break
    time.sleep(60)

# 4. استخرج النتائج
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        text = result.result.message.content[0].text
        save_summary(result.custom_id, text)
    elif result.result.type == "errored":
        log_error(result.custom_id, result.result.error)

السطر اللي بيخصم لك 50% هو batches.create. مفيش أي فرق في شكل الـ messages، ده نفس الـ format بالظبط اللي بتبعته للـ Messages API.

قبل وبعد — أرقام مقاسة من سيناريو واقعي

سيناريو: 10,000 طلب تلخيص يومي، متوسط 4000 input token + 500 output token لكل طلب، على claude-sonnet-4-6 بأسعار أبريل 2026 (3$ / 1M input، 15$ / 1M output).

• Standard Messages API: 10,000 × (4000 × 0.000003 + 500 × 0.000015) = 195 دولار/يوم → 5,850 دولار/شهر
• Batch API (خصم 50%): ≈ 97.5 دولار/يوم → 2,925 دولار/شهر
• الوفر الفعلي: 2,925 دولار/شهر، أو 35,100 دولار/سنة

الفارق ده عبارة عن راتب مهندس junior. ركّز إن التحسين الوحيد اللي عملته هو تغيير endpoint واحد.

trade-offs الحقيقية اللي بتدفعها مقابل الخصم

الخصم مش ببلاش. بتدفع ثمنه في 4 حاجات:

• زمن الرد: من ثوانٍ إلى ساعات. لو أي UX بيعتمد على رد فوري، Batch مش هيشتغل خالص.
• complexity إضافي في الـ infrastructure: محتاج storage مؤقت لتخزين الطلبات، job tracker لمتابعة كل batch، وآلية لاستلام النتائج وربطها بالسجلات في DB.
• retry policy مختلف: الفشل في طلب واحد مش بيفشل الـ batch كله، لكنك محتاج تعالج كل custom_id فاشل لوحده. لازم منطق reconciliation واضح.
• debugging أصعب: لو 50 طلب فشلوا بنفس السبب، عندك latency بالساعات بين السبب والاكتشاف، مش ثواني.

متى لا تستخدم Batch API

تجنّبه نهائيًا في الحالات دي:

• تطبيقات تفاعلية: chatbot، code completion، live search، أي حاجة المستخدم بيستنى الرد فيها على شاشته.
• workload صغير: أقل من 100 طلب يوميًا. التوفير المطلق صغير جدًا مقارنة بتعقيد إضافي.
• طلبات متسلسلة (chained): لو رد طلب لازم يدخل كـ input في طلب تاني، Batch مش مناسب لإنك مش هتقدر تبني الـ chain فورًا.
• SLA صارم أقل من ساعتين: حتى لو الـ batch بيخلص غالبًا في 30 دقيقة، Anthropic مش ضامنة الـ 30 دقيقة دي.
• طلبات بتعتمد على real-time data: لو السؤال محتاج بيانات من اللحظة دي بالظبط، الـ batch ممكن يرد بعد ساعات لما البيانات اتغيّرت.

الخطوة التالية الواضحة

افتح dashboard الفواتير على console.anthropic.com وحدّد أكبر job ثابت يومي عندك (تلخيص، تصنيف، تحليل لوجز، إثراء بيانات). لو حجمه ≥ 1000 طلب يوميًا والمستخدم النهائي مش بيستنى الرد بشكل فوري، حوّله لـ Batch API الأسبوع ده. قِس الفاتورة قبل وبعد لمدة أسبوعين، ولو الوفر فعلي خليه default في كل nightly pipeline جديد عندك.

المصادر

• Anthropic Message Batches API Documentation — docs.anthropic.com/en/api/creating-message-batches
• Anthropic Pricing Page (Batch tier 50% discount) — anthropic.com/pricing
• Anthropic Python SDK — github.com/anthropics/anthropic-sdk-python
• Anthropic Cookbook — Batch API examples — github.com/anthropics/anthropic-cookbook