API de Kling 3.0: código de solicitud de texto a video y clips reales

Una tarea de texto a video de Kling 3.0 es un solo POST a https://api.omniakey.com/v1/media/tasks con el id de modelo kling-3.0, la operación text_to_video y dos parámetros obligatorios: duration (5, 10 o 15 segundos) y mode (std o pro). La respuesta trae un id de tarea; consúltelo hasta que termine y luego descargue el MP4. El 29 de octubre de 2026 hicimos dos clips de 5 segundos en modo standard a 1280×720 y medimos los archivos y los fotogramas.

Qué lleva una solicitud de Kling 3.0

En el cuerpo van siete campos. Dos de ellos, duration y mode, son obligatorios en Kling y fijan la duración del clip y la banda de calidad.

La muestra de la propia página del modelo envía duration 6 y un campo resolution de 720p, y ninguno de los dos es válido aquí: la página solo admite 5, 10 o 15 segundos y dice que no hay un campo resolution aparte (página del modelo, consultada el 29 de octubre de 2026). Sus preguntas frecuentes asignan la salida standard a 720P y la pro a 1080P.

El audio llega de forma predeterminada y la página no muestra ningún interruptor (consultada el 29 de octubre de 2026). La relación de aspecto se aplica al texto a video; el image to video toma su forma del primer fotograma y rechaza una proporción explícita. Estas dos ejecuciones usaron std a 5 segundos y 16:9, mientras que el modo pro, 10 s y 15 s, 9:16 y 1:1, image to video y un último fotograma quedaron fuera de ellas.

La redacción del prompt define la escena, la acción y la cámara. La guía de prompts de Kling 3.0 cubre las partes de un prompt y el lenguaje de cámara.

El código de la solicitud

Un solo archivo de Python envía el cuerpo, consulta la tarea y descarga el MP4. Lee la clave de OMNIAKEY_API_KEY, pone un Idempotency-Key aleatorio en la solicitud de creación y espera 5 segundos entre consultas, hasta 180 intentos. El cuerpo lleva los mismos campos y valores que los dos clips de la sección siguiente: modelo kling-3.0, type video, operation text_to_video, duration 5, mode std y relación de aspecto 16:9.

import json
import os
import time
import urllib.error
import urllib.request
import uuid

API = "https://api.omniakey.com/v1/media/tasks"
KEY = os.environ["OMNIAKEY_API_KEY"]

def request(method, url, body=None, extra_headers=None):
    headers = {"Authorization": f"Bearer {KEY}", "User-Agent": "omniakey-example/1"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    headers.update(extra_headers or {})
    req = urllib.request.Request(url, data=data, headers=headers, method=method)
    with urllib.request.urlopen(req, timeout=120) as resp:
        return json.load(resp)

def poll(url, attempts=5):
    for attempt in range(attempts):
        try:
            return request("GET", url)
        except urllib.error.HTTPError as err:
            if err.code < 500 or attempt == attempts - 1:
                raise
        except urllib.error.URLError:
            if attempt == attempts - 1:
                raise
        time.sleep(5 * (attempt + 1))

def text_to_video(prompt, out_path, duration=5, mode="std", aspect_ratio="16:9"):
    body = {
        "model": "kling-3.0",
        "type": "video",
        "operation": "text_to_video",
        "input": {"prompt": prompt},
        "parameters": {"duration": duration, "mode": mode, "aspect_ratio": aspect_ratio},
    }
    task = request("POST", API, body, {"Idempotency-Key": str(uuid.uuid4())})["id"]
    print("task", task, flush=True)
    for _ in range(180):
        time.sleep(5)
        state = poll(f"{API}/{task}")
        if state["status"] not in ("queued", "processing"):
            break
    if state["status"] != "succeeded":
        raise RuntimeError(state.get("error") or state["status"])
    asset_url = state["assets"][0]["url"]  # enlace firmado: dura poco, así que descárguelo ahora
    req = urllib.request.Request(asset_url, headers={"User-Agent": "omniakey-example/1"})
    with urllib.request.urlopen(req, timeout=300) as resp, open(out_path, "wb") as f:
        f.write(resp.read())
    return task

if __name__ == "__main__":
    task = text_to_video(
        "A paper boat drifts slowly down a rain-soaked street at dusk. Warm streetlights reflect on "
        "the wet cobblestones. The camera follows the boat at a steady pace. No people, no text.",
        "paper-boat.mp4",
    )
    print("done", task)

Cada consulta es un GET a la dirección de la tarea, y el bucle sigue el status en lugar de progress.percent, que puede quedarse en 0 mientras se renderiza el clip. Cuando el status deja de ser queued o processing, el código se detiene: succeeded lleva a la descarga desde assets[0].url y cualquier otro estado lanza el mensaje de error de la propia tarea. La descarga se hace de inmediato porque ese enlace del recurso caduca; si caduca, vuelva a consultar la tarea para obtener uno nuevo. Una consulta que sufre una conexión cortada o un error del servidor (5xx) se reintenta hasta cinco veces, con una pausa mayor cada vez.

Ejecutamos este archivo una vez más el 29 de octubre de 2026 con los mismos ajustes. El primer intento perdió la conexión durante el sondeo, y por eso ahora la consulta reintenta. La segunda ejecución devolvió la tarea task_PNB1kPopriUyfcHsXhVWY2hBOEoSUIqM, y su MP4 midió 5.04 segundos a 1280×720 con una pista AAC estéreo. De la creación a la descarga tardó 807 segundos, frente a 82.2 y 110.7 segundos de los dos clips de abajo, así que conviene prever esperas largas.

Dos clips que hicimos

Ambas solicitudes salieron el 29 de octubre de 2026 con el cuerpo indicado arriba. La tarea del paper boat es task_cbOtsBxO75cml3nOmVUu9YG3PkYXW2ja y la del teapot es task_M2Ub1EoCaCUa1FjOZDdWDOuEOS9nRjnt. Cada prompt se envió exactamente como está escrito.

Barco de papel

A paper boat drifts slowly down a rain-soaked street at dusk. Warm streetlights reflect on the wet cobblestones. The camera follows the boat at a steady pace. No people, no text.

Tetera

A ceramic teapot sits on a wooden table by a window. Steam rises in slow curls. Soft morning light moves across the table. The camera pushes in slowly. No people, no text.

Qué midieron los archivos

Una herramienta de clips midió cada descarga el 29 de octubre de 2026.

• Barco de papel — Tamaño: 1280×720; Frecuencia de fotogramas: 24.0 fps; Duración: 5.04 s; Audio: AAC, 2 canales, 44.1 kHz; Nivel medio: −50.9 dB; Nivel máximo: −34.0 dB; Cortes: ninguno
• Tetera — Tamaño: 1280×720; Frecuencia de fotogramas: 24.0 fps; Duración: 5.04 s; Audio: AAC, 2 canales, 44.1 kHz; Nivel medio: −54.3 dB; Nivel máximo: −35.9 dB; Cortes: ninguno
• Clip del código — Tamaño: 1280×720; Frecuencia de fotogramas: 24.0 fps; Duración: 5.04 s; Audio: AAC, 2 canales, 44.1 kHz; Nivel medio: −48.4 dB; Nivel máximo: −20.0 dB; Cortes: ninguno

Los dos primeros clips son muy silenciosos: niveles medios de −50.9 dB y −54.3 dB, con picos de −34.0 dB y −35.9 dB. El clip del código suena más alto, con una media de −48.4 dB y un pico de −20.0 dB. Solo medimos el nivel; el contenido de las pistas quedó fuera de la medición. El detector de cambios de plano no encontró ningún corte fuerte ni débil en los tres, así que cada clip se reproduce como un solo plano.

Qué muestran los fotogramas

Ambos clips siguen el prompt, y el de la tetera añade un pequeño movimiento propio.

En el clip del barco de papel, el barco permanece cerca del centro del encuadre durante los 5.04 segundos mientras la calle mojada se desliza por detrás, así que el plano se lee como una cámara que sigue al barco. Los reflejos cálidos de las farolas siguen en los adoquines hasta el último fotograma (fotogramas revisados el 29 de octubre de 2026). Ningún corte interrumpe el seguimiento.

En el clip de la tetera, el vapor sube en espirales lentas y se desvanece, y la luz de la mañana avanza por la mesa de madera. La tetera termina más grande y más hacia la parte inferior derecha de lo que empezó, lo que se lee como un acercamiento con cierta deriva lateral; el prompt pedía un acercamiento lento, y la deriva es algo que el prompt no pidió (fotogramas revisados el 29 de octubre de 2026).

Errores y límites

Una duración fuera de 5, 10 y 15 devuelve HTTP 400 model_price_error y no se crea ningún trabajo (documentación de la API de video, consultada el 29 de octubre de 2026). Envíe segundos enteros de los tres valores permitidos.

Una solicitud de creación sin Idempotency-Key devuelve 400 missing_idempotency_key; la clave puede tener hasta 255 caracteres. La misma clave con el mismo cuerpo devuelve la tarea existente con HTTP 200 y no se cobra nada nuevo, mientras que un cuerpo cambiado bajo esa clave devuelve 409 idempotency_key_reused (resumen de la API de medios, consultado el 29 de octubre de 2026).

El 29 de octubre de 2026, un POST con el User-Agent predeterminado de urllib de Python devolvió HTTP 403 con el cuerpo error code: 1010 de Cloudflare, y nuestra propia cabecera User-Agent llegó a la API. Configure un User-Agent en la solicitud de creación y en la descarga.

Los enlaces de salida duran poco: vuelva a consultar la tarea para obtener un assets[].url nuevo en lugar de guardar uno (documentación de la API de video, consultada el 29 de octubre de 2026). Los registros de tareas se conservan 24 horas después de la creación (resumen de la API de medios, consultado el 29 de octubre de 2026).

Kling 3.0 se cobra por generación y no por segundo (documentación de la API de video, consultada el 29 de octubre de 2026). Para las tarifas actuales, consulte los precios de OmniaKey.

Preguntas frecuentes

¿Qué duraciones acepta kling-3.0?

5, 10 y 15 segundos. Cualquier otro valor devuelve HTTP 400 model_price_error y no crea ningún trabajo (documentación de la API de video, consultada el 29 de octubre de 2026).

¿Cuál es la diferencia entre std y pro?

La página del modelo los llama Standard y Pro, y asigna la salida standard a 720P y la pro a 1080P (consultada el 29 de octubre de 2026). Solo ejecutamos std, así que no tenemos una diferencia medida entre los dos.

¿Los clips tienen sonido?

Cada clip lleva una pista AAC de dos canales a 44.1 kHz. Los dos primeros son muy silenciosos, con niveles medios de −50.9 dB y −54.3 dB; el clip del código suena más alto, con una media de −48.4 dB y un pico de −20.0 dB. Solo medimos el nivel y no identificamos el contenido.

¿Puedo empezar un clip desde una imagen?

La página del modelo incluye image to video con un primer fotograma y un último fotograma opcional (consultada el 29 de octubre de 2026). El primer fotograma fija la relación de aspecto, y una proporción explícita se rechaza en esa operación.

¿Cuánto tarda en generarse un clip?

En nuestras dos ejecuciones del 29 de octubre de 2026, el barco de papel terminó en 110.7 segundos y la tetera en 82.2 segundos. Ambos eran clips std de 5 segundos a 16:9.

Empiece en la página del modelo Kling 3.0 y envíe el mismo cuerpo con su propio prompt.