Перейти до основного вмісту

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

У цій статті описано інструкцію по інтеграції Fish Model API, який повністю сумісний з офіційним OpenAPI Fish Audio. API включає:
  • POST /fish/model: створення нового клонованого голосу (Voice Model) на основі аудіозразка.
  • GET /fish/model: посторінковий запит списку голосів, доступних для поточного акаунту або всієї платформи.

​
Процес подачі заявки

Для використання API необхідно спочатку подати заявку на відповідний сервіс на сторінці Fish Model API. Після переходу на сторінку натисніть кнопку «Acquire». Якщо ви ще не увійшли або не зареєстровані, вас автоматично перенаправить на сторінку входу для реєстрації або авторизації. Після входу ви повернетесь на поточну сторінку. При першій подачі заявки надається безкоштовний ліміт для використання API.

​
Відмінності від офіційного API

  • Метод автентифікації: використовується Authorization: Bearer {token}, де {token} — це ключ, отриманий на цій платформі.
  • Завантаження зразків при створенні моделі: наразі цей API підтримує лише подачу у форматі JSON із передачею URL аудіозразків у полі voices. Офіційний Fish підтримує multipart/msgpack для прямого завантаження бінарних даних, але ця платформа поки що не реалізувала цю можливість. Формат URL охоплює близько 80% поширених випадків.
  • Структура відповіді: POST /fish/model та GET /fish/model безпосередньо передають відповідь Fish без додаткової обгортки платформи. У разі помилки використовується стандартна структура платформи {success:false, error:{code,message}, trace_id}.

​
Створення голосу (POST /fish/model)

Мінімальний запит на створення потребує два поля: title і voices. voices — список URL аудіозразків, рекомендується, щоб кожен файл був довжиною понад 30 секунд із частотою дискретизації 16 кГц і вище. 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "title": "Мій клонований голос",
    "description": "Голос, клонований з запису подкасту",
    "voices": [
      "https://example.com/sample-voice.mp3"
    ],
    "cover_image": "https://example.com/cover.png",
    "visibility": "private"
  }'
Успішна відповідь повертає об’єкт ModelEntity з платформи Fish: 
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "Мій клонований голос",
  "description": "Голос, клонований з запису подкасту",
  "cover_image": "https://example.com/cover.png",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [],
  "created_at": "2025-05-09T12:34:56.789Z",
  "updated_at": "2025-05-09T12:34:56.789Z",
  "languages": ["zh", "en"],
  "visibility": "private",
  "lock_visibility": false,
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "author": {
    "_id": "user_id",
    "nickname": "user_nickname",
    "avatar": "user_avatar"
  }
}
Повернене поле _id можна використовувати як значення reference_id у наступних запитах POST /fish/tts для синтезу мовлення з цим клонованим голосом.

​
Запит списку голосів (GET /fish/model)

curl -G 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=10' \
  --data-urlencode 'page_number=1' \
  --data-urlencode 'self=true'
Доступні параметри запиту (ідентичні офіційному Fish API):
  • page_size: кількість записів на сторінку, за замовчуванням 10.
  • page_number: номер сторінки, починаючи з 1.
  • title: пошук за назвою (неповний збіг).
  • tag: фільтрація за тегом.
  • self: якщо true, повертає лише голоси, створені поточним акаунтом.
  • author_id: фільтрація за автором.
  • language: фільтрація за мовою голосу.
  • title_language: фільтрація за мовою назви.
Успішна відповідь також безпосередньо передає сторінкову структуру платформи Fish: 
{
  "items": [
    {
      "_id": "d7900c21663f485ab63ebdb7e5905036",
      "title": "Мій клонований голос",
      "description": "Голос, клонований з запису подкасту",
      "cover_image": "https://example.com/cover.png",
      "type": "tts",
      "state": "trained",
      "tags": [],
      "languages": ["zh", "en"],
      "visibility": "private",
      "created_at": "2025-05-09T12:34:56.789Z",
      "updated_at": "2025-05-09T12:34:56.789Z"
    }
  ],
  "total": 1
}

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

Цей API стягує плату лише за створення голосу (POST /fish/model із полем voices у тілі запиту). Запити на отримання списку голосів (GET /fish/model) безкоштовні.

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

  • 400 token_mismatched: Некоректний запит, можливо, через відсутні або неправильні параметри.
  • 400 api_not_implemented: Некоректний запит, можливо, через відсутні або неправильні параметри.
  • 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 Model API повністю сумісний з інтерфейсом ModelEntity офіційного Fish Audio OpenAPI, що дозволяє мігрувати існуючий код управління клонованими голосами без змін у коді. Створений _id голосу можна безпосередньо використовувати у полі reference_id Fish TTS API для синтезу мовлення.