Cómo usar la API de Seedance: clave, solicitud, sondeo y referencias

Para usar la API de Seedance, crea una clave de API, envía el cuerpo oficial de tarea de vídeo de ModelArk a un único endpoint y sondea la tarea que devuelve hasta que la URL del vídeo esté lista. Los mismos pasos sirven para Seedance 2.0, Seedance 2.0 Fast, Seedance 2.0 Mini y Seedance 2.5; solo cambian el valor de model y algunos límites propios de cada modelo.

Esta guía recorre cada paso con código que funciona y después muestra cómo añadir referencias, editar un clip con Seedance 2.5 y delegar el trabajo a un agente de programación.

¿Qué necesitas antes de la primera solicitud?

1. Una clave de API. Créala en la página de claves de API y guárdala en tu servidor. Nunca la pongas en código del navegador.
2. Créditos. Añade saldo en la página de facturación. Los créditos nunca caducan y las tareas fallidas no se cobran.
3. Un ID de modelo. Elige uno de la tabla de abajo.

¿No sabes cuál elegir? La guía Seedance 2.0 vs Fast vs Mini y la guía Seedance 2.5 vs 2.0 los comparan.

export SEEDROUTER_API_KEY="your-key"

¿Cómo se envía una solicitud a Seedance?

Envía la tarea por POST a /v1/contents/generations/tasks. El cuerpo es la solicitud oficial de ModelArk «crear una tarea de generación 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
  }'

La respuesta es un ID de tarea, no un vídeo:

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

Si ya llamas a ModelArk, cambia solo la URL base a https://api.seedrouter.ai/v1 y la clave de API. Los campos desconocidos se rechazan antes de cobrar nada, igual que un ajuste que el modelo no admite, como 1080p en Fast o Mini.

¿Cómo se obtiene el vídeo?

Sondea la tarea cada 10 a 20 segundos hasta que status sea succeeded, failed o expired. Un clip de 5 segundos en 720p suele tardar de dos a tres minutos. En 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}.")

Una tarea completada tiene el vídeo en content.video_url, los tokens de vídeo facturados en usage.completion_tokens y los ajustes con los que realmente se renderizó, incluida la seed que eligió el modelo. El vídeo se aloja en nuestro almacenamiento; descárgalo al tuyo si lo necesitas a largo plazo.

Un tiempo de espera agotado al sondear no significa que el vídeo haya fallado. Conserva el ID de tarea y vuelve a consultarla; enviar una tarea nueva supone pagar un segundo vídeo. No hay URL de callback, así que el sondeo es la forma de obtener el resultado, y una tarea enviada no se puede cancelar.

¿Cómo se añaden imágenes, vídeos y audio?

Añade elementos a content, cada uno con una URL pública y un 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
  }'

Seedance 2.0 y sus versiones Fast y Mini aceptan hasta 9 imágenes de referencia, 3 vídeos y 3 pistas de audio; Seedance 2.5 acepta hasta 30, 10 y 10. Los archivos multimedia deben ser URL: no se aceptan base64 ni subidas de archivos. El modelo no admite imágenes ni vídeos de referencia con rostros humanos reales. Los archivos se comprueban al iniciar la tarea, y un archivo que incumple un límite hace fallar la tarea antes de cualquier generación, sin cobro.

¿Cómo se edita o extiende un clip con Seedance 2.5?

Envía el clip como reference_video y define 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"
}

Usa edit para cambiar lo que aparece en el metraje y extend para continuarlo más allá de su último fotograma. Para edit, deja duration en su valor por defecto de -1; para ambos, deja ratio como adaptive. Los segundos de entrada se facturan a la tarifa de referencia, como explica la guía de precios.

¿Cómo dejas que un agente de programación use la API de Seedance?

Un agente de programación como Claude Code, Codex o Cursor puede llamar a la API con un comando de shell o un script corto. SeedRouter no ofrece un servidor MCP, una skill empaquetada ni un nodo de ComfyUI; este prompt es toda la integración. Exporta primero la clave y luego pega:

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.

El paso de aprobación importa: el agente gasta tu saldo, así que nunca debe enviar tareas por su cuenta.

Preguntas frecuentes

¿Cómo consigo una clave de API de Seedance?

Inicia sesión, abre la página de claves de API y crea una clave. La misma clave sirve para todos los modelos Seedance y para el resto de modelos de SeedRouter.

¿Dónde está la documentación de la API de Seedance?

Las referencias de la API de Seedance 2.0 y Seedance 2.5 enumeran cada campo, límite y error, con ejemplos en cURL, Python, Node.js y Go, además de un archivo OpenAPI y una versión en Markdown que se puede copiar.

¿Puedo generar varios vídeos a la vez?

Envía una tarea por vídeo y sondea las tareas en paralelo. Cada tarea devuelve un vídeo y se factura por separado. Para listar las tareas recientes, llama a GET /v1/contents/generations/tasks con page_num, page_size y filtros como filter.status.

¿Qué errores debo gestionar?

Un 400 significa que el cuerpo incumplió una regla, como un campo desconocido o una resolución no admitida, y no se cobra nada. Una tarea que termina en failed o expired lleva un código y un mensaje de error y tampoco se cobra. La guía de errores enumera cada código y cuándo reintentar.

Envía tu primera solicitud

Crea una clave, añade un saldo pequeño y ejecuta el ejemplo de Python de arriba, o prueba la misma solicitud sin código en el playground de Seedance 2.0. Para clips más largos y edición, cambia el modelo a dreamina-seedance-2-5 y consulta la página de Seedance 2.5.