Инструкция по интеграции Fish TTS API

Этот интерфейс предоставляет преобразование текста в речь, вызов сохранённых голосов и одноразовое мгновенное клонирование голоса по адресу POST https://api.acedata.cloud/fish/tts.

Процесс получения

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

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

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

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

Header	Обязательно	Описание
`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`.
`references`	object[]	Нет	Одноразовое мгновенное клонирование голоса, поддерживается только один образец `{audio, text}`: `audio` — публичный HTTPS MP3/WAV URL, `text` — точная дословная расшифровка аудио. Нельзя использовать одновременно с `reference_id`.
`sample_rate`	integer	Нет	Частота дискретизации, обычно используются `16000`, `22050`, `44100`. По умолчанию для `format=mp3` — 44100.
`mp3_bitrate`	integer	Нет	Битрейт MP3: `64`, `128`, `192`. Действует только при `format=mp3`.
`prosody`	object	Нет	Переопределение просодии, поддерживает `speed` (скорость речи, 1.0 — исходная скорость) и `volume` (усиление громкости в dB). Например: `{"speed":1.2,"volume":0}`.
`chunk_length`	integer	Нет	Длина сегмента на стороне вышестоящего сервиса, по умолчанию определяется вышестоящим сервисом.
`temperature`	number	Нет	Температура семплирования, диапазон примерно 0.0–1.0.
`top_p`	number	Нет	Параметр семплирования top-p.
`latency`	string	Нет	`normal` или `balanced`; при отсутствии этот интерфейс автоматически подставляет `normal` (при прямой передаче пустой строки вышестоящий сервис отклонит запрос).
`normalize`	boolean	Нет	Выполнять ли нормализацию текста.
`callback_url`	string	Нет	Адрес асинхронного обратного вызова, см. ниже раздел «Асинхронный обратный вызов». Это расширение относительно официального интерфейса.

Одноразовое клонирование принимает только HTTPS URL аудио и не принимает MessagePack, Base64, data URI или URL с учётными данными. Рекомендуемая длительность референсного аудио — 10–270 секунд; Studio использует более консервативный диапазон 10–60 секунд.

Пример 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://cdn.acedata.cloud/assets/examples/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d-230825dfc559.mp3"
}

audio_url указывает на CDN этой платформы, его можно напрямую скачать через GET или воспроизвести в <audio>. Итоговый успешный ответ также возвращает cost верхнего уровня, где amount — фактически списанные Credits за этот раз; при наличии скидки аккаунта list_amount обозначает лимит до скидки. Ссылка доступна в течение длительного времени, но всё же рекомендуется сохранить копию в собственном хранилище.

Пример 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://cdn.acedata.cloud/assets/examples/fish/b6f161f2-a100-4818-add2-47694f234659-6532864739de.mp3"
}

Пример 3: одноразовое мгновенное клонирование голоса (`references`)

Разместите референсное аудио по публичному HTTPS-адресу и предоставьте точный исходный текст, который фактически произносится в нём. Этот голос используется только для текущего синтеза и не создаёт постоянную модель:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "新的旅程从这一刻开始，让我们一起向前。",
    "format": "mp3",
    "references": [{
      "audio": "https://cdn.acedata.cloud/assets/examples/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9-570cfdf96ad9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

Успешный ответ при фактическом тестировании:

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/995dfe37-b187-474d-8323-b08d6678ed8f-6359be9f8873.mp3",
  "cost": {"amount": 0.007609319999999999, "currency": "credit"}
}

Способ	Жизненный цикл	Подходящие сценарии
`references`	Только для текущего TTS-запроса	Временное использование или разный голос для каждого запроса
`reference_id`	Можно использовать повторно	Общие голоса или долгосрочные голоса, созданные через `/fish/model`

Пример 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://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
}

speed больше 1 ускоряет, меньше 1 замедляет; единица volume — дБ, 0 означает без изменений, положительное значение усиливает, отрицательное ослабляет.

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

Переключитесь на стабильную модель через 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": "high bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

Ответ (фактическое тестирование):

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

Пример 6: исходная PCM-волна

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

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

Ответ (фактическое тестирование):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/64adc04b-c196-4a0f-9070-222ba101ce6c-fc50de38c165.wav"
}

Расширение ссылки соответствует format в запросе: mp3 возвращает .mp3, а wav и pcm возвращают .wav (контейнер WAV, 16-битный PCM).

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

Однократный синтез длинного текста может занимать от десятка до нескольких десятков секунд, и при разрыве соединения потребуется повторная попытка. После передачи callback_url в теле запроса интерфейс немедленно вернёт {task_id, started_at}, а после фактического завершения на стороне сервиса полный результат будет отправлен POST JSON-запросом на этот URL, с тем же task_id и итоговым cost верхнего уровня за эту операцию. Первоначальное подтверждение задачи ещё не означает завершения синтеза, поэтому не содержит cost.

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://cdn.acedata.cloud/assets/examples/fish/bd66b8c5-7543-4557-b684-baa72407e336-52f2e79732f2.mp3"
}

Также можно активно получать результат по task_id с помощью Fish Tasks API; response.cost в записи терминального состояния совпадает с cost в обратном вызове, см. подробности в этой документации.

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

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

Ошибка валидации параметров укажет недопустимое поле в поле 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

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

Coding

Другие руководства

Инструкция по интеграции Fish TTS API

Процесс получения

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

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

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

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

Пример 3: одноразовое мгновенное клонирование голоса (`references`)

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

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

Пример 6: исходная PCM-волна

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

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

Заключение

​Процесс получения

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

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

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

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

​Пример 3: одноразовое мгновенное клонирование голоса (references)

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

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

​Пример 6: исходная PCM-волна

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

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

​Заключение

Процесс получения

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

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

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

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

Пример 3: одноразовое мгновенное клонирование голоса (`references`)

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

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

Пример 6: исходная PCM-волна

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

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

Заключение