Istruzioni per l'integrazione dell'API di query del modello Fish

Questa API si basa sulla Model API ufficiale di Fish Audio e viene utilizzata per recuperare in modo paginato la libreria pubblica di voci Fish o le voci clonate dell’account corrente. L’indirizzo è GET https://api.acedata.cloud/fish/model.

Per creare una voce, fare riferimento a Fish Model Create API; per interrogare i dettagli di una singola voce tramite _id, fare riferimento a Fish Model Get API.

Procedura di richiesta

Per utilizzare Fish Model API, prima vai alla console di Ace Data Cloud per ottenere il tuo API Token, da conservare come riserva.

Se non hai ancora effettuato l’accesso o non ti sei registrato, verrai automaticamente reindirizzato alla pagina di accesso per invitarti a registrarti e ad accedere; al termine, tornerai automaticamente alla pagina corrente. Un solo API Token può chiamare tutti i servizi della piattaforma, senza necessità di richiederne uno separatamente per ogni servizio. La prima richiesta include credito gratuito, per consentire un’esperienza gratuita; quando il credito è insufficiente, puoi ricaricare il saldo universale nella console.

📘 Documentazione completa: Fish Model API →

Parametri di query

Parametro	Tipo	Predefinito	Descrizione
`page_size`	integer	10	Numero di elementi per pagina.
`page_number`	integer	1	Numero di pagina a partire da 1.
`title`	string	—	Ricerca fuzzy per titolo.
`tag`	string	—	Filtra per un singolo tag.
`self`	boolean	—	Quando è `true`, restituisce solo le voci create e salvate tramite questa piattaforma dall’account chiamante corrente.
`author_id`	string	—	Filtra per ID dell’autore della voce.
`language`	string	—	Filtra per lingua della voce, ad esempio `en`, `zh`, `es`.
`title_language`	string	—	Filtra per lingua del titolo nella libreria pubblica di voci.
`sort_by`	string	—	Campo di ordinamento; quando `self=true`, supporta `created_at`, `task_count`.

I nomi dei parametri sono completamente coerenti con l’upstream GET https://api.fish.audio/model; per i dettagli, consulta la documentazione ufficiale di Fish.

Esempio 1: paginazione predefinita (per `page_size`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=2'

Restituisce (testato effettivamente, il totale della libreria pubblica è di circa 1,8 milioni di elementi; per leggibilità, nell’esempio seguente sono omessi alcuni campi lunghi):

{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "A mature and authoritative male voice with a calm, spiritual tone...",
      "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
      "train_mode": "fast",
      "state": "trained",
      "tags": ["male", "old", "narration", "calm", "Spanish"],
      "samples": [
        {
          "title": "Default Sample",
          "text": "Hermanos míos, recordemos las palabras del Señor...",
          "task_id": "59ce7df6935c42249759327ddf70f37b",
          "audio": "https://platform.r2.fish.audio/task/59ce7df6935c42249759327ddf70f37b.mp3"
        }
      ],
      "languages": ["es"],
      "visibility": "public",
      "like_count": 4344,
      "task_count": 708461,
      "author": {
        "_id": "1b82fb6a329c4462b67aa9ee0a42046f",
        "nickname": "Fernando Caicedo"
      }
    },
    {
      "_id": "90e65eaaf50e4470b8e6d43ee6afd7d5",
      "type": "tts",
      "title": "Super Smash Bros. 4/Ultimate Announcer",
      "tags": ["male", "old", "announcer", "gaming", "cinematic"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

Esempio 2: ricerca fuzzy per titolo (`title`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'title=narration' \
  --data-urlencode 'page_size=2'

Restituisce (testato effettivamente):

{
  "total": 161,
  "items": [
    {
      "_id": "fb8fe4a94658429d9be70efd4eec35a2",
      "type": "tts",
      "title": "Miles Morales ( Narration Paw )",
      "tags": ["male", "middle-aged", "entertainment", "storytelling", "Children's Content"],
      "languages": ["en"],
      "visibility": "public",
      "task_count": 770
    },
    {
      "_id": "76b55591c758444cb95253708696dfad",
      "type": "tts",
      "title": "Joe NARRATION",
      "tags": ["male", "middle-aged", "narration", "deep", "raspy"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

Nota che title è una «corrispondenza fuzzy globale», che troverà contemporaneamente tutte le voci nella libreria pubblica Fish (non solo le proprie).

Esempio 3: elenca solo le voci create da te (`self=true`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'self=true' \
  --data-urlencode 'page_size=5'

Esempio di risposta:

{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "smoke test from api.acedata.cloud",
      "state": "trained",
      "languages": ["zh"],
      "visibility": "public",
      "samples": [
        {
          "title": "Default Sample",
          "text": "师父，[语气坚定]我真的受够了这山上的清冷日子！...",
          "task_id": "6a1bf398dfae49dca0e23159214342a0",
          "audio": "https://platform.r2.fish.audio/task/6a1bf398dfae49dca0e23159214342a0.mp3"
        }
      ],
      "created_at": "2026-05-10T03:52:55.601000Z",
      "author": {
        "_id": "780f2b2f862d41a08c0507bbbda77eb6",
        "nickname": "Penny Conrad"
      }
    }
  ],
  "has_more": false
}

self=true elenca le voci create e salvate tramite questa piattaforma in base all’account chiamante effettivo; verranno elencate insieme anche le voci create dallo stesso account utilizzando API Token diversi. I risultati vengono impaginati in ordine cronologico inverso di creazione, e author_id può ulteriormente filtrare l’ID autore di queste voci. Questo parametro filtra solo l’elenco, le voci restano comunque pubblicamente disponibili. self=true non supporta title_language; se è necessario cercare per lingua del titolo, interrogare la libreria pubblica delle voci.

Esempio 4: filtro per lingua + tag

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'language=zh' \
  --data-urlencode 'tag=narration' \
  --data-urlencode 'page_size=5'

L’upstream restituisce risultati anche per tag non presenti nel dizionario dei tag, ma la corrispondenza è relativamente permissiva; se il numero di risultati è 0, si consiglia di usare invece una corrispondenza fuzzy con title.

Campi di risposta

Ogni elemento in items[] è un oggetto ModelEntity completo, campi comunemente usati:

Campo	Tipo	Descrizione
`_id`	string	ID della voce, usato come valore di `reference_id` in `/fish/tts`.
`type`	string	Tipo di modello, solitamente `tts`.
`title`	string	Nome della voce.
`description`	string	Descrizione della voce.
`state`	string	Stato di addestramento: `trained` indica che è utilizzabile.
`tags`	string[]	Tag della libreria pubblica.
`languages`	string[]	Lingue in cui la voce eccelle.
`visibility`	string	`public` o `private`.
`samples`	object[]	Campioni preimpostati (incluso il collegamento diretto `audio`).
`like_count`	integer	Numero di Mi piace nella libreria pubblica.
`task_count`	integer	Numero storico di sintesi.
`author`	object	Informazioni sull’autore della voce: `_id` / `nickname` / `avatar`.
`total`（livello superiore）	integer	Numero totale di elementi che soddisfano le condizioni.
`has_more`	boolean?	È un valore booleano quando `self=true`; la query della libreria pubblica delle voci potrebbe essere `null`.

Informazioni sulla fatturazione

Questa interfaccia non prevede addebiti: la query paginata dell’elenco delle voci è un’operazione gratuita. Anche la creazione di voci (Fish Model Create) è gratuita; i costi vengono generati in base all’utilizzo solo quando si chiama Fish TTS per sintetizzare la voce.

Gestione degli errori

400 token_mismatched: parametri della richiesta mancanti o non validi.
401 invalid_token: token di autenticazione inesistente o non valido.
429 too_many_requests: è stato attivato il limite di frequenza dell’account.
500 api_error: errore interno del server.

Esempio di risposta di errore:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusione

Per selezionare una voce dalla libreria pubblica Fish da fornire a reference_id di /fish/tts, usare prima questa interfaccia insieme a title / tag / language per cercare, individuare l’obiettivo _id, quindi usare Fish Model Get per ottenere campioni da ascoltare. Per elencare le voci create da sé, è sufficiente passare self=true.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Istruzioni per l'integrazione dell'API di query del modello Fish

Procedura di richiesta

Parametri di query

Esempio 1: paginazione predefinita (per `page_size`)

Esempio 2: ricerca fuzzy per titolo (`title`)

Esempio 3: elenca solo le voci create da te (`self=true`)

Esempio 4: filtro per lingua + tag

Campi di risposta

Informazioni sulla fatturazione

Gestione degli errori

Conclusione

​Procedura di richiesta

​Parametri di query

​Esempio 1: paginazione predefinita (per page_size)

​Esempio 2: ricerca fuzzy per titolo (title)

​Esempio 3: elenca solo le voci create da te (self=true)

​Esempio 4: filtro per lingua + tag

​Campi di risposta

​Informazioni sulla fatturazione

​Gestione degli errori

​Conclusione

Procedura di richiesta

Parametri di query

Esempio 1: paginazione predefinita (per `page_size`)

Esempio 2: ricerca fuzzy per titolo (`title`)

Esempio 3: elenca solo le voci create da te (`self=true`)

Esempio 4: filtro per lingua + tag

Campi di risposta

Informazioni sulla fatturazione

Gestione degli errori

Conclusione