Fish Model Query API Integration Guide

This API is based on the Fish Audio official Model API, and is used to paginate and retrieve the Fish public voice library or cloned voices under the current account. The endpoint is GET https://api.fishapi.cloud/fish/model.

To create a voice, please refer to Fish Model Create API; to query details of a single voice by _id, please refer to Fish Model Get API.

Application Process

To use the Fish Model API, first go to the Fishapi Cloud Console to obtain your API Token and keep it for later use.

If you have not yet logged in or registered, you will be automatically redirected to the login page and invited to register and log in. After completion, you will automatically return to the current page.

One API Token can call all platform services; there is no need to apply separately for each service. Your first application includes free credits for a free trial; when credits are insufficient, you can recharge your general balance in the console.

📘 Full documentation: Fish Model API →

Query Parameters

Parameter Type Default Description
page_size integer 10 Number of items per page.
page_number integer 1 Page number starting from 1.
title string — Fuzzy search by title.
tag string — Filter by a single tag.
self boolean — When true, returns only voices created and saved through this platform by the current calling account.
author_id string — Filter by voice author ID.
language string — Filter by voice language, such as en, zh, es.
title_language string — Filter by title language in the public voice library.
sort_by string — Sort field; when self=true, supports created_at and task_count.

The parameter names are fully consistent with the upstream GET https://api.fish.audio/model. For details, see the Fish official documentation.

Example 1: Default Pagination (by page_size)

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

Response (tested; the public library contains approximately 1.8 million entries; some long fields are omitted in the example below for readability):

{
  "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
}

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

Response (tested):

{
  "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 that title is a “global fuzzy match”, which will match all voices in the Fish public library at the same time (not only your own).

Example 3: List Only Voices Created by Yourself (self=true)

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

Response example:

{
  "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 lists the voices created and saved through this platform by the actual calling account; voices created by the same account using different API Tokens will also be listed together. Results are paginated in reverse chronological order by creation time, and author_id can further filter the author ID of these voices. This parameter only filters the list; the voices remain publicly available.

self=true does not support title_language; if you need to search by title language, please query the public voice library.

Example 4: Filter by language + tag

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

The upstream will also return results for tag values not in the tag dictionary, but the matching is relatively loose; if the number of matches is 0, it is recommended to use fuzzy matching with title instead.

Response Fields

Each item in items[] is a complete ModelEntity object. Common fields include:

Field Type Description
_id string Voice ID, used as the value of reference_id in /fish/tts.
type string Model type, usually tts.
title string Voice name.
description string Voice description.
state string Training status: trained indicates availability.
tags string[] Public library tags.
languages string[] Languages the voice is proficient in.
visibility string public or private.
samples object[] Preset samples (including direct audio links).
like_count integer Number of likes in the public library.
task_count integer Number of historical synthesis requests.
author object Voice author information: _id / nickname / avatar.
total (top level) integer Total number of items matching the criteria.
has_more boolean? A boolean when self=true; may be null for public voice library queries.

Billing Information

This API is not billed—paginated voice list queries are free operations. Creating voices (Fish Model Create) is also free. Charges are incurred only based on usage when calling Fish TTS to synthesize speech.

Error Handling

  • 400 token_mismatched: Request parameters are missing or invalid.
  • 401 invalid_token: The authentication token does not exist or is invalid.
  • 429 too_many_requests: The account rate limit has been triggered.
  • 500 api_error: Internal server error.

Error response example:

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

Conclusion

To select a voice from the Fish public library for the reference_id of /fish/tts, first use this API with title / tag / language to search, identify the target _id, and then use Fish Model Get to retrieve samples for listening. To list voices you created yourself, simply pass self=true.