> ## 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.

# Istruzioni per l'integrazione dell'API Fish Model Get

> Fish music generation 集成指南 - XHuoAPI

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](https://docs.fish.audio/resources/api-reference/model), 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](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a); per la ricerca tramite paginazione, consultare [Fish Model Query API](https://api.xhuoapi.ai/documents/5a9b3e03-2896-5606-a6b9-d9f4469f0e9d).

## Processo di richiesta

Per utilizzare l'API, è necessario prima richiedere il servizio corrispondente alla pagina [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509). 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](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a) o tramite ricerca paginata con [Fish Model Query API](https://api.xhuoapi.ai/documents/5a9b3e03-2896-5606-a6b9-d9f4469f0e9d).

## Esempio di richiesta

```shell theme={null}
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:

```json theme={null}
{
  "_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](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) 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

```json theme={null}
{
  "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](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) per completare il flusso end-to-end di clonazione e sintesi.