Blog

Tutorial

Cómo usar kling-4.0-flash de imagen a video con la API de HiAPI: curl y Python

Recorrido práctico de la solicitud: entrada del fotograma inicial, sondeo de tareas asíncronas, audio síncrono y resolución de errores

Nov 12, 2026
Imagen de portada: una pila de hojas de color blanco crema desalineadas, con los bordes delineados en negro carbón, entre las que se intercala una hoja guarda de color rojo óxido, que proyecta debajo una sombra plana.
Modelo
kling-4.0-flash
En esta página

Qué hace el endpoint de imagen a video kling-4.0-flash

kling-4.0-flash/image-to-video es un modelo de generación de video condicionado por imagen. Le entregas una imagen —el fotograma inicial— junto con un prompt de texto, y devuelve un video generado que comienza en ese fotograma y evoluciona según tu descripción.

Lo más importante que debes interiorizar antes de escribir código: esta no es una llamada de solicitud/respuesta que devuelva los bytes del video en el mismo intercambio HTTP. La generación requiere tiempo, por lo que el endpoint sigue un modelo de tarea asíncrona. Tu primera solicitud envía un trabajo; después consultas el estado del trabajo repetidamente hasta que alcanza un estado terminal.

Distingue bien estos tres conceptos, porque corresponden a tres partes distintas del cliente:

  • Envío: la carga útil que mandas: la imagen del fotograma inicial, el prompt y las opciones de generación.
  • Referencia de la tarea: el identificador devuelto al enviar, que usarás después para consultar esa tarea.
  • Obtención del resultado: comprobar el estado repetidamente hasta recibir el video finalizado (o un fallo).

Una vez que tratas el endpoint como una cola de tareas en lugar de una RPC, el resto de la integración —el intervalo de sondeo, los tiempos de espera, los reintentos— pasa a ser una tubería asíncrona ordinaria y deja de ser un caso especial. Si quieres consultar también la documentación más completa del endpoint mientras sigues este recorrido, ábrela en otra pestaña y ve alternando.

Antes de enviar la solicitud

Hay tres cosas que preparar antes de la primera llamada.

1. Credenciales de API

Necesitas una clave de API de HiAPI. Cada solicitud la envía como token bearer mediante la cabecera Authorization. No la incluyas en el control de versiones: léela de una variable de entorno en lugar de pegarla en el script.

export HIAPI_API_KEY="your-api-key-here"

2. Ruta del endpoint

Todas las llamadas pasan por la interfaz unificada de HiAPI. El identificador de modelo al que apuntas es kling-4.0-flash/image-to-video. Tanto tu solicitud de envío como las consultas de estado posteriores apuntan al mismo espacio de nombres de modelo, así que coloca ese identificador en una constante del código en lugar de dispersar literales de cadena por todas partes.

3. Una imagen de fotograma inicial lista

Necesitas una imagen que sirva como fotograma de apertura. Antes de enviarla, decide dos cosas:

  • Cómo pasarla: como URL de acceso público o como datos de imagen codificados, según la forma que acepte el endpoint en tu caso de uso.
  • Si está bien formada: formato correcto, legible y no tan grande como para inflar el cuerpo de la solicitud.

Una regla práctica: mantén el cuerpo de la solicitud pequeño y explícito. Si pasas una URL, asegúrate de que sea accesible sin autenticación. Si pasas datos codificados, confirma que la codificación es exactamente la que espera el endpoint.

Prepara también un prompt breve y concreto. Los prompts de imagen a video funcionan mejor cuando describen movimiento y cambio (qué se mueve, cómo se mueve la cámara) en lugar de repetir lo que ya se ve en el fotograma.

La solicitud curl que funciona

Abajo tienes una llamada de envío completa. Sustituye los marcadores de posición por tu clave, tu imagen y tu prompt.

curl -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Slow dolly-in on the subject as light shifts across the scene",
    "image": "https://your-host.example/first-frame.jpg"
  }'

Desglose elemento por elemento:

  • -X POST: el envío es una operación de escritura, no una consulta.
  • URL: el identificador del modelo forma parte de la ruta unificada del endpoint. Es el único lugar donde especificas el modelo.
  • Authorization: Bearer $HIAPI_API_KEY: cabecera que el shell expande desde tu variable de entorno. Las comillas dobles permiten la expansión de la variable y a la vez mantienen su valor como un único argumento.
  • Content-Type: application/json: el cuerpo es JSON; sin esta cabecera, algunas pasarelas rechazan o analizan mal la carga útil.
  • -d '{ ... }': el cuerpo JSON. prompt describe el movimiento; image proporciona el fotograma inicial. Cada campo es explícito: nada queda implícito por posición ni por valores predeterminados que no ves.

Un envío correcto devuelve un cuerpo JSON con el identificador de la tarea. Captúralo: ese valor es tu manejador para operar sobre la tarea. Si estás explorando de forma interactiva, puedes pasar la respuesta por un formateador JSON para copiar el identificador:

curl -s -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Slow dolly-in as light shifts","image":"https://your-host.example/first-frame.jpg"}' | python -m json.tool

No supongas que el video está en esta respuesta. No lo está: esta respuesta solo te dice que la tarea fue aceptada.

La misma solicitud en Python

El cliente en Python se corresponde exactamente con la carga útil de curl. Cambiar de lenguaje no altera la semántica, solo el mecanismo que envía los bytes. Usa requests y lee la clave de una variable de entorno:

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-4.0-flash/image-to-video"
BASE_URL = "https://api.hiapi.ai/v1/models"

def submit_job(prompt: str, image: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/{MODEL}",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "prompt": prompt,
            "image": image,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

job = submit_job(
    prompt="Slow dolly-in on the subject as light shifts across the scene",
    image="https://your-host.example/first-frame.jpg",
)
print(job)

Puntos clave de la migración:

  • json= en lugar de -d: pasar un dict hace que requests serialice el cuerpo y establezca el tipo de contenido. Obtienes el mismo formato en el cable que el ejemplo de curl, sin escribir JSON a mano.
  • raise_for_status(): convierte las respuestas que no son 2xx en excepciones, para que no confundas por error un cuerpo de error con una referencia de tarea.
  • timeout=30: el envío debería ser rápido. Un tiempo de espera holgado evita que la conexión se quede colgada sin ocultar llamadas realmente lentas.
  • Un solo constante para el modelo: si más adelante cambias de modelo, solo tocas una línea.

El dict devuelto contiene el identificador de la tarea, que se aprovecha en la siguiente sección.

Gestionar el ciclo de vida de la tarea asíncrona

El patrón de integración es enviar y luego sondear. Dos fases claramente delimitadas.

Fase 1: enviar y capturar la referencia

La llamada submit_job de la sección anterior devuelve un cuerpo JSON con el identificador de la tarea. Guárdalo. Lo necesitarás en cada comprobación de estado posterior, y perderlo significa perder la tarea.

Fase 2: sondear hasta el estado terminal

La comprobación de estado es una solicitud de lectura sobre la misma tarea. Repítela a intervalos fijos hasta que la tarea alcance un estado terminal: completada o fallida. Un bucle sencillo con un número máximo de intentos:

import time

def wait_for_job(task_id: str, attempts: int = 60, interval: float = 5.0) -> dict:
    for _ in range(attempts):
        response = requests.get(
            f"{BASE_URL}/{MODEL}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
            timeout=30,
        )
        response.raise_for_status()
        status = response.json()

        state = status.get("status")
        if state in ("succeeded", "failed"):
            return status
        time.sleep(interval)

    raise TimeoutError(f"Job {task_id} did not finish in time")

Decisiones de diseño que conviene tomar deliberadamente:

  • Limita las iteraciones del bucle. Nunca sondees de forma infinita. Un número máximo de intentos más un intervalo fijo te da una espera máxima predecible.
  • Duerme entre comprobaciones, no dentro de la solicitud. Sondear con demasiada frecuencia desperdicia cuota y puede provocar límites de tasa.
  • Trata el fallo como estado terminal. Una tarea fallida no se convertirá en exitosa en el siguiente sondeo: detente y expón el error.
  • Distingue entre en espera y terminado. Solo los estados terminales ponen fin al bucle; cualquier otro estado significa seguir esperando.
  • Persiste el ID de la tarea. Si el proceso se cae a mitad del sondeo, querrás poder reanudar en lugar de regenerar.

En producción, saca el sondeo del hilo de la solicitud —llévalo a un trabajador en segundo plano o a un consumidor de cola— para que las generaciones largas no mantengan abierta una solicitud web.

Usar la opción de audio síncrono

El endpoint ofrece una opción de audio síncrono. En la práctica, para el cliente esto significa una cosa: si la habilitas, la llamada se bloquea hasta que la generación termina, en lugar de devolver una referencia de tarea que puedas sondear.

Esto cambia tu diseño de forma concreta:

  • El presupuesto de tiempo de espera debe aumentar. Una llamada de generación bloqueante puede tardar mucho más que una solicitud de API típica. Configura el tiempo de espera del cliente para cubrir toda la duración prevista, no solo la del envío.
  • No hay puntos de control intermedios. Con el sondeo, puedes recuperarte de una caída usando el ID de la tarea. Con una llamada bloqueante, si se corta la conexión significa rehacer el trabajo.
  • Presión sobre hilos y grupos de conexiones. Una llamada bloqueante ocupa un trabajador durante toda su duración. En un servidor web, esto limita rápidamente tu capacidad de concurrencia.

¿Cuándo es aceptable una llamada bloqueante? Cuando ejecutas un script puntual, una herramienta de CLI o una tarea por lotes, donde nada más espera el resultado y la sencillez prima sobre el rendimiento. En esos escenarios, la llamada síncrona elimina por completo el mecanismo de sondeo y el código queda más corto.

¿Cuándo evitarla? En cualquier ruta de solicitud orientada al usuario, en servicios de alta concurrencia o en cualquier lugar donde el cliente pueda agotar el tiempo de espera y reintentar: una llamada bloqueante reintentada puede duplicar tu trabajo. En esos escenarios, mantén el patrón asíncrono de envío y sondeo de la sección anterior y desactiva la opción síncrona.

Diagnosticar fallos comunes

Aborda los fallos por capas. El primer error que ves suele ser el más superficial, así que corrígelo y vuelve a ejecutar en lugar de adivinar varios problemas a la vez.

Errores de autenticación

Un 401 o 403 significa que las credenciales faltan, están mal formadas o fueron rechazadas. Comprueba que HIAPI_API_KEY esté realmente definida en el entorno que ve tu proceso: una variable exportada en un shell no pasa a otro shell ni a un contenedor. Confirma que la cabecera Authorization es Bearer <key>, con un solo espacio y sin comillas sobrantes traídas del copiar y pegar.

Cuerpo de solicitud mal formado

Un 400 suele significar que el cuerpo no se puede analizar o que faltan campos obligatorios. Revisa si enviaste Content-Type: application/json, si el JSON es válido (una coma final lo hace fallar) y si prompt e image están presentes y son cadenas no vacías. Al depurar, vuelca el cuerpo que realmente enviaste, no el dict que pretendías enviar.

Problemas con la imagen de entrada

Estos problemas suelen manifestarse como errores de validación, no como errores evidentes de imagen. Comprueba en orden:

  • Accesibilidad: si pasas una URL, recupérala desde el mismo entorno de red desde el que se origina la solicitud. Una URL que funciona en el navegador puede estar bloqueada por el firewall o protegida por autenticación para la API.
  • Formato: confirma que la imagen es un archivo compatible y no está dañado. En caso de duda, vuelve a exportarla.
  • Tamaño: una imagen demasiado grande puede provocar fallos de validación o inflar el cuerpo de la solicitud más allá de los límites.
  • Codificación: si envías datos codificados, confirma exactamente que la codificación coincide con la que espera el endpoint; un prefijo que no coincide o un espacio en blanco sobrante lo hacen fallar.

Fallos a nivel de tarea

Si el envío tiene éxito pero la tarea termina en estado fallido, la solicitud está bien formada pero la generación no se completó. Relee el prompt, comprueba si hay ambigüedad o movimientos físicamente poco razonables, y confirma que la imagen del fotograma inicial sirve realmente como punto de partida. Reintenta una vez con un prompt simplificado antes de suponer un problema sistémico, y registra el ID de la tarea y el mensaje de fallo para poder correlacionarlos más adelante.

Tiempo de espera agotado en el bucle de sondeo

El TimeoutError que lanza wait_for_job significa que tus límites son demasiado ajustados, no que la tarea esté muerta. Aumenta el número de intentos o el intervalo, y comprueba si estás sondeando un ID de tarea anterior de una ejecución ya finalizada.

Empieza con la solicitud mínima —una imagen, un prompt breve, sin campos opcionales— y añade complejidad solo cuando la línea base funcione. La mayoría de los problemas de integración desaparecen cuando la carga útil es pequeña y explícita.

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