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

​
Processo di richiesta

Per utilizzare l’API, è necessario prima andare alla pagina corrispondente dell’API Kling Motion Generation per richiedere il servizio corrispondente. Una volta entrati nella pagina, cliccare sul pulsante “Acquire”, come mostrato nell’immagine: Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di login 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

Iniziamo a comprendere il modo di utilizzo di base, che consiste nell’inserire la parola chiave prompt, l’immagine di riferimento image_url e il link al video di riferimento video_url, per ottenere il risultato elaborato. Inoltre, è necessario inserire il modello mode, attualmente disponibili i modelli std e pro, i dettagli sono i seguenti:

Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, che includono:
  • 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:
  • image_url: immagine di riferimento, gli elementi come persone e sfondi nel video generato sono basati su questa immagine.
  • video_url: link per ottenere il video di riferimento. I movimenti delle persone nel video generato saranno coerenti con il video di riferimento.
  • mode: modalità di generazione del video, principalmente ci sono due modalità: standard std e modalità rapida pro.
  • keep_original_sound: opzione per mantenere l’audio originale del video, valori enumerati: yes, no.
  • character_orientation: orientamento delle persone nel video generato, può essere scelto per essere coerente con l’immagine o con il video, valori enumerati: image, video.
  • prompt: parola chiave.
  • callback_url: URL per ricevere il risultato della callback.
Dopo aver effettuato le scelte, 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": "842578800134742051",
  "video_url": "https://v4-fdl.kechuangai.com/ksc2/yGPGHvUVDQEzDCs6tC0rYIbd_JwWNFaF8BEYAlw_xVcWX72xFuIUVqB_Hp5Sa7YEijI-yXqfKI92WW7bmyeCtpMjSOImlOFpQCmMUa-9iojt_ifXJnex_tvNkA0ZlJmuJLpeOfvX3j8d9oeeWgLeU3ftzBjQq1g9OC9FU92OfjRQLUTSzfWRzkhzirV32BT-BwfxgqJKsUD-WHxjqCJmOw.mp4?cacheKey=ChtzZWN1cml0eS5rbGluZy5tZXRhX2VuY3J5cHQSsAHtyCrKxB23NXn5ddMedV5Mw4pp_kOk_TRbCVA-wO9LJZuga8_KxXCzhw6bU3hS1V5PpNoSTxSkm_E80i5U1PkJ5d444cjPvoIq2VboPqCip2QbsoiVMu6CuGP7tB7fStLbezBNA4lQtHeSVPxWTE7Hy0wbJ33tKlf-X_-1ad3u0cyHfT_8EroD4iYZ1ZVasuYxAKjcdmbbVZ7NlDK9rqyI5euyz-70-M-QM5Lk6l88SRoSS2Y9drB8Z4ednHxTIh7XZcnaIiB5Xf4Mv8Rc51nUyIC5lKp02LP7oViCg6OaAhR4ynNJkCgFMAE&x-kcdn-pid=112757&pkey=AAX8ukavvkZsIz-IUg2pTvMOAV7LVItIdg_5TUYhGA1YINT8x-SR7rXY7BWLKqspLTYIjK7C0SjbXtX25Lm4_sx2V229AIyfVzjrlQQ7IjPsxvAv9cTG72YN0TPSjVowBZQ",
  "duration": "5.066",
  "state": "succeed",
  "task_id": "363c7a84-e880-472e-a4d4-098e50cfc292"
}
Il risultato restituito contiene diversi campi, descritti come segue:
  • success, lo stato attuale del compito di generazione del video.
  • task_id, l’ID del compito di generazione del video.
  • video_id, l’ID del video generato dal compito di generazione.
  • video_url, il link al video generato dal compito di generazione.
  • duration, la durata del video generato dal compito di generazione.
  • state, lo stato attuale del compito di generazione.
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 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/motion' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://sourceyoya.wenge.com/2025/06/03/683e9f76e4b0684509ab1aca.jpg",
  "video_url": "https://cdn.acedata.cloud/odwfm5.mp4",
  "prompt": "Rendi l'immagine vivace",
  "mode": "std",
  "character_orientation": "image"
}'

​
Callback asincrona

Poiché il tempo di generazione dell’API Kling Motion Generation è 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. Pertanto, questa API offre anche supporto per callback asincrone. Il processo complessivo è: quando il client avvia la richiesta, deve specificare un campo callback_url aggiuntivo. Dopo che il client ha effettuato la richiesta all’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 JSON POST, includendo anche il campo task_id, in modo che il risultato del compito possa essere associato tramite l’ID. Di seguito, vediamo un esempio per comprendere come operare concretamente. Innanzitutto, il callback Webhook è un servizio in grado di ricevere richieste HTTP, e gli sviluppatori dovrebbero sostituirlo con l’URL del server HTTP che hanno creato. Qui, per comodità di dimostrazione, utilizziamo un sito Web pubblico di esempio per Webhook https://webhook.site/, aprendo questo sito si otterrà un URL Webhook, come mostrato nell’immagine: Copia questo URL, che può essere utilizzato come Webhook, l’esempio qui è https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Successivamente, possiamo impostare il campo callback_url sull’URL Webhook sopra menzionato, riempiendo i parametri corrispondenti, i dettagli sono mostrati nell’immagine qui sotto:

Cliccando su esegui, possiamo 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 qui sotto: 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"
}
Possiamo vedere che nel risultato c’è un campo task_id, gli altri campi sono simili a quelli sopra, attraverso 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 failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusione

Attraverso questo documento, hai appreso come utilizzare l’API Kling Motion Generation per implementare le funzionalità di controllo delle azioni ufficiali di Kling. 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.