إنشاء فيديو

نظرة عامة

يعمل توليد الفيديو بشكل غير متزامن. ترسل طلبًا، وتتلقى 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 الكبيرة أصعب في إعادة المحاولة والفحص وتتبع الأعطال.

جسم الطلب

model

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

prompt

string

مطلوب

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

operation

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 بشكل صريح في بيئات الإنتاج.

image_url

string

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

image

string

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

reference_images

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 فقط ولا يقبل مراجع الصور.

material_asset_id

string

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

material_asset_ids

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

reference_image_type

string

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

kling_elements

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 عند استخدام مراجع العناصر.

video_url

string

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

video_urls

array

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

audio_url

string

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

audio_urls

array

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

task_id

string

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

extend_at

integer

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

extend_times

string

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

duration

integer

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

seconds

integer

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

aspect_ratio

string

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

resolution

string

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

output_audio

boolean

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

draft

boolean

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

draft_task_id

string

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

ratio

string

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

generate_audio

boolean

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

execution_expires_after

integer

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

priority

integer

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

safety_identifier

string

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

service_tier

string

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

frames

integer

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

camera_fixed

boolean

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

fps

integer

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

negative_prompt

string

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

seed

integer

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

cfg_scale

number

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

motion_strength

number

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

start_image

string

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

end_image

string

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

size

string

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

watermark

boolean

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

effect_type

string

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

user

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، فاعتبرهما نفس المهمة.

task_id

string

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

poll_url

string

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

billing_transaction_id

string

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

status

string

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

created

integer

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

model

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 Elements

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

​نظرة عامة

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

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

​جسم الطلب

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

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

​معاملات Seedance

​مثال Seedance

​الاستجابة

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

​Kling 3.0 Elements

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

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

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

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

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

نظرة عامة

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

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

جسم الطلب

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

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

معاملات Seedance

مثال Seedance

الاستجابة

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

Kling 3.0 Elements

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

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

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

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

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