curl.
المتغيرات
جميع المتغيرات غير متزامنة. أرسل عبر
POST /api/v1/video/queue، ثم استعلم POST /api/v1/video/retrieve حتى يصبح جسم الاستجابة video/mp4. راجع توليد الفيديو لتدفق قائمة الانتظار العام.
مرّر resolution كواحدة من: 480p أو 720p أو 1080p أو 4k (أحرف صغيرة). تقبل Seedance 2.0 (غير Fast) الأربعة جميعًا؛ بينما 2.0 Fast و 2.5 تقبلان 480p / 720p فقط. اكتشف معرفات النماذج الحية وقدراتها عبر GET /models?type=video — لا تُشفّر التوفر بشكل ثابت.
نموذج “نموذج واحد، أربعة تدفقات”
تستخدم متغيرات المرجع إلى الفيديو (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 من نوع “نفس مدة المصدر”.
تدفق 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 المضمّن.التسعير
استدعِ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 — المدة ونسبة العرض المتطابقتان مع المصدر
duration: "auto" (أو "-1") و aspect_ratio: "adaptive" (أو "auto") تجعل الإخراج يتبع المقطع المصدر. راجع نسبة العرض إلى الارتفاع والمدة المتطابقة مع المصدر.
تدفق Edit مع تثبيت الصورة
Extend للأمام
Stitch (3 مقاطع)
الاستعلام حتى الاكتمال
بعد كل إرسال إلى قائمة الانتظار، احفظqueue_id المُعاد واستعلم /video/retrieve حتى يصبح جسم الاستجابة video/mp4:
{ "status": "queued" | "running" | "failed", ... }) حتى تكتمل المهمة، عندها يتحول جسم الاستجابة إلى بايتات video/mp4. راجع توليد الفيديو لنمط الاستعلام الكامل.
استكشاف الأخطاء وإصلاحها
At least one reference is required for this model
يجب أن تتضمن طلبات المرجع إلى الفيديو واحدًا على الأقل من reference_image_urls أو reference_video_urls أو image_references أو video_references. التوليد النصي البحت ليس تدفق R2V صالحًا — استخدم معرف نموذج نص إلى فيديو بدلًا من ذلك. reference_audio_urls وحده ليس كافيًا (راجع قسم الصوت أعلاه).
الكثير جدًا من الفيديوهات / الصور المرجعية
تحدّ 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 العامة تدفق إثبات موافقة. قد تفشل الوسائط التي تحتوي على أشخاص يمكن اكتشافهم بخطأ سياسة محتوى أو خطأ من المزوّد. استخدم تطبيق Venice أو Studio بدلًا من ذلك.عرض السعر لا يطابق المبلغ المُدرَج في قائمة الانتظار
إذا أدرجت فيديو مرجعيًا ولكنك لم تمرّرreference_video_total_duration إلى /video/quote، فقد يختلف عرض السعر عن المبلغ المُدرَج في قائمة الانتظار. مرّر دائمًا reference_video_total_duration (مجموع مدد جميع المقاطع المرجعية بالثواني) عندما تكون الفيديوهات المرجعية موجودة.
المراجع
- نقطة نهاية قائمة انتظار الفيديو في Venice:
POST /api/v1/video/queue - نقطة نهاية عرض السعر في Venice:
POST /api/v1/video/quote - دليل مرافق: المرجع إلى الفيديو (يغطي Kling O3 + Grok Imagine R2V)
- دليل مرافق: توليد الفيديو (نظرة عامة على قائمة الانتظار / الاستعلام)