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

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
}

Типовой сценарий

  1. Создайте задачу через POST /hailuo/video/generate.
  2. Сохраните taskId из ответа.
  3. Опрашивайте GET /hailuo/video/task/{taskId} до успешного статуса.
  4. Возьмите fileId из ответа.
  5. Получите ссылку на видео через GET /hailuo/video/file?taskId={taskId}&fileId={fileId}.

Ограничения

  • prompt поддерживает до 2000 символов.
  • Для 1080P доступна длительность только 6 секунд.
  • Для 10 секунд доступно только 768P.
  • Изображения должны быть доступны по публичному URL или переданы как Base64 Data URL.
  • Для subjectReference сейчас поддерживается только один референс и тип character.