Skip to main content
Questo documento introduce una guida all’integrazione dell’Hailuo Videos Generation API, che consente di generare video ufficiali di Hailuo tramite l’inserimento di parametri personalizzati.

​
Processo di richiesta

Per utilizzare l’Hailuo Videos Generation API, 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 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 provare senza costi; se il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.
📘 Documentazione completa: Hailuo Videos Generation API →

​
Uso 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 del primo fotogramma first_image_url e il modello model, per ottenere il risultato elaborato. Prima di tutto, è necessario passare un campo action, il cui valore è generate, e poi dobbiamo inserire il modello, attualmente ci sono principalmente il modello video da immagine minimax-i2v e il modello video da testo minimax-t2v, 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:
  • model: il modello per generare il video, principalmente ci sono due modelli: minimax-i2v per video da immagine e minimax-t2v per video da testo.
  • action: l’azione per il compito di generazione video.
  • first_image_url: quando si sceglie il modello video da immagine minimax-i2v, è necessario caricare il link dell’immagine di riferimento del primo fotogramma, non supporta la codifica Base64.
  • prompt: la parola chiave.
  • callback_url: l’URL per ricevere il risultato.
  • async: opzionale, se impostato su true, l’interfaccia restituisce immediatamente task_id, senza necessità di fornire callback_url, successivamente si può ottenere il risultato tramite l’interfaccia di query del compito corrispondente.
Dopo aver effettuato la selezione, possiamo 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:
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.
  • trace_id, l’ID di tracciamento del compito di generazione video attuale.
  • data, l’elenco dei risultati del compito di generazione video attuale.
    • id, l’ID del video generato dal compito di generazione video attuale.
    • prompt, la parola chiave del compito di generazione video attuale.
    • model, il link di copertura del compito di generazione video attuale.
    • video_url, il link del video generato dal compito di generazione video attuale.
    • state, lo stato del compito di generazione video attuale.
Possiamo vedere che abbiamo ottenuto informazioni soddisfacenti sul video, e dobbiamo solo ottenere il video Hailuo generato dal link video presente in data. 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’Hailuo Videos Generation API è 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 processo 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, includendo anche il campo task_id, in modo che il risultato del compito possa essere associato tramite l’ID. Di seguito, attraverso un esempio, vediamo 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, che può essere utilizzato come Webhook; l’esempio qui è https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83. Successivamente, possiamo impostare il campo callback_url su questo URL Webhook, riempiendo i parametri corrispondenti, come mostrato nell’immagine:

Cliccando su “Esegui”, possiamo notare che riceviamo immediatamente un risultato, come segue:
Dopo un momento, possiamo osservare il risultato del video generato su https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83, 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 generazione video Hailuo, che può generare video tramite input di parole chiave e un’immagine 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.