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	Ні	Довжина фрагмента, за замовчуванням визначається верхнім рівнем.
`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://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 в одиницях 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": "високий бітрейт 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": "запит не вдався"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Помилки валідації параметрів будуть описані в полі 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

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

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

Висновок