> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Istruzioni per l'integrazione dell'API di generazione di video Kling > Kling video generation API guide - Ace Data Cloud 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](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare per uso futuro. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 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](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [API di generazione di video Kling →](https://platform.acedata.cloud/documents/kling-videos) ## 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: ```json theme={null} { "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: ```shell theme={null} 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](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels), 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: ```python theme={null} 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: ```json theme={null} { "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 `<<>>`, `<<>>` (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 di riferimento e editing video (`video_list`) `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): ```shell theme={null} 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 <<>> 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 `<<>>`, `<<>>`. 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 `<<>>`. 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: ```shell theme={null} 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 <<>> si trovino nella scena di <<>>, 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/](https://webhook.site/), aprendo questo sito si ottiene un URL Webhook, come mostrato nell'immagine: ![](https://cdn.acedata.cloud/tbcnai.png) 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: ![](https://cdn.acedata.cloud/zv5u2q.png) Il contenuto è il seguente: ```json theme={null} { "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 ```json theme={null} { "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.