Cómo llamar a kling-4.0/image-to-video en HiAPI: curl, Python y sondeo

Qué hace el endpoint kling-4.0/image-to-video

kling-4.0/image-to-video convierte una sola imagen estática en un videoclip generado de corta duración. En HiAPI se ofrece como un endpoint basado en tareas: se envía una imagen junto con una descripción estilo prompt que indica cómo debería moverse la escena, y la API devuelve inmediatamente un identificador de tarea en lugar del vídeo final terminado.

A nivel de solicitud, quien llama debe proporcionar:

• el identificador del modelo (kling-4.0/image-to-video),
• la imagen de origen (normalmente una URL de imagen accesible públicamente),
• una descripción de texto que guíe cómo debe moverse la imagen o qué debe ocurrir en la escena,
• cualquier opción de generación adicional que este endpoint documente para este modelo.

Lo que se devuelve no es el vídeo en sí. La respuesta de envío incluye un identificador de tarea y un estado inicial. El clip de vídeo real solo estará disponible cuando la tarea de generación haya terminado; en ese momento podrá obtenerse haciendo referencia a dicho identificador.

Esta separación es el modelo mental completo de este endpoint: enviar → obtener el id de la tarea → sondear el estado → descargar el resultado. Cada sección a continuación es una variante de este ciclo.

Como el endpoint es asíncrono, tu código de integración tiene dos responsabilidades en lugar de una: debe enviar una solicitud de envío bien formada y debe gestionar el proceso posterior hasta que la tarea alcance un estado terminal. Si haces bien ambas cosas, el resto es trabajo de conexión habitual.

Requisitos previos y autenticación

Antes de cualquier llamada necesitas dos cosas: una cuenta de HiAPI con acceso a este modelo y una clave de API emitida desde la consola.

La autenticación se realiza por solicitud. Cada llamada a la API incluye tu clave en una cabecera HTTP: el patrón estándar es una cabecera de autorización de estilo bearer:

Authorization: Bearer <YOUR_HIAPI_API_KEY>

No dejes que la clave llegue al control de versiones. La práctica habitual es:

• guardarla en una variable de entorno (por ejemplo, HIAPI_API_KEY) y leerla en tiempo de ejecución;
• no pegarla nunca en código de cliente ni en comandos curl que luego vayas a confirmar en un repositorio;
• rotarla desde la consola en cuanto se filtre.

Expórtala en la shell para que la lean tanto los ejemplos de curl como los de Python que aparecen a continuación:

export HIAPI_API_KEY="your-key-here"

También necesitas una URL de imagen accesible. Este endpoint usa la imagen por referencia, así que una ruta de archivo local en tu portátil no sirve: aloja la imagen en un lugar con una URL HTTPS estable o, si la plataforma ofrece un mecanismo de recursos, súbela y usa la referencia devuelta.

Con la clave exportada y la imagen accesible, ya puedes enviar la tarea.

Desglose paso a paso de la solicitud curl

Una solicitud de envío completa tiene este aspecto:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0/image-to-video",
    "input": {
      "image": "https://example.com/your-image.jpg",
      "prompt": "A slow camera push-in as the subject turns toward the light; soft afternoon shadows"
    }
  }'

Desglose parte por parte:

• -X POST: la creación de tareas es un POST, no un GET. La solicitud lleva en el cuerpo la descripción del trabajo.
• URL: el endpoint unificado de tareas de HiAPI. Para los modelos basados en tareas esta es la misma ruta; el modelo se elige en el cuerpo, no en la ruta.
• Authorization: tu clave, como se describió en la sección anterior.
• Content-Type: application/json: el cuerpo es JSON; si omites o escribes mal esta cabecera, el servidor normalmente rechaza la solicitud antes de que llegue al modelo.
• model: la cadena literal kling-4.0/image-to-video. Trátala como exacta y sensible a mayúsculas; una errata produce un error de modelo no encontrado, no una pista útil.
• input.image: la imagen estática de origen, proporcionada como URL. Es el fotograma que el modelo animará, así que elige una imagen clara y bien compuesta.
• input.prompt: la guía en lenguaje natural. Describe el movimiento y el comportamiento de cámara (acercamiento, paneo, movimiento del sujeto) y el ambiente general. Un prompt vago produce un movimiento vago.

La respuesta inmediata es un objeto de tarea, no un vídeo. Contiene el identificador del trabajo y un campo de estado, normalmente algo parecido a un estado en cola o pendiente tras el envío. Guarda ese identificador; es lo único que necesitas para comprobar el trabajo más adelante.

En este punto el clip de vídeo aún no existe. Es el comportamiento esperado; la siguiente sección muestra cómo gestionarlo.

La misma llamada en Python

La versión en Python hace exactamente lo mismo: mismo endpoint, mismas cabeceras, mismo cuerpo; la herramienta que elijas no cambia el protocolo.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "kling-4.0/image-to-video",
    "input": {
        "image": "https://example.com/your-image.jpg",
        "prompt": "A slow camera push-in as the subject turns toward the light; "
                  "soft afternoon shadows",
    },
}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

resp.raise_for_status()
task = resp.json()
task_id = task["id"]
print("submitted:", task_id, task.get("status"))

Algunos puntos a tener en cuenta en la práctica:

• Usa json=payload en lugar de serializar una cadena a mano. Eso establece el tipo de contenido por ti y evita errores de comillas.
• Mantén la solicitud de envío y las operaciones posteriores en la misma función o clase, para que el id de la tarea no se pierda entre pasos.
• Establece un tiempo de espera explícito. La llamada de envío debería volver rápido; solo crea el trabajo, no espera al vídeo.
• No llames a raise_for_status() y luego asumas que la tarea existe: una respuesta que no sea 2xx significa que no se creó ninguna tarea, y el cuerpo del error normalmente te indicará qué campo está mal.

Si estás construyendo un servicio, envuelve esta llamada en un cliente pequeño, con un método para enviar y otro para consultar el estado. Así centralizas los reintentos, el registro y el manejo de la clave en un solo lugar, en lugar de dispersarlos por cada punto de llamada.

Sondear la tarea asíncrona hasta que termine

La generación de vídeo a partir de una imagen tarda bastante más que una finalización de chat: el modelo debe sintetizar muchos fotogramas, codificarlos y almacenar el resultado. No sería viable devolver el clip manteniendo la conexión abierta tanto tiempo en la respuesta de envío, así que este endpoint es asíncrono por diseño.

Cómo comprobar el estado

Sondea la tarea por su identificador con una solicitud GET:

curl "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

La respuesta describe el trabajo: su estado y, cuando haya terminado, la salida. El estado normalmente pasa de un estado en cola a un estado en ejecución y luego a un estado terminal, por ejemplo, completado con éxito o fallido con un mensaje de error.

Un bucle de sondeo sencillo en Python

import time

def wait_for_task(session, base_url, task_id, timeout=900):
    deadline = time.time() + timeout
    delay = 2.0
    while time.time() < deadline:
        r = session.get(f"{base_url}/tasks/{task_id}", timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")

        if status in ("succeeded", "failed"):
            return data

        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)  # gentle backoff, capped

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

Guía sobre el backoff

• Empieza con intervalos cortos y auméntalos gradualmente. La generación no termina en el primer segundo, así que consultar el endpoint con demasiada frecuencia solo desperdicia cuota y provoca límites de tasa.
• Limita el intervalo para detectar con prontitud los trabajos ya completados; unos pocos segundos en estado estable es suficiente.
• Establece siempre un plazo máximo. Sin un límite, una tarea que nunca termina es indistinguible de una tarea que tarda excepcionalmente mucho.
• Sondea desde un proceso de trabajo en segundo plano o una tarea programada, no bloqueando la solicitud web. Si el usuario espera en la UI, haz que el frontend consulte tu propio endpoint de estado.
• Reintenta los errores de red transitorios en las llamadas de estado, pero no reintentes una tarea que ya informa failed; en ese caso la acción correcta es enviar una nueva tarea.

Obtener y almacenar el clip de vídeo devuelto

Cuando el sondeo devuelve un estado terminal exitoso, el objeto de tarea contiene la referencia de salida del vídeo generado: una URL de recurso o una referencia equivalente que apunta al vídeo terminado.

result = wait_for_task(session, "https://api.hiapi.ai/v1", task_id)
if result["status"] != "succeeded":
    raise RuntimeError(result.get("error") or "generation failed")

video_url = result["output"]["video_url"]

with session.get(video_url, stream=True, timeout=120) as r:
    r.raise_for_status()
    with open(f"{task_id}.mp4", "wb") as f:
        for chunk in r.iter_content(chunk_size=1 << 16):
            f.write(chunk)

Aquí suelen aparecer dos decisiones de diseño.

Descargar a tiempo. Las URL de salida suelen tener caducidad. Si piensas conservar el clip, cópialo a tu propio almacenamiento en lugar de entregar a los usuarios la URL sin procesar y confiar en que siga siendo válida.

Guardar los metadatos junto con el archivo. Persiste el id de la tarea, el prompt, la referencia de la imagen de origen y la hora de creación junto con el vídeo. Cuando más adelante alguien pregunte por qué el clip se ve así, ese registro es la respuesta.

Para ofrecer un servicio, el patrón habitual es: generar en el backend, almacenar el archivo en un almacenamiento de objetos y devolver al cliente tu propia URL estable. Así tu aplicación controla el acceso, la caducidad y la caché, en lugar de depender del ciclo de vida del recurso generado.

Si quieres regenerar con un movimiento distinto, envía una nueva tarea con un prompt ajustado; cada tarea es independiente y no hace falta modificar una tarea ya completada.

Diagnosticar solicitudes fallidas

Cuando algo va mal, investiga desde la estructura de la solicitud hacia fuera. La mayoría de los fallos se reducen a unas pocas causas.

La llamada de envío devuelve un error

• Cadena de modelo incorrecta. kling-4.0/image-to-video debe coincidir exactamente, incluidos mayúsculas y barra. Imprime la cadena que envías realmente en lugar de confiar en el archivo fuente.
• Autenticación rechazada. Confirma que la cabecera es Authorization: Bearer <key> (no la clave sin más, no un parámetro de consulta) y que la variable de entorno está definida en la misma shell o proceso que ejecuta la solicitud.
• Imagen inaccesible. La plataforma debe poder obtener la imagen mediante HTTPS. Las URL de localhost, los buckets privados o los hosts con protección contra hotlinking fallarán. Abre la URL en una ventana de incógnito para verificar que se resuelve sin autenticación.
• Campo ausente o mal nombrado. El cuerpo anida las entradas del modelo bajo input. Poner prompt o image en el nivel superior en lugar de dentro de input es un error habitual; los errores de validación normalmente señalan el nombre del campo.
• Tipo de contenido. Enviar un cuerpo JSON sin Content-Type: application/json se rechaza antes de que el modelo intervenga.

La tarea se creó pero nunca tuvo éxito

• Se sondea poco o nada. Comprueba que tu bucle se ejecuta de verdad y que compara los valores de estado que devuelve la API. Una errata en la comprobación del estado terminal provoca un bucle infinito.
• La tarea pasa a failed. Lee el mensaje de error del objeto de tarea; normalmente apunta a la entrada, por ejemplo, una imagen que no se puede decodificar.
• Has alcanzado el plazo límite. Si el trabajo sigue en ejecución cerca del tiempo de espera, aumenta el límite en lugar de reenviar repetidamente, lo que solo añade carga y coste.
• El enlace de salida ha caducado. Si la tarea tuvo éxito pero la descarga devuelve 404, ha pasado demasiado tiempo entre la finalización y la recuperación. Descarga inmediatamente tras el éxito.

Un hábito de diagnóstico rápido: en las primeras integraciones, registra literalmente el cuerpo de la respuesta de envío. Te dirá el id de la tarea, el estado inicial y los nombres exactos de los campos que devuelve este endpoint, lo que elimina las conjeturas en cada fallo posterior.