الفيديو والمواد

إنشاء فيديو

بدء مهمة إنشاء فيديو

POST
/v1/videos/generations

نظرة عامة

عملية إنشاء الفيديو غير متزامنة (asynchronous). يعيد طلب الإنشاء الناجح معرف المهمة id (نفس قيمة task_id) و poll_url. قم باستدعاء GET /v1/tasks/{id} باستخدام هذا المعرف حتى تصبح status هي completed أو failed، ثم اقرأ video_url. راجع الحصول على حالة الفيديو.

  • يتم حفظ ملف النتيجة لمدة 30 يومًا. قم بتنزيله إذا كنت بحاجة إليه لفترة أطول؛ راجع الاحتفاظ بالبيانات.
  • يمكن إلغاء مهمة Seedance الموجودة في قائمة الانتظار باستخدام إلغاء المهمة.
  • يمكن حجز التكلفة عند قبول المهمة وتتم تسويتها عند انتهاء المهمة أو فشلها. راجع الفوترة والتسعير.
  • أرسل ترويسة Idempotency-Key لإعادة محاولة طلب الإنشاء بأمان بعد انتهاء المهلة.

يقبل كل نموذج عملياته وحقوله الخاصة. تسرد GET /v1/models/{model} (الحصول على النموذج)، لكل عملية، الحقول والدقات والمدد ونسب العرض إلى الارتفاع المقبولة. أي حقل أو قيمة خارج تلك القائمة ستُرجع 400 مع القيم المقبولة. قم بتعيين duration و resolution و aspect_ratio و output_audio بنفسك: عند حذف أحدها، يستخدم TokenLab القيمة الافتراضية للنموذج لهذه العملية، وإذا لم يتطابق أي خيار افتراضي، يُرجع الطلب 400 ويحدد اسم الحقل المطلوب تعيينه.

مدخلات الصوت والوسائط

يعتمد سلوك الصوت على النموذج المختار والعملية. قد يحتوي الفيديو على صوت حتى في حال عدم عرض محدد صوت. حذف المحدد يختلف عن إرسال 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 عند دمجها. لا تفترض أن كل إصدار أو عملية ضمن عائلة النموذج تشترك في نفس عناصر التحكم في الصوت.

استخدم عناوين https URL يمكن الوصول إليها بشكل عام للصور ومقاطع الفيديو والصوت، واحتفظ بها صالحة حتى تبدأ المهمة. يمكن أن يصل طول عنوان URL للوسائط إلى 8,192 حرفًا. تقبل بعض النماذج أيضًا عناوين URL لصور data: المضمنة (حتى 2,000,000 حرف لكل حقل)؛ وتعد عناوين URL أكثر موثوقية للملفات الكبيرة. لا تخلط بين base64 المضمن وعناوين URL البعيدة في نفس الطلب.

نص الطلب

modelstringالافتراضي: veo3.1

معرف نموذج الفيديو. اعرض نماذج الفيديو الحالية باستخدام قائمة النماذج (recommended_for=video)، ثم أرسل النموذج بشكل صريح.

PixVerse

  • نموذج: pixverse-c1, pixverse-v6, pixverse-v5.6
  • العمليات: text-to-video, image-to-video, start-end-to-video, reference-to-video
  • محدد الصوت: output_audio, الافتراضي false

في TokenLab، نماذج PixVerse أعلاه لا تقبل operation=video-extension.

HappyHorse

  • نموذج: happyhorse-1.0
  • العمليات: text-to-video, image-to-video, reference-to-video, video-to-video
  • محدد الصوت: لا ترسل output_audio
promptstring

وصف نصي للفيديو، حتى 10,000 حرف. تتطلب معظم العمليات وصفًا نصيًا؛ وتوضح تفاصيل النموذج الحالات التي لا تتطلب ذلك.

operationstring

وضع التوليد: text-to-video، image-to-video، reference-to-video، start-end-to-video، video-to-video، video-extension، أو motion-control. يدعم كل نموذج بعضاً منها فقط؛ بينما تُرجع العمليات الأخرى 400 unsupported_operation. إذا قمت بحذفه، يقوم TokenLab باستنتاجه من المدخلات: task_id مع extend_at أو extend_times يعطي video-extension، الصور المرجعية أو المواد تعطي reference-to-video، end_image تعطي start-end-to-video، مدخل الفيديو يعطي video-to-video، مدخل الصورة (image أو image_url أو image_urls أو start_image) يعطي image-to-video، وبخلاف ذلك يتم اختيار text-to-video. أرسله بشكل صريح لضمان فشل الحقول غير المتوافقة مبكراً.

image_urlstring

عنوان URL يمكن الوصول إليه بشكل عام لصورة الإطار الأول. تقبل نماذج Seedance 2.0 أيضًا asset://asset-YYYYMMDDHHMMSS-xxxxx لاستخدام مادة TokenLab بحالة ACTIVE كإطار أول. يُفضل استخدام عنوان https URL للحصول على أوسع توافق مع النماذج.

imagestring

صورة مضمنة كعنوان data URL (على سبيل المثال، data:image/jpeg;base64,...). تقبلها بعض النماذج فقط؛ بينما يعمل image_url على عدد أكبر منها.

image_urlsarray

عناوين URL للصور للنماذج التي تسرد هذا الحقل. راجع reference_images لمعرفة حدود العدد.

reference_imagesarray

صور مرجعية لـ reference-to-video، كعناوين https URL أو data URLs. يعتمد حد العدد على النموذج:

  • seedance-2.0 و seedance-2.0-fast و seedance-2.0-mini: ما يصل إلى 9 مراجع صور إجمالاً، بما في ذلك أصول المواد. تؤدي الزيادة إلى إرجاع 400 too_many_seedance_reference_images.
  • seedance-2.5: ما يصل إلى 30 مدخلاً للصور إجمالاً عبر image_urls و reference_images.
  • grok-imagine-video: ما يصل إلى 7، والحد الأقصى لـ duration هو 10 ثوانٍ. لا يقبل grok-imagine-video-1.5 و grok-imagine-video-1.5-preview صورًا مرجعية.
  • النماذج الأخرى: راجع تفاصيل النموذج. الطلب الذي يتجاوز الحد يُرجع 400 too_many_items.

تقبل نماذج Seedance 2.0 أيضًا asset://asset-YYYYMMDDHHMMSS-xxxxx لمادة TokenLab بحالة ACTIVE. لاختيار النموذج وحدود 4K وملاحظات Mini، راجع دليل نماذج فيديو Seedance 2.0. بالنسبة لـ grok-imagine-video، لا تجمع بين الصور المرجعية و image_url أو image.

start_imagestring

صورة الإطار الأول. عند استخدام end_image، يكون الطلب من نوع start-end-to-video. وبدون end_image، يكون الطلب من نوع image-to-video، وتعمل start_image مثل image في النماذج التي تدرجها ضمن اتفاقية الاستخدام الخاصة بها. تقبل رابطاً عاماً (public URL) أو رابط بيانات (data URL)؛ كما تقبل نماذج Seedance 2.0 الصيغة asset://asset-YYYYMMDDHHMMSS-xxxxx.

end_imagestring

صورة الإطار الأخير لـ start-end-to-video. تقبل نفس مدخلات start_image.

material_asset_idstring

معرف أصل مادة TokenLab Seedance الذي يتم إرجاعه بواسطة إنشاء أصل مادة. مقبول فقط في نماذج Seedance 2.0؛ وتُرجع النماذج الأخرى 400 unsupported_seedance_material_asset_model. يجب أن يكون الأصل بحالة ACTIVE وينتمي إلى حسابك. هذا الحقل هو مدخل مرجعي عام؛ لتعيين دلالة الإطار الأول أو الإطار الأخير أو الصورة المرجعية بشكل صريح، ضع asset://<material_asset_id> في start_image أو end_image أو reference_images بدلاً من ذلك.

material_asset_idsarray

ما يصل إلى 9 معرفات لأصول مواد TokenLab Seedance. ويتم احتسابها ضمن مراجع الصور التسعة لنماذج Seedance 2.0.

يتم تمرير عناوين URL العادية للصور كمدخلات صور؛ وهي لا تنشئ أصول مواد قابلة لإعادة الاستخدام. أنشئ أصولاً قابلة لإعادة الاستخدام عبر API المواد، ثم استخدم معرفات TokenLab الخاصة بها أو معرفات الموارد المنتظمة (URIs) بالصيغة asset://asset-YYYYMMDDHHMMSS-xxxxx. إذا أرجعت مادة صريحة الخطأ 409 seedance_material_preparing، فتحقق من inactive_asset_ids المرتجعة وأعد المحاولة بعد أن تصبح تلك المواد بحالة ACTIVE.

video_urlstring

عنوان URL يمكن الوصول إليه بشكل عام لفيديو المصدر، للعمليات التي تتطلب فيديو: video-to-video و video-extension و motion-control، في النماذج التي تسرد هذا الحقل.

video_urlsarray

مقاطع فيديو مصدر أو مرجعية للنماذج التي تسرد هذا الحقل. يقبل seedance-2.5 ما يصل إلى 10 مدخلات فيديو إجمالاً عبر video_url و video_urls. راجع تفاصيل النموذج بالنسبة للنماذج الأخرى.

audio_urlstring

عنوان URL صوتي عام لمرجع صوتي أو عملية معتمدة على الصوت، في النماذج التي تسرد هذا الحقل. إنه مدخل، وليس مفتاح تبديل لمخرجات الصوت.

audio_urlsarray

صوت مرجعي للنماذج التي تسرد هذا الحقل. يقبل seedance-2.5 ما يصل إلى 10 مدخلات صوتية إجمالاً عبر audio_url و audio_urls ويسمح بطلب يحتوي على مراجع صوتية وبدون وصف نصي. بالنسبة لـ seedance-2.5، يبلغ الحد الأقصى للمدة الإجمالية للصوت المرجعي والفيديو المرجعي معًا 30 ثانية.

task_idstring

معرف مهمة سابقة في مساحة العمل الخاصة بك، لـ video-extension في النماذج التي تسرد هذا الحقل. المهمة التي لا تنتمي إلى مساحة العمل الخاصة بك تُرجع 403 task_not_owned.

extend_atinteger

الثانية من الفيديو المصدر التي يبدأ عندها video-extension. مطلوب بواسطة grok-imagine-video.

extend_timesstring

عدد الثواني المراد إضافتها في video-extension، في النماذج التي تسرد هذا الحقل. يقبل grok-imagine-video القيمة 6 أو 10.

durationinteger

مدة الإخراج بالثواني. تعتمد القيم المسموح بها على النموذج والعملية؛ وتُرجع القيم الأخرى 400 invalid_duration. تقبل نماذج Seedance أيضًا -1 للسماح للنموذج بالاختيار ضمن نطاقه؛ ثم يتم تقدير الفوترة بشكل متحفظ حتى تنتهي المهمة. لا تتطلب بعض العمليات مدة، مثل motion-control وتحويل الفيديو إلى فيديو في grok-imagine-video.

secondsinteger

اسم بديل متوافق لـ duration. إذا تم إرسال كلاهما، فيجب أن يكونا متطابقين.

aspect_ratiostring

نسبة العرض إلى الارتفاع، على سبيل المثال 16:9، أو 9:16، أو 1:1، أو 4:3، أو 3:4، أو 21:9، أو adaptive (Seedance). تعتمد القيم المسموح بها على النموذج والعملية؛ وتُرجع القيم الأخرى 400 invalid_aspect_ratio.

resolutionstring

دقة الإخراج، على سبيل المثال 480p، أو 720p، أو 1080p، أو 4k. تعتمد القيم المسموح بها على النموذج والعملية، وتستخدم بعض النماذج أيضًا 360p، أو 540p، أو 768p. تُرجع القيم الأخرى 400 invalid_resolution.

output_audioboolean

محدد إخراج الصوت للعمليات التي تسرده. يتبع الحذف القيمة الافتراضية للنموذج؛ ويطلب false إخراجًا صامتًا فقط عندما يسمح النموذج بذلك. راجع ملاحظات الصوت أعلاه وتفاصيل النموذج المحدد.

output_formatstring

تنسيق الحاوية، mp4 أو mov، للنماذج التي تسرد هذا الحقل، مثل seedance-2.5. احذفه للنماذج التي لا تسرده.

return_last_frameboolean

إرجاع آخر إطار تم إنشاؤه أيضًا كـ last_frame_url. لنماذج Seedance فقط.

watermarkboolean

مفتاح تبديل العلامة المائية للنماذج التي تسرد هذا الحقل (نماذج Seedance).

negative_promptstring

ما يجب تجنبه في الفيديو المنشأ، حتى 5,000 حرف، للنماذج التي تسرد هذا الحقل.

seedinteger

قيمة البذور (Seed) لإنشاء قابل لإعادة الإنتاج، للنماذج التي تسرد هذا الحقل. تقبل نماذج Seedance 2.0 القيمة -1 لبذور عشوائية؛ ولا يقبل seedance-2.5 هذا الحقل.

fpsinteger

عدد الإطارات في الثانية (1-120)، للنماذج التي تسرد هذا الحقل.

framesinteger

عدد الإطارات، للنماذج التي تسرد هذا الحقل. لا تقبله نماذج Seedance.

execution_expires_afterinteger

عدد الثواني التي قد تنتظرها المهمة في قائمة الانتظار قبل انتهاء صلاحيتها (من 3600 إلى 259200)، لنماذج Seedance.

priorityinteger

أولوية المهمة من 0 إلى 9، لنماذج Seedance. لا تدمجها مع service_tier=flex.

service_tierstring

يتم قبول default كعملية غير فعالة للتوافق في نماذج Seedance 2.0 و 2.5. ويتم رفض flex في تلك النماذج.

safety_identifierstring

معرف أمان المستخدم النهائي (حتى 128 حرفًا)، لنماذج Seedance. إذا تم حذفه، يستخدم TokenLab القيمة user عند تقديمها.

toolsarray

الأدوات التي قد يستخدمها النموذج أثناء الإنشاء، لنماذج Seedance 2.0 و 2.5. الأداة المدعومة هي {"type": "web_search"}.

userstring

معرف فريد للمستخدم النهائي. بالنسبة لنماذج Seedance، يستخدمه TokenLab أيضًا كـ safety_identifier عند حذف هذا الحقل.

أسماء الحقول المتوافقة

  • تستخدم الحقول الأساسية صيغة snake_case: مثل aspect_ratio و output_audio و reference_images.
  • للتوافق، يقبل TokenLab أيضًا ratio و generate_audio و outputAudio و seconds و referenceImages.
  • إذا تم إرسال حقل أساسي واسمه البديل معًا، فيجب أن تتطابق قيمهما. يؤدي عدم التطابق إلى إرجاع 400 مع conflicting_audio_selector أو conflicting_duration أو conflicting_aspect_ratio.

معلمات Seedance

تأخذ نماذج Seedance (seedance-2.0 و seedance-2.0-fast و seedance-2.0-mini و seedance-2.5) أسماء حقول TokenLab الموضحة أعلاه والأسماء البديلة seconds و ratio و generate_audio. وتختلف الإصدارات فيما بينها:

نماذج Seedance 2.0seedance-2.5
الدقةseedance-2.0: 480p، 720p، 1080p، 4k. seedance-2.0-fast و seedance-2.0-mini: 480p، 720p480p، 720p
المدة-1، من 4 إلى 15 ثانية-1، من 4 إلى 30 ثانية
نسبة العرض إلى الارتفاع1:1، 3:4، 4:3، 9:16، 16:9، 21:9، adaptiveنفسها لتحويل النص إلى فيديو والمرجع إلى فيديو. يتطلب تحويل الصورة إلى فيديو، والبداية والنهاية، وتعديل الفيديو، والتوسيع استخدام adaptive؛ يتطلب تعديل الفيديو أيضًا duration=-1
تنسيق الإخراجmp4mp4 أو mov
seedمقبولغير مقبول
مدخلات المراجع9 مراجع صور تشمل المواد (تُقبل المواد فقط في هذه النماذج)30 صورة، و 10 مقاطع فيديو، و 10 ملفات صوتية إجمالاً

تعد تفاصيل النموذج هي المصدر الحالي لهذه القيم. أرسل duration و resolution و aspect_ratio و output_audio بشكل صريح بدلاً من الاعتماد على القيمة الافتراضية؛ يوضح recommended_request الخاص بالنموذج طلبًا نموذجيًا.

يتيح duration=-1 أو seconds=-1 لـ Seedance اختيار مدة الإخراج ضمن نطاق النموذج. يقدّر TokenLab التكلفة بشكل متحفظ قبل انتهاء المهمة، ثم تتم التسوية بناءً على الاستخدام الفعلي للمهمة المكتملة عند توفره. يتم رفض service_tier=flex و frames في هذه النماذج.

مثال Seedance

cURL
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

الاستجابة

يتم إرجاع الحقول التي تصف النتائج والأخطاء والطوابع الزمنية والنموذج عند توفرها للمهمة.

idstring

معرف المهمة. مطابق لـ task_id.

task_idstring

معرف المهمة للاستعلام عنه باستخدام GET /v1/tasks/{id}.

poll_urlstring

عنوان URL لحالة هذه المهمة، /v1/tasks/{id}. اطلبه باستخدام مفتاح API الخاص بك.

statusstring

حالة المهمة: pending، أو processing، أو completed، أو failed. عادةً ما تكون المهمة الجديدة بحالة pending.

createdinteger

طابع زمني Unix لوقت إنشاء المهمة.

modelstring

النموذج المستخدم.

billing_transaction_idstring

معرف معاملة الفوترة عند اكتمال التسوية بالفعل. وهو منفصل عن معرف المهمة.

video_urlstring

عنوان URL للفيديو، ويكون موجودًا فقط عندما تحمل استجابة الإنشاء النتيجة بالفعل. في العادة، تقرأه من استجابة الحالة.

errorstring | object

رسالة الخطأ أو كائن خطأ منظم عند فشل المهمة.

الأخطاء

الحالة والرمزالمعنى
400 invalid_requestحقل غير صالح، أو خارج النطاق، أو مفقود. يحدد error.param اسم الحقل. رسالة مثل "Set aspect_ratio explicitly" تعني أن الحقل المحذوف ليس له قيمة افتراضية لهذا الطلب.
400 unsupported_operation، unsupported_parameter، invalid_resolution، invalid_duration، invalid_aspect_ratio، invalid_parameter_value، too_many_items، prompt_too_longالطلب لا يتطابق مع ما يقبله النموذج للعملية. يسرد الخطأ عادةً القيم المقبولة.
400 invalid_parameterإدخال لا يناسب العملية، على سبيل المثال إرسال صورة مع text-to-video.
400 conflicting_audio_selector، conflicting_duration، conflicting_aspect_ratioعدم تطابق بين الاسم البديل وحقله الأساسي.
400 unpriceable_selectionالتشكيلة المحددة ليس لها سعر. قم بتغيير resolution، أو duration، أو aspect_ratio، أو إعداد الصوت.
400 too_many_seedance_reference_images، unsupported_seedance_material_asset_modelمراجع صور كثيرة جدًا لنموذج Seedance 2.0، أو تم إرسال مادة إلى نموذج آخر.
402رصيد غير كافٍ.
403 task_not_ownedحقل task_id ينتمي إلى مساحة عمل أخرى.
409 seedance_material_preparing، seedance_material_route_unavailableالمادة ليست بحالة ACTIVE بعد، أو أن النموذج المحدد لا يمكنه استخدام المواد المقدمة.
429تم تجاوز حد المعدل. راجع حدود المعدل.

الطلب

curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1",
    "prompt": "A cat walking through a garden, cinematic lighting",
    "operation": "text-to-video",
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

الاستجابة

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000
}

تحويل الصورة إلى فيديو

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3",
        "prompt": "The scene begins from the provided image and adds gentle natural motion.",
        "operation": "image-to-video",
        "image_url": "https://example.com/image.jpg",
        "duration": 6,
        "resolution": "768p"
    }
)

تحويل المرجع إلى فيديو

استخدم operation=reference-to-video عندما يدعم النموذج شروط مرجعية مخصصة. يتم وضع مراجع الصور في reference_images؛ وتستخدم النماذج التي تقبل مقاطع فيديو وصوتيات مرجعية video_urls و audio_urls. يحدد duration طول الإخراج المنشأ فقط، ولا يحدد طول مدخلات الفيديو المرجعي. راجع reference_images أعلاه لمعرفة حدود العدد لكل نموذج.

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "veo3.1",
        "prompt": "Keep the same subject identity, palette, and framing while adding subtle natural motion.",
        "operation": "reference-to-video",
        "reference_images": [
            "https://example.com/ref-a.jpg",
            "https://example.com/ref-b.jpg"
        ],
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

التحكم في الإطارات المفتاحية

استخدم start_image و end_image للتحكم في الإطارين الأول والأخير:

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "viduq2-pro",
        "operation": "start-end-to-video",
        "start_image": "https://example.com/day.jpg",
        "end_image": "https://example.com/night.jpg",
        "duration": 5,
        "resolution": "720p"
    }
)

تحويل الفيديو إلى فيديو

استخدم operation=video-to-video عندما يقبل النموذج فيديو حاليًا كمدخل أساسي. بالنسبة لـ grok-imagine-video، أرسل عنوان HTTPS عام لملف .mp4 في video_url ووصف التعديل prompt، واحذف resolution و duration و aspect_ratio.

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "grok-imagine-video",
        "operation": "video-to-video",
        "video_url": "https://example.com/source.mp4",
        "prompt": "Enhance the clip while preserving the original motion."
    }
)

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

استخدم operation=video-extension لمتابعة نتيجة سابقة. أرسل task_id لمهمة من مساحة العمل الخاصة بك و prompt؛ وتعتمد الحقول الأخرى على النموذج. يحتاج grok-imagine-video أيضًا إلى extend_at ويقبل extend_times بقيمة 6 أو 10. يأخذ veo3.1 و veo3.1-fast كلاً من task_id و prompt. تسرد نماذج Seedance الحقول video_url و video_urls و task_id لهذه العملية.

التحكم في الحركة

استخدم operation=motion-control عندما يتوقع النموذج كلاً من صورة الموضوع وفيديو مرجعي للحركة. أرسل image_url و video_url؛ ويعد resolution مطلوبًا.

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "kling-3.0-motion-control",
        "operation": "motion-control",
        "prompt": "Keep the subject identity stable while following the motion reference.",
        "image_url": "https://example.com/subject.png",
        "video_url": "https://example.com/motion.mp4",
        "resolution": "720p"
    }
)

استكشاف النماذج

يتغير مخزون الفيديو العام والعمليات المدعومة بمرور الوقت. استخدم Models API للتحقق من الدعم الحالي قبل ربط مسار مخصص لنموذج معين:

curl "https://api.tokenlab.sh/v1/models?recommended_for=video"

curl "https://api.tokenlab.sh/v1/models/veo3.1"

اقرأ استجابة تفاصيل النموذج قبل الاعتماد على عمليات أو حقول خاصة بالنموذج. فالعمليات مثل video-extension و motion-control خاصة بنماذج معينة؛ تحقق من التوفر الحالي هناك بدلاً من الاعتماد على الأمثلة الثابتة في هذه الصفحة.

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

مفتاح اختياري يجعل طلب الإنشاء آمناً لإعادة المحاولة. أرسل قيمة فريدة جديدة، مثل UUID، لكل مهمة. إعادة المحاولة بنفس المفتاح ونفس نص الطلب تُرجع نتيجة طلب الإنشاء الأصلي، وعادةً ما تكون المهمة الأصلية، ولا تقوم بإنشاء أو إرسال أو احتساب تكلفة مهمة ثانية. يتم رفض نص الطلب المختلف الذي يستخدم مفتاحاً تم قبوله مسبقاً بالرمز 409. يتم تجاهل المفتاح الذي يتجاوز 255 حرفاً، وعندها لا يتمتع الطلب بحماية idempotency. راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.

الطول1 <= length <= 255

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json