Como usar a API Seedance: chave, requisição, consulta e referências

Para usar a API Seedance, crie uma chave de API, envie o corpo oficial de tarefa de vídeo do ModelArk para um único endpoint e consulte a tarefa retornada até a URL do vídeo ficar pronta. Os mesmos passos valem para o Seedance 2.0, o Seedance 2.0 Fast, o Seedance 2.0 Mini e o Seedance 2.5; só o valor de model e alguns limites específicos de cada modelo mudam.

Este guia percorre cada passo com código que funciona e depois mostra como adicionar referências, editar um clipe com o Seedance 2.5 e passar o trabalho para um agente de código.

Do que você precisa antes da primeira requisição?

1. Uma chave de API. Crie uma na página de chaves de API e mantenha-a no seu servidor. Nunca a coloque em código do navegador.
2. Créditos. Adicione saldo na página de cobrança. Os créditos nunca expiram, e tarefas que falham não são cobradas.
3. Um ID de modelo. Escolha um na tabela abaixo.

Não sabe qual escolher? O guia Seedance 2.0 vs Fast vs Mini e o guia Seedance 2.5 vs 2.0 comparam os modelos.

export SEEDROUTER_API_KEY="your-key"

Como enviar uma requisição ao Seedance?

Faça um POST da tarefa para /v1/contents/generations/tasks. O corpo é a requisição oficial do ModelArk para “criar uma tarefa de geração de vídeo”:

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

A resposta é um ID de tarefa, não um vídeo:

{"id": "task_..."}

Se você já chama o ModelArk, mude apenas a URL base para https://api.seedrouter.ai/v1 e a chave de API. Campos desconhecidos são recusados antes de qualquer cobrança, assim como uma configuração que o modelo não suporta, como 1080p no Fast ou no Mini.

Como obter o vídeo?

Consulte a tarefa a cada 10 a 20 segundos até que status seja succeeded, failed ou expired. Um clipe de 5 segundos em 720p costuma levar de dois a três minutos. Em Python:

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}

response = requests.post(
    f"{API}/contents/generations/tasks",
    headers=headers,
    json={
        "model": "dreamina-seedance-2-0",
        "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5,
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = requests.get(f"{API}/contents/generations/tasks/{task_id}", headers=headers, timeout=30)
    result.raise_for_status()
    task = result.json()
    if task["status"] == "succeeded":
        print(task["content"]["video_url"])
        break
    if task["status"] in ("failed", "expired"):
        raise RuntimeError(task["error"]["message"])
    time.sleep(15)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Uma tarefa com sucesso traz o vídeo em content.video_url, os tokens de vídeo cobrados em usage.completion_tokens e as configurações realmente renderizadas, incluindo o seed que o modelo escolheu. O vídeo fica hospedado no nosso armazenamento; baixe-o para o seu se precisar dele a longo prazo.

Um tempo limite durante a consulta não significa que o vídeo falhou. Guarde o ID da tarefa e consulte de novo; enviar uma nova tarefa significa pagar por um segundo vídeo. Não há URL de callback, então a consulta é a forma de obter o resultado, e uma tarefa enviada não pode ser cancelada.

Como adicionar imagens, vídeos e áudio?

Adicione itens em content, cada um com uma URL pública e um role:

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [
      {"type": "text", "text": "The character from the image walks through the market in the video, same camera move"},
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/market.mp4"}, "role": "reference_video"}
    ],
    "ratio": "adaptive",
    "duration": 8
  }'

O Seedance 2.0 e suas versões Fast e Mini aceitam até 9 imagens de referência, 3 vídeos e 3 faixas de áudio; o Seedance 2.5 aceita até 30, 10 e 10. A mídia precisa ser URL: base64 e upload de arquivos não são aceitos. Imagens e vídeos de referência com rostos humanos reais não são suportados pelo modelo. A mídia é verificada quando a tarefa começa, e um arquivo que viola um limite faz a tarefa falhar antes de qualquer geração, sem cobrança.

Como editar ou estender um clipe com o Seedance 2.5?

Envie o clipe como reference_video e defina omni_reference_task_type:

{
  "model": "dreamina-seedance-2-5",
  "content": [
    {"type": "text", "text": "Change the jacket to red. Keep everything else the same."},
    {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}, "role": "reference_video"}
  ],
  "omni_reference_task_type": "edit"
}

Use edit para mudar o que aparece no vídeo e extend para continuá-lo depois do último quadro. Para edit, deixe duration no padrão -1; nos dois casos, deixe ratio como adaptive. Os segundos de entrada são cobrados pela tarifa de referência, como explica o guia de preços.

Como deixar um agente de código usar a API Seedance?

Um agente de código como Claude Code, Codex ou Cursor pode chamar a API com um comando de shell ou um script curto. A SeedRouter não oferece um servidor MCP, uma skill empacotada nem um nó do ComfyUI; este prompt é toda a integração. Exporte a chave primeiro e depois cole:

Use the SeedRouter API to generate a Seedance video for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.

Goal: [subject, action, camera move, lighting, what the clip is for]
Model: [dreamina-seedance-2-0 | dreamina-seedance-2-0-fast | dreamina-seedance-2-0-mini | dreamina-seedance-2-5]
Resolution: [480p | 720p | 1080p | 4k]    Ratio: [16:9 | 9:16 | 1:1 | adaptive]    Duration: [seconds]
References: [public image, video or audio URLs with their roles, or none]

Send POST https://api.seedrouter.ai/v1/contents/generations/tasks with
{"model": "...",
 "content": [{"type": "text", "text": "..."}],
 "resolution": "...", "ratio": "...", "duration": 5}
Media goes in content as image_url, video_url or audio_url items with a role,
never base64. Do not add fields that are not in the API reference.

Before sending, show me the request body and wait for my approval: each
task is charged. Then poll GET https://api.seedrouter.ai/v1/contents/generations/tasks/{id}
every 15 seconds until status is succeeded, failed or expired. If polling
times out, keep checking the same task; never resubmit. Save
content.video_url into ./videos/ and tell me the file path.

A etapa de aprovação importa: o agente gasta o seu saldo, então ele nunca deve enviar por conta própria.

Perguntas frequentes

Como obter uma chave de API do Seedance?

Entre na sua conta, abra a página de chaves de API e crie uma chave. A mesma chave funciona para todos os modelos Seedance e para os outros modelos da SeedRouter.

Onde está a documentação da API Seedance?

As referências da API do Seedance 2.0 e do Seedance 2.5 listam cada campo, limite e erro, com exemplos em cURL, Python, Node.js e Go, além de um arquivo OpenAPI e uma versão em Markdown para copiar.

Posso gerar vários vídeos de uma vez?

Envie uma tarefa por vídeo e consulte as tarefas em paralelo. Cada tarefa retorna um vídeo e é cobrada separadamente. Para listar as tarefas recentes, chame GET /v1/contents/generations/tasks com page_num, page_size e filtros como filter.status.

Quais erros devo tratar?

Um 400 significa que o corpo violou uma regra, como um campo desconhecido ou uma resolução não suportada, e nada é cobrado. Uma tarefa que termina como failed ou expired traz um código e uma mensagem de erro e também não é cobrada. O guia de erros lista cada código e quando tentar de novo.

Envie sua primeira requisição

Crie uma chave, adicione um saldo pequeno e execute o exemplo em Python acima, ou teste a mesma requisição sem código no playground do Seedance 2.0. Para clipes mais longos e edição, mude o modelo para dreamina-seedance-2-5 e veja a página do Seedance 2.5.