Fish Model Query API Integrazione Istruzioni

Questa interfaccia si basa sull’API Model ufficiale di Fish Audio ed è utilizzata per ricercare in modo paginato il database pubblico di timbri di Fish o i timbri clonati sotto l’account attuale. L’indirizzo è GET https://api.acedata.cloud/fish/model.

Per creare un timbro, si prega di fare riferimento all’API Fish Model Create; per cercare i dettagli di un singolo timbro per _id, si prega di fare riferimento all’API Fish Model Get.

Processo di Richiesta

Per utilizzare l’API Fish Model, prima di tutto vai al Pannello di Controllo di Ace Data Cloud per ottenere il tuo API Token, da tenere a disposizione.

Se non hai ancora effettuato il login o registrato, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, non è necessario richiederne uno separato per ogni servizio. La prima richiesta ti darà un credito gratuito, per un’esperienza senza costi; quando il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.

📘 Documentazione completa: Fish Model API →

Parametri di Ricerca

Parametro	Tipo	Predefinito	Descrizione
`page_size`	intero	10	Numero di elementi per pagina.
`page_number`	intero	1	Numero di pagina a partire da 1.
`title`	stringa	—	Ricerca fuzzy per titolo.
`tag`	stringa	—	Filtra per un singolo tag.
`self`	booleano	—	Se `true`, restituisce solo i timbri creati dall’account attuale, senza ulteriori condizioni.
`author_id`	stringa	—	Filtra per `_id` dell’utente upstream.
`language`	stringa	—	Filtra per lingua del timbro, come `en`, `zh`, `es`.
`title_language`	stringa	—	Filtra per lingua del titolo.
`sort_by`	stringa	—	Campo di ordinamento, coerente con l’upstream, come `created_at`, `task_count`.

La denominazione dei parametri è completamente coerente con l’upstream GET https://api.fish.audio/model, per maggiori dettagli vedere 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'

Risposta (testato, il totale del database pubblico è di circa 1,8 milioni di elementi; per leggibilità, l’esempio sottostante omette alcuni campi lunghi):

{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "Una voce maschile matura e autorevole con un tono calmo e spirituale...",
      "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'

Risposta (testato):

{
  "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”, colpirà tutti i timbri nel database pubblico di Fish (non solo i propri).

Esempio 3: Elenca solo i timbri creati 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'

Risposta (testato, attualmente l’account ha solo 1 timbro):

{
  "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": null
}

self=true è equivalente a limitare il filtro a author_id == ID upstream dell'account attuale, è un comune punto di accesso per “la mia lista di timbri”.

Esempio 4: Filtraggio 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 restituirà risultati anche per tag non presenti nel dizionario dei tag, ma la corrispondenza sarà relativamente ampia; se il numero di corrispondenze è 0, si consiglia di utilizzare la corrispondenza fuzzy con title.

Campi di risposta

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

Campo	Tipo	Descrizione
`_id`	string	ID del timbro, utilizzato come valore di `reference_id` in `/fish/tts`.
`type`	string	Tipo di modello, solitamente `tts`.
`title`	string	Nome del timbro.
`description`	string	Descrizione del timbro.
`state`	string	Stato di addestramento: `trained` indica che è disponibile.
`tags`	string[]	Tag della libreria pubblica.
`languages`	string[]	Lingue in cui il timbro è specializzato.
`visibility`	string	`public` o `private`.
`samples`	object[]	Campioni preimpostati (inclusi i link diretti `audio`).
`like_count`	integer	Numero di “mi piace” nella libreria pubblica.
`task_count`	integer	Numero di sintesi storiche.
`author`	object	Informazioni sull’autore upstream: `_id` / `nickname` / `avatar`.
`total` (livello superiore)	integer	Numero totale di elementi che soddisfano i criteri.
`has_more`	boolean?	Indicazione di paginazione upstream, potrebbe essere `null`. Si consiglia di calcolare il numero totale di pagine usando `total / page_size`.

Informazioni di fatturazione

Questa interfaccia non comporta costi - la query paginata della lista dei timbri è un’operazione gratuita. La creazione di timbri (Fish Model Create) è anch’essa gratuita, i costi si generano solo durante la chiamata a Fish TTS per la sintesi vocale in base all’uso.

Gestione degli errori

400 token_mismatched: Parametri di richiesta mancanti o non validi.
401 invalid_token: Il token di autorizzazione non esiste o è non valido.
429 too_many_requests: Limite di velocità dell’account attivato.
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 un timbro dalla libreria pubblica di Fish da fornire a /fish/tts come reference_id, utilizzare prima questa interfaccia insieme a title / tag / language per cercare, localizzare l’ _id target, quindi utilizzare Fish Model Get per ottenere campioni da ascoltare. Per elencare i timbri creati da sé, basta passare self=true.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Proxy

Avanzato

Coding

Fish Model Query API Integrazione Istruzioni

Processo di Richiesta

Parametri di Ricerca

Esempio 1: Paginazione predefinita (per `page_size`)

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

Esempio 3: Elenca solo i timbri creati da te (`self=true`)

Esempio 4: Filtraggio per lingua + tag

Campi di risposta

Informazioni di fatturazione

Gestione degli errori

Conclusione

​Processo di Richiesta

​Parametri di Ricerca

​Esempio 1: Paginazione predefinita (per page_size)

​Esempio 2: Ricerca fuzzy per titolo (title)

​Esempio 3: Elenca solo i timbri creati da te (self=true)

​Esempio 4: Filtraggio per lingua + tag

​Campi di risposta

​Informazioni di fatturazione

​Gestione degli errori

​Conclusione

Processo di Richiesta

Parametri di Ricerca

Esempio 1: Paginazione predefinita (per `page_size`)

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

Esempio 3: Elenca solo i timbri creati da te (`self=true`)

Esempio 4: Filtraggio per lingua + tag

Campi di risposta

Informazioni di fatturazione

Gestione degli errori

Conclusione