Come si usa l'API text-to-video di Kling 3.0 Turbo? Parametri, codice ed errori

TL;DR

• Il nome del modello per il text-to-video di Kling 3.0 Turbo è kling-3.0-turbo/text-to-video, la variante rapida di Kling 3.0. Apri la pagina del modello per provarlo online.
• Fatturazione al secondo: 720p $0.13 al secondo, 1080p $0.16 al secondo. La durata può essere qualsiasi numero intero da 3 a 15 secondi; un video da 5 secondi in 720p costa $0.65.
• I parametri sono solo 4: prompt, duration, aspect_ratio, resolution. Qualsiasi campo aggiuntivo (ad esempio seed, negative_prompt) restituisce 400.

Prima un assaggio

720p, 5 secondi, 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

Genera con questo prompt → (5 secondi, 720p, 16:9)

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

Riferimento rapido dei parametri

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	Massimo 2500 caratteri	Scena, soggetto, azione, movimento di camera; le battute tra virgolette possono essere sincronizzate col labiale
duration	No	Intero 3–15, predefinito 5	Fatturazione al secondo: un secondo in più, un secondo in più di costo
aspect_ratio	No	16:9 (predefinito) / 9:16 / 1:1	Orizzontale, verticale, quadrato
resolution	No	720p (predefinito) / 1080p	Determina il prezzo al secondo

Non esiste il campo sound, ma il video finale include l'audio e non si può disattivare. Non ci sono 4K, frame finale né immagini di riferimento: per queste serve Kling 3.0 standard o Omni.

curl: il primo test riuscito

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 risposta contiene solo data.taskId. Esegui il polling di GET /v1/tasks/{taskId} ogni 5–10 secondi; quando status diventa success, scarica il video da output[0].url.

Python: invio, polling, download

# pip install requests; export HIAPI_KEY=la_tua_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):
    # Riutilizza la stessa Idempotency-Key per ritentare lo stesso invio: addebita una sola volta
    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)

# Prova verticale 3 secondi 720p per l'orientamento, $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)

Quanto costa

Durata	720p ($0.13/s)	1080p ($0.16/s)
3 secondi (minimo)	$0.39	$0.48
5 secondi	$0.65	$0.80
10 secondi	$1.30	$1.60
15 secondi (massimo)	$1.95	$2.40

Prezzi attuali di HiAPI, verificati il 18 ottobre 2026.

In caso di fallimento non viene addebitato nulla. Confronto completo in Prezzi dell'API Kling 3.0 Turbo.

Errori che incontrerai

Cosa hai inviato	Risposta
prompt mancante	400, missing required field "prompt"
Campi aggiuntivi (come 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, sono ammessi solo 16:9, 9:16, 1:1
resolution: "480p"	400, sono ammessi solo 720p, 1080p
Key errata o mancante	401, permission_denied
Saldo insufficiente	402, ricarica prima di indagare

Gli errori di parametri vengono restituiti in modo sincrono al momento dell'invio; i fallimenti di generazione emergono durante il polling con status uguale a fail, con l'errore in data.error. Bisogna gestire entrambi i casi.

Note prima del go-live

• Usa i callback invece del polling: aggiungi al livello di input "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"}; la notifica arriva una sola volta al termine del task, deduplica per taskId.
• Includi l'header Idempotency-Key: in caso di retry per timeout usa la stessa Key, così viene creato un solo task e l'addebito avviene una sola volta.
• Scarica subito il risultato: output[0].url ha una scadenza.
• Oltre 15 secondi, segmenta: passa l'ultimo frame del video precedente come primo frame a kling-3.0-turbo/image-to-video e continua la generazione.

Domande frequenti

Quanto tempo richiede un video?

Nell'ordine dei minuti: più lunga la durata e più alta la risoluzione, più tempo serve. Si consiglia un limite di polling di 10–15 minuti, oppure usa direttamente i callback.

Sono supportati i negative prompt?

No. Scrivi direttamente nel prompt ciò che vuoi evitare, ad esempio «no text overlays, no watermarks».

Turbo o Kling 3.0 standard: quale scegliere?

Turbo è la variante veloce e include l'audio; la versione standard senza audio in 720p costa meno, $0.10 al secondo, l'audio è opzionale e può generare anche in 4K. Confronto con lo stesso prompt in Kling 3.0 Turbo vs Kling 3.0.

Copia il prompt del fiordo qui sopra e genera un test da 3 secondi per $0.39.