> ## 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`. Це відповідає офіційному Fish.
* **Значення за замовчуванням для `latency`**: upstream `/fish/v1/tts` повертає помилку, якщо `latency` не передано. У цьому інтерфейсі при відсутності параметра автоматично додається `latency=normal`, що відповідає поведінці Fish.
* **Асинхронний callback (розширення платформи)**: якщо в тілі запиту передати додаткове поле `callback_url`, API одразу поверне `{task_id, started_at}`, а після завершення обробки upstream надішле повний результат `{audio_url, ...}` у форматі POST JSON на цей URL. Офіційний Fish не підтримує це поле, і його передача активує асинхронний процес на нашій платформі.

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

## Базове використання

Мінімальний запит потребує лише поле `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:

* `audio_url`: URL згенерованого аудіо, доступний для завантаження або відтворення.
* `latency_ms` (необов’язкове): час обробки upstream у мілісекундах.

Якщо потрібно використовувати клонований голос, додайте в тіло запиту `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

Оскільки генерація Fish TTS для довгих текстів може займати значний час, утримання довгого з’єднання споживає ресурси системи. Цей API пропонує можливість асинхронного callback (розширення порівняно з офіційним Fish).

Загальний процес: клієнт при запиті додає в тіло поле `callback_url`, API одразу повертає відповідь з `task_id`; після завершення генерації upstream відправляє повний результат із `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`.

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

Цей інтерфейс зберігає 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 при генерації довгих текстів для уникнення тривалого утримання з’єднань і споживання ресурсів.