Перейти к основному содержанию

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. Включает:
  • POST /fish/model: создание нового клонированного голосового профиля (Voice Model) на основе аудиопробы.
  • GET /fish/model: постраничный запрос списка голосовых профилей, доступных для текущего аккаунта или на всей платформе.

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

Для использования API необходимо сначала подать заявку на соответствующую услугу на странице Fish Model API, нажав кнопку «Acquire». Если вы не вошли в систему или не зарегистрированы, будет выполнен автоматический переход на страницу входа с приглашением зарегистрироваться и войти. После входа или регистрации вы автоматически вернетесь на текущую страницу. При первом запросе предоставляется бесплатный лимит для использования API.

​
Отличия от официального API

  • Метод аутентификации: используется Authorization: Bearer {token}, где {token} — ключ, полученный на данной платформе.
  • Загрузка образцов при создании модели: данный интерфейс поддерживает только отправку 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):
  • 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
}

​
Информация о тарификации

Оплата взимается только при создании голосового профиля (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 официального OpenAPI Fish Audio, что позволяет мигрировать существующий код управления клонированными голосами без изменений. Созданный голосовой профиль _id можно напрямую использовать в поле reference_id Fish TTS API для синтеза речи.