الفيديو والمواد
إنشاء مهمة (متوافق مع Volc)
إنشاء مهمة Seedance باستخدام API المتوافق مع Volc.
نظرة عامة
يمكن لعملاء Seedance الحاليين بنمط Volc استخدام TokenLab عن طريق تغيير عنوان API والمفتاح.
تستخدم الأمثلة Seedance 2.0. تدعم نقطة النهاية هذه أيضاً Seedance 2.5 مع الاختلافات الخاصة بالنموذج الموضحة أدناه. تنطبق أمثلة URI لمواد TokenLab القابلة لإعادة الاستخدام في هذه الصفحة على Seedance 2.0.
راجع أيضاً نماذج فيديو Seedance 2.0 و توليد الفيديو.
المصادقة ونقاط النهاية
- استخدم
Authorization: Bearer <TOKENLAB_API_KEY>. - لا يتم قبول توقيع Volc AK/SK. يجب أن تتضمن الطلبات مفتاح TokenLab Bearer.
- استخدم مسار المهمة الرسمي:
POST /api/v3/contents/generations/tasks.
قواعد المحتوى
type: "text"هو نص المطالبة (prompt).type: "image_url"بدونrole، أو معrole: "first_frame"، يتم التعامل معه كإطار أول.- يجب إقران
role: "last_frame"بإطار أول. - يتطلب
type: "video_url"استخدامrole: "reference_video"، ويتطلبtype: "audio_url"استخدامrole: "reference_audio". يحددrole: "reference_image"صورة مرجعية. - حدود العناصر: يقبل Seedance 2.0 ما يصل إلى 16 عنصراً في
content(1 نص، 9 صور، 3 فيديوهات، 3 ملفات صوتية، 1draft_task). يقبل Seedance 2.5 ما يصل إلى 51 عنصراً (1 نص، 30 صورة، 10 فيديوهات، 10 ملفات صوتية، 1draft_task). - يقبل
image_url.urlرابط صورة عام أو URI لمادة مثلasset://asset-YYYYMMDDHHMMSS-xxxxx. يحددroleما إذا كانت تلك المادة إطاراً أول، أو إطاراً أخيراً، أو صورة مرجعية. - لا تخلط بين مدخلات الإطار الأول/الأخير ووسائط المرجع في طلب واحد.
- يقبل جسم طلب REST الحقول الموجودة في هذه الصفحة فقط. أي حقل آخر على المستوى الأعلى، بما في ذلك
material_asset_idوmaterial_asset_ids، سيعيد الخطأ400 UnsupportedParameter. ضع URI لمادة TokenLab فيimage_url.url.
ملاحظات المعلمات
يقبل model معرف نموذج TokenLab مثل seedance-2.0 أو seedance-2.5. يمكن للعملاء الحاليين الاستمرار في إرسال معرف نموذج Volcengine الذي يستخدمونه بالفعل لهذه النماذج. تعيد استجابة get-task قيمة model التي أرسلتها. القيمة غير المعروفة تعيد الخطأ 400 InvalidParameter.
duration هو رقم صحيح يمثل الثواني؛ -1 يختار المدة التلقائية. تختلف القيم الافتراضية والحدود حسب النموذج:
| المعلمة | Seedance 2.0 | Seedance 2.5 |
|---|---|---|
duration | 4–15 / -1 (الافتراضي: 5) | 4–30 / -1 (الافتراضي: -1) |
resolution | 480p, 720p, 1080p (الافتراضي: 720p) | 480p, 720p (الافتراضي: 720p) |
generate_audio | boolean (الافتراضي: false) | boolean (الافتراضي: true) |
priority | غير مدعوم | integer: 0–9 |
seed | integer: -1–4294967295 (الافتراضي: -1) | غير مدعوم |
execution_expires_after | 3600–259200 ثانية (الافتراضي: 172800) | 3600–259200 ثانية (الافتراضي: 172800) |
بالنسبة لـ 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(الافتراضي:adaptive). watermarkوreturn_last_frameهي قيم منطقية (الافتراضي:false).safety_identifierهو سلسلة نصية تصل إلى 64 حرفاً.- يقبل
service_tierالقيمةdefaultفقط؛ تعيدflexالخطأ400 UnsupportedParameter. - يقبل
toolsعنصراً واحداً على الأكثر،{"type": "web_search"}. draft: trueوframesوcamera_fixedغير مدعومة. يتم قبولcamera_fixed: falseلـ Seedance 2.0 فقط.- قد يشير
callback_urlإلى نقطة نهاية HTTP(S) عامة يصل طولها إلى 2,048 حرفاً.
تسليم رد الاتصال (Callback)
عند وجود callback_url، يرسل TokenLab طلب HTTP POST عند تغير حالة المهمة. حالات الرد هي queued و running و succeeded و failed و expired. يطابق جسم JSON استجابة get-task.
تؤكد استجابة 2xx نجاح التسليم. بالنسبة لحالتي succeeded و failed، إذا لم ينجح التسليم في غضون خمس ثوانٍ، تتم إعادة المحاولة حتى ثلاث مرات. يحتوي رد الاتصال على ترويسة محتوى JSON القياسية فقط ولا يحتوي على ترويسات تسليم خاصة بـ TokenLab. لا يتم اتباع عمليات إعادة التوجيه (Redirects)، ويتم رفض أهداف الشبكة الخاصة أو المحجوزة.
احفظ معرف المهمة (task ID). إذا لم يتم تسليم رد الاتصال، فلا يزال بإمكانك استرداد النتيجة باستخدام نقطة نهاية get-task.
إعداد الصور
تُستخدم روابط صور HTTP(S) العامة وروابط البيانات المدعومة كما هي؛ ولا يتم حفظها تلقائياً كمواد قابلة لإعادة الاستخدام. تستخدم مراجع asset://asset-... الصريحة مواد TokenLab الموجودة. يتحقق TokenLab من الملكية والجاهزية قبل التوليد. إذا كانت المادة المشار إليها لا تزال قيد الإعداد، فانتظر حتى تصبح جاهزة وأعد المحاولة؛ افحص error.code و error.message عند فشل الإنشاء.
بالنسبة للمواد الموجودة، استخدم المعرف العام asset-YYYYMMDDHHMMSS-xxxxx بدلاً من معرف الأصل الأصلي الذي تم إرجاعه بواسطة نظام آخر. يتحقق TokenLab من ملكية المادة قبل التوليد.
استجابة الإنشاء
{
"id": "cgt-20260102030405-a1b2c"
}تحتوي استجابة الإنشاء على معرف المهمة فقط. احفظه حتى تتمكن من استرداد الحالة والنتائج في أي وقت.
منع المهام المكررة
أرسل Idempotency-Key فريداً (1–255 حرفاً، بدون فواصل أسطر) مع طلبات الإنشاء. إذا تم إغلاق الاتصال قبل وصول الاستجابة، أعد المحاولة باستخدام نفس مفتاح API، ومفتاح التكرار (idempotency key)، وجسم الطلب:
- إذا تم إنشاء المهمة الأصلية، يعيد TokenLab نفس معرف
cgt-...ويضيفIdempotency-Replayed: true. - إعادة استخدام المفتاح مع جسم طلب مختلف يعيد
409مع الرمزidempotency_conflictولا ينشئ مهمة ثانية أبداً. - المفتاح الذي يزيد طوله عن 255 حرفاً أو يحتوي على فواصل أسطر يعيد
400 InvalidParameter.
لا يغير المفتاح شكل استجابة JSON. لا يستنتج TokenLab التكرارات من X-Request-ID أو من أجسام الطلبات المتطابقة بدون مفتاح.
مثال
إنشاء 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.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"}
}
]الأخطاء
تستخدم أخطاء REST الصيغة {"error": {"code", "message", "param", "type"}}. تعيد مشاكل الطلب 400 مع InvalidParameter أو UnsupportedParameter، ويعيد فقدان مفتاح Bearer الخطأ 401 AuthenticationError. الأخطاء الناتجة عن توليد الفيديو، مثل عدم كفاية الرصيد (402) أو تجاوز حد المعدل (429)، تحتفظ بحالة HTTP الخاصة بها.
تتوفر نفس العمليات أيضاً كإجراءات (Actions) وهي CreateContentsGenerationsTasks و GetContentsGenerationsTask و ListContentsGenerationsTasks و DeleteContentsGenerationsTasks على المسار POST /api/v3?Version=2024-01-01. يجب على عمليات التكامل الجديدة استخدام مسارات REST أعلاه.
الخطوة التالية
استخدم معرف cgt-... الذي تم إرجاعه مع الحصول على مهمة (متوافقة مع Volc) حتى تصل المهمة إلى حالة نهائية.
curl -X POST "https://example.com/api/v3/contents/generations/tasks" \ -H "Content-Type: application/json" \ -d '{ "model": "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 }'{ "id": "string"}التفويض
BearerAuth مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.
الموضع: header
الترويسات
سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.
القيم المتاحة
- "auto"
- "verified"
- "official"
مفتاح تم إنشاؤه بواسطة العميل لإنشاء مهمة REST متطابقة (idempotent)، بطول 1-255 حرفاً بدون فواصل أسطر. تحت نفس اعتماد TokenLab API، إعادة استخدام نفس المفتاح مع نفس جسم JSON يعيد معرف مهمة cgt الأصلي؛ إعادة استخدامه مع جسم مختلف يعيد 409 مع رمز idempotency_conflict. المفتاح الطويل جداً أو الذي يحتوي على فواصل أسطر يعيد 400. احتفظ بالاعتماد والمفتاح وجسم الطلب دون تغيير عند إعادة المحاولة بعد انتهاء المهلة أو انقطاع الاتصال.
1 <= length <= 255جسم الطلب
application/json
الاستجابة
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json