أدلة الوسائط
توليد الفيديو
إنشاء مقاطع فيديو من نصوص، أو صور، أو ملفات صوتية، أو مقاطع موجودة مسبقاً
توليد الفيديو هو عملية غير متزامنة (asynchronous). يقوم POST /v1/videos/generations بإرجاع معرف المهمة (task ID) وعادةً ما يتضمن poll_url. قم بعمل استعلام (poll) عبر GET /v1/tasks/{id} باستخدام ذلك المعرف حتى يصبح الفيديو جاهزاً.
أرسل روابط HTTP(S) عامة أو روابط بيانات مدعومة في حقول الصور التي يقبلها النموذج الذي اخترته. تتبع هذه المدخلات مسار الوسائط العادي ولا تقوم بإنشاء معرفات مواد (material IDs) قابلة لإعادة الاستخدام تلقائياً.
عندما تكون المادة الصريحة لا تزال قيد التحضير، يقوم POST /v1/videos/generations بإرجاع 409 seedance_material_preparing مع inactive_asset_ids. قم بعمل استعلام عن تلك الأصول حتى تصبح ACTIVE (نشطة)، ثم أعد المحاولة باستخدام نفس معرفات المواد. إذا كان الأصل في حالة FAILED (فشل)، افحص error_message وقم بتصحيحه أو إعادة استيراده قبل إعادة المحاولة.
اختيار API
استخدم /v1/videos/generations لدمج ميزة فيديو جديدة. يمكن لعملاء Seedance 2.0 الحاليين الذين يرسلون بالفعل طلبات content[] الخاصة بـ Volcengine أو طلبات Action الاحتفاظ بهذا التنسيق عبر /api/v3. يستخدم كلا الـ API مفتاح TokenLab Bearer، لكن حقولهما وقيم الحالة الخاصة بهما مختلفة.
اختيار ما تريد إنشاءه
قم بتعيين operation بشكل صريح حتى يتمكن الـ API من التحقق من صحة الحقول المناسبة للمهمة.
| العملية | المدخلات المطلوبة أو المعتادة | حالة الاستخدام |
|---|---|---|
text-to-video | prompt | التوليد من النص فقط |
image-to-video | image_url أو image متوافق | تحريك صورة أولية |
reference-to-video | reference_images و video_urls / audio_urls اختيارية في النماذج المدعومة | الحفاظ على الهوية، أو النمط، أو مراجع الأصول |
start-end-to-video | start_image, end_image | التحكم في الإطارين الأول والأخير |
video-to-video | video_url أو task_id خاص بالنموذج | تحويل أو رفع دقة مقطع موجود |
motion-control | image_url بالإضافة إلى video_url | تطبيق مرجع حركة على موضوع ما |
audio-to-video | audio_url | تدفقات الفيديو المعتمدة على الصوت |
video-extension | task_id, extend_at, أو حقول تمديد خاصة بالنموذج | إكمال فيديو تم توليده |
اختيار نموذج
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
-H "Authorization: Bearer sk-your-api-key"استخدم معرف النموذج الذي يرجعه TokenLab، ثم اختر نوع التوليد باستخدام operation ومدخلات الوسائط المقابلة. لا تستخدم اسم العملية كمعرف للنموذج.
اقرأ تفاصيل النموذج المختار قبل الاعتماد على حقول متخصصة مثل reference_images أو kling_elements أو output_audio أو duration أو resolution أو aspect_ratio.
إنشاء فيديو
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1",
"operation": "text-to-video",
"prompt": "A calm cinematic shot of a cat walking through a sunlit garden",
"resolution": "720p",
"duration": 4,
"aspect_ratio": "16:9"
}'استخدم روابط https للوسائط التي يمكن جلبها من الإنترنت. يجب أن تظل الروابط المؤقتة صالحة حتى يقوم TokenLab بإنشاء المهمة.
حقول خاصة بالنموذج
يعتمد سلوك الصوت على النموذج المختار والعملية. قد يحتوي الفيديو على صوت حتى في حال عدم عرض محدد صوت. حذف المحدد يختلف عن إرسال false.
- نماذج
veo3.1وveo3.1-fastوveo3.1-liteتولد الصوت دائماً. قم بحذفoutput_audioأو إرسالtrue؛ حيث يتم رفضfalse. - نماذج
wan-2.6وwan-2.7تتضمن الصوت دائماً. قم بحذفoutput_audioأو إرسالtrue. كما أنwan-3.0وwan-3.0-primeتتضمن الصوت دائماً ولا تقبل أي محدد صوت. - نموذج
hailuo-h3يولد صوتاً أصلياً ولا يحتوي على مفتاح كتم. لا ترسل محدد صوت غير مدرج في تفاصيل النموذج. - نماذج
viduq3-proوviduq3-turboتولد الصوت افتراضياً؛ أرسلoutput_audio: false(أوaudio: false) للحصول على مخرجات صامتة. نماذج Seedance و PixVerse تقبلoutput_audio؛ أرسله بشكل صريح بدلاً من الاعتماد على القيمة الافتراضية. استخدمه فقط للعمليات التي تدرجه ضمن خياراتها. - توفر
audio_url/audio_urlsمدخلات أو مراجع صوتية. وهي ليست مفاتيح لإخراج الصوت. قد تحتفظ عمليات تحرير الفيديو، ونقل الحركة، ونقل النمط بالمقطع الصوتي للمدخلات؛ الحفاظ على الصوت المصدر لا يعني كتمه.
تحقق من تفاصيل النموذج لمعرفة القيم المسموح بها والأسعار المعتمدة على الصوت. في الحالات التي تدرج فيها النماذج هذه الخيارات، يجب أن تتوافق الأسماء المستعارة outputAudio و generate_audio والقيمة المنطقية audio مع output_audio عند دمجها. لا تفترض أن كل إصدار أو عملية ضمن عائلة النموذج تشترك في نفس عناصر التحكم في الصوت.
- بالنسبة لعائلة Seedance 2.0، اقرأ دليل نماذج فيديو Seedance 2.0 قبل استخدام مخرجات 4K، أو حدود دقة Fast/Mini، أو مدخلات مرجعية متعددة الوسائط.
- بالنسبة لـ
grok-imagine-videoفي عملية فيديو-إلى-فيديو، أرسلpromptورابطvideo_urlعام بصيغة.mp4عبر HTTPS. يعمل رابط نتيجة.mp4من TokenLab من مهمة سابقة. لا تستخدم هذه العملية محدداتdurationأوresolutionأوaspect_ratio.
PixVerse و HappyHorse
| نموذج | العمليات | المدخلات | الدقة | المدة | محدد الصوت |
|---|---|---|---|---|---|
pixverse-c1, pixverse-v6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | prompt; image_url; start_image + end_image; reference_images | 360p, 540p, 720p, 1080p | أي عدد صحيح من 1 إلى 15 ثانية | output_audio, الافتراضي false |
pixverse-v5.6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | نفس الحقول مثل C1 و V6 | 360p, 540p, 720p, 1080p | 5 أو 8 أو 10 ثوانٍ؛ 1080p يدعم 5 أو 8 ثوانٍ | output_audio, الافتراضي false |
happyhorse-1.0 | text-to-video, image-to-video, reference-to-video, video-to-video | prompt; image_url; reference_images; video_url + reference_images | 720p, 1080p | من 3 إلى 15 ثانية لعمليات التوليد؛ إخراج video-to-video محدود بـ 15 ثانية | لا ترسل output_audio |
في TokenLab، نماذج PixVerse أعلاه لا تقبل operation=video-extension.
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "pixverse-v6",
"operation": "image-to-video",
"prompt": "A slow camera move through a neon-lit street",
"image_url": "https://example.com/start.jpg",
"resolution": "1080p",
"duration": 5,
"output_audio": true
}'الحصول على الفيديو النهائي
قم باستدعاء GET /v1/tasks/{id} باستخدام id أو task_id من استجابة الإنشاء حتى تصبح المهمة completed (مكتملة) أو failed (فاشلة).
قد تُرجع مهام الفيديو المكتملة video_url أو video أو videos اعتماداً على النموذج وعدد المخرجات. تعامل مع billing_transaction_id كمعرف فوترة، وليس كمعرف للمهمة.
روابط نتائج الفيديو هي روابط وسائط من TokenLab تنتهي بنوع الملف، مثل .mp4، وتظل صالحة لمدة 30 يوماً. يقوم media_retention.items بالإبلاغ عن حالة حفظ كل عنصر وتاريخ انتهاء صلاحيته expires_at؛ يمكن للاستجابة حذف media_retention عندما لا تكون حالة الحفظ معروفة في الوقت المناسب، وسيظل الرابط يعمل. تُرجع المهام الفاشلة أو التي لا تزال قيد التنفيذ حقول فيديو فارغة. لقطات المهام غير المتزامنة لها دورة حياة منفصلة. راجع الاحتفاظ بالبيانات.
مآزق شائعة
- لا تستخدم مسارات الحالة الخاصة بكل نمط مثل
/v1/videos/generations/{id}في الكود الجديد؛ قم بعمل استعلام عبرGET /v1/tasks/{id}. - لا تدمج حقول الإطار الأول مع تدفقات الصور المرجعية المخصصة إلا إذا كانت تفاصيل النموذج تسمح بذلك.
- لا تفترض أن
durationتصف طول فيديو المرجع المدخل؛ فهي عادةً تتحكم في طول المخرج المولد. - أرسل
Idempotency-KeyمعPOST /v1/videos/generations. بعد انتهاء المهلة، أرسل نفس الطلب بنفس المفتاح للحصول على المهمة الأصلية. بدون مفتاح، تحقق مما إذا كانت المهمة قد تم إنشاؤها بالفعل قبل إعادة المحاولة.
مرجع API
| الموضوع | المرجع |
|---|---|
| إنشاء فيديو | إنشاء فيديو |
| الحصول على حالة الفيديو | الحصول على حالة الفيديو |
| الحصول على حالة المهمة | الحصول على حالة المهمة |
| إلغاء مهمة | إلغاء مهمة |
| الفوترة والأسعار | الفوترة والأسعار |
يقوم Hailuo H3-Max بتوليد مقاطع فيديو مدتها 5-15 ثانية بدقة 480p أو 768p من نص، أو إطار أول، أو إطارين أول وأخير. سير عمله الذي يركز على السرعة مفيد لتحويل فكرة لقطة بسرعة إلى مقطع قصير.
{
"model": "hailuo-h3-max",
"operation": "text-to-video",
"prompt": "A slow camera move through a quiet garden",
"resolution": "768p",
"duration": 5,
"aspect_ratio": "16:9"
}