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

إنشاء دفعة (Batch)

إنشاء دفعة من ملف JSONL تم تحميله.

POST
/v1/batches

نظرة عامة

قم بتحميل ملف JSONL مع ضبط purpose=batch على القيمة المطلوبة، ثم استخدم معرف الملف الخاص به كـ input_file_id. تُرجع الدفعات المكتملة معرفات ملفات المخرجات والأخطاء.

ملف الإدخال

يجب أن يكون الملف بتنسيق JSONL: طلب واحد لكل سطر، بحد أقصى 50,000 سطر و 200 ميجابايت. بالنسبة لـ /v1/embeddings، يقتصر إجمالي عدد المدخلات عبر جميع الأسطر أيضًا على 50,000. يحتاج كل سطر إلى:

  • custom_id: سلسلة نصية، يجب أن تكون فريدة داخل الملف.
  • method: يجب أن تكون POST.
  • url: نفس قيمة endpoint الخاصة بالدفعة.
  • body: نص الطلب، مع تحديد model.
{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}}

ملاحظات

  • يجب أن تستخدم ملفات إدخال الدفعات purpose=batch.
  • completion_window هي 24h، وهي القيمة الافتراضية والوحيدة المتاحة.
  • تقبل metadata ما يصل إلى 16 زوجًا من السلاسل النصية: المفاتيح بحد أقصى 64 حرفًا، والقيم بحد أقصى 512 حرفًا.
  • تحدد output_expires_after وقت انتهاء صلاحية ملفات النتائج: anchor تكون created_at أو completed_at، و seconds بحد أقصى 30 يومًا.
  • قد يختلف ترتيب المخرجات عن ترتيب المدخلات. قم بمطابقة كل نتيجة باستخدام custom_id.
  • البث (Streaming) غير مدعوم داخل عناصر الدفعة.
  • نقاط النهاية (endpoints) المدعومة للعناصر هي /v1/chat/completions و /v1/embeddings. نقطة النهاية /v1/responses غير مدعومة.
  • يتم حجز التكلفة التقديرية عند إنشاء الدفعة. إذا كان الرصيد منخفضًا جدًا، سيتم إرجاع الخطأ 402.
  • الملف غير الصالح يُرجع الخطأ 400 مع ضبط param على input_file_id، وتحدد الرسالة السطر الذي يحتوي على الخطأ.

مثال

الطلب

cURL
curl -X POST "https://api.tokenlab.sh/v1/batches" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file_abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

قد تختلف أسعار الدفعات عن الطلبات المتزامنة. تحقق من الفاتورة النهائية لمعرفة الرسوم.

الاستجابة

200 OK
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "input_file_id": "file_abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1706000000
}

الحقول المهمة

idstring
معرف الدفعة (Batch ID).
statusstring
حالة الدفعة.
output_file_idstring|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"

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json