HiAPI
Блог

Руководство

Как вызывать wan2.7-video для генерации видео по тексту через HiAPI API: curl и Python

Nov 12, 2026
Обложка блога HiAPI: на фоне глубокого нефтяного синего — плоские геометрические срезы минералов в бирюзовых и малахитовых тонах, без глянца.
На этой странице

Что будет создано в этом руководстве

После прочтения этого руководства у вас будет рабочий небольшой конвейер: вы отправите задачу генерации видео по тексту в wan2.7-video/text-to-video через HiAPI API — сначала реализуете это с помощью curl, затем на Python — и дождётесь завершения генерации видео.

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

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

Перед отправкой первого запроса

Чтобы первый вызов прошёл успешно, нужно выполнить три условия.

Учётные данные

Вам нужен API-ключ HiAPI, который передаётся в заголовке Authorization как bearer token. Храните его в переменной окружения, а не в исходном коде:

export HIAPI_API_KEY="your-key-here"

Известный идентификатор модели

Идентификатор модели — это точная строка. В этом руководстве это значение wan2.7-video/text-to-video — включая суффикс задачи. Приблизительные варианты вроде wan2.7-video или wan2.7/text-to-video будут отклонены, поэтому копируйте идентификатор из списка моделей, а не пишите его по памяти.

Промпт, который можно оценить

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

Также понадобится HTTP-клиент и способ читать JSON. На стороне shell — curl и jq; на стороне скрипта — Python и requests.

Разбор структуры тела запроса

Запрос на генерацию видео по тексту — это JSON-объект, поля которого можно разделить на три группы.

Идентификация

  • model — точный идентификатор модели, то есть wan2.7-video/text-to-video.

Содержание

  • prompt — текст, описывающий желаемое видео. Это основное поле; конкретно указывайте движение, композицию и стиль, а не нагромождайте прилагательные.
  • negative_prompt — необязательно. Описывает то, чего не должно быть. Полезен для подавления типичных артефактов, но не заменяет хороший промпт.

Настройки генерации

  • duration — длительность выходного фрагмента.
  • resolution — размер/уровень разрешения выходного видео.
  • seed — необязательно. Фиксируйте его, когда хотите сравнить два промпта или два изменения настроек при стабильной отправной точке.

Минимальное тело запроса требует только model и prompt; платформа применит значения по умолчанию для остальных полей. Но значения по умолчанию — это не ваш выбор. О том, почему в продакшене следует задавать их явно, см. раздел о длительности и разрешении ниже.

Держите тело запроса плоским и неглубоким. Вкладывайте только те поля, которые действительно являются подобъектами, — так запрос проще читать и легче обнаруживать ошибки схемы.

Отправка задачи через curl

Ниже приведён полный пример отправки. Эндпоинт принимает JSON и возвращает дескриптор задачи, а не само видео.

curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video",
    "prompt": "медленный следящий проезд камеры по мокрому от дождя неоновому переулку ночью, отражающие лужи на земле, малая глубина резкости, кинематографическая цветокоррекция",
    "duration": 5,
    "resolution": "720p"
  }'

При успешной отправке возвращается объект, содержащий идентификатор задачи или задания и статус. Структура примерно такая:

{
  "id": "job_abc123",
  "status": "queued",
  "model": "wan2.7-video/text-to-video"
}

Следует учесть два момента. Во-первых, status не равен succeeded — на этом этапе ещё ничего не отрендерено. Во-вторых, в ответе нет URL видео. Этот URL появляется только после того, как задача достигнет терминального состояния.

Если вы хотите сохранить идентификатор в сеансе shell для шага опроса:

JOB_ID=$(curl -s -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | jq -r '.id')
echo "$JOB_ID"

Вынесение тела запроса в payload.json делает команду короче и позволяет удобнее менять промпт между запусками.

Отправка задачи на Python

Версия на Python — тот же запрос, только удобнее в использовании. То, что в curl является заголовком или ключом JSON, здесь становится именованным аргументом.

import os
import time
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 = {
    "model": "wan2.7-video/text-to-video",
    "prompt": (
        "медленный следящий проезд камеры по мокрому от дождя неоновому переулку ночью, "
        "отражающие лужи на земле, малая глубина резкости, кинематографическая цветокоррекция"
    ),
    "duration": 5,
    "resolution": "720p",
}

resp = requests.post(
    f"{BASE_URL}/v1/video/generations",
    headers=HEADERS,
    json=payload,
    timeout=30,
)
resp.raise_for_status()
job = resp.json()
print(job["id"], job["status"])

Соответствие с версией для shell — однозначное:

  • -H "Authorization: ..." → словарь HEADERS.
  • -d '<json>' → json=payload. Передача словаря вместо строки означает, что сериализацией занимается requests, поэтому некорректный JSON не будет отправлен по ошибке.
  • .id, извлекаемый через jq → job["id"].

Есть две специфичные для Python привычки, которые стоит выработать сразу. Всегда задавайте timeout для вызова отправки — этот запрос небольшой и должен возвращаться быстро, поэтому долгое зависание означает проблему с соединением, а не с рендерингом. И вызывайте raise_for_status() перед чтением тела ответа, чтобы сбой на уровне HTTP давал понятный traceback, а не сбивающий с толку KeyError на job["id"].

Работа с асинхронными задачами и опрос

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

def wait_for_job(job_id, interval=5, max_attempts=120):
    url = f"{BASE_URL}/v1/video/generations/{job_id}"
    for attempt in range(max_attempts):
        r = requests.get(url, headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "succeeded":
            return data
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"Job {job_id} ended as {status}: {data.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job_id} still not finished after {max_attempts} polls")

В этом цикле есть несколько проектных решений, важность которых выше, чем кажется:

Явно проверяйте терминальные состояния. Если считать все состояния, отличные от succeeded, поводом «продолжать ждать», то неудачные задачи будут молча расходовать весь ваш бюджет опроса. Сопоставляйте состояния неудачи и выбрасывайте исключение.

Осознанно выбирайте интервал опроса. Рендеринг видео занимает от десятков секунд до нескольких минут. Опрос каждые 200 миллисекунд лишь увеличивает нагрузку и не даёт новой информации. Начните примерно с 5 секунд; если задачи часто выполняются долго, увеличивайте интервал, а не количество попыток.

Всегда ограничивайте цикл. Верхняя граница max_attempts превращает бесконечное зависание в диагностируемый TimeoutError. Также записывайте ID задачи — это значение понадобится при диагностике.

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

При успехе ответ будет содержать расположение готового ресурса. Скачайте его сразу и не рассматривайте запись задачи как постоянное хранилище.

Выбор длительности и разрешения

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

Длительность

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

  • Короткие (несколько секунд) — социальные циклы, ключевые визуалы продукта, B-roll. Дешевле всего итерировать и проще всего оценивать.
  • Средние — повествовательные такты, установочные кадры.
  • Длинные — только если этого действительно требует история. Если нужен длинный ролик, рассмотрите генерацию нескольких коротких фрагментов с последующим монтажом; это обычно дешевле одного длинного рендера и даёт больше контроля.

При итерации по промпту генерируйте самый короткий фрагмент, который допускает модель. Оценивайте композицию и движение на этой длине, а затем увеличивайте время, когда результат устроит.

Разрешение

Более высокое разрешение означает больше пикселей на кадр, более длительный рендеринг и более высокую стоимость. Но на маленьких экранах оно важно меньше, чем кажется. Мастер в 1080p подходит для передачи клиенту; черновик в 720p (или ниже) подходит для оценки того, работает ли промпт.

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

Диагностика типичных ошибок

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

401 / 403 — проблемы с учётными данными

Проверьте, что ключ задан в окружении, фактически видимом процессу (ключ, экспортированный в одном shell, не виден службе systemd), что заголовок имеет вид Authorization: Bearer <key> и что в переменной нет завершающих пробелов. При отладке выводите только первые несколько символов ключа и никогда не выводите ключ полностью.

404 — неверный путь или модель

Путь эндпоинта и идентификатор модели — разные вещи, и оба должны быть точными. Проверьте URL, на который вы отправляете POST, и убедитесь, что wan2.7-video/text-to-video скопирован из списка моделей посимвольно. Действительный ключ с неверной строкой модели всё равно вернёт ошибку, похожую на not-found.

400 — некорректный формат тела запроса

Это самая частая категория. Типичные причины: числовые поля вроде duration отправляются как строка "5", промпт отправляется как список, а не строка, или тело запроса случайно закодировано дважды. Самый быстрый способ триажа — повторно отправить ту же самую команду curl: если вызов из shell проходит, а вызов из Python падает, проблема в том, как скрипт строит словарь, а не в самом запросе.

422 / ошибки валидации

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

Задача завершается неудачей после отправки

Вызов отправки прошёл успешно, но рендеринг не удался. Это может быть отказ по политике контента или временный сбой рендеринга. Запишите ID задачи и полезную нагрузку ошибки; при временной проблеме повторная отправка той же нагрузки — разумный первый шаг. Если один и тот же промпт повторяется, измените формулировку промпта или настройки генерации, а не повторяйте один и тот же запрос.

Опрос никогда не завершается

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

При каждой новой проблеме начинайте с эталонной реализации на curl: она исключает ваш код из уравнения и позволяет изолировать причину — в запросе или в клиенте.

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

Все статьи →

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

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

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