API de Kling AI de imagen a vídeo en Python

Usa la API de Kling AI de imagen a vídeo en Python a través del endpoint de tareas asíncronas de HiAPI. El siguiente inicio rápido utiliza el ID del modelo kling-3.0-omni/image-to-video disponible actualmente, sondea la tarea hasta alcanzar un estado terminal y descarga el MP4 generado.

Para consultar los campos exactos, abre la documentación de la API de Kling 3.0 Omni de imagen a vídeo. Usa la página actual del modelo Omni para ver el modelo y el Playground, y verifica el precio en tiempo real de la API de Kling antes de ejecutar en producción.

Inicio rápido: ejecutar Kling de imagen a vídeo en Python

Instala requests con python -m pip install requests, establece HIAPI_API_KEY en el entorno y reemplaza IMAGE_URL por una URL pública de JPEG, PNG o WebP. El script completo es el primer bloque de código copiable:

import os
import time
from pathlib import Path

import requests

API_BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
IMAGE_URL = "https://cdn.example.com/first-frame.jpg"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "kling-3.0-omni/image-to-video",
    "input": {
        "image_urls": [IMAGE_URL],
        "prompt": "The camera slowly pushes in as leaves move in a light breeze",
        "duration": 5,
        "resolution": "1080p",
        "sound": False,
    },
}

created = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json=payload,
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["taskId"]

deadline = time.time() + 900
while time.time() < deadline:
    response = requests.get(
        f"{API_BASE}/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()["data"]

    if task["status"] == "success":
        output_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(task.get("error") or f"Task {task_id} failed")

    time.sleep(8)
else:
    raise TimeoutError(f"Task {task_id} did not finish within 15 minutes")

with requests.get(output_url, stream=True, timeout=180) as download:
    download.raise_for_status()
    with Path("kling-output.mp4").open("wb") as video:
        for chunk in download.iter_content(1024 * 1024):
            if chunk:
                video.write(chunk)

print("Saved kling-output.mp4")

La solicitud de creación devuelve un taskId y no espera a que se complete la generación del vídeo. El script sondea GET /v1/tasks/{taskId}, se detiene en success o fail y descarga la primera salida lo antes posible, ya que las URL de resultado caducan.

Abre el modelo Kling Omni y prueba este payload.

Elegir el modelo de Kling de imagen a vídeo disponible actualmente

ID del modelo	Caso de uso	Convenciones de entrada y salida
kling-3.0-omni/image-to-video	Se requiere control de primer/último fotograma, audio nativo opcional o 4K	Una o dos URL de imagen públicas; 3-15 segundos; 720p, 1080p o 4K
kling-3.0-turbo/image-to-video	Solo se necesita un fotograma inicial y basta con un schema más simple de 720p/1080p	Exactamente una URL de imagen pública; prompt obligatorio; 3-15 segundos; 720p o 1080p

Consulta la referencia completa de campos de Omni en la documentación de Omni I2V. Turbo tiene una referencia de schema de Turbo I2V independiente. Ambos usan el mismo flujo de trabajo de creación y sondeo con /v1/tasks, por lo que puedes mantener un solo ejecutor y solo cambiar model e input.

Cuerpo de solicitud que cumple los requisitos del modelo

Omni con primer y último fotograma

Envía una URL para el primer fotograma, o envía dos URL ordenadas como [first, last]:

{
  "model": "kling-3.0-omni/image-to-video",
  "input": {
    "image_urls": [
      "https://cdn.example.com/first-frame.jpg",
      "https://cdn.example.com/last-frame.jpg"
    ],
    "prompt": "The camera arcs around the subject as the light changes from dawn to noon",
    "duration": 8,
    "resolution": "1080p",
    "sound": true
  }
}

Omni acepta uno o dos image_urls. Su prompt es opcional, duration es un entero de 3 a 15, resolution es 720p, 1080p o 4K, y sound es opcional.

Turbo con un fotograma inicial

{
  "model": "kling-3.0-turbo/image-to-video",
  "input": {
    "prompt": "The subject turns toward the camera while leaves move in a light breeze",
    "image_urls": ["https://cdn.example.com/first-frame.jpg"],
    "duration": 8,
    "resolution": "1080p"
  }
}

Turbo requiere un prompt y exactamente una entrada en image_urls. No envíes campos exclusivos de Omni (como sound) ni añadas campos de texto a vídeo (como aspect_ratio); la imagen de origen determina el encuadre.

Precios de Kling AI: usa las tarifas en tiempo real, no copies precios

Los precios de Kling AI en HiAPI se facturan por uso. Actualmente ambos modelos de imagen a vídeo se facturan por segundos generados, con una tarifa concreta determinada por el modelo y la resolución; Omni además tiene tarifas distintas según el audio esté activado o no. Clips más largos, mayor resolución o audio nativo modifican el coste de la tarea.

Las tarifas pueden cambiar, por lo que esta guía no fija una tabla de precios en dólares. Antes de presupuestar o enviar tareas en lote, consulta inmediatamente la tabla de precios de modelos en tiempo real.

¿Kling AI es gratis?

No: en HiAPI, la generación con la API de Kling de imagen a vídeo no es una API gratuita e ilimitada. Las tareas exitosas consumen saldo según la tarifa en tiempo real del modelo, la duración, la resolución y la configuración de audio elegidos. Las promociones de cuenta o las recompensas para nuevos usuarios pueden cambiar y estar sujetas a condiciones, así que no las consideres un nivel gratuito garantizado de Kling; verifica las ofertas vigentes y tu saldo en la cuenta antes de enviar tareas.

Comprobaciones de producción que evitan tareas fallidas o duplicadas

1. Usa URL de imagen HTTPS directamente descargables. localhost, las páginas que requieren iniciar sesión, las páginas HTML compartidas y las URL firmadas caducadas pueden fallar después de crear la tarea.
2. Guarda el taskId antes de reintentar el worker. Reintentar la llamada de creación puede crear y facturar una segunda tarea.
3. Trata success y fail como estados terminales. En producción, usa el callback.url de nivel superior y mantén el sondeo como respaldo de conciliación.
4. Descarga output[].url a tiempo y copia los resultados que deban conservarse a largo plazo en un almacenamiento bajo tu control.
5. Valida el schema del modelo elegido antes de enviar. Las convenciones estrictas del modelo rechazan campos desconocidos.

Errores comunes

• HTTP 400: la solicitud no coincide con el schema; revisa los campos indicados, los valores de enumeración, la longitud del array y los tipos JSON.
• HTTP 401: la clave bearer falta, no es válida o no puede usarse con el modelo elegido.
• La tarea pasa a fail: la solicitud de creación superó la validación, pero el renderizador no pudo obtener la entrada o completar la generación. Registra el taskId y el error devuelto por separado de la respuesta de creación.
• La URL de salida ha caducado: es posible que el renderizado haya tenido éxito, pero la URL temporal de entrega no se descargó a tiempo.

Preguntas frecuentes

¿Qué modelo de Kling de imagen a vídeo debería usar en Python?

Usa kling-3.0-omni/image-to-video cuando necesites control de uno o dos fotogramas, audio nativo opcional o 4K. Usa kling-3.0-turbo/image-to-video cuando un fotograma inicial y una salida de 720p/1080p sean suficientes. El código Python de creación, sondeo y descarga permanece igual.

¿Cuáles son los ID actuales de los modelos de Kling AI de imagen a vídeo?

Los ID disponibles actualmente que cubre este artículo son kling-3.0-omni/image-to-video y kling-3.0-turbo/image-to-video. Envía cualquiera de ellos en el campo model de nivel superior de POST /v1/tasks.

¿Cuántas imágenes acepta Kling de imagen a vídeo?

Omni acepta una imagen como primer fotograma, o dos imágenes en el orden [first, last]. Turbo acepta exactamente una imagen de fotograma inicial.

¿Cuánto cuesta la API de Kling AI?

Se factura por segundos generados. La tarifa en tiempo real exacta depende del modelo y la resolución, y en Omni también de la configuración de audio. Usa la página de precios en tiempo real, no copies precios estáticos de esta guía.

¿Usar Kling AI a través de la API es gratis?

No se garantiza un nivel gratuito ilimitado de la API de Kling. La generación consume el saldo de la cuenta según la tarifa de tarea en tiempo real. Comprueba si tu cuenta tiene alguna oferta de inicio vigente sujeta a condiciones, en lugar de asumir una cuota gratuita fija.

¿Por qué falla una tarea aunque la solicitud de creación se haya realizado correctamente?

El JSON superó la validación inicial, pero el renderizador puede no haber podido obtener la imagen o completar la generación. Confirma que la imagen sea pública y no haya caducado, y luego revisa el error del estado terminal usando el taskId guardado.

¿Cómo obtengo el vídeo generado?

Lee data.taskId de la respuesta de creación. Un script local puede sondear GET /v1/tasks/{taskId}, y en producción puedes usar callback.url. En success, descarga data.output[0].url antes de que caduque.

A continuación, lee la referencia completa de la API de Kling Omni y luego, cuando estés listo para probar una solicitud, abre la página actual del modelo.