أدلة الوسائط
ترحيل 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/SK | Authorization: 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 استخدام هذه المراجع المكافئة:
- إنشاء مهمة (متوافق مع Volc)
- الحصول على مهمة (متوافق مع Volc)
- سرد المهام (متوافق مع Volc)
- إلغاء مهمة (متوافق مع Volc)
قواعد جسم الطلب
- يقبل
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 ساعة.
تضيف مواد الشخصية الحقيقية إجراءين قبل التحميل:
يعيد الإجراء الثاني GroupId الذي تم التحقق منه. استخدم هذا المعرف مع CreateAsset؛ لا يمكن للعميل إنشاء مجموعة LivenessFace مباشرة.
قائمة التحقق من الترحيل
- استبدل مضيف الـ API بـ
https://api.tokenlab.sh. - استبدل توقيع AK/SK بمفتاح API من نوع Bearer خاص بـ TokenLab.
- احتفظ بطريقة REST الرسمية للمهمة، والمسار، وحالة أحرف جسم الطلب؛ احتفظ بـ Action والإصدار فقط لعمليات المواد أو التحقق.
- احتفظ بنفس
ProjectNameعبر طلبات المواد والتحقق ذات الصلة. - قم بتخزين معرفات المهام والمجموعات والأصول الخاصة بـ TokenLab التي تعيدها نقاط النهاية هذه.
- تحقق من استجابة واحدة للإنشاء والاستطلاع والسرد والخطأ قبل نقل حركة مرور الإنتاج.