In breve Si può accedere ai modelli video Kling supportati tramite CometAPI con un account CometAPI e una chiave API, invece di completare un onboarding separato per sviluppatori Kling. L’attuale percorso text-to-video è POST /kling/v1/videos/text2video. Restituisce un ID attività, che il backend interroga finché l’attività non raggiunge succeed o failed. La disponibilità dei modelli, i parametri, i prezzi e l’idoneità degli account possono cambiare; verificare il catalogo modelli live e la documentazione dell’API prima della messa in produzione.
Risposta diretta
Il percorso pratico è il catalogo dei modelli Kling di CometAPI. Se il modello Kling di cui hai bisogno è disponibile per il tuo account CometAPI, il tuo server può autenticarsi con una chiave API CometAPI e chiamare l’endpoint corrispondente compatibile con Kling. Con questo percorso, una domanda di accesso API separata presso Kling non fa parte dei passaggi di integrazione.
Questa distinzione è importante per i team che già usano CometAPI per altri modelli. L’applicazione mantiene un unico punto di gestione delle credenziali e un’unica relazione con il provider, aggiungendo al contempo un workflow video Kling. Il tuo codice deve comunque usare lo schema di richiesta specifico per i video Kling e il ciclo di vita asincrono dei task; “una sola chiave API” non significa che tutti i provider condividano un corpo di richiesta identico.
Questo articolo si concentra sul text-to-video perché è l’integrazione utile più piccola. CometAPI documenta anche image-to-video e altri workflow Kling, ma ciascuno ha il proprio endpoint e vincoli sui parametri. Inizia con un percorso verificato, quindi aggiungi funzionalità solo dopo aver controllato la documentazione corrente.
Perché questo percorso può essere utile per un team di sviluppo
Il vantaggio immediato è operativo, non “magico”. Un team che già usa CometAPI può aggiungere un workflow Kling disponibile senza creare un’altra integrazione diretta con il provider, distribuire un’altra credenziale o costruire un percorso separato di gestione account. Questo può ridurre il numero di segreti, rapporti di fatturazione e configurazioni client specifiche del provider che la tua piattaforma deve mantenere.
Il secondo vantaggio è architetturale. La tua applicazione può esporre un piccolo contratto interno di generazione video—prompt, workflow, modello, opzioni e stato del job—mentre un adapter verso il provider traduce quel contratto nella richiesta Kling documentata. Se in seguito il team valuta un altro modello video, il modello di job rivolto al prodotto può rimanere stabile anche se percorsi, parametri e metadati di output differiscono.
Il limite è altrettanto importante: un livello di accesso consolidato non rende i modelli sottostanti intercambiabili. Comportamento del prompt, media accettati, latenza, prezzi, policy di sicurezza e schemi dei risultati possono variare. Mantieni visibili tali differenze in configurazione e test anziché nasconderle dietro ipotesi non supportate.
Cosa cambia con questo percorso di accesso—e cosa no
Cosa cambia. Crei e gestisci una chiave CometAPI, invii richieste all’API di CometAPI compatibile con Kling e tracci l’utilizzo dal lato CometAPI. Questo rimuove un passaggio di onboarding diretto separato presso Kling per questo particolare percorso di accesso.
Cosa non cambia. Kling rimane la famiglia di modelli sottostante. Parametri specifici del provider, comportamento di generazione, regole di uso accettabile, disponibilità del modello e caratteristiche dell’output restano rilevanti. La documentazione di CometAPI nota anche che i campi di richiesta e risposta dei provider possono differire, quindi considera il riferimento dell’endpoint live come il contratto per la tua implementazione.
Cosa verificare prima di impegnarsi. Conferma che il tuo account possa accedere all’ID modello richiesto, rivedi il prezzo e i limiti di frequenza correnti ed esegui un piccolo test autenticato. Non progettare un workflow di produzione attorno a un nome di modello trovato in un vecchio post sul blog o in un esempio in cache.
Prima di iniziare
Ti servono un account CometAPI, una chiave API conservata sul tuo server e un backend in grado di gestire un job asincrono. Mantieni la chiave in una variabile d’ambiente come COMETAPI_KEY; non esporla nel codice del browser o delle app mobili.
- Apri il catalogo dei modelli Kling e conferma che il modello che intendi usare sia attualmente elencato per il tuo account.
- Esamina il riferimento corrente dell’API Kling text-to-video. Al momento della verifica, l’esempio documentato usa
kling-v3. - Crea una chiave API lato server nella console CometAPI e impostala nel tuo ambiente di runtime.
- Decidi dove il tuo servizio memorizzerà l’ID del task e il video finale. La richiesta di generazione restituisce un task, non il file video finito.
Scegliere il workflow Kling prima di progettare la richiesta
Parti dall’asset che il tuo prodotto ha già. Se l’utente ha solo un concept scritto, il text-to-video è il percorso diretto. Se l’utente ha un’immagine statica che deve rimanere l’ancora visiva, usa il percorso image-to-video documentato separatamente. Non aggiungere un campo immagine a una richiesta text-to-video assumendo che l’API deduca il workflow.
| Workflow | Percorso di creazione corrente | Usalo quando |
|---|---|---|
| Da testo a video | POST /kling/v1/videos/text2video | L’input è una scena scritta o un concept di movimento e non è necessario preservare un’immagine sorgente. |
| Da immagine a video | POST /kling/v1/videos/image2video | L’input include un’immagine sorgente che dovrebbe guidare il movimento generato e l’identità visiva. |
Il riferimento corrente per image-to-video accetta un URL pubblico dell’immagine o una stringa base64 e restituisce un task asincrono. I workflow Kling più specializzati hanno le proprie pagine e vincoli di richiesta. Aggiungili uno alla volta solo quando il requisito di prodotto e la documentazione corrente giustificano l’extra adapter.
Per una prima prova in produzione, usa un solo workflow, un solo ID modello verificato, una durata breve e un piccolo set di prompt rappresentativi. Questo isola l’accesso all’account e l’orchestrazione dei task dalla valutazione soggettiva dell’output. Una volta che la pipeline è affidabile, confronta modalità o modelli con un set di valutazione fisso invece di cambiare più variabili nello stesso test.
Esegui la tua prima richiesta Kling text-to-video
L’endpoint corrente text-to-video accetta JSON e autenticazione Bearer. Inizia con un prompt breve e la durata minima supportata. La richiesta seguente usa solo i campi mostrati nel riferimento CometAPI corrente:
curl https://api.cometapi.com/kling/v1/videos/text2video \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A small ceramic cup on a wooden table, steam rising in soft morning light",
"model_name": "kling-v3",
"mode": "std",
"duration": "5",
"sound": "off"
}'
Un invio riuscito restituisce un oggetto contenente data.task_id e uno stato del task. Salva quell’ID del task nel record di job della tua applicazione. Non mantenere aperta la connessione HTTP mentre il video viene generato.
| Campo | Valori documentati | Nota di implementazione |
|---|---|---|
| model_name | L’enum corrente include kling-v3 e track precedenti | Conferma l’enum live e la disponibilità per l’account prima del deployment. |
| duration | 5 o 10 | Inizia con 5 secondi per convalidare il workflow. |
| aspect_ratio | 16:9, 9:16, 1:1 | Omettilo solo se il default documentato si adatta alla tua superficie di delivery. |
| mode | std o pro | Il riferimento descrive pro come qualità superiore e costo maggiore. |
| sound | on o off | Si applica solo ai track di modello che supportano audio generato. |
Gestire in modo sicuro l’attività asincrona
La generazione Kling è asincrona. Per il text-to-video, interroga GET /kling/v1/videos/text2video/{task_id}. Il riferimento ai task di CometAPI indica che una risposta può restituire il task direttamente o all’interno di un contenitore data, quindi l’esempio normalizza entrambe le forme. Tratta inoltre ogni stato non terminale come “continua ad attendere”, invece di assumere un elenco fisso di stati intermedi.
import os
import time
import requests
API_KEY = os.environ["COMETAPI_KEY"]
BASE_URL = "https://api.cometapi.com/kling/v1/videos/text2video"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(prompt: str) -> str:
response = requests.post(
BASE_URL,
headers=HEADERS,
json={
"prompt": prompt,
"model_name": "kling-v3",
"mode": "std",
"duration": "5",
"sound": "off",
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
return payload["data"]["task_id"]
def wait_for_video(task_id: str, timeout_seconds: int = 600) -> str:
deadline = time.monotonic() + timeout_seconds
poll_url = f"{BASE_URL}/{task_id}"
while time.monotonic() < deadline:
response = requests.get(poll_url, headers=HEADERS, timeout=30)
response.raise_for_status()
payload = response.json()
task = payload.get("data") or payload
status = task.get("task_status")
if status == "succeed":
videos = task.get("task_result", {}).get("videos", [])
if not videos or not videos[0].get("url"):
raise RuntimeError("Task succeeded without a video URL")
return videos[0]["url"]
if status == "failed":
detail = task.get("task_status_msg") or task.get("task_result")
raise RuntimeError(f"Kling task failed: {detail}")
time.sleep(10)
raise TimeoutError(f"Kling task {task_id} exceeded {timeout_seconds}s")
task_id = submit_video(
"A small ceramic cup on a wooden table, steam rising in soft morning light"
)
video_url = wait_for_video(task_id)
print(video_url)
La stringa di successo terminale è succeed, non succeeded. Quando un task si completa, copia l’asset generato in uno storage sotto il tuo controllo se il tuo prodotto richiede la conservazione. Gli URL di consegna del provider non dovrebbero essere trattati come storage permanente dell’applicazione.
Per carichi maggiori, usa una coda o un worker invece di effettuare polling all’interno di una richiesta web. CometAPI documenta anche gli URL di callback per i task Kling. Se adotti i webhook, autentica e deduplica gli eventi di callback e mantieni un fallback a polling per le consegne mancate.
Progettare il ciclo di vita del job dell’applicazione prima di scalare
Tratta il task del provider come una parte del tuo record di job. Memorizza un ID job dell’applicazione, il workflow, il modello richiesto, l’ID task del provider, l’URL di query, lo stato corrente, l’ora di invio, l’ora dell’ultimo polling e la posizione dell’output. Questo fornisce ai team di supporto e operations contesto sufficiente per indagare su una generazione fallita o lenta senza cercare nei log grezzi delle richieste.
Non ritentare la richiesta di creazione solo perché il client non ha ricevuto una risposta. Il provider potrebbe aver già creato un task. Conserva il job locale prima dell’invio, salva immediatamente l’ID del task restituito e separa i retry di creazione dai retry di interrogazione dello stato. Il riferimento text-to-video corrente documenta anche external_task_id per il tracciamento; conferma il comportamento live prima di farne affidamento come meccanismo di deduplicazione.
const TERMINAL = new Set(["succeed", "failed"]);
function normalizeKlingTask(payload) {
const task = payload?.data ?? payload;
if (!task?.task_id || !task?.task_status) {
throw new Error("Kling response is missing task identity or status");
}
return task;
}
async function refreshVideoJob(job, apiKey) {
const response = await fetch(job.queryUrl, {
headers: { Authorization: `Bearer ${apiKey}` },
});
if (!response.ok) {
throw new Error(`Task query failed with HTTP ${response.status}`);
}
const task = normalizeKlingTask(await response.json());
const outputUrl = task.task_result?.videos?.[0]?.url ?? null;
return {
...job,
providerTaskId: task.task_id,
providerStatus: task.task_status,
terminal: TERMINAL.has(task.task_status),
outputUrl,
failureDetail: task.task_status_msg ?? null,
checkedAt: new Date().toISOString(),
};
}
Questo esempio deliberatamente non traduce ogni possibile stato intermedio del provider in una promessa di prodotto. Il tuo worker mantiene attivi i task non terminali, gestisce esplicitamente succeed e failed e registra lo stato grezzo del provider per il debug. Aggiungi un timeout applicativo separato affinché un task bloccato non rimanga aperto indefinitamente.
Usa il polling come base perché l’ID del task rimane interrogabile. Quando l’endpoint selezionato supporta callback_url, un webhook può ridurre le richieste ripetute di stato, ma non dovrebbe diventare l’unico meccanismo di recupero. La guida ufficiale a polling e webhook nota che i payload di callback possono essere specifici del provider. Conserva l’evento grezzo, rendi l’elaborazione idempotente per ID task, restituisci rapidamente una risposta HTTP di successo e riconcilia lo stato terminale tramite polling.
Checklist di produzione per i team di sviluppo
- Convalida il modello a runtime. Controlla il catalogo corrente e segnala chiaramente quando un modello richiesto non è disponibile. Non sostituire silenziosamente un altro modello se il comportamento dell’output è importante.
- Separa invio e recupero. Memorizza l’ID del task CometAPI, il tuo ID job, il modello selezionato e i timestamp in modo che i retry non creino lavoro duplicato.
- Limita il polling. Usa un timeout, backoff esponenziale o un intervallo fisso ragionevole, e un numero massimo di retry. Rivedi le linee guida su rate limit e concorrenza di CometAPI prima di aumentare il parallelismo.
- Classifica gli errori. Non ritentare parametri non validi o errori di autenticazione. Applica backoff a errori di rate limit e di piattaforma ritentabili, seguendo la guida corrente su codici di errore e strategia di retry.
- Proteggi credenziali e input. Tieni le chiavi API lato server, evita di loggare segreti e conferma che gli utenti abbiano i diritti su prompt, immagini o altri asset sorgente inviati.
- Misura l’intero job. Traccia successo dell’invio, tempo in coda, tempo di generazione, tasso di fallimento terminale, tasso di timeout, successo del recupero dell’output e costo per modello e modalità.
- Conserva gli output deliberatamente. Scarica gli asset completati nel tuo storage controllato quando il prodotto richiede accesso durevole, quindi applica la tua policy di conservazione e cancellazione.
FAQ pratiche
Ho bisogno di un account sviluppatore Kling separato per questo percorso?
Nessun passaggio di onboarding separato presso Kling appare nel flusso di integrazione CometAPI. Usi un account CometAPI e una chiave API. L’accesso dipende comunque dal fatto che il modello sia disponibile per il tuo account CometAPI e la tua regione, quindi confermalo prima di impegnarti in produzione.
L’API Kling è pienamente compatibile con OpenAI?
Non per il workflow video mostrato qui. Usa percorsi specifici di Kling come /kling/v1/videos/text2video e campi specifici di Kling. Puoi gestire la credenziale tramite CometAPI, ma il tuo adapter dovrebbe preservare lo schema specifico del provider.
Quale ID modello Kling dovrei usare?
Il riferimento corrente CometAPI per il text-to-video usa kling-v3 nel primo esempio funzionante e elenca diversi track precedenti. Usa un ID modello dall’enum dell’endpoint live e verifica che sia abilitato per il tuo account. Non dare per scontato che il modello più recente sia disponibile ovunque.
Perché la prima risposta non contiene un video?
La generazione del video è un task asincrono. La risposta iniziale restituisce un ID task. Effettua polling del percorso di query corrispondente finché task_status non diventa succeed o failed, quindi leggi i metadati del risultato.
Dovrei effettuare polling o usare un URL di callback?
Il polling è più semplice per una prima integrazione. I callback riducono le richieste ripetute su larga scala ma richiedono un ricevitore autenticato, idempotente e logiche di recupero. Molti sistemi in produzione usano i callback come percorso primario e il polling come fallback.
Posso usare image-to-video tramite lo stesso endpoint?
No. CometAPI documenta image-to-video sotto un percorso separato, /kling/v1/videos/image2video. Segui lo schema di richiesta corrente di quell’endpoint invece di aggiungere un campo immagine all’esempio text-to-video.
Dovrei iniziare con la modalità standard o professionale?
Usa std per convalidare autenticazione, forma della richiesta, memorizzazione del task, polling e recupero dell’output. Il riferimento corrente descrive pro come modalità di qualità superiore e costo maggiore. Valutala con prompt rappresentativi solo dopo che il workflow di base funziona, e confronta la qualità dell’output insieme al tempo di generazione e al costo effettivo.
Come posso evitare generazioni duplicate durante i retry?
Crea un record di job dell’applicazione prima di chiamare l’API e salva immediatamente l’ID del task del provider restituito. Ritenta le interrogazioni di stato indipendentemente dalle richieste di creazione. Non presumere che ripetere lo stesso POST sia idempotente. L’endpoint attuale documenta external_task_id per il tracciamento, ma verifica le sue semantiche correnti prima di trattarlo come una garanzia di deduplicazione.
Conclusioni
Per un team di sviluppo negli Stati Uniti che desidera testare la generazione video di Kling senza completare una domanda separata per sviluppatori Kling, CometAPI offre un percorso documentato: verifica che il modello Kling richiesto sia disponibile per l’account, autenticati con una chiave CometAPI, chiama l’endpoint specifico del workflow e traccia il task asincrono fino a uno stato terminale.
Il valore ingegneristico pratico è l’accesso centralizzato e un modello di job riutilizzabile per l’applicazione—non l’assunzione che ogni provider video si comporti allo stesso modo. Mantieni un adapter snello per ciascun workflow, conserva deliberatamente l’identità del task e l’output e mantieni il polling come percorso di recupero anche quando i callback sono abilitati.
Un rollout sicuro è piccolo e misurabile: convalida un modello e un workflow, invia job brevi a basso costo, registra i tassi di successo e fallimento terminali, verifica il recupero dell’output e confronta costo e latenza effettivi con i requisiti del tuo prodotto. Espandi a image-to-video o ad altri workflow Kling solo dopo che la documentazione corrente e il tuo account di destinazione sono stati controllati.