أدلة الوسائط

ترحيل Seedance من Volcengine

احتفظ بتنسيق طلبات Volcengine وقم بتحويل Seedance إلى TokenLab

إذا كان تطبيقك يستخدم بالفعل واجهة برمجة تطبيقات (API) Seedance الخاصة بـ Volcengine، فيمكنك الاحتفاظ بمسارات REST الخاصة بها، وجسم الطلب content[]، وحقول الاستجابة، وcallbacks، وإجراءات (Actions) المواد المكتوبة بصيغة PascalCase. قم بتغيير مضيف الـ API واستبدل توقيع AK/SK بمفتاح API خاص بـ TokenLab.

ما الذي يتغير

التغييرعميل Volcengine الحاليTokenLab
Base URLنقطة نهاية Volcengine الخاصة بكhttps://api.tokenlab.sh/
المصادقةتوقيع طلب AK/SKAuthorization: Bearer <TOKENLAB_API_KEY>
نقل المهاممسارات REST الرسمية /api/v3/contents/generations/tasksمحفوظ
إجراءات المواد/التحققمعاملات الاستعلام Action و Versionمحفوظ
جسم المهمةcontent[] بنمط Volcengineمحفوظ
جسم المادةحقول PascalCase مثل GroupId و ProjectNameمحفوظ
النتيجة غير المتزامنةدورة حياة مهمة Volcengineمعرف مهمة cgt-... في TokenLab مع الاستطلاع (polling) و callback اختياري

الطلبات الموقعة بـ AK/SK فقط ستعيد 401 AuthenticationError. يجب أن يتضمن كل طلب إلى TokenLab ترويسة Authorization: Bearer <TOKENLAB_API_KEY>.

اختيار نقطة النهاية

العميل الحالينقطة نهاية TokenLab
عميل مهام REST الخاص بـ Volcengine/api/v3/contents/generations/tasks ومسارات المهام الخاصة بها
عميل إجراءات المواد أو التحققPOST /?Action=...&Version=2024-01-01 أو POST /api/v3?Action=...&Version=2024-01-01

بالنسبة لمهام الفيديو، احتفظ بطريقة REST والمسار وجسم JSON الحاليين. تستمر طلبات المواد والتحقق في استخدام معاملات الاستعلام Action و Version. تقبل نقطة نهاية Action أيضاً إجراءات المهام CreateContentsGenerationsTasks و GetContentsGenerationsTask و ListContentsGenerationsTasks و DeleteContentsGenerationsTasks؛ استخدم مسارات REST للأعمال الجديدة.

مسارات المهام الرسمية

الطريقة والمسارالغرض
POST /api/v3/contents/generations/tasksإنشاء مهمة فيديو
GET /api/v3/contents/generations/tasks/{id}قراءة مهمة واحدة
GET /api/v3/contents/generations/tasksسرد المهام
DELETE /api/v3/contents/generations/tasks/{id}إلغاء مهمة لا تزال في قائمة الانتظار. المهمة التي بدأت ستعيد 409 task_not_cancellable

يمكن لعملاء REST استخدام هذه المراجع المكافئة:

قواعد جسم الطلب

  • يقبل content[] عناصر من نوع text و image_url و video_url و audio_url و draft_task.
  • بالنسبة لـ image_url، احذف role أو استخدم first_frame للتحويل من صورة إلى فيديو. استخدم last_frame مع إطار أول، أو reference_image للتحويل من مرجع إلى فيديو.
  • يمكن استخدام URI مادة عام مثل asset://asset-YYYYMMDDHHMMSS-xxxxx حيثما يقبل سير عمل Seedance المحدد دور الوسائط ذلك.
  • يقبل جسم REST الحقول الرسمية فقط، بما في ذلك model و content و ratio و duration و resolution و generate_audio و watermark و return_last_frame و seed و execution_expires_after و safety_identifier. تعتمد القيم الافتراضية على النموذج: generate_audio تكون false لنماذج seedance-2.0 و true لنماذج seedance-2.5، و duration تكون 5 لنماذج seedance-2.0 و -1 لنماذج seedance-2.5. يقبل تنسيق REST هذا قيم resolution التالية: 480p و 720p و 1080p (480p و 720p لـ seedance-2.5) ولكن ليس 4k، الذي يقبله فقط الـ API الموحد /v1/videos/generations. ترفض seedance-2.5 كلاً من seed و frames و camera_fixed.
  • يقبل callback_url نقطة نهاية HTTP(S) عامة. يرسل TokenLab نفس جسم استعلام المهمة لحالات queued و running و succeeded و failed و expired؛ فقط succeeded و failed تتبع السلوك الرسمي: مهلة زمنية مدتها خمس ثوانٍ، وإعادة محاولة عندما لا تقر نقطة النهاية الخاصة بك بالإشعار.

مثال REST مصغر

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": "seedance-2.5",
    "content": [
      {"type":"text","text":"A cinematic product reveal"},
      {"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'

قم بتخزين معرف cgt-... الذي تم إرجاعه. استمر في الاستطلاع حتى تصبح الحالة status هي succeeded أو failed أو cancelled أو expired؛ لا تتعامل مع استجابة الإنشاء على أنها فيديو مكتمل. إذا قمت بتوفير callback_url، اسمح بإشعارات succeeded أو failed المتكررة واستمر في الاستطلاع كمسار استرداد.

حافظ على فصل أنواع v1 و v3

لا تقم بإعادة استخدام هيكل استجابة /v1/tasks/{id} لهذه النقطة النهائية. يبلغ الـ API الموحد v1 عن حالات pending و processing و completed و failed؛ بينما يبلغ API v3 المتوافق مع Volc عن حالات queued و running و succeeded و failed و cancelled و expired. تمثل استجابة v3 الرسمية أيضاً duration كسلسلة نصية JSON وتحذف error في المهام غير الفاشلة.

للاسترداد الآمن بعد مهلة الإنشاء أو انقطاع الاتصال، أضف Idempotency-Key فريداً إلى طلب إنشاء REST. إعادة محاولة نفس الجسم بنفس المفتاح ستعيد معرف cgt-... الأصلي؛ بينما نفس المفتاح مع جسم مختلف سيعيد 409.

المواد والتحقق من الشخصية الحقيقية

تدعم نقطة نهاية Action نفسها أيضاً عمليات المواد العشر وعمليات مجموعات المواد. راجع إجراءات المواد (متوافق مع Volc) للحصول على أجسام PascalCase الدقيقة، والفلاتر، والترقيم، وغلاف الاستجابة، وعناوين URL للمواد التي تدوم 12 ساعة.

تضيف مواد الشخصية الحقيقية إجراءين قبل التحميل:

  1. إنشاء جلسة تحقق مرئي
  2. الحصول على نتيجة التحقق المرئي

يعيد الإجراء الثاني GroupId الذي تم التحقق منه. استخدم هذا المعرف مع CreateAsset؛ لا يمكن للعميل إنشاء مجموعة LivenessFace مباشرة.

قائمة التحقق من الترحيل

  1. استبدل مضيف الـ API بـ https://api.tokenlab.sh.
  2. استبدل توقيع AK/SK بمفتاح API من نوع Bearer خاص بـ TokenLab.
  3. احتفظ بطريقة REST الرسمية للمهمة، والمسار، وحالة أحرف جسم الطلب؛ احتفظ بـ Action والإصدار فقط لعمليات المواد أو التحقق.
  4. احتفظ بنفس ProjectName عبر طلبات المواد والتحقق ذات الصلة.
  5. قم بتخزين معرفات المهام والمجموعات والأصول الخاصة بـ TokenLab التي تعيدها نقاط النهاية هذه.
  6. تحقق من استجابة واحدة للإنشاء والاستطلاع والسرد والخطأ قبل نقل حركة مرور الإنتاج.

في هذه الصفحة