Zum Hauptinhalt springen
POST
Main changes vs 2.0: max duration 15s → 30s; references 9 images + 3 videos + 3 audios → 30 images + 10 videos + 10 audios; audio-only reference supported; mov output added.
Note: resolution supports 480p / 720p / 1080p (2.0’s 4k is not available on 2.5).

Authentication

string
erforderlich
Bearer token auth. Get a key from the API Key page.

Request parameters

string
erforderlich
Fixed value: seedance-2.5
boolean
Standard:"false"
Legt fest, ob der Inhalt vor dem Absenden des Videoauftrags moderiert wird.
  • true: Prompts und Eingabebilder mit omni-moderation-latest prüfen
  • false oder nicht angegeben: keine Moderationsanfrage und damit keine zusätzlichen Moderationskosten oder Verzögerung (Standard)
Geprüfte Inhalte:
  • Text: prompt, negative_prompt
  • Bilder: image_urls, image_with_roles[].url, first_frame_image, last_frame_image
  • Private Bild-Assets mit asset://: ursprüngliche öffentliche URL auflösen und prüfen
  • Base64-Bilder: nach der Umwandlung in eine öffentliche URL prüfen
video_urls, audio_urls sowie private Video- und Audio-Assets werden nicht geprüft, da das Moderationsmodell Video und Audio nicht unterstützt.Unterstützte Modell-IDs: seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.0-face, seedance-2.0-fast-face, seedance-2-0 (alter Name) und seedance-2.5.Der Moderationsaufruf selbst wird dem Benutzer, der die Videoanfrage absendet, nicht berechnet.
  • Bei erkannten Inhalten wird synchron HTTP 400 (nsfw_content_detected) zurückgegeben. Es werden weder ein Auftrag noch eine task_id erstellt und kein Kontingent für die Videogenerierung abgezogen
  • Ist die Moderation nicht verfügbar, läuft in ein Timeout oder liefert eine ungültige Antwort, gilt fail-open und die Generierung wird fortgesetzt. Diese Option ist keine absolute Garantie für Inhaltssicherheit
  • Eingaben, die nicht in eine öffentliche Bild-URL aufgelöst werden können, werden übersprungen; nicht unterstützte Modelle ignorieren nsfw_check: true ohne Meldung
Beispiel:
Antwort bei Erkennung:
boolean
Mit true wird ein 480p-Entwurf erstellt. Nur seedance-2.5 unterstützt dies. Ohne Angabe erfolgt eine normale Generierung.
  • resolution darf nur 480p sein; ohne Angabe gilt ebenfalls 480p
  • Nicht mit draft_task_id kombinierbar
  • Entwürfe sind 7 Tage ab Erstellung gültig; nach erfolgreichem Abschluss kann ein finales 1080p-Video erstellt werden
Ablauf siehe Entwurfsmodus.
string
Erstellt ein finales 1080p-Video aus einem abgeschlossenen Entwurf. Verwenden Sie die APIMart-Aufgaben-ID aus der Entwurfsantwort (data[0].task_id), keine Video-URL.
  • Nur seedance-2.5; dasselbe Modell wie beim Entwurf verwenden
  • Der Entwurf muss dem Benutzer des aktuellen API Key gehören, erfolgreich abgeschlossen und höchstens 7 Tage alt sein
  • resolution darf nur 1080p sein; ohne Angabe gilt ebenfalls 1080p
  • Nicht mit draft: true kombinieren und geerbte Felder wie prompt, Referenzmedien oder Dauer nicht erneut senden
Änderbare Felder und Einschränkungen siehe Entwurfsmodus.
string
Für normale Generierung und Entwürfe erforderlich. Bei draft_task_id darf das Feld nicht gesendet werden; der Prompt wird vom Entwurf übernommen.Prompt. Reference media with @图片1 / @视频1 / @音频1 (1-based index matching array order). English aliases in prompts may also be used depending on model behavior; keep indices aligned with arrays.Example: "Use @视频1 for first-person framing throughout, @音频1 as BGM, first frame is @图片1"
string
Standard:"720p"
Resolution — only:
  • 480p
  • 720p (default)
  • 1080p
Unsupported values like 2k / 4k return a sync 400.Ausnahme im Entwurfsmodus: draft: true unterstützt ausschließlich 480p als Standard; draft_task_id ausschließlich 1080p als Standard.
string
Standard:"adaptive"
Aspect ratio (field name aspect_ratio is also accepted).Values: 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive (default)
Edit, extend, and first/last-frame jobs have hard size constraints — see Task types and constraints.
integer
Standard:"5"
Duration in seconds:
  • 4 ~ 30
  • -1: model picks duration (pre-charge at the 30s cap; settle to actual length after completion)
If omitted: generate and bill 5 seconds.
boolean
Standard:"true"
Whether to generate audio (alias field name: audio).
  • true: with audio (default)
  • false: silent video
boolean
Standard:"false"
Add an “AI generated” watermark. Default false.
integer
Random seed. Different seeds usually yield different results for the same request; the same seed is similar but not guaranteed identical.
string
Standard:"mp4"
Output container:
  • mp4 (default)
  • mov: higher color precision — recommended for edit / extend workflows
string
Standard:"auto"
Sub-task type hint: auto / reference / edit / extend.Passing reference / edit / extend validates that type’s constraints at submit time. Invalid requests return 400, create no task, and charge nothing. See Task types and constraints.
array<string>
Reference image URLs, all treated as reference_image.Supports:
  • Public URL: https://example.com/pic.jpg
  • Private asset: asset://cm9xxxxxxxx
For first/last frames use image_with_roles.
  • Max 30 images
  • Prefer image_with_roles for first/last-frame roles
array<object>
Images with explicit roles.Example:
If video_urls / audio_urls are present, first_frame / last_frame are auto-converted to reference_image (multimodal reference job).
array<string>
Reference videos (reference_video).Input: video URL or asset ID (asset://...).See Reference video specs.
array<string>
Reference audio URLs (reference_audio). Public URLs or asset://....Max 10; total duration ≤ 30s (each clip 2~30s).
2.5 supports audio-only reference (no image/video required).
boolean
Standard:"false"
When true, the successful result also includes the last-frame image for chaining.
array<object>
Tool list for enhancements such as web search.Example:

Media limits

Reference video specs

  • Input: video URL or asset ID (asset://...)
  • Container: mp4, mov — codecs in the table below
  • Resolution: 480p, 720p, 1080p
  • Duration: each clip [2, 30] s; up to 10 reference videos; total duration of all videos ≤ 30s
  • Per-video dimensions:
    • Aspect ratio (width/height): [0.4, 2.5]
    • Side length (px): [300, 6000]
    • Total pixels: [640×640=409600, 3326×2494=8295044], i.e. width × height must fall in [409600, 8295044]
  • Size: each video ≤ 200 MB
  • Frame rate (FPS): [24, 60]

Supported codecs

Task types and constraints

The service infers task type from references and prompt intent. The last three types hard-constrain size / duration; violations fail asynchronously after the job starts (e.g. InvalidParameter.TaskTypeConstraint):

Turn async errors into sync errors with omni_reference_task_type

Passing reference / edit / extend declares the sub-task type so its constraints are validated at submit time. Invalid requests return 400 immediately: no task is created and nothing is charged — you do not have to poll until failed. Notes:
  • If edit omits duration, the platform sets it to -1. Omitting duration otherwise defaults to 5 seconds, which conflicts with the upstream edit requirement of -1. The trade-off is a 30-second prepaid hold (same as duration: -1); unused amount is refunded after completion. For a smaller hold, skip edit and use default auto.
  • If edit sends duration explicitly, it must be -1. Any other value returns 400 (output length follows the source video).
  • ⚠️ You can still fail asynchronously with InvalidParameter.TaskTypeMismatch. Upstream re-classifies the job from the prompt; a mismatch with your declared type is rejected. Keep prompt wording aligned (edit: “edit / delete / replace…”; extend: “extend forward/backward / continue…”).
  • All Seedance 2.5 channels share the same validation and upstream payload; switching channels does not change this behavior.

Asset library

You can pass public URLs as references, or upload into the library first and use asset://. Prefer the library when:
  1. Real human faces must use the library — raw URLs are blocked by content moderation; only approved library assets can be used
  2. Assets are reused often — upload once, skip repeated moderation on later jobs, faster submits
  3. URLs are signed temporary links — the platform stores a durable copy on ingest so later use does not depend on the original URL staying alive
  4. Library assets are synced to all available channels so multi-channel routing can use them wherever the job lands
The library is shared with the 2.0 family; approved asset:// IDs work in both 2.0 and 2.5 generation requests. Full submit fields: also see Private avatar assets.

Upload assets

The response includes a local task id. Poll with Get task status (GET /v1/tasks/{id}). After approval, list assets to obtain the asset:// ID.

Media limits (validated at submit)

Violations return 400 immediately (which asset index and which rule), without starting moderation or consuming moderation quota: Error example:
For 30s video assets, submit with "model": "seedance-2.5" (2.0 cannot use assets longer than 15s).
If the platform cannot probe the media (e.g. network blip), it may pass through and leave the decision to moderation.

Use in generation requests

Reference approved assets with asset:// in image_urls / image_with_roles / video_urls / audio_urls:
Multi-channel: after ingest, assets sync to all available channels so any routed channel can use them. If a channel’s copy is missing, the platform may re-upload from the original URL as a fallback (if that URL is already expired, that channel is skipped and another takes over).

Management APIs (quick reference)

Asset APIs are free of charge (auth + rate limits only); they do not create billing records.

FAQ

Q: How long does moderation take?
Images usually seconds; video and real-person assets may take minutes. Poll the task id until a terminal status.
Q: Moderation failed with no clear reason?
Some failures omit a detailed reason (often a transient fetch failure). The platform already retries once; if it still fails, change the URL (ensure it is publicly downloadable) and resubmit.
Q: Same asset for both 2.0 and 2.5 — upload twice?
No. Upload once; asset:// works for both generations. Cross-channel / cross-model sync is handled by the platform.
Q: Can I pass a real-person face as a raw URL?
Real-person assets must go through the library first.

Billing

Diese Regeln gelten für normale Generierung und Entwürfe. Für finale Videos siehe Abrechnung im Entwurfsmodus.
  • Billed by seconds × resolution tier.
  • With reference video input: billable seconds = total input video duration (≤30s) + output duration, at the input-reference rate tier.
  • duration = -1 (auto): pre-charge at the 30s cap; settle to actual output after completion.
  • Omit duration: generate and bill 5 seconds.
  • Failed jobs or content moderation blocks: full refund (charge only on successful output).

Entwurfsmodus

Erstellen Sie zunächst einen 480p-Entwurf zur Sichtprüfung und anschließend mit dessen Aufgaben-ID ein finales 1080p-Video. Dieses übernimmt Prompt, Referenzmedien, Dauer, Seitenverhältnis, seed, Audioeinstellung und Aufgabentyp, um dem Entwurf zu entsprechen.

Schritt 1: 480p-Entwurf erstellen

Ergänzen Sie eine normale Anfrage um "draft": true. Medien- und Aufgabentypbeschränkungen gelten weiterhin. Ohne resolution gilt 480p; 720p oder 1080p ergeben 400.
Lesen Sie die Entwurfs-ID aus data[0].task_id. Fragen Sie den Aufgabenstatus ab und senden Sie das finale Video erst bei data.status=completed.
Abfrageintervall: 5–15 Sekunden. pending bedeutet Warteschlange, processing Generierung, completed Erfolg und failed Fehler. Die Video-URL steht im Array data.result.videos[].url; lesen Sie url[0].

Schritt 2: Finales 1080p-Video erstellen

Setzen Sie draft_task_id auf die ID aus Schritt 1. Ohne resolution gilt 1080p; andere Auflösungen ergeben 400.
Das finale Video erhält eine neue Aufgaben-ID. Ergebnisabfrage über GET /v1/tasks/{task_id}. Folgende Felder werden geerbt. Nicht erneut senden: Selbst identische Werte ergeben 400: prompt, image_urls, image_with_roles, video_urls, audio_urls, duration, size, aspect_ratio, seed, generate_audio, audio, omni_reference_task_type, generation_type, camerafixed, web_search, tools. Diese Ausgabeoptionen können geändert werden:
draft: true und draft_task_id schließen sich aus. Weder Entwürfe noch finale Videos unterstützen service_tier.Entwürfe sind ab Erstellung 7 Tage gültig. Fehlende, fremde, noch nicht erfolgreiche, nicht als Entwurf erstellte oder abgelaufene Aufgaben führen bei Einreichung zu 400, ohne neue Aufgabe oder Abbuchung.
Das finale Video verwendet dieselbe Route wie der Entwurf; die Zuordnung erfolgt automatisch. Ist die Route vorübergehend nicht verfügbar, ergibt die Einreichung 400. Später mit derselben draft_task_id erneut versuchen. Ein gültiger Entwurf kann mehrfach finale Videos erzeugen. Jede Generierung ist eine eigene, separat abgerechnete Aufgabe.

Abrechnung im Entwurfsmodus

Entwürfe werden als normale 480p-Videos abgerechnet. Die Eingabedauer von Referenzvideos wird regulär berücksichtigt, insgesamt bis zu 30 Sekunden. Finale Videos nutzen immer den 1080p-Tarif ohne Videoeingabe. Referenzvideodauer aus dem Entwurf wird nicht erneut berechnet. Nach Erfolg erfolgt die Abrechnung nach tatsächlichen Tokens mit Erstattung oder Nachbelastung der Differenz. Fehler führen zur vollständigen Erstattung. Preise und Rabatte richten sich nach dem Modellpreis.
Breite und Höhe sind die Ausgabepixelmaße der jeweiligen Aufgabe. Nach Erfolg enthält data.usage.completion_tokens die abgerechneten Tokens.

Request examples

Text-to-video (30s)

Multimodal reference (image + video + audio)

Video edit

First–last frame

Private asset

Common errors

Response (submit)

integer
Status code; 200 on success
array
Submit response with status / task_id

Completed task (GET /v1/tasks/{task_id})

After submit, poll with Get task status. When status is completed, the payload looks like this.

Completed response example

Completed fields

Notes

  • Failed tasks (status=failed): cost is always 0 (pre-charge fully refunded); reason in data.error.message
  • usage may be missing for a few seconds after completion (settlement lag); query again shortly

Differences from 2.0