Fish Model Query API Integration Instructions

Esta interface é baseada na API Model do Fish Audio e é utilizada para pesquisar em páginas a biblioteca pública de timbres do Fish ou os timbres clonados da conta atual. O endereço é GET https://api.acedata.cloud/fish/model.

Para criar timbres, consulte a API Fish Model Create; para consultar os detalhes de um único timbre por _id, consulte a API Fish Model Get.

Processo de Solicitação

Para usar a API Fish Model, primeiro acesse o console da Ace Data Cloud para obter seu Token API, que deve ser guardado para uso futuro.

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será redirecionado de volta para a página atual. Um Token API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço individualmente. A primeira solicitação oferece um crédito gratuito, permitindo uma experiência sem custo; quando o crédito estiver baixo, você pode recarregar o saldo geral no console.

📘 Documentação completa: Fish Model API →

Parâmetros de Consulta

Parâmetro	Tipo	Padrão	Descrição
`page_size`	integer	10	Número de itens por página.
`page_number`	integer	1	Número da página começando de 1.
`title`	string	—	Pesquisa difusa por título.
`tag`	string	—	Filtra por um único tag.
`self`	boolean	—	Quando `true`, retorna apenas os timbres criados pela conta atual, sem necessidade de condições adicionais.
`author_id`	string	—	Filtra por `_id` do usuário upstream.
`language`	string	—	Filtra por idioma do timbre, como `en`, `zh`, `es`.
`title_language`	string	—	Filtra por idioma do título.
`sort_by`	string	—	Campo de ordenação, igual ao upstream, como `created_at`, `task_count`.

A nomenclatura dos parâmetros é idêntica à do GET https://api.fish.audio/model, consulte a documentação oficial do Fish.

Exemplo 1: Paginação padrão (por `page_size`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=2'

Retorno (testado, total de itens na biblioteca pública é cerca de 1,8 milhões; para legibilidade, alguns campos longos foram omitidos):

{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "Uma voz masculina madura e autoritária com um tom calmo e espiritual...",
      "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
      "train_mode": "fast",
      "state": "trained",
      "tags": ["male", "old", "narration", "calm", "Spanish"],
      "samples": [
        {
          "title": "Default Sample",
          "text": "Hermanos míos, recordemos las palabras del Señor...",
          "task_id": "59ce7df6935c42249759327ddf70f37b",
          "audio": "https://platform.r2.fish.audio/task/59ce7df6935c42249759327ddf70f37b.mp3"
        }
      ],
      "languages": ["es"],
      "visibility": "public",
      "like_count": 4344,
      "task_count": 708461,
      "author": {
        "_id": "1b82fb6a329c4462b67aa9ee0a42046f",
        "nickname": "Fernando Caicedo"
      }
    },
    {
      "_id": "90e65eaaf50e4470b8e6d43ee6afd7d5",
      "type": "tts",
      "title": "Super Smash Bros. 4/Ultimate Announcer",
      "tags": ["male", "old", "announcer", "gaming", "cinematic"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

Exemplo 2: Pesquisa difusa por título (`title`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'title=narration' \
  --data-urlencode 'page_size=2'

Retorno (testado):

{
  "total": 161,
  "items": [
    {
      "_id": "fb8fe4a94658429d9be70efd4eec35a2",
      "type": "tts",
      "title": "Miles Morales ( Narration Paw )",
      "tags": ["male", "middle-aged", "entertainment", "storytelling", "Children's Content"],
      "languages": ["en"],
      "visibility": "public",
      "task_count": 770
    },
    {
      "_id": "76b55591c758444cb95253708696dfad",
      "type": "tts",
      "title": "Joe NARRATION",
      "tags": ["male", "middle-aged", "narration", "deep", "raspy"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

Note que title é uma “correspondência difusa global”, que atingirá todos os timbres da biblioteca pública do Fish (não apenas os seus).

Exemplo 3: Listar apenas os timbres que você criou (`self=true`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'self=true' \
  --data-urlencode 'page_size=5'

Retorno (testado, a conta atual possui apenas 1 timbre):

{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "teste de fumaça do api.acedata.cloud",
      "state": "trained",
      "languages": ["zh"],
      "visibility": "public",
      "samples": [
        {
          "title": "Default Sample",
          "text": "师父，[语气坚定]我真的受够了这山上的清冷日子！...",
          "task_id": "6a1bf398dfae49dca0e23159214342a0",
          "audio": "https://platform.r2.fish.audio/task/6a1bf398dfae49dca0e23159214342a0.mp3"
        }
      ],
      "created_at": "2026-05-10T03:52:55.601000Z",
      "author": {
        "_id": "780f2b2f862d41a08c0507bbbda77eb6",
        "nickname": "Penny Conrad"
      }
    }
  ],
  "has_more": null
}

self=true é equivalente a filtrar author_id == ID upstream da conta atual, sendo uma entrada comum para “minha lista de timbres”.

Exemplo 4: Filtrar por idioma + tag

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'language=zh' \
  --data-urlencode 'tag=narration' \
  --data-urlencode 'page_size=5'

O upstream também retornará resultados para tag que não estão no dicionário de tags, mas a correspondência é relativamente flexível; se o número de correspondências for 0, recomenda-se usar a correspondência difusa de title.

Campos de Resposta

Cada item em items[] é um objeto ModelEntity completo, campos comuns:

Campo	Tipo	Descrição
`_id`	string	ID da voz, usado como valor de `reference_id` em `/fish/tts`.
`type`	string	Tipo de modelo, geralmente `tts`.
`title`	string	Nome da voz.
`description`	string	Descrição da voz.
`state`	string	Estado de treinamento: `trained` significa disponível.
`tags`	string[]	Tags da biblioteca pública.
`languages`	string[]	Idiomas em que a voz é especializada.
`visibility`	string	`public` ou `private`.
`samples`	object[]	Amostras pré-definidas (inclui link direto de `audio`).
`like_count`	integer	Número de curtidas na biblioteca pública.
`task_count`	integer	Número de sínteses históricas.
`author`	object	Informações do autor upstream: `_id` / `nickname` / `avatar`.
`total` (nível superior)	integer	Número total de itens que atendem aos critérios.
`has_more`	boolean?	Indicação de paginação upstream, pode ser `null`. Recomenda-se calcular o total de páginas usando `total / page_size`.

Instruções de Cobrança

Esta interface não gera cobrança — a consulta de lista de vozes paginada é uma operação gratuita. A criação de vozes (Fish Model Create) também é gratuita, a cobrança ocorre apenas ao chamar Fish TTS para sintetizar voz com base no uso.

Tratamento de Erros

400 token_mismatched: Parâmetros de solicitação ausentes ou inválidos.
401 invalid_token: Token de autenticação inexistente ou inválido.
429 too_many_requests: Limite de taxa da conta acionado.
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

Para selecionar uma voz da biblioteca pública Fish para alimentar o reference_id de /fish/tts, primeiro use esta interface em conjunto com title / tag / language para pesquisar, localize o _id alvo e, em seguida, use Fish Model Get para obter amostras para audição. Para listar as vozes que você criou, basta passar self=true.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

Coding

Fish Model Query API Integration Instructions

Processo de Solicitação

Parâmetros de Consulta

Exemplo 1: Paginação padrão (por `page_size`)

Exemplo 2: Pesquisa difusa por título (`title`)

Exemplo 3: Listar apenas os timbres que você criou (`self=true`)

Exemplo 4: Filtrar por idioma + tag

Campos de Resposta

Instruções de Cobrança

Tratamento de Erros

Conclusão

​Processo de Solicitação

​Parâmetros de Consulta

​Exemplo 1: Paginação padrão (por page_size)

​Exemplo 2: Pesquisa difusa por título (title)

​Exemplo 3: Listar apenas os timbres que você criou (self=true)

​Exemplo 4: Filtrar por idioma + tag

​Campos de Resposta

​Instruções de Cobrança

​Tratamento de Erros

​Conclusão

Processo de Solicitação

Parâmetros de Consulta

Exemplo 1: Paginação padrão (por `page_size`)

Exemplo 2: Pesquisa difusa por título (`title`)

Exemplo 3: Listar apenas os timbres que você criou (`self=true`)

Exemplo 4: Filtrar por idioma + tag

Campos de Resposta

Instruções de Cobrança

Tratamento de Erros

Conclusão