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

Цей інтерфейс базується на Fish Audio офіційному Model API і використовується для пагінації пошуку 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	—	Поле для сортування, таке ж, як у попередніх запитах, наприклад, `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": "Досвідчений і авторитетний чоловічий голос з спокійним, духовним тоном...",
      "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'

Відповідь (на основі тестування, під поточним акаунтом лише 1 звук):

{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "тест диму з 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": null
}

self=true еквівалентно фільтрації author_id == поточний акаунт, це звичайний вхід для «списку моїх звуків».

Приклад 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?	Індикація пагінації, може бути `null`. Рекомендується використовувати `total / page_size` для обчислення загальної кількості сторінок.

Опис оплати

Цей інтерфейс не підлягає оплаті — пагінований запит списку голосів є безкоштовною операцією. Створення голосу (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 для передачі його в /fish/tts як reference_id, спочатку використовуйте цей інтерфейс у поєднанні з title / tag / language для пошуку, щоб знайти цільовий _id, а потім використовуйте Fish Model Get для прослуховування зразків. Щоб перерахувати створені вами голоси, передайте self=true.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Проксі

Advanced

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

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

Опис оплати

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

Висновок