Istruzioni per l'integrazione dell'API di generazione di video Kling

Questo documento presenterà le istruzioni per l’integrazione dell’API di generazione di video Kling, che consente di generare video ufficiali Kling inserendo parametri personalizzati.

Procedura di richiesta

Per utilizzare l’API di generazione di video Kling, prima di tutto vai al Pannello di controllo di Ace Data Cloud per ottenere il tuo API Token, da conservare per uso futuro.

Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ogni servizio. La prima richiesta ti darà un credito gratuito, per un’esperienza senza costi; quando il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.

📘 Documentazione completa: API di generazione di video Kling →

Utilizzo di base

Iniziamo a comprendere il modo di utilizzo di base, che consiste nell’inserire la parola chiave prompt, l’azione action, l’URL dell’immagine di riferimento per il primo fotogramma start_image_url e il modello model, per ottenere il risultato elaborato. Prima di tutto, è necessario passare un campo action, il cui valore è text2video, che include principalmente tre azioni: video da testo (text2video), video da immagine (image2video), video esteso (extend). Inoltre, dobbiamo inserire il modello model, attualmente disponibili i modelli kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-o1, i dettagli specifici sono i seguenti:

Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, tra cui:

accept: il formato della risposta desiderata, qui impostato su application/json, ovvero formato JSON.
authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.

Inoltre, abbiamo impostato il corpo della richiesta, che include:

model: il modello per generare il video, principalmente kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-o1.
mode: la modalità di generazione del video, i valori opzionali sono modalità standard std, modalità veloce pro e modalità nativa 4K 4k. La modalità 4k è supportata solo da kling-v3 e kling-v3-omni, e non è compatibile con camera_control (controllo della camera).
action: l’azione per il compito di generazione video, che include principalmente tre azioni: video da testo (text2video), video da immagine (image2video), video esteso (extend).
start_image_url: quando si sceglie l’azione video da immagine image2video, è necessario caricare il link dell’immagine di riferimento per il primo fotogramma.
end_image_url: opzionale per video da immagine, specifica il fotogramma finale.
duration: durata del video, in secondi. kling-v3 e kling-v3-omni supportano durate intere da 3 a 15 secondi; kling-o1 supporta solo 5 secondi; altri modelli supportano 5 o 10 secondi.
generate_audio: se generare audio in sincrono, opzionale, valore booleano. Supporta kling-v3, kling-v3-omni e kling-v2-6 (solo modalità pro). Di default è false.
aspect_ratio: rapporto di aspetto del video, opzionale, supporta 16:9, 9:16, 1:1, di default 16:9.
cfg_scale: intensità di correlazione, intervallo [0,1], maggiore è il valore, più si adatta alla parola chiave.
camera_control: opzionale, parametri per controllare il movimento della camera, supporta preset type/simple e configurazioni come horizontal, vertical, pan, tilt, roll, zoom.
negative_prompt: opzionale, parole chiave inverse che non si desidera appaiano, massimo 200 caratteri.
image_list: elenco di immagini di riferimento Omni, applicabile ai modelli kling-o1 e kling-v3-omni, vedere la sezione “Riferimento Omni” qui sotto.
video_list: elenco di video di riferimento Omni (supporta l’editing video), applicabile ai modelli kling-o1 e kling-v3-omni, vedere la sezione “Riferimento Omni” qui sotto.
prompt: parola chiave.
callback_url: URL per ricevere il risultato.
async: opzionale, impostato su true per restituire immediatamente task_id, senza necessità di fornire callback_url, successivamente è possibile ottenere i risultati tramite l’interfaccia di query del compito corrispondente.

Dopo aver effettuato le scelte, possiamo notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Prova” è possibile effettuare un test, come mostrato nell’immagine sopra, e abbiamo ottenuto il seguente risultato:

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://platform2.cdn.acedata.cloud/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5.mp4",
  "duration": "5.041",
  "state": "succeed",
  "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5"
}

Il risultato restituito contiene diversi campi, descritti di seguito:

success, lo stato attuale del compito di generazione video.
task_id, l’ID del compito di generazione video attuale.
video_id, l’ID del video generato dal compito di generazione video attuale.
video_url, il link al video generato dal compito di generazione video attuale.
duration, la durata del video generato dal compito di generazione video attuale.
state, lo stato attuale del compito di generazione video.

Possiamo vedere che abbiamo ottenuto informazioni soddisfacenti sul video, e dobbiamo solo utilizzare l’indirizzo del link video in data per ottenere il video Kling generato. Inoltre, se desideri generare il codice di integrazione corrispondente, puoi semplicemente copiarlo, ad esempio il codice CURL è il seguente:

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v3",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

Matrice delle capacità del modello

Il supporto ai parametri varia notevolmente tra i diversi modelli. La seguente matrice è stata organizzata dalla documentazione ufficiale dei modelli video Kling, prima di effettuare una chiamata verifica se la combinazione attuale di model / mode / duration supporta le funzionalità richieste, altrimenti il sistema restituirà errori come model/mode/duration(...) is not supported with image_tail.

Modello	Modalità	`end_image_url` (fotogramma finale)	`generate_audio` (audio)	`camera_control` (controllo della camera)	Note
`kling-v1`	std / pro	✅ solo `duration=5`	❌	✅ solo `duration=5`	`extend` non supporta `negative_prompt` e `cfg_scale`
`kling-v1-6`	std	❌	❌	❌	Video multi-immagine, `extend` disponibile in tutte le modalità
`kling-v1-6`	pro	✅	❌	❌
`kling-v2-master`	—	❌	❌	❌	Modalità singola, solo `duration=5/10`
`kling-v2-1-master`	—	❌	❌	❌	Modalità singola, solo `duration=5/10`
`kling-v2-5-turbo`	std	❌	❌	❌
`kling-v2-5-turbo`	pro	✅	❌	❌
`kling-v2-6`	std	❌	❌	❌
`kling-v2-6`	pro	✅	✅	❌	Unico modello non v3 che supporta audio contemporaneamente
`kling-v3`	std / pro	✅	✅	✅	Intervallo `duration` 3–15 secondi
`kling-v3`	4k	✅	✅	❌	Modalità 4K non compatibile con il controllo della camera
`kling-v3-omni`	std / pro / 4k	✅	✅	❌
`kling-o1`	std / pro	✅	❌	❌	Solo supporta `duration=5`

Note:

mode=4k supportato solo da kling-v3 e kling-v3-omni; e in conflitto con camera_control (controllo della camera).
end_image_url può essere utilizzato solo con action=image2video insieme a start_image_url. Inviare solo end_image_url (senza start_image_url) verrà rifiutato.
kling-v3 / kling-v3-omni accettano qualsiasi intero duration da 3 a 15 secondi; kling-o1 accetta solo 5; gli altri modelli accettano solo 5 o 10.
generate_audio è impostato su false per impostazione predefinita. Solo kling-v3, kling-v3-omni e kling-v2-6 (modalità pro) supportano.

Funzionalità di estensione video

Se si desidera continuare a generare un video Kling già creato, è possibile impostare il parametro action su extend e inserire l’ID del video da continuare a generare. L’ID del video può essere ottenuto in base all’uso di base, come mostrato nell’immagine seguente:

A questo punto, si può vedere che l’ID del video è:

"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"

Nota: l’video_id qui è l’ID del video generato. Se non sai come generare un video, puoi fare riferimento all’uso di base descritto sopra.

Successivamente, dobbiamo compilare le parole chiave necessarie per personalizzare la generazione del video, specificando i seguenti contenuti:

model: modello per la generazione del video, principalmente kling-v1, kling-v1-5 e kling-v1-6.
mode: modalità di generazione del video, valori opzionali sono modalità standard std, modalità veloce pro e modalità nativa 4K 4k (solo supportata da kling-v3 e kling-v3-omni, non compatibile con il controllo della camera).
duration: durata del video per questo compito di generazione, principalmente 5s e 10s.
start_image_url: quando si sceglie l’azione di generazione video da immagine image2video, è necessario caricare il link dell’immagine di riferimento del fotogramma iniziale.
prompt: parole chiave.

Esempio di compilazione:

Una volta completato, verrà generato automaticamente il seguente codice:

Codice Python corrispondente:

import requests

url = "https://api.acedata.cloud/kling/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "model": "kling-v1",
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "duration": 10
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Cliccando su esegui, si può notare che si ottiene un risultato, come segue:

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

Si può notare che il contenuto del risultato è coerente con quanto descritto sopra, realizzando così la funzionalità di estensione del video.

Riferimento Omni (video editing / video di riferimento / riferimento multi-immagine)

kling-o1 e kling-v3-omni sono due modelli indipendenti, entrambi supportano la capacità di “riferimento universale”. Sulla base della generazione video da testo (action=text2video), è possibile fornire immagini di riferimento o video di riferimento per realizzare riferimenti multi-immagine, video di riferimento e modifiche dirette a video esistenti. Convenzione principale: il materiale di riferimento deve essere citato nel prompt nel formato <<<image_1>>>, <<<video_1>>> (numerazione a partire da 1) per i materiali corrispondenti in image_list / video_list, affinché il modello applichi questi riferimenti. Se si forniscono solo materiali senza citarli nel prompt, i materiali verranno ignorati.

Nota di sicurezza: l’attuale API non apre element_list. L’ID upstream della Kling Element Library appartiene allo spazio dei nomi dell’account del fornitore; prima di fornire un’API di gestione degli elementi con isolamento per i clienti, si consiglia di utilizzare image_list per fornire immagini di riferimento principali.

Le richieste Omni non supportano negative_prompt, cfg_scale o camera_control, e non possono utilizzare mode=4k. Quando si includono video di riferimento, generate_audio deve essere impostato su false. video_list è utilizzato per passare video di riferimento, è lo scenario più comune per questa funzionalità, i campi degli elementi dell’array sono i seguenti:

video_url: link al video di riferimento, non può essere vuoto. Requisiti: formato MP4/MOV; risoluzione 720px–2160px; durata 3–10 secondi; frame rate 24–60fps; dimensione del file ≤200MB; massimo 1 video.
refer_type: tipo di riferimento, opzionale base (predefinito, video di base da modificare, ovvero “modificare direttamente il video”, è possibile aggiungere/rimuovere/modificare elementi, cambiare composizione, cambiare stile, cambiare colore, cambiare meteo, ecc.) o feature (riferimento alle caratteristiche, riferimento al suo stile / movimento della camera / continuazione della scena successiva).
keep_original_sound: se mantenere l’audio originale del video, opzionale yes (mantieni) o no (rimuovi).

Nota: quando è presente un video di riferimento, generate_audio deve essere false. I video con refer_type=base non possono avere frame iniziali / finali specificati.

Esempio di CURL per modificare un video esistente (trasformare il video in stile anime):

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "Trasforma <<<video_1>>> in uno stile anime di livello cinematografico, mantenendo il movimento e la composizione originali",
  "video_list": [
    {
      "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4",
      "refer_type": "base",
      "keep_original_sound": "no"
    }
  ]
}'

Riferimento a più immagini (`image_list`)

image_list è utilizzato per passare immagini di riferimento (elementi / scene / stili, ecc.), i campi degli elementi dell’array sono i seguenti:

image_url: link all’immagine di riferimento, non può essere vuoto. Requisiti: formato .jpg/.jpeg/.png; dimensione del file ≤10MB; lato più corto ≥300px; rapporto di aspetto 1:2.5 ~ 2.5:1.
type: opzionale. Se non specificato, viene considerato come immagine di riferimento pura; se specificato first_frame / end_frame, viene utilizzato rispettivamente come frame iniziale / finale (equivalente a start_image_url / end_image_url).

Quando si utilizza, è necessario fare riferimento in prompt con <<<image_1>>>, <<<image_2>>>. Limiti di quantità: se non ci sono video di riferimento, le immagini di riferimento ≤ 7; se ci sono video di riferimento, le immagini di riferimento ≤ 4. Se si inviano solo frame iniziali / finali, è possibile utilizzare direttamente start_image_url / end_image_url, ma il frame finale deve essere utilizzato insieme al frame iniziale.

Nota: se si inviano contemporaneamente start_image_url / end_image_url e image_list, i frame iniziali / finali verranno posizionati prima di image_list, il che potrebbe influenzare la corrispondenza degli indici di <<<image_N>>>. Si consiglia di scegliere uno dei due: se è necessario un frame iniziale / finale, specificarlo direttamente in image_list utilizzando type, senza mescolarlo con start_image_url / end_image_url.

Esempio di CURL per generare un video con riferimento a più immagini:

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "Fai in modo che i personaggi in <<<image_1>>> si trovino nella scena di <<<image_2>>>, con illuminazione cinematografica",
  "image_list": [
    { "image_url": "https://cdn.acedata.cloud/subject.png" },
    { "image_url": "https://cdn.acedata.cloud/scene.png" }
  ]
}'

Callback asincrona

Poiché il tempo di generazione dell’API Kling Videos è relativamente lungo, circa 1-2 minuti, se l’API non risponde per un lungo periodo, la richiesta HTTP manterrà la connessione, causando un consumo aggiuntivo di risorse di sistema, quindi questa API offre anche supporto per callback asincroni. Il flusso complessivo è: quando il client invia una richiesta, specifica un campo callback_url aggiuntivo, dopo che il client ha inviato la richiesta API, l’API restituirà immediatamente un risultato, contenente un campo task_id, che rappresenta l’ID del compito corrente. Quando il compito è completato, il risultato del video generato verrà inviato al callback_url specificato dal client in formato POST JSON, che include anche il campo task_id, in modo che il risultato del compito possa essere associato tramite l’ID. Di seguito vediamo un esempio per capire come operare concretamente. Innanzitutto, il callback Webhook è un servizio in grado di ricevere richieste HTTP, gli sviluppatori dovrebbero sostituirlo con l’URL del server HTTP che hanno costruito. Qui, per comodità di dimostrazione, utilizziamo un sito Web pubblico di esempio per Webhook https://webhook.site/, aprendo questo sito si ottiene un URL Webhook, come mostrato nell’immagine:

Copia questo URL e puoi usarlo come Webhook, l’esempio qui è https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Successivamente, possiamo impostare il campo callback_url su questo URL Webhook, riempiendo i parametri corrispondenti, il contenuto specifico è mostrato nell’immagine:

Cliccando su Esegui, si può notare che si ottiene immediatamente un risultato, come segue:

{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Dopo un momento, possiamo osservare il risultato del video generato su https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3, come mostrato nell’immagine:

Il contenuto è il seguente:

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Si può notare che nel risultato c’è un campo task_id, gli altri campi sono simili a quelli sopra, tramite questo campo è possibile realizzare l’associazione del compito.

Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:

400 token_mismatched: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
400 api_not_implemented: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.
429 too_many_requests: Troppe richieste, hai superato il limite di frequenza.
500 api_error: Errore interno del server, qualcosa è andato storto sul server.

Esempio di risposta di errore

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch fallito"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusione

Attraverso questo documento, hai appreso come utilizzare l’API di generazione video Kling tramite l’inserimento di parole chiave e un’immagine di riferimento per il primo fotogramma per generare video. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Proxy

Avanzato

Istruzioni per l'integrazione dell'API di generazione di video Kling

Procedura di richiesta

Utilizzo di base

Matrice delle capacità del modello

Funzionalità di estensione video

Riferimento Omni (video editing / video di riferimento / riferimento multi-immagine)

Riferimento a più immagini (`image_list`)

Callback asincrona

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Procedura di richiesta

​Utilizzo di base

​Matrice delle capacità del modello

​Funzionalità di estensione video

​Riferimento Omni (video editing / video di riferimento / riferimento multi-immagine)

​Video di riferimento e editing video (video_list)

​Riferimento a più immagini (image_list)

​Callback asincrona

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Procedura di richiesta

Utilizzo di base

Matrice delle capacità del modello

Funzionalità di estensione video

Riferimento Omni (video editing / video di riferimento / riferimento multi-immagine)

Video di riferimento e editing video (`video_list`)

Riferimento a più immagini (`image_list`)

Callback asincrona

Gestione degli errori

Esempio di risposta di errore

Conclusione