La generación de video con Seedance funciona con tareas asíncronas: la petición de creación solo devuelve un identificador de tarea y el video no aparece en la respuesta de forma inmediata. Quien integra la API debe consultar el estado por su cuenta, gestionar los fallos y guardar el resultado antes de que caduque el enlace.

Si se escribe el código con la lógica síncrona de Chat Completions, lo habitual es sufrir un tiempo de espera agotado en el primer paso. Este artículo sigue el orden real de implementación y explica Base URL, autenticación, envío, sondeo, descarga, callbacks e idempotencia.

Nota: Seedance, ByteDance, Doubao, Volcano Engine y Volcano Ark son marcas de sus respectivos titulares. Este artículo solo ofrece una explicación técnica y no implica ninguna relación de cooperación, representación ni licencia. Las rutas de interfaz, los nombres de modelo y los precios se rigen por la documentación oficial o la del sitio.

1. Parámetros de integración: Base URL, modelo y autenticación

La Base URL oficial del plano de datos de Volcano Ark es https://ark.cn-beijing.volces.com/api/v3, y la ruta para crear tareas de video es /contents/generations/tasks. La autenticación se realiza con Authorization: Bearer $ARK_API_KEY y el cuerpo de la petición es JSON.

El campo model admite un Model ID o un Endpoint ID. La diferencia está en la autenticación: con una clave de API suelen funcionar ambos; con firma AK/SK normalmente hay que indicar el Endpoint ID y no se puede escribir directamente el Model ID. Es uno de los errores más frecuentes al migrar o al diagnosticar.

Antes de integrar hay que confirmar tres puntos: que el modelo esté habilitado, que la cuota de la cuenta sea suficiente y que el canal actual admita la duración y la resolución que se van a usar. Quien utilice una pasarela debe revisar primero la documentación del sitio y comprobar si el canal de video y los campos de la tarea coinciden con los oficiales.

Operación Método y ruta Descripción
Crear tarea POST /contents/generations/tasks Devuelve un ID de tarea, no el video
Consultar tarea GET /contents/generations/tasks/{id} Consulta el estado y el resultado
Consultar lista GET /contents/generations/tasks Conciliación y compensación por lotes
Cancelar tarea Interfaz de cancelación o borrado según la documentación Suele aplicarse solo a tareas en cola

El grado de soporte de cancelación, borrado y consulta de listas varía entre plataformas; antes de integrar, guíate por la documentación. No repitas /api/v3 al final de la Base URL, porque se produce un error de ruta.

2. Enviar una tarea: qué incluye un POST

A continuación se muestra una petición habitual de creación de tarea; los campos son solo ilustrativos:

export ARK_API_KEY="tu-clave-de-api"
export BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

curl -sS -X POST "$BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
      {"type": "text", "text": "Puerto al amanecer, grúas cargando contenedores, toma aérea que rodea despacio, estilo realista"},
      {"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}, "role": "first_frame"}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "watermark": false,
    "callback_url": "https://api.example.com/callbacks/seedance"
  }'

Vale la pena fijarse en varios campos:

  • content es un arreglo; el texto, el fotograma inicial, las imágenes de referencia y los videos de referencia usan distintos valores de type y role.
  • Los rangos admitidos de duration, ratio y resolution cambian según la versión del modelo; no copies sin más la documentación de otro proveedor.
  • watermark determina si la pieza lleva marca de agua; confirma las reglas de la plataforma antes de un uso comercial.
  • callback_url recibe la notificación de finalización; si se admite o no depende de la plataforma real.
  • Campos como seed, camera_fixed y return_last_frame no están disponibles en todos los modelos.

Tras un envío correcto, guarda de inmediato en la base de datos el ID de tarea que devuelve la respuesta y vincúlalo al número de pedido del negocio. El sondeo, los reintentos, la conciliación y la imputación de costos dependen de ese identificador.

3. Sondeo: máquina de estados y estrategia de retroceso

Para consultar una tarea solo hace falta el ID:

curl -sS "$BASE_URL/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $ARK_API_KEY"

Los estados habituales y su tratamiento son los siguientes:

status Significado Tratamiento sugerido
queued En cola Seguir esperando; cancelar si es necesario
running Generando Continuar el sondeo; no reenviar
succeeded Correcto Leer el resultado y guardarlo de inmediato
failed Fallido Registrar el código de error y decidir si se reintenta
expired Terminado por tiempo agotado Ajustar el tiempo límite o los parámetros y reenviar
cancelled Cancelado Confirmar si la cancelación fue voluntaria

El sondeo no debe hacerse cada segundo de forma fija. Conviene empezar a los 5 segundos y retroceder a 10 y 20 segundos, con un máximo cercano a 30 segundos, añadiendo una pequeña variación aleatoria para que varias instancias no golpeen el proveedor al mismo tiempo. El tiempo máximo total se define según el negocio, por ejemplo 10 minutos; al superarlo, la tarea se marca como pendiente de revisión en lugar de esperar indefinidamente.

Los registros de tareas suelen poder consultarse solo durante un periodo limitado; la documentación oficial indica aproximadamente 7 días. Pasado ese plazo, el historial solo existe en la tabla de tareas propia, así que cada cambio de estado debe persistirse a tiempo.

4. Descargar y conservar el resultado

Cuando la tarea termina correctamente, la respuesta incluye una dirección de video. Ese enlace suele tener vigencia limitada; la documentación oficial señala unas 24 horas y algunos modelos limitan el número de descargas. No lo entregues al frontend ni al cliente como si fuera una dirección CDN permanente.

Lo correcto es descargar en cuanto se recibe el estado de éxito, transferir el archivo al almacenamiento de objetos propio y registrar el ID de tarea, el número de pedido, la ruta del objeto, el tamaño y el valor de verificación. Solo después se escribe la dirección interna en la base de datos del negocio. Así, aunque el enlace del proveedor caduque, los pedidos históricos pueden reproducirse y entregarse.

En la descarga también hay que prever archivos grandes, reanudación, límites de concurrencia y reintentos. Si la respuesta incluye además un fotograma inicial o audio, guárdalos por separado según su campo; no conserves solo el video.

5. ¿Webhook o sondeo?

Ambos métodos permiten obtener el resultado; la diferencia está en la inmediatez y el costo operativo:

Método Ventajas Desventajas Escenario adecuado
Webhook Menor latencia y menos consultas inútiles Requiere accesibilidad pública, verificación de firma y protección contra repetición Tareas asíncronas en producción
Sondeo Implementación sencilla, sin requisitos de red pública Latencia y peticiones adicionales Herramientas internas, pruebas y respaldo
Mixto Callback como vía principal y sondeo como respaldo Requiere deduplicación de estados La mayoría de sistemas en producción

En producción resulta más robusto combinar callback y conciliación: el callback aporta baja latencia y una tarea programada revisa los registros que llevan demasiado tiempo sin estado final. La interfaz de callback debe verificar la firma y ser idempotente; no puede insertar dos veces el mismo resultado ni activar dos veces el proceso siguiente por cada notificación recibida. La pérdida de callbacks no es rara, de modo que no conviene usarlos como único mecanismo de notificación.

6. Idempotencia y envíos duplicados

Las tareas de video tienen un costo unitario alto y tardan mucho; el precio de un envío duplicado es mucho mayor que en una interfaz de texto. Conviene controlarlo en cuatro niveles:

  • Generar una clave de idempotencia de negocio antes de enviar, por ejemplo el número de pedido más la versión, y consultar la base de datos antes de crear la tarea.
  • Crear un índice único entre el ID de tarea y el número de pedido para impedir registros duplicados a nivel de base de datos.
  • Un tiempo de espera agotado no equivale a un fallo de la tarea. Consulta primero por la clave de idempotencia o revisa la lista de tareas y confirma que no se creó nada antes de reintentar.
  • Reintentar solo ante 429, 5xx y errores de red; no repetir a ciegas un 400 por parámetros ni un rechazo de moderación de contenido.

Las cancelaciones y los reenvíos también deben registrarse con su motivo. De lo contrario, un mismo pedido puede producir varios videos, lo que aumenta el gasto y complica la conciliación. Se recomienda ejecutar a diario una tarea de conciliación que compare estados, costos y productos generados.

7. Errores comunes y diagnóstico

  • 401 AuthenticationError: clave ausente, caducada o con formato incorrecto en la cabecera; también puede deberse a una Base URL que no corresponde a la clave.
  • 403 AccessDenied, AccountOverdueError: permisos insuficientes, cuenta con deuda o servicio no habilitado.
  • 404 ModelNotOpen, UnsupportedModel: modelo no habilitado o nombre mal escrito.
  • 400 SensitiveContentDetected: el prompt o el material activó la moderación de contenido; cambia el material en lugar de reintentar una y otra vez.
  • 400 InvalidParameter: nombre de campo, duración, proporción o resolución fuera del rango permitido.
  • 429 RateLimitExceeded: reducir la concurrencia y aplicar retroceso exponencial; solicitar más cuota si hace falta.
  • failed o expired: leer error.code y error.message para distinguir un problema de parámetros, un rechazo de moderación y un fallo del proveedor.

Las cadenas de error pueden cambiar con las actualizaciones de la plataforma; al diagnosticar, guíate por la respuesta real y la documentación de códigos. Registrar en el log el código original, el ID de petición y los parámetros redactados acorta de forma notable el tiempo de localización.

8. Lista de comprobación para migrar

Al pasar de la interfaz oficial a una pasarela, o de una pasarela a otra plataforma, revisa cada punto:

  1. ¿Se sustituyen la Base URL y el método de autenticación como un conjunto, en lugar de cambiar solo la clave?
  2. ¿model debe llevar un Model ID o un Endpoint ID, y coincide con el método de autenticación actual?
  3. ¿Los nombres de campo, la duración, la proporción y la resolución están dentro del rango admitido por el nuevo canal?
  4. ¿La enumeración de estados cubre cola, ejecución, éxito, fallo, tiempo agotado y cancelación?
  5. ¿Se han validado la vigencia del enlace de resultado, el límite de descargas y la lógica de transferencia?
  6. ¿La dirección de callback es accesible desde internet y se han implementado la verificación de firma y la idempotencia?
  7. ¿Están en producción la clave de idempotencia, la tabla de tareas, la conciliación y las alertas?
  8. ¿Se han probado bajo carga la limitación de peticiones, los tiempos máximos, los reintentos y el límite de concurrencia?

Después de migrar, ejecuta primero un lote pequeño y compara tasa de éxito, tiempo medio y costo por pieza antes de aumentar el volumen. No cambies todo el tráfico sin un mecanismo de conciliación.

Preguntas frecuentes

¿La API de Seedance devuelve el video de forma síncrona?

Normalmente no. La creación de la tarea solo devuelve un ID; hay que sondear o esperar un callback y, una vez completada, descargar el video. Diseñar la integración como una interfaz síncrona favorece los tiempos agotados y los envíos duplicados.

¿Cuánto tiempo se conservan el ID de tarea y el resultado?

Según la documentación oficial, los registros de tareas suelen consultarse durante unos 7 días y el enlace del video resultante tiene una vigencia aproximada de 24 horas. Para conservarlo a largo plazo hay que transferirlo a un almacenamiento de objetos propio.

¿Qué intervalo de sondeo conviene?

Se puede empezar a los 5 segundos y retroceder gradualmente hasta 15 o 30 segundos, con un tiempo máximo total. El sondeo fijo y muy frecuente desperdicia peticiones y facilita la limitación de tasa.

¿Admite callbacks webhook?

La interfaz oficial de creación de tareas ofrece el campo callback_url, pero la entrega depende de la red y de las políticas de la plataforma. Si la pasarela admite callbacks debe confirmarse en la documentación del sitio; en producción conviene mantener el sondeo como respaldo.

¿Se cobra una tarea fallida?

Las reglas varían según la plataforma y el tipo de fallo. Antes de integrar, confirma cómo se facturan el rechazo de moderación, el tiempo agotado y la cancelación, y verifica la factura con un lote pequeño.

Siguiente paso

Ejecuta primero una tarea con la duración más corta y una resolución baja, y después completa la tabla de tareas, el sondeo, la transferencia y la conciliación. Si necesitas un punto de entrada unificado, puedes registrarte en ZSQH AI Gateway y confirmar el canal de Seedance y su facturación en la página de precios de modelos.

Lecturas relacionadas: