إنشاء مهمة (متوافقة مع Volc)

نظرة عامةCopy Anchor Link

يمكن لعملاء Seedance الحاليين بنمط Volc استخدام TokenLab عن طريق تغيير عنوان API والمفتاح.

راجع أيضاً نماذج فيديو Seedance 2.0 و توليد الفيديو.

المصادقة ونقاط النهاية (Endpoints)Copy Anchor Link

• استخدم Authorization: Bearer <TOKENLAB_API_KEY>.
• لا يتم قبول توقيع Volc AK/SK. يجب أن تتضمن الطلبات مفتاح TokenLab Bearer.
• استخدم مسار المهمة الرسمي: POST /api/v3/contents/generations/tasks.

قواعد المحتوىCopy Anchor Link

• type: "text" هو نص المطالبة (prompt).
• type: "image_url" بدون role، أو مع role: "first_frame"، يتم التعامل معه كإطار أول.
• يجب إقران role: "last_frame" بإطار أول.
• تُستخدم role: "reference_image" و reference_video و reference_audio كمرجع.
• تقبل image_url.url رابط صورة عام أو معرف مورد (URI) مثل asset://asset-YYYYMMDDHHMMSS-xxxxx. يحدد role ما إذا كانت تلك المادة عبارة عن إطار أول، أو إطار أخير، أو صورة مرجعية.
• لا تخلط بين مدخلات الإطار الأول/الأخير ووسائط المرجع في طلب واحد.
• يتم رفض الحقلين material_asset_id وmaterial_asset_ids على المستوى الأعلى. ضع URI مادة TokenLab في image_url.url. يُدعم priority في Seedance 2.5 فقط.

ملاحظات حول المعلماتCopy Anchor Link

duration عدد صحيح من الثواني؛ تحدد القيمة -1 المدة التلقائية. تختلف القيم الافتراضية والحدود حسب النموذج:

في Seedance 2.5، تتطلب طلبات الإطار الأول، والإطارين الأول والأخير، وتمديد الفيديو، والفيديو إلى الفيديو ratio: "adaptive". ويتطلب الفيديو إلى الفيديو أيضًا duration: -1. يقبل output_format القيمتين mp4 أو mov في Seedance 2.5 فقط.

• تقبل ratio القيم 16:9 أو 4:3 أو 1:1 أو 3:4 أو 9:16 أو 21:9 أو adaptive.
• يتم قبول watermark و return_last_frame و seed و execution_expires_after و safety_identifier عندما تكون صالحة للنموذج المحدد.
• قد تشير callback_url إلى نقطة نهاية HTTP(S) عامة.

تسليم رد الاتصال (Callback)Copy Anchor Link

عند وجود callback_url، يرسل TokenLab طلب HTTP POST عند تغير حالة المهمة. حالات رد الاتصال هي queued و running و succeeded و failed و expired. يتطابق نص JSON مع استجابة get-task.

تؤكد استجابة 2xx نجاح التسليم. بالنسبة لحالتي succeeded و failed، إذا لم ينجح التسليم في غضون خمس ثوانٍ، تتم إعادة المحاولة حتى ثلاث مرات. يحتوي رد الاتصال على رأس محتوى JSON القياسي فقط ولا يحتوي على رؤوس تسليم خاصة بـ TokenLab. لا يتم اتباع عمليات إعادة التوجيه، ويتم رفض أهداف الشبكة الخاصة أو المحجوزة.

احفظ معرف المهمة. إذا لم يتم تسليم رد الاتصال، فلا يزال بإمكانك استرداد النتيجة باستخدام نقطة نهاية get-task.

إعداد الصورCopy Anchor Link

تُستخدم روابط صور HTTP(S) العامة وروابط data المدعومة كما أُرسلت، ولا تُحفظ تلقائيًا كمواد قابلة لإعادة الاستخدام. تستخدم مراجع asset://asset-... الصريحة مواد TokenLab الموجودة. يجري التحقق من الملكية والجاهزية قبل التوليد. إذا كانت المادة لا تزال قيد الإعداد، فانتظر حتى تصبح جاهزة ثم أعد المحاولة. عند فشل الإنشاء، افحص error.code وerror.message.

بالنسبة للمواد الموجودة، استخدم معرف asset-YYYYMMDDHHMMSS-xxxxx العام بدلاً من معرف الأصل الأصلي الذي تم إرجاعه بواسطة نظام آخر. يتحقق TokenLab من ملكية المادة قبل التوليد.

استجابة الإنشاءCopy Anchor Link

{
  "id": "cgt-20260102030405-a1b2c"
}

تحتوي استجابة الإنشاء على معرف المهمة فقط. احفظه حتى تتمكن من استرداد الحالة والنتائج في أي وقت.

منع المهام المكررةCopy Anchor Link

أرسل Idempotency-Key فريداً مع طلبات الإنشاء. إذا تم إغلاق الاتصال قبل وصول الاستجابة، أعد المحاولة باستخدام نفس مفتاح API ومفتاح التكرار (idempotency key) ونص الطلب:

• إذا تم إنشاء المهمة الأصلية، يعيد TokenLab نفس معرف cgt-... ويضيف Idempotency-Replayed: true.
• إذا كان الطلب الأصلي لا يزال قيد التسجيل، يعيد TokenLab الخطأ 409 IdempotencyRequestInProgress. أعد المحاولة لاحقًا بالمفتاح ونص الطلب نفسيهما.
• إعادة استخدام المفتاح مع نص مختلف يعيد 409 IdempotencyConflict ولا ينشئ مهمة ثانية أبداً.

ينطبق التكرار (Idempotency) على مسار إنشاء REST الرسمي v3. وهو لا يغير شكل استجابة JSON، ولا يتم استنتاجه من X-Request-ID أو من نصوص طلب متطابقة بدون مفتاح.

مثالCopy Anchor Link

إنشاء RESTCopy Anchor Link

curl https://api.tokenlab.sh/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

بالنسبة للمواد الموجودة، ضع كل معرف مورد (URI) في عنصر content[] الرسمي وحدد دوره:

[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]

الخطوة التاليةCopy Anchor Link

استخدم معرف cgt-... الذي تم إرجاعه مع الحصول على مهمة (متوافقة مع Volc) حتى تصل المهمة إلى حالة نهائية.

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "doubao-seedance-2-0-260128",    "content": [      {        "type": "text",        "text": "A cinematic forest at sunset"      },      {        "type": "image_url",        "role": "reference_image",        "image_url": {          "url": "https://example.com/ref.png"        }      }    ],    "ratio": "16:9",    "duration": 5,    "resolution": "720p",    "generate_audio": false  }'

{  "id": "string"}