Інструкція з інтеграції Fish TTS API

Цей API надає перетворення тексту на мовлення, виклик збережених голосів і одноразове миттєве клонування голосу за адресою POST https://api.acedata.cloud/fish/tts.

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

Щоб використовувати Fish TTS API, спочатку перейдіть до консолі Ace Data Cloud, щоб отримати ваш API Token, і збережіть його для подальшого використання.

Якщо ви ще не увійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу із запрошенням зареєструватися та увійти, а після завершення ви автоматично повернетеся на поточну сторінку. Один 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`, якщо не вказано, цей API автоматично додасть `normal` (у разі прямого передавання порожнього рядка верхній рівень відхилить запит).
`normalize`	boolean	Ні	Чи виконувати нормалізацію тексту.
`callback_url`	string	Ні	Адреса асинхронного зворотного виклику, див. нижче «Асинхронний зворотний виклик». Це розширення порівняно з офіційним API.

Одноразове клонування приймає лише 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 — dB, 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.

Getting Started

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

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

Висновок