Come si usa l'API Kling 2.5 Turbo? Il primo video in 5 minuti

TL;DR

• Kling 2.5 Turbo è la versione rapida del modello video di Kuaishou Kling; su HiAPI ci sono due ingressi, text-to-video e image-to-video, apri la pagina del modello per provarlo online; i nuovi utenti ricevono 200 crediti alla registrazione.
• Entrambi gli ingressi costano $0,06 al secondo: 5 secondi $0,30, 10 secondi $0,60.
• Come chiamarlo: invia con POST /v1/tasks, recupera il risultato con taskId; il video finito è in output[0].url.

Cosa può fare Kling 2.5 Turbo

• 5 o 10 secondi, circa 1080p: la risoluzione segue il formato, l'output 16:9 è 1920×1080, non serve impostarla separatamente.
• Il text-to-video include l'audio: ogni video ha una traccia audio, non c'è un interruttore.
• L'image-to-video supporta l'ultimo frame: il primo frame definisce l'inizio, l'ultimo frame la fine, il modello genera il passaggio intermedio.
• L'image-to-video ha 6 formati: oltre a orizzontale, verticale e quadrato, anche 4:3, 3:4 e 21:9 widescreen.

Vertical cinematic shot of a ceramic artist in a sunlit studio. Her hands shape a small terracotta bowl on a spinning pottery wheel. The wet clay gradually rises as the wheel turns, a little water glints on the surface. The camera gently tracks upward from the bowl to her focused face. Warm morning light, linen apron, natural movement, one continuous shot, no text or logos.

Genera con questo prompt → (scegli 10 secondi, 9:16)

kling-2.5-turbo/text-to-video, 9:16, 1080×1920, 10 secondi, con traccia audio, $0,60.

Come scegliere tra i due ingressi

ID modello	Input	Formato	Audio	Adatto a
kling-2.5-turbo/text-to-video	prompt	16:9, 9:16, 1:1	traccia audio inclusa	nessun materiale, partire dal testo
kling-2.5-turbo/image-to-video	primo frame obbligatorio, ultimo frame opzionale	6 formati; 3 formati con l'ultimo frame	nessuna traccia audio	foto prodotto, fotografia, illustrazioni da animare

I due ingressi hanno lo stesso prezzo, $0,06 al secondo.

Due percorsi per iniziare

Provare nel browser (3 passi)

1. Apri la pagina del modello text-to-video o image-to-video e accedi.
2. Scrivi il prompt; per image-to-video carica prima il primo frame, poi se serve l'ultimo frame.
3. Scegli 5 secondi e il formato, poi clicca esegui.

Chiamare via API (3 passi)

1. Crea una chiave nella pagina API Key della console e inseriscila nella variabile d'ambiente HIAPI_KEY.
2. Invia con POST https://api.hiapi.ai/v1/tasks, la risposta contiene data.taskId.
3. Con GET /v1/tasks/{taskId} verifica che status sia success, poi scarica output[0].url.

curl: il primo video

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5-turbo/text-to-video",
    "input": {
      "prompt": "Hands pour glossy caramel over a stack of pancakes, steam rises, camera slowly pushes in, warm kitchen light",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

5 secondi, 16:9, $0,30. Per l'image-to-video cambia model in kling-2.5-turbo/image-to-video e aggiungi "image_urls": ["https://tuo-hosting-immagini/frame.jpg"].

Python: invio, polling, download

# pip install requests; prima esegui export HIAPI_KEY=la_tua_chiave
import os, time, uuid, requests

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

def generate(model, timeout_s=900, **inp):
    # per riprovare lo stesso task usa la stessa Idempotency-Key, evitando doppi addebiti
    r = requests.post(API, json={"model": model, "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"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

# primo frame + ultimo frame: un'auto rossa va da sinistra a destra e diventa blu (5 secondi, $0,30)
url = generate(
    "kling-2.5-turbo/image-to-video",
    prompt="A toy car moves smoothly from the left to the right and changes from red to blue. "
           "Keep the simple light grey background and beige ground. Continuous static camera shot.",
    image_urls=["https://tuo-hosting-immagini/first.png", "https://tuo-hosting-immagini/last.png"],
    duration=5, aspect_ratio="9:16",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Primo frame più ultimo frame: fermare l'inquadratura sull'immagine che vuoi

Passa due immagini in image_urls: la prima è il primo frame, la seconda è l'ultimo frame. Qui sotto il primo frame è l'auto rossa a sinistra, l'ultimo frame è l'auto blu a destra:

Primo frame	Ultimo frame

A toy car moves smoothly from the left to the right and changes from red to blue. Keep the simple light grey background and beige ground. Continuous static camera shot.

Genera con questo prompt → (carica primo e ultimo frame, scegli 5 secondi, 9:16)

kling-2.5-turbo/image-to-video, 9:16, 1080×1920, 5 secondi, primo + ultimo frame, $0,30.

L'auto va verso destra, a metà strada il colore passa dal rosso al viola e poi al blu, e infine si ferma nella posizione dell'ultimo frame, con lo sfondo invariato per tutta la durata. I risultati sono più stabili quando le due immagini sono identiche tranne che per l'elemento da cambiare. Con l'ultimo frame il formato può essere solo 16:9, 9:16 o 1:1.

Tabella dei parametri

Campo	Obbligatorio	Valori	Descrizione
prompt	sì	1–2500 caratteri	descrivi azione e inquadratura; per image-to-video non serve ridurre la scena
duration	no	5 (predefinito) / 10	fatturazione al secondo
aspect_ratio	no	text-to-video: 16:9 (predefinito) 9:16 1:1; image-to-video ha anche 4:3 3:4 21:9	con l'ultimo frame solo 16:9 9:16 1:1
image_urls	obbligatorio per image-to-video	1–2 immagini, jpeg/png/webp, max 10MB ciascuna	la 1ª è il primo frame, la 2ª l'ultimo frame; il text-to-video non accetta questo campo
negative_prompt	no	text-to-video ≤2500, image-to-video ≤2496 caratteri	contenuti che non vuoi
cfg_scale	no	0–1, predefinito 0.5	più alto, più aderente al prompt

Non esistono resolution, seed né un interruttore audio.

Errori che incontrerai

Se i parametri non sono corretti al momento dell'invio, l'API restituisce direttamente 400, senza creare il task né addebitare:

• duration: value must be one of 5, 10: la durata può essere solo 5 o 10.
• aspect_ratio: value must be one of '16:9', '9:16', '1:1': hai passato un altro formato al text-to-video, oppure hai aggiunto l'ultimo frame all'image-to-video scegliendo 4:3, 3:4 o 21:9.
• image_urls: maxItems: got 3, want 2: massimo due immagini, primo e ultimo frame.
• image_urls: missing required field "image_urls": per l'image-to-video non hai inviato il primo frame.
• cfg_scale: maximum: got 5, want 1: cfg_scale va da 0 a 1, non 1–20 come in altri modelli.
• additional properties 'seed', 'sound' not allowed: questi due campi non esistono.

Da sapere prima della messa in produzione

• Usa il callback invece del polling: aggiungi al livello superiore della richiesta (allo stesso livello di input) "callback": {"url": "https://tuo-dominio/hiapi/callback"} e deduplica per taskId.
• Salva subito: output[0].url scade dopo circa 7 giorni, salvalo nel tuo storage appena lo ricevi.
• Indica esplicitamente duration e aspect_ratio: se non li scrivi valgono 5 secondi e 16:9, e per esigenze verticali è facile dimenticarsene.
• Riprova con la chiave di idempotenza: aggiungi Idempotency-Key nell'header, con la stessa chiave viene creato un solo task.

Domande frequenti

Si può disattivare l'audio nel text-to-video?

No, non c'è un interruttore audio. Se non vuoi l'audio, rimuovi la traccia in montaggio, oppure usa l'image-to-video, che non ha traccia audio.

Cosa succede se le proporzioni del primo frame nell'image-to-video non corrispondono al formato?

Il primo frame viene ritagliato al centro secondo il formato scelto. Se scegli 9:16 per un'immagine 16:9, viene mantenuta la striscia verticale centrale: il soggetto al centro è la scelta più stabile.

Si può ottenere il 4K?

No. L'output è circa 1080p, in base al formato; il più ampio è 2200×940 in 21:9.

Come scegliere tra questo e Kling 3.0 Turbo?

Se 5 o 10 secondi bastano e vuoi il prezzo più basso, scegli Kling 2.5 Turbo; se ti servono 3–15 secondi selezionabili secondo per secondo, o vuoi scegliere tra 720p e 1080p, vedi il confronto tra Kling 2.5 Turbo e 3.0 Turbo.

Per il dettaglio dei prezzi vedi Prezzi dell'API Kling 2.5 Turbo, per altri scenari vedi Raccolta di prompt per Kling 2.5 Turbo. Se vuoi prima vedere il risultato, copia il prompt sulla ceramista qui sopra e vai alla pagina del modello per generare il primo video.