Vai al contenuto principale
Questo documento presenterà un’istruzione per l’integrazione dell’Hailuo Videos Generation API, che consente di generare video ufficiali di Hailuo inserendo parametri personalizzati.

​
Processo di Richiesta

Per utilizzare l’API, è necessario prima andare alla pagina corrispondente dell’Hailuo Videos Generation API 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 login per invitare a registrarsi e accedere. Dopo aver effettuato il login o la registrazione, si tornerà automaticamente alla pagina corrente. Alla prima richiesta, verrà offerto un credito gratuito, che consente di utilizzare gratuitamente questa API.

​
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 first_image_url e il modello model, per ottenere il risultato elaborato. È necessario prima passare un campo action, il cui valore è generate, e poi dobbiamo inserire il modello. Attualmente, ci sono principalmente il modello di generazione video da immagine minimax-i2v e il modello di generazione video da testo minimax-t2v, i dettagli sono i seguenti:

Possiamo vedere che qui 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 ci sono due modelli: minimax-i2v per generazione video da immagine e minimax-t2v per generazione video da testo.
  • action: l’azione per il compito di generazione video.
  • first_image_url: quando si sceglie il modello di generazione 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.
Dopo aver effettuato la selezione, 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,
  "task_id": "baf1034c-684c-46be-ae6d-89ebb89b690d",
  "trace_id": "3221eb74-1a25-447a-ba69-7d9b310e306c",
  "data": [
    {
      "id": "0pv8yhe4fdrge0cmckpv23pd2g",
      "model": "minimax-t2v",
      "prompt": "Internal heat",
      "video_url": "https://file.aigpai.com/czjl/qoueLWBokF3ud6tdVD6VJTZuXTnK5HaMO2qAOS46Ef8VSBFUA/tmp9e3u11c1.output.mp4",
      "state": "succeeded"
    }
  ]
}
Il risultato restituito ha diversi campi, descritti come segue:
  • 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 del 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 del 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 in base all’indirizzo del link video in data. 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/hailuo/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "Internal heat"
}'

​
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, che include 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, e 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: Copiare questo URL, 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, mentre inseriamo i parametri corrispondenti, i dettagli sono mostrati nell’immagine:

Cliccando su Esegui, possiamo notare che otteniamo immediatamente un risultato, come segue: 
{
  "task_id": "05aff65c-5e84-442b-8e29-3a5d27130840"
}
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: 
{
    "success": true,
    "task_id": "05aff65c-5e84-442b-8e29-3a5d27130840",
    "trace_id": "b9856b8a-725d-45c9-befe-e789d9fd9ffb",
    "data": [
        {
            "id": "t80jhsf96srg80cmcm6b0rk8gm",
            "model": "minimax-t2v",
            "prompt": "Internal heat",
            "video_url": "https://file.aigpai.com/czjl/YPaUz2DcwpJqItTXAG9XHAoEoj3dbF0XPU69LT5nefCMzBFUA/tmp8s_59jez.output.mp4",
            "state": "succeeded"
        }
    ]
}
Possiamo vedere che nel risultato c’è un campo task_id, gli altri campi sono simili a quelli sopra, e tramite 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 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

{
  "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 di generazione video Hailuo, che può generare video tramite l’inserimento 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.