HiAPI
Блог

Руководство

Как использовать pixverse-v6-max image-to-video через HiAPI API: curl, Python и один рабочий запрос

Nov 13, 2026
Обложка в стиле плоской редакционной иллюстрации: на тёмно-сосново-зелёном фоне крупная призма разделена на цветовые блоки шалфейно-зелёного и туманно-зелёного оттенков.
На этой странице

Что требуется эндпоинту pixverse-v6-max image-to-video

Эндпоинт pixverse-v6-max/image-to-video в HiAPI — это асинхронная задача генерации видео, обусловленная изображением. Эта фраза определяет почти каждое решение, которое вы примете при интеграции.

Эндпоинт принимает исходное изображение (первый кадр) и набор параметров генерации, а возвращает ссылку на задачу, а не готовое видео. Сама отрисовка происходит на сервере и в зависимости от выбранных параметров может занять от нескольких секунд до нескольких минут. Ваш клиент отправляет задачу, а затем периодически запрашивает её статус, пока не получит конечное состояние.

Сравните это с синхронным редактированием изображений: при синхронном редактировании вы POSTите тело запроса и сразу в том же HTTP-ответе получаете преобразованное изображение. Здесь же процесс такой:

  1. POSTите изображение и параметры на эндпоинт генерации.
  2. Получаете идентификатор задачи (обычно вместе с начальным статусом).
  3. С интервалом GETите статус задачи, пока она не завершится или не упадёт.
  4. Читаете URL сгенерированного видео из тела ответа завершённой задачи.

Из-за такого разделения возникают два разных класса ошибок: проблемы на этапе отправки (ошибки аутентификации, неверно сформированное тело запроса, отклонённое изображение) и проблемы на этапе выполнения (задача принята, но затем завершилась ошибкой или зависла). Хорошая интеграция обрабатывает оба класса явно — конкретный чек-лист приведён в разделе диагностики ниже.

Ещё одно, что стоит запомнить: исходное изображение — это якорь. Модель начинает анимацию с этого первого кадра, поэтому качество, соотношение сторон и содержимое изображения влияют на результат сильнее, чем любой текст промпта, который вы передаёте. Считайте корректность загрузки главным приоритетом, а не чем-то второстепенным.

Подготовьте API-ключ и эндпоинт

Перед первым запросом вам нужны всего две вещи: API-ключ HiAPI и правильный базовый URL эндпоинта.

Получите ключ

Создайте API-ключ в консоли вашего аккаунта HiAPI. Обращайтесь с ним как с паролем: храните в переменной окружения, а не в исходном коде или истории командной оболочки.

export HIAPI_API_KEY="your_key_here"

Если вы локально используете файл .env, добавьте его в .gitignore до того, как что-либо закоммитите. Любой ключ, попавший в общие логи, скриншоты или репозиторий, следует немедленно отозвать.

Узнайте базовый URL и путь

Эндпоинт расположен на хосте HiAPI API, путь модели — pixverse-v6-max/image-to-video. В примерах ниже базовый URL указан как https://api.hiapi.ai, полный путь составляется из него. Если ваш аккаунт или регион выдаёт другой хост, замените его согласованно — несовпадение хоста и ключа является одной из самых частых причин 401, которую разработчики ошибочно принимают за «недействительный ключ».

Выберите инструмент

  • curl для первой быстрой проверки — он исключает все переменные, кроме самого запроса.
  • Python 3 с requests (или httpx) для реальной интеграции.
python3 -c "import requests; print(requests.__version__)"

Если он выводит номер версии, вы готовы. Примерам в этой статье SDK не нужен; всё — чистый HTTP, а значит, вы позже сможете перенести это на любой язык. Как только ключ и хост проверены, можно начинать собирать запрос.

Соберите запрос с помощью curl

Начните с минимального запроса, который действительно срабатывает, и только потом добавляйте параметры. Ниже показано тело, демонстрирующее структуру полной отправки image-to-video.

curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://your-cdn.example.com/first-frame.jpg",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Здесь происходит три вещи:

  • Аутентификация передаётся как bearer-токен в заголовке Authorization.
  • Тело запроса — JSON, поэтому изображение указывается как URL-строка (как вместо этого передать локальный файл — в следующем разделе).
  • Два параметра генерации — duration и aspect_ratio — находятся на верхнем уровне полей.

Успешная отправка возвращает JSON-объект с идентификатором задачи. Захватите его:

JOB_ID=$(curl -s -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"https://your-cdn.example.com/first-frame.jpg","duration":5,"aspect_ratio":"16:9"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "$JOB_ID"

Затем опрашивайте его:

curl -s "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

При ошибках обязательно проверяйте поле статуса и исходное тело ответа с ошибкой. curl может выводить JSON с ошибкой при коде выхода 0, поэтому в скриптах не полагайтесь только на код выхода.

Правильно передайте изображение первого кадра

Исходное изображение — самая частая точка отказа, и почти каждое отклонение сводится к одной из четырёх причин.

1. Изображение недоступно

Когда вы передаёте URL, серверы HiAPI должны уметь выполнить GET по нему — из их сети, а не из вашей. URL с localhost, приватное хранилище, подписанный URL, истекающий через шестьдесят секунд, или эндпоинт за VPN — всё это не сработает. Используйте публично доступный URL объектного хранилища или ссылку на CDN и убедитесь, что она открывается в новой сессии браузера без cookie.

2. Формат изображения не поддерживается

Придерживайтесь стандартных веб-форматов — JPEG, PNG, WebP. Файлы с необычными расширениями, HEIC со смартфонов или анимированные GIF рискованны. Если ваш пайплайн выдаёт экзотический формат, сначала выполните перекодирование.

3. Первый кадр не соответствует заявленному соотношению сторон

Это более тонкий момент. Если исходное изображение квадратное, а вы запрашиваете 16:9, сервису придётся обрезать, добавить поля или отклонить вход. Поведение может различаться, и ни один из этих вариантов не нужен большинству разработчиков. Обрежьте или добавьте поля до загрузки, чтобы геометрия изображения уже соответствовала aspect_ratio, который вы будете запрашивать. Это делает результат предсказуемым и позволяет не тратить задачу впустую.

4. Изображение слишком большое или слишком маленькое

Снимки сверхвысокого разрешения (например, с 8K-камеры) расходуют полосу пропускания и могут быть отклонены или уменьшены; крошечные миниатюры оставляют модели почти ничего для анимации. Приведите изображение к разумному размеру по длинной стороне как часть шага перед загрузкой.

Передача локального файла

Если эндпоинт принимает multipart-загрузку для поля изображения, схема такая:

curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -F "image=@./first-frame.jpg" \
  -F "duration=5" \
  -F "aspect_ratio=16:9"

Обратите внимание, что при multipart числовые поля становятся строками. Сверьтесь со справочной документацией эндпоинта, какие типы содержимого принимаются, и в продакшн-пайплайне предпочитайте форму с URL — так крупные бинарные файлы вообще не попадают на ваш сервер приложения.

Настройка длительности и соотношения сторон

Эти два поля влияют на стоимость и результат сильнее, чем что-либо ещё в теле запроса.

duration

duration — длительность генерируемого фрагмента в секундах. Это также поле, напрямую связанное с оплатой — тарификация рассчитывается по запрошенной длительности вывода, поэтому выбирайте осознанно, а не берите максимум по умолчанию. Практические рекомендации:

  • Начинайте с кратчайшей длительности, которая доносит вашу идею. Пятисекундный фрагмент отлично подходит для зацикливания, анонса продукта или крючка для соцсетей.
  • Используйте более длинную длительность, только если сцене действительно нужно больше времени; статичный первый кадр, анимированный долго, часто уходит в сторону и теряет связность.
  • Валидируйте на клиенте: отклоняйте нецелые, нулевые, отрицательные и абсурдно большие значения до того, как запрос покинет ваш сервис.
if not isinstance(duration, int) or not 1 <= duration <= 8:
    raise ValueError("duration out of supported range")

Уточните текущий поддерживаемый диапазон в справочной документации эндпоинта и отразите его в своей логике валидации — не зашивайте в код допущения из этой статьи.

aspect_ratio

aspect_ratio — строка, например "16:9", "9:16" или "1:1". Она управляет геометрией выходного кадра.

  • 16:9 для горизонтального видео: YouTube, веб-баннеры, воспроизведение на десктопе.
  • 9:16 для вертикального: Reels, Shorts, размещение в стиле TikTok.
  • 1:1 для лент и миниатюр.

Два правила избавят вас от проблем. Во-первых, соответствие исходного изображения запрашиваемой пропорции — вертикальный первый кадр в горизонтальном запросе приведёт к обрезке, которую вы, скорее всего, не хотели. Во-вторых, относитесь к пропорции как к перечислению, а не свободному тексту: валидируйте по белому списку, чтобы опечатка вроде "16x9" быстро падала в вашем коде, а не после одного сетевого запроса.

Всё остальное

Если эндпоинт предоставляет дополнительные параметры генерации, оставьте их вне первого запроса. Минимальное проверенное тело запроса — это ваша база; добавляйте по одному параметру за раз и сравнивайте результат. Такая дисциплина делает очевидным, какое поле вызвало регрессию.

Тот же запрос на Python

Ниже — перенос curl-процесса на Python. Зависимости намеренно минимальны: requests плюс стандартная библиотека.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def submit(image_url: str, duration: int = 5, aspect_ratio: str = "16:9") -> str:
    resp = requests.post(
        f"{BASE}/v1/pixverse-v6-max/image-to-video",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image": image_url, "duration": duration, "aspect_ratio": aspect_ratio},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]

def fetch(job_id: str) -> dict:
    resp = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)
    resp.raise_for_status()
    return resp.json()

if __name__ == "__main__":
    job_id = submit("https://your-cdn.example.com/first-frame.jpg")
    print("submitted", job_id)

Несколько намеренных решений, которые стоит перенять:

  • raise_for_status() при отправке. 400 или 401 должны немедленно проявляться как исключение, а не превращаться в KeyError, когда вы попытаетесь прочитать ["id"] из тела ошибочного ответа.
  • Явные таймауты. Без таймаута зависшее соединение подвесит ваш воркер навсегда.
  • Конфигурация из окружения. Базовый URL и ключ никогда не зашиваются в код.
  • Маленькие типизированные вспомогательные функции. submit возвращает строку идентификатора задачи; fetch возвращает словарь. Сосредоточение разбора в одном месте означает, что при изменении схемы нужно править одну строку.

Если вы предпочитаете httpx, просто замените на httpx.post(...) и httpx.get(...); в остальном вызовы идентичны. Для всего, что работает внутри обработчика веб-запросов, отправляйте задачу здесь, а идентификатор задачи передавайте фоновому воркеру, вместо того чтобы заставлять HTTP-запрос пользователя блокироваться на генерации видео.

Опрос асинхронной задачи до завершения

Опрос — та часть, которую большинство руководств обходят стороной и которая является источником большинства инцидентов. Сам цикл короткий; дисциплина вокруг него — вот что важно.

def wait_for_video(job_id: str, timeout: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        job = fetch(job_id)
        status = job.get("status")
        if status == "completed":
            return job["output"]["video_url"]
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"job {job_id} ended as {status}: {job.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish within {timeout}s")

Ключевые моменты, заложенные выше:

  • Всегда задавайте дедлайн. Генерация видео медленная; бесконечный цикл превращается в бесконечные счета и зависшие воркеры. Десять минут — разумный верхний предел для коротких видео; скорректируйте его под вашу длительность.
  • Различайте конечные состояния. Только completed даёт URL. failed и cancelled тоже конечные — прекращайте опрос и показывайте поле error.
  • Используйте разумный интервал. Каждые несколько секунд достаточно. Частые запросы к эндпоинту статуса приведут к ограничению скорости и не дадут новой информации.
  • Мягкое увеличение интервала для длинных задач: после первой минуты увеличивайте интервал с 3 до 10 секунд. Это снижает нагрузку и не добавляет задержки.
  • Сохраняйте идентификаторы задач. Храните их вместе со своими записями, чтобы при перезапуске процесса можно было возобновить опрос, а не отправлять заново — и снова оплачивать — ту же задачу.
  • Никогда не опрашивайте напрямую из браузера с вашим API-ключом. Проксируйте проверку статуса через свой бэкенд.

Когда задача завершена, своевременно скачайте видео в собственное хранилище, а не ссылайтесь вечно на возвращённый URL; URL сгенерированных ресурсов не гарантируют постоянную доступность.

Диагностика неудачных и зависших задач

Проходите этот чек-лист по порядку. Каждый шаг изолирует один уровень.

Ошибки отправки (задача не создана)

  • 401 Unauthorized — ключ отсутствует, неверно отформатирован, отозван или указан для неправильного хоста. Проверьте, что заголовок ровно Authorization: Bearer <key> с одним пробелом в середине и что в переменной окружения нет лишнего перевода строки.
  • 403 Forbidden — ключ действителен, но не разрешён для этой модели или эндпоинта. Проверьте путь ресурса посимвольно: pixverse-v6-max/image-to-video.
  • 400 Bad Request — ваш JSON неверно сформирован или какое-то поле недопустимо. Декодируйте тело ответа с ошибкой; обычно оно указывает на проблемное поле. Частые виновники: duration — строка вместо числа, "16x9" вместо "16:9", отсутствует image.
  • Ошибки валидации типа 422 — поле присутствует, но вне диапазона. Сверяйтесь со справочной документацией эндпоинта, а не угадывайте.
  • 429 Too Many Requests — вы отправляете слишком быстро. Поставьте отправки в очередь и повторяйте с экспоненциальной задержкой и джиттером; никогда не повторяйте в плотном цикле.

Ошибки выполнения (задача создана, но не завершилась успешно)

  • Статус failed с ошибкой, связанной с изображением — после отправки не удалось получить исходный URL. Это классическая ловушка «у меня в браузере работает»: URL требует cookie, referrer или белого списка IP. Переразместите изображение публично.
  • Статус failed с ошибкой контента или валидации — исходное изображение отклонено по техническим причинам (формат, геометрия, размер). Перекодируйте, измените размер и обрежьте под заявленное соотношение сторон.
  • Задача остаётся в очереди или в обработке после вашего дедлайна — сначала убедитесь, что вы читаете правильный идентификатор задачи (ошибки копирования-вставки удивительно распространены). Затем проверьте, действительно ли статус не изменился или ваш опрос идёт на неверный базовый URL. Если задача действительно зависла, отмените её и отправьте заново один раз, если API это позволяет; многократная молчаливая повторная отправка — именно так исчезает бюджет.

Привычка, экономящая время

Логируйте полный идентификатор запроса, идентификатор задачи, HTTP-статус и тело ответа для каждого вызова — с маскированием ключей. Когда что-то сломается в два часа ночи, идентификатор запроса — это разница между пятиминутным исправлением и часом догадок. Начните с минимального проверенного тела запроса и добавляйте по одному параметру, и этот чек-лист вам почти наверняка не понадобится.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API