HaiLuo
HaiLuo — семейство моделей для генерации видео через CDNvideo AI Hub media API.
Base URL
https://api.cdnvideo.ru/app/aihub-router/v1/media
Для работы используется обычный ключ AI Hub в заголовке Authorization. Модель для маршрутизации передаётся в X-Model.
Сейчас поддерживаются модели hailuo-2.0 и hailuo-2.3. Интерфейс для них одинаковый:
Authorization: Bearer ${AIHUB_API_KEY}
X-Model: hailuo-2.3
Асинхронная обработка
HaiLuo возвращает taskId, а не готовое видео. После создания задачи запросите GET /hailuo/video/task/{taskId}, получите fileId, затем запросите GET /hailuo/video/file?taskId={taskId}&fileId={fileId} для получения mediaUrl.
Создание видео
POST /hailuo/video/generate
Метод создаёт задачу генерации видео. Один и тот же endpoint используется для text-to-video, image-to-video, генерации по первому и последнему кадру, director-режима и subject-to-video. Конкретный сценарий определяется переданными полями.
Параметры запроса
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
prompt |
string |
Зависит от сценария | Описание видео. Максимальная длина: 2000 символов. Для text-to-video обычно обязательно, для image-to-video может быть пустым или отсутствовать. |
promptOptimizer |
boolean |
Нет | Включает автоматическую оптимизацию промпта. По умолчанию: true. Для более строгого следования инструкции укажите false и передайте более детальный промпт. |
fastPretreatment |
boolean |
Нет | Сокращает время предварительной оптимизации promptOptimizer. По умолчанию: false. |
duration |
integer |
Нет | Длительность видео в секундах. По умолчанию: 6. Для 768P доступны 6 и 10, для 1080P — только 6. |
resolution |
string |
Нет | Разрешение видео. Для 6 секунд доступны 768P по умолчанию и 1080P; для 10 секунд — 768P. |
firstFrameImage |
string |
Для image-to-video | Первый кадр видео: публичный URL или Base64 Data URL вида data:image/jpeg;base64,{data}. |
lastFrameImage |
string |
Для start/end frames | Последний кадр видео: публичный URL или Base64 Data URL. Размер итогового видео следует первому кадру. |
subjectReference |
array<object> |
Для subject-to-video | Референс субъекта. Сейчас поддерживается субъект типа character. |
subjectReference[].type |
string |
Для subject-to-video | Тип субъекта. Сейчас поддерживается только character. |
subjectReference[].image |
array<string> |
Для subject-to-video | Массив из одного изображения-референса: публичный URL или Base64 Data URL. |
Требования к изображениям
| Поле | Требования |
|---|---|
firstFrameImage |
Формат JPG, JPEG или PNG; соотношение сторон от 2:5 до 5:2; короткая сторона больше 300px; размер до 20MB. |
lastFrameImage |
Формат JPG, JPEG, PNG или WebP; соотношение сторон от 2:5 до 5:2; короткая сторона больше 300px; размер до 20MB. Если размер отличается от первого кадра, последний кадр может быть обрезан относительно первого. |
subjectReference[].image |
Формат JPG, JPEG или PNG; размер до 20MB; изображение должно содержать валидный человеческий субъект. |
Text-to-video
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/hailuo/video/generate \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: hailuo-2.3" \
-d '{
"prompt": "A man picks up a book [Push In], then reads it near a window [Fixed].",
"promptOptimizer": true,
"duration": 6,
"resolution": "768P"
}'
Ответ
{
"taskId": "106916112212032"
}
Image-to-video
Для image-to-video передайте firstFrameImage. Промпт можно оставить пустым или не передавать, если нужно, чтобы модель сама определила развитие сцены.
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/hailuo/video/generate \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: hailuo-2.3" \
-d '{
"prompt": "Two pink koi fish are swimming together. One fish leaps out of the water, then falls back into it.",
"firstFrameImage": "https://example.com/first-frame.jpeg",
"duration": 6,
"resolution": "768P"
}'
Видео по первому и последнему кадру
Передайте firstFrameImage и lastFrameImage, чтобы задать начальное и финальное состояние видео.
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/hailuo/video/generate \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: hailuo-2.3" \
-d '{
"prompt": "Spring has arrived. A Shiba Inu runs across a green lawn and chases butterflies.",
"firstFrameImage": "https://example.com/start.jpeg",
"lastFrameImage": "https://example.com/end.jpeg",
"duration": 6,
"resolution": "768P"
}'
Subject-to-video
Для subject-to-video передайте subjectReference. Сейчас поддерживается только тип character, то есть человеческое лицо или персонаж.
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/hailuo/video/generate \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: hailuo-2.3" \
-d '{
"prompt": "The camera moves slowly, following the character through a sunlit forest.",
"promptOptimizer": true,
"subjectReference": [
{
"type": "character",
"image": ["https://example.com/character-reference.jpg"]
}
]
}'
Управление камерой
HaiLuo поддерживает команды камеры внутри prompt. Команды указываются в квадратных скобках в месте, где движение должно примениться.
A man picks up a book [Push In], then reads near a window [Fixed].
Рекомендуется объединять не больше трёх команд в одной группе.
| Тип | Команды |
|---|---|
| Горизонтальное движение | [Pan Left], [Pan Right] |
| Наклон | [Tilt Left], [Tilt Right] |
| Приближение и отдаление камеры | [Push In], [Pull Out] |
| Подъём и спуск | [Ascend], [Descend] |
| Вертикальный наклон | [Tilt Up], [Tilt Down] |
| Zoom | [Zoom In], [Zoom Out] |
| Тряска | [Shake] |
| Следование | [Follow] |
| Фиксированная камера | [Fixed] |
Комбинирование движений
| Формат | Пример | Описание |
|---|---|---|
| Одно движение | [Tilt Left] |
Применяется одна камера-команда. |
| Одновременные движения | [Tilt Left, Pan Right] |
Команды внутри одной группы применяются одновременно. |
| Последовательные движения | scene [Tilt Left], next scene [Pan Right] |
Первая вставленная команда применяется раньше следующей. |
Команды камеры можно сочетать с естественным языком. Использование точных названий движений повышает точность результата.
Получение статуса и fileId
GET /hailuo/video/task/{taskId}
Метод возвращает статус задачи. Когда задача завершена успешно, в ответе появляется fileId или file_id готового видео.
Пример curl
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/hailuo/video/task/106916112212032 \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "X-Model: hailuo-2.3"
Ответ
{
"status": "Success",
"fileId": "243456265392387",
"taskId": "106916112212032",
"videoWidth": 1280,
"videoHeight": 768
}
Статусы задачи
| Статус | Описание |
|---|---|
PENDING |
Задача ожидает обработки. |
IN_PROGRESS |
Задача выполняется. |
Preparing |
Видео подготавливается. |
Success |
Задача успешно завершена. |
Fail |
Задача завершилась ошибкой. |
Получение URL видео
GET /hailuo/video/file?taskId={taskId}&fileId={fileId}
Метод возвращает временный URL готового видео.
Пример curl
curl "https://api.cdnvideo.ru/app/aihub-router/v1/media/hailuo/video/file?taskId=106916112212032&fileId=243456265392387" \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "X-Model: hailuo-2.3"
Ответ
{
"fileId": "243456265392387",
"createdAt": 1740990443,
"filename": "output.mp4",
"purpose": "video_generation",
"mediaUrl": "https://example.com/output.mp4",
"expireTime": 1741022843
}
Типовой сценарий
- Создайте задачу через
POST /hailuo/video/generate. - Сохраните
taskIdиз ответа. - Опрашивайте
GET /hailuo/video/task/{taskId}до успешного статуса. - Возьмите
fileIdиз ответа. - Получите ссылку на видео через
GET /hailuo/video/file?taskId={taskId}&fileId={fileId}.
Ограничения
promptподдерживает до2000символов.- Для
1080Pдоступна длительность только6секунд. - Для
10секунд доступно только768P. - Изображения должны быть доступны по публичному URL или переданы как Base64 Data URL.
- Для
subjectReferenceсейчас поддерживается только один референс и типcharacter.