curl.
المتغيرات
جميع المتغيرات غير متزامنة. أرسل عبر
POST /api/v1/video/queue، ثم استعلم POST /api/v1/video/retrieve حتى يصبح جسم الاستجابة video/mp4. راجع توليد الفيديو لتدفق قائمة الانتظار العام.
مرّر resolution كواحدة من: 480p أو 720p أو 1080p أو 4k (أحرف صغيرة). تقبل Seedance 2.0 (غير Fast) و2.5 الأربعة جميعًا؛ وتقبل 2.0 Fast القيمتين 480p / 720p فقط. اكتشف معرفات النماذج الحية وقدراتها عبر GET /models?type=video — لا تُشفّر التوفر بشكل ثابت.
معدل بت الإخراج
يمكنك ضبط معدل بت ترميز الإخراج على كل نموذج Seedance 2.0 عام (بما في ذلك Fast) و 2.5. مرّرbitrate_mode على /video/queue بنفسك — لا يختار Venice ذلك تلقائيًا.
هذا خيار ترميز خاص بقائمة الانتظار فقط: لا يغيّر السعر ولا تكلفة الرموز، ولا يقبل
/video/quote الحقل bitrate_mode. عائلات الفيديو الأخرى (Wan و Kling و LTX وما إلى ذلك) لا تدعم هذا الحقل.
نموذج “نموذج واحد، أربعة تدفقات”
تستخدم متغيرات المرجع إلى الفيديو (seedance-2-0-reference-to-video-basic، وشقيقها Fast، و seedance-2-5-reference-to-video-basic) نمط توجيه الـ prompt نفسه. يستنتج النموذج المهمة من بادئة الـ prompt وشكل مدخلاتك. لا يوجد حقل task أو workflow — بناء الـ prompt هو التوجيه.
بناء الـ prompt قياسي وحساس لحالة الأحرف: أقواس زاوية، حرف أول كبير، مسافة واحدة قبل الرقم —
<Video 1> و <Image 1> و <Audio 1>.
أنماط التدفقات
تدفق Reference
استخدم الملفات المرجعية المرفوعة كـمصادر — الموضوع، المشهد، الحركة، الأسلوب، جرس الصوت — لتوليد فيديو جديد كليًا. أنماط الـ prompt القياسية:Refer to <Subject 1> in <Image 1> to generate a 5-second clip of the same character riding a horse through snow.Refer to the camera scene in <Video 1> to generate a similar establishing shot of a futuristic city at dawn.Refer to <Subject 1> in <Image 1> and use the timbre in <Audio 1> for the narrator describing the scene.(يجب إقران مصادر الصوت بمرجع صورة أو فيديو واحد على الأقل — يُرفض الصوت وحده)
تدفق Edit
عدّل فيديو مدخل واحد. يتم الحفاظ على كل ما لم يُذكر صراحةً في الـ prompt. استخدم هذا عندما تريد تغييرًا موضعيًا (استبدال الموضوع، تغيير الطقس / اللون، إضافة / إزالة عنصر) بدلًا من فيديو جديد كليًا. نمط الـ prompt القياسي:Strictly edit <Video 1>, changing its weather from sunny to a heavy rainstorm.Add snacks such as fried chicken and pizza to the countertop in <Video 1>.Remove the red car from <Video 1>, keeping the rest of the video content unchanged.Replace the perfume featured in <Video 1> with the face cream from <Image 1>, with all original motions and camera work preserved.
<Image 1> كمصدر بصري للاستبدال.
نسبة العرض إلى الارتفاع والمدة المتطابقة مع المصدر
بالنسبة لتدفقات edit / extend في المرجع إلى الفيديو من Seedance، يمكنك أن تطلب من الإخراج أن يتبع المقطع المصدر بدلًا من اختيار نسبة أو مدة ثابتة:
المتطلبات:
- Queue: أي قيمة متطابقة مع المصدر تتطلب
reference_video_urls. - Quote: أي قيمة متطابقة مع المصدر تتطلب
reference_video_total_duration. تُحاسَب المدة المتطابقة مع المصدر بـceil(reference_video_total_duration)ثانية. - النسبة والمدة مستقلتان — يمكنك مطابقة إحداهما دون الأخرى.
- بالنسبة لـ extend، فضّل
durationثابتة (المدة التي تريد توليدها) واختياريًاaspect_ratio: "adaptive".durationالمتطابقة مع المصدر مخصصة لمهام edit من نوع “نفس مدة المصدر”.
omni_reference_task_type (Seedance 2.5 R2V)
يصنّف BytePlus مهام المرجع متعدد الوسائط في Seedance 2.5 على أنها reference أو edit أو extend بناءً على الـ prompt. يمكنك اختياريًا توجيه ذلك التصنيف مسبقًا في /video/queue عبر:
يُقبل الاسمان المستعاران
editing→edit و extension→extend. عند حذف القيمة، تستنتجها Venice من الـ prompt إذا كانت reference_video_urls موجودة. يجب أن يظل الـ prompt متطابقًا مع النوع المختار — فأي تعارض قد يفشل بشكل غير متزامن.
تدفق Extend
استمرار مقطع واحد للأمام أو للخلف زمنيًا. افتراضيًا تُعيد Seedance المحتوى الجديد فقط — وليس المدخل الأصلي متسلسلًا مع الامتداد. هذا بحكم التصميم، لضمان استمرارية الانتقال؛ إذا كنت تريد الحفاظ على مقطع المدخل بجانب الامتداد، فاذكر ذلك صراحةً:Extend <Video 1>, generate a dramatic chase scene through narrow alleys at dusk.Extend <Video 1> backward, the same character walking toward the camera before the original shot begins.Extend <Video 1>, start with <Video 1>, then the camera pulls back to reveal a vast landscape.
تدفق Stitch (إتمام المسار)
اربط المقاطع المدخلة بانتقالات مولّدة بالذكاء الاصطناعي. احترم حدود المدة المُجمّعة وعدد المقاطع الخاصة بكل عائلة في حدود الإدخال متعدد الوسائط (Seedance 2.0: ≤3 مقاطع / ≤15 ثانية مجموع؛ Seedance 2.5: حدود فيديو أعلى). نمط الـ prompt القياسي:<Video 1> + a smooth seamless cut + followed by <Video 2><Video 1>. The moment a leaf falls to the ground, it sets off a special effect of golden particles. A gust of wind blows by, leading into <Video 2>.<Video 1> + a wisp of smoke transforms into a flock of birds + followed by <Video 2> + a slow dolly-in + followed by <Video 3>
صيغة الـ prompt الشاملة
عبر التدفقات الأربعة جميعًا، الصيغة الموصى بها للتأليف هي:- Subject + Motion: الأساس المنطقي — حدّد “مَن” يؤدي “أي فعل”
- Environment + Aesthetics: خلفية مكانية، إضاءة، أسلوب بصري
- Camera: نوع اللقطة أو الحركة الصريحة
- Audio: مؤثرات صوت محيطية أو توجيه صوتي للحصول على إخراج غامر
Strictly edit <Video 1>, changing its <subject + motion + environment + ...>) تنتج مخرجات بأعلى جودة.
حدود الإدخال متعدد الوسائط
القيم أدناه هي ما يقبله Venice API. تُرفض الطلبات خارج هذه النطاقات في طبقة الـ schema بخطأ 400 قبل الوصول إلى الاستدلال. تستخدم Seedance 2.0 و Seedance 2.5 حدودًا مختلفة. تحقق دائمًا من العمود الخاص بعائلة النموذج التي تستدعيها.الحدود الدنيا المشتركة للوسائط
مقارنة العائلات
الصوت المرجعي مدعوم على متغيرات R2V فقط. تُمرَّر كل إدخال إلى النموذج كعنصر محتوى بـ
role: "reference_audio" يُخاطبه الـ prompt بـ <Audio 1> و <Audio 2> … — يستخدم النموذج كل مقطع لجرس الصوت أو المؤثرات الصوتية أو الموسيقى الخلفية بناءً على كيفية صياغة الـ prompt له. حقل audio_url المفرد القديم يُطابق نفس شكل المحتوى وأصبح الآن مكافئًا لتمرير reference_audio_urls بعنصر واحد.
حجم الطلب
تقبل نقطة نهاية قائمة الانتظار أجسام JSON حتى 35 MB. عناوين URL المضمّنة للبيانات (data URLs) للفيديوهات الكبيرة يمكن أن تتجاوز هذا الحد — بالنسبة لتدفق Stitch متعدد المقاطع بشكل خاص، فضّل عناوين URL على base64 المضمّن.وضع المسودة (Seedance 2.5)
يمكن لنماذج Seedance 2.5 التي تدعم وضع المسودة، مثلseedance-2-5-text-to-video-basic، إنشاء مسودة بدقة 480p ثم ترقيتها لاحقًا إلى 1080p أو 4k. المسودة والترقية طلبان منفصلان ويُحاسَب عليهما بشكل منفصل. استدعِ POST /api/v1/video/quote للحصول على سعر كل منهما قبل إدراجه في قائمة الانتظار.
يؤدي إرسال draft إلى أي نموذج آخر إلى إرجاع 400 “This model does not support draft”. ويؤدي إرسال draft_task_id إلى أي نموذج آخر إلى إرجاع 400 “This model does not support draft_task_id”.
إنشاء مسودة
عيّنdraft: true في POST /api/v1/video/queue أو POST /api/v1/video/quote. القيمة الافتراضية لـ resolution هي 480p. أي قيمة أخرى تُرجع 400 “Draft mode requires resolution 480p”. مسودة مدتها 5 ثوانٍ بنسبة 16:9 أبعادها 854×480.
احصل على عرض سعر المسودة:
PROCESSING، هذه الحقول. draft_task_id هو queue_id الخاص بالمسودة.
استرجع المسودة أثناء تشغيلها:
average_execution_time وexecution_duration، كما في أي استجابة retrieve أخرى. draft_expires_at هو بعد 7 أيام من إنشاء المسودة. عندما يتحول جسم الاستجابة إلى video/mp4، تُرسَل قيم المسودة نفسها كترويسات استجابة: x-venice-is-draft وx-venice-draft-task-id وx-venice-draft-expires-at وx-venice-can-upgrade-to-hd. في تلك الاستجابة المكتملة، تكون قيمة x-venice-can-upgrade-to-hd هي true حتى draft_expires_at.
تُحفظ وسائط المسودة حتى انتهاء نافذة الترقية إلى HD، حتى عندما تكون قيمة delete_media_on_completion هي true.
ترقية المسودة إلى 1080p أو 4k
أرسل طلبPOST /api/v1/video/queue جديدًا مع تعيين draft_task_id إلى queue_id الخاص بالمسودة. يجب أن تكون المسودة ملكك، وعلى النموذج نفسه، وضمن نافذة الأيام السبعة. القيمة الافتراضية لـ resolution هي 1080p؛ أرسل "resolution": "4k" لترقية بدقة 4k. أي قيمة أخرى تُرجع 400 “Draft HD upgrade requires resolution 1080p or 4k”.
الحقلان duration وaspect_ratio اختياريان في الترقية. تتبع البذرة والمدة ونسبة العرض إلى الارتفاع والصوت المسودة. يُتجاهَل أي duration أو aspect_ratio لا يطابق المسودة، وتُستخدم قيم المسودة. تُتجاهَل مدخلات الوسائط في طلب الترقية. لا يزال prompt مطلوبًا. يمكن ترقية المسودة نفسها أكثر من مرة ضمن النافذة. لا ترسل draft وdraft_task_id معًا.
احصل على عرض سعر الترقية. يتطلب عرض السعر هذا المصادقة. الحقل duration مطلوب في طلب عرض السعر، لكن السعر يعتمد على مدة المسودة. أضف "resolution": "4k" للحصول على عرض سعر ترقية بدقة 4k:
التسعير
استدعِPOST /api/v1/video/quote للحصول على عرض سعر لشكل طلب معين قبل إرساله إلى /video/queue. نقطة نهاية عرض السعر هي المصدر الموثوق الوحيد؛ قد تتغير تفاصيل التسعير ولا ينبغي تخزينها مؤقتًا أو تكرارها من جانب العميل.
عندما تكون الفيديوهات المرجعية جزءًا من الطلب، مرّر أيضًا reference_video_total_duration (مجموع مدد جميع المقاطع المرجعية بالثواني) حتى يطابق عرض السعر ما سيحاسب عليه /video/queue:
أمثلة كاملة
تفترض جميع الأمثلة أنVENICE_API_KEY مضبوط في البيئة.
النص إلى فيديو
Seedance 2.0 النص إلى فيديو (4K)
Seedance 2.5 النص إلى فيديو (مدة أطول)
الصورة إلى فيديو (الإطار الأول)
نماذج Seedance I2V (
seedance-2-0-image-to-video-basic، ومتغيره Fast، و seedance-2-5-image-to-video-basic) لا تقبل aspect_ratio — تُشتق نسبة العرض إلى الارتفاع للإخراج تلقائيًا من أبعاد صورة المدخل. تمرير الحقل يُعيد خطأ 400 مع “This model does not support aspect_ratio”. استخدم متغيرات T2V أو R2V إذا كنت بحاجة إلى تحكم صريح في نسبة العرض إلى الارتفاع.تدفق Reference — مصدر الموضوع
تدفق Reference في Seedance 2.5 — صور متعددة
تدفق Reference — مصدر موضوع + صوت
تدفق Edit
Seedance 2.5 edit — المدة ونسبة العرض المتطابقتان مع المصدر
omni_reference_task_type: "edit" يوجّه تصنيف BytePlus مسبقًا. duration: "auto" (أو "-1") و aspect_ratio: "adaptive" (أو "auto") تجعل الإخراج يتبع المقطع المصدر. راجع نسبة العرض إلى الارتفاع والمدة المتطابقة مع المصدر و omni_reference_task_type.
تدفق Edit مع تثبيت الصورة
Extend للأمام
Stitch (3 مقاطع)
الاستعلام حتى الاكتمال
بعد كل إرسال إلى قائمة الانتظار، احفظqueue_id المُعاد واستعلم /video/retrieve حتى يصبح جسم الاستجابة video/mp4:
{ "status": "PROCESSING", ... }) أثناء تشغيل المهمة، ويتحول جسم الاستجابة إلى بايتات video/mp4 بمجرد اكتمالها. قيمة status إما PROCESSING أو COMPLETED — لا توجد حالة failed. المهمة الفاشلة تعيد بدلًا من ذلك استجابة غير 200 تحمل الخطأ المسجَّل. راجع توليد الفيديو لنمط الاستعلام الكامل.
استكشاف الأخطاء وإصلاحها
At least one reference is required for this model
يجب أن تتضمن طلبات المرجع إلى الفيديو واحدًا على الأقل من reference_image_urls أو reference_video_urls أو image_references. التوليد النصي البحت ليس تدفق R2V صالحًا — استخدم معرف نموذج نص إلى فيديو بدلًا من ذلك. reference_audio_urls وحده ليس كافيًا (راجع قسم الصوت أعلاه). لاحظ أن video_references غير مقبول على Seedance — فهو خاص بالنماذج التي تدعم صوتًا لكل مرجع على حدة، وتمريره يعيد “This model does not support per-reference video entities”.
الكثير جدًا من الفيديوهات / الصور المرجعية
تحدّ Seedance 2.0 R2V بـ9 صور و3 فيديوهات. ترفع Seedance 2.5 تلك الحدود إلى 30 صورة و10 فيديوهات. إذا تجاوزت حد العائلة، قلّص المدخلات أو ادمج أولًا خارج الاتصال.أخطاء المدة / المدة المُجمّعة
- 2.0: فيديو / صوت مرجعي لكل مقطع
[2, 15]ثانية؛ فيديو / صوت مُجمّع ≤ 15 ثانية؛ إخراج 4–15 ثانية. - 2.5: فيديو / صوت مرجعي لكل مقطع
[2, 30]ثانية؛ فيديو / صوت مُجمّع ≤ 30 ثانية؛ إخراج 4–30 ثانية. - المدة المتطابقة مع المصدر (
-1/autoفي Seedance 2.5): يجب أن يكون المقطع المصدر بين 4 و 30 ثانية، ويُطلبreference_video_urls(queue) أوreference_video_total_duration(quote).
الـ prompt يوجّه إلى التدفق الخطأ
يُستنتَج التدفق من بناء الـ prompt. حالات التوجيه الخاطئ الشائعة:- تريد Extend لكنك تكتب
Refer to ...→ يعامل النموذج فيديوك كـمصدر، وليس كخلفية للاستمرار - تريد Stitch لكنك تكتب
Refer to ...→ يختار النموذج واحدًا كمصدر، ويتجاهل الآخرين - تريد Edit لكنك تكتب
Generate a video based on <Video 1>→ غامض؛ قد يعود النموذج افتراضيًا إلى Reference
Strictly edit <Video 1>, ...، Extend <Video 1>, ...، <Video 1> + ... + followed by <Video 2>.
الوسائط التي تحتوي على أشخاص غير مدعومة
لا تُشغّل نماذج Seedance API العامة تدفق إثبات موافقة (consents.seedance / needs_consent). قد تفشل الوسائط التي تحتوي على أشخاص يمكن اكتشافهم بخطأ سياسة محتوى أو خطأ من المزوّد. استخدم تطبيق Venice أو Studio بدلًا من ذلك.
عرض السعر لا يطابق المبلغ المُدرَج في قائمة الانتظار
إذا أدرجت فيديو مرجعيًا ولكنك لم تمرّرreference_video_total_duration إلى /video/quote، فقد يختلف عرض السعر عن المبلغ المُدرَج في قائمة الانتظار. مرّر دائمًا reference_video_total_duration (مجموع مدد جميع المقاطع المرجعية بالثواني) عندما تكون الفيديوهات المرجعية موجودة.
وضع المسودة
تُرجع هذه الطلبات 400 ولا يُحاسَب عليها. راجع وضع المسودة (Seedance 2.5).draftعلى نموذج لا يدعمه: “This model does not support draft”draft_task_idعلى نموذج لا يدعمه: “This model does not support draft_task_id”draftوdraft_task_idمعًا: “draft cannot be combined with draft_task_id”draft_task_idليس UUID: “draft_task_id must be a valid queue_id”- معرّف غير معروف أو غير متاح: “Draft queue id was not found or is no longer available.”
- queue id ليس مسودة Seedance 2.5: “Only a Seedance 2.5 draft can be upgraded to HD.”
- نموذج مختلف عن نموذج المسودة: “Draft HD upgrade must use the same model as the draft.”
- المسودة لا تزال قيد الإنشاء: “Draft has not finished generating. Wait until it completes, then upgrade to HD.”
- المسودة لم يقبلها المزوّد بعد: “Draft is still submitting. Wait until the draft task is accepted before upgrading.”
- أقدم من 7 أيام: “Draft expired. Draft task IDs are valid for 7 days from creation.”
resolutionللمسودة غير480p: “Draft mode requires resolution 480p”resolutionللترقية غير1080pأو4k: “Draft HD upgrade requires resolution 1080p or 4k”
المراجع
- نقطة نهاية قائمة انتظار الفيديو في Venice:
POST /api/v1/video/queue - نقطة نهاية عرض السعر في Venice:
POST /api/v1/video/quote - دليل مرافق: المرجع إلى الفيديو (يغطي Kling O3 + Grok Imagine R2V)
- دليل مرافق: توليد الفيديو (نظرة عامة على قائمة الانتظار / الاستعلام)