Fish TTS API интеграция

Этот интерфейс основан на Fish Audio официальном TTS API, различия заключаются только в способе аутентификации (использование токена этой платформы) и асинхронном обратном вызове (расширение callback_url), структура тела запроса соответствует upstream. Адрес: POST https://api.acedata.cloud/fish/tts.

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

Чтобы использовать Fish TTS API, сначала перейдите в консоль Ace Data Cloud и получите ваш API токен для резервного копирования.

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

📘 Полная документация: Fish TTS API →

Заголовки запроса

Заголовок	Обязательный	Описание
`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 или получить в 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.

Пример 1: Минимальный запрос (`text` + `format=mp3`)

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

Ответ (проверено):

{
  "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):

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"
  }'

Ответ (проверено):

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

Пример 3: Регулировка скорости / громкости (`prosody`)

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"
  }'

Ответ (проверено):

{
  "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:

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
  }'

Возврат (проверено):

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

Пример 5: PCM оригинальная волна

Необходимо для реального соединения в браузере или для последующей обработки на клиенте (смешивание, изменение скорости), рекомендуется использовать pcm:

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
  }'

Возврат (проверено):

{
  "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.

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"
  }'

Немедленный возврат (проверено):

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}

Позже callback_url получит следующее:

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

Также можно использовать Fish Tasks API для активного получения результатов по task_id, подробности см. в документации.

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

400 token_mismatched: отсутствуют или недействительны параметры запроса (чаще всего text пустой или format имеет значение, отличное от mp3/wav/pcm).
401 invalid_token: токен аутентификации отсутствует или недействителен.
429 too_many_requests: превышен лимит скорости аккаунта.
500 api_error: внутренняя ошибка сервера.

Пример ответа об ошибке:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

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

{
  "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 и Fish Model Get.

Начало работы

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Прокси

Продвинутый

Fish TTS API интеграция

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

Заголовки запроса

Поля тела запроса

Пример 1: Минимальный запрос (`text` + `format=mp3`)

Пример 2: Использование клонированного голоса `reference_id`

Пример 3: Регулировка скорости / громкости (`prosody`)

Пример 4: Переключение модели + управление битрейтом

Пример 5: PCM оригинальная волна

Асинхронный обратный вызов (`callback_url`)

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

Заключение

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

​Заголовки запроса

​Поля тела запроса

​Пример 1: Минимальный запрос (text + format=mp3)

​Пример 2: Использование клонированного голоса reference_id

​Пример 3: Регулировка скорости / громкости (prosody)

​Пример 4: Переключение модели + управление битрейтом

​Пример 5: PCM оригинальная волна

​Асинхронный обратный вызов (callback_url)

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

​Заключение

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

Заголовки запроса

Поля тела запроса

Пример 1: Минимальный запрос (`text` + `format=mp3`)

Пример 2: Использование клонированного голоса `reference_id`

Пример 3: Регулировка скорости / громкости (`prosody`)

Пример 4: Переключение модели + управление битрейтом

Пример 5: PCM оригинальная волна

Асинхронный обратный вызов (`callback_url`)

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

Заключение