API de Seedance 2.5: ID de modelo, Python y Node.js

A 4 de agosto de 2026, ByteDance ya ha publicado Seedance 2.5 como producto, pero la API de vídeo y la tabla pública de modelos de BytePlus todavía enumeran la serie Seedance 2.0. Las capacidades del producto 2.5 están confirmadas; un ID ModelArk first-party de 2.5 aún no es verificable. Antes de llamar a la API, fija cuatro valores del mismo proveedor: host, alcance de la clave, namespace del modelo y endpoint asíncrono.

Distingue el producto Seedance 2.5 del contrato API

La página oficial de Seedance 2.5 confirma vídeos de hasta 30 segundos, dos extensiones, mejores referencias y edición, control de white model y edición con pantalla verde. No publica host, proceso de clave, ID de modelo ni esquema de petición.

La API de creación de BytePlus, actualizada el 31 de julio de 2026, y la tabla actual de modelos y precios siguen mostrando solo IDs 2.0. No presentes dreamina-seedance-2-5-260628, visto en páginas de terceros, como ID oficial de BytePlus. Si necesitas 2.5, espera a que aparezca en el catálogo first-party de tu cuenta o usa un proveedor que publique host, key, ID, endpoint, facturación y límites como un solo contrato. Para desplegar hoy, conserva 2.0 como fallback verificado.

Este es el contrato mínimo del fallback 2.0 de BytePlus:

text
host        = https://ark.ap-southeast.bytepluses.com
key scope   = proyecto de recursos de ModelArk + modelo/endpoint permitido (+ IP allowlist opcional)
model       = dreamina-seedance-2-0-260128
create      = POST /api/v3/contents/generations/tasks
retrieve    = GET  /api/v3/contents/generations/tasks/{task_id}
delivery    = callback_url + polling de reparación

Crea la clave en el proyecto de recursos de BytePlus ModelArk, guárdala en una variable de entorno del servidor y no la incluyas en JavaScript cliente, aplicaciones móviles ni repositorios públicos. La llamada de creación, según la referencia actual de BytePlus, puede empezar así:

bash
curl -X POST \
  "https://ark.ap-southeast.bytepluses.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-260128",
    "content": [{
      "type": "text",
      "text": "A calm product shot, one slow camera move, clean studio light"
    }],
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

La respuesta de creación contiene un id de tarea; no es el vídeo terminado. En esta revisión solo se comprobó, sin credenciales, que el endpoint correcto alcanza una frontera de autenticación con HTTP 401 y cuerpo JSON. No se ejecutó una generación autenticada ni se confirmó el acceso de una cuenta concreta al modelo, su cuota o su saldo.

Implementa el mismo task ID en Python y Node.js

Obtén las tres variables del mismo proveedor. SEEDANCE_MODEL puede ser el fallback 2.0 confirmado o un ID 2.5 que ese proveedor haya documentado. No reutilices estas rutas si su contrato no tiene forma Ark.

Python

python
import os, time, requests

base = os.environ["SEEDANCE_BASE_URL"].rstrip("/")
headers = {"Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}", "Content-Type": "application/json"}
payload = {
    "model": os.environ["SEEDANCE_MODEL"],
    "content": [{"type": "text", "text": "Plano de estudio lento de una taza de cerámica"}],
    "ratio": "16:9", "resolution": "720p", "duration": 5, "generate_audio": True,
}
r = requests.post(f"{base}/contents/generations/tasks", headers=headers, json=payload, timeout=30)
r.raise_for_status()
task_id = r.json()["id"]  # Persistir antes del polling.
while True:
    r = requests.get(f"{base}/contents/generations/tasks/{task_id}", headers=headers, timeout=30)
    r.raise_for_status()
    task = r.json()
    if task["status"] in {"succeeded", "failed", "expired"}:
        print(task)
        break
    time.sleep(5)

Node.js 18+

js
const base = process.env.SEEDANCE_BASE_URL.replace(/\/$/, "");
const headers = { Authorization: `Bearer ${process.env.SEEDANCE_API_KEY}`, "Content-Type": "application/json" };
async function call(path, init = {}) {
  const r = await fetch(`${base}${path}`, { ...init, headers: { ...headers, ...init.headers } });
  const type = r.headers.get("content-type") || "";
  if (!type.includes("application/json")) throw new Error(`Se esperaba JSON; llegó ${type}`);
  const data = await r.json();
  if (!r.ok) throw new Error(`${r.status}: ${JSON.stringify(data)}`);
  return data;
}
const created = await call("/contents/generations/tasks", {
  method: "POST",
  body: JSON.stringify({ model: process.env.SEEDANCE_MODEL, content: [{ type: "text", text: "Slow studio shot of a ceramic cup" }], ratio: "16:9", resolution: "720p", duration: 5, generate_audio: true }),
});
const taskId = created.id; // Persistir antes de consultar.
for (;;) {
  const task = await call(`/contents/generations/tasks/${taskId}`);
  if (["succeeded", "failed", "expired"].includes(task.status)) { console.log(task); break; }
  await new Promise(resolve => setTimeout(resolve, 5000));
}

Si el create agota el tiempo antes de devolver el ID, no envíes otro POST automáticamente. Registra el resultado como desconocido y reconcilia callback, logs o soporte del proveedor.

Elige una ruta completa, no un model ID aislado

Las tres rutas cubren necesidades distintas. Conserva todos los valores de una sola fila durante la petición.

El tutorial oficial de Seedance 2.0 de BytePlus distingue Standard, Fast y Mini. Trátalos como contratos de modelo separados y confirma en la consola que el ID esté disponible y activado para tu proyecto. Un resultado de Google o el ejemplo de otro proveedor puede revelar la intención de búsqueda, pero no sustituye esta fuente ni demuestra disponibilidad para una cuenta o país.

Si tu integración necesita propiedad oficial internacional y controles de endpoint, empieza por BytePlus. Si opera dentro de la infraestructura china y usa contratos doubao-*, elige Volcengine. Si ya centralizas proveedores detrás de una sola puerta de enlace, la documentación actual de LaoZhang ofrece una ruta relay. Su contrato actual no admite flujos con rostros de personas reales; detén esos trabajos antes de subir material. Si el relay no expone un modelo, región o control necesario, detén la integración en esa ruta y cambia al proveedor oficial directo.

Prueba la frontera antes de depurar el prompt

Una petición sin credenciales no valida una generación, pero sí ayuda a detectar un host o prefijo equivocado. Envía un POST con {} y registra status, Content-Type y si el cuerpo realmente es JSON.

Por tanto, 401 no prueba que el modelo esté habilitado, y 200 no prueba éxito si el cuerpo es HTML. Esta separación evita perder horas cambiando el prompt cuando el error pertenece al contrato de transporte.

Priority ordena una cola concreta; no acelera el modelo

En la inferencia online basada en endpoint de Seedance 2.0 de BytePlus, priority acepta enteros de 0 a 9. Un valor mayor adelanta una solicitud en cola frente a solicitudes de prioridad menor dentro del mismo endpoint. No interrumpe una tarea que ya se ejecuta, no compara colas de endpoints diferentes y no garantiza una generación más rápida. Tampoco es un parámetro de inferencia flexible offline.

Si necesitas prioridad, valida primero que tu ruta sea exactamente esa y registra el endpoint junto al job. No copies el campo a Volcengine o a un gateway suponiendo que conservará la misma semántica.

El callback es un evento repetible, no el dueño único del estado

BytePlus permite enviar callback_url al crear la tarea. Publica cambios de estado como queued, running, succeeded, failed y expired. Para entregas terminales succeeded o failed, la documentación indica hasta tres reintentos si no recibe confirmación satisfactoria dentro de cinco segundos.

Ese límite no convierte al callback en entrega exactamente una vez. El mismo evento puede llegar más de una vez, desordenado o después de que tu polling ya haya actualizado el job. Tampoco hay una firma pública que esta guía pueda afirmar con seguridad; no inventes un header de firma. Usa HTTPS y valida por otros medios verificables: task ID existente, pertenencia del task al job y al usuario, tipo y tamaño del cuerpo, estados permitidos y transición monotónica.

ts
async function handleSeedanceCallback(payload: ProviderTask) {
  const job = await jobs.findByProviderTaskId(payload.id);
  if (!job) return { status: 404 };

  await jobs.transaction(async (tx) => {
    const current = await tx.lock(job.id);
    if (current.processedEvents.includes(`${payload.id}:${payload.status}`)) return;
    if (!canAdvance(current.status, payload.status)) return;

    await tx.applyProviderState(current.id, payload);
    await tx.markEventProcessed(current.id, `${payload.id}:${payload.status}`);
  });

  return { status: 200 };
}

Responde con rapidez y mueve la descarga o el procesamiento pesado a una cola interna. Mantén además polling con backoff para tareas no terminales: es la vía de reparación cuando el callback no llega, tu despliegue estaba reiniciando o la validación local falló.

Un timeout de creación entra en cuarentena

El fallo más costoso no es un polling adicional, sino crear dos tareas para la misma intención. Antes del POST, crea un job local con una clave idempotente derivada del usuario, ruta, modelo, prompt normalizado, referencias y parámetros de salida. Después guarda el task ID del proveedor en una actualización atómica.

La regla de parada es sencilla: si existe cualquier evidencia de que el proveedor aceptó el trabajo, no repitas el create. Repara el vínculo task/job mediante registros y consultas disponibles. Solo un operador o una política explícita debe liberar una segunda creación cuando el resultado de la primera siga siendo indeterminado.

Cierra el flujo en tu almacenamiento

Cuando retrieve o callback indique succeeded, comprueba que exista la URL de salida, descárgala desde un worker y cópiala a almacenamiento controlado por tu aplicación. No conviertas una URL del proveedor en enlace permanente ni prometas un plazo de retención que no se haya verificado en la documentación actual.

Guarda junto al resultado el proveedor, host, modelo exacto, task ID, job ID local, estado terminal y parámetros necesarios para soporte. En los fallos, conserva el código y mensaje del proveedor sin registrar la API key ni URLs sensibles de entrada. Para separar selección de proveedor y diseño del input, consulta la comparación de proveedores de Seedance 2 API y la guía de prompts y referencias.

El contrato operativo completo queda así: elige una ruta, valida su frontera, crea una sola vez, persiste el task ID, acepta callbacks como eventos repetibles, repara con polling y conserva el resultado en tu propio sistema.