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

> Fish music generation 集成指南 - XHuoAPI

Este documento apresenta as instruções para integração da API Fish Model, que é totalmente compatível com a [OpenAPI oficial do Fish Audio](https://docs.fish.audio/resources/api-reference/model), incluindo:

* `POST /fish/model`: Cria um novo modelo de voz (Voice Model) baseado em amostras de áudio.
* `GET /fish/model`: Consulta paginada da lista de modelos de voz visíveis para a conta atual ou para toda a plataforma.

## Processo de Solicitação

Para usar a API, é necessário solicitar o serviço correspondente na página do [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 fazer login. Após o login/registro, você será redirecionado automaticamente para a página atual.

Na primeira solicitação, será concedida uma cota gratuita para uso da API.

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

* **Método de autenticação**: Utiliza `Authorization: Bearer {token}`, onde `{token}` é a chave obtida nesta plataforma.
* **Upload das amostras ao criar o modelo**: Atualmente, esta API suporta apenas o envio em formato JSON, passando as URLs das amostras de áudio pelo campo `voices`. A API oficial do Fish suporta upload direto de binários via multipart/msgpack, recurso ainda não implementado aqui, mas o envio via URL cobre cerca de 80% dos casos comuns.
* **Estrutura da resposta**: Tanto `POST /fish/model` quanto `GET /fish/model` retornam diretamente a resposta da plataforma Fish, sem encapsulamento adicional. Em caso de erro, utiliza a estrutura padrão da plataforma `{success:false, error:{code,message}, trace_id}`.

## Criar Modelo de Voz (POST /fish/model)

A requisição mínima para criação requer os campos `title` e `voices`. `voices` é uma lista de URLs das amostras de áudio, recomendando-se arquivos com mais de 30 segundos e taxa de amostragem de 16k ou superior.

```shell theme={null}
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": "Meu modelo clonado",
    "description": "Modelo clonado a partir de uma gravação de podcast",
    "voices": [
      "https://example.com/sample-voice.mp3"
    ],
    "cover_image": "https://example.com/cover.png",
    "visibility": "private"
  }'
```

A resposta de sucesso retorna diretamente o objeto ModelEntity da plataforma Fish:

```json theme={null}
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "Meu modelo clonado",
  "description": "Modelo clonado a partir de uma gravação de podcast",
  "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"
  }
}
```

O `_id` retornado pode ser usado como valor do campo `reference_id` em chamadas subsequentes para `POST /fish/tts` para síntese de voz com o modelo clonado.

## Consultar Lista de Modelos de Voz (GET /fish/model)

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

Parâmetros de consulta disponíveis (compatíveis com a API oficial do Fish):

* `page_size`: número de itens por página, padrão 10.
* `page_number`: número da página, iniciando em 1.
* `title`: busca por título com correspondência parcial.
* `tag`: filtro por etiqueta.
* `self`: se `true`, retorna apenas modelos criados pela conta atual.
* `author_id`: filtro por autor.
* `language`: filtro por idioma do modelo.
* `title_language`: filtro por idioma do título.

A resposta de sucesso também é repassada diretamente com a estrutura paginada da plataforma Fish:

```json theme={null}
{
  "items": [
    {
      "_id": "d7900c21663f485ab63ebdb7e5905036",
      "title": "Meu modelo clonado",
      "description": "Modelo clonado a partir de uma gravação de podcast",
      "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
}
```

## Informações sobre Cobrança

Esta API cobra apenas pela criação de modelos de voz (`POST /fish/model` com o campo `voices` no corpo da requisição). Consultas à lista de modelos (`GET /fish/model`) são gratuitas.

## Tratamento de Erros

* `400 token_mismatched`: Requisição inválida, possivelmente por parâmetros ausentes ou inválidos.
* `400 api_not_implemented`: Requisição inválida, possivelmente por parâmetros ausentes ou inválidos.
* `401 invalid_token`: Não autorizado, token de autorização inválido ou ausente.
* `429 too_many_requests`: Muitas requisições, limite de taxa 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 API Fish Model é totalmente compatível com a interface ModelEntity da OpenAPI oficial do Fish Audio, permitindo migrar códigos existentes de gerenciamento de modelos clonados sem necessidade de alterações. O `_id` do modelo criado pode ser diretamente utilizado no campo `reference_id` da [API Fish TTS](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) para síntese de voz.