Как использовать grok-imagine-1.5/image-to-video через hiapi API: curl, Python и готовый к запуску запрос

Краткое резюме

• Что это: готовое к копированию руководство о том, как с помощью единого API задач hiapi использовать grok-imagine-1.5/image-to-video для анимации статичного изображения в короткое видео.
• Процесс: создайте задачу через POST /v1/tasks, опрашивайте GET /v1/tasks/<taskId> (или зарегистрируйте callback), затем до истечения срока скачайте MP4 из data.output[0].url.
• Схема ввода (проверено по онлайн-API): принимается только один элемент image_urls, необязательный prompt, duration от 1 до 15 секунд, resolution — 480p/720p, aspect_ratio — одно из auto, 1:1, 16:9, 9:16, 3:2, 2:3. Другие поля не принимаются.

Что вы создадите и что нужно подготовить

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

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

• API-ключ hiapi — создайте его в панели управления. Ключ имеет вид sk-... и передаётся в заголовке Authorization: Bearer.
• Публично доступный URL исходного изображения (JPEG/PNG). API загружает изображение на сервере, поэтому ссылки на localhost или файлы, требующие аутентификации, не подойдут.
• Любой HTTP-клиент. В примерах ниже используются curl и Python requests.

Идентификатор модели — это голая строка grok-imagine-1.5/image-to-video, без суффикса.

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

Создание задачи:

curl -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/image-to-video",
    "input": {
      "image_urls": ["https://example.com/product-shot.jpg"],
      "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Успешная отправка вернёт 200 и taskId:

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5", "status": "queued" },
  "message": "success"
}

Опрашивайте до достижения задачей конечного состояния (status последовательно проходит queued → handling → success или fail):

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5" \
  -H "Authorization: Bearer sk-YOUR_KEY"

Завершённая задача (реальный ответ, сокращён):

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

⚠️ storage: "temp" и expireAt означают, что URL для скачивания временный. Сразу после успеха задачи скачайте MP4 и сохраните его в своей инфраструктуре — не используйте горячие ссылки.

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

Полный скрипт — создание, опрос, скачивание:

import time
import requests

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

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json={
    "model": "grok-imagine-1.5/image-to-video",
    "input": {
        "image_urls": ["https://example.com/product-shot.jpg"],
        "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
        "duration": 6,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll for the result (image-to-video usually lands well within a few minutes)
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS).json()["data"]
    status = task["status"]
    if status == "success":
        break
    if status == "fail":
        raise RuntimeError(f"generation failed: {task.get('error')}")
    time.sleep(5)
else:
    raise TimeoutError(f"task {task_id} still not finished after 10 min")

# 3. Download immediately — the output URL expires
video_url = task["output"][0]["url"]
mp4 = requests.get(video_url, timeout=120)
mp4.raise_for_status()
with open("clip.mp4", "wb") as f:
    f.write(mp4.content)
print("saved clip.mp4,", len(mp4.content), "bytes")

Справочник по вводу (что реально принимает схема)

Эти ограничения взяты напрямую из онлайн-валидатора, а не из догадок — отправка чего-либо другого вернёт 400 INVALID_REQUEST с точным сообщением:

Поле	Тип	Правило
image_urls	массив строк	Обязательно, ровно 1 URL (maxItems: 1)
prompt	строка	Необязательно — описывает движение, движение камеры и настроение
duration	целое число	1–15 секунд
resolution	строка	480p или 720p
aspect_ratio	строка	auto, 1:1, 16:9, 9:16, 3:2, 2:3

Примечания:

• У этой модели нет полей seed, negative_prompt, fps, motion_strength или camera_fixed. Схема отклоняет неизвестные свойства (additional properties ... not allowed), поэтому управляйте движением и поведением камеры исключительно через prompt.
• На каждую задачу допускается только одно исходное изображение. Передача двух вернёт image_urls: maxItems: got 2, want 1.
• aspect_ratio: "auto" сохраняет собственные пропорции исходного изображения — обычно именно это и нужно для товарных фото.
• Более старая grok-imagine/image-to-video принимает до 30 секунд за клип; у 1.5上限 15 секунд. Цена за секунду у обеих одинакова: $0.015 для 480p и $0.0282 для 720p.

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

Используйте callback вместо опроса. Для любого сценария за пределами скрипта зарегистрируйте webhook при создании задачи и пропустите цикл опроса:

{
  "model": "grok-imagine-1.5/image-to-video",
  "input": { "image_urls": ["https://example.com/shot.jpg"], "duration": 6 },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

callback.url должен быть публичным http(s)-эндпоинтом, а when поддерживает только "final" — вы получите один POST, когда задача достигнет success или fail. Опрос подходит для CLI и пакетных задач; callback лучше, когда нужно массово генерировать много клипов и не хочется разворачивать толпу опросчиков. Оставьте запасной опрос (например, периодически проверяйте задачи, по которым не пришёл callback), чтобы потеря webhook не оставила задачу без внимания.

Идемпотентность. Создание задач на сервере не дедуплицируется, поэтому простой повтор после сетевого таймаута может привести к дублирующим отправкам и двойному списанию. Сохраняйте taskId сразу после возврата вызова создания, а при повторе сначала проверяйте своё хранилище; если вы упали между отправкой и сохранением, перечислите последние задачи (GET /v1/tasks) и сопоставьте по модели + времени создания перед повторной отправкой.

Обработка ошибок. Режимы отказа, с которыми вы реально столкнётесь:

• 401 с {"error": {"code": "permission_denied", "type": "hiapi_error", ...}} — неверный ключ или у ключа нет доступа к модели. В ответе есть request_id для поддержки.
• 400 с error_code: "INVALID_REQUEST" — нарушение схемы; message укажет конкретное поле и правило (например, duration: maximum: got 99, want 15). Исправьте тело запроса, не повторяйте вслепую.
• 402 недостаточно средств — видеомодели предварительно проверяют вашу квоту при отправке. Пополните баланс и отправьте снова.
• Сама задача status: "fail" — сбой на стороне генерации; проверьте data.error и повторите с экспоненциальной задержкой. Частая причина — недоступность исходного изображения.

Сохраняйте результат немедленно. Стоит повторить: output[0].url находится во временном хранилище с меткой expireAt. В момент, когда видите success, сразу стримьте MP4 в собственное хранилище. Если ваш конвейер упадёт после успеха, но до скачивания, повторно получите задачу по id — URL остаётся действительным до expireAt, но не бессрочно.

Связанные материалы

• Страница модели grok-imagine-1.5/image-to-video — цены, параметры и playground в браузере
• Как использовать grok-imagine/image-to-video — предыдущая модель, тот же поток задач, лимит 30 секунд
• Руководство по Grok Imagine text-to-video — начинаем с подсказки, а не с изображения
• Справочник по API hiapi — полный контракт API задач

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

Какой длины может быть видео grok-imagine-1.5? От 1 до 15 секунд, задаётся целочисленным полем duration. Запрос большей длительности вернёт 400 (duration: maximum: got X, want 15). Если нужно до 30 секунд, используйте более старую grok-imagine/image-to-video.

Какие разрешения и соотношения сторон поддерживаются? resolution — 480p или 720p; aspect_ratio — auto, 1:1, 16:9, 9:16, 3:2 или 2:3. 9:16 при 720p — предпочтительная комбинация для вертикальных клипов в стиле Shorts/Reels.

Можно ли передать несколько исходных изображений? Нет — image_urls этой модели принимает ровно один URL. Для рабочих процессов с несколькими референсами связывайте задачи последовательно или сначала объедините референсы в одно входное изображение.

Есть ли seed или негативная подсказка? Нет. Схема ввода напрямую отклоняет seed, negative_prompt, fps и подобные поля. Стиль движения, движение камеры и настроение полностью управляются строкой prompt.

Сколько это стоит? Оплата за секунды сгенерированного видео: $0.015/сек для 480p и $0.0282/сек для 720p. Клип на 6 секунд стоит $0.09 в 480p и $0.1692 в 720p. Если не передать duration, по умолчанию используется 8 секунд. Больше примеров в разборе цен Grok Imagine 1.5.

Почему мой запрос возвращает 401 permission_denied? Либо API-ключ неверный/отозван, либо у него нет доступа к модели. Проверьте ключ в панели управления и убедитесь, что отправляете Authorization: Bearer sk-... — отсутствие префикса Bearer даёт ту же ошибку.

Как узнать, что видео готово, без опроса? Добавьте при создании задачи "callback": {"url": "https://your-endpoint", "when": "final"}. Когда задача достигает конечного состояния, hiapi отправляет POST на ваш эндпоинт. В качестве запасного варианта опрашивайте GET /v1/tasks/<taskId>.

Почему мой URL видео перестаёт работать через несколько дней? Результат хранится во временном хранилище — каждая запись вывода содержит метку expireAt. Скачайте файл сразу после success и раздавайте его из собственного хранилища.