إنشاء فيديو

نظرة عامة

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

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

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

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

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

جسم الطلب

model

string

افتراضي:"sora-2"

معرّف نموذج الفيديو. القيمة الافتراضية في API هي sora-2. راجع دليل توليد الفيديو للاطلاع على مصفوفة النماذج العامة الحالية والقدرات المدعومة.

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 ملفات صوت مرجعية. يُفضَّل استخدام روابط https العامة، كما تقبل النماذج المتوافقة أيضًا روابط data:.

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

رابط URL عام للفيديو المصدر. هذا الحقل مطلوب للتدفقات العامة الحالية من نوع video-to-video ولنماذج motion-control.

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

مدة فيديو الإخراج الناتج بالثواني. القيم المتاحة تعتمد على النموذج. هذا الحقل يتحكم فقط في طول الإخراج، ولا يمثّل حدًا لمدة فيديو المرجع المُدخل.

aspect_ratio

string

نسبة الأبعاد، مثل 16:9 أو 9:16 أو 1:1.

resolution

string

دقة الإخراج، مثل 720p أو 1080p أو 4k. ويعتمد توفرها على النموذج.

output_audio

boolean

مفتاح إخراج الصوت يعتمد على النموذج. في TokenLab، طلبات عائلة Veo 3 تكون true افتراضيا عند حذف هذا الحقل. يقبل kling-3.0-video هذا المحدد للطلبات التي لا تستخدم مراجع العناصر ويحوّله إلى تحكم الصوت المتوافق upstream؛ وعند الحذف تكون طلبات Kling صامتة افتراضيا. لا تجمع output_audio=true مع kling_elements. تتبع نماذج الفيديو العامة الأخرى سلوكها الافتراضي المحكوم. يتم قبول الاسم camelCase outputAudio للتوافق.

fps

integer

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

negative_prompt

string

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

seed

integer

قيمة seed عشوائية للحصول على نتائج قابلة لإعادة الإنتاج.

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

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

watermark

boolean

مفتاح العلامة المائية للنماذج التي تكشفه بشكل عام.

effect_type

string

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

user

string

معرّف فريد للمستخدم النهائي.

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

الحقول العامة القياسية تستخدم صيغة snake_case: reference_images و reference_image_type و output_audio.
ولأغراض التوافق، يقبل TokenLab أيضًا الأسماء البديلة camelCase: referenceImages و referenceImageType و outputAudio.
إذا لم تُرسل operation، فسيقوم TokenLab باستنتاجها من المدخلات. ومع ذلك، في الإنتاج يُنصح بإرسالها بشكل صريح.

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

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

الاستجابة

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": "sora-2",
    "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": "sora-2",
  "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 ملفات صوت مرجعية. يتحكم duration فقط في طول الإخراج الناتج، ولا يضع حدًا منفصلًا لمدة فيديو المرجع المُدخل.

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

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

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

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

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

إذا كان النموذج يحتاج إلى صورة للعنصر وفيديو مرجعي للحركة معًا، فاستخدم operation=motion-control. يقوم TokenLab بتطبيع الشكل العام image_url + video_url ليتوافق مع عقدة الـ upstream المناسبة.

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

التوفر الحالي لـ audio-to-video و video-extension

يقبل العقد العام لـ TokenLab القيمتين audio-to-video و video-extension لبعض التدفقات الخاصة بالنماذج. لكن قائمة النماذج العامة المفعلة على نطاق واسع في هذا البناء من الوثائق لا تتضمن حاليًا نموذجًا عامًا واسع التفعيل يعلن أيًا من هاتين القدرتين. قبل دمج هذه التدفقات، تحقق من التوفر الحالي عبر واجهة Models API أو صفحة النماذج.

قائمة نماذج الفيديو العامة المفعّلة حاليًا

هذه القائمة متوافقة مع مخزون نماذج الفيديو العامة المفعلة في هذا البناء من الوثائق. ولأحدث حالة، استخدم واجهة Models API.

OpenAI

النموذج	العمليات العامة
`sora-2`	نص إلى فيديو، image-to-video
`sora-2-pro`	نص إلى فيديو، image-to-video
`sora-2-pro-storyboard`	من صورة إلى فيديو

Kuaishou

النموذج	العمليات العامة
`kling-3.0-motion-control`	تحكم في الحركة
`kling-3.0-video`	نص إلى فيديو، image-to-video، start-end-to-video، مراجع العناصر
`kling-v2.5-turbo-pro`	نص إلى فيديو، image-to-video، start-end-to-video
`kling-v2.5-turbo-std`	نص إلى فيديو، image-to-video
`kling-v2.6-pro`	نص إلى فيديو، image-to-video، start-end-to-video
`kling-v2.6-std`	نص إلى فيديو، image-to-video
`kling-v3.0-pro`	نص إلى فيديو، image-to-video، start-end-to-video
`kling-v3.0-std`	نص إلى فيديو، image-to-video، start-end-to-video
`kling-video-o1-pro`	نص إلى فيديو، image-to-video، reference-to-video، start-end-to-video، video-to-video
`kling-video-o1-std`	نص إلى فيديو، image-to-video، reference-to-video، start-end-to-video، video-to-video

Google

النموذج	العمليات العامة
`veo3`	نص إلى فيديو، image-to-video
`veo3-fast`	نص إلى فيديو، image-to-video
`veo3-pro`	نص إلى فيديو، image-to-video
`veo3.1`	نص إلى فيديو، image-to-video، reference-to-video، start-end-to-video
`veo3.1-fast`	نص إلى فيديو، image-to-video، reference-to-video، start-end-to-video
`veo3.1-pro`	نص إلى فيديو، image-to-video، start-end-to-video

ByteDance

النموذج	العمليات العامة
`seedance-1.5-pro`	نص إلى فيديو، image-to-video

MiniMax

النموذج	العمليات العامة
`hailuo-2.3-fast`	من صورة إلى فيديو
`hailuo-2.3-pro`	نص إلى فيديو، image-to-video
`hailuo-2.3-standard`	نص إلى فيديو، image-to-video

Alibaba

النموذج	العمليات العامة
`wan-2.2-plus`	نص إلى فيديو، image-to-video
`wan-2.5`	نص إلى فيديو، image-to-video
`wan-2.6`	نص إلى فيديو، image-to-video، reference-to-video

Shengshu

النموذج	العمليات العامة
`viduq2`	نص إلى فيديو، reference-to-video
`viduq2-pro`	صورة إلى فيديو، مرجع إلى فيديو، إطار بداية/نهاية إلى فيديو
`viduq2-pro-fast`	صورة إلى فيديو، إطار بداية/نهاية إلى فيديو
`viduq2-turbo`	صورة إلى فيديو، إطار بداية/نهاية إلى فيديو
`viduq3-pro`	نص إلى فيديو، image-to-video، start-end-to-video
`viduq3-turbo`	نص إلى فيديو، image-to-video، start-end-to-video

xAI

النموذج	العمليات العامة
`grok-imagine-image-to-video`	من صورة إلى فيديو
`grok-imagine-text-to-video`	نص إلى فيديو
`grok-imagine-upscale`	من فيديو إلى فيديو

أخرى

النموذج	العمليات العامة
`topaz-video-upscale`	من فيديو إلى فيديو

Documentation Index

​نظرة عامة

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

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

​جسم الطلب

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

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

​الاستجابة

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

​Kling 3.0 Elements

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

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

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

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

​التوفر الحالي لـ audio-to-video و video-extension

​قائمة نماذج الفيديو العامة المفعّلة حاليًا

​OpenAI

​Kuaishou

​Google

​ByteDance

​MiniMax

​Alibaba

​Shengshu

​xAI

​أخرى

نظرة عامة

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

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

جسم الطلب

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

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

الاستجابة

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

Kling 3.0 Elements

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

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

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

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

التوفر الحالي لـ audio-to-video و video-extension

قائمة نماذج الفيديو العامة المفعّلة حاليًا

OpenAI

Kuaishou

Google

ByteDance

MiniMax

Alibaba

Shengshu

xAI

أخرى