Vai al contenuto principale

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.

Questo documento illustra le istruzioni per l’integrazione con Fish Model Query API (GET /fish/model), un’interfaccia completamente compatibile con la Fish Audio OpenAPI ufficiale, utilizzata per la ricerca paginata della lista dei timbri clonati visibili all’account corrente o su tutta la piattaforma.
Per creare un timbro, fare riferimento a Fish Model Create API. Per interrogare i dettagli di un singolo timbro tramite _id, consultare Fish Model Get API.

​
Procedura di richiesta

Per utilizzare l’API, è necessario prima richiedere il servizio corrispondente nella pagina Fish Model API. Una volta entrati nella pagina, cliccare sul pulsante “Acquire”. Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per registrarsi e accedere; dopo il login o la registrazione, si tornerà automaticamente alla pagina corrente. Alla prima richiesta verrà assegnato un credito gratuito per l’utilizzo dell’API.

​
Differenze rispetto all’API ufficiale

  • Metodo di autenticazione: si utilizza Authorization: Bearer {token}, dove {token} è la chiave ottenuta tramite la piattaforma.
  • Struttura della risposta: la risposta paginata upstream di Fish viene trasmessa direttamente senza incapsulamento aggiuntivo dalla piattaforma; in caso di errore viene utilizzata la struttura standard della piattaforma {success:false, error:{code,message}, trace_id}.

​
Esempio di richiesta

curl -G 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=10' \
  --data-urlencode 'page_number=1' \
  --data-urlencode 'self=true'

​
Parametri di query

Identici a quelli ufficiali Fish:
  • page_size: numero di elementi per pagina, default 10.
  • page_number: numero della pagina, a partire da 1.
  • title: ricerca fuzzy per titolo.
  • tag: filtro per tag.
  • self: se impostato a true, restituisce solo i timbri creati dall’account corrente.
  • author_id: filtro per creatore.
  • language: filtro per lingua del timbro.
  • title_language: filtro per lingua del titolo.

​
Esempio di risposta

La risposta di successo trasmette direttamente la struttura paginata della piattaforma Fish: 
{
  "items": [
    {
      "_id": "d7900c21663f485ab63ebdb7e5905036",
      "title": "我的克隆音色",
      "description": "用一段播客录音克隆的音色",
      "cover_image": "https://example.com/cover.png",
      "type": "tts",
      "state": "trained",
      "tags": [],
      "languages": ["zh", "en"],
      "visibility": "private",
      "created_at": "2025-05-09T12:34:56.789Z",
      "updated_at": "2025-05-09T12:34:56.789Z"
    }
  ],
  "total": 1
}
L’_id restituito può essere utilizzato come valore del campo reference_id nella successiva Fish TTS API per la sintesi vocale con il timbro clonato.

​
Informazioni sui costi

Questa interfaccia non prevede costi: la ricerca paginata della lista dei timbri è gratuita; solo la creazione di nuovi timbri tramite POST /fish/model con il campo voices nel corpo della richiesta è a pagamento.

​
Gestione degli errori

  • 400 token_mismatched: parametri della richiesta mancanti o non validi.
  • 400 api_not_implemented: metodo o parametri della richiesta non supportati.
  • 401 invalid_token: informazioni di autenticazione mancanti o non valide.
  • 429 too_many_requests: superato il limite di velocità per l’account corrente.
  • 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

Fish Model Query API offre una capacità di ricerca dei timbri completamente compatibile con Fish Audio ufficiale, permettendo di mantenere una libreria personale di timbri clonati sulla piattaforma. In combinazione con Fish Model Get API, è possibile ottenere i dettagli completi di un singolo timbro tramite ID.