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

​
Procedura di richiesta

Per utilizzare l’API, è necessario prima visitare la pagina corrispondente all’API di generazione di video Kling per richiedere il servizio corrispondente. Una volta entrati nella pagina, fare clic sul pulsante “Acquire”, come mostrato nell’immagine: Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di accesso per registrarsi e accedere. Dopo aver effettuato il login o la registrazione, si verrà riportati automaticamente alla pagina corrente. Alla prima richiesta, verrà offerto un credito gratuito, che consente di utilizzare l’API senza costi.

​
Utilizzo di base

Per prima cosa, è necessario comprendere il modo di utilizzo di base, che consiste nell’inserire la parola chiave prompt, l’azione action, l’URL dell’immagine di riferimento del primo fotogramma start_image_url e il modello model, per ottenere il risultato elaborato. È necessario prima 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, è necessario 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-video-o1, i dettagli sono i seguenti:

Si può notare che 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-video-o1.
  • mode: la modalità di generazione del video, principalmente standard std e modalità rapida pro.
  • action: l’azione per il compito di generazione video, che include 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 del primo fotogramma.
  • end_image_url: opzionale durante il video da immagine, specifica il fotogramma finale.
  • aspect_ratio: rapporto di aspetto del video, opzionale, supporta 16:9, 9:16, 1:1, predefinito 16:9.
  • cfg_scale: intensità di correlazione, intervallo [0,1], maggiore è, più si adatta alla parola chiave.
  • camera_control: opzionale, controlla i parametri dell’oggetto del movimento della fotocamera, supporta preset type/simple e configurazioni come orizzontale, verticale, panoramica, inclinazione, rotazione, zoom, ecc.
  • negative_prompt: opzionale, parole chiave inverse che non si desidera appaiano, massimo 200 caratteri.
  • element_list: elenco di riferimenti principali, applicabile solo al modello kling-video-o1, il modo specifico di utilizzo di questo parametro è descritto nella documentazione ufficiale.
  • video_list: video di riferimento, ottenuto tramite URL, applicabile solo al modello kling-video-o1, il modo specifico di utilizzo di questo parametro è descritto nella documentazione ufficiale.
  • prompt: parola chiave.
  • callback_url: URL per ricevere il risultato.
Dopo aver selezionato, si può notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Try” è possibile effettuare un test, come mostrato nell’immagine sopra, e abbiamo ottenuto il seguente risultato: 
{
  "success": true,
  "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4",
  "duration": "5.1",
  "state": "succeed",
  "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0"
}
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 del video generato dal compito di generazione video attuale.
  • duration, la durata del video generato dal compito di generazione video attuale.
  • state, lo stato del compito di generazione video attuale.
Si può notare 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 si desidera generare il codice di integrazione corrispondente, è possibile 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-v1",
  "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."
}'

​
Funzione di video esteso

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ò notare che l’ID del video è: 
"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"
Nota: l’ID video_id qui è l’ID del video generato. Se non si sa come generare un video, è possibile fare riferimento all’uso di base descritto sopra per generare un video.
Successivamente, è necessario compilare la parola chiave da utilizzare per personalizzare la generazione del video, specificando i seguenti contenuti:
  • model：il modello per generare video, principalmente ci sono i modelli kling-v1, kling-v1-5 e kling-v1-6.
  • mode：la modalità di generazione video, principalmente ci sono due modalità: modalità standard std e modalità veloce pro.
  • duration：la durata del video per questo compito di generazione video, principalmente include 5s e 10s.
  • start_image_url：quando si sceglie il comportamento di generazione video da immagine image2video, è necessario caricare il link dell’immagine di riferimento del primo fotogramma.
  • prompt：parola chiave.
Esempio di compilazione:

Dopo aver completato la compilazione, il codice generato automaticamente è il seguente:

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ò vedere che il contenuto del risultato è coerente con quanto sopra, realizzando così la funzionalità di estensione del video.

​
Callback asincrono

Poiché il tempo di generazione dell’API Kling Videos è relativamente lungo, circa 1-2 minuti, se l’API non risponde per lungo tempo, la richiesta HTTP manterrà la connessione, causando un consumo aggiuntivo di risorse di sistema. Pertanto, questa API offre anche supporto per callback asincroni. Il flusso complessivo è: quando il client avvia la richiesta, specifica un campo callback_url aggiuntivo. Dopo che il client ha avviato 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, includendo anche il campo task_id, in modo che il risultato del compito possa essere correlato 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 può essere utilizzato 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, come 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ò vedere che nel risultato c’è un campo task_id, gli altri campi sono simili a quanto sopra, tramite questo campo è possibile realizzare l’associazione dei compiti.

​
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 failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusione

Attraverso questo documento, hai compreso come utilizzare l’API Kling Videos Generation per generare video tramite l’inserimento di parole chiave e immagini di riferimento del primo fotogramma. 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.