Saltar para o conteúdo principal

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.

Este documento apresenta as instruções para integração da API Fish Model Query (GET /fish/model), que é totalmente compatível com a Fish Audio OpenAPI oficial. Esta API é usada para consultar paginadamente a lista de timbres clonados visíveis para a conta atual ou para toda a plataforma.
Para criar timbres, consulte a Fish Model Create API. Para consultar detalhes de um timbre específico pelo _id, consulte a Fish Model Get API.

​
Processo de Solicitação

Para usar a API, é necessário solicitar o serviço correspondente na página da Fish Model API. 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, onde poderá se registrar e entrar. Após o login ou 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.
  • Estrutura da resposta: a resposta paginada do Fish é repassada diretamente, sem envelope adicional da plataforma; em caso de erro, é usado o formato padrão da plataforma {success:false, error:{code,message}, trace_id}.

​
Exemplo de Requisição

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

Idênticos aos da Fish oficial:
  • page_size: número de itens por página, padrão 10.
  • page_number: número da página, começando em 1.
  • title: busca por título com correspondência parcial.
  • tag: filtro por tag.
  • self: se true, retorna apenas os timbres criados pela conta atual.
  • author_id: filtro por criador.
  • language: filtro por idioma do timbre.
  • title_language: filtro por idioma do título.

​
Exemplo de Resposta

Resposta bem-sucedida repassa diretamente a estrutura paginada da plataforma 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
}
O _id retornado pode ser usado como valor do campo reference_id na Fish TTS API para síntese de voz utilizando o timbre clonado.

​
Informações sobre Cobrança

Esta API não gera cobrança — a consulta paginada da lista de timbres é gratuita. Apenas o POST /fish/model com o campo voices no corpo da requisição para criar novos timbres 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.
  • 429 too_many_requests: limite de taxa da conta excedido.
  • 500 api_error: erro interno do servidor.

​
Exemplo de Resposta de Erro

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

​
Conclusão

A Fish Model Query API oferece capacidade de busca de timbres totalmente compatível com a Fish Audio oficial, permitindo a manutenção de uma biblioteca própria de timbres clonados nesta plataforma. Em conjunto com a Fish Model Get API, é possível obter detalhes completos de um timbre específico pelo seu ID.