Перейти до основного вмісту

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

У цій статті описано інструкцію зі інтеграції Fish TTS API. Цей інтерфейс повністю сумісний з офіційним OpenAPI Fish Audio і дозволяє безпосередньо перенести код, який раніше викликав https://api.fish.audio/v1/tts, на https://api.xhuoapi.ai/v1/fish/tts, замінивши лише інформацію для аутентифікації без необхідності змінювати структуру запиту.

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

Щоб використовувати API, потрібно спочатку подати заявку на відповідну послугу на сторінці Fish TTS API. Після переходу на сторінку натисніть кнопку «Acquire». Якщо ви ще не увійшли або не зареєстровані, вас автоматично перенаправлять на сторінку входу для реєстрації або авторизації. Після входу ви автоматично повернетесь на поточну сторінку. При першій подачі заявки надається безкоштовний ліміт для використання API.

​
Відмінності від офіційного API

Цей API зберігає поля запитів і відповідей офіційного Fish Audio, але має кілька невеликих розширень для кращої інтеграції на нашій платформі:
  • Метод аутентифікації: використовується Authorization: Bearer {token}, де {token} — це ключ, отриманий на нашій платформі, а не офіційний ключ Fish.
  • Вибір моделі TTS: задається через HTTP-заголовок model, доступні варіанти s1 або s2-pro, за замовчуванням s2-pro. Це відповідає офіційному Fish.
  • Значення за замовчуванням для latency: upstream /fish/v1/tts повертає помилку, якщо latency не передано. У цьому інтерфейсі при відсутності параметра автоматично додається latency=normal, що відповідає поведінці Fish.
  • Асинхронний callback (розширення платформи): якщо в тілі запиту передати додаткове поле callback_url, API одразу поверне {task_id, started_at}, а після завершення обробки upstream надішле повний результат {audio_url, ...} у форматі POST JSON на цей URL. Офіційний Fish не підтримує це поле, і його передача активує асинхронний процес на нашій платформі.
Окрім зазначених відмінностей, усі поля у тілі запиту TTS (text, reference_id, references, prosody, format, sample_rate, mp3_bitrate, chunk_length, temperature, top_p тощо) передаються напряму upstream, і поведінка повністю відповідає офіційній документації.

​
Базове використання

Мінімальний запит потребує лише поле text. Приклад CURL: 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。"
  }'
Приклад відповіді: 
{
  "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}
Відповідь містить офіційні поля Fish:
  • audio_url: URL згенерованого аудіо, доступний для завантаження або відтворення.
  • latency_ms (необов’язкове): час обробки upstream у мілісекундах.
Якщо потрібно використовувати клонований голос, додайте в тіло запиту reference_id: 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "reference_id": "d7900c21663f485ab63ebdb7e5905036",
    "format": "mp3",
    "sample_rate": 44100
  }'

​
Асинхронний callback

Оскільки генерація Fish TTS для довгих текстів може займати значний час, утримання довгого з’єднання споживає ресурси системи. Цей API пропонує можливість асинхронного callback (розширення порівняно з офіційним Fish). Загальний процес: клієнт при запиті додає в тіло поле callback_url, API одразу повертає відповідь з task_id; після завершення генерації upstream відправляє повний результат із audio_url у форматі POST JSON на callback_url, додаючи той самий task_id для зв’язку асинхронної відповіді з початковим завданням. Приклад запиту: 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
Миттєва відповідь: 
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "started_at": "2025-05-09T12:34:56.789Z"
}
Через деякий час callback_url отримає повний результат: 
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
Також можна використовувати Fish Tasks API для активного опитування статусу завдання за task_id.

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

Цей інтерфейс зберігає HTTP статуси помилок Fish, але тіло відповіді використовує уніфікований формат платформи для узгодженості з /fish/audios та /fish/voices:
  • 400 token_mismatched: Некоректний запит, можливо, через відсутні або неправильні параметри.
  • 400 api_not_implemented: Некоректний запит, можливо, через відсутні або неправильні параметри.
  • 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"
}

​
Висновок

Fish TTS API повністю сумісний з офіційним OpenAPI Fish Audio і дозволяє мігрувати існуючі проекти без змін у коді, одночасно отримуючи переваги уніфікованої аутентифікації, обліку використання та асинхронних callback. Рекомендується використовувати асинхронний callback при генерації довгих текстів для уникнення тривалого утримання з’єднань і споживання ресурсів.