Vai al contenuto principale
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 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: 
{
  "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: 
curl -X POST 'https://api.acedata.cloud/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/, 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: 
{
    "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

{
  "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.