Kling 3.0 API: codice della richiesta da testo a video e clip reali

Un task da testo a video con Kling 3.0 è una sola POST a https://api.omniakey.com/v1/media/tasks con il modello kling-3.0, l'operazione text_to_video e due parametri obbligatori: duration (5, 10 o 15 secondi) e mode (std o pro). La risposta contiene un id del task; interrogalo fino al successo, poi scarica l'MP4. Il 29 ottobre 2026 abbiamo creato due clip da 5 secondi in modalità std a 1280×720 e misurato i file e i fotogrammi.

Cosa serve per una richiesta a Kling 3.0

Nel body della richiesta ci sono sette campi. Due, duration e mode, sono obbligatori per Kling e stabiliscono la lunghezza della clip e la fascia di qualità.

L'esempio della pagina del modello invia duration 6 e un campo resolution con 720p, e qui non vale né l'uno né l'altro: la pagina accetta solo 5, 10 o 15 secondi e dichiara che non esiste un campo resolution separato (pagina del modello, verificata il 29 ottobre 2026). Le sue domande frequenti associano l'output standard a 720P e pro a 1080P.

L'audio arriva per impostazione predefinita e la pagina non elenca alcun interruttore per toglierlo (verificata il 29 ottobre 2026). Il rapporto d'aspetto vale per il testo a video; l'immagine a video prende la forma dal primo fotogramma e rifiuta un rapporto esplicito. Queste due esecuzioni hanno usato std, 5 secondi e 16:9, mentre modalità pro, 10 e 15 secondi, 9:16 e 1:1, immagine a video e ultimo fotogramma sono rimasti fuori.

Le parole del prompt definiscono scena, azione e camera. La guida ai prompt di Kling 3.0 copre le parti di un prompt e il linguaggio di camera.

Il codice della richiesta

Un file Python invia il body, interroga il task e scarica l'MP4. Legge la chiave da OMNIAKEY_API_KEY, mette un Idempotency-Key casuale sulla richiesta di creazione e aspetta 5 secondi tra un controllo e l'altro, per un massimo di 180 tentativi. Il body porta gli stessi campi e valori delle due clip della sezione successiva: modello kling-3.0, type video, operation text_to_video, duration 5, mode std, rapporto 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"]  # link firmato di breve durata: scarica subito
    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)

Ogni controllo è una GET sul percorso del task, e il ciclo segue lo status, non progress.percent, che può restare a 0 mentre la clip viene renderizzata. Quando lo status esce da queued e processing, il codice si ferma: succeeded porta al download da assets[0].url, qualsiasi altro status lancia il messaggio di errore del task stesso. Il download va fatto subito perché il link dell'asset scade; quando succede, interroga di nuovo il task per un link nuovo. Un controllo che incontra una connessione caduta o un errore del server (5xx) viene ripetuto fino a cinque volte, con una pausa più lunga ogni volta.

Abbiamo eseguito di nuovo questo file il 29 ottobre 2026, con le stesse impostazioni. Il primo tentativo ha perso la connessione durante il polling, ed è per questo che ora il controllo ritenta. La seconda esecuzione ha restituito il task task_PNB1kPopriUyfcHsXhVWY2hBOEoSUIqM, e il suo MP4 misurava 5.04 secondi a 1280×720 con una traccia AAC stereo. Dalla creazione al download sono passati 807 secondi, contro 82.2 e 110.7 secondi delle due clip qui sotto, quindi metti in conto attese lunghe.

Due clip che abbiamo creato

Entrambe le richieste sono partite il 29 ottobre 2026 con il body elencato sopra. Il task della barca di carta è task_cbOtsBxO75cml3nOmVUu9YG3PkYXW2ja e quello della teiera è task_M2Ub1EoCaCUa1FjOZDdWDOuEOS9nRjnt. Ogni prompt è stato inviato esattamente come scritto.

Barca di carta

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.

Teiera

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.

Cosa dicono i file

Uno strumento per clip ha misurato ogni download il 29 ottobre 2026.

• Barca di carta — Dimensione: 1280×720; Frame rate: 24.0 fps; Durata: 5.04 s; Audio: AAC, 2 canali, 44.1 kHz; Livello medio: −50.9 dB; Livello massimo: −34.0 dB; Tagli: nessuno
• Teiera — Dimensione: 1280×720; Frame rate: 24.0 fps; Durata: 5.04 s; Audio: AAC, 2 canali, 44.1 kHz; Livello medio: −54.3 dB; Livello massimo: −35.9 dB; Tagli: nessuno
• Clip dal codice — Dimensione: 1280×720; Frame rate: 24.0 fps; Durata: 5.04 s; Audio: AAC, 2 canali, 44.1 kHz; Livello medio: −48.4 dB; Livello massimo: −20.0 dB; Tagli: nessuno

Le prime due clip sono molto silenziose: livelli medi di −50.9 dB e −54.3 dB, con picchi a −34.0 dB e −35.9 dB. La clip dal codice è più forte, con una media di −48.4 dB e un picco di −20.0 dB. Abbiamo misurato solo il livello; il contenuto delle tracce è rimasto fuori dalla misura. Il rilevatore di cambi di inquadratura non ha trovato tagli forti o deboli in nessuna delle tre, quindi ogni clip scorre come un'unica inquadratura.

Cosa si vede nei fotogrammi

Entrambe le clip seguono il prompt, e la teiera aggiunge un piccolo movimento suo.

Nella clip della barca di carta la barca resta vicino al centro del fotogramma per tutti i 5.04 secondi mentre la strada bagnata scorre dietro, quindi l'inquadratura si legge come una camera che segue la barca. I riflessi caldi dei lampioni restano sui ciottoli fino all'ultimo fotogramma (fotogrammi verificati il 29 ottobre 2026). Nessun taglio interrompe l'inseguimento.

Nella clip della teiera il vapore sale in volute lente e svanisce, e la luce del mattino si sposta sul tavolo di legno. La teiera finisce più grande e più verso il basso a destra rispetto all'inizio, il che si legge come un push-in con un po' di deriva laterale; il prompt chiedeva un push-in lento, e la deriva è qualcosa che il prompt non chiedeva (fotogrammi verificati il 29 ottobre 2026).

Errori e limiti

Una durata fuori da 5, 10 e 15 restituisce HTTP 400 model_price_error, e nessun job viene creato (documentazione dell'API video, verificata il 29 ottobre 2026). Invia secondi interi tra i tre valori ammessi.

Una richiesta di creazione senza Idempotency-Key restituisce 400 missing_idempotency_key; la chiave può arrivare a 255 caratteri. La stessa chiave con lo stesso body restituisce il task esistente con HTTP 200 e non viene addebitato nulla di nuovo, mentre un body cambiato con quella chiave restituisce 409 idempotency_key_reused (panoramica dell'API media, verificata il 29 ottobre 2026).

Il 29 ottobre 2026 una POST con lo User-Agent predefinito di urllib in Python ha restituito HTTP 403 con il body error code: 1010 da Cloudflare, mentre il nostro header User-Agent arrivava all'API. Imposta uno User-Agent sulla richiesta di creazione e sul download.

I link di output durano poco: interroga di nuovo il task per un assets[].url nuovo invece di salvarne uno (documentazione dell'API video, verificata il 29 ottobre 2026). I record dei task vengono conservati per 24 ore dalla creazione (panoramica dell'API media, verificata il 29 ottobre 2026).

Kling 3.0 viene addebitato per generazione, non al secondo (documentazione dell'API video, verificata il 29 ottobre 2026). Per le tariffe attuali, vedi la pagina dei prezzi OmniaKey.

Domande frequenti

Quali durate accetta kling-3.0?

5, 10 e 15 secondi. Qualsiasi altro valore restituisce HTTP 400 model_price_error e non crea alcun job (documentazione dell'API video, verificata il 29 ottobre 2026).

Che differenza c'è tra std e pro?

La pagina del modello li chiama Standard e Pro e associa l'output standard a 720P e pro a 1080P (verificata il 29 ottobre 2026). Abbiamo eseguito solo std, quindi non abbiamo una differenza misurata tra i due.

Le clip hanno l'audio?

Ogni clip porta una traccia AAC con due canali a 44.1 kHz. Le prime due sono molto silenziose, con livelli medi di −50.9 dB e −54.3 dB; la clip dal codice è più forte, con una media di −48.4 dB e un picco di −20.0 dB. Abbiamo misurato solo il livello e lasciato il contenuto non identificato.

Posso partire da un'immagine?

La pagina del modello elenca immagine a video con un primo fotogramma e un ultimo facoltativo (verificata il 29 ottobre 2026). Il primo fotogramma determina il rapporto d'aspetto, e un rapporto esplicito viene rifiutato su quell'operazione.

Quanto tempo serve per generare una clip?

Nelle nostre due esecuzioni del 29 ottobre 2026 la barca di carta è terminata in 110.7 secondi e la teiera in 82.2 secondi. Erano entrambe clip std da 5 secondi in 16:9.

Parti dalla pagina del modello Kling 3.0 e invia lo stesso body con il tuo prompt.