Come usare l'API di Kling 4.0: modalità, fotogrammi chiave, riferimenti, modifica ed estensione

Per usare l'API di Kling 4.0, crea una chiave API, invia un corpo JSON con l'ID modello kling-4-0 e il tuo prompt, e interroga l'attività che restituisce finché l'URL del video non è pronto. Lo stesso endpoint copre tutte e cinque le modalità: testo a video, immagine a video con fino a 10 fotogrammi, riferimenti da immagini, video e audio, modifica video ed estensione. I media che invii e un campo, omni_reference_task_type, decidono quale modalità viene eseguita.

Questa guida esamina ogni modalità con corpi di richiesta che hanno funzionato il 22 ottobre 2026, quindi mostra come ogni modalità viene addebitata e quali richieste vengono rifiutate prima di addebitare qualsiasi cosa.

Di cosa hai bisogno prima della prima richiesta?

1. Una chiave API. Crea una nella pagina chiavi API e mantienila sul tuo server. Non metterla mai nel codice del browser.
2. Crediti. Aggiungi un saldo nella pagina fatturazione. I crediti non scadono mai e le attività non riuscite non vengono addebitate.
3. L'ID modello kling-4-0.

export SEEDROUTER_API_KEY="your-key"

Come invii una richiesta di Kling 4.0?

Invia l'attività a /v1/videos/generations:

curl https://api.seedrouter.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4-0",
    "prompt": "A woman with a red umbrella walks down a neon-lit street on a rainy night, signs shimmering in the puddles, the camera tracking low beside her. No text, no logos.",
    "resolution": "720p",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

La risposta è un'attività, non un video:

{"id": "task_...", "model": "kling-4-0", "status": "processing", "created_at": 1789689600}

Ogni campo tranne model e, nella maggior parte delle modalità, prompt ha un valore predefinito:

Non c'è interruttore audio: ogni clip di Kling 4.0 ha una traccia stereo. Non ci sono nemmeno campi mode, negative_prompt o watermark. Lo schema è rigoroso, quindi un campo sconosciuto viene rifiutato con HTTP 400 prima della creazione di un'attività e un errore di digitazione non si trasforma mai in una clip a pagamento con l'impostazione ignorata silenziosamente.

Come ottieni il video?

Interroga GET /v1/tasks/{id} ogni 10–20 secondi finché status non è completed o failed. I nostri cinque test hanno richiesto tra 2 minuti 41 secondi e 4 minuti 22 secondi per clip di 3 secondi a 720p, quindi pianifica in termini di minuti, non secondi.

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}

task = requests.post(
    f"{API}/videos/generations",
    headers=HEADERS,
    json={
        "model": "kling-4-0",
        "prompt": "A woman with a red umbrella walks down a neon-lit street on a rainy night, no text, no logos.",
        "duration": 5,
    },
    timeout=60,
)
task.raise_for_status()
task_id = task.json()["id"]

while True:
    result = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=60).json()
    if result["status"] in ("completed", "failed"):
        break
    time.sleep(15)

if result["status"] == "completed":
    print(result["output"]["video_url"])
else:
    print(result["error"])

Un'attività finita si presenta così:

{
  "id": "task_...",
  "model": "kling-4-0",
  "status": "completed",
  "output": {"video_url": "https://static.seedrouter.ai/media/tasks/task_example/0.mp4"}
}

Questa è la clip che la prima richiesta su questa pagina ha prodotto, 5 secondi a 720p:

Kling 4.0, testo a video, 720p, 5 secondi, con audio stereo.

Le nostre clip a 720p sono tornate come MP4 (H.264) a 1280 × 720 con una traccia AAC stereo. Scarica il file nel tuo archivio personale: i link ospitati non sono permanenti. Un timeout di rete durante l'interrogazione non significa che la generazione non sia riuscita, quindi conserva l'ID attività e controllalo di nuovo invece di inviare una nuova attività.

In quale modalità viene eseguita una richiesta di Kling 4.0?

I media nel corpo selezionano la modalità. omni_reference_task_type la rende esplicita dove i media soli sarebbero ambigui:

Fotogrammi e media di riferimento non possono essere mescolati in una richiesta, e un video_url senza edit o extend viene rifiutato. Entrambi vengono restituiti come HTTP 400 prima di un'attività esistente.

Come fissi i fotogrammi chiave in Kling 4.0?

Invia image_with_roles, una lista di oggetti {url, role}. Esattamente un first_frame, un last_frame opzionale e fino a 8 voci keyframe, 10 immagini in totale. I fotogrammi chiave vengono usati nell'ordine in cui li elenchi, quindi l'elenco è la sequenza temporale.

{
  "model": "kling-4-0",
  "prompt": "A girl walks from the window to the door, then looks back and smiles",
  "image_with_roles": [
    {"url": "https://example.com/1.png", "role": "first_frame"},
    {"url": "https://example.com/2.png", "role": "keyframe"},
    {"url": "https://example.com/3.png", "role": "last_frame"}
  ],
  "duration": 10
}

Per solo inizio e fine, image_urls: [first, last] è più breve. Image to video è l'unica modalità in cui prompt può essere lasciato fuori; la clip assume la forma del primo fotogramma.

Come usi riferimenti di immagini, video e audio?

Aggiungi video_urls (fino a 5 clip, 30 secondi usati in totale), audio_urls (fino a 3 clip di 5–30 secondi) e immagini di riferimento, al massimo 15 file in totale. Menzionali nel prompt come @Image1, @Video1 e @Audio1, numerati da 1 in ogni elenco:

{
  "model": "kling-4-0",
  "prompt": "The woman from @Image1 walks along the deck of the sailboat from @Video1 at sunset",
  "image_with_roles": [{"url": "https://example.com/woman.png", "role": "reference_image"}],
  "video_urls": ["https://example.com/boat.mp4"],
  "aspect_ratio": "auto",
  "duration": 5
}

Le immagini di riferimento possono anche andare in image_urls, ma solo con omni_reference_task_type: "reference"; senza di esso, image_urls vengono letti come primo e ultimo fotogramma. L'audio di un video di riferimento viene sostituito per impostazione predefinita; imposta audio_setting: "origin" per mantenerlo.

Come modifichi un video con Kling 4.0?

Imposta omni_reference_task_type su edit, passa il video in video_url e descrivi il cambiamento. Fino a 10 immagini di riferimento possono andare in image_urls.

{
  "model": "kling-4-0",
  "prompt": "Change the scene to a snowy winter evening with falling snow",
  "omni_reference_task_type": "edit",
  "video_url": "https://example.com/in.mp4"
}

L'input deve durare almeno 3 secondi e vengono utilizzati solo i suoi primi 30 secondi. Lascia fuori duration e il risultato segue la durata del video di input; l'audio originale viene mantenuto a meno che non imposti audio_setting: "auto".

Come estendi un video?

Imposta omni_reference_task_type su extend, passa il video e dai duration come lunghezza della nuova parte. Kling 4.0 continua dall'ultimo fotogramma e restituisce l'originale più i nuovi secondi come un file. Nel nostro test una clip di 5,2 secondi estesa di 3 secondi è tornata lunga 8,1 secondi.

{
  "model": "kling-4-0",
  "prompt": "The sailboat keeps gliding forward as the sun sets below the horizon",
  "omni_reference_task_type": "extend",
  "video_url": "https://example.com/in.mp4",
  "duration": 3
}

Aggiungi last_frame_image per scegliere dove termina la nuova parte. L'estensione mantiene il rapporto e l'audio dell'input, quindi aspect_ratio e audio_setting vengono rifiutati.

Quanto costa una richiesta di Kling 4.0?

Kling 4.0 viene addebitato al secondo di video con una tariffa impostata dalla risoluzione. I secondi che contano dipendono dalla modalità:

L'input è la lunghezza sommata dei video di input, arrotondata ai secondi interi e limitata a 30. Viene misurato quando la richiesta viene accettata, quindi l'importo riservato è l'importo addebitato. Nel nostro test di modifica un input di 5,2 secondi e un risultato di 3 secondi hanno addebitato 3 + 6 = 9 secondi. Queste sono le tariffe attuali:

Un video la cui durata non può essere letta viene rifiutato prima di qualsiasi addebito, e un'attività che fallisce non viene addebitata.

Quali richieste vengono rifiutate prima di addebitare qualsiasi cosa?

Questi vengono restituiti come HTTP 400 alla presentazione, senza alcuna attività creata e nulla addebitato:

Un'attività che viene accettata e poi fallisce, ad esempio nella politica dei contenuti del modello, restituisce status: "failed" con un codice error e non viene addebitata. Il catalogo errori elenca i codici.

Un agente di codifica può farlo per te?

Sì. La pagina di Kling 4.0 ha un prompt pronto per Claude Code, Codex o Cursor che legge la chiave dal tuo ambiente, ti mostra la richiesta e il suo costo, attende la tua approvazione, quindi invia, interroga e scarica la clip. La stessa pagina ha un playground che invia il corpo esatto che invierebbe il tuo codice, con ogni campo raggruppato per modalità.

Domande sull'API di Kling 4.0

L'API di Kling 4.0 è gratuita?

No. Viene addebitata al secondo di video. I nuovi account di SeedRouter ricevono un piccolo credito per provarlo, non c'è abbonamento e le attività non riuscite non vengono addebitate.

Kling 4.0 Flash è nell'API?

Non ancora. Kling 4.0 Flash è un modello più leggero e separato della stessa famiglia; Kling lo elenca con clip più brevi a 720p e senza più fotogrammi chiave.^[1] L'ID modello kling-4-0 è il Kling 4.0 completo.

Come differisce Kling 4.0 da Kling 3.0 nell'API?

Kling 4.0 crea clip fino a 30 secondi, accetta fotogrammi chiave, riferimenti video e audio, e può modificare o estendere un video; il suono è sempre attivo. Kling 3.0 crea clip di 3–15 secondi, offre 4K, prompt multi-inquadratura e elementi denominati, e ha un interruttore audio. La guida API di Kling 3.0 copre i suoi campi. Kling ha annunciato 4.0 con la sua durata di 30 secondi, 10 fotogrammi chiave e audio stereo il 30 settembre 2026.^[2]

Posso annullare un'attività?

No. Una volta accettata, un'attività viene eseguita fino al completamento o al fallimento. Le attività non riuscite non vengono addebitate.

Riferimenti

1. Kling AI. Kling 4.0 video generation (panoramica delle funzioni e FAQ). Verificato l'8 ottobre 2026 su kling.ai.
2. Kling AI. Introducing Kling 4.0: Visual Realism, Creative Control, and Next-Level Storytelling. 30 settembre 2026. Verificato l'8 ottobre 2026 su kling.ai.