Skip to main content
Questo documento presenterà le istruzioni per l’integrazione dell’API Kling Motion Generation, che consente di generare video ufficiali Kling tramite l’immissione di parametri personalizzati.

​
Procedura di richiesta

Per utilizzare l’API Kling Motion Generation, prima di tutto vai al Pannello di controllo di Ace Data Cloud per ottenere il tuo API Token, da conservare per uso futuro. Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti inviterà a registrarti e a effettuare il login; 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, che ti permetterà di provare senza costi; quando il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.
📘 Documentazione completa: Kling Motion Generation API →

​
Utilizzo di base

Iniziamo a comprendere il modo di utilizzo di base, che consiste nell’immettere la parola chiave prompt, l’URL dell’immagine di riferimento image_url e il link del video di riferimento video_url, per ottenere il risultato elaborato; poi dobbiamo anche inserire il modello mode, attualmente ci sono principalmente 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 che desideri ricevere, qui è impostato su application/json, ovvero formato JSON.
  • authorization: la chiave per chiamare l’API, che puoi selezionare direttamente dopo la richiesta.
Inoltre, abbiamo impostato il corpo della richiesta, che include:
  • image_url: URL dell’immagine di riferimento per l’aspetto del personaggio. Supporta JPG/JPEG/PNG, file ≤50MB, larghezza e altezza ≥300px, rapporto di aspetto 1:2.5～2.5:1; il personaggio deve essere chiaramente visibile nella parte superiore del corpo o a figura intera con la testa.
  • video_url: URL del video di riferimento per il movimento. Supporta MP4/MOV, file ≤100MB, larghezza e altezza tra 340–3850px, almeno 3 secondi; quando character_orientation=image, massimo 10 secondi, quando character_orientation=video, massimo 30 secondi. Si consiglia di utilizzare video a singolo piano sequenza in cui il personaggio rimane sempre all’interno dell’inquadratura.
  • mode: modalità di generazione del video, principalmente ci sono due modalità: standard std e modalità rapida pro.
  • keep_original_sound: puoi scegliere se mantenere l’audio originale del video, valori enumerati: yes, no.
  • character_orientation: orientamento del personaggio nel video generato, puoi scegliere di allinearlo all’immagine o al video, valori enumerati: image, video.
  • 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 puoi ottenere i risultati tramite l’interfaccia di query del compito corrispondente.
Dopo aver effettuato la selezione, puoi notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Try” puoi effettuare un test, come mostrato nell’immagine sopra, e abbiamo ottenuto il seguente risultato:
Il risultato restituito ha diversi campi, descritti di seguito:
  • 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 del 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 desideri generare il codice di integrazione corrispondente, puoi semplicemente copiarlo, ad esempio il codice CURL è il seguente:

​
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 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 attuale. Quando il compito è completato, il risultato del video generato verrà inviato al callback_url specificato dal client in formato JSON POST, che include anche il campo task_id, in modo che il risultato del compito possa essere correlato 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; gli sviluppatori dovrebbero sostituirlo con l’URL del server HTTP che hanno costruito. Qui, per comodità di dimostrazione, utilizziamo un sito di esempio Webhook pubblico https://webhook.site/, aprendo questo sito otterrai un URL Webhook, come mostrato nell’immagine: 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, mentre inseriamo i parametri corrispondenti, i dettagli sono mostrati nell’immagine:

Cliccando su Esegui, puoi notare che riceverai immediatamente un risultato, come segue:
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:
Si può 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 incontra un errore, l’API restituirà il relativo codice di errore e informazioni. 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

​
Conclusione

Attraverso questo documento, hai già compreso come utilizzare l’API di Kling Motion Generation per realizzare 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.