Как использовать Grok Imagine API для генерации видео по тексту: curl, Python и один рабочий запрос

Grok Imagine — это видеомодель от xAI, а HiAPI открывает её вариант «текст в видео» через тот же универсальный асинхронный эндпоинт, что и все остальные генеративные модели: POST /v1/tasks. Вы отправляете промпт (плюс необязательные длительность, режим, соотношение сторон и разрешение), сразу получаете taskId и после завершения задачи получаете URL .mp4.

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

Что вы создаёте и что вам нужно

Цель: через grok-imagine/text-to-video, полностью по HTTP, превратить текстовый промпт в видеоклип длительностью 6–30 секунд.

Вам нужно только одно: API-ключ HiAPI. Создайте его в панели HiAPI — один ключ работает со всеми моделями, поэтому если вы уже вызывали на HiAPI модели изображений, тот же ключ подойдёт и здесь. Запросы аутентифицируются стандартным заголовком bearer:

Authorization: Bearer sk-<your-key>

Входная схема (до написания любого кода)

Task API строго валидирует input по модели — неизвестные поля отклоняются с 400, а не молча игнорируются. Вот полная схема для grok-imagine/text-to-video:

Поле	Тип	Обязательно	Значения	По умолчанию
prompt	string	Да	до 5000 символов, лучше всего работает на английском	—
duration	integer	Нет	6–30 (секунд)	6
mode	enum	Нет	fun, normal	normal
aspect_ratio	enum	Нет	2:3, 3:2, 1:1, 16:9, 9:16	2:3
resolution	enum	Нет	480p, 720p	480p

Три вещи стоит знать заранее:

• mode — это переключатель «режима движения». normal — сбалансированный; fun создаёт более креативное, более преувеличенное движение. Если вы где-то видели, что режимы Grok Imagine описываются другими именами, параметр API — это mode — отправка чего-то вроде motion_mode даст вам 400 additional properties 'motion_mode' not allowed.
• duration линейно влияет на стоимость. Grok Imagine тарифицируется по секундам вывода, поэтому 30-секундный клип стоит в 5 раз дороже 6-секундного. Актуальный тариф за секунду см. на странице тарифов HiAPI.
• Соотношение сторон по умолчанию — 2:3 (портрет). Если вам нужен широкоэкранный формат, явно передайте 16:9 — это застаёт врасплох пользователей, переходящих с моделей, где по умолчанию горизонтальный формат.

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

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: duration: maximum: got 31, want 30"}

Минимальный рабочий пример: curl

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

1. Создать задачу:

export HIAPI_API_KEY="sk-..."

curl -sS -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-video",
    "input": {
      "prompt": "A red fox trotting through fresh snow at dawn, low golden light, cinematic tracking shot",
      "duration": 6,
      "mode": "normal",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Обратите внимание, что id модели — это просто строка grok-imagine/text-to-video — без префикса провайдера и без суффикса версии.

2. Опрашивать до терминального состояния:

TASK_ID="tk-hiapi-..."

curl -sS "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# while .data.status is "handling", sleep a few seconds and retry.
# On success:
# {
#   "code": 200,
#   "data": {
#     "status": "success",
#     "model": "grok-imagine/text-to-video",
#     "output": [
#       {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1783300000}
#     ],
#     ...
#   }
# }

URL .mp4 — временный: expireAt — это Unix-временная метка примерно на неделю вперёд. Скачайте байты сразу после успешного завершения задачи и сохраните их самостоятельно; не используйте горячие ссылки на URL temp.hiapi.ai нигде, где их видят пользователи. (Если вы когда-либо сталкивались с нерабочими ссылками на вывод, причина именно в этом — см. URL вывода hiapi истёк: скачайте до истечения срока.)

Python: небольшой клиент с опросом

Повторно используемый скрипт для того же процесса — создание, опрос с дедлайном, скачивание:

# pip install requests
import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}


def create_task(prompt: str, duration: int = 6, mode: str = "normal",
                aspect_ratio: str = "16:9", resolution: str = "720p") -> str:
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "grok-imagine/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # 6-30, billed per second
            "mode": mode,                  # "normal" | "fun"
            "aspect_ratio": aspect_ratio,  # "2:3" | "3:2" | "1:1" | "16:9" | "9:16"
            "resolution": resolution,      # "480p" | "720p"
        },
    }, timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id


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}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task(
        "A red fox trotting through fresh snow at dawn, low golden light, "
        "cinematic tracking shot",
        duration=6,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    video = requests.get(url, timeout=120).content   # expires — persist now
    with open("fox.mp4", "wb") as f:
        f.write(video)
    print(f"saved fox.mp4 ({len(video)} bytes)")

6-секундный клип обычно завершается задолго до указанного 15-минутного дедлайна; более длинные ролики занимают пропорционально больше времени, поэтому для 30-секундных задач сохраняйте этот щедрый тайм-аут.

Замечания для продакшена

Используйте callback вместо опроса. Для всего, что выходит за рамки скриптов, передайте при создании объект callback верхнего уровня — HiAPI отправит POST с терминальным состоянием задачи на ваш эндпоинт, и цикл опроса не потребуется:

{
  "model": "grok-imagine/text-to-video",
  "input": {"prompt": "...", "duration": 12},
  "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"}
}

when принимает только "final" (вы получите один POST, когда задача достигнет success или fail, а не промежуточный прогресс). Практическое правило: опрос подходит для CLI, пакетных заданий и любых короткоживущих сценариев; callback подходит для веб-бэкендов, иначе вы будете удерживать ёмкость рабочих процессов на многоминутный рендеринг. Если ваш callback-эндпоинт, похоже, ничего не получает, разберитесь, почему ваш callback задачи hiapi не срабатывает.

Идемпотентность. Создание задачи не идемпотентно — повторная попытка создать задачу после тайм-аута может породить две платные задачи. Записывайте taskId в момент его получения и при неоднозначном сбое (сетевой тайм-аут при создании) проверяйте историю задач перед повторной отправкой. Поскольку duration тарифицируется по секундам, дублирующая 30-секундная задача — это дорогой вид дублирования.

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

• Ошибки схемы 400 (error_code: "INVALID_REQUEST") — неверное имя поля, длительность вне диапазона, недопустимое значение перечисления. Они детерминированы; исправьте запрос, не повторяйте его.
• Сбои аутентификации — недействительный ключ или ключ без доступа к этой модели возвращает 401 с "code": "permission_denied" и сообщением "This API key cannot use the selected model." Проверьте ключ в панели и убедитесь, что модель для него включена.
• Сбои на уровне задачи — создание прошло успешно, но задача затем перешла в терминальное состояние с status: "fail" и объектом error (политика контента, ёмкость на стороне апстрима). Их стоит один раз повторить с экспоненциальной задержкой. Если задача, похоже, зависла в handling, см. диагностика зависших или превысивших тайм-аут заданий /v1/tasks.

Дальнейшие шаги

• Страница модели Grok Imagine текст в видео — песочница и текущие цены
• Справочник входных данных модели — каноничная схема для этой модели
• Создание задачи и получение сведений о задаче — полная обёртка асинхронного API
• Быстрый старт — выполните первый вызов HiAPI от начала до конца, а также аутентификация о работе с ключами

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

Что такое Grok Imagine API и как получить к нему доступ? Grok Imagine — это видеомодель от xAI. Через HiAPI вы вызываете её с помощью одного ключа HiAPI на унифицированном эндпоинте POST /v1/tasks как grok-imagine/text-to-video — отдельная учётная запись xAI или SDK не нужна.

Какой длины может быть видео Grok Imagine? duration принимает целое число от 6 до 30 секунд (по умолчанию 6). Значения вне этого диапазона отклоняются с 400 при создании, тарификация идёт по секундам вывода.

В чём разница между режимами fun и normal? normal (по умолчанию) даёт сбалансированное, реалистичное движение; fun больше склоняется к креативности и преувеличению. Это единственный переключатель стиля движения, который предоставляет API — выбор делается для каждого запроса, а не для учётной записи.

Поддерживает ли grok-imagine/text-to-video разрешение 1080p? Сейчас нет — resolution принимает 480p (по умолчанию) или 720p. Если вам нужно более высокое разрешение вывода, увеличьте его на последующем этапе или сравните другие видеомодели на странице моделей.

Могу ли я анимировать существующее изображение с помощью Grok Imagine? Не с этой моделью — она поддерживает только текст. На том же эндпоинте задач есть отдельная модель grok-imagine/image-to-video, принимающая изображение на вход; асинхронный жизненный цикл (создание → опрос/callback → скачивание) полностью идентичен.

Есть ли у Grok Imagine API бесплатный уровень? Генерация тарифицируется по секундам видео с вашего баланса HiAPI — бесплатного эндпоинта без ключа нет. Актуальные тарифы см. на странице цен; о том, как реально обстоят дела с «бесплатностью» в этой области, рассказывает это сравнение бесплатных API текст в видео, охватывающее разные варианты.