Как использовать API преобразования текста в видео grok-imagine-1.5-lite (curl + Python)

Если вы хотите сгенерировать короткое видео со звуком из одного предложения, grok-imagine-1.5-lite/text-to-video — самый дешёвый вариант на hiapi, способный выдавать 1080P. Он принимает одну подсказку и возвращает MP4 длительностью 1–15 секунд с уже смикшированным аудио, работая на том же едином API задач, что и все остальные модели платформы. На этой странице приведены готовые к запуску запросы, точная схема (проверенная по живому эндпоинту, а не списанная из спецификации), пример реального ответа и подводные камни, которые я встретил при тестировании.

Всё ниже проверено по живому API 2026-10-21. Цены получены мной на практике; если они изменятся, ориентируйтесь на страницу цен.

1. Что вы создадите и что для этого нужно

Цель: отправить текстовую подсказку и получить загружаемый MP4-фрагмент со звуком.

Вам нужно только одно: ключ API hiapi. Создайте его в консоли и храните на сервере — он выглядит как sk-... и передаётся в заголовке Authorization: Bearer. Пути без ключа нет; каждый запрос ниже должен проходить аутентификацию.

Модель работает асинхронно. Вы не получите видео прямо в ответе на POST. Сначала вы создаёте задачу, получаете taskId, затем опрашиваете (или используете callback), пока задача не завершится и не вернёт URL вывода.

2. Минимальный рабочий пример

Два шага: создать задачу, затем опросить результат.

Создание задачи (curl)

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-1.5-lite/text-to-video",
    "input": {
      "prompt": "На рассвете рыжая лиса ступает по свежему снегу, дыхание превращается в белый пар, мягкий утренний свет, тихий фоновый ветер. Кинематографично, естественные цвета. Без текста.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Обратите внимание на структуру: model на верхнем уровне, всё остальное вложено в input. Если отправлять поля плоско (без обёртки input), API отклонит всё тело запроса с ошибкой invalid input: must be a JSON object — это самая частая ошибка.

При успешном создании立即 возвращается id задачи:

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

Опрос результата (Python)

import time, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEAD = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def generate(prompt, duration=5, resolution="720p", aspect_ratio="16:9"):
    r = requests.post(BASE, headers=HEAD, json={
        "model": "grok-imagine-1.5-lite/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # integer, 1–15
            "resolution": resolution,      # "480p" | "720p" | "1080p"
            "aspect_ratio": aspect_ratio,  # see schema below
        },
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    # Poll the SAVED task_id. A single transient network error is not a failure —
    # keep polling the same id rather than re-creating (re-creating bills again).
    deadline = time.time() + 300
    while time.time() < deadline:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEAD, timeout=30).json()
        except requests.RequestException:
            time.sleep(5); continue
        task = d.get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

print(generate("На рассвете рыжая лиса ступает по свежему снегу, тихий фоновый ветер. Кинематографично."))

Схема (проверена по живому API)

Поля размещаются внутри input. Схема закрытая — любой неизвестный ей ключ возвращает 400, поэтому не отправляйте seed, negative_prompt или motion_mode (здесь их нет; все ракурсы и направления движения задаются формулировкой подсказки).

Поле	Тип	Обязательно	Допустимые значения
prompt	string	Да	Свободный текст
duration	integer	Да	1–15 (целые секунды; 5.5 будет отклонено)
resolution	string	—	480p, 720p, 1080p
aspect_ratio	string	—	16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16

У этой модели нет auto соотношения сторон (у её аналога image-to-video оно есть; у этого эндпоинта text-to-video — нет). Указывайте соотношение явно, иначе получите соотношение по умолчанию.

Вот реальный ответ завершённой задачи:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E3QKSB2TAJRDHR5Y8EQNEB",
    "model": "grok-imagine-1.5-lite/text-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      { "type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1793153637 }
    ]
  },
  "message": "success"
}

Вот фрагмент, сгенерированный этой моделью (эталонный вывод hiapi для grok-imagine-1.5-lite/text-to-video, созданный по примеру подсказки из его документации — "на рассвете стеклянный воздушный шар плывёт над террасами"):

3. Ввод в эксплуатацию

Используйте callback вместо опроса. Опрос хорош для скриптов; для сервера добавьте callback, чтобы не держать запрос открытым. Когда задача переходит в конечное состояние, платформа POST-ит детали задачи на ваш URL:

{
  "model": "grok-imagine-1.5-lite/text-to-video",
  "input": { "prompt": "...", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9" },
  "callback": { "url": "https://your.app/hooks/hiapi", "when": "final" }
}

Для этого типа задачи when принимает только "final". Дедуплицируйте в обработчике по taskId — callback может повторяться, поэтому обработчик должен быть идемпотентным.

URL вывода истекают. Обратите внимание на storage: "temp" и unix-метку expireAt — временные выводы хранятся на temp.hiapi.ai около 7 дней, после чего возвращают 404. Не сохраняйте горячие ссылки. Скачайте байты сразу после успеха задачи или вызовите эндпоинт переноса в хранилище, чтобы переместить артефакт в постоянное хранилище до истечения TTL.

Стоимость считается по секундам вывода. Тарификация зависит только от duration и запрошенного разрешения. При тестировании: 480P $0.029/s, 720P $0.043/s, 1080P $0.20/s. Так, 5-секундный фрагмент 720P стоит около $0.215, 5-секундный 1080P — около $1.00, 1-секундный 480P — около $0.029. Тариф 1080P примерно в 5 раз выше 720P — используйте его, только если действительно нужно такое разрешение. Актуальные цифры см. на странице цен.

Обработка ошибок. Отклонённые запросы возвращают HTTP 400 с точным сообщением, которое можно логировать и обрабатывать. Валидация происходит до создания задачи, поэтому 400 здесь не влечёт расходов. Реальные ответы, которые я получил на практике:

invalid input: duration: maximum: got 999, want 15
invalid input: duration: minimum: got 0, want 1
invalid input: duration: got number, want integer
invalid input: resolution: value must be one of '480p', '720p', '1080p'
invalid input: aspect_ratio: value must be one of '16:9', '4:3', '3:2', '1:1', '2:3', '3:4', '9:16'
invalid input: prompt: missing required field "prompt"
invalid input: <root>: additional properties 'bogus_field' not allowed

Если задача принята, но затем завершается ошибкой, это проявляется как data.status: "fail" с объектом data.error в эндпоинте деталей — а не как HTTP-ошибка, поэтому проверяйте status, а не полагайтесь на HTTP-код при опросе.

4. Что я наблюдал на практике

Я запустил реальную генерацию, чтобы подтвердить сквозной процесс (а не только схему): duration: 1, resolution: "480p", aspect_ratio: "16:9".

• Оно действительно работает и тарифицируется — POST вернул taskId, задача завершилась с реальным URL вывода. Серверная отрисовка 1-секундного фрагмента заняла около 51 секунды; даже крошечные фрагменты не мгновенны, поэтому ставьте щедрый дедлайн опроса (я поставил 300 секунд).
• Задача проходит через промежуточные состояния. Поле status последовательно проходит handling → archiving → success. Только success и fail — конечные; не считайте archiving завершением.
• 480P при 16:9 рендерится как 848×480 H.264. Запустите ffprobe на скачанном файле: видеопоток H.264 (848×480) плюс встроенный поток миниатюр MJPEG. Этот файл размером 495 КБ — валидный MP4.
• Аудио всегда встроено. Даже если в моей подсказке упоминался только "тихий фоновый ветер", вывод содержал дорожку AAC — модель синтезирует подходящее аудио и микширует его в тот же MP4. Отдельного URL аудио нет, и переключателя для его отключения тоже нет; если нужен беззвучный фрагмент, удалите дорожку сами (ffmpeg -an).

Оговорка о масштабе: я проверил контракт API, три типа ошибок выше и одну отрисовку 480P. Я не проводил бенчмарки качества вывода 720P/1080P или длинных (15 секунд) длительностей, поэтому не делаю по ним утверждений о качестве — лишь отмечаю, что схема их принимает и тарификация идёт по секундам.

5. Сравнение Lite и стандартного API Grok Imagine для видео

Перед разработкой выберите правильный эндпоинт:

• grok-imagine-1.5-lite/text-to-video (эта страница): 480P/720P/1080P, 1–15 секунд (поэтому можно создавать 1- или 2-секундные фрагменты), цена $0.029–$0.20/s. Это единственный эндпоинт text-to-video 1.5-го поколения, размещённый на hiapi, и единственный уровень Grok t2v, достигающий 1080P.
• grok-imagine/text-to-video (более старый стандартный уровень, см. это руководство): дешевле за секунду ($0.0114–$0.0214/s) и имеет Motion Modes, но максимум 720p и требует длительности 6–30 секунд — невозможно создать фрагмент короче 6 секунд.

Так что "lite" здесь — не самый дешёвый вариант за секунду; это уровень, который открывает 1080P и очень короткие фрагменты. Если вы хотите подавать на вход одно статичное изображение, а не текст, используйте эндпоинт того же уровня grok-imagine-1.5-lite/image-to-video (та же цена, вход — image_urls).

6. Полезные ссылки

• Страница модели grok-imagine-1.5-lite text-to-video / площадка для испытаний
• Создание задачи — справочник API
• Получение деталей задачи — справочник API
• Цены

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

Обязательно ли опрашивать или есть callback? Оба варианта работают. Скрипты используют опрос через GET /v1/tasks/{taskId}; серверы добавляют callback.url и устанавливают when в "final". Дедуплицируйте по taskId.

Почему мой запрос возвращает 400 с сообщением "must be a JSON object"? Ваши поля не обёрнуты в input. Тело запроса должно быть {"model": "...", "input": { ... }}.

Можно ли отключить аудио? При запросе — нет; каждый вывод содержит смикшированную дорожку AAC. Если нужна тишина, удалите её ниже по потоку с помощью ffmpeg -an.

Сколько действует URL вывода? Это временный URL с expireAt (около 7 дней). Скачайте сразу или перенесите в постоянное хранилище; не используйте его как горячую ссылку.

Какой самый дешёвый допустимый запрос? 1 секунда в 480P стоит около $0.029. До пакетной обработки это хороший способ в качестве канареечного запроса убедиться, что на вашем ключе есть баланс.