Руководство
Как использовать pixverse-v6-max/text-to-video через API HiAPI: curl, Python и рабочие примеры запросов
На этой странице
Что делает этот эндпоинт и когда его использовать
pixverse-v6-max/text-to-video — это эндпоинт генерации видео из текста в HiAPI. Вы отправляете текстовый промпт с описанием нужной сцены, а эндпоинт возвращает готовое видео. Поскольку генерация видео требует времени, эндпоинт работает асинхронно: первый запрос возвращает не само видео, а идентификатор задачи, по которому вы отслеживаете прогресс и получаете итоговый результат.
Эта схема «запрос — подтверждение — опрос» лежит в основе всего в этом руководстве. Внутренний процесс всегда одинаков:
- Отправьте задачу генерации с промптом и параметрами.
- Сразу получите идентификатор задачи.
- Опрашивайте задачу, пока она не сообщит о завершении (или ошибке).
- Скачайте или вставьте 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 — видео из изображения для анимации существующих стоп-кадров и интерактивный режим итерации промптов, чтобы отточить стиль изображения до запуска полной генерации. Форма запросов, которую вы здесь освоили, переносится почти без изменений.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий