Инструкция по интеграции Fish Model Query API

Данный интерфейс основан на официальном Model API Fish Audio и предназначен для постраничного поиска в публичной библиотеке голосов Fish или среди клонированных голосов текущего аккаунта. Адрес: GET https://api.acedata.cloud/fish/model.

Для создания голоса обратитесь к Fish Model Create API; для запроса сведений об одном голосе по _id обратитесь к Fish Model Get API。

Процесс получения

Чтобы использовать Fish Model API, сначала получите ваш API Token в консоли Ace Data Cloud и сохраните его для дальнейшего использования.

Если вы ещё не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа, где вам будет предложено зарегистрироваться и войти; после завершения вы автоматически вернётесь на текущую страницу. Один API Token позволяет вызывать все сервисы платформы, и не требуется подавать отдельную заявку для каждого сервиса. При первом получении предоставляется бесплатная квота для бесплатного ознакомления; при недостатке квоты вы можете пополнить общий баланс в консоли.

📘 Полная документация: Fish Model API →

Параметры запроса

Параметр	Тип	По умолчанию	Описание
`page_size`	integer	10	Количество записей на странице.
`page_number`	integer	1	Номер страницы, начиная с 1.
`title`	string	—	Нечёткий поиск по названию.
`tag`	string	—	Фильтрация по одному тегу.
`self`	boolean	—	При `true` возвращает только голоса, созданные и сохранённые текущим вызывающим аккаунтом через данную платформу.
`author_id`	string	—	Фильтрация по ID автора голоса.
`language`	string	—	Фильтрация по языку голоса, например `en`, `zh`, `es`.
`title_language`	string	—	Фильтрация по языку названия в публичной библиотеке голосов.
`sort_by`	string	—	Поле сортировки; при `self=true` поддерживаются `created_at`, `task_count`.

Имена параметров полностью совпадают с вышестоящим GET https://api.fish.audio/model; подробности см. в официальной документации Fish。

Пример 1: постраничный вывод по умолчанию (по `page_size`)

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

Ответ (проверено на практике, общий объём публичной библиотеки составляет около 1,8 млн записей; для удобства чтения в примере ниже опущены некоторые длинные поля):

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

Пример 2: нечёткий поиск по названию (`title`)

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

Ответ (проверено на практике):

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

Обратите внимание, что title — это «глобальное нечёткое сопоставление», которое одновременно находит все голоса в публичной библиотеке Fish (не только собственные).

Пример 3: вывести только голоса, созданные вами (`self=true`)

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

Пример ответа:

{
  "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 выводит голоса, созданные и сохранённые через эту платформу для фактически вызывающего аккаунта; голоса, созданные одним и тем же аккаунтом с использованием разных API Token, также будут перечислены вместе. Результаты постранично сортируются по времени создания в обратном порядке, author_id может дополнительно фильтровать ID автора этих голосов. Этот параметр фильтрует только список, голоса по-прежнему доступны публично. self=true не поддерживает title_language; если требуется поиск по языку названия, выполните запрос к публичной библиотеке голосов.

Пример 4: фильтрация по языку + тегу

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'

Вышестоящий сервис также возвращает результаты для tag, отсутствующих в словаре тегов, однако сопоставление относительно неточное; если количество совпадений равно 0, рекомендуется использовать нечёткое сопоставление по title.

Поля ответа

Каждый элемент в items[] является полным объектом ModelEntity, часто используемые поля:

Поле	Тип	Описание
`_id`	string	ID голоса, используемый как значение `reference_id` в `/fish/tts`.
`type`	string	Тип модели, обычно `tts`.
`title`	string	Название голоса.
`description`	string	Описание голоса.
`state`	string	Статус обучения: `trained` означает, что голос доступен.
`tags`	string[]	Теги публичной библиотеки.
`languages`	string[]	Языки, в которых голос наиболее хорош.
`visibility`	string	`public` или `private`.
`samples`	object[]	Предустановленные образцы (включая прямую ссылку `audio`).
`like_count`	integer	Количество лайков в публичной библиотеке.
`task_count`	integer	Количество исторических синтезов.
`author`	object	Информация об авторе голоса: `_id` / `nickname` / `avatar`.
`total`（верхний уровень）	integer	Общее количество записей, соответствующих условиям.
`has_more`	boolean?	При `self=true` является булевым значением; запросы к публичной библиотеке голосов могут возвращать `null`.

Описание тарификации

Этот интерфейс не тарифицируется — постраничный запрос списка голосов является бесплатной операцией. Создание голосов (Fish Model Create) также бесплатно, расходы возникают только при вызове Fish TTS для синтеза речи в зависимости от использования.

Обработка ошибок

400 token_mismatched: параметры запроса отсутствуют или недопустимы.
401 invalid_token: токен авторизации не существует или недействителен.
429 too_many_requests: сработало ограничение скорости для аккаунта.
500 api_error: внутренняя ошибка сервера.

Пример ответа с ошибкой:

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

Заключение

Чтобы выбрать голос из публичной библиотеки Fish и передать его в reference_id для /fish/tts, сначала используйте этот интерфейс вместе с title / tag / language для поиска, найдите целевой _id, затем используйте Fish Model Get, чтобы получить образцы для прослушивания. Чтобы вывести созданные вами голоса, достаточно передать self=true.

Начало работы

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Coding

Другие руководства

Инструкция по интеграции Fish Model Query API

Процесс получения

Параметры запроса

Пример 1: постраничный вывод по умолчанию (по `page_size`)

Пример 2: нечёткий поиск по названию (`title`)

Пример 3: вывести только голоса, созданные вами (`self=true`)

Пример 4: фильтрация по языку + тегу

Поля ответа

Описание тарификации

Обработка ошибок

Заключение

​Процесс получения

​Параметры запроса

​Пример 1: постраничный вывод по умолчанию (по page_size)

​Пример 2: нечёткий поиск по названию (title)

​Пример 3: вывести только голоса, созданные вами (self=true)

​Пример 4: фильтрация по языку + тегу

​Поля ответа

​Описание тарификации

​Обработка ошибок

​Заключение

Процесс получения

Параметры запроса

Пример 1: постраничный вывод по умолчанию (по `page_size`)

Пример 2: нечёткий поиск по названию (`title`)

Пример 3: вывести только голоса, созданные вами (`self=true`)

Пример 4: фильтрация по языку + тегу

Поля ответа

Описание тарификации

Обработка ошибок

Заключение