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 presenta le istruzioni per l’integrazione dell’API Fish Model Get (GET /fish/model/{id}), compatibile al 100% con Fish Audio API OpenAPI ufficiale, utilizzata per ricercare i dettagli completi di un singolo clone di voice tramite ID.
Per creare una voice, fare riferimento a Fish Model Create API; per la ricerca tramite paginazione, consultare Fish Model Query API.

​
Processo di richiesta

Per utilizzare l’API, è necessario prima richiedere il servizio corrispondente alla pagina Fish Model API. Accedendo alla pagina, cliccare sul pulsante “Acquire”. Se non sei ancora loggato o registrato, verrai automaticamente reindirizzato alla pagina di login per registrarti e accedere. Dopo aver effettuato login o registrazione, verrai reindirizzato automaticamente alla pagina corrente. Durante la prima richiesta, viene assegnato un credito gratuito che consente di usare l’API gratuitamente.

​
Differenze rispetto all’API ufficiale

  • Metodo di autenticazione: utilizza Authorization: Bearer {token}, dove {token} è la chiave richiesta sulla piattaforma.
  • Struttura di risposta: trasmette direttamente l’oggetto Fish ModelEntity upstream, senza incapsulamento platform envelope; in caso di errore, utilizza la struttura standard {success:false, error:{code,message}, trace_id}.
  • Parametri di percorso: {id} corrisponde all’_id della voice, che può essere ottenuto durante la creazione tramite Fish Model Create API o tramite ricerca paginata con Fish Model Query API.

​
Esempio di richiesta

curl 'https://api.xhuoapi.ai/v1/fish/model/d7900c21663f485ab63ebdb7e5905036' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}'
Sostituisci semplicemente {id} nel percorso URL con l’ID specifico della voice, senza bisogno di parametri di query o corpo della richiesta.

​
Esempio di risposta

La risposta di successo trasmette direttamente l’oggetto Fish ModelEntity: 
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "La mia voice clonata",
  "description": "Voice clonata da una registrazione podcast",
  "cover_image": "https://example.com/cover.png",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [
    {
      "audio": "https://example.com/sample-voice.mp3",
      "text": ""
    }
  ],
  "created_at": "2025-05-09T12:34:56.789Z",
  "updated_at": "2025-05-09T12:34:56.789Z",
  "languages": ["zh", "en"],
  "visibility": "private",
  "lock_visibility": false,
  "default_text": "",
  "default_mode": "fast",
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "unliked": false,
  "liked": false,
  "marked": false,
  "author": {
    "_id": "00000000000000000000000000000000",
    "nickname": "",
    "avatar": ""
  }
}
L’_id restituito può essere utilizzato come valore del campo reference_id nel Fish TTS API per effettuare la sintesi vocale con questa voice clonata.

​
Note sui costi

Questa API è gratuita — la ricerca dei dettagli di una voice tramite ID è un’operazione gratuita. La creazione di nuove voci tramite POST /fish/model con il campo voices nel corpo della richiesta è l’unica operazione soggetta a costo.

​
Gestione degli errori

  • 400 token_mismatched: parametri mancanti o non validi.
  • 400 api_not_implemented: metodo o parametri non supportati attualmente.
  • 401 invalid_token: mancanza o invalidità delle credenziali di autenticazione.
  • 404 not_found: la voice con _id specificato non esiste o non è visibile dall’account corrente.
  • 429 too_many_requests: superato il limite di richiesta per l’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"
}

​
Conclusioni

L’API Fish Model Get offre una funzionalità di ricerca dettagliata di singole voci, compatibile con l’API ufficiale Fish Audio. Dopo aver ottenuto l’ID della voice, è possibile usare questa API per recuperare l’oggetto completo ModelEntity (inclusi campioni, stato, visibilità, statistiche, ecc.), e combinarla con Fish TTS API per completare il flusso end-to-end di clonazione e sintesi.