Перейти к основному содержанию

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. Это совпадает с официальным API Fish.
  • Значение по умолчанию для latency: в официальном API /fish/v1/tts при отсутствии параметра latency возвращается ошибка, в нашем API при отсутствии этого параметра автоматически подставляется latency=normal, что соответствует поведению официального API.
  • Асинхронный callback (расширение платформы): при передаче дополнительного поля callback_url в теле запроса API сразу возвращает {task_id, started_at}, а после завершения обработки отправляет полный результат {audio_url, ...} POST-запросом в формате JSON на указанный URL. Официальный API Fish не поддерживает это поле, и его передача активирует только асинхронный процесс на нашей стороне.
Кроме указанных отличий, все поля тела запроса TTS (text, reference_id, references, prosody, format, sample_rate, mp3_bitrate, chunk_length, temperature, top_p и др.) напрямую передаются на сервер Fish, поведение полностью соответствует официальной документации.

​
Основное использование

Минимальный запрос требует передачи только поля 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 API, включая:
  • audio_url: URL сгенерированного аудио, доступного для загрузки или воспроизведения.
  • latency_ms (опционально): время обработки на сервере в миллисекундах.
Если требуется использовать клон голоса, можно добавить в тело запроса поле 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

Поскольку генерация речи для длинных текстов может занимать значительное время, а поддержание долгих соединений потребляет ресурсы системы, данный API предоставляет возможность асинхронного callback (расширение по сравнению с официальным API Fish). Общий процесс: клиент при отправке запроса дополнительно указывает поле callback_url в теле запроса, API сразу возвращает ответ с task_id; после завершения генерации полный результат с 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.

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

API сохраняет 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 при генерации длинных текстов, чтобы избежать длительного удержания соединений и расхода ресурсов.