Istruzioni di integrazione dell'API Kling Videos Generation

Questo articolo introdurrà un metodo di integrazione dell’API Kling Videos Generation, che consente di generare video ufficiali Kling inserendo parametri personalizzati.

Procedura di richiesta

Per utilizzare l’API Kling Videos Generation, per prima cosa vai alla console Ace Data Cloud per ottenere il tuo API Token, da conservare come riserva.

Se non hai ancora effettuato l’accesso o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso per invitarti a registrarti e ad accedere; al termine tornerai automaticamente alla pagina corrente. Un solo API Token può chiamare tutti i servizi della piattaforma, senza necessità di richiederne uno separatamente per ogni servizio. La prima richiesta offre crediti gratuiti, per una prova gratuita; quando i crediti non sono sufficienti, puoi ricaricare il saldo universale nella console.

📘 Documentazione completa: Kling Videos Generation API →

Utilizzo di base

Per prima cosa, vediamo il metodo di utilizzo di base: inserendo il prompt prompt, l’azione di generazione action, l’immagine di riferimento del primo fotogramma start_image_url e il modello model, è possibile ottenere il risultato elaborato. Per prima cosa è necessario passare semplicemente un campo action, il cui valore è text2video; esso include principalmente tre azioni: testo in video (text2video), immagine in video (image2video), estensione video (extend). Poi è necessario inserire anche il modello model; attualmente i modelli principali sono 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 cui dettagli sono i seguenti:

Qui possiamo vedere che abbiamo impostato i Request Headers, inclusi:

accept: il formato della risposta che si desidera ricevere; qui viene compilato con application/json, ovvero il formato JSON.
authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dal menu a discesa dopo la richiesta.

Inoltre, abbiamo impostato il Request Body, incluso:

model: il modello per generare il video; i principali sono 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.
mode: la modalità di generazione del video; i valori opzionali sono la modalità standard std, la modalità ultra rapida pro e la modalità nativa 4K 4k. Tra queste, 4k supporta solo kling-v3 e kling-v3-omni, ed è incompatibile con camera_control (controllo del movimento della camera).
action: l’azione di questa attività di generazione video; include principalmente tre azioni: testo in video (text2video), immagine in video (image2video), estensione video (extend).
start_image_url: quando si seleziona l’azione immagine in video image2video, è obbligatorio il link dell’immagine di riferimento del primo fotogramma da caricare.
end_image_url: opzionale per immagine in video, 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; gli altri modelli supportano 5 o 10 secondi.
generate_audio: se generare simultaneamente l’audio, opzionale, valore booleano. Supportato da kling-v3, kling-v3-omni e kling-v2-6 (solo modalità pro). Il valore predefinito è false.
aspect_ratio: rapporto d’aspetto del video, opzionale, supporta 16:9, 9:16, 1:1, valore predefinito 16:9.
cfg_scale: intensità della correlazione, intervallo [0,1]; maggiore è il valore, più il risultato aderisce al prompt.
camera_control: opzionale, parametro oggetto per controllare il movimento della camera, supporta preimpostazioni type/simple e configurazioni come horizontal, vertical, pan, tilt, roll, zoom.
negative_prompt: opzionale, prompt negativo delle cose che non si desidera appaiano, fino a 200 caratteri.
image_list: elenco di immagini di riferimento Omni, applicabile ai modelli kling-o1 e kling-v3-omni; per l’utilizzo, vedere più avanti «Riferimento universale Omni».
video_list: elenco di video di riferimento Omni (supporta l’editing video), applicabile ai modelli kling-o1 e kling-v3-omni; per l’utilizzo, vedere più avanti «Riferimento universale Omni».
prompt: prompt.
callback_url: l’URL per il risultato di callback.
async: opzionale; se impostato su true, l’interfaccia restituisce immediatamente task_id, senza necessità di fornire callback_url; successivamente il risultato viene ottenuto tramite polling attraverso la corrispondente interfaccia di interrogazione delle attività.

Dopo la selezione, è possibile notare che sulla destra viene generato anche il codice corrispondente, come mostrato nell’immagine:

Fai clic sul pulsante «Try» per eseguire il test; come mostrato nell’immagine sopra, qui otteniamo il seguente risultato:

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.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 dell’attività di generazione video in questo momento.
task_id, l’ID dell’attività di generazione video in questo momento.
video_id, l’ID video dell’attività di generazione video in questo momento.
video_url, il link video dell’attività di generazione video in questo momento.
duration, la durata del link video dell’attività di generazione video in questo momento.
state, lo stato dell’attività di generazione video in questo momento.

Possiamo vedere che abbiamo ottenuto informazioni video soddisfacenti; dobbiamo solo ottenere il video Kling generato in base all’indirizzo del link video in data nel risultato. Inoltre, se desideri generare il codice di integrazione corrispondente, puoi copiarlo direttamente; 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à dei modelli

I diversi modelli presentano notevoli differenze nel supporto dei parametri. La seguente matrice è organizzata sulla base della documentazione ufficiale Kling sui video models; prima della chiamata, verifica che la combinazione corrente model / mode / duration supporti le funzionalità necessarie, altrimenti verranno restituiti errori come model/mode/duration(...) is not supported with image_tail.

Modello	Modalità	`end_image_url` (primo e ultimo fotogramma)	`generate_audio` (audio di accompagnamento)	`camera_control` (movimento della videocamera)	Note
`kling-v1`	std / pro	✅ Solo `duration=5`	❌	✅ Solo `duration=5`	`extend` non supporta `negative_prompt` e `cfg_scale`
`kling-v1-6`	std	❌	❌	❌	Video da più immagini, tutte le modalità di `extend` disponibili
`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	✅	✅	❌	L’unico modello non v3 che supporta contemporaneamente l’audio di accompagnamento
`kling-v3`	std / pro	✅	✅	✅	Intervallo di `duration` 3–15 secondi
`kling-v3`	4k	✅	✅	❌	La modalità 4K non è compatibile con il movimento della videocamera
`kling-v3-omni`	std / pro / 4k	✅	✅	❌
`kling-o1`	std / pro	✅	❌	❌	Supporta solo `duration=5`

Note:

mode=4k è supportato solo da kling-v3 e kling-v3-omni; inoltre è mutuamente esclusivo con camera_control (movimento della videocamera).
end_image_url può essere utilizzato solo insieme a start_image_url quando action=image2video. Trasmettere solo end_image_url (senza start_image_url) verrà rifiutato.
kling-v3 / kling-v3-omni accettano qualsiasi duration intera da 3 a 15 secondi; kling-o1 accetta solo 5; gli altri modelli accettano solo 5 o 10.
generate_audio è false per impostazione predefinita. Solo kling-v3, kling-v3-omni e kling-v2-6 (modalità pro) lo supportano.

Funzionalità di estensione video

Se si desidera continuare a generare un video Kling già generato, è possibile impostare il parametro action su extend e inserire l’ID del video che deve continuare a essere generato. L’ottenimento dell’ID del video avviene in base all’utilizzo di base, come mostrato nell’immagine seguente:

A questo punto è possibile vedere che l’ID del video è:

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

Nota, qui il video_id nel video è l’ID del video dopo la generazione. Se non sai come generare un video, puoi fare riferimento all’utilizzo di base sopra riportato per generare un video.

Successivamente dobbiamo necessariamente compilare il prompt che deve essere esteso nel passaggio successivo per personalizzare la generazione del video, ed è possibile specificare il seguente contenuto:

model: il modello per generare il video, principalmente i modelli kling-v1, kling-v1-5 e kling-v1-6.
mode: la modalità di generazione del video, i valori opzionali sono la modalità standard std, la modalità veloce pro e la modalità 4K nativa 4k (supportata solo da kling-v3 e kling-v3-omni, incompatibile con il controllo del movimento della videocamera).
duration: la durata del video per questa attività di generazione video, principalmente 5s e 10s.
start_image_url: quando si seleziona il comportamento di generazione video da immagine image2video, è necessario il link dell’immagine di riferimento del primo fotogramma da caricare.
prompt: prompt.

L’esempio di compilazione è il seguente:

Dopo aver completato la compilazione, il codice viene generato automaticamente come segue:

Il 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)

Facendo clic su esegui, è possibile vedere che si ottiene un risultato, come segue:

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

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

Riferimento Omni universale (editing video / 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 inoltre trasmettere immagini di riferimento o video di riferimento, realizzando il riferimento multi-immagine, il video di riferimento e l’editing diretto di video esistenti. Convenzione fondamentale: i materiali di riferimento devono essere citati nel prompt nella forma <<<image_1>>>, <<<video_1>>> (la numerazione inizia da 1) per fare riferimento al materiale nella posizione corrispondente di image_list / video_list, affinché il modello applichi questi riferimenti. Se vengono trasmessi solo i materiali senza citarli nel prompt, i materiali verranno ignorati.

Nota di sicurezza: l’API attuale non apre element_list. Gli ID della Kling Element Library non sono isolati per tenant; prima di fornire una Element Management API con isolamento per tenant, utilizzare image_list per trasmettere le immagini di riferimento del soggetto.

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

video_url: link del video di riferimento, non può essere vuoto. Massimo 1 video MP4/MOV, dimensione file ≤200MB, frame rate 24–60fps. kling-o1 richiede una durata di 3–10 secondi e larghezza e altezza rispettivamente di 700–2160px; kling-v3-omni richiede una durata di 3–15.5 secondi, larghezza e altezza rispettivamente di 700–4553px, pixel totali ≤8,294,400, rapporto d’aspetto 0.4–2.
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, stile, colore, condizioni meteo ecc.) o feature (riferimento di caratteristiche, fa riferimento al suo stile / movimento di camera / continuazione della ripresa 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. Per un video con refer_type=base non è possibile specificare ulteriormente il primo fotogramma / l’ultimo fotogramma.

Di seguito è riportato un esempio 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": "把 <<<video_1>>> 改成电影级动漫风格，保留原有的运动和构图",
  "video_list": [
    {
      "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4",
      "refer_type": "base",
      "keep_original_sound": "no"
    }
  ]
}'

Riferimento multi-immagine (`image_list`)

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

image_url: link dell’immagine di riferimento, non può essere vuoto. Requisiti: formato .jpg/.jpeg/.png; dimensione file ≤10MB; lato più corto ≥300px; rapporto d’aspetto 1:2.5 ~ 2.5:1.
type: opzionale. Se non viene passato, viene usato come pura immagine di riferimento; se viene passato first_frame / end_frame, viene usato rispettivamente come primo fotogramma / ultimo fotogramma (equivalente a start_image_url / end_image_url).

Durante l’uso, è necessario fare riferimento nel prompt tramite <<<image_1>>>, <<<image_2>>>. Limite di quantità: quando non esiste un video di riferimento, immagini di riferimento ≤ 7; quando esiste un video di riferimento, immagini di riferimento ≤ 4. Quando si passa solo il primo / ultimo fotogramma, è anche possibile usare direttamente start_image_url / end_image_url, ma l’ultimo fotogramma deve essere usato insieme al primo fotogramma.

Nota: se vengono passati contemporaneamente start_image_url / end_image_url e image_list, il primo / ultimo fotogramma verranno posizionati prima di image_list, il che potrebbe influire sulla corrispondenza dei numeri di sequenza di <<<image_N>>>. Si consiglia di scegliere una delle due opzioni: quando sono necessari il primo / ultimo fotogramma, specificarli direttamente in image_list usando type, senza mescolarli con start_image_url / end_image_url.

Esempio CURL per generare un video con riferimento multi-immagine:

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": "让 <<<image_1>>> 里的人物站在 <<<image_2>>> 的场景中，电影感光线",
  "image_list": [
    { "image_url": "https://cdn.acedata.cloud/subject.png" },
    { "image_url": "https://cdn.acedata.cloud/scene.png" }
  ]
}'

Callback asincrono

Poiché il tempo di generazione della Kling Videos Generation API è relativamente lungo, circa 1-2 minuti, se l’API non risponde per molto tempo, la richiesta HTTP manterrà sempre la connessione, causando un consumo aggiuntivo di risorse di sistema; pertanto questa API fornisce anche il supporto per callback asincroni. Il flusso complessivo è il seguente: quando il client avvia una richiesta, specifica inoltre un campo callback_url; dopo che il client ha avviato la richiesta API, l’API restituirà immediatamente un risultato contenente un campo task_id, che rappresenta l’ID dell’attività corrente. Quando l’attività è completata, il risultato del video generato verrà inviato tramite POST JSON al callback_url specificato dal client, includendo anch’esso il campo task_id, in modo che i risultati dell’attività possano essere associati tramite l’ID. Di seguito vediamo come operare concretamente tramite un esempio. Innanzitutto, il callback Webhook è un servizio in grado di ricevere richieste HTTP; lo sviluppatore dovrebbe sostituirlo con l’URL del proprio server HTTP configurato. Qui, per comodità di dimostrazione, viene utilizzato un sito web di esempio Webhook pubblico https://webhook.site/; aprendo tale sito web è possibile ottenere un Webhook URL, come mostrato nella figura:

Copia questo URL e potrà essere utilizzato come Webhook; l’esempio qui è https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Successivamente, possiamo impostare il campo callback_url sul Webhook URL sopra indicato e compilare contemporaneamente i parametri corrispondenti; il contenuto specifico è mostrato nella figura:

Facendo clic su Esegui, si può notare che viene immediatamente ottenuto un risultato, come segue:

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

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

Il contenuto è il seguente:

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Si può vedere che nel risultato è presente un campo task_id; gli altri campi sono simili a quelli sopra, e tramite questo campo è possibile realizzare l’associazione delle attività.

Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice e il messaggio di errore 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 failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusione

Attraverso questo documento, avete già compreso come utilizzare Kling Videos Generation API per generare video tramite l’inserimento di prompt e immagini di riferimento del primo fotogramma. Ci auguriamo che questo documento possa aiutarvi a integrare e utilizzare meglio questa API. Per qualsiasi domanda, non esitate a contattare il nostro team di supporto tecnico.

Kling 3.0 Turbo

model="kling-v3-turbo" supporta la generazione di video da testo e la generazione di video da immagini del primo fotogramma, con una durata intera di 3–15 secondi. mode="std" produce 720p, mode="pro" produce 1080p. Questo modello dispone di audio nativo integrato e non fornisce un’opzione per disattivarlo; omettere generate_audio o impostarlo su true. Questo modello non supporta il fotogramma finale, gli oggetti di movimento della telecamera, prompt negativi indipendenti o cfg_scale. Descrivete direttamente in prompt i contenuti desiderati o da evitare.

Video multi-inquadratura

kling-v3 e kling-v3-omni supportano multi_shot=true. shot_type="intelligence" crea automaticamente lo storyboard in base a prompt; shot_type="customize" fornisce 1–6 storyboard tramite multi_prompt, ogni elemento contiene un index che aumenta consecutivamente a partire da 1, un prompt di massimo 512 caratteri e una duration intera di almeno 1 secondo. La somma delle durate di tutti gli storyboard deve essere uguale alla duration totale. Gli storyboard personalizzati non utilizzano il prompt globale. Le riprese multiple vengono fatturate in base al modello selezionato, alla qualità dell’immagine, alla configurazione audio e alla durata totale.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Istruzioni di integrazione dell'API Kling Videos Generation

Procedura di richiesta

Utilizzo di base

Matrice delle capacità dei modelli

Funzionalità di estensione video

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

Riferimento multi-immagine (`image_list`)

Callback asincrono

Gestione degli errori

Esempio di risposta di errore

Conclusione

Kling 3.0 Turbo

Video multi-inquadratura

​Procedura di richiesta

​Utilizzo di base

​Matrice delle capacità dei modelli

​Funzionalità di estensione video

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

​Video di riferimento ed editing video (video_list)

​Riferimento multi-immagine (image_list)

​Callback asincrono

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

​Kling 3.0 Turbo

​Video multi-inquadratura

Procedura di richiesta

Utilizzo di base

Matrice delle capacità dei modelli

Funzionalità di estensione video

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

Video di riferimento ed editing video (`video_list`)

Riferimento multi-immagine (`image_list`)

Callback asincrono

Gestione degli errori

Esempio di risposta di errore

Conclusione

Kling 3.0 Turbo

Video multi-inquadratura