Vai al contenuto principale
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.acedata.cloud/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.acedata.cloud/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.