curl-Beispiele.
Varianten
Alle Varianten sind asynchron. Übermitteln Sie über
POST /api/v1/video/queue und pollen Sie anschließend POST /api/v1/video/retrieve, bis der Response-Body den Typ video/mp4 hat. Siehe Video Generation für den allgemeinen Queue-Ablauf.
Übergeben Sie resolution als einen der Werte: 480p, 720p, 1080p oder 4k (in Kleinbuchstaben). Seedance 2.0 (Nicht-Fast) und 2.5 akzeptieren alle vier; 2.0 Fast akzeptiert nur 480p / 720p. Ermitteln Sie aktuelle Model-IDs und Fähigkeiten über GET /models?type=video – kodieren Sie die Verfügbarkeit nicht fest.
Ausgabe-Bitrate
Sie können die Encode-Bitrate der Ausgabe bei jedem öffentlichen Seedance-2.0-Modell (einschließlich Fast) und 2.5-Modell festlegen. Übergeben Siebitrate_mode auf /video/queue selbst – Venice wählt dies nicht automatisch aus.
Dies ist eine reine Queue-Encoding-Option: Sie ändert weder Preis noch Token-Kosten, und
/video/quote akzeptiert bitrate_mode nicht. Andere Videofamilien (Wan, Kling, LTX usw.) unterstützen dieses Feld nicht.
Das Modell “Ein Modell, vier Workflows”
Die Reference-to-Video-Varianten (seedance-2-0-reference-to-video-basic, das Fast-Pendant und seedance-2-5-reference-to-video-basic) verwenden dasselbe Prompt-Routing-Muster. Das Modell leitet die Aufgabe aus dem Prompt-Präfix und der Form Ihrer Eingaben ab. Es gibt kein Feld task oder workflow – die Prompt-Syntax ist das Routing.
Die Prompt-Syntax ist kanonisch und Groß-/Kleinschreibung-sensitiv: spitze Klammern, großer Anfangsbuchstabe, ein Leerzeichen vor der Nummer –
<Video 1>, <Image 1>, <Audio 1>.
Workflow-Muster
Reference-Workflow
Verwenden Sie die hochgeladenen Referenzdateien als Donors – Motiv, Szene, Bewegung, Stil, Stimmklang –, um ein völlig neues Video zu erzeugen. Kanonische Prompt-Muster: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.(Audio-Donors müssen mit mindestens einer Bild- oder Video-Referenz kombiniert werden – reines Audio wird abgelehnt)
Edit-Workflow
Modifiziert ein einzelnes Eingabevideo. Alles, was nicht ausdrücklich im Prompt genannt wird, bleibt erhalten. Verwenden Sie diesen Workflow, wenn Sie eine lokale Änderung (Motiv-Austausch, Wetter-/Farbwechsel, Hinzufügen/Entfernen von Elementen) statt eines völlig neuen Videos wünschen. Kanonisches Prompt-Muster: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> als visuellen Donor für die Ersetzung.
Quellabgeglichenes Seitenverhältnis und Dauer
Für Seedance Reference-to-Video Edit / Extend können Sie die Ausgabe an den Quellclip anlehnen, statt ein festes Verhältnis oder eine feste Länge zu wählen:
Voraussetzungen:
- Queue: Jeder quellabgeglichene Wert erfordert
reference_video_urls. - Quote: Jeder quellabgeglichene Wert erfordert
reference_video_total_duration. Quellabgeglichene Dauer wird mitceil(reference_video_total_duration)Sekunden abgerechnet. - Seitenverhältnis und Dauer sind unabhängig – Sie können eines abgleichen, ohne das andere abzugleichen.
- Für Extend bevorzugen Sie eine feste
duration(wie lange generiert werden soll) und optionalaspect_ratio: "adaptive". Quellabgeglichenedurationist für Edit-typische „gleiche Länge wie Quelle”-Jobs gedacht.
omni_reference_task_type (Seedance 2.5 R2V)
BytePlus klassifiziert Seedance-2.5-All-Modal-Reference-Jobs anhand des Prompts als reference, edit oder extend. Sie können diese Klassifizierung bei /video/queue optional vorab steuern mit:
Die Aliase
editing→edit und extension→extend werden akzeptiert. Wird der Wert weggelassen, leitet Venice ihn aus dem Prompt ab, sofern reference_video_urls vorhanden sind. Der Prompt muss weiterhin zum gewählten Typ passen – ein Konflikt kann trotzdem asynchron fehlschlagen.
Extend-Workflow
Setzen Sie einen einzelnen Clip zeitlich vorwärts oder rückwärts fort. Standardmäßig gibt Seedance nur den neuen Inhalt zurück – nicht den ursprünglichen Input verkettet mit der Erweiterung. Das ist Absicht und dient der Übergangskontinuität; wenn Sie möchten, dass der Eingabeclip zusammen mit der Erweiterung erhalten bleibt, geben Sie das ausdrücklich an: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-Workflow (Track Completion)
Verbindet Eingabeclips mit KI-generierten Übergängen. Beachten Sie die familienspezifischen Obergrenzen für kombinierte Dauer und Clip-Anzahl in Multimodale Eingabelimits (Seedance 2.0: ≤3 Clips / ≤15 s kombiniert; Seedance 2.5: höhere Video-Obergrenzen). Kanonisches Prompt-Muster:<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>
Universelle Prompt-Formel
Über alle vier Workflows hinweg lautet die empfohlene Autorenformel:- Subject + Motion: die logische Grundlage – definiert “Wer” welche “Aktion” ausführt
- Environment + Aesthetics: räumlicher Hintergrund, Beleuchtung, visueller Stil
- Camera: expliziter Aufnahmetyp oder Bewegung
- Audio: Umgebungsklänge oder Stimmvorgabe für immersive Ausgabe
Strictly edit <Video 1>, changing its <subject + motion + environment + ...>), erhalten Sie Ergebnisse höchster Qualität.
Multimodale Eingabelimits
Die untenstehenden Werte sind das, was die Venice API akzeptiert. Anfragen außerhalb dieser Bereiche werden auf Schema-Ebene mit einem 400-Fehler abgelehnt, noch bevor Inferenz stattfindet. Seedance 2.0 und Seedance 2.5 verwenden unterschiedliche Obergrenzen. Prüfen Sie immer die Spalte für die Modellfamilie, die Sie aufrufen.Gemeinsame Medien-Mindestwerte
Familienvergleich
Referenzaudio wird nur bei den R2V-Varianten unterstützt. Jeder Eintrag wird an das Modell als
role: "reference_audio"-Content-Item weitergeleitet, das der Prompt als <Audio 1>, <Audio 2>, … adressiert. Das Modell verwendet jeden Clip je nach Prompt-Formulierung für Stimmklang, Soundeffekte oder Hintergrundmusik. Das veraltete singuläre Feld audio_url mappt auf dieselbe Content-Form und entspricht nun der Übergabe eines einelementigen reference_audio_urls.
Anfragegröße
Der Queue-Endpunkt akzeptiert JSON-Bodies bis 35 MB. Inline-Data-URLs für große Videos können diese Grenze überschreiten – insbesondere für Multi-Clip-Stitch bevorzugen Sie URLs gegenüber Inline-Base64.Entwurfsmodus (Seedance 2.5)
Seedance-2.5-Modelle, die den Entwurfsmodus unterstützen, etwaseedance-2-5-text-to-video-basic, können einen Entwurf in 480p rendern und diesen Entwurf später auf 1080p oder 4k hochstufen. Entwurf und Upgrade sind getrennte Anfragen und werden getrennt abgerechnet. Rufen Sie POST /api/v1/video/quote für jeden Preis auf, bevor Sie die Anfrage in die Warteschlange stellen.
Wenn Sie draft an ein anderes Modell senden, wird 400 “This model does not support draft” zurückgegeben. Wenn Sie draft_task_id an ein anderes Modell senden, wird 400 “This model does not support draft_task_id” zurückgegeben.
Einen Entwurf erstellen
Setzen Siedraft: true bei POST /api/v1/video/queue oder POST /api/v1/video/quote. resolution ist standardmäßig 480p. Jeder andere Wert gibt 400 “Draft mode requires resolution 480p” zurück. Ein 5-Sekunden-Entwurf in 16:9 hat 854×480.
Angebot für den Entwurf abrufen:
PROCESSING ist, enthalten diese Felder. draft_task_id ist die queue_id des Entwurfs.
Entwurf abrufen, während er läuft:
average_execution_time und execution_duration, wie jede andere Retrieve-Antwort. draft_expires_at liegt 7 Tage nach der Erstellung des Entwurfs. Wenn der Body zu video/mp4 wechselt, werden dieselben Entwurfswerte als Antwort-Header geliefert: x-venice-is-draft, x-venice-draft-task-id, x-venice-draft-expires-at und x-venice-can-upgrade-to-hd. In dieser abgeschlossenen Antwort ist x-venice-can-upgrade-to-hd bis draft_expires_at true.
Die Medien eines Entwurfs bleiben bis zum Ende des HD-Upgrade-Fensters erhalten, auch wenn delete_media_on_completion true ist.
Den Entwurf auf 1080p oder 4k hochstufen
Senden Sie ein neuesPOST /api/v1/video/queue mit draft_task_id gleich der queue_id des Entwurfs. Der Entwurf muss Ihnen gehören, dasselbe Modell verwenden und innerhalb des 7-Tage-Fensters liegen. resolution ist standardmäßig 1080p; senden Sie "resolution": "4k" für ein 4k-Upgrade. Jeder andere Wert gibt 400 “Draft HD upgrade requires resolution 1080p or 4k” zurück.
duration und aspect_ratio sind beim Upgrade optional. Seed, Dauer, Seitenverhältnis und Audio folgen dem Entwurf. Eine duration oder ein aspect_ratio, die nicht zum Entwurf passen, werden ignoriert, und die Werte des Entwurfs werden verwendet. Medieneingaben in der Upgrade-Anfrage werden ignoriert. prompt ist weiterhin erforderlich. Derselbe Entwurf kann innerhalb des Fensters mehrmals hochgestuft werden. Senden Sie draft und draft_task_id nicht zusammen.
Angebot für das Upgrade abrufen. Dieses Angebot erfordert Authentifizierung. duration ist in der Angebotsanfrage erforderlich, der Preis richtet sich aber nach der Dauer des Entwurfs. Fügen Sie "resolution": "4k" hinzu, um ein 4k-Upgrade anzufragen:
Preisgestaltung
Rufen SiePOST /api/v1/video/quote auf, um für eine bestimmte Anfrageform ein Angebot zu erhalten, bevor Sie sie an /video/queue senden. Der Quote-Endpunkt ist die einzige autoritative Quelle; Preisdetails können sich ändern und sollten nicht clientseitig gecacht oder dupliziert werden.
Wenn Referenzvideos Teil der Anfrage sind, geben Sie auch reference_video_total_duration (die Summe aller Referenzclip-Dauern in Sekunden) an, damit das Angebot dem entspricht, was /video/queue in Rechnung stellen wird:
Vollständige Beispiele
Alle Beispiele gehen davon aus, dassVENICE_API_KEY in der Umgebung gesetzt ist.
Text-to-Video
Seedance 2.0 Text-to-Video (4K)
Seedance 2.5 Text-to-Video (längere Dauer)
Image-to-Video (Erstes Frame)
Seedance-I2V-Modelle (
seedance-2-0-image-to-video-basic, seine Fast-Variante und seedance-2-5-image-to-video-basic) akzeptieren aspect_ratio nicht – das Ausgabe-Seitenverhältnis wird automatisch aus den Abmessungen des Eingabebildes abgeleitet. Wird das Feld übergeben, kommt ein 400-Fehler mit “This model does not support aspect_ratio” zurück. Verwenden Sie die T2V- oder R2V-Varianten, wenn Sie explizite Kontrolle über das Seitenverhältnis benötigen.Reference-Workflow – Motiv-Donor
Seedance 2.5 Reference-Workflow – Multi-Image
Reference-Workflow – Motiv- + Audio-Donor
Edit-Workflow
Seedance 2.5 Edit — quellabgeglichene Dauer und Seitenverhältnis
omni_reference_task_type: "edit" steuert die BytePlus-Klassifizierung vorab. duration: "auto" (oder "-1") und aspect_ratio: "adaptive" (oder "auto") bewirken, dass die Ausgabe dem Quellclip folgt. Siehe Quellabgeglichenes Seitenverhältnis und Dauer und omni_reference_task_type.
Edit-Workflow mit Bild-Verankerung
Extend vorwärts
Stitch (3 Clips)
Polling auf Abschluss
Nach jeder Queue-Übermittlung speichern Sie die zurückgegebenequeue_id und pollen /video/retrieve, bis der Response-Body vom Typ video/mp4 ist:
{ "status": "PROCESSING", ... }), während der Job läuft; sobald er abgeschlossen ist, wechselt der Response-Body zu video/mp4-Bytes. status ist entweder PROCESSING oder COMPLETED – es gibt keinen failed-Status. Ein fehlgeschlagener Job liefert stattdessen eine Non-200-Response mit dem aufgezeichneten Fehler. Siehe Video Generation für das vollständige Polling-Muster.
Fehlerbehebung
At least one reference is required for this model
Reference-to-Video-Übermittlungen müssen mindestens eines von reference_image_urls, reference_video_urls oder image_references enthalten. Reine Textgenerierung ist kein gültiger R2V-Workflow – verwenden Sie stattdessen eine Text-to-Video-Model-ID. reference_audio_urls allein reicht nicht aus (siehe Audio-Abschnitt oben). Beachten Sie, dass video_references auf Seedance nicht akzeptiert wird – es ist spezifisch für Modelle, die Voice-Audio pro Referenz unterstützen, und das Übergeben liefert “This model does not support per-reference video entities”.
Zu viele Referenzvideos / -bilder
Seedance 2.0 begrenzt R2V auf 9 Bilder und 3 Videos. Seedance 2.5 hebt diese Obergrenzen auf 30 Bilder und 10 Videos an. Wenn Sie das Familien-Limit überschreiten, kürzen Sie die Eingaben oder fügen Sie sie zuvor offline zusammen.Fehler bei Dauer / Gesamtdauer
- 2.0: Referenzvideo/-audio pro Clip
[2, 15]s; kombiniert Video/Audio ≤ 15 s; Ausgabe 4–15 s. - 2.5: Referenzvideo/-audio pro Clip
[2, 30]s; kombiniert Video/Audio ≤ 30 s; Ausgabe 4–30 s. - Quellabgeglichene Dauer (
-1/autobei Seedance 2.5): Quellclip muss 4–30 s sein, undreference_video_urls(Queue) bzw.reference_video_total_duration(Quote) ist erforderlich.
Prompt wird dem falschen Workflow zugeordnet
Der Workflow wird aus der Prompt-Syntax abgeleitet. Häufige Fehlrouten:- Extend gewollt, aber
Refer to ...geschrieben → das Modell behandelt Ihr Video als Donor, nicht als fortzusetzende Leinwand - Stitch gewollt, aber
Refer to ...geschrieben → das Modell wählt einen als Donor und ignoriert die anderen - Edit gewollt, aber
Generate a video based on <Video 1>geschrieben → mehrdeutig; das Modell greift möglicherweise auf Reference zurück
Strictly edit <Video 1>, ..., Extend <Video 1>, ..., <Video 1> + ... + followed by <Video 2>.
Nicht unterstützte Medien mit Personen
Die öffentlichen Seedance-API-Modelle führen keinen Consent-Attestierungs-Flow aus (consents.seedance / needs_consent). Medien mit erkennbaren Personen können mit einem Content-Policy- oder Provider-Fehler fehlschlagen. Verwenden Sie stattdessen die Venice-App oder Studio.
Angebot entspricht nicht dem in Rechnung gestellten Betrag
Wenn Sie ein Referenzvideo eingeschlossen, aberreference_video_total_duration nicht an /video/quote übergeben haben, können sich Angebot und in Rechnung gestellter Betrag unterscheiden. Übergeben Sie immer reference_video_total_duration (Summe aller Referenzclip-Dauern in Sekunden), wenn Referenzvideos vorhanden sind.
Entwurfsmodus
Diese Anfragen geben 400 zurück und werden nicht berechnet. Siehe Entwurfsmodus (Seedance 2.5).draftbei einem Modell, das es nicht unterstützt: “This model does not support draft”draft_task_idbei einem Modell, das es nicht unterstützt: “This model does not support draft_task_id”draftunddraft_task_idzusammen: “draft cannot be combined with draft_task_id”draft_task_id, die keine UUID ist: “draft_task_id must be a valid queue_id”- Unbekannte oder nicht verfügbare ID: “Draft queue id was not found or is no longer available.”
- Eine Queue-ID, die kein Seedance-2.5-Entwurf ist: “Only a Seedance 2.5 draft can be upgraded to HD.”
- Ein anderes Modell als der Entwurf: “Draft HD upgrade must use the same model as the draft.”
- Entwurf wird noch generiert: “Draft has not finished generating. Wait until it completes, then upgrade to HD.”
- Entwurf noch nicht vom Anbieter angenommen: “Draft is still submitting. Wait until the draft task is accepted before upgrading.”
- Älter als 7 Tage: “Draft expired. Draft task IDs are valid for 7 days from creation.”
- Entwurfs-
resolutionungleich480p: “Draft mode requires resolution 480p” - Upgrade-
resolutionungleich1080poder4k: “Draft HD upgrade requires resolution 1080p or 4k”
Referenzen
- Venice Video-Queue-Endpunkt:
POST /api/v1/video/queue - Venice Quote-Endpunkt:
POST /api/v1/video/quote - Ergänzender Leitfaden: Reference to Video (behandelt Kling O3 + Grok Imagine R2V)
- Ergänzender Leitfaden: Video Generation (Übersicht über Queue / Polling)