> ## 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.
# Fish Audios Generation API Integrazione Istruzioni
> Fish music generation 集成指南 - XHuoAPI
Questo documento presenterà una guida all'integrazione dell'API Fish Audios Generation, che consente di clonare la propria voce tramite l'inserimento di parole chiave.
## Processo di Richiesta
Per utilizzare l'API, è necessario prima andare alla pagina corrispondente dell'[API Fish Audios Generation](https://api.xhuoapi.ai/documents/e681b715-54fd-4464-a59a-d7f14500e095) 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à fornito un credito gratuito, che consente di utilizzare l'API senza costi.
## Utilizzo di Base
Innanzitutto, è importante comprendere il modo di utilizzo di base, che consiste nell'inserire la parola chiave `prompt`, l'azione di clonazione `action`, l'ID della voce `voice_id` 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 `model`, attualmente principalmente il modello `fish-tts`, 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 clonare la voce, principalmente il modello `fish-tts`.
* `action`: l'azione per il compito di clonazione della voce.
* `prompt`: la parola chiave da clonare.
* `voice_id`: l'ID della voce da clonare.
* `callback_url`: l'URL per ricevere il risultato.
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:
```json theme={null}
{
"success": true,
"task_id": "5872ab00-3cf4-4040-a798-8510aaa16756",
"trace_id": "5eda3694-448a-4b72-af33-2acb3851ffe1",
"data": [
{
"audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}
]
}
```
Il risultato restituito ha diversi campi, descritti come segue:
* `success`, lo stato attuale del compito di clonazione della voce.
* `data`, il risultato del compito di clonazione della voce
* `audio_url`, il link audio del compito di clonazione della voce.
Possiamo vedere che abbiamo ottenuto informazioni soddisfacenti sulla voce, e dobbiamo solo ottenere la voce clonata in base all'indirizzo del link musicale presente 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/fish/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "speech",
"prompt": "a white siamese cat",
"model": "fish-tts",
"voice_id": "d7900c21663f485ab63ebdb7e5905036"
}'
```
## Callback Asincrona
Poiché il tempo di generazione dell'API Fish Audios Generation è 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 compito generato verrà inviato al `callback_url` specificato dal client in formato POST JSON, 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:
Copiare questo URL, che può essere utilizzato come Webhook, l'esempio qui è `https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34`.
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:
```
{
"task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5"
}
```
Dopo un momento, possiamo osservare il risultato del compito generato su `https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34`, come mostrato nell'immagine:
Il contenuto è il seguente:
```json theme={null}
{
"success": true,
"task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"data": [
{
"audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
]
}
```
Possiamo vedere che nel risultato c'è un campo `task_id`, e gli altri campi sono simili a quelli precedenti, 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 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 già compreso come utilizzare l'API di generazione audio Fish per clonare voci tramite l'inserimento di parole chiave. 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.