Seedance es un modelo de generación de video de ByteDance. A diferencia de los modelos de texto, su API funciona con tareas asíncronas: al enviar una petición solo se obtiene un ID de tarea, hay que sondear el estado y, cuando termina correctamente, descargar el video. Para los equipos que operan desde China, el reto no es solo conseguir que la petición salga, sino también resolver el pago y la factura, el tiempo en cola, la conservación del resultado y la conmutación ante fallos.

Este artículo compara tres rutas habituales —conexión directa a Volcano Ark, proxy inverso propio y pasarela de IA local— y ofrece métodos de sondeo, entrega y validación.

Nota: Seedance es el nombre de un modelo de generación de video de Volcengine, perteneciente a ByteDance; las marcas relacionadas pertenecen a sus titulares. Este artículo solo ofrece una explicación técnica y no implica relación de dependencia ni cooperación con ByteDance. Las interfaces, los modelos y los precios se rigen por la documentación oficial y la página de precios de modelos del sitio.

1. Las tres rutas en una tabla

Dimensión Conexión directa oficial Proxy propio Pasarela de IA local
Entrada Dirección oficial de Volcano Ark Proxy inverso mantenido por el equipo Entrada unificada compatible con OpenAI
Red Depende de la salida local y de la región Depende del servidor de proxy La mantiene el proveedor, aunque sigue influyendo la red local
Pago Según los métodos de recarga oficiales Hay que asumir primero servidor y ancho de banda Recarga en el sitio, reglas según la página
Factura Se solicita según las reglas oficiales Se gestiona por cuenta propia Según las reglas de facturación del proveedor
Alcance de modelos Modelos Seedance disponibles en el canal oficial Lo determina la configuración del proxy Según habilitación; puede incluir modelos de video de varios proveedores
Coste operativo Bajo Alto Medio
Equipo adecuado Un solo modelo y capacidad de completar el proceso oficial Con capacidad de operar red Varios modelos y facturación unificada

Ninguna ruta sirve para todos. El orden de decisión es: si el negocio tolera interrupciones, si necesita varios modelos y factura, y si el equipo tiene a alguien que mantenga el proxy a largo plazo.

2. Conexión directa oficial: primero una tarea asíncrona

La interfaz de generación de video de Volcano Ark suele tener dos pasos, crear la tarea y consultarla, con una Base URL del tipo https://ark.cn-beijing.volces.com/api/v3. Las regiones disponibles, los ID de modelo y los campos concretos se confirman en la consola y en la documentación.

  1. Habilitar el modelo de generación de video en la consola de Volcano Ark y revisar los requisitos de cuenta y cumplimiento.
  2. Crear una clave de API independiente, llamada seedance-test, sin mezclarla con la clave de producción.
  3. Copiar el ID de modelo desde la consola; no reconstruyas de memoria el sufijo de versión.
  4. Enviar una tarea de prueba con la duración y la resolución más bajas.
  5. Registrar el ID de tarea devuelto y consultar el estado hasta que finalice.
export ARK_API_KEY="tu-clave"
export BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

curl -X POST "$BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ID del modelo copiado de la consola",
    "content": [
      {"type": "text", "text": "Calle de una ciudad después de la lluvia, la cámara avanza despacio, estilo cinematográfico"}
    ]
  }'

Si la petición agota el tiempo de espera pero la tarea aparece en la consola, significa que se creó. No la reenvíes de inmediato: podrías generar dos videos y pagar dos veces. Consulta primero por el número de pedido y decide después si reintentar.

3. Proxy propio: resuelve la salida, no la cola

La práctica habitual es montar un proxy inverso en un servidor con acceso estable a la interfaz oficial. Alivia los problemas de salida local, pero añade trabajo:

  • El servidor de proxy es un punto único de fallo; si cae, todas las tareas fallan a la vez.
  • Hay que gestionar TLS, autenticación, control de acceso y registros para evitar abusos.
  • Las peticiones de video son grandes y lentas; el ancho de banda y las conexiones del proxy se convierten fácilmente en cuello de botella.
  • Una capa adicional de reenvío no acelera la cola del proveedor; en horas punta, la espera sigue existiendo.
  • La responsabilidad de red y cumplimiento sigue recayendo en el equipo.

Sin una persona dedicada, el proxy suele pasar de solución temporal a deuda permanente. Puede servir de transición, pero no conviene que sea la única entrada.

4. Pasarela de IA: entrada, facturación y conmutación en un solo punto

El valor de una pasarela de IA local es concentrar la gestión de claves, la recarga, el detalle de consumo, la factura y el cambio de modelo. El código del negocio apunta a una sola entrada y, al cambiar de modelo, se modifica la configuración en lugar del código. Para equipos que usan a la vez modelos de texto, imagen y video, esto importa más que ahorrar unos milisegundos de latencia.

Al elegir una pasarela hay que confirmar: si tiene habilitada la capacidad de video de Seedance, qué modelos y parámetros admite, cómo traduce los estados de tarea, cómo factura los fallos y las cancelaciones, cuánto tiempo conserva la URL del resultado y cómo notifica las incidencias. Puedes crear una clave de prueba en ZSQH AI Gateway, ejecutar primero la tarea mínima y revisar después precios de modelos y el criterio de facturación.

La pasarela no cambia la capacidad del proveedor. Unifica la entrada y facilita el tratamiento de fallos, pero no permite prometer que no habrá cola en horas punta.

5. Sondeo y entrega del resultado: la verdadera dificultad de la API de video

Según la documentación de Volcano Ark, los estados de tarea suelen incluir queued, running, succeeded, failed, cancelled y expired. La consulta de tareas normalmente cubre los últimos 7 días y el video_url de un resultado correcto se limpia a las 24 horas aproximadamente. Estas dos condiciones determinan el diseño del sistema.

  • Separa el envío del sondeo; no dejes que una petición HTTP espere varios minutos de forma síncrona.
  • Empieza el sondeo a los 5 segundos y retrocede hasta 15 o 30 segundos, con un tiempo máximo total.
  • La respuesta correcta puede incluir un objeto error; en caso de fallo, registra error.code y error.message.
  • Al recibir video_url, descarga de inmediato a tu almacenamiento de objetos; no entregues la URL temporal al negocio como enlace permanente.
  • Tras la descarga, verifica el tamaño y la reproducibilidad, y genera tu propia URL firmada o dirección CDN.
  • La cancelación suele afectar solo a tareas en cola; las reglas concretas figuran en la documentación.

Conviene tratar la entrega como un proceso independiente: descarga, transcodificación, revisión y registro, cada uno con reintentos propios. Así, cuando caduque la URL del proveedor, los datos del negocio no se pierden con ella.

6. Pago, facturas y contrato

  • Los equipos que necesitan pago corporativo deben confirmar de antemano el método de recarga, el plazo de abono, el tipo de factura y la periodicidad.
  • Confirmar cómo se facturan las tareas fallidas, las que agotan el tiempo y las canceladas, y si hay reembolso o devolución de cuota.
  • Pedir el detalle de consumo por tarea o por clave, con capacidad de cruzar ID de tarea, modelo, duración y estado.
  • Leer las condiciones de datos y comprobar si las imágenes, los prompts y los resultados se conservan o se usan para mejorar el servicio.
  • La clave de producción no entra en el frontend ni en repositorios públicos; se separa por entorno y se le fija un límite de cuota.

7. Conmutación ante fallos: reintentar bien

Reintentar una tarea de video cuesta más que en texto, porque cada intento es una generación completa. Recomendaciones:

  1. Generar un identificador único por pedido y comprobar si ya existe una tarea antes de enviar.
  2. Reintentar con retroceso solo ante 429, 5xx y tiempos de conexión agotados; no reintentar errores de parámetros ni rechazos de moderación.
  3. Aplicar un cortacircuitos al alcanzar un umbral de fallos consecutivos para evitar una tormenta de reintentos.
  4. Preparar una entrada o un modelo alternativo, pero revisar el estado de las tareas tras el cambio para que las dos rutas no generen una copia cada una.
  5. Conciliar a diario el número de tareas, el de éxitos y el de cargos facturados, y detener el volumen si aparece una anomalía.

8. Lista de validación antes de salir a producción

  1. La tarea mínima se envía correctamente y el ID de tarea se devuelve de forma estable.
  2. Los seis estados de tarea se identifican y se guardan correctamente.
  3. Están configurados el tiempo máximo de sondeo, el número máximo de reintentos y el umbral del cortacircuitos.
  4. El resultado correcto se transfiere dentro de las 24 horas y existe una tarea de compensación si falla la descarga.
  5. Se han confirmado las reglas de facturación de tareas fallidas, canceladas y agotadas por tiempo.
  6. Se ha probado la limitación de peticiones con envíos concurrentes y el 429 tiene retroceso.
  7. La factura y el detalle de tareas se pueden cruzar línea a línea.
  8. Se registran durante 7 días consecutivos la tasa de éxito, el tiempo P95 y el costo por pieza antes de decidir si se amplía el volumen.

Preguntas frecuentes

¿Se puede llamar a la API de Seedance directamente desde China?

Depende de la cuenta, la región, la red y las condiciones de cumplimiento. La conexión directa oficial es una ruta posible, pero en producción hay que prever tiempos agotados, reintentos y una entrada alternativa; guíate por la documentación oficial y la normativa local.

¿Qué es más estable, la conexión directa o una pasarela?

No hay una respuesta única. La conexión directa elimina una capa de reenvío, pero deja todo el tratamiento de fallos en el equipo; la pasarela unifica entrada y facturación, pero añade una dependencia. Prueba el mismo lote de tareas en ambas y compara tasa de éxito y tiempo P95.

¿Cuánto tarda en generarse un video?

Influyen la cola, la duración, la resolución y la carga del proveedor; lo habitual va de decenas de segundos a varios minutos. En producción conviene fijar un tiempo máximo total y mostrar el estado de la tarea al área de negocio.

¿Cuánto tiempo se conserva el resultado?

Según la documentación de Volcano Ark, la consulta de tareas suele cubrir los últimos 7 días y la URL del video se limpia a las 24 horas aproximadamente. Hay que transferirlo de inmediato al almacenamiento propio y no depender de un enlace temporal.

¿Se cobran las tareas fallidas o canceladas?

Las reglas varían según la plataforma y el motivo. Antes de integrar, confirma cómo se facturan el rechazo de moderación, el fallo del sistema, el tiempo agotado y la cancelación voluntaria, y guíate por el detalle de la factura.

Siguiente paso

Crea primero una clave de prueba en ZSQH AI Gateway, ejecuta una tarea de Seedance con la configuración mínima y confirma la transición de estados, la transferencia del resultado y el criterio de facturación antes de decidir la ruta de producción. Los modelos y los precios figuran en precios de modelos.

Lecturas relacionadas: