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

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

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

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

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

📘 Полная документация: 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`.
`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` (громкость в дБ). Например, `{"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	Нет	Адрес асинхронного обратного вызова, см. ниже в разделе «Асинхронный обратный вызов». Это расширение относительно официального интерфейса.

Одноразовое клонирование принимает только 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://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}

audio_url указывает на CDN данной платформы, можно напрямую скачать через GET или воспроизвести в <audio>. В окончательном успешном ответе также будет возвращен верхний уровень cost, где amount — это фактически списанные кредиты; если есть скидка на аккаунт, 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://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.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://platform2.cdn.acedata.cloud/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

Проверенный успешный ответ:

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/995dfe37-b187-474d-8323-b08d6678ed8f.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": "Быстрая речь с переопределениями просодии.",
    "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 означает без изменений, положительное значение увеличивает, отрицательное уменьшает.

Пример 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": "высокий битрейт mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

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

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

Пример 6: 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 и окончательной стоимостью 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://platform2.cdn.acedata.cloud/fish/bd66b8c5-7543-4557-b684-baa72407e336.mp3"
}

Также можно использовать Fish Tasks API для активного получения результатов по task_id; конечная запись 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`)

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

Заключение