Saltar al contenido 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
requerido
Bearer token auth. Get a key from the API Key page.

Request parameters

string
requerido
Fixed value: seedance-2.5
boolean
predeterminado:"false"
Indica si se debe moderar el contenido antes de enviar la tarea de vídeo.
  • true: revisar los prompts y las imágenes de entrada con omni-moderation-latest
  • false u omitido: no enviar una solicitud de moderación, sin coste ni latencia de moderación adicionales (predeterminado)
Contenido revisado:
  • Texto: prompt, negative_prompt
  • Imágenes: image_urls, image_with_roles[].url, first_frame_image, last_frame_image
  • Recursos privados de imagen asset://: resolver y revisar su URL pública original
  • Imágenes Base64: revisarlas después de convertirlas en una URL pública
video_urls, audio_urls y los recursos privados de vídeo/audio no se revisan, ya que el modelo de moderación no admite vídeo ni audio.ID de modelos compatibles: seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.0-face, seedance-2.0-fast-face, seedance-2-0 (nombre antiguo) y seedance-2.5.La llamada de moderación no se factura al usuario que envía la solicitud de vídeo.
  • El contenido detectado devuelve HTTP 400 (nsfw_content_detected) de forma síncrona. No se crea ninguna tarea ni task_id, y no se descuenta cuota de generación de vídeo
  • Si la moderación no está disponible, agota el tiempo de espera o devuelve una respuesta no válida, se aplica fail-open y la generación continúa. Esta opción no es una garantía absoluta de seguridad del contenido
  • Las entradas que no puedan resolverse como una URL pública de imagen se omiten; los modelos no compatibles ignoran silenciosamente nsfw_check: true
Ejemplo:
Respuesta cuando se detecta contenido:
boolean
Usa true para generar un borrador 480p. Solo lo admite seedance-2.5. Si se omite, la generación es normal.
  • resolution solo puede ser 480p; si se omite, usa 480p
  • No se puede combinar con draft_task_id
  • El borrador es válido 3 días desde su creación y, tras completarse, permite generar un vídeo final 1080p
Consulta el flujo en Modo borrador.
string
Genera un vídeo final 1080p a partir de un borrador completado. Indica el ID de tarea APIMart de la respuesta del borrador (data[0].task_id), no una URL de vídeo.
  • Solo seedance-2.5; usa el mismo modelo que en el borrador
  • El borrador debe pertenecer al usuario de la API Key actual, haberse completado correctamente y tener como máximo 3 días desde su creación
  • resolution solo puede ser 1080p; si se omite, usa 1080p
  • No combinar con draft: true ni reenviar campos heredados como prompt, referencias o duración
Campos ajustables y restricciones: Modo borrador.
string
Obligatorio en generación normal y de borradores. Prohibido con draft_task_id: el vídeo final hereda el prompt del borrador.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
predeterminado:"720p"
Resolution — only:
  • 480p
  • 720p (default)
  • 1080p
Unsupported values like 2k / 4k return a sync 400.Excepción del modo borrador: draft: true solo admite 480p, también por defecto; draft_task_id solo admite 1080p, también por defecto.
string
predeterminado:"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
predeterminado:"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
predeterminado:"true"
Whether to generate audio (alias field name: audio).
  • true: with audio (default)
  • false: silent video
boolean
predeterminado:"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
predeterminado:"mp4"
Output container:
  • mp4 (default)
  • mov: higher color precision — recommended for edit / extend workflows
string
predeterminado:"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
predeterminado:"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

Estas reglas corresponden a la generación normal y los borradores. Para vídeos finales, consulta Facturación del modo borrador.
  • 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).

Modo borrador

Genera un borrador 480p para comprobar el resultado visual y usa su ID para crear un vídeo final 1080p. Este reutiliza el prompt, referencias, duración, proporción, seed, ajuste de audio y tipo de tarea para ajustarse al borrador.

Paso 1: Generar un borrador 480p

Añade "draft": true a una solicitud normal. Las restricciones de medios y tipo de tarea son las mismas. Sin resolution, usa 480p; 720p o 1080p devuelve 400.
Lee el ID de data[0].task_id. Consulta el estado de la tarea y envía el vídeo final solo cuando data.status=completed.
Consulta cada 5–15 segundos. pending: en cola; processing: generando; completed: correcto; failed: fallido. La URL del vídeo está en el array data.result.videos[].url; lee url[0].

Paso 2: Generar el vídeo final 1080p

Rellena draft_task_id con el ID del paso 1. Sin resolution, usa 1080p; otras resoluciones devuelven 400.
El vídeo final devuelve un ID de tarea nuevo. Consulta el resultado con GET /v1/tasks/{task_id}. Estos campos se heredan del borrador. No los reenvíes: incluso valores idénticos devuelven 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. Puedes modificar estas opciones de salida:
draft: true y draft_task_id son mutuamente excluyentes. Ni los borradores ni los vídeos finales admiten service_tier.El borrador caduca 3 días después de crearse. Una tarea inexistente, de otro usuario, aún no completada correctamente, que no sea borrador o caducada devuelve 400 al enviar el vídeo final, sin crear tarea ni cobrar.
El vídeo final usa la misma ruta que el borrador; el servicio los vincula automáticamente. Si esa ruta no está disponible temporalmente, el envío devuelve 400. Reintenta después con el mismo draft_task_id. Un borrador vigente puede generar varios vídeos finales. Cada uno es una tarea independiente que se cobra por separado.

Facturación del modo borrador

El borrador se cobra como un vídeo 480p normal. La duración de los vídeos de referencia de entrada se incluye normalmente, hasta 30 segundos en total. El vídeo final se factura en 1080p. Selecciona el nivel 1080P-input si el paso 1 incluía vídeos de referencia originales, o el nivel estándar 1080P si no. La liquidación utiliza el precio unitario de los tokens del nivel correspondiente. Los segundos de entrada facturables del vídeo final corresponden a la duración total de los vídeos de referencia originales del paso 1, hasta 30 segundos. El vídeo Draft generado no cuenta como entrada de vídeo. El POST del vídeo final sigue haciendo referencia a draft_task_id; no vuelvas a enviar los medios de referencia ni otros campos heredados. No reenviar los medios no elimina su duración original del cálculo de la factura. Por ejemplo, si el paso 1 solicitó 11 segundos de salida con 22 segundos de vídeos de referencia originales, los tokens del vídeo final se estiman con 11 + 22 = 33 segundos y el precio unitario de los tokens del nivel 1080P-input. Tras el éxito se liquida según los tokens reales: se reembolsa el exceso o se cobra la diferencia. Los fallos se reembolsan íntegramente. Tarifas y descuentos según el precio del modelo.
Anchura y altura son las dimensiones de salida en píxeles de la tarea. Tras el éxito, data.usage.completion_tokens indica los tokens liquidados para comprobar la factura.

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