TokenLab
الحصول على مفتاح API
التوثيقمرجع APIالتكاملات

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

إنشاء فيديو

ينشئ مهمة توليد فيديو

POST
/v1/videos/generations

نظرة عامة

يعمل توليد الفيديو بشكل غير متزامن. ترسل طلبًا، وتتلقى task_id و poll_url، ثم تتحقق من الحالة بشكل دوري إلى أن تصبح النتيجة النهائية جاهزة.

سلوك الاستعلام

للحصول على أكثر سلوك موثوق في التحقق من الحالة، استخدم قيمة poll_url المعادة من استجابة الإنشاء كما هي تمامًا.

إذا أعادت استجابة الإنشاء poll_url، فاستدعِ هذا الرابط نفسه تمامًا. وعندما يشير إلى /v1/tasks/{id}، فاعتبره نقطة الحالة الثابتة المعيارية.

سلوك النموذج والوسائط

يعتمد سلوك الصوت على النموذج والعملية. قد يحتوي الفيديو على صوت حتى عندما لا يوجد مفتاح للتحكم فيه. حذف المعامل يختلف عن إرسال false.

  • ينشئ veo3.1 وveo3.1-fast الصوت دائمًا وفق عقد Gemini API. كما لا يدعم توليد الفيديو في wan-2.6 وwan-2.7 تعطيل الصوت. احذف output_audio أو استخدم true إذا سمحت تفاصيل النموذج بذلك.
  • ينشئ hailuo-h3 ونماذج فيديو Grok صوتًا أصليًا. لا تضف مفتاح صوت غير مدرج في تفاصيل النموذج.
  • يكون الصوت مفعّلًا افتراضيًا في Seedance 1.5/2.x وviduq3-pro / viduq3-turbo مع دعم الإخراج الصامت. ويكون معطّلًا افتراضيًا في PixVerse C1/V5.6/V6. استخدم output_audio فقط للعمليات التي تعلنه؛ ويقبل Vidu أيضًا الحقل المنطقي audio المعلن في عقده.
  • يوفّر audio_url / audio_urls صوت الإدخال أو المرجع، وليس مفتاحًا لصوت الإخراج. قد يحافظ تحرير الفيديو ونقل الحركة والأسلوب على المسار الصوتي الأصلي. الاحتفاظ بالصوت الأصلي لا يعني كتمه.

راجع تفاصيل النموذج للقيم المسموحة والأسعار المتعلقة بالصوت. يجب أن تتطابق الأسماء البديلة المدعومة outputAudio وgenerate_audio والحقل المنطقي audio مع output_audio عند جمعها. قد تختلف أدوات التحكم بين الإصدارات والعمليات.

في تكاملات الإنتاج، يُفضّل استخدام روابط https عامة للصور والفيديو والصوت. ما تزال النماذج المتوافقة تقبل روابط data:، لكن حمولات base64 الكبيرة أصعب في إعادة المحاولة والفحص وتتبع الأعطال.

جسم الطلب

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

معرف نموذج الفيديو. استخدم معرفات النماذج التي تعرضها TokenLab مثل veo3.1 أو wan-2.7 أو happyhorse-1.0 أو viduq3 أو pixverse-v6 أو kling-3.0-video؛ واختر text-to-video أو image-to-video أو reference-to-video أو غيرها عبر operation. راجع دليل إنشاء الفيديو وModels API.

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

وصف نصي للفيديو المطلوب توليده. هذا الحقل مطلوب لمعظم نماذج الفيديو العامة.

operationstring

عملية الفيديو المطلوب تنفيذها. يدعم القيم text-to-video و image-to-video و reference-to-video و start-end-to-video و video-to-video و video-extension و audio-to-video و motion-control. يمكن لـ TokenLab استنتاج العملية من المدخلات المرسلة، لكن يُنصح بإرسال operation بشكل صريح في بيئات الإنتاج.

image_urlstring

رابط URL عام للصورة الابتدائية في تدفقات image-to-video. ولأوسع توافق بين النماذج، يُفضّل استخدام image_url.

imagestring

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

reference_imagesarray

صور مرجعية للتدفقات التي تدعم التكييف المرجعي المخصص. العدد المدعوم يعتمد على النموذج. بالنسبة إلى seedance-2.0 و seedance-2.0-fast، تدعم TokenLab حاليًا ما يصل إلى 9 صور مرجعية، بالإضافة إلى ما يصل إلى 3 مقاطع فيديو مرجعية و3 ملفات صوت مرجعية. لاختيار النموذج وحدود 4K وملاحظات Mini، راجع دليل نماذج فيديو Seedance 2.0. يُفضَّل استخدام روابط https العامة، كما تقبل النماذج المتوافقة أيضًا روابط data:. بالنسبة إلى grok-imagine-video، تقبل reference-to-video حتى 7 مراجع صور ويكون duration بحد أقصى 10 ثوانٍ. يدعم grok-imagine-video-1.5-preview image-to-video فقط ولا يقبل مراجع الصور.

material_asset_idstring

معرف مادة Seedance من TokenLab المعاد من إنشاء مادة. استخدمه بعد أن تصبح المادة ACTIVE مع نماذج Seedance التي يمكنها استخدام مكتبة مواد TokenLab.

material_asset_idsarray

عدة معرفات مواد Seedance من TokenLab. تشترك مع reference_images في حد مراجع الصور الخاص بـ Seedance؛ يجب أن يستطيع النموذج المحدد استخدام مكتبة مواد TokenLab.

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

reference_image_typestring

حقل اختياري للنماذج التي تميّز بين المراجع من نوع asset و style.

kling_elementsarray

استخدم kling_elements فقط إذا أدرجته التفاصيل العامة الحالية للنموذج. أرسل صورًا و1–3 عناصر، لكل منها name وdescription اختياري و2–4 روابط element_input_urls، وأشر إليها بصيغة @name في prompt. لا تجمعها مع output_audio=true.

video_urlstring

رابط عام للفيديو المصدر. مطلوب لتدفقات video-to-video المعتمدة على URL الفيديو ولـ motion-control؛ بعض التدفقات المشتقة تستخدم task_id بدلًا من ذلك.

video_urlsarray

مدخلات إضافية لمقاطع الفيديو المرجعية للنماذج التي تدعم التكييف المرجعي متعدد الوسائط. العدد المدعوم يعتمد على النموذج. بالنسبة إلى seedance-2.0 و seedance-2.0-fast، تدعم TokenLab حاليًا ما يصل إلى 3 مقاطع فيديو مرجعية.

audio_urlstring

رابط صوت عام لعملية تعتمد على الصوت أو مرجع صوتي يدعمه النموذج المحدد.

audio_urlsarray

مدخلات إضافية للصوت المرجعي للنماذج التي تدعم التكييف المرجعي متعدد الوسائط. العدد المدعوم يعتمد على النموذج. بالنسبة إلى seedance-2.0 و seedance-2.0-fast، تدعم TokenLab حاليًا ما يصل إلى 3 ملفات صوت مرجعية.

task_idstring

معرّف مهمة تستخدمه بعض تدفقات المتابعة أو التمديد أو التدفقات المشتقة.

extend_atinteger

إزاحة بداية خاصة بالنموذج لبعض تدفقات video-extension.

extend_timesstring

مضاعف أو عدد تكرارات خاص بالنموذج لبعض تدفقات video-extension.

durationinteger

مدة فيديو الإخراج المُنشأ بالثواني. في نماذج Seedance 1.5/2.0، يؤدي حذف هذا الحقل إلى استخدام 5؛ وإرسال -1 يجعل النموذج يختار ضمن النطاق المدعوم، ويتم تقدير الفوترة بشكل محافظ إلى أن تنتهي المهمة.

secondsinteger

اسم بديل متوافق لـ duration. إذا أرسلت seconds وduration معًا، فيجب أن تكون القيمتان متطابقتين. في Seedance، يحمل seconds=-1 معنى المدة التلقائية نفسه مثل duration=-1.

aspect_ratiostring

نسبة العرض إلى الارتفاع المعيارية، مثل adaptive أو 16:9 أو 9:16 أو 1:1 أو 4:3 أو 3:4 أو 21:9. تستخدم Seedance القيمة adaptive افتراضيًا عند الحذف.

resolutionstring

دقة الإخراج تعتمد على النموذج. تستخدم Seedance 720p افتراضيًا؛ يدعم seedance-2.0 القيم 480p و720p و1080p و4k، بينما يقتصر seedance-2.0-fast وseedance-2.0-mini على 480p و720p.

output_audioboolean

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

draftboolean

علامة سير عمل المسودة في Seedance 1.5 Pro. استخدم draft=true مع نماذج Seedance التي تدعم مهام المسودة. لا ترسله مع draft_task_id.

draft_task_idstring

معرّف مهمة مسودة Seedance 1.5 Pro للترقية. أرسل معرّف مهمة مسودة سابقة لإنشاء الفيديو النهائي؛ هذا ليس حقلاً عاماً لكل نماذج الفيديو.

ratiostring

اسم بديل متوافق لـ aspect_ratio. إذا أُرسل ratio وaspect_ratio معًا، فيجب أن يكونا متطابقين.

generate_audioboolean

اسم بديل متوافق لـ output_audio. إذا ظهرت generate_audio وoutput_audio وoutputAudio معًا، فيجب أن تتطابق جميع القيم.

execution_expires_afterinteger

نافذة انتهاء تنفيذ اختيارية بالثواني لنماذج الفيديو المتوافقة. تستخدم Seedance 172800 ثانية افتراضيًا عند الحذف.

priorityinteger

أولوية مهمة اختيارية من 0 إلى 9 لنماذج الفيديو المتوافقة. لا تجمع priority مع service_tier=flex.

safety_identifierstring

معرّف أمان اختياري للمستخدم النهائي لنماذج الفيديو المتوافقة. إذا حُذف في Seedance، تستخدم TokenLab قيمة user عند توفرها.

service_tierstring

تُقبل default كعملية توافقية بلا تأثير لنماذج Seedance 2.0. لا يُسمح بـ flex إلا عندما يدعمه النموذج المحدد.

framesinteger

عدد إطارات اختياري لنماذج الفيديو المتوافقة. لا تدعم نماذج Seedance 2.0 وSeedance 1.5 Pro هذا الحقل.

camera_fixedboolean

محدد كاميرا ثابتة اختياري لنماذج الفيديو المتوافقة. لا تدعم نماذج Seedance 2.0 هذا الحقل.

fpsinteger

عدد الإطارات في الثانية (1-120). لا يكون فعالًا إلا في النماذج التي تكشف التحكم في FPS.

negative_promptstring

العناصر التي ترغب في تجنبها في الفيديو الناتج.

seedinteger

بذرة عشوائية للتوليد القابل للتكرار. تستخدم Seedance القيمة -1 كبذرة عشوائية عند الحذف.

cfg_scalenumber

شدة الالتزام بالـ prompt (من 0 إلى 20) في النماذج التي تدعم هذا التحكم.

motion_strengthnumber

شدة الحركة (من 0 إلى 1) في النماذج التي تدعم هذا التحكم.

start_imagestring

رابط الصورة الخاصة بالإطار الأول، أو إدخال صورة متوافق، لعملية start-end-to-video.

end_imagestring

رابط الصورة الخاصة بالإطار الأخير، أو إدخال صورة متوافق، لعملية start-end-to-video.

sizestring

مستوى حجم خاص بالنموذج لنماذج الفيديو المتوافقة.

watermarkboolean

مفتاح علامة مائية اختياري للنماذج التي توفره. تستخدم Seedance القيمة false افتراضيًا عند الحذف.

effect_typestring

محدد تأثير خاص بالنموذج لبعض تدفقات التحرير أو التأثيرات المتخصصة.

userstring

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

ملاحظات التوافق

  • تبقى الحقول العامة المعيارية بصيغة snake_case: aspect_ratio وoutput_audio وreference_images وreference_image_type.
  • للتوافق، تقبل TokenLab أيضًا ratio وgenerate_audio وoutputAudio وseconds وreferenceImages وreferenceImageType.
  • إذا أُرسلت الحقول المعيارية وأسماؤها البديلة معًا، فيجب أن تتطابق القيم؛ تُرفض القيم المتعارضة قبل إنشاء المهمة.

أفضل الممارسات لمدخلات الوسائط

  • بالنسبة إلى image_url و reference_images و video_url و audio_url، يُفضّل استخدام روابط https عامة.
  • حاول تجنّب خلط base64 المضمن وروابط URL البعيدة داخل الطلب نفسه قدر الإمكان.
  • تأكد من أن روابط الوسائط البعيدة تبقى صالحة لمدة تكفي لإعادة المحاولة ومرحلة إنشاء المهمة غير المتزامنة.

معاملات Seedance

في نماذج Seedance 1.5/2.0، يتبع المسار الموحّد أسماء حقول TokenLab ويقبل أيضًا الأسماء البديلة المتوافقة seconds وratio وgenerate_audio. عند حذف محددات Seedance، تُستخدم القيم الافتراضية التالية: duration=5 وresolution=720p وaspect_ratio=adaptive وoutput_audio=true وwatermark=false وreturn_last_frame=false وexecution_expires_after=172800 وpriority=0 وseed=-1.

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

مثال 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

المعرّف المعياري للمهمة غير المتزامنة. عندما يظهر كلٌّ من id وtask_id، فاعتبرهما نفس المهمة.

task_idstring

معرّف المهمة الفريد لاستخدامه في التحقق من الحالة.

poll_urlstring

رابط التحقق من الحالة الموصى به لهذه المهمة. استخدم هذا المسار كما هو عند فحص الحالة.

billing_transaction_idstring

معرّف معاملة الفوترة في TokenLab عندما تكون التسوية قد اكتملت بالفعل. هذا هو معرّف المعاملة المستخدم في لوحة التحكم / المطابقة، وهو منفصل عن id / task_id غير المتزامن.

statusstring

حالة المهمة: pending, processing, completed, failed.

createdinteger

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

modelstring

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

videoobject

حمولة فيديو مفردة تحتوي على الحقول url, duration, width, و height عندما تتوفر.

videosarray

حمولات فيديو متعددة عندما تعيد مهمة التوليد أكثر من مخرج واحد.

errorstring | object

رسالة الخطأ (إذا فشلت).

الطلب

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": "veo3.1",
    "prompt": "A cat walking through a garden, cinematic lighting",
    "operation": "text-to-video",
    "duration": 4,
    "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
}

من صورة إلى فيديو

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3-standard",
        "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"
    }
)

عناصر Kling 3.0

استخدم kling_elements فقط إذا أدرجته التفاصيل العامة الحالية للنموذج. أرسل صورًا و1–3 عناصر، لكل منها name وdescription اختياري و2–4 روابط element_input_urls، وأشر إليها بصيغة @name في prompt. لا تجمعها مع output_audio=true.

من مرجع إلى فيديو

استخدم operation=reference-to-video عندما يدعم النموذج تكييفًا مرجعيًا مخصصًا. في تفاصيل النموذج لـ TokenLab تستخدم مراجع الصور reference_images، بينما تستخدم الفيديوهات والصوتيات المرجعية متعددة الوسائط الحقول video_urls و audio_urls. بالنسبة إلى seedance-2.0 و seedance-2.0-fast، تدعم TokenLab حاليًا ما يصل إلى 9 صور مرجعية، بالإضافة إلى ما يصل إلى 3 مقاطع فيديو مرجعية و3 ملفات صوت مرجعية. لاختيار النموذج وحدود 4K وملاحظات Mini، راجع دليل نماذج فيديو Seedance 2.0. يتحكم duration فقط في طول الإخراج الناتج، ولا يضع حدًا منفصلًا لمدة فيديو المرجع المُدخل. بالنسبة إلى grok-imagine-video، تقبل reference-to-video حتى 7 مراجع صور (reference_images أو image_urls) ويكون duration بحد أقصى 10 ثوانٍ. لا تجمع مراجع الصور مع إدخالات الإطار الأول image_url / image. يدعم grok-imagine-video-1.5-preview image-to-video فقط.

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"
        ],
        "reference_image_type": "asset",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

التحكم في الإطارين الأول والأخير

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

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",
        "aspect_ratio": "16:9"
    }
)

من فيديو إلى فيديو

في video-to-video مع grok-imagine-video، أرسل رابط HTTPS عام بصيغة .mp4 في video_url. يمكنك ضبط resolution على 480p أو 720p؛ ولا يقبل مسار التحرير هذا duration أو aspect_ratio.

إذا كان النموذج يقبل فيديو موجودًا كمدخل رئيسي، فاستخدم operation=video-to-video.

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=motion-control. يقوم TokenLab بتطبيع الشكل العام image_url + video_url إلى تنسيق motion-control لذلك النموذج.

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 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"

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

التفويض

BearerAuth
AuthorizationBearer <token>

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

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

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

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

  • "auto"
  • "verified"
  • "official"

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

الحصول على حالة الموسيقى

السابق

إنشاء مهمة (متوافقة مع Volc)

التالي