إنشاء فيديو

نظرة عامة

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

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

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

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

يعتمد إخراج الصوت على النموذج. في TokenLab، تكون طلبات Veo 3 وSeedance مفعّلة الصوت افتراضيًا عند حذف output_audio. عندما يدعم النموذج التحكم في الصوت، استخدم output_audio لتبديله صراحة. تُقبل الأسماء البديلة outputAudio وgenerate_audio للتوافق، ويجب أن تطابق output_audio عند توفير أكثر من حقل. في تكاملات الإنتاج، يُفضّل استخدام روابط https عامة للصور والفيديو والصوت. ما تزال النماذج المتوافقة تقبل روابط data:، لكن حمولات base64 الكبيرة أصعب في إعادة المحاولة والفحص وتتبع الأعطال.

جسم الطلب

string

افتراضي:"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

string

مطلوب

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

string

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

string

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

string

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

array

صور مرجعية للتدفقات التي تدعم التكييف المرجعي المخصص. العدد المدعوم يعتمد على النموذج. بالنسبة إلى 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 فقط ولا يقبل مراجع الصور.

string

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

array

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

عندما يستطيع نموذج Seedance المحدد استخدام مكتبة مواد TokenLab، يجهز TokenLab حقول الصور (image وimage_url وimage_urls وreference_images وstart_image وend_image) كمواد قابلة لإعادة الاستخدام قبل التوليد. إذا لم يكتمل التجهيز خلال 60 ثانية، تعيد الواجهة 409 seedance_material_preparing مع auto_material_asset_ids؛ أعد المحاولة بعد أن تصبح هذه المواد ACTIVE. إذا لم يستطع النموذج المحدد استخدام مكتبة المواد، تستمر مدخلات الصور العادية عبر مسار الصور المعتاد وتفشل معرفات المواد الصريحة بأمان مع خطأ قابل لإعادة المحاولة يخص توفر المادة.

string

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

array

تعريفات مراجع العناصر في Kling 3.0. هذه الميزة مدعومة فقط مع kling-3.0-video للطلبات المشروطة بصورة. عرّف 1-3 عناصر؛ يحتوي كل عنصر على name و description اختياري و element_input_urls بعدد 2-4 روابط صور. استخدم @name داخل prompt للإشارة إلى العنصر. لا تجمع kling_elements مع output_audio=true؛ احذف output_audio أو اجعله false عند استخدام مراجع العناصر.

string

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

array

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

string

رابط URL عام للصوت للنماذج التي تدعم audio-to-video.

array

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

string

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

integer

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

string

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

integer

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

integer

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

string

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

string

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

boolean

مفتاح إخراج الصوت المعياري المعتمد على النموذج. يستخدم Veo 3 وSeedance القيمة true افتراضيًا عند الحذف. يقبل kling-3.0-video هذا المحدد للطلبات التي لا تستخدم مراجع العناصر، ويكون الإخراج صامتًا افتراضيًا عند الحذف. لا تجمع output_audio=true مع kling_elements.

boolean

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

string

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

string

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

boolean

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

integer

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

integer

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

string

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

string

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

integer

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

boolean

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

integer

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

string

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

integer

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

number

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

number

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

string

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

string

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

string

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

boolean

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

string

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

string

معرّف فريد للمستخدم النهائي. في 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.0",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

الاستجابة

string

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

string

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

string

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

string

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

string

الحالة الأولية: pending.

integer

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

string

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

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

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

عناصر Kling 3.0

استخدم kling_elements مع kling-3.0-video عندما تحتاج إلى مراجع عناصر. يجب أن يحتوي الطلب على شرط صورة (image_url أو image_urls أو start_image أو end_image) وأن تشير إلى كل عنصر في prompt باستخدام @name. لا تجمع kling_elements مع output_audio=true؛ احذف output_audio أو اجعله false عند استخدام مراجع العناصر.

response = requests.post("https://api.tokenlab.sh/v1/videos/generations",
    headers=headers,
    json={
        "model": "kling-3.0-video",
        "prompt": "Place @hero_bag on a studio turntable with soft product lighting.",
        "operation": "image-to-video",
        "image_url": "https://example.com/studio-start.png",
        "duration": 5,
        "resolution": "720p",
        "kling_elements": [
            {
                "name": "hero_bag",
                "description": "black leather handbag",
                "element_input_urls": [
                    "https://example.com/bag-front.png",
                    "https://example.com/bag-side.png"
                ]
            }
        ]
    }
)

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

استخدم 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",
        "prompt": "Smooth transition from day to night",
        "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. يحوله TokenLab إلى جسم REST الخاص بـ xAI بصيغة 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.",
        "resolution": "720p"
    }
)

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

إذا كان النموذج يحتاج إلى صورة للعنصر وفيديو مرجعي للحركة معًا، فاستخدم 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" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models/veo3.1" \
  -H "Authorization: Bearer sk-your-api-key"

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

الأساسيات

النص

الملفات والدفعات

الصور

الصوت والوقت الفعلي

الموسيقى

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

Worlds

3D

المهام غير المتزامنة

Gemini الأصلي

الإدارة

إنشاء فيديو

نظرة عامة

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

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

جسم الطلب

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

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

معاملات Seedance

مثال Seedance

الاستجابة

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

عناصر Kling 3.0

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

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

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

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

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

​نظرة عامة

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

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

​جسم الطلب

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

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

​معاملات Seedance

​مثال Seedance

​الاستجابة

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

​عناصر Kling 3.0

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

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

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

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

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

نظرة عامة

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

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

جسم الطلب

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

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

معاملات Seedance

مثال Seedance

الاستجابة

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

عناصر Kling 3.0

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

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

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

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

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