> ## 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 Audios Generation API
> Fish music generation 集成指南 - XHuoAPI
В этой статье будет представлена инструкция по интеграции Fish Audios Generation API, который позволяет клонировать свой голос с помощью ввода подсказок.
## Процесс подачи заявки
Чтобы использовать API, сначала необходимо перейти на соответствующую страницу [Fish Audios Generation API](https://api.xhuoapi.ai/documents/e681b715-54fd-4464-a59a-d7f14500e095) и подать заявку на соответствующую услугу. После перехода на страницу нажмите кнопку «Acquire», как показано на изображении:
Если вы еще не вошли в систему или не зарегистрировались, вас автоматически перенаправит на страницу входа, чтобы пригласить вас зарегистрироваться и войти в систему. После входа в систему вы автоматически вернетесь на текущую страницу.
При первой подаче заявки будет предоставлен бесплатный лимит, который позволяет бесплатно использовать этот API.
## Основное использование
Сначала ознакомьтесь с основным способом использования, который включает ввод подсказки `prompt`, действия `action`, ID голоса `voice_id` и модели `model`, чтобы получить обработанный результат. Сначала необходимо передать поле `action`, значение которого равно `generate`, затем нам также нужно ввести модель `model`, в настоящее время основная модель — это `fish-tts`, конкретное содержание представлено ниже:
Мы видим, что здесь мы настроили заголовки запроса, включая:
* `accept`: в каком формате вы хотите получить ответ, здесь указано `application/json`, то есть в формате JSON.
* `authorization`: ключ для вызова API, который можно выбрать из выпадающего списка после подачи заявки.
Кроме того, настроено тело запроса, включая:
* `model`: модель для клонирования голоса, в основном это модель `fish-tts`.
* `action`: действие для этой задачи клонирования голоса.
* `prompt`: подсказка, которую нужно клонировать.
* `voice_id`: ID голоса для клонирования.
* `callback_url`: URL для обратного вызова результата.
После выбора вы можете заметить, что справа также сгенерирован соответствующий код, как показано на изображении:
Нажмите кнопку «Try», чтобы провести тестирование, как показано на изображении, и мы получим следующий результат:
```json theme={null}
{
"success": true,
"task_id": "5872ab00-3cf4-4040-a798-8510aaa16756",
"trace_id": "5eda3694-448a-4b72-af33-2acb3851ffe1",
"data": [
{
"audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}
]
}
```
Возвращаемый результат содержит несколько полей, описание которых приведено ниже:
* `success`: статус задачи клонирования голоса.
* `data`: результат задачи клонирования голоса
* `audio_url`: ссылка на аудиофайл задачи клонирования голоса.
Мы видим, что получили удовлетворительную информацию о голосе, и нам нужно просто получить клонированный голос по ссылке на музыку в `data`.
Кроме того, если вы хотите сгенерировать соответствующий код интеграции, вы можете просто скопировать его, например, код CURL выглядит следующим образом:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "speech",
"prompt": "a white siamese cat",
"model": "fish-tts",
"voice_id": "d7900c21663f485ab63ebdb7e5905036"
}'
```
## Асинхронный обратный вызов
Поскольку время генерации Fish Audios Generation API относительно долгое, примерно 1-2 минуты, если API долго не отвечает, HTTP-запрос будет поддерживать соединение, что приведет к дополнительному потреблению системных ресурсов. Поэтому этот API также предоставляет поддержку асинхронного обратного вызова.
Общий процесс таков: когда клиент инициирует запрос, дополнительно указывается поле `callback_url`. После того как клиент инициирует запрос API, API немедленно возвращает результат, содержащий информацию о поле `task_id`, представляющем текущий ID задачи. Когда задача завершена, результат генерации задачи будет отправлен на указанный клиентом `callback_url` в формате POST JSON, который также включает поле `task_id`, таким образом, результат задачи можно связать по ID.
Давайте рассмотрим конкретные действия на примере.
Во-первых, Webhook обратный вызов — это служба, которая может принимать HTTP-запросы, разработчик должен заменить его на URL своего HTTP-сервера. Для удобства демонстрации используется публичный сайт примера Webhook [https://webhook.site/](https://webhook.site/), открыв этот сайт, вы получите URL Webhook, как показано на изображении:
Скопируйте этот URL, и вы сможете использовать его в качестве Webhook, пример здесь: `https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34`.
Далее мы можем установить поле `callback_url` на указанный Webhook URL, а также заполнить соответствующие параметры, конкретное содержание представлено на изображении:
Нажмите «Запустить», и вы сразу получите результат, как показано ниже:
```
{
"task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5"
}
```
Через некоторое время мы можем наблюдать результат генерации задачи на `https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34`, как показано на изображении:
Содержимое следующее:
```json theme={null}
{
"success": true,
"task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"data": [
{
"audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
]
}
```
Мы видим, что в результате есть поле `task_id`, остальные поля аналогичны вышеупомянутым, с помощью этого поля можно связать задачи.
## Обработка ошибок
При вызове API, если возникает ошибка, API возвращает соответствующий код ошибки и информацию. Например:
* `400 token_mismatched`: Неверный запрос, возможно, из-за отсутствия или недействительных параметров.
* `400 api_not_implemented`: Неверный запрос, возможно, из-за отсутствия или недействительных параметров.
* `401 invalid_token`: Неавторизован, недействительный или отсутствующий токен авторизации.
* `429 too_many_requests`: Слишком много запросов, вы превысили лимит частоты.
* `500 api_error`: Внутренняя ошибка сервера, что-то пошло не так на сервере.
### Пример ответа об ошибке
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Заключение
С помощью этого документа вы уже узнали, как использовать API генерации звуков Fish, чтобы клонировать голос с помощью вводимых подсказок. Надеемся, что этот документ поможет вам лучше интегрировать и использовать этот API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.