Blog

Tutorial

Tutorial de la API seedance-2.5-flash de imagen a video: curl y Python Requests

Recorrido práctico de integración para desarrolladores: estructura de la solicitud, entradas de primer y último fotograma, sondeo asíncrono y solución de errores

Nov 19, 2026
Imagen de portada: sobre un fondo marrón oscuro, tiras de tela de color beige y cobre de anchos variables se entrelazan formando un patrón geométrico plano de tejido de cestería.
En esta página

Qué hace realmente una llamada de imagen a video

Antes de escribir la primera línea de código, ayuda entender qué hace la API en el otro extremo. Una llamada a seedance-2.5-flash/image-to-video no es una solicitud síncrona que se bloquea hasta que se devuelve el archivo de video. Es un flujo de trabajo asíncrono en dos fases: primero envías una tarea y luego sondeas su resultado.

Fase de envío

Envías una solicitud POST con la imagen de entrada y los ajustes de generación. La API valida el cuerpo de la solicitud, pone la tarea en cola y devuelve inmediatamente una respuesta que contiene un identificador de tarea y un estado inicial. Este proceso es rápido —normalmente instantáneo— porque en ese momento todavía no se ha renderizado ningún píxel. Tu trabajo es capturar ese identificador y guardarlo de forma segura.

Fase de renderizado

La generación ocurre en segundo plano. Según la duración del clip y los ajustes, esto puede llevar una cantidad considerable de tiempo real. Durante ese periodo, no esperes que la URL del video final ya esté disponible. En su lugar, debes consultar el estado de la tarea.

Fase de resultado

La tarea final alcanza un estado terminal: éxito, con un artefacto de video descargable; o fallo, con un error que puedes investigar. Una vez alcanzado el estado terminal, debes dejar de sondear.

Por qué esto importa para tu código

Como el modelo es asíncrono, los errores de integración más comunes son de arquitectura, no de sintaxis: suponer que la primera respuesta ya contiene el video, esperar con un intervalo fijo en lugar de sondear el campo de estado, y no distinguir un estado processing transitorio de un fallo permanente. Todo en este tutorial gira en torno a un ciclo limpio de «enviar → sondear → salir», así que ten presentes estas tres fases mientras lees.

Requisitos previos y estructura de la solicitud

Qué necesitas antes de la primera llamada

  • Credenciales de API. Tu clave de API de HiAPI, que se envía con cada solicitud. Guárdala en una variable de entorno (HIAPI_API_KEY) en lugar de en el control de versiones; los ejemplos siguientes la leen así.
  • Identificador del modelo. En este tutorial la cadena es fija: seedance-2.5-flash/image-to-video. Trátala como una constante opaca; no la construyas concatenando partes.
  • Imagen de origen. Una URL pública o una referencia de imagen en línea admitida. El modelo necesita al menos una imagen de primer fotograma.
  • Cliente HTTP. curl para la prueba de humo y requests para cualquier cosa que planees conservar.

Campos lógicos del cuerpo de la solicitud

Independientemente del lenguaje, el cuerpo de una solicitud de imagen a video se compone de varios grupos conceptuales. Conocerlos por separado facilita la comprensión del JSON:

Modelo y entrada

  • El identificador del modelo.
  • Un objeto de entrada que contiene la imagen de primer fotograma y, opcionalmente, la imagen de último fotograma. El capítulo 4 explica cómo interactúan.

Ajustes de salida

  • Opciones relacionadas con la resolución y la duración.
  • El interruptor de audio nativo, que determina si el clip generado incluye una pista de audio acompañante. El capítulo 5 explica cuándo activarlo.

Qué se devuelve

Un envío exitoso devuelve un objeto de tarea. Los campos que realmente necesitas son el identificador de la tarea y el estado actual. Todo lo demás son metadatos que puedes registrar o ignorar. El primer día, no analices toda la respuesta en un modelo tipado: registra, inspecciona y luego acota.

Antes de continuar, haz una comprobación rápida de realidad: si tu cuerpo de solicitud contiene algún campo cuyo nombre no puedas explicar en una frase, elimínalo y empieza por lo mínimo. La página del modelo seedance-2.5-flash/image-to-video es la referencia de los nombres exactos de los campos aceptados.

Enviar una tarea con curl

Empieza con la solicitud mínima que pueda funcionar y luego añade un campo a la vez. Aquí tienes el envío mínimo con curl:

curl -X POST "$HIAPI_BASE_URL/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-flash/image-to-video",
    "input": {
      "first_frame_image": "https://your-bucket.example.com/frame-001.jpg"
    }
  }'

Comentario campo por campo

  • Authorization —— tu clave de API, como token bearer. Si esto falla, recibirás un error de autenticación antes de que se ejecute cualquier validación, así que revísalo primero al depurar.
  • Content-Type: application/json —— obligatorio; omitirlo produce errores posteriores confusos.
  • model —— el identificador fijo del modelo. Un error tipográfico aquí devuelve un 4xx, no una alternativa silenciosa.
  • input.first_frame_image —— la imagen de apertura del clip. Usa una URL realmente accesible desde tu red; las URL privadas o caducadas fallan al recuperarse, no al enviarse.

Leer la respuesta

La respuesta es un JSON que contiene el identificador de la tarea y el estado. Guarda el identificador de inmediato: es lo que sondearás en el capítulo 7. Una forma rápida de extraerlo en el shell:

# Después del curl anterior, canaliza a través de jq
# {"job_id": "...", "status": "queued"}

Añadir el último fotograma

Para controlar también el fotograma final, añade una segunda imagen dentro del mismo objeto input. El nombre del campo y los formatos aceptados se especifican en la documentación del modelo; no adivines variantes ortográficas: la API rechaza claves desconocidas en lugar de ignorarlas.

Una vez que la solicitud mínima funciona, tienes una prueba de humo que puedes volver a ejecutar cuando algo falle. Guárdala en un archivo; cuando el servicio falle a las dos de la madrugada, vale más que cualquier discurso.

Entradas de primer y último fotograma

Las imágenes de entrada son el mayor factor determinante del éxito de una tarea. Moldean el contenido del clip y, al mismo tiempo, son la fuente más común de solicitudes rechazadas.

Qué controla el primer fotograma

La imagen del primer fotograma establece el estado inicial del clip generado: composición, sujeto, iluminación y color. El modelo genera movimiento y continuación a partir de ese punto de partida, por lo que la imagen debe parecerse a un fotograma que realmente querrías en el tiempo cero. Las imágenes de origen borrosas, recortadas o muy comprimidas no mejoran mágicamente en etapas posteriores.

Qué controla el último fotograma

Proporcionar una imagen de último fotograma fija el estado final. Es útil cuando el clip debe terminar en una toma concreta: un fotograma de producto atractivo, una revelación de logotipo o un corte a juego en la edición. Si se omite, el modelo elige el final por sí mismo, lo cual está bien para trabajos exploratorios pero es impredecible para producción.

Cómo interactúan ambos

Cuando se proporcionan ambos, el modelo interpola entre ellos. Esto tiene consecuencias prácticas:

  • La continuidad gana a la confrontación. Dos fotogramas de la misma escena con un movimiento moderado producen un clip más coherente que dos imágenes no relacionadas. Si los fotogramas difieren enormemente, espera deformaciones visibles en lugar de una transición razonable.
  • Las relaciones de aspecto deben coincidir. Una relación de aspecto discordante entre el primer y el último fotograma obliga al modelo a recomponer de forma incómoda. Recorta ambos a la misma proporción antes de enviar.
  • Las resoluciones deben ser comparables. Enviar un primer fotograma nítido y un último fotograma de baja resolución da señales contradictorias al modelo.

Lista de verificación antes del envío

Antes de enviar, verifica: que ambas URL de imagen sean accesibles públicamente y no caduquen a mitad de la tarea; que ambas estén en un formato admitido; que ambas tengan la misma relación de aspecto; y que ninguna sea una captura de pantalla con elementos de interfaz que no quieres que se rendericen. Una solicitud HEAD rápida a cada URL detecta la mayoría de estos problemas de forma más barata que una tarea de generación fallida.

Si aun así encuentras un rechazo, el mensaje de error normalmente apunta al objeto de entrada. Valida las imágenes localmente primero —dimensiones, formato y accesibilidad— y después sospecha de la API.

Ajustes de resolución y audio nativo

Los ajustes de salida son donde los desarrolladores tienden a configurar en exceso. La buena noticia es que los valores predeterminados son razonables; el riesgo está en copiar valores de la documentación de otro modelo.

Resolución

La resolución determina el tamaño del video entregado y, a su vez, influye en el tiempo de generación y el volumen de salida. Dos reglas prácticas:

  • Elige para el destino, no por el número. Un clip para un feed móvil no necesita renderizarse a un tamaño grande para luego reducirlo. Elige la resolución más pequeña que satisfaga a la plataforma de destino.
  • Prefiere uno de los valores predefinidos de la documentación. Pasar valores arbitrarios o no admitidos es una causa común de rechazo de solicitudes. Si necesitas un tamaño de fotograma específico, recorta o escala after la generación en lugar de pelearte con el validador de la solicitud.

Audio nativo

El interruptor de audio nativo determina si el clip generado incluye una pista de audio acompañante producida junto con el video. Considera si lo necesitas:

  • Actívalo cuando el clip sea el entregable final que se verá con sonido: contenido social, promociones cortas, escenas de personajes donde el audio ambiental realza el movimiento.
  • Desactívalo cuando vayas a añadir tu propia música o narración en el editor, o cuando el clip sea un activo intermedio. Generar audio que vas a descartar es trabajo desperdiciado y hace que el procesamiento posterior sea más pesado.

Duración

La duración está acoplada a todo lo demás: los clips más largos tardan más en generarse y son más propensos a la deriva de consistencia del sujeto. Para una primera integración, empieza corto. Confirma que la canalización funciona de extremo a extremo con un clip breve y luego alarga cuando confíes en el flujo.

Mantén pequeño el objeto de ajustes

Si te encuentras añadiendo ajustes para corregir problemas de calidad, detente y comprueba si el problema está realmente en las imágenes de entrada. La mayoría de las salidas decepcionantes se remontan al capítulo 4, no a la falta de un botón. Configura con intención, registra el objeto de ajustes exacto junto con cada identificador de tarea y podrás atribuir los cambios de calidad a ajustes concretos.

La misma solicitud con Python

La solicitud curl se traduce directamente a Python. El objetivo aquí no es un framework, sino un cliente pequeño y legible que envía la tarea y devuelve el identificador, de modo que la capa de sondeo pueda mantenerse separada.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "seedance-2.5-flash/image-to-video"


def submit_job(first_frame_url: str, last_frame_url: str | None = None) -> dict:
    payload = {
        "model": MODEL,
        "input": {"first_frame_image": first_frame_url},
    }
    if last_frame_url:
        payload["input"]["last_frame_image"] = last_frame_url

    response = requests.post(
        f"{BASE_URL}/image-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Por qué está estructurado así

  • Configuración mediante variables de entorno. La URL base y la clave están fuera del código, de modo que el mismo cliente puede ejecutarse contra distintos entornos.
  • timeout=30 en el envío. El envío es rápido; un envío que se cuelga indica un problema de red o autenticación que quieres descubrir pronto, no bloquear indefinidamente un proceso de trabajo.
  • raise_for_status() antes de analizar. El cuerpo de una respuesta 4xx suele ser un objeto de error JSON, no una tarea. Lanzar la excepción primero mantiene limpio el camino normal y permite que quien llama maneje el fallo de forma explícita.
  • Envío separado del sondeo. submit_job hace una sola cosa. El bucle de sondeo del capítulo siguiente recibe el diccionario devuelto y se encarga de esperar.

Portarlo a un servicio

En un servicio real, envuelve la llamada para que los fallos aparezcan como excepciones tipadas que lleven el código de estado y el cuerpo de la respuesta; al depurar en producción querrás el cuerpo sin procesar. Registra el cuerpo de la solicitud junto con el identificador de tarea devuelto; cuando un compañero pregunte por qué un clip se ve mal, esa línea de registro será toda la investigación.

Los nombres de los campos son exactamente los mismos que en el ejemplo de curl. Si sabes leer uno, sabes leer el otro; esa es precisamente la razón por la que vale la pena dedicar cinco minutos a empezar con curl.

Sondear el resultado sin saturar la API

Ahora la tarea existe y tiene un identificador. El enfoque ingenuo —dormir sesenta segundos y cruzar los dedos— falla de dos maneras: desperdicia tiempo cuando la tarea termina antes y falla por completo cuando la tarea tarda más.

Sondea el campo de estado, no el reloj

Escribe un bucle que consulte el estado actual de la tarea y ramifique según él:

import time
import requests


def wait_for_job(job_id: str, timeout_s: int = 600) -> dict:
    deadline = time.monotonic() + timeout_s
    delay = 2.0
    while time.monotonic() < deadline:
        r = requests.get(
            f"{BASE_URL}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        r.raise_for_status()
        job = r.json()
        status = job.get("status")

        if status == "succeeded":
            return job
        if status == "failed":
            raise RuntimeError(f"job failed: {job.get('error')}")

        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)  # retroceso exponencial acotado

    raise TimeoutError(f"job {job_id} not terminal after {timeout_s}s")

Características importantes

  • Estados terminales explícitos. Solo succeeded y failed terminan el bucle. Cualquier otro estado es transitorio. No trates un estado desconocido como fallo: con el tiempo aparecen nuevos estados intermedios y tu bucle debe tolerarlos.
  • Retroceso acotado. Empieza pequeño (unos segundos), crece con un factor moderado y limita a unos diez o quince segundos. Esto mantiene ágiles las tareas cortas sin saturar el endpoint durante renderizaciones largas.
  • Fecha límite estricta. Limita siempre el tiempo total de espera. Sin ella, una tarea atascada ocupa un proceso de trabajo para siempre. Elige el límite según tu tiempo de renderizado real más largo más un margen.
  • Separa el fallo del tiempo de espera agotado. Una tarea failed es un error de generación que merece reportarse al usuario. Un tiempo de espera agotado es una condición de infraestructura que merece reintentarse o investigarse por separado. Mezclar ambos hace que la revisión de incidentes sea dolorosa.

En un servicio web

No ejecutes este bucle dentro del manejador de la solicitud que el usuario está esperando. Envía la tarea, almacena el identificador, devuelve de inmediato y deja que un proceso de trabajo en segundo plano sondee y entregue el resultado —mediante webhook, cola o actualizaciones de fila que vigile el frontend. El bucle anterior es una preocupación del proceso de trabajo, no de HTTP.

Solucionar fallos comunes

La mayoría de los fallos se agrupan en tres categorías. Identifica primero la categoría y luego la causa concreta.

Categoría 1: fallo de validación de la entrada

Síntoma: un 4xx inmediato al enviar, antes de cualquier renderizado.

Diagnostica en este orden:

  1. ¿Es accesible la URL de la imagen? Recupérala tú mismo desde la misma red. Las URL firmadas caducadas y los buckets privados son la causa principal.
  2. ¿Es compatible el formato? Vuelve a codificar a un formato estándar en lugar de discutir.
  3. ¿Son coherentes el primer y el último fotograma? Las relaciones de aspecto discordantes o las escenas muy diferentes suelen manifestarse como problemas de validación o de calidad.
  4. ¿Has añadido campos con nombres incorrectos? Las claves desconocidas suelen rechazarse en lugar de ignorarse. Compáralas con la referencia del modelo.

Categoría 2: discrepancia de parámetros

Síntoma: la solicitud se rechaza por algún ajuste, o la salida ignora tu configuración.

  • Resolución o duración no admitidas. Usa solo los valores de la documentación; los números arbitrarios son una causa común de rechazo.
  • Error tipográfico en el identificador del modelo. Es una cadena fija: cópiala, no la vuelvas a escribir.
  • Anidamiento incorrecto. Un ajuste que pertenece al nivel superior colocado dentro de input, o viceversa, produce errores confusos. Usa la estructura de solicitud del capítulo 3 como referencia.

Categoría 3: tiempos de espera de sondeo agotados y tareas fallidas

Síntoma: la tarea se acepta pero nunca alcanza un estado terminal de éxito.

  • Confirma que estás sondeando el identificador correcto. Los errores de copiar y pegar entre tareas en scripts por lotes son sorprendentemente comunes.
  • Comprueba si el estado avanza realmente. Registra el estado en cada sondeo para ver si la tarea progresa o se estanca.
  • Distingue un fallo de la API de un fallo de generación. Si la propia solicitud de sondeo falla, es un problema de transporte. Si la tarea informa failed, lee el cuerpo del error; normalmente señala la entrada que causó el problema.
  • Vuelve a ejecutar la prueba de humo mínima con curl. Si la prueba de humo también falla, el problema está en las credenciales o en el servicio; si tiene éxito, el problema está en tu cuerpo de solicitud.

Postura general de depuración

Registra tres cosas por cada tarea: el cuerpo exacto de la solicitud, el identificador de tarea devuelto y el estado final con el cuerpo del error. Con esas tres cosas, casi cualquier incidente es un diagnóstico de cinco minutos en lugar de una tarde entera. En caso de duda, reduce la solicitud a la forma mínima del capítulo 3 y añade campos uno a uno hasta que falle; el último campo añadido es el culpable.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API