> ## 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}`, а когда задача будет завершена, полный результат будет отправлен обратно на этот URL в формате POST JSON с тем же `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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

Ошибки валидации параметров будут содержать оригинальный текст ошибки pydantic в поле `message`, что поможет определить, какой именно параметр недействителен, например:

```json theme={null}
{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Input should be 'pcm' or '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).