Guía de integración de la API Seedance 1.5 Pro vía EvoLink: tareas asíncronas, rellamadas y modos

Lo que aprenderás

• Implementar Seedance 1.5 Pro vía la API de tareas asíncronas de EvoLink (crear → estado → resultados).
• Usar callback_url de forma segura (solo HTTPS, semántica de reintento y manejo de fallos).
• Utilizar un único punto de conexión para texto a vídeo, imagen a vídeo y guía de primer y último fotograma.
• Prevenir el doble procesamiento con claves de idempotencia y presupuestos de reintento.
• Realojar los resultados antes de que expiren los enlaces (ventana de retención de 24 horas).
• Modelar el "coste por resultado exitoso" sin depender de instantáneas de precios frágiles.
• Comparar los pros y contras de la integración frente a Veo 3.1 y Kling O1 (basado en arquitectura, no en precio).

Lista de verificación de inicio rápido (copia y pega en tu ticket)

• Implementar POST /v1/videos/generations para crear tareas
• Implementar sondeo (polling) GET /v1/tasks/{task_id}
• Implementar el punto de conexión callback_url (respuesta 2xx rápida + procesamiento asíncrono)
• Añadir clave de idempotencia por intención de usuario (clic en "Generar")
• Realojar los activos de vídeo en un plazo de 24 horas
• Instrumentar: latencia p50/p95, tasa de fallos de política, tasa de reintentos, intentos por éxito

Contrato de la API de EvoLink (lo que realmente implementas)

• Crea una tarea → recibe un task_id
• Sondea el estado vía GET /v1/tasks/{task_id} o recibe una rellamada en callback_url
• Al completarse, obtén las URL de los results y descárgalas inmediatamente (los enlaces expiran)

Resumen de puntos de conexión

• POST https://api.evolink.ai/v1/videos/generations

• GET https://api.evolink.ai/v1/tasks/{task_id}

• Los enlaces de salida son válidos durante 24 horas. Recalójalo prontamente.

Un punto de conexión, tres modos (detección de modo vía image_urls)

• 0 imágenes → texto a vídeo (Text-to-Video)
• 1 imagen → imagen a vídeo (Image-to-Video)
• 2 imágenes → primer y último fotograma (guía mediante primer y último fotograma)

• Máximo 2 imágenes por solicitud
• Cada imagen ≤ 10MB
• Formatos: jpg/jpeg/png/webp
• Las URL deben ser accesibles directamente por el servidor

Campos de solicitud clave en producción

Estos son los parámetros que realmente operacionalizarás:

• model: usa "seedance-1.5-pro"
• prompt (obligatorio): hasta 2000 tokens
• duration: por defecto 5s; soportado de 4 a 12s

  Nota operativa: la facturación escala con la duración; trata la duración como una palanca presupuestaria de primer nivel.

• quality: 480p o 720p (por defecto 720p)
• aspect_ratio: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, adaptive (por defecto 16:9)
• generate_audio: booleano (por defecto true)

  Consejo: pon el diálogo entre comillas dobles para mejorar la dicción de las líneas.

• callback_url: URL de rellamada (solo HTTPS) para tareas completadas/fallidas/canceladas (recomendado)

Parámetros predeterminados por escenario (decisiones rápidas)

Ciclo de vida de la tarea: diseña primero tu máquina de estados

Una integración fiable comienza con una máquina de estados interna predecible:

created → queued/processing → succeeded → (descargar → realojar → entregado)
                     └──────→ failed (política | transitorio | interno)
                     └──────→ cancelled

Ejemplos mínimos de funcionamiento (EvoLink)

1) Crear una tarea (cURL) — apto para copiar/pegar

Este ejemplo evita problemas de escape en la terminal al usar un prompt sencillo sin comillas simples.

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header 'Authorization: Bearer <tu_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-1.5-pro",
    "prompt": "A detective in the rain says: \"Do not move.\" Neon reflections on the street. Subtle footsteps and radio static.",
    "duration": 8,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "callback_url": "https://tu-dominio.com/webhooks/evolink-task"
  }'

La API responde inmediatamente con un objeto de tarea que contiene al menos:

• id (id de la tarea)
• status
• campos de usage (ej., billing_rule, credits_reserved)

2) Sondear estado de la tarea (cURL)

curl --request GET \
  --url https://api.evolink.ai/v1/tasks/<task_id> \
  --header 'Authorization: Bearer <tu_token>'

Al completarse, la tarea incluye:

• Array de results con las URL de salida
• status y progress

callback_url: reglas de fiabilidad (no las omitas)

• Solo HTTPS
• Bloqueo de IP de red interna/privada
• Tiempo de espera (timeout): 10 segundos
• Máximo 3 reintentos con periodos de espera de 1 / 2 / 4 segundos
• El cuerpo de la rellamada coincide con el formato de respuesta de la consulta de tarea

Lista de verificación de rellamadas en producción (copia/pega)

• Responder con 2xx en un plazo de 200ms–500ms (encola el trabajo; no hagas el procesamiento pesado en línea)
• Validar que el task_id existe y pertenece a tu cliente/usuario
• Volver a consultar inmediatamente GET /v1/tasks/{task_id} antes de marcar el estado final
• Deduplicar rellamadas (almacena task_id + estado final; ignora repeticiones)
• Registrar la carga útil (payload) de la rellamada para depuración (oculta secretos)
• Alertar cuando la tasa de fallos de rellamada aumente (normalmente indica problemas en tu punto de conexión)

Idempotencia: prevenir el doble procesamiento (y el doble cargo)

Incluso si tu proveedor funciona correctamente, tu sistema puede crear duplicados debido a:

• Los usuarios hacen doble clic en "Generar"
• Las redes móviles reintentan la solicitud
• Los tiempos de espera de las pasarelas

• El cliente genera una idempotency_key por cada intención de usuario (un clic = una clave)
• El servidor almacena (user_id, idempotency_key) → task_id con un TTL
• En caso de repeticiones, devuelve el mismo task_id en lugar de crear una nueva tarea

No asumas que la idempotencia se "maneja automáticamente" a menos que la API lo documente explícitamente. Impleméntala en el nivel de tu aplicación.

Entrega de activos: la trampa de las 24 horas

Dado que los enlaces de resultados expiran en 24 horas, tu pipeline debería:

• Descargar el resultado inmediatamente cuando el status=completed
• Realojarlo en tu propio almacenamiento de objetos (S3/GCS/R2)
• Servirlo vía CDN
• Persistir metadatos: task_id, hash del prompt, id de usuario, duración, calidad, bandera de audio, categoría de moderación

Evítalo realojando automáticamente al completarse la tarea.

Modelado de costes sin instantáneas de precios

Incluso si no publicas cifras de precios, necesitas un modelo económico de unidad duradero.

1) Conoce qué factura la plataforma

Operativamente, tu gasto se rige por:

• duration (clips más largos → más costosos)
• generate_audio (el audio añade coste)
• Iteración (los usuarios rara vez aciertan a la primera)

2) Presupuesta "coste por resultado exitoso", no "coste por intento"

Rastrea:

• attempts_per_success (por escenario)
• retry_rate
• policy_failure_rate
• p95_latency

Así, tu unidad real sería:

resultados exitosos por sesión × promedio de intentos necesarios

3) Borrador → Aprobar → Final (la forma más fiable de reducir gastos)

Cuando veas una alta iteración:

• Genera borradores usando configuraciones más económicas (ej. menor calidad/duración) o un modelo más barato
• Finaliza con Seedance 1.5 Pro (con audio) solo después de que el usuario lo apruebe

Errores comunes en producción y soluciones

1) El problema del asincronismo (timeouts + trabajos zombies)

• Establece un "TTL del trabajo" y un estado de UI de "procesando"
• Rastrea el tiempo de finalización p95; degrada el servicio con elegancia si hay picos

2) Los resultados de moderación pueden llegar tarde

Diseña estados de UI/backend para "fallo después del procesamiento".

• Separa: política vs transitorio vs interno
• Nunca reintentes automáticamente fallos de política de contenido
• Proporciona orientación para reescribir el prompt (especialmente en contenido sensible)

Comparación: Seedance 1.5 Pro vs Veo 3.1 vs Kling O1

Los números envejecen rápido. Compara lo que perdura: la estructura de integración y el ajuste al flujo de trabajo.

Tabla A — Integración y estructura de costes

Tabla B — Matriz de decisión en producción

Lista de verificación de decisión (SÍ/NO rápido)

• Necesitas audio nativo y puedes estructurar diálogos entre comillas.
• Necesitas texto a vídeo + imagen a vídeo + primer/último fotograma bajo un mismo contrato.
• Puedes automatizar el realojamiento de activos en un plazo de 24 horas.

• Prefieres presupuestar por duración y un flujo de trabajo estable en el ecosistema cloud de Google.

• La edición/estilización es fundamental y has confirmado un acceso estable.

FAQ

P: ¿Cómo cambio entre texto a vídeo e imagen a vídeo en EvoLink?

P: ¿Rellamada (webhook) o sondeo (polling)? ¿Cuál es más seguro?

P: ¿Por qué debo realojar el resultado?

Los enlaces expiran en 24 horas. Descarga y almacena los resultados rápidamente.

P: ¿Cómo evito tareas duplicadas cuando los usuarios reintentan?

Empieza a construir con Seedance 1.5 Pro hoy mismo

Ya conoces el contrato. Entiendes las ventajas y desventajas. Ahora conviértelo en una función de producción.

• Una sola clave de API para Seedance 1.5 Pro, Veo 3.1, Kling y otros modelos.
• Tareas asíncronas + rellamadas con semántica de reintento definida.
• Facturación basada en el uso con créditos transparentes y sin mínimos.

La mayoría de los equipos se integran en menos de una hora.