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 API, un’interfaccia completamente compatibile con la Fish Audio OpenAPI ufficiale, che include:
  • POST /fish/model: crea un nuovo modello vocale (Voice Model) basato su campioni audio.
  • GET /fish/model: ricerca paginata della lista dei modelli vocali visibili per l’account corrente o su tutta la piattaforma.

​
Procedura di richiesta

Per utilizzare l’API, è necessario prima richiedere il servizio corrispondente sulla pagina Fish Model API. Una volta entrati nella pagina, cliccare sul pulsante “Acquire”. Se non si è ancora effettuato l’accesso o la registrazione, si verrà reindirizzati automaticamente alla pagina di login per registrarsi o accedere; dopo il login o la registrazione, si tornerà automaticamente alla pagina corrente. Alla prima richiesta verrà assegnata una quota gratuita per utilizzare l’API senza costi.

​
Differenze rispetto all’API ufficiale

  • Metodo di autenticazione: si utilizza Authorization: Bearer {token}, dove {token} è la chiave ottenuta sulla nostra piattaforma.
  • Upload dei campioni per la creazione del modello: attualmente questa API supporta solo l’invio in formato JSON tramite il campo voices, contenente gli URL dei campioni audio. L’API ufficiale Fish supporta multipart/msgpack per l’upload diretto di binari, ma questa funzionalità non è ancora implementata sulla nostra piattaforma; l’uso degli URL copre circa l’80% degli scenari comuni.
  • Struttura della risposta: sia POST /fish/model che GET /fish/model inoltrano direttamente la risposta proveniente da Fish senza incapsularla in un envelope della piattaforma; in caso di errore viene utilizzata la struttura standard {success:false, error:{code,message}, trace_id}.

​
Creazione di un modello vocale (POST /fish/model)

La richiesta minima per la creazione richiede i campi title e voices. voices è una lista di URL dei campioni audio, consigliati file di almeno 30 secondi con frequenza di campionamento di 16kHz o superiore. 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "title": "我的克隆音色",
    "description": "用一段播客录音克隆的音色",
    "voices": [
      "https://example.com/sample-voice.mp3"
    ],
    "cover_image": "https://example.com/cover.png",
    "visibility": "private"
  }'
La risposta di successo restituisce direttamente l’oggetto ModelEntity della piattaforma Fish: 
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "我的克隆音色",
  "description": "用一段播客录音克隆的音色",
  "cover_image": "https://example.com/cover.png",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [],
  "created_at": "2025-05-09T12:34:56.789Z",
  "updated_at": "2025-05-09T12:34:56.789Z",
  "languages": ["zh", "en"],
  "visibility": "private",
  "lock_visibility": false,
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "author": {
    "_id": "user_id",
    "nickname": "user_nickname",
    "avatar": "user_avatar"
  }
}
L’_id restituito può essere utilizzato come valore del campo reference_id nelle successive chiamate POST /fish/tts per la sintesi vocale con il modello clonato.

​
Ricerca della lista dei modelli vocali (GET /fish/model)

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 disponibili (uguali all’API ufficiale 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 true, restituisce solo i modelli creati dall’account corrente.
  • author_id: filtro per autore.
  • language: filtro per lingua del modello vocale.
  • title_language: filtro per lingua del titolo.
La risposta di successo inoltra 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
}

​
Informazioni sulla fatturazione

Questa API addebita solo per la creazione di modelli vocali (POST /fish/model con campo voices nel corpo della richiesta); la ricerca della lista dei modelli (GET /fish/model) è gratuita.

​
Gestione degli errori

  • 400 token_mismatched: richiesta errata, probabilmente parametri mancanti o non validi.
  • 400 api_not_implemented: richiesta errata, probabilmente parametri mancanti o non validi.
  • 401 invalid_token: non autorizzato, token di autorizzazione mancante o non valido.
  • 429 too_many_requests: troppe richieste, superato il limite di frequenza.
  • 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 API è completamente compatibile con l’interfaccia ModelEntity della Fish Audio OpenAPI ufficiale, permettendo di migrare il codice di gestione dei modelli vocali clonati esistente senza modifiche. L’_id del modello creato può essere utilizzato direttamente come valore del campo reference_id nella Fish TTS API per la sintesi vocale.