الملفات والدفعات

إنشاء دفعة رسائل (Message Batch)

ينشئ دفعة من طلبات الرسائل التي يتم تشغيلها بشكل غير متزامن.

POST
/v1/messages/batches

نظرة عامة

أرسل ما يصل إلى 100,000 طلب رسالة في استدعاء واحد. يتم تشغيل الدفعة بشكل غير متزامن. يعود الرد فوراً مع ضبط processing_status على in_progress. قم بـ استرجاع الدفعة حتى تصبح حالتها ended، ثم احصل على النتائج.

ملاحظات

  • يحتوي كل عنصر في requests على custom_id و params. تأخذ params نفس الحقول الموجودة في إنشاء رسالة، بما في ذلك max_tokens. لا يمكن للعناصر استخدام speed: "fast".
  • يتكون custom_id من 1 إلى 64 حرفاً أو رقماً أو شرطة سفلية أو واصلة، ويجب أن يكون فريداً داخل الدفعة.
  • يجب أن يكون كل نموذج في الدفعة متاحاً للعمليات المجمعة. ترفض TokenLab الطلب بالكامل مع رمز 400 إذا لم يكن النموذج متاحاً، أو إذا لم يكن هناك مسار واحد يمكنه خدمة جميع النماذج في الدفعة.
  • تحجز TokenLab التكلفة التقديرية عند قبول الدفعة وتعيد 402 إذا كان الرصيد لا يغطيها. بعد انتهاء الدفعة، تقوم TokenLab بتسوية استخدام الطلبات التي نجحت. قد تختلف أسعار الدفعات عن أسعار الطلبات المتزامنة.
  • إذا كان العنصر يشير إلى محتوى file_id، أرسل anthropic-beta: files-api-2025-04-14.
  • أرسل Idempotency-Key لإعادة محاولة طلب الإنشاء الذي انتهت مهلته بأمان. راجع إعادة المحاولة بأمان باستخدام مفتاح التكرار (idempotency key).

مثال

الطلب

cURL
curl -X POST "https://api.tokenlab.sh/v1/messages/batches" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Idempotency-Key: 6f1c2a9e-0b7d-4c1e-9a53-2d9f3a1b7c10" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "request-1",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Hello, Claude!"}]
        }
      },
      {
        "custom_id": "request-2",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Name three colors."}]
        }
      }
    ]
  }'

الاستجابة

200 OK
{
  "id": "msgbatch_01ABC123",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2026-11-01T10:00:00Z",
  "expires_at": "2026-11-02T10:00:00Z",
  "cancel_initiated_at": null,
  "archived_at": null,
  "results_url": null
}

حقول هامة

idstring
معرف دفعة الرسائل. استخدمه لاسترجاع الدفعة أو إلغائها أو حذفها وللحصول على نتائجها.
processing_statusstring
in_progress أو canceling أو ended.
request_countsobject
عدد الطلبات التي هي في حالة processing أو succeeded أو errored أو canceled أو expired.
expires_atstring
وقت انتهاء صلاحية الدفعة. الطلبات التي لم تنتهِ بحلول ذلك الوقت ستنتهي بحالة expired.
results_urlstring|null
رابط النتائج. يكون null حتى تنتهي الدفعة.

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

مفتاح اختياري يجعل طلب الإنشاء آمناً لإعادة المحاولة. أرسل قيمة فريدة جديدة، مثل UUID، لكل مهمة. إعادة المحاولة بنفس المفتاح ونفس نص الطلب تُرجع نتيجة طلب الإنشاء الأصلي، وعادةً ما تكون المهمة الأصلية، ولا تقوم بإنشاء أو إرسال أو احتساب تكلفة مهمة ثانية. يتم رفض نص الطلب المختلف الذي يستخدم مفتاحاً تم قبوله مسبقاً بالرمز 409. يتم تجاهل المفتاح الذي يتجاوز 255 حرفاً، وعندها لا يتمتع الطلب بحماية idempotency. راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.

الطول1 <= length <= 255

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json