أدلة الوسائط

توليد الفيديو

إنشاء مقاطع فيديو من نصوص، أو صور، أو ملفات صوتية، أو مقاطع موجودة مسبقاً

توليد الفيديو هو عملية غير متزامنة (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-videopromptالتوليد من النص فقط
image-to-videoimage_url أو image متوافقتحريك صورة أولية
reference-to-videoreference_images و video_urls / audio_urls اختيارية في النماذج المدعومةالحفاظ على الهوية، أو النمط، أو مراجع الأصول
start-end-to-videostart_image, end_imageالتحكم في الإطارين الأول والأخير
video-to-videovideo_url أو task_id خاص بالنموذجتحويل أو رفع دقة مقطع موجود
motion-controlimage_url بالإضافة إلى video_urlتطبيق مرجع حركة على موضوع ما
audio-to-videoaudio_urlتدفقات الفيديو المعتمدة على الصوت
video-extensiontask_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-v6text-to-video, image-to-video, start-end-to-video, reference-to-videoprompt; image_url; start_image + end_image; reference_images360p, 540p, 720p, 1080pأي عدد صحيح من 1 إلى 15 ثانيةoutput_audio, الافتراضي false
pixverse-v5.6text-to-video, image-to-video, start-end-to-video, reference-to-videoنفس الحقول مثل C1 و V6360p, 540p, 720p, 1080p5 أو 8 أو 10 ثوانٍ؛ 1080p يدعم 5 أو 8 ثوانٍoutput_audio, الافتراضي false
happyhorse-1.0text-to-video, image-to-video, reference-to-video, video-to-videoprompt; image_url; reference_images; video_url + reference_images720p, 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"
}

في هذه الصفحة