Passer au contenu principal
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
requis
Bearer token auth. Get a key from the API Key page.

Request parameters

string
requis
Fixed value: seedance-2.5
boolean
défaut:"false"
Indique s’il faut modérer le contenu avant d’envoyer la tâche vidéo.
  • true : vérifier les prompts et les images d’entrée avec omni-moderation-latest
  • false ou omis : ne pas envoyer de requête de modération, sans coût ni latence de modération supplémentaires (par défaut)
Contenu vérifié :
  • Texte : prompt, negative_prompt
  • Images : image_urls, image_with_roles[].url, first_frame_image, last_frame_image
  • Ressources privées image asset:// : résoudre puis vérifier leur URL publique d’origine
  • Images Base64 : les vérifier après conversion en URL publique
video_urls, audio_urls ainsi que les ressources privées vidéo/audio ne sont pas vérifiés, car le modèle de modération ne prend pas en charge la vidéo ni l’audio.ID de modèles pris en charge : seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.0-face, seedance-2.0-fast-face, seedance-2-0 (ancien nom) et seedance-2.5.L’appel de modération lui-même n’est pas facturé à l’utilisateur qui envoie la requête vidéo.
  • Un contenu détecté renvoie immédiatement HTTP 400 (nsfw_content_detected). Aucune tâche ni task_id n’est créé et aucun quota de génération vidéo n’est débité
  • Si la modération est indisponible, expire ou renvoie une réponse incorrecte, le comportement est fail-open et la génération continue. Cette option ne constitue pas une garantie absolue de sécurité du contenu
  • Les entrées impossibles à résoudre en URL publique d’image sont ignorées ; les modèles non pris en charge ignorent silencieusement nsfw_check: true
Exemple :
Réponse en cas de détection :
boolean
Définissez true pour créer un brouillon 480p. Seul seedance-2.5 le prend en charge. Sans ce champ, la génération est normale.
  • resolution doit être 480p ; valeur par défaut si omis : 480p
  • Incompatible avec draft_task_id
  • Le brouillon est valable 3 jours après sa création et permet de produire une vidéo finale 1080p après réussite
Voir Mode brouillon pour le déroulement.
string
Génère une vidéo finale 1080p à partir d’un brouillon terminé. Indiquez l’ID de tâche APIMart de la réponse du brouillon (data[0].task_id), pas une URL vidéo.
  • Uniquement seedance-2.5 ; utiliser le même modèle que le brouillon
  • Le brouillon doit appartenir à l’utilisateur de l’API Key actuelle, être terminé avec succès et avoir moins de 3 jours depuis sa création
  • resolution doit être 1080p ; valeur par défaut si omis : 1080p
  • Incompatible avec draft: true ; ne pas renvoyer les champs hérités tels que prompt, les références ou la durée
Champs modifiables et restrictions : Mode brouillon.
string
Obligatoire pour la génération normale et les brouillons. Interdit avec draft_task_id : la vidéo finale hérite de la consigne du brouillon.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
défaut:"720p"
Resolution — only:
  • 480p
  • 720p (default)
  • 1080p
Unsupported values like 2k / 4k return a sync 400.Exception du mode brouillon : draft: true accepte uniquement 480p, également par défaut ; draft_task_id accepte uniquement 1080p, également par défaut.
string
défaut:"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
défaut:"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
défaut:"true"
Whether to generate audio (alias field name: audio).
  • true: with audio (default)
  • false: silent video
boolean
défaut:"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
défaut:"mp4"
Output container:
  • mp4 (default)
  • mov: higher color precision — recommended for edit / extend workflows
string
défaut:"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
défaut:"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

Ces règles concernent la génération normale et les brouillons. Pour la vidéo finale, voir Facturation du mode brouillon.
  • 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).

Mode brouillon

Créez un brouillon 480p pour vérifier le rendu, puis utilisez son ID pour produire une vidéo finale 1080p. Celle-ci reprend la consigne, les références, la durée, le format, seed, le réglage audio et le type de tâche pour correspondre au brouillon.

Étape 1 : Créer un brouillon 480p

Ajoutez "draft": true à une requête normale. Les contraintes de médias et de type de tâche restent identiques. Sans resolution, 480p est utilisé ; 720p ou 1080p renvoie 400.
Lisez l’ID dans data[0].task_id. Interrogez le statut de la tâche et ne soumettez la vidéo finale qu’après data.status=completed.
Interrogez toutes les 5 à 15 secondes. pending : en attente ; processing : génération ; completed : réussite ; failed : échec. L’URL vidéo est dans le tableau data.result.videos[].url ; lisez url[0].

Étape 2 : Créer la vidéo finale 1080p

Renseignez draft_task_id avec l’ID de l’étape 1. Sans resolution, 1080p est utilisé ; les autres résolutions renvoient 400.
La vidéo finale reçoit un nouvel ID de tâche. Consultez le résultat via GET /v1/tasks/{task_id}. Ces champs sont hérités du brouillon. Ne les renvoyez pas : même une valeur identique entraîne 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. Vous pouvez modifier ces options de sortie :
draft: true et draft_task_id sont incompatibles. Ni les brouillons ni les vidéos finales ne prennent en charge service_tier.Le brouillon expire 3 jours après sa création. Une tâche absente, appartenant à un autre utilisateur, non réussie, qui n’est pas un brouillon ou expirée entraîne 400 à la soumission finale, sans création de tâche ni facturation.
La vidéo finale utilise la même route que le brouillon ; le service les associe automatiquement. Si cette route est temporairement indisponible, la soumission renvoie 400. Réessayez plus tard avec le même draft_task_id. Un brouillon non expiré peut produire plusieurs vidéos finales. Chacune constitue une tâche indépendante facturée séparément.

Facturation du mode brouillon

Le brouillon est facturé comme une vidéo 480p normale. La durée des vidéos de référence est comptée normalement, jusqu’à 30 secondes au total. La vidéo finale est facturée en 1080p. Choisissez le niveau 1080P-input si l’étape 1 contenait des vidéos de référence d’origine, ou le niveau standard 1080P dans le cas contraire. Le règlement utilise le prix unitaire des tokens du niveau choisi. La durée d’entrée facturable de la vidéo finale correspond à la durée totale des vidéos de référence d’origine de l’étape 1, dans la limite de 30 secondes. La vidéo Draft générée ne compte pas comme vidéo d’entrée. Le POST de la vidéo finale fait toujours référence à draft_task_id ; ne renvoyez pas les médias de référence ni les autres champs hérités. L’absence de nouvel envoi des médias ne supprime pas la facturation de leur durée d’origine. Par exemple, si l’étape 1 demande 11 secondes de sortie avec 22 secondes de vidéos de référence d’origine, les tokens de la vidéo finale sont estimés sur 11 + 22 = 33 secondes, avec le prix unitaire des tokens du niveau 1080P-input. Après réussite, règlement selon les tokens réels avec remboursement du surplus ou débit du complément. Échec : remboursement intégral. Tarifs et remises selon le prix du modèle.
Largeur et hauteur correspondent aux pixels de sortie de la tâche. Après réussite, data.usage.completion_tokens indique les tokens facturés pour vérification.

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