Saltar para o conteúdo 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
obrigatório
Bearer token auth. Get a key from the API Key page.

Request parameters

string
obrigatório
Fixed value: seedance-2.5
boolean
padrão:"false"
Define se o conteúdo deve ser moderado antes do envio da tarefa de vídeo.
  • true: verificar prompts e imagens de entrada com omni-moderation-latest
  • false ou omitido: não enviar solicitação de moderação, sem custo nem latência adicionais de moderação (padrão)
Conteúdo verificado:
  • Texto: prompt, negative_prompt
  • Imagens: image_urls, image_with_roles[].url, first_frame_image, last_frame_image
  • Assets privados de imagem asset://: resolver e verificar a URL pública original
  • Imagens Base64: verificar após a conversão para uma URL pública
video_urls, audio_urls e assets privados de vídeo/áudio não são verificados, pois o modelo de moderação não aceita vídeo nem áudio.IDs de modelo compatíveis: seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.0-face, seedance-2.0-fast-face, seedance-2-0 (nome antigo) e seedance-2.5.A chamada de moderação não é cobrada do usuário que envia a solicitação de vídeo.
  • Conteúdo detectado retorna HTTP 400 (nsfw_content_detected) de forma síncrona. Nenhuma tarefa ou task_id é criada e nenhuma cota de geração de vídeo é descontada
  • Se a moderação estiver indisponível, expirar ou retornar uma resposta inválida, o comportamento será fail-open e a geração continuará. Esta opção não é uma garantia absoluta de segurança do conteúdo
  • Entradas que não possam ser resolvidas para uma URL pública de imagem serão ignoradas; modelos não compatíveis ignoram silenciosamente nsfw_check: true
Exemplo:
Resposta quando detectado:
boolean
Defina true para gerar um rascunho 480p. Apenas seedance-2.5 oferece suporte. Se omitido, a geração é normal.
  • resolution deve ser 480p; se omitido, também usa 480p
  • Não pode ser combinado com draft_task_id
  • O rascunho vale por 3 dias desde a criação e, após sucesso, pode gerar um vídeo final 1080p
Veja o fluxo em Modo de rascunho.
string
Gera um vídeo final 1080p a partir de um rascunho concluído. Informe o ID de tarefa APIMart da resposta do rascunho (data[0].task_id), não uma URL de vídeo.
  • Apenas seedance-2.5; use o mesmo modelo do rascunho
  • O rascunho deve pertencer ao usuário da API Key atual, ter sido concluído com sucesso e estar dentro de 3 dias desde a criação
  • resolution deve ser 1080p; se omitido, também usa 1080p
  • Não combine com draft: true nem reenvie campos herdados, como prompt, referências ou duração
Campos ajustáveis e restrições: Modo de rascunho.
string
Obrigatório na geração normal e de rascunhos. Proibido com draft_task_id: o vídeo final herda o prompt do rascunho.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
padrão:"720p"
Resolution — only:
  • 480p
  • 720p (default)
  • 1080p
Unsupported values like 2k / 4k return a sync 400.Exceção do modo de rascunho: draft: true aceita apenas 480p, também padrão; draft_task_id aceita apenas 1080p, também padrão.
string
padrão:"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
padrão:"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
padrão:"true"
Whether to generate audio (alias field name: audio).
  • true: with audio (default)
  • false: silent video
boolean
padrão:"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
padrão:"mp4"
Output container:
  • mp4 (default)
  • mov: higher color precision — recommended for edit / extend workflows
string
padrão:"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
padrão:"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 regras são para geração normal e rascunhos. Para vídeos finais, veja Cobrança do modo de rascunho.
  • 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 de rascunho

Gere um rascunho 480p para conferir as imagens e use seu ID para criar um vídeo final 1080p. O vídeo final reutiliza o prompt, referências, duração, proporção, seed, configuração de áudio e tipo de tarefa para corresponder ao rascunho.

Etapa 1: Gerar um rascunho 480p

Adicione "draft": true à requisição normal. As restrições de mídia e tipo de tarefa continuam iguais. Sem resolution, usa 480p; 720p ou 1080p retorna 400.
Leia o ID em data[0].task_id. Consulte o status da tarefa e só envie o vídeo final após data.status=completed.
Consulte a cada 5–15 segundos. pending: na fila; processing: gerando; completed: sucesso; failed: falha. A URL do vídeo fica no array data.result.videos[].url; leia url[0].

Etapa 2: Gerar o vídeo final 1080p

Preencha draft_task_id com o ID da etapa 1. Sem resolution, usa 1080p; outras resoluções retornam 400.
O vídeo final retorna um novo ID de tarefa. Consulte o resultado com GET /v1/tasks/{task_id}. Os campos abaixo são herdados. Não os reenvie: até valores idênticos retornam 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. Estas opções de saída podem ser alteradas:
draft: true e draft_task_id são mutuamente exclusivos. Nem rascunhos nem vídeos finais aceitam service_tier.O rascunho expira 3 dias após a criação. Tarefa inexistente, de outro usuário, ainda não bem-sucedida, que não seja rascunho ou expirada retorna 400 ao enviar o vídeo final, sem criar tarefa ou cobrar.
O vídeo final usa a mesma rota do rascunho, associada automaticamente pelo serviço. Se a rota estiver indisponível, o envio retorna 400. Tente mais tarde com o mesmo draft_task_id. Um rascunho não expirado pode gerar vários vídeos finais. Cada um é uma tarefa independente, cobrada separadamente.

Cobrança do modo de rascunho

Rascunhos são cobrados como vídeos 480p normais. A duração dos vídeos de referência é incluída normalmente, até 30 segundos no total. O vídeo final é cobrado em 1080p. Selecione a faixa 1080P-input se o passo 1 incluiu vídeos de referência originais, ou a faixa padrão 1080P caso contrário. O acerto usa o preço unitário dos tokens da faixa correspondente. Os segundos de entrada cobrados no vídeo final correspondem à duração total dos vídeos de referência originais do passo 1, até 30 segundos. O próprio vídeo Draft gerado não conta como entrada de vídeo. O POST do vídeo final continua usando draft_task_id; não reenvie mídias de referência nem outros campos herdados. Não reenviar as mídias não retira sua duração original do cálculo da cobrança. Por exemplo, se o passo 1 solicitou 11 segundos de saída com 22 segundos de vídeos de referência originais, estime os tokens do vídeo final com 11 + 22 = 33 segundos e o preço unitário dos tokens da faixa 1080P-input. Após sucesso, o valor é ajustado aos tokens reais, com reembolso do excedente ou cobrança da diferença. Falhas são reembolsadas integralmente. Tarifas e descontos seguem o preço do modelo.
Largura e altura são as dimensões de saída da tarefa em pixels. Após sucesso, data.usage.completion_tokens informa os tokens usados no acerto.

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