المستوى: متوسط — يُفترض إنك جربت Claude API مرة على الأقل، وعارف ازاي تبعت request وتقرأ usage tokens، لكن مش شرط تكون اشتغلت على pipelines خلفية قبل كده.

لو شركتك بتشغّل 50,000 طلب Claude شهريًا لتصنيف مراجعات، ترجمة، أو استخراج بيانات من فواتير، نص الفاتورة دي ممكن تختفي بسطر كود واحد. الشرط الوحيد إنك مش محتاج الرد في نفس الثانية.

Message Batches API: ليه نص السعر مش حيلة تسويقية

Anthropic بتدّي خصم ثابت 50% على input و output tokens لما تبعت requests كـ batch بدل ما تبعتها واحدة واحدة. الخصم مش مرتبط بحجم الشركة ولا بعقد enterprise، ومش عرض مؤقت. مكتوب رسميًا في توثيق Anthropic، وأي حد عنده API key يقدر يستخدمه دلوقتي.

تخيّل المشهد ده قبل ما ندخل في الكود

عندك مغسلة ملابس. لو زبون جالك بقميص واحد، هتشغّل الغسالة عشانه. الكهربا بتاعت دورة كاملة، الصابون، المياه — كل ده عشان قميص واحد. لكن لو 50 زبون سابوا غسيلهم الصبح وقالولك "ابعتلنا بكره"، إنت بتجمّعهم في 5 دورات بدل 50 دورة. التكلفة لكل قميص بتنزل لأقل من النص.

الـ Batches API بيشتغل بنفس المنطق. Anthropic بتقدر تجدول الـ requests على أوقات الـ GPU الفاضية وتجمّع الشغل بكفاءة، وعشان كده بتخصم نص السعر مقابل إنك تستنى لحد 24 ساعة.

التعريف الدقيق: مش async عادي

أي async API request بيرجع رد لما المعالجة تخلص — يعني ثواني لـ minutes. الـ Message Batch مختلف: إنت بتبعت لحد 100,000 request في "وعاء" واحد، الـ batch بياخد ID، وبيدخل طابور معالجة بأولوية أقل من الـ realtime API. زمن الإنجاز المضمون ≤ 24 ساعة، لكن في الممارسة معظم الـ batches بتخلص في أقل من ساعة.

الفروق التقنية المهمة:

• كل request في الـ batch له custom_id إنت بتحدده، عشان تربط الردود بالـ inputs الأصلية لما ترجع مش بالترتيب.
• النتايج بترجع كـ JSONL stream، مش JSON واحد كبير، فممكن تعالجها بدون ما تحمّلها كلها في الذاكرة.
• كل request بيتعالج بشكل مستقل — فشل واحد ميأثرش على الباقي.
• الـ batch بياخد رسوم على كل request اتنفّذ، حتى لو إنت ألغيت الـ batch قبل ما يخلص بالكامل.

الكود التنفيذي: تصنيف 10,000 مراجعة عربية

السيناريو: عندك 10,000 review من عملاء على منتج، عايز تصنّف كل واحد كـ positive/negative/neutral. الـ realtime على معدل 200 RPM هياخد منك حوالي 50 دقيقة وفاتورة كاملة. الـ batch هيكلّفك النص ووقت معالجة متوقع 30 دقيقة لساعة.

import anthropic
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()
reviews = load_reviews_from_db()  # 10,000 مراجعة

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id=f"review-{r['id']}",
            params={
                "model": "claude-sonnet-4-6",
                "max_tokens": 50,
                "messages": [{
                    "role": "user",
                    "content": (
                        "صنّف المراجعة كـ positive أو negative أو neutral فقط:\n"
                        + r["text"]
                    ),
                }],
            },
        )
        for r in reviews
    ]
)
print(f"Batch created: {batch.id}")

بعد ما تبعت الـ batch، التطبيق بتاعك مش لازم يفضل شغّال مستني. اعمل polling في job منفصل أو cron، وعالج النتايج لما تجاهز.

import time

while True:
    status = client.messages.batches.retrieve(batch.id)
    if status.processing_status == "ended":
        break
    print(f"Pending: {status.request_counts.processing}")
    time.sleep(120)

results = {}
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        results[result.custom_id] = result.result.message.content[0].text
    else:
        results[result.custom_id] = None  # سجّل الفشل للـ retry لاحقًا

الأرقام الحقيقية على Claude Sonnet 4.6

الفرضية: 10,000 مراجعة، متوسط 500 input token + 50 output token لكل واحدة، نموذج claude-sonnet-4-6 بسعر input 3$ لكل مليون token و output 15$ لكل مليون.

• Realtime API: (10,000 × 500 × 3) ÷ 1,000,000 + (10,000 × 50 × 15) ÷ 1,000,000 = 15$ + 7.5$ = 22.5$.
• Batches API: نفس الحساب × 0.5 = 11.25$.
• التوفير: 11.25$ شهريًا على الـ workload الصغير ده. لو شغلت 1 مليون مراجعة شهريًا التوفير بيوصل 1,125$، أي ميزانية مهندس junior لشهر كامل.

الأرقام دي مأخوذة من سعر API الرسمي في توثيق Anthropic Pricing لشهر مايو 2026، والحساب deterministic مش تقدير.

الـ Trade-offs اللي مش ظاهرة في الإعلانات

1. الزمن غير مضمون داخل الـ 24 ساعة: الـ SLA بيقول لحد 24 ساعة. في وقت الضغط (إطلاق Anthropic موديل جديد، نهاية ربع سنة)، الـ batch ممكن يقرب من الحد. ما تستخدمش الـ batch لأي حاجة لو فشلت لساعتين بتأثر على المستخدم.
2. الـ orchestration شغل إضافي: إنت محتاج تخزّن state الـ batch في DB بتاعتك، تعمل polling في background worker، وتعالج النتايج لما ترجع. ده code مش موجود في الـ realtime path.
3. أخطاء جزئية لكل request: ممكن 1-3% من الـ requests ترجع errored أو expired بدل succeeded، وإنت محتاج retry logic للفاشلين فقط، مش الـ batch كله. لو نسيت الجزء ده هتفقد بيانات بصمت.
4. مفيش streaming: الردود بترجع كاملة لكل request. لو شغلك محتاج token-by-token (مثلًا UI بيعرض الرد وهو بيتولّد)، الـ batch مش الحل.
5. الـ rate limits منفصلة: الـ Batches بتتعامل مع limits خاصة بيها (in-progress requests cap وtokens/day)، مش نفس RPM/TPM بتاع الـ realtime. الميزة هنا إنك تقدر تشغّل realtime + batch بالتوازي بدون ما واحد ياكل من سعة التاني.

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

الـ Batches مش الحل في أربع حالات واضحة:

• أي شات أو رد على المستخدم في app — التأخير مرفوض، حتى دقيقة واحدة.
• Pipelines خطية بتعتمد على رد LLM في خطوة بعدها خلال ثواني.
• Workloads أصغر من 100 request — الـ overhead في الـ orchestration والـ polling بيلغي التوفير.
• تطبيقات regulated بتحتاج audit trail لحظي لكل decision (مثلًا قرارات قروض، أو فلترة محتوى عمره أقل من 18).

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

افتح dashboard الـ Anthropic بتاعك، وشوف أعلى 3 endpoints بتستهلك tokens. أي endpoint منهم بيشتغل في background job (تحليل documents يومي، LLM-as-judge على evals، تصنيف tickets ليلًا، توليد embeddings descriptions)، حوّله لـ Batches API الأسبوع ده. التحويل في 90% من الحالات تغيير سطرين كود (من client.messages.create لـ client.messages.batches.create + worker للـ polling). راقب الفاتورة لمدة أسبوع وقارن.

المصادر

• Anthropic Docs — Message Batches API: https://docs.anthropic.com/en/docs/build-with-claude/batch-processing
• Anthropic Pricing الرسمي: https://www.anthropic.com/pricing
• Anthropic Python SDK — batches module على GitHub: https://github.com/anthropics/anthropic-sdk-python
• Anthropic API Reference — Create Message Batch: https://docs.anthropic.com/en/api/creating-message-batches