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

# Instruções para Integração da API Fish Model Get

> Fish music generation 集成指南 - XHuoAPI

Este documento apresenta as instruções para integração da API Fish Model Get (`GET /fish/model/{id}`), que é totalmente compatível com a [OpenAPI oficial do Fish Audio](https://docs.fish.audio/resources/api-reference/model) e é usada para **consultar os detalhes completos de um único timbre clonado por ID**.

> Para criação de timbres, consulte a [Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a). Para consultas paginadas, consulte a [Fish Model Query API](https://api.xhuoapi.ai/documents/5a9b3e03-2896-5606-a6b9-d9f4469f0e9d).

## Processo de Solicitação

Para usar a API, é necessário solicitar o serviço correspondente na página da [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509). Após acessar a página, clique no botão "Acquire".

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login para se registrar e entrar. Após o login ou registro, você será redirecionado automaticamente para a página atual.

Na primeira solicitação, há uma cota gratuita concedida, permitindo o uso gratuito da API.

## Diferenças em Relação à API Oficial

* **Método de autenticação**: usa `Authorization: Bearer {token}`, onde `{token}` é a chave obtida nesta plataforma.
* **Estrutura da resposta**: o objeto ModelEntity do Fish é repassado diretamente, sem envelope da plataforma; em caso de erro, é usado o formato padrão da plataforma `{success:false, error:{code,message}, trace_id}`.
* **Parâmetro de caminho**: `{id}` é o `_id` do timbre, que pode ser obtido na resposta da [Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a) ou na consulta paginada da [Fish Model Query API](https://api.xhuoapi.ai/documents/5a9b3e03-2896-5606-a6b9-d9f4469f0e9d).

## Exemplo de Requisição

```shell theme={null}
curl 'https://api.xhuoapi.ai/v1/fish/model/d7900c21663f485ab63ebdb7e5905036' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}'
```

Basta substituir o `{id}` na URL pelo ID específico do timbre, sem necessidade de parâmetros de consulta ou corpo na requisição.

## Exemplo de Resposta

Resposta bem-sucedida repassa diretamente o objeto ModelEntity da plataforma Fish:

```json theme={null}
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "我的克隆音色",
  "description": "用一段播客录音克隆的音色",
  "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": ""
  }
}
```

O `_id` retornado pode ser usado como valor do campo `reference_id` na [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d), para síntese de voz usando este timbre clonado.

## Informações sobre Cobrança

Esta API não gera cobrança — a consulta de detalhes do timbre por ID é gratuita. Apenas o `POST /fish/model` que cria um novo timbre com o campo `voices` no corpo da requisição gera cobrança.

## Tratamento de Erros

* `400 token_mismatched`: parâmetros da requisição ausentes ou inválidos.
* `400 api_not_implemented`: método ou parâmetros da requisição não suportados atualmente.
* `401 invalid_token`: autenticação ausente ou inválida.
* `404 not_found`: timbre com `_id` especificado não existe ou não é visível para a conta atual.
* `429 too_many_requests`: limite de taxa da conta excedido.
* `500 api_error`: erro interno do servidor.

### Exemplo de Resposta de Erro

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Conclusão

A Fish Model Get API oferece a capacidade de consultar detalhes completos de um único timbre, totalmente compatível com o Fish Audio oficial. Após obter o ID do timbre, esta API pode ser usada para recuperar o objeto ModelEntity completo (incluindo amostras, estado, visibilidade, campos estatísticos etc.), que pode ser combinado com a [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) para realizar o fluxo completo de clonagem e síntese de voz.