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}, а коли завдання буде завершено, повний результат буде надіслано POST JSON формою на цей URL, з тим же 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": "отримання не вдалося"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

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

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

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Проксі

Advanced

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`)

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

Висновок