AIREITERUna richiesta video a Kling non corrisponde a una chiamata API universale. Il modello di generazione video di Kuaishou è disponibile sia sulla Open Platform ufficiale sia tramite aggregatori come WaveSpeedAI, KIE e fal. Credenziali, ID dei modelli, struttura delle richieste e fatturazione cambiano da un servizio all'altro. Il flusso affidabile resta invece lo stesso: inviare un job, salvarne l'ID, attendere uno stato finale e recuperare l'output senza ritentare alla cieca.
Prima scegli il canale di accesso, poi l'SDK
Kling dispone di una Open Platform ufficiale, ma nei risultati di ricerca per “Kling API” compaiono anche gateway indipendenti. La scelta non va fatta solo in base al nome del modello: contano l'accesso al fornitore, la velocità di integrazione e il controllo della fatturazione.
| Canale | Forma dell'autenticazione | Schema del job | Ideale per | Compromesso principale |
|---|---|---|---|---|
| Kling Open Platform | Usa le credenziali e lo schema indicati nella documentazione sviluppatori Kling aggiornata | Segui il flusso dei task ufficiale | Rapporto diretto con Kuaishou e accesso first-party | Onboarding, prezzi e regole di concorrenza vanno verificati nell'account ufficiale |
| WaveSpeedAI | Authorization: Bearer <key> | POST della prediction, poi GET del risultato | Un'integrazione REST lineare su molti modelli | Si applicano ID endpoint, prezzi e limiti di WaveSpeed |
| KIE | Authorization: Bearer <token> | createTask, quindi callback o query del task | Multi-shot ed elementi nominati di Kling 3.0 | La struttura dei task KIE non è intercambiabile con WaveSpeed o fal |
| fal | Authorization: Key $FAL_KEY oppure SDK fal | Invio in coda e recupero del risultato | Utenti SDK che vogliono helper per la coda e schemi specifici per modello | Gli ID endpoint e il comportamento della coda sono specifici di fal |
Per i dettagli sui prezzi in base alla risoluzione, consulta l'attuale guida ai prezzi della Kling 3 API; in questo articolo considera prezzi, moltiplicatori per l'audio, concorrenza e addebiti per task falliti come configurazioni specifiche del provider.
Il flusso della piattaforma Kling ufficiale
Usa la Open Platform quando gli acquisti richiedono un rapporto diretto con Kuaishou o ti serve la disponibilità dei modelli first-party. La documentazione ufficiale corrente distingue configurazione delle credenziali, creazione dei task, callback, regole di concorrenza e codici di errore: segui quel percorso invece di adattare il payload di un aggregatore.
- Crea o recupera la credenziale ufficiale dalla guida all'autenticazione, quindi mantieni il token lato server.
- Invia il task video asincrono documentato usando l'endpoint specifico del modello e i campi di richiesta indicati nel riferimento ufficiale.
- Aggiungi
callback_urlse vuoi ricevere aggiornamenti di stato. Gli stati documentati per il callback includonosubmitted,processing,succeedefailed; per i fallimenti salvatask_status_msg. - Applica localmente l'attuale limite di concorrenza assegnato all'account. La guida ufficiale alla concorrenza descrive il sovraccarico come HTTP
429con codice business1303, non come lavoro che Kling necessariamente accoderà per te. - Usa il riferimento ai codici di errore ufficiale per distinguere credenziali errate, parametri non validi, risorse esaurite, blocchi di policy e errori server ritentabili.
La pagina di autenticazione ufficiale è renderizzata lato client nella versione accessibile della documentazione, quindi questa guida non riporta uno snippet non verificato per generare il token. Copia il formato di credenziale aggiornato da quella pagina, senza presumere che un header di WaveSpeed, KIE o fal possa funzionare anche qui.
Il ciclo di vita ufficiale può comunque essere normalizzato senza fare ipotesi sul payload esatto:
official_credential = get_from_kling_console()
task = POST official_model_endpoint(official_credential, documented_input)
store(task.task_id)
wait_for_callback_or_query_status(task.task_id)
if status == "succeed": save_output(task_result.videos)
else: classify(http_status, business_code, task_status_msg)È uno schema del ciclo di vita, non un endpoint da copiare e incollare. Per token, percorso, campi di richiesta e struttura della risposta esatti, usa il riferimento ufficiale collegato.
Quando conviene un aggregatore
Gli aggregatori sono più rapidi per prototipi che richiedono accesso pay-as-you-go, un unico account per più modelli oppure l'SDK di un provider. In compenso, controllano chiave, schema, coda, URL dell'output e talvolta la conservazione dei file. Prima di ritentare, identifica il livello in cui si è verificato l'errore.
Il contratto Kling API che puoi davvero standardizzare
Un client pronto per la produzione dovrebbe nascondere le differenze tra provider dietro un'unica funzione interna. Indipendentemente dal canale scelto, l'applicazione deve eseguire questi passaggi:
- Validare prompt e URL dei media prima di spendere crediti.
- Inviare un task di generazione video con un ID modello specifico del provider.
- Salvare immediatamente l'ID restituito per task o prediction.
- Ricevere una callback oppure interrogare un endpoint dei risultati finché il job non raggiunge uno stato finale.
- Salvare URL dell'output, provider, modello, parametri e metadati di costo.
- Interrompere i tentativi quando il provider segnala errore, annullamento, timeout o eliminazione.
L'astrazione dovrebbe restituire un oggetto normalizzato di tua proprietà, ad esempio:
{
"provider": "wavespeed",
"job_id": "provider-job-id",
"status": "queued",
"output_url": null,
"error": null
}I parametri più portabili
| Concetto | Uso comune con Kling | Valori di esempio |
|---|---|---|
| Prompt | Descrive soggetto, azione, camera, illuminazione e atmosfera | A slow dolly toward a rain-soaked neon street |
| Durata | Seleziona la lunghezza della clip | 3, 5, 10 o 15 secondi, a seconda dell'endpoint |
| Formato | Adatta il video alla piattaforma di destinazione | 16:9, 9:16, 1:1 |
| Audio o suono | Abilita l'audio nativo dove il canale lo supporta | true / false oppure sound |
| Immagine iniziale | Anima un primo frame fornito dall'utente | URL pubblico di un'immagine |
| Immagine finale | Guida il frame conclusivo dove supportato | URL pubblico di un'immagine |
| Prompt negativo | Esclude sfocatura, distorsioni o oggetti indesiderati | Campo stringa specifico del provider |
| Prompt multi-shot | Divide un'idea più lunga in più inquadrature | Un array di oggetti prompt-durata |
| Modalità o livello | Bilancia costo di iterazione e qualità | std, pro oppure un livello specifico del provider |
I concetti sono portabili, i nomi dei campi no. generate_audio, sound e generate_audio: true possono descrivere comportamenti correlati su servizi diversi. Tratta lo schema di ogni provider come un adapter separato.
I parametri che non puoi riutilizzare tra provider
Gli ID modello sono la prima trappola. kling-3.0, kling-3.0/video, fal-ai/kling-video/v3/standard/text-to-video e kwaivgi/kling-v3.0-std/text-to-video identificano route API diverse, non valori intercambiabili.
Lo stesso vale per header di autenticazione, nomi delle callback, URL dei risultati, valori di stato dei task e regole di upload dei file. Un client che codifica uno stato di un provider, come completed, può classificare in modo errato la risposta succeeded o failed di un altro servizio.
Tre formati di richiesta reali
Questi esempi, specifici per provider, mostrano perché non esiste un unico endpoint Kling universale.
WaveSpeedAI: ID della prediction e polling del risultato
WaveSpeedAI documenta Kling 3.0 Standard text-to-video su questo endpoint:
POST https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-videoLa richiesta usa un token Bearer. L'endpoint restituisce un ID prediction, mentre il risultato si legge qui:
GET https://api.wavespeed.ai/api/v3/predictions/{prediction_id}/resultUn flusso cURL essenziale è il seguente:
export WAVESPEED_API_KEY="replace_me"
submit=$(curl --fail-with-body -s \
-X POST \
"https://api.wavespeed.ai/api/v3/kwaivgi/kling-v3.0-std/text-to-video" \
-H "Authorization: Bearer $WAVESPEED_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A cinematic sunrise over a futuristic cityscape",
"duration": 5,
"aspect_ratio": "16:9",
"cfg_scale": 0.5,
"shot_type": "customize"
}')
prediction_id=$(printf '%s' "$submit" | jq -r '.data.id // .id')
curl -s \
"https://api.wavespeed.ai/api/v3/predictions/$prediction_id/result" \
-H "Authorization: Bearer $WAVESPEED_API_KEY"La documentazione del modello WaveSpeedAI indica una durata da 3 a 15 secondi, formati 16:9, 9:16 e 1:1, e un valore predefinito di cfg_scale pari a 0.5. La tabella prezzi Standard riporta $0.42 per una clip di 5 secondi senza audio e $0.63 con audio; considera queste cifre come un'istantanea del provider, non come un prezzo Kling universale.
In produzione, interroga l'endpoint dei risultati con backoff anziché inviare richieste in un ciclo serrato. Interrompi il polling su completed, failed, cancelled, timeout o deleted, gli stati terminali documentati per questo endpoint.
KIE: createTask con callback o query del task
KIE usa un endpoint condiviso per la creazione dei task:
POST https://api.kie.ai/api/v1/jobs/createTaskL'identificatore del modello Kling 3.0 è kling-3.0/video e l'autenticazione usa un token Bearer. Un payload compatto per una singola inquadratura è questo:
{
"model": "kling-3.0/video",
"callBackUrl": "https://example.com/webhooks/kie",
"input": {
"prompt": "A paper boat moving across a sunlit stream, gentle camera push-in",
"duration": "5",
"aspect_ratio": "16:9",
"mode": "std",
"sound": false,
"multi_shots": false
}
}KIE documenta video da 3 a 15 secondi, formati di output 16:9, 9:16 e 1:1, e fino a cinque inquadrature in modalità multi-shot. Le singole voci multi-shot possono specificare da 1 a 12 secondi ciascuna. Gli elementi immagine usano da 2 a 4 URL JPG o PNG, con un massimo documentato di 10 MB per immagine; gli elementi video usano un URL MP4 o MOV fino a 50 MB.
La callback è facoltativa, ma KIE la raccomanda in produzione. Il webhook dovrebbe verificare la firma quando disponibile, confermare rapidamente la ricezione e inserire il risultato del task in una coda. Mantieni il polling della query task come percorso di recupero per le callback mancate.
KIE documenta codici di risposta distinti per gli errori più comuni, tra cui 401 per autenticazione non valida, 402 per crediti insufficienti, 422 per errori di validazione e 429 per limiti di frequenza. Registra insieme codice e messaggio: un generico “Kling failed” non basta per capire se sia sicuro ritentare.
fal: endpoint del modello e client per la coda
fal espone Kling 3.0 tramite ID endpoint specifici del modello. Per Standard text-to-video, l'ID documentato è:
fal-ai/kling-video/v3/standard/text-to-videoL'API raw usa un header Authorization: Key $FAL_KEY. Gli esempi Python e JavaScript usano il client fal compatibile con le code, in genere più semplice rispetto alla scrittura manuale del ciclo di polling.
import { fal } from "@fal-ai/client";
fal.config({ credentials: process.env.FAL_KEY });
const result = await fal.subscribe(
"fal-ai/kling-video/v3/standard/text-to-video",
{
input: {
prompt: "A paper boat moving across a sunlit stream, gentle camera push-in",
duration: 5,
aspect_ratio: "16:9",
generate_audio: false,
negative_prompt: "blur, distort, low quality",
cfg_scale: 0.5
},
logs: true
}
);
console.log(result.data.video.url);fal documenta una durata da 3 a 15 secondi, tre formati text-to-video e un intervallo cfg_scale da 0 a 1, con valore predefinito 0.5. Lo schema Standard specifica che prompt e multi_prompt sono alternativi: fornisci uno dei due, non entrambi. Il valore predefinito documentato per generate_audio è true, quindi impostalo esplicitamente se il budget o la pipeline di post-produzione presuppongono un output senza audio.
fal documenta inoltre ID distinti per image-to-video e motion-control. Non dedurre questi ID limitandoti a cambiare text-to-video in una stringa: prima controlla il riferimento aggiornato del modello.
Quote, tempi di coda e protezione dei crediti
Non esiste una singola quota Kling pubblica valida per piattaforma ufficiale, WaveSpeedAI, KIE e fal. Concorrenza, rate limit, saldo crediti, fatturazione dei task falliti e conservazione dell'output dipendono dal canale selezionato. Salva questi valori nella configurazione del provider, non come costanti chiamate KLING_LIMIT.
Un utente ha riassunto il rischio operativo con maggiore precisione di una generica raccomandazione sui retry:
“Kling addebita ogni generazione e presenta una latenza reale di coda. La prima cosa che implementerei è un limite a costi/concorrenza, altrimenti un agente che ritenta su un frame sbagliato si brucia silenziosamente i crediti durante la notte.” — @ukrroot su X
Protezione di budget e concorrenza
Implementa questi controlli prima di consentire a un agente o a un worker batch di chiamare Kling:
- Numero massimo di job in corso: Imposta un tetto specifico per provider invece di avviare un job per ogni prompt.
- Budget per job: Stima durata, livello, audio e numero di output prima dell'invio.
- Budget per i retry: Ritenta selettivamente gli errori di trasporto; non ritentare errori di validazione, autenticazione o crediti insufficienti.
- Registro dei job: Registra l'ID del job del provider prima di qualsiasi richiesta successiva, così il riavvio di un worker non invierà una generazione duplicata.
- Politica sugli stati terminali: Contrassegna come conclusi i job falliti, annullati, scaduti o eliminati, salvo indicazione esplicita del provider che consenta un nuovo invio sicuro.
- Allarme crediti: Ferma la coda quando il saldo o la spesa prevista supera una soglia.
- Sicurezza di chiavi e output: Mantieni le chiavi lato server, ruota subito quelle esposte e copia i video completati in uno storage durevole.
Un test Standard di cinque secondi può costare poco rispetto a un job Pro di 15 secondi o con audio abilitato, ma il significato di “poco” dipende dal provider. Consulta la pagina live del modello prima di scegliere un livello predefinito.
Cosa misurare prima della produzione
Traccia questi campi per ogni richiesta:
| Metrica | Perché conta |
|---|---|
| Attesa in coda | Distingue il backlog del provider dal tempo di inferenza del modello |
| Tempo di inferenza | Aiuta a impostare timeout client realistici |
| Stato finale | Mostra tassi di fallimento e annullamento |
| Stato HTTP | Distingue 401, 402, 422, 429 ed errori server |
| Costo effettivo | Include retry, audio e job abbandonati |
| Conservazione dell'output | Indica quando devi copiare il video nel tuo storage |
| Numero di job in corso | Mostra se ti stai avvicinando a un limite del provider |
Considera latenza e quote come dati specifici dell'endpoint: le fonti pubbliche non forniscono un unico SLA cross-provider.
FAQ sulla Kling API
Kling ha un'API ufficiale?
Sì. Kling mantiene un'area di documentazione per sviluppatori della Open Platform ufficiale. Il canale ufficiale e i gateway di terze parti sono servizi separati: verifica quindi credenziali, quote e prezzi aggiornati nella documentazione Kling Open Platform.
Esiste un endpoint Kling API universale?
No. La piattaforma ufficiale, WaveSpeedAI, KIE e fal usano percorsi endpoint, ID modello, header di autenticazione e strutture delle risposte differenti. Costruisci un adapter per provider invece di assumere che kling-3.0 sia valido ovunque.
Meglio polling o webhook?
In produzione usa callback o webhook se il provider li supporta, ma conserva il polling per i test locali e il recupero delle callback mancate. Aggiungi backoff esponenziale, un limite totale di attesa e idempotenza, così una callback tardiva non potrà creare un record duplicato.
Quali durate e formati sono supportati?
Diverse documentazioni correnti degli aggregatori per Kling 3.0 indicano clip da 3 a 15 secondi e formati 16:9, 9:16 e 1:1. I singoli endpoint possono differire: verifica quindi la pagina del modello selezionato invece di trattare questi valori come un contratto universale first-party.
L'audio modifica il costo?
Spesso sì. WaveSpeedAI documenta un moltiplicatore audio di 1.5× per il proprio endpoint Kling 3.0 Standard, mentre fal e KIE espongono audio o sound come parametri della richiesta. Controlla la pagina di fatturazione live dell'endpoint scelto e imposta il flag in modo esplicito.
Perché un retry ha generato addebiti aggiuntivi?
Un retry può creare una seconda generazione anche se il primo job è ancora in coda. Salva l'ID del job, applica un limite di concorrenza, ritenta solo gli errori transitori e riconcilia la fatturazione del provider prima di reinviare una richiesta ambigua.
Per il primo test simile alla produzione, esegui un solo job Standard silenzioso di 5 secondi, registra l'intero ciclo di vita e aggiungi Pro, audio, multi-shot o concorrenza soltanto dopo aver gestito correttamente i worker duplicati.