Vai al contenuto principale
Questo documento presenterà un’istruzione per l’integrazione dell’API Fish Voices Generation, che consente di creare il proprio timbro audio inserendo un link audio.

​
Processo di Richiesta

Per utilizzare l’API, è necessario prima andare alla pagina corrispondente dell’API Fish Voices Generation 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 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 l’API.

​
Utilizzo di Base

Innanzitutto, è importante comprendere il modo di utilizzo di base, che consiste nell’inserire il link audio del timbro voice_url, per ottenere il risultato elaborato. I dettagli sono i seguenti:

Si può notare che 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:
  • voice_url: il link audio del timbro caricato.
  • title: le informazioni sul titolo di quel timbro.
  • image_urls: l’immagine di copertura di quel timbro.
  • description: le informazioni descrittive di quel timbro.
  • callback_url: l’URL per ricevere il risultato.
Dopo aver selezionato, si può notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Facendo clic sul pulsante “Try” è possibile effettuare un test, come mostrato nell’immagine sopra, e si ottiene il seguente risultato: 
{
  "success": true,
  "task_id": "b01db503-dd9e-4f92-861a-344f14756217",
  "trace_id": "8731a2f1-7736-4a47-98e7-da942f9346a7",
  "data": {
    "_id": "d5d21261512b4852b9ccd709facf93f3",
    "type": "tts",
    "title": "test",
    "description": "test",
    "cover_image": "coverimage/d5d21261512b4852b9ccd709facf93f3",
    "train_mode": "fast",
    "state": "trained",
    "tags": [],
    "samples": [
      {
        "title": "Default Sample",
        "text": "Attraverso un'osservazione a lungo termine, si è scoperto che i pesci nell'ecosistema della barriera corallina presentano modelli complessi di comportamento di gruppo. Utilizzano cambiamenti di colore e posture di nuoto specifiche per comunicare, e questo sistema di comunicazione non verbale raffinato dimostra l'intelligenza adattativa degli organismi marini.",
        "task_id": "4ae961828fc94c07b2103dc039a8466b",
        "audio": "task/4ae961828fc94c07b2103dc039a8466b.mp3"
      }
    ],
    "created_at": "2025-09-21T07:29:41.058506Z",
    "updated_at": "2025-09-21T07:29:41.057917Z",
    "languages": [
      "zh"
    ],
    "visibility": "public",
    "lock_visibility": false,
    "default_text": "Attraverso un'osservazione a lungo termine, si è scoperto che i pesci nell'ecosistema della barriera corallina presentano modelli complessi di comportamento di gruppo. Utilizzano cambiamenti di colore e posture di nuoto specifiche per comunicare, e questo sistema di comunicazione non verbale raffinato dimostra l'intelligenza adattativa degli organismi marini.",
    "like_count": 0,
    "mark_count": 0,
    "shared_count": 0,
    "task_count": 0,
    "unliked": false,
    "liked": false,
    "marked": false,
    "author": {
      "_id": "7ecad23df62a4174acd6a2a6cb5201ee",
      "nickname": "Matthew Garcia",
      "avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
    }
  }
}
Il risultato restituito contiene diversi campi, descritti come segue:
  • success, lo stato della creazione del timbro audio in quel momento.
    • data, il risultato del compito musicale
      • _id, l’ID del compito di generazione del timbro audio, che sarà utilizzato in seguito per clonare il suono.
      • title, il titolo del timbro audio.
      • image_url, le informazioni sulla copertura del timbro audio.
      • description, le informazioni descrittive del timbro audio.
      • train_mode, il modo utilizzato per il compito di generazione del timbro audio.
      • tags, lo stile del timbro audio.
      • default_text, le informazioni testuali del timbro audio generato in quel momento.
Si può notare che abbiamo ottenuto informazioni soddisfacenti sul timbro audio, e dobbiamo solo utilizzare l’_id di data per eseguire il compito di clonazione del suono. 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/voices' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "voice_url": "https://platform.r2.fish.audio/task/604133d7b3c7430385382470f67770e8.mp3",
  "title": "test",
  "description": "test"
}'

​
Callback Asincrona

Poiché il tempo di generazione dell’API Fish Voices Generation è relativamente lungo, circa 1-2 minuti, se l’API non risponde per un lungo periodo, 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 corrente. 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, 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 creato. 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, 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:

Facendo clic su Esegui, si può notare che si ottiene immediatamente un risultato, come segue: 
{
  "task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8"
}
Attendere un momento, possiamo osservare i risultati del compito generato su https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34, come mostrato nell’immagine: Il contenuto è il seguente: 
{
    "success": true,
    "task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8",
    "trace_id": "3fcdea82-7c1c-4a0a-b8d8-f7616f722d8f",
    "data": {
        "_id": "fa75e7c3f02f42e79a6aa622b6cf075e",
        "type": "tts",
        "title": "test",
        "description": "test",
        "cover_image": "coverimage/fa75e7c3f02f42e79a6aa622b6cf075e",
        "train_mode": "fast",
        "state": "trained",
        "tags": [],
        "samples": [
            {
                "title": "Default Sample",
                "text": "I delfini navigano nell'oceano attraverso un sistema di ecolocalizzazione, questa tecnologia acustica precisa consente loro di rilevare l'ambiente circostante, cercare cibo e evitare pericoli. Questo non solo dimostra l'adattabilità della vita marina, ma rivela anche il meraviglioso design della natura.",
                "task_id": "68cdda24d26e4794bae177e20da740db",
                "audio": "task/68cdda24d26e4794bae177e20da740db.mp3"
            }
        ],
        "created_at": "2025-09-21T07:36:20.200865Z",
        "updated_at": "2025-09-21T07:36:20.200353Z",
        "languages": [
            "zh"
        ],
        "visibility": "public",
        "lock_visibility": false,
        "default_text": "I delfini navigano nell'oceano attraverso un sistema di ecolocalizzazione, questa tecnologia acustica precisa consente loro di rilevare l'ambiente circostante, cercare cibo e evitare pericoli. Questo non solo dimostra l'adattabilità della vita marina, ma rivela anche il meraviglioso design della natura.",
        "like_count": 0,
        "mark_count": 0,
        "shared_count": 0,
        "task_count": 0,
        "unliked": false,
        "liked": false,
        "marked": false,
        "author": {
            "_id": "7ecad23df62a4174acd6a2a6cb5201ee",
            "nickname": "Matthew Garcia",
            "avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
        }
    }
}
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 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 appreso come utilizzare l’API di generazione delle voci di pesce per creare la tua voce attraverso il collegamento audio del timbro di input. 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.