HiAPI
Блог

Руководство

Как использовать pixverse-v6-max/text-to-video через API HiAPI: curl, Python и рабочие примеры запросов

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

Что делает этот эндпоинт и когда его использовать

pixverse-v6-max/text-to-video — это эндпоинт генерации видео из текста в HiAPI. Вы отправляете текстовый промпт с описанием нужной сцены, а эндпоинт возвращает готовое видео. Поскольку генерация видео требует времени, эндпоинт работает асинхронно: первый запрос возвращает не само видео, а идентификатор задачи, по которому вы отслеживаете прогресс и получаете итоговый результат.

Эта схема «запрос — подтверждение — опрос» лежит в основе всего в этом руководстве. Внутренний процесс всегда одинаков:

  1. Отправьте задачу генерации с промптом и параметрами.
  2. Сразу получите идентификатор задачи.
  3. Опрашивайте задачу, пока она не сообщит о завершении (или ошибке).
  4. Скачайте или вставьте URL готового видео.

Когда уместно использовать этот эндпоинт

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

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

Перед началом: аутентификация и основы запросов

Прежде чем писать код, убедитесь в трёх вещах.

1. API-ключ

Каждый запрос к HiAPI требует аутентификации по API-ключу. Относитесь к нему как к паролю: не коммитьте в репозиторий, загружайте из переменной окружения и сразу заменяйте при утечке. Примеры ниже читают его из HIAPI_API_KEY, поэтому сначала экспортируйте его в shell:

export HIAPI_API_KEY="your_key_here"

2. Правильный базовый URL

Все запросы отправляются на базовый URL API HiAPI с добавлением пути эндпоинта. Используйте базовый URL, указанный в вашей учётной записи HiAPI, а не жёстко зашитый хост из статей в блогах — если не уверены, сверьтесь со справочником API в панели управления. В примерах ниже $HIAPI_BASE_URL служит заполнителем для этого значения.

3. Соглашения JSON

И отправка, и запрос статуса — это JSON поверх HTTPS:

  • Для каждого запроса с телом отправляйте Content-Type: application/json.
  • Для каждого запроса (включая запрос статуса) отправляйте Authorization: Bearer $HIAPI_API_KEY.
  • Ожидайте JSON, в том числе при ошибках — читайте тело ответа с ошибкой, а не только HTTP-код.

Быстрая проверка работоспособности

Если у вас есть доступный лёгкий эндпоинт (например, маршрут models или account), вызовите его один раз перед тем, как трогать видеоэндпоинт. Ответ 200 там докажет, что ваш ключ, базовый URL и формат заголовков верны, исключив сразу три переменные при дальнейшей отладке.

Рабочий запрос curl

Ниже полный вызов отправки. Путь эндпоинта — pixverse-v6-max/text-to-video; тело запроса содержит ваш промпт и параметры генерации.

curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Ночной переулок, залитый дождём, неоновый свет, медленный наезд камеры, кинематографично",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Разбор полей

  • prompt — текстовое описание. Указывайте субъект, движение, движение камеры и атмосферу. Это самый важный рычаг влияния на качество результата.
  • duration — запрашиваемая длительность фрагмента. См. раздел о длительности и соотношении сторон ниже.
  • aspect_ratio — соотношение сторон выходного кадра, например 16:9, 9:16, 1:1.

Что возвращается

Успешная отправка возвращает JSON-объект с идентификатором задачи — дескриптором для опроса. Точные имена полей смотрите в справочнике API; в этом руководстве мы называем его task_id. Сохраните его:

TASK_ID=$(curl -sS -X POST "$HIAPI_BASE_URL/pixverse-v6-max/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Ночной переулок, залитый дождём, неоновый свет, медленный наезд камеры, кинематографично","duration":5,"aspect_ratio":"16:9"}' \
  | python -c 'import sys,json; print(json.load(sys.stdin)["task_id"])')
echo "$TASK_ID"

Обратите внимание, чего в ответе нет: видео. Генерация выполняется в фоне. Считайте ответ на отправку квитанцией, а не результатом.

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

Версия на Python полностью соответствует вызову curl. Для краткости используем requests, но httpx или urllib подойдут так же — требуется лишь те же заголовки и JSON-тело.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "prompt": "Ночной переулок, залитый дождём, неоновый свет, медленный наезд камеры, кинематографично",
    "duration": 5,
    "aspect_ratio": "16:9",
}

resp = requests.post(
    f"{BASE_URL}/pixverse-v6-max/text-to-video",
    headers=headers,
    json=payload,
    timeout=30,
)

if resp.status_code >= 400:
    # Выводим тело ответа с ошибкой от сервера — обычно оно указывает проблемное поле
    raise RuntimeError(f"submit failed {resp.status_code}: {resp.text}")

data = resp.json()
task_id = data["task_id"]
print("submitted:", task_id)

Моменты, которые стоит скопировать

  • json=payload автоматически сериализует тело и задаёт тип содержимого. Если вместо этого использовать data=json.dumps(payload), нужно явно оставить заголовок Content-Type.
  • Клиентский таймаут при отправке предотвращает зависание соединения. Он не ограничивает время генерации — генерация происходит на сервере, именно поэтому нужен опрос.
  • Сначала проверяйте код статуса, потом разбирайте. Тело ответа 4xx обычно информативнее самого кода; выведите его.
  • Никогда не логируйте API-ключ. Логируйте task_id — его безопасно хранить, и это ваш отладочный дескриптор.

Параметры длительности и соотношения сторон

Эти два поля — самый частый источник отклонённых запросов, поэтому отнеситесь к ним серьёзно.

duration

duration задаёт запрашиваемую длину фрагмента в секундах. Допустимые значения ограничены поддерживаемым диапазоном эндпоинта; отправка значения вне этого диапазона обычно вызывает ошибку валидации параметра, а не молчаливое обрезание фрагмента. Выбирайте из поддерживаемых значений, указанных в справочнике API, и оставляйте целым числом. Чем длиннее фрагмент, тем дольше рендеринг, поэтому на этапе разработки предпочитайте минимальную поддерживаемую длительность — вы проверяете цепочку, а не художественность.

aspect_ratio

aspect_ratio — строка вида W:H. Согласуйте её с местом, где видео в итоге будет показано:

  • 16:9 — горизонтальное: главные баннеры сайтов, плееры в стиле YouTube, фоны рабочего стола.
  • 9:16 — вертикальное: мобильные ленты коротких видео и истории.
  • 1:1 — квадратное: сеточные раскладки и миниатюры.

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

Что проверять при отклонении

  • Несовпадение типов — duration записан строкой ("5") вместо числа, или aspect_ratio записан двумя числами. Держите duration числом, а aspect ratio строкой.
  • Неподдерживаемые значения — длительность или соотношение вне документированного диапазона. Сверьтесь с эталонным списком пункт за пунктом.
  • Именование полей — опечатки вроде aspectRatio или durationSeconds в лучшем случае молча трактуются как неизвестные поля. Копируйте имена полей из справочной документации.

Быстрый способ найти проблемное поле: сначала отправьте повторно только с prompt, затем добавляйте параметры по одному. Первое отклонение укажет на проблемное поле.

Опрос асинхронной задачи до готовности видео

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

import time
import requests

def wait_for_video(task_id, base_url, api_key, timeout=600):
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"{base_url}/tasks/{task_id}"   # маршрут статуса см. в справочнике API
    deadline = time.time() + timeout
    delay = 2

    while time.time() < deadline:
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        task = r.json()
        status = task["status"]

        if status == "succeeded":
            return task["result"]["video_url"]
        if status == "failed":
            raise RuntimeError(f"generation failed: {task.get('error')}")

        time.sleep(delay)
        delay = min(delay * 1.5, 15)   # мягкий backoff с верхней границей

    raise TimeoutError(f"task {task_id} not finished in {timeout}s")

Почему важен backoff

Опрос задачи, которой нужна минута, раз в секунду тратит десятки запросов впустую. Начинайте с малого интервала и постепенно увеличивайте — указанный выше множитель с ограничением стабилизируется на комфортном интервале, не нагружая API постоянно. Если вы запускаете много задач, очередь с одним рабочим процессом опроса дружелюбнее, чем цикл на каждый запрос.

Обработка результата

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

Устранение типичных ошибок

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

Аутентификация и доступ

  • 401 / unauthorized — ключ отсутствует, имеет неверный формат или не отправлен. Убедитесь, что заголовок точно Authorization: Bearer <key>, и что в shell или процессе, выполняющем вызов, эта переменная окружения действительно задана.
  • 403 / forbidden — ключ действителен, но доступ к этому эндпоинту не разрешён. Проверьте область прав ключа в панели управления.

Валидация запроса

  • 400 / 422 — неверный JSON или ошибочное значение поля. Выведите полное тело ответа с ошибкой; обычно оно указывает поле. Перепроверьте тип duration и строковый формат aspect_ratio.
  • 404 при отправке — неверный путь эндпоинта. Убедитесь, что путь точно pixverse-v6-max/text-to-video, а в базовом URL нет дублирующихся или отсутствующих сегментов пути.

Сбои на уровне задачи

  • Статус failed — задача принята, но генерация не удалась. Прочитайте сообщение об ошибке в задаче; оно отличает отказ по содержимому от внутреннего сбоя. Отклонённый промпт — это проблема промпта, а не API; измените и отправьте заново.
  • Застревание в рабочем статусе — задайте срок для опроса и считайте таймаут сбоем, который нужно обработать, а не исключением, роняющим сервис.

Эксплуатационные проблемы

  • 429 / срабатывание ограничения частоты — слишком много одновременных отправок или опросов. Снизьте параллелизм и соблюдайте любые подсказки о повторной попытке из ответа.
  • Таймаут соединения при отправке — проблема сети или прокси, а не генерации. Повторяйте отправку с backoff, но только если можете допустить возможные дубликаты задач.
  • 404 URL видео при скачивании — URL истёк. Запросите результат задачи заново, а не используйте старый URL.

Одна повторяемая привычка

При каждом сбое записывайте три значения: HTTP-код, тело ответа и (если есть) task_id. Эти три превращают «оно сломалось» в «оно сломалось здесь», и это единственный ключ к быстрой отладке.

Что делать дальше

Теперь у вас есть полный цикл: аутентификация, отправка, получение идентификатора задачи, опрос с backoff и получение результата. Для вывода в продакшен оформите отправку и опрос в небольшой клиентский класс, сохраняйте task_id и промпт вместе с каждым активом для прослеживаемости и вынесите опрос в фоновый рабочий процесс, чтобы пользовательские запросы никогда не блокировались из-за рендеринга.

Далее изучите соседние эндпоинты в справочнике HiAPI — видео из изображения для анимации существующих стоп-кадров и интерактивный режим итерации промптов, чтобы отточить стиль изображения до запуска полной генерации. Форма запросов, которую вы здесь освоили, переносится почти без изменений.

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

Все статьи →

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

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

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