¿Cómo se usa la API de texto a vídeo de Kling 3.0 Turbo? Parámetros, código y errores

TL;DR

• El nombre del modelo de texto a vídeo de Kling 3.0 Turbo es kling-3.0-turbo/text-to-video, la variante rápida de Kling 3.0. Abre la página del modelo para probarlo en línea.
• Facturación por segundo: 720p a $0.13 por segundo, 1080p a $0.16 por segundo. La duración puede ser cualquier entero entre 3 y 15 segundos; un vídeo de 5 segundos en 720p cuesta $0.65.
• Solo hay 4 parámetros: prompt, duration, aspect_ratio y resolution. Si envías cualquier otro campo (por ejemplo seed o negative_prompt), devuelve 400.

Primero, mira uno

720p, 5 segundos, 16:9:

aerial drone shot sweeping over a norwegian fjord waterfall, mist drifting,
camera gliding forward, smooth natural motion, stable cinematic camera
movement, consistent lighting across frames, cinematic composition, dramatic
directional lighting, rich cohesive color grade, ultra-detailed, premium
commercial finish

Generar con este prompt → (5 segundos, 720p, 16:9)

kling-3.0-turbo/text-to-video, 5 segundos.

Referencia rápida de parámetros

Campo	Obligatorio	Valores	Descripción
prompt	Sí	Máximo 2500 caracteres	Escena, sujeto, acción, movimiento de cámara; el diálogo entre comillas permite sincronización labial
duration	No	Entero 3–15, por defecto 5	Facturación por segundo: un segundo más cuesta un segundo más
aspect_ratio	No	16:9 (por defecto) / 9:16 / 1:1	Horizontal, vertical, cuadrado
resolution	No	720p (por defecto) / 1080p	Determina el precio unitario por segundo

No hay campo sound, pero el vídeo final incluye audio y no se puede desactivar. Tampoco hay 4K, fotograma final ni imagen de referencia; si necesitas eso, usa Kling 3.0 estándar u Omni.

curl: consigue tu primer resultado

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-turbo/text-to-video",
    "input": {
      "prompt": "A golden retriever surfing a turquoise wave at sunset, cinematic slow motion, water droplets frozen mid-air",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'

La respuesta solo contiene data.taskId. Consulta GET /v1/tasks/{taskId} cada 5–10 segundos; cuando status pase a success, descarga el vídeo desde output[0].url.

Python: enviar, consultar y descargar

# pip install requests; export HIAPI_KEY=tu Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(timeout_s=900, **inp):
    # Al reintentar el mismo envío, reutiliza el mismo Idempotency-Key: solo se cobra una vez
    r = requests.post(API, json={"model": "kling-3.0-turbo/text-to-video", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(8)
    raise TimeoutError(task_id)

# Prueba de orientación vertical, 3 segundos en 720p, $0.39
url = generate(
    prompt="A barista pours latte art in slow motion, close-up, warm cafe light",
    duration=3, aspect_ratio="9:16", resolution="720p",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Cuánto cuesta

Duración	720p ($0.13/segundo)	1080p ($0.16/segundo)
3 segundos (mínimo)	$0.39	$0.48
5 segundos	$0.65	$0.80
10 segundos	$1.30	$1.60
15 segundos (máximo)	$1.95	$2.40

Precio actual de HiAPI, verificado el 18 de octubre de 2026.

Los fallos no se cobran. Consulta la comparativa completa en Precios de la API de Kling 3.0 Turbo.

Errores que encontrarás

Qué enviaste	Respuesta
No enviaste prompt	400, missing required field "prompt"
Enviaste campos adicionales (p. ej., seed, negative_prompt)	400, additional properties ... not allowed
duration: 2	400, duration: minimum: got 2, want 3
duration: 99	400, duration: maximum: got 99, want 15
aspect_ratio: "4:3"	400, solo puede ser 16:9, 9:16, 1:1
resolution: "480p"	400, solo puede ser 720p, 1080p
Key incorrecta o ausente	401, permission_denied
Saldo insuficiente	402, recarga primero y luego revisa

Los errores de parámetros se devuelven de forma síncrona al enviar; los fallos de generación se detectan después al consultar y ver status como fail, con el error en data.error. Hay que manejar ambos casos.

Antes de salir a producción

• Usa callbacks en lugar de polling: añade al mismo nivel que input "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"}; solo se notifica una vez al terminar la tarea, deduplica por taskId.
• Incluye la cabecera Idempotency-Key: al reintentar por timeout, usa la misma Key; solo se crea una tarea y se cobra una vez.
• Descarga el resultado de inmediato: output[0].url tiene un periodo de validez.
• Si superas los 15 segundos, divide en segmentos: pasa el último fotograma del anterior a kling-3.0-turbo/image-to-video como primer fotograma y continúa generando.

Preguntas frecuentes

¿Cuánto tarda uno?

Se mide en minutos; cuanto más larga sea la duración y mayor la resolución, más tarda. Se recomienda un límite de polling de 10–15 minutos, o usar directamente callbacks.

¿Admite prompts negativos?

No. Lo que quieras evitar escríbelo directamente en el prompt, por ejemplo "no text overlays, no watermarks".

¿Cómo elegir entre Turbo y Kling 3.0 estándar?

Turbo es la variante rápida e incluye audio; la versión estándar sin audio en 720p cuesta $0.10 por segundo y es más barata, el audio se puede activar o desactivar y además puede generar 4K. Consulta la comparación con el mismo prompt en Kling 3.0 Turbo vs Kling 3.0.

Copia el prompt del fiordo de arriba y genera una prueba de 3 segundos por $0.39.