Come usare l'API Kling 3.0: chiave, richiesta, polling, fotogrammi e multi-inquadratura

Per usare l'API Kling 3.0, crea una chiave API, invia in POST un corpo JSON con l'ID modello kling-3-0 e il tuo prompt, e interroga l'attività restituita finché l'URL del video non è pronto. Un solo endpoint copre testo a video, video da primo e ultimo fotogramma, clip multi-inquadratura e riferimenti agli elementi; sono i campi del corpo a decidere quale.

Questa guida percorre ogni passaggio con codice funzionante, poi mostra fotogrammi, clip multi-inquadratura, elementi e le richieste che vengono rifiutate prima di qualsiasi addebito.

Cosa ti serve prima della prima richiesta?

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

export SEEDROUTER_API_KEY="your-key"

Come si invia una richiesta a Kling 3.0?

Invia l'attività in POST 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-3-0",
    "prompt": "A red paper boat drifting on a calm pond at sunrise, soft mist on the water, slow push-in, no text, no logos.",
    "mode": "std",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

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

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

Ogni campo tranne model e prompt ha un valore predefinito:

Lo schema è rigoroso: un campo sconosciuto viene rifiutato con HTTP 400 prima che venga creata l'attività, così un refuso non diventa mai una clip pagata con l'impostazione ignorata in silenzio.

Come si ottiene il video?

Interroga GET /v1/tasks/{id} ogni 10–20 secondi finché status non diventa completed o failed. Nei nostri test una clip std di 3 secondi è stata completata in circa due minuti e una clip pro di 5 secondi con audio in circa due minuti e mezzo.

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-3-0",
        "prompt": "A red paper boat drifting on a calm pond at sunrise, slow push-in, no text, no logos.",
        "mode": "std",
        "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à completata si presenta così:

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

std è tornata a 1280 × 720 e pro a 1920 × 1080, entrambe MP4 (H.264); con sound attivo il file contiene una traccia audio stereo. Scarica il file nel tuo storage: i link ospitati non sono permanenti. Un timeout di rete durante il polling non significa che la generazione sia fallita, quindi conserva l'ID attività e controllalo di nuovo invece di inviare una nuova attività.

Come si parte da un primo e un ultimo fotogramma?

Passa uno o due URL di immagini in image_urls. La prima immagine apre la clip; una seconda è il punto in cui termina. Senza immagini la clip nasce dal solo prompt.

{
  "model": "kling-3-0",
  "prompt": "The camera glides from the empty street to the lit shop window",
  "image_urls": ["https://example.com/start.png", "https://example.com/end.png"],
  "mode": "pro",
  "duration": 6
}

Le immagini devono essere URL HTTP(S) pubblici, in JPG o PNG. I dati in base64 vengono rifiutati; carica prima il file nel tuo storage.

Come si crea una clip multi-inquadratura?

Imposta multi_shots su true e descrivi ogni inquadratura in multi_prompt, fino a cinque inquadrature di 1–12 secondi ciascuna. Le durate delle inquadrature devono sommare 3–15 secondi, e quella somma è la durata della clip che ti viene addebitata; duration non viene usato.

{
  "model": "kling-3-0",
  "mode": "pro",
  "sound": true,
  "multi_shots": true,
  "multi_prompt": [
    {"prompt": "Wide shot of a small open kitchen, a chef tosses vegetables in a wok, flames rising, warm light.", "duration": 3},
    {"prompt": "Close-up of the wok, vegetables flipping through the flames, oil sizzling, steam drifting.", "duration": 3}
  ]
}

Questa è la clip prodotta da quella richiesta nel nostro test: un unico video di 6 secondi che stacca da un campo lungo a un primo piano:

Kling 3.0, pro (1080p), multi-inquadratura 3 + 3 secondi, con audio.

Come si mantiene coerente una persona o un prodotto?

Aggiungilo a kling_elements: un name, una breve description e 2–4 URL di immagini del soggetto, fino a tre elementi per richiesta. Cita l'elemento per nome nel prompt.

{
  "model": "kling-3-0",
  "prompt": "@hero slowly turns toward the camera in soft window light",
  "kling_elements": [
    {
      "name": "hero",
      "description": "a young woman with short black hair and a yellow raincoat",
      "element_input_urls": ["https://example.com/hero-front.png", "https://example.com/hero-side.png"]
    }
  ]
}

Quali richieste vengono rifiutate prima di qualsiasi addebito?

Queste tornano come HTTP 400 all'invio, senza creare alcuna attività e senza addebiti:

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

In cosa differisce dall'API di Kling?

L'API per sviluppatori di Kling usa nomi di campo propri, e la sua versione legacy e quella attuale differiscono tra loro.^[1][2] Se stai migrando un'integrazione, fai corrispondere i campi:

SeedRouter consegna i risultati come un'attività da interrogare; callback_url non è offerto.

Un agente di programmazione può farlo per te?

Sì. La pagina di Kling 3.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, poi invia, interroga e scarica la clip. La stessa pagina ha un Playground che invia esattamente il corpo che invierebbe il tuo codice.

Domande sull'API di Kling 3.0

Esiste un'API ufficiale di Kling 3.0?

Sì. Kling pubblica un'API per sviluppatori con chiavi proprie, fatturazione a unità e un proprio formato di richiesta.^[1][3] SeedRouter è un modo alternativo di chiamare Kling 3.0, con una sola chiave e un saldo condiviso con altri modelli.

Quanto costa l'API di Kling 3.0?

Si paga per secondo di video, in base alla modalità e all'audio attivo o meno. La guida ai prezzi dell'API Kling 3.0 calcola il costo delle clip, e la pagina del modello mostra le tariffe attuali.

Posso annullare un'attività?

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

Riferimenti

1. Kling AI. Kling 3.0: Text to Video (riferimento API, versione legacy). Consultato il 6 ottobre 2026 su kling.ai.
2. Kling AI. Kling 3.0: Image to Video (riferimento API, versione legacy). Consultato il 6 ottobre 2026 su kling.ai.
3. Kling AI. Pricing: Video (API per sviluppatori). Consultato il 6 ottobre 2026 su kling.ai.