Как использовать API преобразования текста в видео Ray 3.2: curl, Python и один готовый к запуску запрос

Ray 3.2 — это модель преобразования текста в видео из каталога моделей hiapi, и она, как и все остальные видеомодели, вызывается через единый асинхронный API задач — id модели ray-3.2/text-to-video, отправляется на POST /v1/tasks. В отличие от некоторых видеомоделей, у которых единственный параметр настройки — это промпт, Ray 3.2 предоставляет три реально работающих параметра управления выводом — duration, resolution и aspect_ratio — и каждый из них строго проверяется на стороне сервера.

Это руководство позволит вам с первого раза отправить запрос, который сработает: точная схема входных данных (проверена на живом API 2026-10-19), готовый к копированию и вставке вызов curl, полный скрипт Python для отправки/опроса/скачивания, а также детали для продакшена — обратные вызовы, идемпотентные повторы и ответы с ошибками, которые вы реально увидите.

Что вы построите и что вам понадобится

Цель: отправить текстовый промпт, опросить задачу и скачать беззвучный клип .mp4 (5 или 10 секунд).

Предварительные требования:

• Ключ API hiapi — получите его в вашей консоли. Ключ имеет вид sk-... и передаётся в заголовке Authorization: Bearer. Впервые работаете с API задач? Начните с быстрого старта.
• Любой HTTP-клиент. Мы покажем curl и Python (requests).

Вывод Ray 3.2 тарифицируется за клип, и цена сильно растёт в зависимости от ваших настроек — актуальные тарифы смотрите на странице цен. Во время итераций над промптом начинайте с 540p / 5 секунд; клип 1080p на 10 секунд может стоить во много раз дороже, чем один рендер изображения в рамках бюджета, так что не гоняйте цикл разработки постоянно на максимальных настройках.

Точная схема входных данных (одно обязательное поле, три строгих перечисления)

Всё передаётся в объекте input. Проверено поле за полем на живом API:

Поле	Тип	Обязательно	Допустимые значения	Значение по умолчанию
prompt	string	Да	Описание сцены, до 6000 символов	—
duration	integer	Нет	5 или 10	5
resolution	string	Нет	540p, 720p, 1080p	540p
aspect_ratio	string	Нет	16:9, 9:16, 1:1, 4:3, 3:4, 21:9	16:9

Три вещи стоит запомнить перед написанием кода:

1. duration — это целое число, а не строка. Передавайте просто число — "duration": 5. Это противоположно некоторым другим видеомоделям на API задач (например, hailuo-2.3 требует "duration": "6" в виде строки). Если вы переносите тело запроса с одной модели на другую, перепроверьте это поле; это самая частая кросс-модельная ошибка.
2. Значения перечислений проверяются, а не усекаются. Значения вне диапазона отклоняются с 400, а не молча округляются. Нет 2k, нет 480p, нет 2:1.
3. Нет prompt_optimizer, seed или negative_prompt. Композиция полностью управляется через aspect_ratio плюс промпт. Если вы отправите поле, которое схема не знает, ожидайте 400 — схема входных данных /v1/tasks зависит от модели, поэтому не предполагайте, что ключи, работающие в другом месте, подойдут и здесь.

Что реально возвращает валидация

Ниже реальные ответы живого эндпоинта (намеренно отправлены недопустимые значения, задача не создаётся, списания нет):

// POST with "resolution": "2k"
{"code":400,"data":null,"error_code":"INVALID_REQUEST",
 "message":"invalid input: resolution: value must be one of '540p', '720p', '1080p'"}

// POST with "duration": 7
{"code":400,"data":null,"error_code":"INVALID_REQUEST",
 "message":"invalid input: duration: value must be one of 5, 10"}

// POST with "aspect_ratio": "2:1"
{"code":400,"data":null,"error_code":"INVALID_REQUEST",
 "message":"invalid input: aspect_ratio: value must be one of '16:9', '9:16', '1:1', '4:3', '3:4', '21:9'"}

message указывает точное поле и точный допустимый набор — так что если вы забыли какое-то значение перечисления, API вам его подскажет. Обратите внимание, что у duration 5, 10 без кавычек (числа), а у resolution '540p' в кавычках — это строки: разница в кавычках подсказывает вам, какое поле является целым числом.

Минимальный рабочий пример: 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": "Дождливой ночью уличная танцовщица кружится под неоновыми огнями, лужи отражают розовый и голубой свет, её куртка развевается при вращении, камера облетает её с нижнего ракурса, кинематографично",
      "duration": 5,
      "resolution": "540p",
      "aspect_ratio": "9:16"
    }
  }'

Ответ на создание содержит id задачи (обрезано):

{ "data": { "taskId": "task_01k..." } }

Опрашивайте её, пока она не перейдёт в терминальное состояние:

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

Пока задача выполняется, data.status сообщает промежуточный статус. Два терминальных состояния — success и fail. При успехе (обрезано):

{
  "data": {
    "taskId": "task_01k...",
    "status": "success",
    "output": [ { "url": "https://.../clip.mp4" } ]
  }
}

Скачайте data.output[0].url немедленно. URL вывода подписан и истекает — сохраните байты в своё хранилище, а не давайте прямые ссылки на URL задачи. Ray 3.2 возвращает беззвучный MP4 (без аудиодорожки), так что не ждите аудиопотока, который никогда не придёт.

Полный скрипт Python (отправка → опрос → скачивание)

import time
import requests

API_BASE = "https://api.hiapi.ai/v1"
API_KEY = "sk-YOUR_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_task(prompt: str, duration: int = 5,
                resolution: str = "540p", aspect_ratio: str = "9:16") -> str:
    resp = requests.post(
        f"{API_BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "ray-3.2/text-to-video",
            "input": {
                "prompt": prompt,
                "duration": duration,          # 5 or 10 — an INTEGER, not a string
                "resolution": resolution,      # "540p" | "720p" | "1080p"
                "aspect_ratio": aspect_ratio,  # "16:9" | "9:16" | "1:1" | "4:3" | "3:4" | "21:9"
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_task(task_id: str, timeout_s: int = 900, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
        time.sleep(poll_interval)  # any non-terminal status = still running
    raise TimeoutError(f"task {task_id} not finished after {timeout_s}s")


task_id = create_task(
    "Бумажный кораблик плывёт по залитой дождевой водой канаве, капли поднимают круги на воде,"
    "осенние листья кружатся и проплывают мимо, съёмка с низкой точки у самой поверхности воды, мягкий пасмурный свет"
)
print("task created:", task_id)

task = wait_task(task_id)
video_url = task["output"][0]["url"]

# Output URLs expire — download right away and store the bytes yourself.
video = requests.get(video_url, timeout=120).content
with open("ray32-clip.mp4", "wb") as f:
    f.write(video)
print(f"saved ray32-clip.mp4 ({len(video) / 1e6:.1f} MB)")

Установите зависимость через pip install requests, подставьте свой ключ — и когда задача завершится, на диске будет .mp4. Видеозадачи занимают минуты, а не секунды — дайте циклу опроса щедрый дедлайн (в примере выше 15 минут), а не предполагайте, что он вернётся быстро.

Замечания для продакшена: обратные вызовы, идемпотентность, ошибки

Предпочитайте обратные вызовы опросу

Для всего, что выходит за рамки скрипта, регистрируйте webhook при создании задачи вместо опроса:

{
  "model": "ray-3.2/text-to-video",
  "input": { "prompt": "...", "duration": 10, "resolution": "720p" },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

С "when": "final" hiapi вызовет ваш эндпоинт один раз, когда задача перейдёт в терминальное состояние — без трафика опроса и без пропущенных уведомлений о завершении между интервалами. Ваш обработчик затем выполняет GET /v1/tasks/<id> (или читает тело доставленного ответа), чтобы получить output[0].url. Для CLI и ноутбуков, которые не могут предоставить HTTPS-эндпоинт, опрос по-прежнему подходит.

Делайте повторы идемпотентными

Сохраняйте taskId в тот момент, когда вызов создания возвращается. Если ваш процесс упадёт посреди генерации, восстановитесь, опрашивая сохранённый id — не создавайте задачу заново, иначе вы заплатите за второй рендер. Создавайте заново только если сам исходный запрос на создание не удался до возврата id задачи. Поскольку Ray 3.2 тарифицируется за клип, а клипы в высоком разрешении недёшевы, дублирующее создание — это реальная ошибка в затратах, а не просто потеря времени.

Ошибки, которые вы реально увидите

Каждая строка ниже — проверенная форма живого ответа:

Симптом	Ответ	Исправление
Ключ отсутствует/недействителен	401, вложенный {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}}	Проверьте заголовок Authorization: Bearer sk-... и есть ли у ключа доступ. При обращении в поддержку предоставьте request_id.
Неверное значение перечисления	400 INVALID_REQUEST, плоский {"code":400,"error_code":"INVALID_REQUEST","message":"invalid input: <field>: value must be one of ..."}	Прочитайте поле, указанное в message; там перечислен точный допустимый набор.
duration отправлен как строка	400 INVALID_REQUEST	Отправляйте просто число 5 или 10, а не "5".
Неизвестный id модели	400, error_code: "MODEL_UNAVAILABLE", "model not available via /v1/tasks"	Используйте строго ray-3.2/text-to-video — канонический id смотрите на странице модели.
Неверный id задачи при опросе	404, плоский {"code":404,"data":null,"message":"task not found"} (примечание: у 404 нет error_code)	Либо id неверен, либо вы запрашиваете ключом другого аккаунта.
status: "fail" при опросе	Терминальное состояние задачи, подробности в data.error	Прочитайте data.error.code / data.error.message. Неудачные задачи возвращают деньги; здесь проявляются пометки политики контента и проблемы с мощностями вышестоящего сервиса — для пометок контента повторите с переписанным промптом.

Связанные ресурсы

• Страница модели Ray 3.2 для преобразования текста в видео — попробуйте онлайн, статус в реальном времени и полная таблица цен
• API Ray 3.2 для преобразования изображения в видео — та же серия моделей, но она анимирует опорный кадр, а не начинает с текста (схема входных данных отличается — проверьте её перед повторным использованием этого тела запроса)
• Как использовать API Hailuo 2.3 для преобразования текста в видео — аналогичный рецепт, где duration — это строка, что служит полезным контрастом с целым числом у Ray
• Цены hiapi — тарифы на видео за клип с разбивкой по разрешению и длительности

Часто задаваемые вопросы

Каков id модели и какой эндпоинт мне вызывать? ray-3.2/text-to-video, отправляется как верхнеуровневое model на POST https://api.hiapi.ai/v1/tasks, параметры передаются в input. Он асинхронный — вы получаете taskId, затем опрашиваете GET /v1/tasks/<id> (или регистрируете обратный вызов).

duration указывается в секундах, и почему "5" не проходит? Клипы бывают на 5 или 10 секунд, и поле является целым числом: отправляйте 5 или 10. Строка в кавычках или любое другое число, например 7, не пройдёт и вернёт 400 INVALID_REQUEST: duration: value must be one of 5, 10.

Могу ли я задать разрешение и соотношение сторон? Да — именно этим Ray 3.2 отличается от видеомоделей, поддерживающих только промпт. resolution — 540p, 720p или 1080p; aspect_ratio — одно из 16:9, 9:16, 1:1, 4:3, 3:4, 21:9. Оба необязательны (по умолчанию 540p и 16:9), и оба отклоняют значения вне диапазона с 400.

Сколько стоит клип? Ray 3.2 тарифицируется за клип, и разрешение — главный рычаг: при одинаковой длине клип 1080p стоит в несколько раз дороже 540p, а клип на 10 секунд стоит примерно втрое дороже клипа на 5 секунд. Тарифы меняются, поэтому смотрите страницу цен, а не хардкодьте число, и прототипируйте на 540p/5 секундах.

Есть ли в клипе звук? Нет — Ray 3.2 для преобразования текста в видео возвращает беззвучный MP4. Если вам нужен звук, добавьте его на постобработке или используйте отдельную аудиомодель.

Поддерживает ли Ray 3.2 преобразование изображения в видео? Да, как отдельный id модели на том же API задач: ray-3.2/image-to-video. Его схема входных данных отличается (он принимает опорное изображение), поэтому проверьте её перед повторным использованием этого тела запроса — см. страницу модели преобразования изображения в видео.

Моя генерация идёт медленно или выглядит зависшей. Что считать нормальным? Видеозадачи выполняются несколько минут. В цикле опроса сохраняйте промежуточные data.status и ждите — закладывайте дедлайн 10–15 минут или используйте callback с "when": "final", чтобы hiapi уведомил вас в терминальном состоянии, а не вы угадывали интервал.