Інструкція з інтеграції Fish Model Query API

Цей 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, спочатку перейдіть до консолі Ace Data Cloud, щоб отримати свій API Token, і збережіть його для подальшого використання.

Якщо ви ще не увійшли в систему або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу, де вам буде запропоновано зареєструватися та увійти; після завершення ви автоматично повернетеся на поточну сторінку. Один 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.

Getting Started

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: Фільтрація за мовою + тегом

Поля відповіді

Інформація про тарифікацію

Обробка помилок

Висновок