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.acedata.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 Ace Data 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.acedata.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
}

Example 2: Fuzzy Search by Title (`title`)

curl -G 'https://api.acedata.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.acedata.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.acedata.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.

Getting Started

Core Concepts

Integrations

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Coding

More guides

Fish Model Query API Integration Guide

Application Process

Query Parameters

Example 2: Fuzzy Search by Title (`title`)

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

Example 4: Filter by language + tag

Response Fields

Billing Information

Error Handling

Conclusion

​Application Process

​Query Parameters

​Example 1: Default Pagination (by page_size)

​Example 2: Fuzzy Search by Title (title)

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

​Example 4: Filter by language + tag

​Response Fields

​Billing Information

​Error Handling

​Conclusion

Application Process

Query Parameters

Example 1: Default Pagination (by `page_size`)

Example 2: Fuzzy Search by Title (`title`)

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

Example 4: Filter by language + tag

Response Fields

Billing Information

Error Handling

Conclusion