> ## 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

> Fish music generation 集成指南 - XHuoAPI

В этой статье описывается инструкция по интеграции Fish Model API, который полностью совместим с [официальным OpenAPI Fish Audio](https://docs.fish.audio/resources/api-reference/model). Включает:

* `POST /fish/model`: создание нового клонированного голосового профиля (Voice Model) на основе аудиопробы.
* `GET /fish/model`: постраничный запрос списка голосовых профилей, доступных для текущего аккаунта или на всей платформе.

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

Для использования API необходимо сначала подать заявку на соответствующую услугу на странице [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509), нажав кнопку «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 кГц.

```shell theme={null}
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:

```json theme={null}
{
  "_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)

```shell theme={null}
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:

```json theme={null}
{
  "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`: Внутренняя ошибка сервера.

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

```json theme={null}
{
  "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](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) для синтеза речи.