الأساسيات

مرجع API

نقاط النهاية، المصادقة، ترويسات الاستجابة، والأخطاء

نظرة عامة

يدعم TokenLab نقاط النهاية المتوافقة مع OpenAI بالإضافة إلى تنسيقات طلبات Anthropic و Gemini. يمكن لعملاء OpenAI الحاليين استخدام /v1؛ اختر تنسيقاً آخر فقط عندما يحتاج تطبيقك إلى سلوك خاص بذلك الـ API. POST /v1/responses اختياري ويعتمد على دعم النموذج.

عنوان URL الأساسي

https://api.tokenlab.sh

المصادقة

تستخدم طلبات النماذج مفتاح API الخاص بـ TokenLab. ترويسة المصادقة القياسية هي:

Authorization: Bearer sk-your-api-key

تعتبر GET /v1/models و GET /v1/models/{model} و GET /v1/models/{model}/pricing و GET /v1/pricing عامة ولا تحتاج إلى مفتاح. تقبل Anthropic Messages أيضاً x-api-key؛ بينما تقبل Gemini x-goog-api-key أو ?key= بالإضافة إلى مصادقة Bearer. تتطلب /v1/management/* رمز إدارة (mt-...).

احصل على مفتاح API الخاص بك من لوحة التحكم.

سياسة التسليم

تقبل طلبات التوليد X-TokenLab-Delivery-Policy: auto | verified | official. تتجاوز ترويسة الطلب إعداد مفتاح API، والذي بدوره يتجاوز الإعداد الافتراضي لمساحة العمل (Workspace).

  • Auto يستخدم TokenLab Verified عند توفره، ثم Official إذا لزم الأمر. أنت تدفع مقابل الخيار الذي يكمل طلبك.
  • TokenLab Verified هو تسليم تم التحقق منه بواسطة TokenLab. يتم تطبيق سعر Verified.
  • Official يحاسب بالسعر الرسمي، وهو السعر المعلن من قبل صانع النموذج.
  • تستخدم جلسات Realtime مفتاح API أو إعداد مساحة العمل ولا تقبل تجاوز الطلب.

ترجع الترويسة غير الصالحة 400. إذا كان الخيار المطلوب غير متاح، يرجع TokenLab 503 delivery_tier_unavailable ومعرف طلب. اقرأ retryable: عندما لا يكون للعملية المحددة إمداد، تكون القيمة false. لا تكرر نفس الطلب دون تغيير.

تقبل صفحات API التي تحتوي على نموذج طلب مفتاح API الخاص بـ TokenLab وترسل طلبات حقيقية. تستخدم هذه الطلبات رصيد حسابك وحدوده. يمكنك أيضاً استخدام cURL أو Postman أو SDK.

نقاط النهاية المدعومة

الدردشة وتوليد النصوص

نقطة النهايةالطريقةالوصف
/v1/chat/completionsPOSTإكمال الدردشة المتوافق مع OpenAI
/v1/messagesPOSTالرسائل المتوافقة مع Anthropic
/v1/messages/count_tokensPOSTحساب الرموز (tokens) المدخلة لطلب الرسائل
/v1/messages/batchesPOST, GETإنشاء و سرد دفعات الرسائل
/v1/messages/batches/{message_batch_id}GET, DELETEاسترجاع أو حذف دفعة رسائل
/v1/messages/batches/{message_batch_id}/resultsGETقراءة النتائج
/v1/messages/batches/{message_batch_id}/cancelPOSTإلغاء دفعة رسائل
/v1/responsesPOSTAPI استجابات OpenAI
/v1/responses/{id}GET, DELETEاسترجاع أو حذف استجابة مخزنة
/v1/responses/compactPOSTضغط سياق محادثة الاستجابات
/v1/translationsPOSTترجمة نص إلى نص

التضمينات (Embeddings) وإعادة الترتيب (Rerank)

القرارات

نقطة النهايةالطريقةالوصف
/v1/systemonePOSTتقييم أسئلة القرار المكتوبة

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

نقطة النهايةالطريقةالوصف
/v1/filesPOST, GETرفع و سرد الملفات
/v1/files/{file_id}GET, DELETEاسترجاع أو حذف ملف
/v1/files/{file_id}/contentGETتنزيل محتوى الملف
/v1/batchesPOST, GETإنشاء و سرد الدفعات
/v1/batches/{batch_id}GETاسترجاع دفعة
/v1/batches/{batch_id}/cancelPOSTإلغاء دفعة

الصور

نقطة النهايةالطريقةالوصف
/v1/images/generationsPOSTتوليد صور من نص
/v1/images/editsPOSTتعديل الصور
/v1/images/variationsPOSTإنشاء تنويعات للصور
/v1/images/generations/{id}GETمسار حالة التوافق لاستجابات الصور القائمة على المهام

قد تعيد نماذج الصور صورة جاهزة أو مهمة غير متزامنة. إذا كانت الاستجابة تتضمن status: "pending" أو معرف مهمة، قم بعمل استطلاع (poll) لـ GET /v1/tasks/{id}.

الصوت

نقطة النهايةالطريقةالوصف
/v1/audio/speechPOSTتحويل النص إلى كلام (TTS)
/v1/audio/transcriptionsPOSTتحويل الكلام إلى نص (STT)
/v1/audio/translationsPOSTترجمة الكلام إلى نص إنجليزي

الوقت الفعلي (Realtime)

نقطة النهايةالطريقةالوصف
/v1/realtime?model={model}WSجلسات WebSocket في الوقت الفعلي

استخدم /v1/realtime لترقيات WebSocket. يرجع GET /v1/realtime العادي بيانات تعريف نقطة النهاية. هذا ليس واجهة REST الخاصة بـ OpenAI Realtime؛ حيث أن سر العميل (client-secret)، والمكالمات، ونقاط نهاية الجلسات التجريبية القديمة غير متوفرة.

الفيديو

نقطة النهايةالطريقةالوصف
/v1/videos/generationsPOSTإنشاء مهمة توليد فيديو
/v1/videos/generations/{id}GETمسار حالة التوافق
/v1/videos/assetsPOST, GETإنشاء وسرد أصول مواد Seedance
/api/v3/contents/generations/tasksPOST, GETمهام Seedance بتنسيق طلب Volcengine

قم بعمل استطلاع لـ GET /v1/tasks/{id} باستخدام id المهمة. يظل /v1/videos/generations/{id} متاحاً لعمليات التكامل الحالية.

المهام غير المتزامنة

نقطة النهايةالطريقةالوصف
/v1/tasks/{id}GETحالة أي مهمة غير متزامنة
/v1/tasks/{id}DELETEإلغاء مهمة غير متزامنة

قم بعمل استطلاع لـ GET /v1/tasks/{id} لكل مهمة غير متزامنة: الصور، الفيديو، الموسيقى، ثلاثية الأبعاد، العوالم، وتحويل الصوت غير المتزامن. استخدم id أو task_id من استجابة الإنشاء. ترجع استجابة إنشاء العوالم poll_url تحت /v1/worlds/generations/{id}؛ قم بعمل استطلاع لـ /v1/tasks/{id} هناك أيضاً. مسارات الحالة لكل نمط في هذه الصفحة هي نقاط نهاية توافق لعمليات التكامل الحالية.

الموسيقى

نقطة النهايةالطريقةالوصف
/v1/music/generationsPOSTإنشاء مهمة توليد موسيقى
/v1/music/generations/{id}GETمسار حالة التوافق

التوليد ثلاثي الأبعاد

نقطة النهايةالطريقةالوصف
/v1/3d/generationsPOSTإنشاء مهمة توليد نموذج ثلاثي الأبعاد
/v1/3d/generations/{id}GETمسار حالة التوافق

العوالم

نقطة النهايةالطريقةالوصف
/v1/worlds/generationsPOSTإنشاء مهمة توليد عالم
/v1/worlds/listPOSTسرد العوالم
/v1/worlds/{id}GET, DELETEاسترجاع أو حذف عالم
/v1/worlds/media-assets/prepare-uploadPOSTتحضير رفع أصل وسائط

النماذج والأسعار

نقطة النهايةالطريقةالوصف
/v1/modelsGETسرد جميع النماذج المتاحة
/v1/models/{model}GETالحصول على معلومات نموذج محدد
/v1/models/{model}/pricingGETالحصول على أسعار نموذج واحد
/v1/pricingGETسرد أسعار النماذج

Gemini (v1beta)

دعم تنسيق Google Gemini API الأصلي:

نقطة النهايةالطريقةالوصف
/v1beta/modelsGETسرد النماذج التي تقبل طلبات Gemini
/v1beta/models/{model}GETالحصول على نموذج
/v1beta/models/{model}:generateContentPOSTتوليد محتوى
/v1beta/models/{model}:streamGenerateContentPOSTتوليد محتوى متدفق
/v1beta/models/{model}:countTokensPOSTحساب الرموز
/v1beta/files, /v1beta/cachedContentsPOST, GET, DELETEملفات Gemini والمحتوى المخزن مؤقتاً

تدعم نقاط نهاية Gemini مصادقة معامل الاستعلام ?key= بالإضافة إلى رمز Bearer القياسي.

الإدارة

يدير /v1/management/* الرصيد، ومفاتيح API، وخطافات الويب (webhooks) باستخدام رمز إدارة. راجع واجهة برمجة تطبيقات الإدارة.

تنسيق الاستجابة

تحتفظ كل نقطة نهاية بتنسيق API الخاص بها. تستخدم أمثلة النجاح والخطأ أدناه تنسيق Chat Completions.

استجابة النجاح

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-5.6-terra",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

ترويسات الاستجابة

استخدم هذه الترويسات عندما تكون موجودة.

الترويسةالوصف
X-Request-IDمعرف الطلب للدعم وتصحيح الأخطاء
X-Routing-Time-MSغير متدفق: إجمالي الوقت بالمللي ثانية حتى وصول استجابة المنبع، بما في ذلك الانتظار والاستدلال لدى المنبع. متدفق: دائماً 0. ليس قياسًا للتوجيه أو الانتظار.
X-Task-IDمعرف المهمة غير المتزامنة العام للاستجابات القائمة على المهام
X-Billing-Transaction-IDمعرف معاملة الفوترة بعد الفوترة النهائية

قد تتضمن رفض الطلبات الرسمية upstream مع الخطأ الذي أبلغت عنه الخدمة واسم الخدمة العام. راجع معالجة أخطاء API.

استجابة الخطأ

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}

حدود المعدل (Rate Limits)

تعتمد الحدود على فئة الحساب وتطبق لكل مفتاح API. تحمل استجابة 429 ترويسات Retry-After و X-RateLimit-Limit و X-RateLimit-Remaining و X-RateLimit-Reset. راجع حدود المعدل لمعرفة الفئات وكيفية إعادة المحاولة.

مواصفات OpenAPI

مواصفات OpenAPI

تنزيل مواصفات OpenAPI 3.1 الكاملة

في هذه الصفحة