> ## 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.
# Инструкция по интеграции Hailuo Videos Generation API
> Hailuo Video Generation 集成指南 - XHuoAPI
В этой статье будет представлена инструкция по интеграции Hailuo Videos Generation API, который позволяет генерировать официальные видео Hailuo, вводя пользовательские параметры.
## Процесс подачи заявки
Чтобы использовать API, сначала необходимо перейти на соответствующую страницу [Hailuo Videos Generation API](https://api.xhuoapi.ai/documents/ee06377b-9185-438f-ac84-3376bcb1275e) и подать заявку на соответствующую услугу. После перехода на страницу нажмите кнопку «Acquire», как показано на изображении:
Если вы еще не вошли в систему или не зарегистрировались, вас автоматически перенаправит на страницу входа, где вам будет предложено зарегистрироваться и войти. После входа или регистрации вы автоматически вернетесь на текущую страницу.
При первой подаче заявки предоставляется бесплатный лимит, который позволяет бесплатно использовать этот API.
## Основное использование
Сначала ознакомьтесь с основным способом использования, который заключается в вводе подсказки `prompt`, действия `action`, ссылки на первое изображение `first_image_url` и модели `model`, чтобы получить обработанный результат. Сначала необходимо просто передать поле `action`, значение которого будет `generate`, затем нам также нужно ввести модель, в настоящее время доступны две основные модели: модель генерации видео из изображений `minimax-i2v` и модель генерации видео из текста `minimax-t2v`, конкретное содержание следующее:
Как видно, мы настроили заголовки запроса, включая:
* `accept`: формат ответа, который вы хотите получить, здесь указано `application/json`, то есть формат JSON.
* `authorization`: ключ для вызова API, который можно выбрать из выпадающего списка после подачи заявки.
Также настроено тело запроса, включая:
* `model`: модель для генерации видео, в основном две: модель генерации видео из изображений `minimax-i2v` и модель генерации видео из текста `minimax-t2v`.
* `action`: действие для этой задачи генерации видео.
* `first_image_url`: ссылка на первое изображение, которое необходимо загрузить при выборе модели генерации видео из изображений `minimax-i2v`, Base64 кодирование не поддерживается.
* `prompt`: подсказка.
* `callback_url`: URL для обратного вызова результата.
После выбора можно заметить, что справа также сгенерирован соответствующий код, как показано на изображении:
Нажмите кнопку «Try», чтобы провести тестирование, как показано на изображении выше, и мы получили следующий результат:
```json theme={null}
{
"success": true,
"task_id": "baf1034c-684c-46be-ae6d-89ebb89b690d",
"trace_id": "3221eb74-1a25-447a-ba69-7d9b310e306c",
"data": [
{
"id": "0pv8yhe4fdrge0cmckpv23pd2g",
"model": "minimax-t2v",
"prompt": "Internal heat",
"video_url": "https://file.aigpai.com/czjl/qoueLWBokF3ud6tdVD6VJTZuXTnK5HaMO2qAOS46Ef8VSBFUA/tmp9e3u11c1.output.mp4",
"state": "succeeded"
}
]
}
```
Возвращаемый результат содержит несколько полей, описание которых следующее:
* `success`: статус задачи генерации видео.
* `task_id`: ID задачи генерации видео.
* `trace_id`: ID отслеживания задачи генерации видео.
* `data`: список результатов задачи генерации видео.
* `id`: ID видео задачи генерации видео.
* `prompt`: подсказка задачи генерации видео.
* `model`: ссылка на обложку задачи генерации видео.
* `video_url`: ссылка на видео задачи генерации видео.
* `state`: статус задачи генерации видео.
Как видно, мы получили удовлетворительную информацию о видео, нам нужно просто получить сгенерированное видео Hailuo по ссылке на видео из результата `data`.
Кроме того, если вы хотите сгенерировать соответствующий код интеграции, вы можете просто скопировать его, например, код CURL будет следующим:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/hailuo/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "generate",
"prompt": "Internal heat"
}'
```
## Асинхронный обратный вызов
Поскольку время генерации Hailuo Videos 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/580b81f5-596e-4321-b03f-606770b0bb83`.
Далее мы можем установить поле `callback_url` на указанный выше URL Webhook и заполнить соответствующие параметры, конкретное содержание показано на изображении:
Нажмите «Запустить», и вы сразу получите результат, как показано ниже:
```
{
"task_id": "05aff65c-5e84-442b-8e29-3a5d27130840"
}
```
Через некоторое время мы можем наблюдать результат сгенерированного видео на `https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83`, как показано на изображении:
Содержимое следующее:
```json theme={null}
{
"success": true,
"task_id": "05aff65c-5e84-442b-8e29-3a5d27130840",
"trace_id": "b9856b8a-725d-45c9-befe-e789d9fd9ffb",
"data": [
{
"id": "t80jhsf96srg80cmcm6b0rk8gm",
"model": "minimax-t2v",
"prompt": "Internal heat",
"video_url": "https://file.aigpai.com/czjl/YPaUz2DcwpJqItTXAG9XHAoEoj3dbF0XPU69LT5nefCMzBFUA/tmp8s_59jez.output.mp4",
"state": "succeeded"
}
]
}
```
Как видно, в результате есть поле `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 генерации видео Hailuo, который позволяет генерировать видео с помощью введенных подсказок и изображения первого кадра. Надеемся, что этот документ поможет вам лучше интегрировать и использовать данный API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.