> ## 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.
# Hailuo Videos Generation API Integrazione Istruzioni
> Hailuo Video Generation 集成指南 - XHuoAPI
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](https://api.xhuoapi.ai/documents/ee06377b-9185-438f-ac84-3376bcb1275e) 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:
```json theme={null}
{
"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:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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/](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:
```json theme={null}
{
"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
```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 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.