Al integrar Seedance en un negocio, muchos equipos eligen primero un punto de entrada de relay o proxy: basta cambiar la URL base y la clave, y parece más cómodo que conectar directamente. Pero la generación de vídeo es una tarea asíncrona, y una cadena de relay añade pasos que una interfaz de texto no tiene: persistencia de tareas, mapeo de estados, almacenamiento del resultado y callbacks. Si cualquiera de esos pasos queda débil, el síntoma será siempre el mismo: "la tarea se envió correctamente, pero el vídeo no llega".

Este artículo parte de la cadena real de un servicio de relay y explica la fiabilidad de las tareas, la retención de resultados, la transparencia del cobro, los riesgos de las claves y cómo validar una migración desde la conexión directa.

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

1. Distingue primero cuatro tipos de "relay"

Tipo Qué hace Riesgo principal Escenario adecuado
Proxy inverso Reenvía las peticiones a la interfaz oficial Punto único, ancho de banda de salida, configuración de autenticación Equipos con capacidad de operación
Pasarela agregadora Punto de entrada único que agrupa varios modelos Mapeo de estados, diferencias de parámetros Negocios con varios modelos
Distribución o recarga por terceros Revende cuota del proveedor o paga por ti Estabilidad del proveedor, condiciones del servicio Pruebas pequeñas, necesidades temporales
Pasarela propia Se despliega y mantiene la capa de reenvío Toda la responsabilidad recae en uno mismo Equipos técnicos que quieren controlar sus datos

Lo que compras, ¿es "servicio técnico" o "cuota de modelo"? Esa diferencia determina quién responde cuando algo falla. Pregunta por contrato, factura y cláusulas de tratamiento de datos en función de esa distinción.

2. Qué pasos adicionales añade una tarea asíncrona en un relay

tu servicio
  → entrada del relay (autenticación, límite de tasa, cobro)
  → el proveedor crea la tarea y devuelve un task_id
  → el relay guarda la relación entre task_id y número de pedido
  → el relay sondea al proveedor o recibe callbacks
  → mapea el estado y lo expone en tu sondeo o webhook
  → descargas el resultado y lo guardas

Cada salto añade un lugar donde el estado puede perderse:

  • El relay se reinicia o cambia de instancia y el mapeo de tareas en memoria desaparece.
  • El proveedor agota el tiempo pero la tarea ya se creó; el relay devuelve un fallo y el cliente reintenta, generando dos piezas.
  • El estado del proveedor es expired, pero el relay solo mapea éxito y fallo, y el negocio espera indefinidamente.
  • El relay guarda la URL del resultado en su propia dirección, pero la caché caduca y no vuelve al origen.
  • El reintento del webhook no tiene clave de idempotencia y el negocio inserta el registro dos veces.

Al evaluar un relay, no preguntes solo "¿admite Seedance?". Pregunta cómo persiste el ID de tarea, cómo mapea los estados y cómo compensa los fallos.

3. Estados de tarea y retención de resultados

Según la documentación de Volcano Ark, los estados de una tarea de Seedance suelen incluir queued, running, succeeded, failed, cancelled y expired; la consulta de tareas suele cubrir solo los últimos 7 días, y la URL del vídeo en un resultado correcto se elimina normalmente a las 24 horas.

Un servicio de relay debe añadir una capa sobre esas dos limitaciones:

  • ¿Guarda registros de tareas? ¿Durante cuánto tiempo? ¿Se pueden consultar después de 7 días?
  • ¿Descarga los vídeos por ti? Si los almacena, ¿cuántos días los conserva y cobra un extra?
  • ¿Devuelve la URL temporal del proveedor o una dirección propia de larga duración?
  • ¿Cómo se mapean la cancelación, el agotamiento de tiempo y el rechazo de moderación?

Si el relay solo hace "paso directo", el cliente sigue asumiendo la responsabilidad de guardar el resultado en 24 horas; si hace "gestión alojada", hay que confirmar la ubicación del almacenamiento, los permisos de acceso y el mecanismo de borrado. Ambas opciones son válidas; la ambigüedad no lo es.

4. Cómo verificar la transparencia del cobro

El cobro de tareas de vídeo genera más disputas que el de texto, porque los fallos, los reintentos y las cancelaciones ocurren en la fase asíncrona. Antes de contratar, confirma:

  • Si la unidad de cobro es por duración, por resolución, por tarea o por conversión a tokens.
  • Si los fallos, los tiempos agotados, las cancelaciones y los rechazos de moderación se cobran en cada caso.
  • Si los envíos duplicados y los reintentos se cobran dos veces y si existe deduplicación idempotente.
  • Si hay consumo mínimo, umbral de prepago, reglas de reembolso y tipos de factura.
  • Si el detalle de uso incluye ID de tarea, modelo, duración, resolución, estado e importe descontado.

No te fijes solo en los descuentos de la página promocional. Ejecuta un lote pequeño de 20–50 tareas durante una semana y cuadra una por una las tareas correctas, las fallidas y la factura; es más fiable que cualquier explicación verbal. Los precios concretos se rigen por la página de precios de modelos del sitio.

5. Claves y riesgos del proveedor

Un relay implica que el contenido de las peticiones pasa por un tercero. Como mínimo, confirma:

  1. Si los prompts, el primer fotograma y los vídeos generados se guardan en disco y durante cuánto tiempo.
  2. Si los datos se usan para entrenamiento o mejora del servicio.
  3. Si la clave permite limitar cuota, IP y fecha de caducidad.
  4. Cómo se notifica una filtración o un abuso y cómo se bloquea.
  5. Si el proveedor usa un solo canal o varios, y cómo se migra si un modelo se retira.
  6. Si las condiciones del servicio permiten reventa o proxy y cuál es el límite de responsabilidad.

Las claves de producción no deben incluirse en el frontend ni en repositorios públicos. Para material muy sensible, prioriza proveedores que permitan no persistir datos o firmar un acuerdo de tratamiento; si no puedes confirmarlo, no subas material de clientes sin anonimizar.

6. Pasos para migrar de la conexión directa al relay

  1. Inventaria las llamadas actuales: ID de modelo, parámetros, concurrencia, duración media y tipos de fallo.
  2. Confirma las rutas de la interfaz del relay, el método de autenticación y las diferencias de campos, y elabora una tabla de mapeo.
  3. Ejecuta en el entorno de pruebas las cuatro rutas: crear, consultar, cancelar y descargar.
  4. Haz una ejecución en espejo con el mismo lote de tareas: una por conexión directa y otra por relay, solo para comparar, sin cambiar el tráfico.
  5. Compara tasa de éxito, tiempo P95, porcentaje de resultados descargables y coste por pieza.
  6. Cambia el tráfico por fases del 5%–20%, manteniendo un interruptor de reversión a la conexión directa.
  7. Observa durante 3–7 días y confirma que la factura y el detalle de tareas cuadran.
  8. Tras el cambio completo, mantén un periodo con dos canales de respaldo y simplifica la arquitectura cuando la estabilidad esté confirmada.

Durante la migración no borres la clave de conexión directa ni escribas ambas tareas con el mismo número de pedido; de lo contrario, no podrás distinguirlas al conciliar.

7. Cómo validar un servicio de relay

# 1. Envía una tarea mínima y registra task_id y la hora de envío
curl -X POST "$RELAY_BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ID de modelo según la documentación del relay","content":[{"type":"text","text":"un gato bostezando junto a la ventana"}]}'

# 2. Consulta cada 10 segundos y registra toda la transición de estados
curl "$RELAY_BASE_URL/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $RELAY_API_KEY"

Durante la prueba, provoca anomalías a propósito: cancela justo después del envío, usa un ID de modelo incorrecto, envía en paralelo y corta la descarga a mitad. Observa los estados que devuelve el relay, los mensajes de error y si la factura coincide. Vuelve a acceder a la dirección del resultado 24 horas después para comprobar si sigue descargable, y consulta la tarea 7 días después para ver si el registro permanece.

8. Monitorización y reversión tras la migración

  • Cuenta las tareas por estado y vigila sobre todo la proporción de failed, cancelled y expired.
  • Registra el tiempo total desde el envío hasta el éxito, separando cola y generación.
  • Vigila la tasa de descarga correcta de resultados y mantén una cola de compensación para tareas fallidas.
  • Cuenta los errores 401, 404, 429 y 5xx, distinguiendo problemas de clave, de modelo y de límite de tasa.
  • Calcula el "coste por vídeo correcto", no solo el precio unitario de la petición.
  • Define umbrales de reversión; por ejemplo, si la tasa de éxito cae claramente por debajo de la línea base durante dos horas seguidas, vuelve a la conexión directa.

Preguntas frecuentes

¿La capacidad del modelo es la misma en relay y en conexión directa?

Depende de si el relay reenvía el mismo modelo y los mismos parámetros del proveedor. Puede haber diferencias en ID de modelo, duración, resolución y audio; antes de integrar, compara las salidas y los parámetros admitidos con el mismo prompt.

¿El relay guarda mis vídeos?

Cada servicio es distinto. Pregunta si persiste datos, durante cuánto tiempo, dónde, quién puede acceder y cómo se borran. Si hay material de clientes, prioriza proveedores con condiciones claras.

¿Qué hago si una tarea se pierde en el relay?

Consulta primero el registro local por número de pedido y después los logs del relay y la tarea en el proveedor. Si no se puede recuperar, solo queda reenviarla; por eso, antes de migrar, confirma si el relay persiste el mapeo de tareas y si permite consultar por número de pedido.

¿Por qué la factura no coincide con el número de tareas?

Las causas habituales son envíos duplicados, reintentos de fallos, reglas de cancelación distintas, consumo mínimo o aciertos de caché. Solicita el detalle de cargos por ID de tarea y revísalo línea por línea, no solo el total.

¿Hay que cambiar código para migrar?

Si el relay es compatible con OpenAI o con la interfaz oficial de tareas, normalmente basta con cambiar la URL base, la clave y algunos campos; si el mapeo de estados o el formato de callback son distintos, habrá que ajustar el sondeo y la persistencia. Una ejecución en espejo permite detectar la mayor parte de las diferencias por adelantado.

Siguiente paso

Crea primero una clave de prueba en la pasarela de IA de ZSQH, valida con una tarea mínima las cuatro rutas de crear, sondear, descargar y facturar, y migra después por fases. Los modelos y los precios se rigen por precios de modelos.

Lecturas relacionadas: