Руководство

Как пользоваться Ray 3.2 API? Запустите первое видео за 5 минут

4 шага онлайн-теста, 4 шага подключения через API, плюс готовые к запуску curl и Python, работа с первым и последним кадром и важные моменты перед запуском в продакшен.

Oct 21, 2026

Модель: ray-3.2

TL;DR

Что это: Ray 3.2 от Luma AI, в HiAPI разделён на два маршрута: ray-3.2/text-to-video принимает только промпт, ray-3.2/image-to-video управляется первым кадром (опционально последним). Уже доступен в HiAPI — откройте страницу модели текст-в-видео и генерируйте, новым пользователям при регистрации 200 кредитов.
Сколько стоит: оплата за штуку, 5 секунд 540p $0.2145, 720p $0.429, 1080p $1.7145; 10 секунд есть только в текст-в-видео, 540p $0.643, 720p $1.286, 1080p $5.143. При неудаче автоматический возврат средств.
Как вызывать API: POST https://api.hiapi.ai/v1/tasks, в model указываете нужный маршрут, получаете taskId, затем опрашиваете или ждёте callback.url, скачиваете беззвучный MP4 из data.output[0].url.

Выход Ray 3.2 — беззвучный MP4. В текст-в-видео можно выбрать длительность и соотношение сторон; в изображение-в-видео фиксированные 5 секунд, соотношение сторон наследуется от первого кадра. Ниже — от онлайн-теста до curl, Python, изображение-в-видео и важных моментов перед запуском, всё за один раз.

Что такое Ray 3.2? Как выбрать маршрут

Текст-в-видео: передаётся только prompt, опционально duration (5 или 10 секунд), resolution (540p / 720p / 1080p), aspect_ratio (16:9, 9:16, 1:1, 4:3, 3:4, 21:9). Промпт до 6000 символов.
Изображение-в-видео: обязательны prompt и первый кадр image_url, опционально последний кадр end_image_url, resolution. Каждое видео фиксировано 5 секунд, соотношение сторон наследуется от первого кадра и автоматически подбирается ближайшее поддерживаемое.
Общее: оба идут через /v1/tasks, оба оплачиваются за штуку, оба выдают MP4 без звуковой дорожки.

Текст-в-видео подходит для кадров, где есть только текстовая идея и нужны 10 секунд или заданное соотношение сторон; изображение-в-видео — когда уже есть фото продукта, постер, концепт или нужно зафиксировать финальный кадр. Общие для обоих маршрутов 5 секунд в трёх разрешениях стоят одинаково, 10 секунд есть только в текст-в-видео.

Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.

Сгенерировать с этим промптом →, выберите соотношение сторон 21:9, 540p — $0.2145 за штуку.

Два пути: онлайн-тест или API?

Онлайн-тест (около 1 минуты)

Откройте страницу модели Ray 3.2 текст-в-видео или нажмите на ссылку с предзаполненным промптом выше.
Зарегистрируйтесь или войдите, новый аккаунт получает 200 кредитов; одно видео 5 секунд 540p списывает 429 кредитов, после пополнения можно генерировать.
Напишите промпт, выберите длительность, разрешение и соотношение сторон, нажмите запуск.
Скачайте готовое видео; когда понадобится API, создайте Key в консоли.

Подключение через API (около 5 минут)

Создайте API Key в консоли HiAPI (sk-...).
POST /v1/tasks создаёт задачу, в ответе получаете data.taskId.
Запрашивайте через GET /v1/tasks/{id} или укажите callback.url на верхнем уровне тела запроса и ждите уведомления.
Когда data.status станет success, скачайте видео из data.output[0].url.

5 секунд 540p стоит $0.2145 за штуку, на $10 можно запустить около 46 штук — достаточно, чтобы как следует отработать движение в наборе кадров.Попробуйте первое видео на странице модели →

Первое видео: версия curl

Создание задачи текст-в-видео:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/text-to-video",
    "input": {
      "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
      "duration": 5,
      "resolution": "540p",
      "aspect_ratio": "21:9"
    }
  }'

Возвращённый ID задачи находится в data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Запрос результата:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Обязателен только prompt. duration по умолчанию 5, resolution по умолчанию 540p, aspect_ratio по умолчанию 16:9. Все три поля строго валидируются, при неверном значении сразу 400, без автоматического округления.

Первое видео: версия Python

Создание, опрос и скачивание в одном месте:

import time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "ray-3.2/text-to-video",
    "input": {
        "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
        "duration": 5,
        "resolution": "540p",
        "aspect_ratio": "21:9",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    video_url = task["output"][0]["url"]
    with open("ray32-clip.mp4", "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
else:
    print(task.get("error"))

Видеозадачи обычно занимают от нескольких десятков секунд до нескольких минут, интервал опроса — 5 секунд, верхний предел таймаута — 10–15 минут. Ссылка на выходной файл истекает, скачивайте сразу после получения и сохраняйте в своё хранилище.

Изображение-в-видео: добавьте первый кадр или первый и последний

Замените model на ray-3.2/image-to-video, добавьте первый кадр image_url — тот же запрос становится изображение-в-видео:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/image-to-video",
    "input": {
      "prompt": "The ribbon of milk keeps folding down through the iced espresso, the ice cubes settle and shift slightly, condensation beads slide down the outside of the glass, very slow push-in toward the glass, warm rim light stays steady, vertical product commercial shot",
      "image_url": "https://www.hiapi.ai/images/model-pages/ray-3-2/iced-coffee-first.jpg",
      "resolution": "1080p"
    }
  }'

Чтобы зафиксировать финальный кадр, добавьте end_image_url. Чем ближе ракурс, освещение и положение объекта на первом и последнем кадре, тем стабильнее переход; если кадры сняты по-разному, модель сама добавит движение камеры для стыковки. Ни одно из полей не влияет на цену.

В изображение-в-видео нет duration и aspect_ratio: каждое видео фиксировано 5 секунд, соотношение сторон подбирается по первому кадру к ближайшему из 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, при несовпадении пропорций края обрезаются. Чтобы полностью контролировать соотношение сторон выхода, заранее обрежьте первый кадр до одного из этих шести соотношений.

3 вещи перед запуском в продакшен

На сервере используйте callback. Добавьте на верхний уровень тела запроса "callback": {"url": "https://yourapp.com/webhook", "when": "final"}, при переходе задачи в терминальное состояние придёт уведомление — избавитесь от опроса. success и fail оба вызывают callback, на сервере делайте идемпотентность по taskId.
При таймауте не повторяйте POST. Каждый POST создаёт новую задачу и оплачивается отдельно. Сначала сохраните taskId, перед повтором выполните дедупликацию в своей системе; если процесс упал, продолжайте запрос по сохранённому id.
В каждом запросе явно указывайте параметры. resolution напрямую определяет цену, duration принимает только целые 5 или 10, в изображение-в-видео не передавайте duration и aspect_ratio. Пропишите их жёстко в запросе — тогда счёт и поведение будут предсказуемы.

Частые ошибки, по одной на строку

400 INVALID_REQUEST, неверное значение resolution → принимаются только 540p, 720p, 1080p, нет 2k, 480p.
400, неверное значение duration → принимаются только целые 5 и 10; строка "5" или число 7 вызовут ошибку.
400 additional properties 'aspect_ratio' not allowed → в изображение-в-видео нет этого поля, удалите его; поддерживается только в текст-в-видео.
401 permission_denied → Key отсутствует, написан неверно или отозван, проверьте Authorization: Bearer sk-....
Создание вернуло 200, но задача позже fail → обычно image_url в изображение-в-видео не открывается или не является изображением. При создании проверяется только форма полей, а не доступность URL.
Ссылка не открывается через несколько дней → у выходного URL есть срок действия, скачивайте сразу после получения.

Предварительно списанная сумма за неудачные задачи автоматически возвращается в полном объёме.

Частые вопросы

Какова длина одного видео Ray 3.2? В текст-в-видео можно выбрать 5 или 10 секунд; в изображение-в-видео фиксировано 5 секунд.

Какой длины может быть промпт? В обоих маршрутах 1–6000 символов.

Есть ли звук в готовом видео? Нет, на выходе MP4 без звуковой дорожки, музыка и звуковые эффекты добавляются на постпродакшене.

Можно ли в изображение-в-видео выбрать соотношение сторон самому? Нет. Соотношение сторон наследуется от первого кадра и автоматически подбирается ближайшее поддерживаемое.

Можно ли в текст-в-видео передать референсное изображение? Нет. Если нужно управление изображением, используйте ray-3.2/image-to-video.

Статьи серии Ray 3.2

Попробуйте сейчас: нажмите на Сгенерировать с этим промптом → под видео с маяком выше, промпт уже заполнен, выберите 5 секунд, 540p, 21:9 и нажмите — получите то же самое.

ТегиПодключение API Руководство