Создание коротких видео с помощью wan2.7-video/text-to-video@pro: сквозной рабочий процесс hiapi API

Успех коротких видео зависит от скорости итераций: вам нужно много кандидатных клипов, в вертикальном формате, со звуком, и быстро. Это руководство посвящено именно этому: используется wan2.7-video/text-to-video@pro на hiapi — модель преобразования текста в видео Alibaba Tongyi Wanxiang 2.7, с выводом до 1080P, нативным аудио и длительностью фрагмента до 15 секунд. Каждая структура запроса, граница параметров и сообщение об ошибке ниже были проверены на работающем API на момент написания статьи, а два демонстрационных фрагмента, встроенных в текст, были сгенерированы ровно тем кодом, который показан.

Что даёт модель

wan2.7-video/text-to-video@pro предоставляется через унифицированную конечную точку асинхронных задач hiapi (/v1/tasks). Ключевые возможности, проверенные по онлайн-схеме:

• Вывод: H.264 MP4, до 1080P, с нативной аудиодорожкой AAC — модель генерирует окружающие звуки и звуковые эффекты на основе вашего запроса, без отдельного шага работы со звуком.
• Длительность: 2–15 секунд на фрагмент (целые секунды).
• Соотношение сторон: 16:9, 9:16, 1:1, 4:3, 3:4 — настоящий вертикальный 9:16, подходящий для форматов Shorts/Reels/TikTok без обрезки.
• Оплата: по секундам выходного видео, на момент написания — от $0.167/сек — 5-секундный фрагмент 1080P около $0.84. Перед массовой генерацией обязательно уточните на странице тарифов.

У видео нет синхронного режима: нужно создать задачу, опрашивать её до завершения, затем скачать результат.

Минимальный работающий пример (curl)

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

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video@pro",
    "input": {
      "prompt": "Макросъёмка в студии: капля королевско-синих чернил падает в чистую воду, замедленное раскрытие, чернильные нити расходятся в форме облака, фон — яркий белый бесшовный фон, чёткая высокоключевая подсветка, мягкий окружающий гул",
      "ratio": "16:9",
      "resolution": "1080P",
      "duration": 4
    }
  }'

Ответ:

{"code": 200, "data": {"taskId": "tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R"}, "message": "success"}

Опрос результата:

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

Во время рендеринга data.status имеет значение handling; после завершения оно становится success, а MP4 содержится в data.output[0].url. Этот запрос сгенерировал следующий фрагмент без изменений:

⚠️ URL вывода — это временная ссылка с меткой времени expireAt. Сразу после успеха задачи скачайте файл в собственное хранилище — не используйте прямые ссылки и не сохраняйте их в базу данных.

Полная входная схема (проверена по онлайн-API)

API строго валидирует input и отклоняет неизвестные поля; ниже — полный список допустимых полей, полученный прямым зондированием конечной точки, а не скопированный откуда-либо:

Поле	Тип	Ограничение	Обязательность
prompt	string	Описание сцены; также управляет генерацией аудио	✅
ratio	string	Одно из 16:9, 9:16, 1:1, 4:3, 3:4	необязательно
resolution	string	720P или 1080P	необязательно
duration	integer	2–15 (секунд)	необязательно
negative_prompt	string	Что нужно подавить (например, водяные знаки, текстовые наложения)	необязательно
seed	integer	Воспроизводимость между попытками	необязательно
watermark	boolean	Переключение водяного знака провайдера	необязательно

Две ловушки, которые помогут избежать 400:

• Имя поля — ratio, а не aspect_ratio — модели изображений на hiapi используют aspect_ratio, эта видеомодель — нет. Отправка aspect_ratio вернёт additional properties 'aspect_ratio' not allowed.
• duration проверяется на сервере: duration: minimum: got 1, want 2 и maximum: got 999, want 15 — это точные ошибки, которые вы получите при выходе за диапазон 2–15.

Сквозной Python: на входе запрос, на выходе готовый к публикации MP4

Это полный рабочий процесс — создание, опрос, скачивание — без SDK, только requests:

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def make_short(prompt: str, out_path: str, duration: int = 5,
               ratio: str = "9:16", seed: int | None = None) -> str:
    payload = {
        "model": "wan2.7-video/text-to-video@pro",
        "input": {
            "prompt": prompt,
            "ratio": ratio,               # 9:16 = вертикальное короткое видео
            "resolution": "1080P",
            "duration": duration,          # 2..15 секунд
            "negative_prompt": "текстовые наложения, водяной знак, искажённые руки",
        },
    }
    if seed is not None:
        payload["input"]["seed"] = seed

    task_id = requests.post(API, headers=HEADERS, json=payload).json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)

    video_url = task["output"][0]["url"]   # временная ссылка — скачайте сразу
    with open(out_path, "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    return out_path

make_short(
    "Вертикальный кадр с рук в ночном уличном рынке в золотой час: уличный "
    "повар подбрасывает шипящую лапшу в пылающем воке, пар и оранжевые "
    "искры кружатся в сторону камеры, неоновые вывески мягко светятся розовым и бирюзовым "
    "в размытом фоне, малая глубина резкости, динамичная документальная "
    "съёмка с рук, шипение и потрескивание",
    "night-market.mp4",
    duration=5,
    seed=20260702,
)

Ниже — фрагмент, фактически сгенерированный этим вызовом: вертикальный 1080×1920, 5 секунд, шипение сгенерировано текстом запроса:

В моём запуске 4-секундный фрагмент 16:9 завершился примерно за 3 минуты, 5-секундный 9:16 — чуть дольше; закладывайте несколько минут на фрагмент, опрашивайте примерно каждые 10 секунд и не перегружайте конечную точку.

Советы по запросам для коротких видео: движение и аудио определяются запросом

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

• Явно называйте поведение камеры: например, "handheld" (с рук), "slow push-in" (медленное приближение), "macro" (макросъёмка), "shallow depth of field" (малая глубина резкости). Документальная тряска в фрагменте ночного рынка полностью исходит от слова "handheld".
• Описывайте желаемое аудио: модель генерирует звук на основе запроса. "sizzling and crackling sounds" (шипение и потрескивание) и "gentle ambient hum" (мягкий окружающий гул) оба появились в выходной аудиодорожке.
• Ставьте крючок в начало: для коротких видео первая секунда решает всё. Помещайте самый динамичный элемент (пламя под воком, капля чернил в воде) в начало описания запроса.
• Используйте negative_prompt defensive: "text overlay, watermark, distorted hands" (текстовые наложения, водяной знак, искажённые руки) убирает самые частые дефекты, не влияя на основной запрос.
• Фиксируйте seed при итерациях: зафиксируйте seed, меняйте за раз одну фразу запроса и наблюдайте, что именно делает эта фраза.

Нужен контроль первого кадра? Используйте вариант «изображение в видео»

Если ваш рабочий процесс начинается с подготовленного ключевого кадра — изображения продукта, первого кадра в фирменном стиле — преобразование текста в видео не принимает изображения на вход. Парная модель wan2.7-video/image-to-video@pro может: она принимает массив media из объектов {"url": "...", "type": "image"} вместе с теми же полями prompt / resolution / duration и анимирует предоставленный вами кадр, а не создаёт его с нуля. Тот же процесс на основе задач, та же оплата по секундам. Практичный конвейер: сгенерируйте стоп-кадр моделью изображений, проверьте его, затем анимируйте утверждённые кадры — так вы платите за генерацию видео только за уже одобренные кадры.

Частые ошибки и их реальное значение

• invalid input: prompt: missing required field "prompt" — prompt — единственное обязательное поле.
• invalid input: ratio: value must be one of '16:9', '9:16', '1:1', '4:3', '3:4' — вы передали неподдерживаемое соотношение сторон (или ошиблись в написании).
• invalid input: <root>: additional properties '...' not allowed — неизвестное поле; схема строгая, проверьте таблицу выше.
• status: "fail" с TASK_FAILED — задача завершилась ошибкой после создания; создайте новую задачу (повторно используя ваш seed для воспроизводимости).
• Скачанный файл маленький или не воспроизводится — скорее всего, вы захватили истёкший URL вывода. Перепроверьте expireAt и скачивайте сразу после success.

Итог

Один POST, один цикл опроса, одно скачивание — вот и всё расстояние от текстового запроса до готового к публикации вертикального MP4 со звуком. Если вы строите конвейер коротких видео, получите API-ключ в консоли, начните с приведённой выше функции Python и просмотрите остальную часть каталога моделей — тот же шаблон /v1/tasks (как показано в нашем руководстве по seedance-2.0-fast) применим ко всем видеомоделям платформы, так что позже смена модели потребует лишь одной строки.