Kling 3.0 API: guida alla migrazione, Motion Control e codice

Per passare da Kling 2.6 a Kling 3.0 non basta sostituire il nome del modello in una richiesta. Kling 3.0 è disponibile ufficialmente, ma le rotte V3, Turbo, Omni e Motion Control hanno capacità e schemi differenti. La strada più sicura è scegliere prima l'endpoint, quindi introdurre una alla volta le opzioni per audio, multi-shot e riferimenti.

Scegli l'endpoint prima di scrivere il codice

La guida ufficiale di Kling per VIDEO 3.0 presenta il modello come successore di VIDEO 2.6 e VIDEO O1: VIDEO 2.6 viene aggiornato a VIDEO 3.0, mentre VIDEO O1 passa a VIDEO 3.0 Omni. La developer API espone operazioni distinte per modello: "Kling 3.0 API" identifica quindi una famiglia di accesso, non un singolo corpo richiesta valido ovunque.

L'errore di integrazione più frequente consiste nel confondere lo schema semplificato di un provider con quello diretto di Kling: la richiesta hosted di Krea è un esempio funzionante, ma non dimostra che URL e campi coincidano con la documentazione ufficiale per sviluppatori di Kling.

Per una panoramica più ampia delle rotte disponibili, consulta la guida all'integrazione della Kling API. Qui l'attenzione è sulla migrazione a Kling 3.0 e sul comportamento degli endpoint.

Cosa cambia passando da Kling 2.6 a 3.0

La guida proprietaria ai modelli di Kling descrive l'evoluzione soprattutto in termini di controllo, continuità e regia audiovisiva, non come un semplice preset a risoluzione più alta. La tabella seguente riporta le capacità attribuite da Kling alla famiglia di modelli.

In pratica, un'integrazione 2.6 costruita intorno a un unico prompt breve può trasformarsi in 3.0 in una sequenza con una regia precisa. La guida Kling dichiara anche una migliore conservazione di personaggi, oggetti e dettagli della scena durante i movimenti di camera, ma non pubblica un benchmark indipendente sulla coerenza. Conviene quindi tenere questa affermazione distinta da ciò che l'applicazione può testare concretamente.

La più piccola integrazione asincrona funzionante con Krea

La generazione video è asincrona. L'applicazione deve inviare un job, conservare l'identificatore del task, effettuare polling o ricevere una callback e archiviare l'output completato. Non mantenere aperta la richiesta HTTP iniziale mentre il modello esegue il rendering.

L'esempio seguente usa l'endpoint Kling 3.0 documentato pubblicamente da Krea, perché richiesta e campi del job sono visibili nella guida alla Kling 3.0 API pubblicata dal provider. Sostituisci URL e nomi dei campi specifici del provider solo dopo aver verificato lo schema ufficiale Kling che intendi utilizzare.

Inviare il job di generazione

import os
import time
import requests

API_KEY = os.environ["KREA_API_KEY"]
BASE_URL = "https://api.krea.ai"

payload = {
    "prompt": (
        "A paper boat crosses a rain-filled city gutter at night, "
        "macro camera, practical street lights, realistic water movement"
    ),
    "duration": 5,
    "mode": "std",
    "aspect_ratio": "16:9",
}

response = requests.post(
    f"{BASE_URL}/generate/video/kling/kling-3.0",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
job_id = job["job_id"]
print(f"submitted {job_id}")

La risposta documentata da Krea include un job_id e uno stato iniziale come scheduled. L'esempio del provider usa un endpoint separato di lookup del job per controllarne lo stato. Prima di iniziare il polling, il database dovrebbe salvare il job ID insieme al proprio order ID.

Polling con timeout e salvataggio dell'output

TERMINAL = {"completed", "failed", "cancelled"}

for attempt in range(60):
    status_response = requests.get(
        f"{BASE_URL}/jobs/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    status_response.raise_for_status()
    job = status_response.json()
    status = job.get("status")

    if status in TERMINAL:
        break

    time.sleep(5)
else:
    raise TimeoutError(f"Kling job did not finish: {job_id}")

if job["status"] != "completed":
    raise RuntimeError(f"Kling job ended as {job['status']}: {job_id}")

video_url = job["result"]["urls"][0]
print(video_url)

Gli esempi di Krea hanno richiesto 51 secondi e 2 minuti e 3 secondi: usa quindi timeout consapevoli della coda, invece di promettere un tempo di generazione Kling fisso.

In produzione, un webhook può eliminare il polling ripetuto. Verifica il job ID rispetto a un job creato dal tuo sistema, rendi l'handler idempotente e non considerare una callback non firmata come prova d'identità sufficiente.

Aggiungi i controlli 3.0 uno alla volta

I nomi dei parametri cambiano tra API Kling diretta e provider hosted. È preferibile creare un piccolo layer di compatibilità, anziché lasciare che JSON specifici del provider si diffondano nell'applicazione.

La guida ufficiale supporta audio nativo, riferimenti a elementi, narrazioni multi-shot e cinque lingue di dialogo nominate. L'endpoint API scelto potrebbe esporre solo una parte delle funzionalità disponibili a livello di famiglia.

Un payload multi-shot personalizzato

Lo schema documentato da Krea usa beat multi_prompt temporizzati. È un modello utile per un'integrazione hosted:

{
  "multi_prompt": [
    {
      "prompt": "Wide shot: a lighthouse stands on a calm rocky coast at dusk.",
      "duration": 4
    },
    {
      "prompt": "Storm clouds arrive; waves rise and spray crosses the rocks.",
      "duration": 4
    },
    {
      "prompt": "Night rain begins as the lighthouse beam sweeps toward camera.",
      "duration": 4
    }
  ],
  "duration": 12,
  "generate_audio": true,
  "mode": "std",
  "aspect_ratio": "16:9"
}

Verifica che la durata al livello superiore corrisponda alla somma delle durate dei beat. Krea riporta un risultato di 12.04 secondi per un test di 12 secondi articolato in tre beat: non presumere quindi che la durata del file sia matematicamente esatta al millisecondo.

Ogni beat Krea è limitato a 512 caratteri e l'intera sequenza con regia ha un tetto di 15 secondi. Scrivi ogni beat come indicazione di inquadratura — soggetto, cambiamento e camera — non come una lunga descrizione della scena. Se la rotta Kling diretta usa invece la grammatica ufficiale delle inquadrature, conserva lo stesso modello temporale ma traduci il payload al confine dell'adapter.

Vincoli su audio e lingue

La guida ufficiale elenca cinese, inglese, giapponese, coreano e spagnolo tra le lingue supportate per i dialoghi, e descrive dialetti, accenti, dialoghi specifici per personaggio e scene in più lingue. Indica inoltre che l'input di dialogo non supportato viene tradotto in inglese: le applicazioni multilingue non devono quindi presumere che ogni lingua sorgente venga mantenuta intatta.

L'audio incide anche sui costi. Le tariffe pubblicate da Krea indicano std a $0.1764 al secondo senza audio e $0.2646 con audio; pro costa $0.2352 senza audio e $0.3528 con audio. La tariffa 4K indicata è $0.441 al secondo, con o senza audio. Sono prezzi Krea, non un listino universale della Kling API.

Un ciclo di iterazione sensato prevede bozze silenziose, abilitando l'audio solo per il candidato finale in std o pro.

In produzione: costi, velocità e gestione degli errori

La guida ufficiale consumer di Kling indica VIDEO 3.0 a 6 crediti al secondo per 720p senza audio nativo, 8 crediti al secondo per 1080p senza audio nativo, 9 crediti al secondo per 720p con audio e 12 crediti al secondo per 1080p con audio. Voice Control aggiunge 2 crediti al secondo. Questi valori spiegano il costo relativo all'interno di quella guida; non vanno convertiti in un prezzo in dollari per la developer API senza prima consultare la pagina dei prezzi per sviluppatori aggiornata.

La scelta non si riduce a "quale modello costa meno?". È una decisione che riguarda fatturazione e operatività:

Gestisci gli errori per categoria:

1. Riprova gli errori transitori del provider con backoff esponenziale limitato.
2. Non riprovare parametri non validi finché l'adapter non ha corretto il payload.
3. Mantieni una chiave di idempotenza lato client o un order ID, così un timeout di rete non crea un job duplicato inosservato.
4. Applica un limite rigido in dollari o crediti alla generazione batch.
5. Scarica o copia il risultato in uno storage durevole prima che l'URL temporaneo del provider scada.
6. Registra insieme variante del modello, durata, impostazione audio, livello di risoluzione e provider; per la contabilità dei costi, "Kling 3.0" da solo non basta.

Checklist per migrare da Kling 2.6 a 3.0

1. Fai l'inventario delle chiamate 2.6 attuali. Registra model ID, input immagine, frame iniziali/finali, durata, audio e comportamento delle callback.
2. Scegli la rotta della famiglia 3.0. Usa V3 per la generazione cinematografica guidata da prompt, Turbo per la rotta più rapida, Omni per il percorso multimodale in stile O1 e Motion Control per il lavoro basato su riferimenti di movimento.
3. Crea un adapter per provider. Mantieni gli schemi diretti Kling, Krea e quelli di altri servizi hosted dietro traduttori distinti.
4. Migra prima la richiesta più piccola. Testa una generazione silenziosa di cinque secondi in 16:9 prima di aggiungere audio o controlli multi-shot.
5. Aggiungi un controllo per test. Valida prima la durata, poi l'audio, quindi la direzione delle inquadrature e infine i riferimenti. In questo modo è più semplice isolare un campo errato.
6. Testa gli stati terminali. Copri i casi di successo, errore, annullamento, timeout, callback duplicata e URL di output scaduto.
7. Esegui un lancio shadow con costi misurati. Confronta un set fisso di prompt fra 2.6 e 3.0 con stessa durata e stesso livello di output, quindi decidi se il guadagno in qualità o controllo giustifica la nuova rotta.

La migrazione è completa quando l'applicazione può ripristinare il model ID precedente senza modificare la logica di business, i controlli di fatturazione o la gestione dei risultati.

FAQ sulla Kling 3.0 API

Esiste una Kling 3.0 API ufficiale?

Sì. La documentazione ufficiale per sviluppatori di Kling espone pagine API specifiche per i modelli 3.0, e la guida proprietaria di Kling descrive VIDEO 3.0 come successore di VIDEO 2.6. Lo schema esatto dell'endpoint va letto nella console per sviluppatori aggiornata, poiché alcune pagine vengono renderizzate lato client.

Motion Control è un parametro di Kling 3.0?

Non darlo per scontato. Motion Control è una funzionalità specializzata con una propria pagina modello nell'ecosistema Kling. Usa l'operazione e lo schema di input documentati dal provider scelto, anziché aggiungere un campo motion_control non verificato a una richiesta text-to-video standard.

Quanto può durare un video generato da Kling VIDEO 3.0?

La guida ufficiale ai modelli Kling indica che VIDEO 3.0 supporta output flessibili da 3 a 15 secondi. Una specifica rotta hosted o Turbo può imporre limiti più stretti, quindi verifica l'endpoint selezionato.

Kling 3.0 supporta l'audio nativo?

La guida ufficiale di VIDEO 3.0 dice di sì e descrive dialoghi specifici per personaggio, più lingue, dialetti e accenti. La possibilità di scegliere l'audio e la relativa fatturazione dipendono dallo schema dell'endpoint o del provider.

Kling 3.0 Omni coincide con Kling 3.0 standard?

No. Kling presenta VIDEO 3.0 come successore di 2.6 e VIDEO 3.0 Omni come successore di O1. Le pagine dei provider possono esporli con model ID diversi e con controlli differenti per riferimenti o voce.

Un abbonamento web Kling può pagare le chiamate API?

Considera gli abbonamenti consumer e la fatturazione della developer API come separati, finché la documentazione aggiornata dell'account non dichiara il contrario. Normalmente la rotta API richiede un proprio account sviluppatore, una chiave e una configurazione di fatturazione.

Il confine utile per la migrazione è semplice: conserva il ciclo di vita del job dell'integrazione 2.6, sostituisci l'adapter specifico del modello e verifica ogni nuovo controllo 3.0 sulla rotta che lo eroga davvero. Così eviti il tipo di errore più costoso: un'integrazione che invia correttamente le richieste ma usa in silenzio la variante, la modalità audio o il livello di fatturazione sbagliati.