Instruções de Integração da API de Consulta de Modelos Fish

Esta API é baseada na API oficial de Modelos Fish Audio e é usada para recuperar de forma paginada a biblioteca pública de vozes Fish ou as vozes clonadas na conta atual. O endereço é GET https://api.acedata.cloud/fish/model.

Para criar uma voz, consulte a API Fish Model Create; para consultar os detalhes de uma única voz por _id, consulte a API Fish Model Get.

Processo de solicitação

Para usar a API Fish Model, primeiro obtenha seu API Token no Console Ace Data Cloud e guarde-o para uso posterior.

Se você ainda não tiver feito login ou se registrado, será redirecionado automaticamente para a página de login para se registrar e fazer login; após a conclusão, você retornará automaticamente à página atual. Um único API Token pode chamar todos os serviços da plataforma, sem necessidade de solicitar um separadamente para cada serviço. A primeira solicitação concederá créditos gratuitos, permitindo uma experiência gratuita; quando os créditos forem insuficientes, você poderá 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 em 1.
`title`	string	—	Pesquisa aproximada por título.
`tag`	string	—	Filtra por uma única tag.
`self`	boolean	—	Quando `true`, retorna apenas as vozes criadas e salvas pela conta de chamada atual através desta plataforma.
`author_id`	string	—	Filtra pelo ID do autor da voz.
`language`	string	—	Filtra pelo idioma da voz, como `en`, `zh`, `es`.
`title_language`	string	—	Filtra pelo idioma do título na biblioteca pública de vozes.
`sort_by`	string	—	Campo de ordenação; quando `self=true`, suporta `created_at`, `task_count`.

A nomenclatura dos parâmetros é totalmente consistente com o upstream GET https://api.fish.audio/model; consulte a documentação oficial do Fish para detalhes.

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, o total da biblioteca pública é de aproximadamente 1,8 milhão de itens; alguns campos longos foram omitidos no exemplo abaixo para legibilidade):

{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "A mature and authoritative male voice with a calm, spiritual tone...",
      "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 aproximada 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
}

Observe que title é uma «correspondência aproximada global», correspondendo simultaneamente a todas as vozes da biblioteca pública Fish (não apenas às próprias).

Exemplo 3: Listar apenas as vozes criadas por você (`self=true`)

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

Exemplo de retorno:

{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "smoke test from 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": false
}

self=true lista as vozes criadas e salvas através desta plataforma pela conta efetivamente utilizada na chamada; vozes criadas pela mesma conta usando diferentes API Tokens também serão listadas juntas. Os resultados são paginados em ordem decrescente de tempo de criação, e author_id pode filtrar ainda mais o ID do autor dessas vozes. Este parâmetro filtra apenas a lista; as vozes continuam publicamente disponíveis. self=true não oferece suporte a title_language; se precisar pesquisar por idioma do título, consulte a biblioteca pública de vozes.

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'

A origem também retorna resultados para tag que não estejam no dicionário de tags, mas a correspondência é relativamente ampla; se o número de correspondências for 0, recomenda-se usar correspondência aproximada por 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	Status de treinamento: `trained` indica que está disponível.
`tags`	string[]	Tags da biblioteca pública.
`languages`	string[]	Idiomas em que a voz se destaca.
`visibility`	string	`public` ou `private`.
`samples`	object[]	Amostras predefinidas (inclui link direto para `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 da voz: `_id` / `nickname` / `avatar`.
`total`（nível superior）	integer	Número total de itens que atendem às condições.
`has_more`	boolean?	É um valor booleano quando `self=true`; a consulta à biblioteca pública de vozes pode ser `null`.

Descrição de cobrança

Esta interface não é cobrada — consultar paginadamente a lista de vozes é uma operação gratuita. Criar vozes (Fish Model Create) também é gratuito; os custos são gerados apenas conforme o uso ao chamar Fish TTS para sintetizar fala.

Tratamento de erros

400 token_mismatched: parâmetros da solicitação ausentes ou inválidos.
401 invalid_token: o token de autenticação não existe ou é inválido.
429 too_many_requests: o limite de taxa da conta foi 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 vozes da biblioteca pública do Fish e fornecê-las ao reference_id de /fish/tts, primeiro use esta interface em conjunto com title / tag / language para pesquisar, localize o _id desejado e, em seguida, use Fish Model Get para obter amostras e ouvi-las. 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

Coding

Mais guias

Instruções de Integração da API de Consulta de Modelos Fish

Processo de solicitação

Parâmetros de consulta

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

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

Exemplo 3: Listar apenas as vozes criadas por você (`self=true`)

Exemplo 4: Filtrar por idioma + tag

Campos de resposta

Descrição 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 aproximada por título (title)

​Exemplo 3: Listar apenas as vozes criadas por você (self=true)

​Exemplo 4: Filtrar por idioma + tag

​Campos de resposta

​Descrição 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 aproximada por título (`title`)

Exemplo 3: Listar apenas as vozes criadas por você (`self=true`)

Exemplo 4: Filtrar por idioma + tag

Campos de resposta

Descrição de cobrança

Tratamento de erros

Conclusão