> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Fish TTS API інтеграційна документація

> Fish voice generation API guide - Ace Data Cloud

Цей інтерфейс базується на [Fish Audio офіційному TTS API](https://docs.fish.audio/text-to-speech/text-to-speech), має лише відмінності в методах аутентифікації (використання токена цієї платформи) та асинхронному зворотному виклику (розширення `callback_url`), структура тіла запиту відповідає upstream. Адреса: `POST https://api.acedata.cloud/fish/tts`.

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

Щоб використовувати Fish TTS API, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications) для отримання вашого API токена, зберігайте його для подальшого використання.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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

**Один API токен дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу.** Перший запит на отримання токена надає безкоштовний ліміт для тестування; при недостатньому ліміті ви можете поповнити загальний баланс у [консолі](https://platform.acedata.cloud/console/coin).

> 📘 Повна документація: [Fish TTS API →](https://platform.acedata.cloud/services/fish)

## Заголовки запиту

| Заголовок       | Обов'язковий | Опис                                                                                                                                                                                                                |
| --------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authorization` | Так          | `Bearer {token}`; `{token}` - це ключ, отриманий на цій платформі.                                                                                                                                                  |
| `content-type`  | Так          | `application/json`.                                                                                                                                                                                                 |
| `accept`        | Ні           | `application/json`.                                                                                                                                                                                                 |
| `model`         | Ні           | TTS модель, може бути `s1`, `s2-pro` або `s2.1-pro`, за замовчуванням `s2-pro`. `s2.1-pro` - нове покоління, `s2-pro` - потужніший; `s1` більш стабільний, довгі тексти не відхиляються. Всі три однакові за ціною. |

## Параметри тіла запиту

| Поле           | Тип                 | Обов'язковий | Опис                                                                                                                                                                                                                          |
| -------------- | ------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`         | string              | Так          | Текст для синтезу, непорожній рядок.                                                                                                                                                                                          |
| `format`       | string              | Ні           | Формат виходу аудіо, може бути `mp3` (за замовчуванням), `wav`, `pcm`. `wav` та `pcm` повертають WAV контейнер. `opus` не підтримується, передача призведе до повернення `400`.                                               |
| `reference_id` | string \| string\[] | Ні           | ID клонованого голосу (може бути створений за допомогою [Fish Model API](https://platform.acedata.cloud/documents/fish-model) або отриманий у [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)). |
| `references`   | object\[]           | Ні           | Вбудовані зразки, структура відповідає upstream, кожен елемент містить `audio` та `text`. Один з `reference_id` або `references` має бути присутнім.                                                                          |
| `sample_rate`  | integer             | Ні           | Частота дискретизації, зазвичай `16000`, `22050`, `44100`. `format=mp3` за замовчуванням 44100.                                                                                                                               |
| `mp3_bitrate`  | integer             | Ні           | Бітрейт MP3, може бути `64`, `128`, `192`. Діє лише для `format=mp3`.                                                                                                                                                         |
| `prosody`      | object              | Ні           | Просодія, підтримує `speed` (швидкість мови, 1.0 - оригінальна швидкість) та `volume` (гучність у дБ). Наприклад, `{"speed":1.2,"volume":0}`.                                                                                 |
| `chunk_length` | integer             | Ні           | Довжина фрагмента, за замовчуванням визначається upstream.                                                                                                                                                                    |
| `temperature`  | number              | Ні           | Температура вибірки, в межах приблизно 0.0–1.0.                                                                                                                                                                               |
| `top_p`        | number              | Ні           | Параметр вибірки top-p.                                                                                                                                                                                                       |
| `latency`      | string              | Ні           | `normal` або `balanced`, за замовчуванням автоматично заповнюється `normal` (передача порожнього рядка призведе до відмови upstream).                                                                                         |
| `normalize`    | boolean             | Ні           | Чи потрібно нормалізувати текст.                                                                                                                                                                                              |
| `callback_url` | string              | Ні           | Адреса асинхронного зворотного виклику, див. нижче «Асинхронний зворотний виклик». **Це розширення відносно офіційного інтерфейсу**.                                                                                          |

> Імена полів повністю відповідають upstream. За винятком `callback_url`, інші поля мають значення та значення, що наведені в [Fish офіційній TTS документації](https://docs.fish.audio/text-to-speech/text-to-speech).

## Приклад 1: Мінімальний запит (`text` + `format=mp3`)

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hello world.",
    "format": "mp3"
  }'
```

Відповідь (перевірено):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}
```

`audio_url` вказує на CDN цієї платформи, його можна безпосередньо завантажити за допомогою GET або відтворити в `<audio>`. Посилання доступне на тривалий термін, але все ж рекомендується зберегти копію у вашому власному сховищі.

## Приклад 2: Використання клонованого голосу `reference_id`

Нижче наведено приклад публічного іспанського голосу на платформі Fish (`_id` можна отримати через [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)):

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hermanos míos, hoy es un buen día.",
    "reference_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
    "format": "mp3"
  }'
```

Відповідь (перевірено):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.mp3"
}
```

## Приклад 3: Регулювання швидкості / гучності (`prosody`)

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Faster speech with prosody overrides.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'
```

Відповідь (перевірено):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3"
}
```

`speed` більше 1 прискорює, менше 1 сповільнює; `volume` в дБ, 0 означає без змін, позитивне число - підвищення, негативне - зниження.

## Приклад 4: Перемикання моделі + контроль бітрейту

Через HTTP заголовок `model: s1` перемикаємося на стабільну модель, в тілі запиту додаємо `mp3_bitrate: 128` для контролю бітрейту MP3:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "висока бітрейт mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'
```

Повернення (фактичне):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e.mp3"
}
```

## Приклад 5: PCM сирцевий сигнал

Необхідно в браузері виконати реальне з'єднання або на клієнті виконати подальшу обробку (міксування, зміна швидкості) - рекомендується використовувати `pcm`:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "привіт",
    "format": "pcm",
    "sample_rate": 16000
  }'
```

Повернення (фактичне):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/64adc04b-c196-4a0f-9070-222ba101ce6c.wav"
}
```

> Розширення посилання слідує за `format` у запиті: `mp3` отримує `.mp3`, `wav` та `pcm` отримують `.wav` (контейнер WAV, 16 біт PCM).

## Асинхронний зворотний виклик (`callback_url`)

Довгий текст може потребувати від десяти до кількох десятків секунд для синтезу, якщо з'єднання переривається, потрібно повторити спробу. Передавши `callback_url` у тілі запиту, інтерфейс відразу поверне `{task_id, started_at}`, а коли завдання буде завершено, повний результат буде надіслано POST JSON формою на цей URL, з тим же `task_id` у тілі запиту.

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Сьогодні погода справді хороша, давай вийдемо на прогулянку.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

Відразу повернення (фактичне):

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}
```

Пізніше `callback_url` отримає у вигляді:

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/bd66b8c5-7543-4557-b684-baa72407e336.mp3"
}
```

Також можна використовувати [Fish Tasks API](https://platform.acedata.cloud/documents/fish-tasks) для активного отримання результатів за `task_id`, деталі дивіться в цій документації.

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

* `400 token_mismatched`: відсутні або недійсні параметри запиту (найпоширеніша причина - `text` порожній або `format` має значення, відмінне від `mp3`/`wav`/`pcm`).
* `401 invalid_token`: токен авторизації відсутній або недійсний.
* `429 too_many_requests`: спрацьовування обмеження швидкості облікового запису.
* `500 api_error`: внутрішня помилка сервера.

Приклад помилкового відповіді:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "отримання не вдалося"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

Помилки валідації параметрів міститимуть оригінальний текст помилки pydantic у полі `message`, що полегшує виявлення, який саме параметр недійсний, наприклад:

```json theme={null}
{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Вхідні дані повинні бути 'pcm' або 'mp3'\",\"input\":\"wav\"}]"
}
```

## Висновок

Мінімальні витрати на інтеграцію Fish TTS: у вже існуючому коді, що викликає `api.fish.audio/v1/tts`, замініть авторизацію на токен платформи та в тілі запиту **явно вкажіть** `format: "mp3"`. Для довгих текстових сценаріїв рекомендується використовувати асинхронний зворотний виклик `callback_url`; для виявлення клонованого голосу `reference_id` використовуйте разом [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query) та [Fish Model Get](https://platform.acedata.cloud/documents/fish-model-get).