Seedance es un modelo de generación de vídeo de ByteDance, habitual en creatividades publicitarias, vídeos cortos de comercio electrónico y previsualización de guiones gráficos. Su API funciona de forma muy distinta a la de los modelos de texto: una petición no devuelve el vídeo directamente, sino que primero crea una tarea, luego hay que consultar su estado y, por último, descargar el resultado. Quien integra la API con la lógica de Chat Completions suele atascarse en el primer paso.

Este artículo sigue el orden de implementación en ingeniería y explica autenticación, envío, sondeo, parámetros, pruebas, costes y cumplimiento normativo. Las direcciones de interfaz, los nombres de modelo y la facturación cambian con rapidez; confirma siempre la documentación oficial y la documentación del sitio.

Nota: Seedance, Doubao y Volcano Engine son marcas de sus respectivos titulares; este artículo solo ofrece una explicación técnica. Las rutas de interfaz y los nombres de modelo de los ejemplos son solo demostrativos; verifícalos en la documentación oficial o del sitio antes de llamar de verdad. Los precios figuran en la página de precios del sitio.

1. Para qué sirve la API de Seedance

  • Vídeos de presentación de productos y vídeos de imagen principal para comercio electrónico;
  • Anuncios en feed y borradores de creatividades para vídeo corto;
  • Guiones gráficos, piezas conceptuales y pruebas de estilo;
  • Contenido vertical para redes sociales;
  • Fragmentos de previsualización para juegos y animación.

No es adecuada para: material informativo que exige una precisión factual estricta, retratos de personas reales sin autorización, o contenido legal y médico que debe cumplir normas de marca precisas. El control de la generación de vídeo sigue siendo inferior al de una grabación real; en encargos comerciales importantes conviene revisar el resultado manualmente antes de publicarlo.

2. Flujo básico de una tarea asíncrona

leer configuración → autenticar → enviar tarea de generación → obtener task_id
        → sondear estado (en cola/en ejecución/éxito/fallo)
        → éxito: descargar el vídeo u obtener una URL temporal
        → fallo: leer el código de error y decidir si reintentar o abandonar

Frente a las interfaces de texto, las tareas de vídeo tienen tres costes adicionales: tiempo en cola, reintentos por fallo y almacenamiento del resultado. La ingeniería debe contemplar estos tres factores; de lo contrario, al pasar a producción aparecerán problemas como "la petición expira pero la tarea sigue en ejecución" o "los envíos duplicados provocan cobros duplicados".

3. Autenticación y preparación de la integración

  1. Confirma el canal: revisa primero si la documentación del sitio ya ofrece la capacidad de vídeo de Seedance y qué modelos, duraciones y resoluciones admite.
  2. Crea una clave: genera una clave independiente en la consola y llámala seedance-test o seedance-prod.
  3. Confirma el nombre del modelo: cópialo de la página de precios o de la documentación; no escribas el sufijo de versión de memoria.
  4. Confirma el método de notificación: algunos canales admiten webhook y otros solo sondeo.
  5. Prepara los materiales: convierte la imagen inicial y las imágenes de referencia en URL de acceso público, o súbelas según indique la documentación.
  6. Fija un presupuesto: pon un límite de cuota a la clave de pruebas para no generar una factura enorme mientras depuras.

La autenticación suele ser Authorization: Bearer <API_KEY>, pero algunas plataformas usan firma AK/SK o tokens temporales. Guíate por la documentación real y no apliques el método de autenticación de una plataforma a otra.

4. Ejemplo de envío de tarea

A continuación se muestra la forma habitual de una petición basada en tareas; las rutas y los campos son solo ilustrativos:

export SEEDANCE_API_KEY="tu-clave"
export BASE_URL="https://tu-pasarela-o-url-oficial"

curl -X POST "$BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-video",
    "content": [
      {"type": "text", "text": "Calle de Shanghái tras la lluvia, la cámara avanza lentamente, estilo cinematográfico, 16:9"},
      {"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "watermark": false
  }'

Si el envío se realiza correctamente, la respuesta incluirá un ID de tarea. Guárdalo en la base de datos y vincúlalo al número de pedido del negocio; el sondeo, los reintentos y la conciliación posteriores dependerán de él.

5. Sondeo y descarga

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

Los estados habituales son en cola, en ejecución, éxito y fallo. Recomendaciones:

  • Empieza con un intervalo de sondeo de 5 segundos y aumenta gradualmente hasta 15–30 segundos;
  • Define un tiempo máximo total, por ejemplo 10 minutos; al superarlo, marca la tarea como fallida en lugar de esperar indefinidamente;
  • La URL del vídeo de una respuesta correcta suele tener caducidad; guárdala cuanto antes en tu propio almacenamiento de objetos;
  • Registra el código de error y los parámetros de las tareas fallidas para poder analizarlas después.

6. Parámetros clave

Parámetro Función Consejo práctico
prompt / text Describe la escena, la acción, el plano y el estilo Escribe primero el sujeto y después el plano y la luz
Imagen inicial Controla el fotograma de inicio Usa una imagen nítida y sin disputas de derechos
duration Duración del vídeo Prueba primero con la opción más corta
resolution Resolución Usa la opción baja para pruebas y súbela para la versión final
ratio Relación de aspecto Para publicación vertical, elige 9:16
seed Semilla aleatoria Fija la semilla para comparar parámetros
watermark Marca de agua Confirma las reglas de la plataforma antes del uso comercial

Los nombres de los parámetros pueden variar entre plataformas: algunas usan image, otras image_url, y otras escriben la duración como cadena de texto. Guíate por la documentación y no copies literalmente el cuerpo de la petición de otro proveedor.

7. Lista de comprobación antes de producción

  1. ¿Pasa la autenticación y se captura correctamente el error 401?
  2. ¿Funciona una tarea con la duración mínima y la resolución más baja?
  3. ¿Se devuelve siempre un ID de tarea y se puede consultar por ese ID?
  4. ¿Están definidos el tiempo máximo de sondeo y el número máximo de reintentos?
  5. ¿Se puede leer el motivo del fallo y distinguir un rechazo de moderación de un error del sistema?
  6. ¿Se han validado la caducidad de la URL del resultado y la lógica de almacenamiento?
  7. ¿La facturación coincide con lo previsto y se cobran las tareas fallidas?
  8. ¿Se activa la limitación de peticiones al enviar en paralelo?

8. Cómo estimar el coste

El coste del vídeo suele ser muy superior al del texto; al estimarlo, no mires solo el precio unitario:

coste por pieza =
  precio unitario × duración × factor de resolución
+ coste de reintentos fallidos
+ almacenamiento y ancho de banda
+ tiempo de revisión manual

La facturación puede basarse en segundos generados, en tramos de resolución o en una conversión a tokens de vídeo. El precio unitario concreto figura en la página de precios de modelos del sitio. Conviene ejecutar primero un lote pequeño de 20–50 piezas, medir la tasa de éxito, el tiempo medio y el coste por pieza, y solo después decidir si se escala.

9. Moderación de contenido y riesgo de derechos

  • Derecho de imagen: subir fotos de personas reales o generar personas identificables requiere autorización.
  • Derechos de autor: las imágenes de referencia, los estilos, la música y las marcas pueden implicar derechos de terceros.
  • Política de contenido: la violencia, la pornografía, los contenidos ilegales y la desinformación se rechazan o se retiran.
  • Publicidad engañosa: las creatividades no deben generar efectos que no correspondan al producto real.
  • Seguridad de datos: las imágenes y los vídeos subidos pueden contener información de clientes; aplica anonimización y define plazos de conservación.
  • Alcance comercial: que el contenido generado pueda usarse comercialmente depende de los términos de la plataforma y de la autorización de tus materiales.

Recomendamos establecer tres controles: revisar los materiales antes de enviarlos, hacer un muestreo manual después de generar y obtener la confirmación de marca o legal antes de publicar. Un rechazo de moderación no es un fallo técnico; no intentes eludirlo cambiando palabras clave una y otra vez.

10. Recomendaciones de estabilidad

  • Guarda las tareas en la base de datos con hora de envío, estado, duración y coste;
  • Separa el envío del sondeo para no bloquear una petición varios minutos;
  • Aplica retroceso exponencial ante errores 429 y 5xx, pero no reintentes a ciegas ante errores 4xx de parámetros;
  • Prepara un canal o un modelo alternativo; los canales de vídeo pueden acumular cola en horas punta;
  • Supervisa la tasa de éxito, el tiempo P95 y el coste por pieza, y concilia a diario.

Preguntas frecuentes

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

Normalmente no. La generación de vídeo suele ser una tarea asíncrona: hay que enviarla, sondear o esperar una notificación y después descargar el resultado.

¿Se puede llamar desde China directamente?

Depende del canal, de la cuenta y de las condiciones de cumplimiento. Antes de usarla, confirma los términos del servicio, la política de contenido y la normativa local.

¿Cuánto tarda en generarse un vídeo?

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 hay que definir tiempos máximos y reintentos.

¿Se cobra una tarea fallida?

Las reglas varían según la plataforma. Antes de integrar, confirma cómo se facturan los fallos, los rechazos de moderación y las cancelaciones por tiempo agotado.

¿Puedo usar mi propia imagen como fotograma inicial?

La mayoría de los modelos de vídeo lo permiten, pero la imagen debe ser accesible para la plataforma y debes tener la autorización correspondiente. Los campos concretos figuran en la documentación.

Siguiente paso

Confirma primero si el sitio ya ofrece el canal de Seedance y ejecuta una tarea con la configuración mínima. Si necesitas un punto de entrada unificado, crea una clave en la pasarela de IA de ZSQH y revisa los modelos disponibles en la página de precios de modelos.

Lecturas relacionadas: