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

> Fish music generation 集成指南 - XHuoAPI

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

> Для создания голосов смотрите [Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a), для запроса деталей одного голоса по `_id` смотрите [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9).

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

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

Если вы не вошли в систему или не зарегистрированы, вас автоматически перенаправят на страницу входа, где можно зарегистрироваться и войти. После входа вы автоматически вернётесь на текущую страницу.

При первом запросе предоставляется бесплатный лимит, позволяющий бесплатно использовать данный API.

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

* **Метод аутентификации**: используется `Authorization: Bearer {token}`, где `{token}` — ключ, полученный на нашей платформе.
* **Структура ответа**: ответ с постраничными данными напрямую передаётся с Fish без дополнительной оболочки платформы; в случае ошибки используется стандартная структура платформы `{success:false, error:{code,message}, trace_id}`.

## Пример запроса

```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 API:

* `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
}
```

Возвращаемый `_id` может использоваться в дальнейшем в поле `reference_id` [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) для синтеза речи с использованием данного клонированного голоса.

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

Данный интерфейс не тарифицируется — постраничный запрос списка голосов является бесплатной операцией. Оплата взимается только при создании нового голоса через `POST /fish/model` с полем `voices` в теле запроса.

## Обработка ошибок

* `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 Query API предоставляет полностью совместимый с официальным Fish Audio функционал поиска голосов, позволяя поддерживать собственную библиотеку клонированных голосов на платформе. В сочетании с [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9) можно получить полные детали отдельного голоса по ID.