> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Istruzioni per l'integrazione dell'API Kling Motion Generation
> Kling video generation 集成指南 - XHuoAPI
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](https://api.xhuoapi.ai/documents/d3f2c369-102d-4856-9565-702ac5f2df63) 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:
```json theme={null}
{
"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:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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/](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:
```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"
}
```
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
```json theme={null}
{
"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.