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

> Fish music generation 集成指南 - XHuoAPI

В этой статье описывается инструкция по интеграции Fish TTS API. Этот интерфейс полностью совместим с [официальным OpenAPI Fish Audio](https://docs.fish.audio/text-to-speech/text-to-speech) и позволяет напрямую перенести код, который ранее вызывал `https://api.fish.audio/v1/tts`, на `https://api.xhuoapi.ai/v1/fish/tts`, заменив только данные для аутентификации без необходимости изменения структуры тела запроса.

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

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

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

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

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

Данный API сохраняет поля запроса и ответа официального Fish Audio, но содержит несколько небольших улучшений для лучшей интеграции на нашей платформе:

* **Метод аутентификации**: используется `Authorization: Bearer {token}`, где `{token}` — это ключ, полученный на нашей платформе, а не официальный ключ Fish.
* **Выбор модели TTS**: указывается в HTTP-заголовке `model`, доступные значения — `s1` или `s2-pro`, по умолчанию `s2-pro`. Это совпадает с официальным API Fish.
* **Значение по умолчанию для `latency`**: в официальном API `/fish/v1/tts` при отсутствии параметра `latency` возвращается ошибка, в нашем API при отсутствии этого параметра автоматически подставляется `latency=normal`, что соответствует поведению официального API.
* **Асинхронный callback (расширение платформы)**: при передаче дополнительного поля `callback_url` в теле запроса API сразу возвращает `{task_id, started_at}`, а после завершения обработки отправляет полный результат `{audio_url, ...}` POST-запросом в формате JSON на указанный URL. Официальный API Fish не поддерживает это поле, и его передача активирует только асинхронный процесс на нашей стороне.

Кроме указанных отличий, все поля тела запроса TTS (`text`, `reference_id`, `references`, `prosody`, `format`, `sample_rate`, `mp3_bitrate`, `chunk_length`, `temperature`, `top_p` и др.) напрямую передаются на сервер Fish, поведение полностью соответствует официальной документации.

## Основное использование

Минимальный запрос требует передачи только поля `text`. Пример CURL:

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。"
  }'
```

Пример ответа:

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}
```

Ответ содержит поля официального Fish API, включая:

* `audio_url`: URL сгенерированного аудио, доступного для загрузки или воспроизведения.
* `latency_ms` (опционально): время обработки на сервере в миллисекундах.

Если требуется использовать клон голоса, можно добавить в тело запроса поле `reference_id`:

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "reference_id": "d7900c21663f485ab63ebdb7e5905036",
    "format": "mp3",
    "sample_rate": 44100
  }'
```

## Асинхронный callback

Поскольку генерация речи для длинных текстов может занимать значительное время, а поддержание долгих соединений потребляет ресурсы системы, данный API предоставляет возможность асинхронного callback (расширение по сравнению с официальным API Fish).

Общий процесс: клиент при отправке запроса дополнительно указывает поле `callback_url` в теле запроса, API сразу возвращает ответ с `task_id`; после завершения генерации полный результат с `audio_url` и другими данными отправляется POST-запросом в формате JSON на указанный `callback_url` с тем же `task_id`, что позволяет связать асинхронный результат с исходной задачей.

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

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

Мгновенный ответ:

```json theme={null}
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "started_at": "2025-05-09T12:34:56.789Z"
}
```

Через некоторое время на `callback_url` придет полный результат:

```json theme={null}
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
```

Также можно использовать [Fish Tasks API](https://api.xhuoapi.ai/documents/fc541fac-a941-47fd-b6f7-48d6cb9da523) для активного опроса статуса задачи по `task_id`.

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

API сохраняет HTTP-коды ошибок официального Fish, но тело ответа использует единый формат платформы для согласованности с `/fish/audios` и `/fish/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 TTS API полностью совместим с официальным OpenAPI Fish Audio и позволяет мигрировать существующие проекты без изменений кода, одновременно предоставляя преимущества единой аутентификации, учёта использования и возможности асинхронного callback. Рекомендуется использовать асинхронный callback при генерации длинных текстов, чтобы избежать длительного удержания соединений и расхода ресурсов.