API vidu-q3-ad reference-to-video: curl, Python и один рабочий запрос

Что вы создадите

Отправьте один вызов reference-to-video в асинхронный API /v1/tasks от hiapi, чтобы превратить 1–7 статичных изображений продукта в короткий видеоролик-рекламу с нативным аудио. vidu-q3-ad/reference-to-video — это рекламный тариф Vidu Q3: вы загружаете референсные изображения продукта, пишете описание кадра, и модель возвращает MP4 длительностью 3–15 секунд с умным монтажом, движением камеры и сгенерированным звуковым оформлением — отдельную звуковую дорожку предоставлять не нужно.

Вы просто отправляете один POST, затем опрашиваете (или принимаете callback) до завершения задачи и скачиваете MP4. Сначала получите ключ в консоли hiapi; каждый запрос ниже использует Authorization: Bearer sk-....

Три вещи, которые нужно скопировать дословно:

• Эндпоинт отправки: POST https://api.hiapi.ai/v1/tasks
• Эндпоинт опроса: GET https://api.hiapi.ai/v1/tasks/{taskId}
• ID модели: vidu-q3-ad/reference-to-video — слэш и суффикс -ad опускать нельзя; vidu-q3-mix и vidu-q4-preview — это другие эндпоинты.

Схема входа (получена живым зондированием)

Поле	Обязательно	Тип	Описание
prompt	Да	string	Описание кадра; ссылайтесь на продукты по порядковому номеру, например «часы с референсного изображения 1»
reference_image_urls	Да	array, 1–7	Публичные URL статичных изображений продукта (загружаются сервером)
duration	Да	integer, 3–15	Количество секунд; должно быть целым числом (4.5 будет отклонено)
size	Нет	enum (10 значений)	Одновременно определяет соотношение сторон и уровень 720/1080; по умолчанию 1280*720

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

• aspect_ratio и resolution оба отклоняются. Почти все другие видеомодели hiapi используют эти поля; q3-ad — нет. Размер задаётся только через size.
• reference_audio_urls также отклоняется. В отличие от тарифа reference-to-video Vidu Q4 (который принимает голосовые фрагменты), у q3-ad нет аудиовхода — его звуковое оформление генерируется нативно. (Как я это подтвердил, см. раздел проверки ниже.)

Как выбрать size

size — это строка width*height из фиксированного набора. Её можно представить как сетку из пяти соотношений сторон × двух уровней качества:

Соотношение сторон	Уровень 720	Уровень 1080
16:9 горизонтальное	1280*720	1920*1080
9:16 вертикальное	720*1280	1080*1920
1:1 квадратное	1280*1280	1808*1808
4:3	1280*960	1920*1440
3:4	960*1280	1440*1920

Выбирайте строку по площадке размещения (для Reels и TikTok — вертикальные 720*1280 / 1080*1920, для рекламных вставок YouTube — горизонтальную строку), а столбец — по компромиссу между качеством и бюджетом. Оплата рассчитывается по выходным секундам, а уровень определяет цену за секунду — подробнее в разделе цен; минимальная оплачиваемая длина — 3-секундный фрагмент.

Минимальный запрос (curl)

Два шага: отправка, затем опрос.

# 1) отправка — возвращает taskId
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vidu-q3-ad/reference-to-video",
    "input": {
      "prompt": "Рекламный ролик титановых умных часов с референсного изображения 1: они медленно вращаются на тёмном отражающем пьедестале, пока жёсткая полоса света проходит слева направо по шлифованному корпусу, экран остаётся тёмным, камера держит низкий героический ракурс. Коммерческое освещение, высокий контраст, макродетали.",
      "reference_image_urls": [
        "https://your-cdn.com/watch-front.png",
        "https://your-cdn.com/watch-side.png"
      ],
      "duration": 5,
      "size": "1280*720"
    }
  }'
# -> {"data":{"taskId":"..."}}

# 2) опрос до тех пор, пока data.status не станет "success" или "fail"
curl -s https://api.hiapi.ai/v1/tasks/THE_TASK_ID \
  -H "Authorization: Bearer sk-your-key"
# успех -> data.status == "success", а data.output[0].url — это MP4

URL референсных изображений должны быть общедоступными — задачи загружают их на сервере, поэтому localhost или подписанные URL, которые истекают через несколько секунд, не подойдут.

Python: отправка, опрос, скачивание

import time
import requests  # или используйте urllib/subprocess, чтобы сохранить нулевую зависимость

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

def submit():
    payload = {
        "model": "vidu-q3-ad/reference-to-video",
        "input": {
            "prompt": "Рекламный кадр кроссовка с референсного изображения 1, вращающегося на освещённом поворотном столе, "
                      "медленный наезд камеры, мягкий контурный свет, композиция с продуктом-героем.",
            "reference_image_urls": ["https://your-cdn.com/sneaker.png"],
            "duration": 5,
            "size": "1080*1920",   # вертикальное 1080p для Reels / TikTok
        },
    }
    body = requests.post(API, headers=HEADERS, json=payload, timeout=60).json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"submit rejected: {body}")   # сюда попадает 400
    return task_id

def wait(task_id, timeout_s=600, interval=5):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json().get("data") or {}
        status = data.get("status")
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(interval)
    raise TimeoutError(task_id)

url = wait(submit())
mp4 = requests.get(url, timeout=120).content   # скачивайте сразу — выходной URL истекает
open("ad.mp4", "wb").write(mp4)

Рендеринг Q3-ad обычно завершается за одну-две минуты; интервала опроса в 5 секунд вполне достаточно. Выходной URL временный (содержит expireAt), поэтому после успеха задачи сразу скачивайте байты, а не вставляйте его как горячую ссылку на странице.

Паттерн для продакшена

Используйте callback вместо опроса. В серверном сценарии добавьте поле верхнего уровня callback, чтобы не держать цикл опроса:

{
  "model": "vidu-q3-ad/reference-to-video",
  "input": { "prompt": "...", "reference_image_urls": ["..."], "duration": 5 },
  "callback": { "url": "https://your-app.com/hooks/hiapi", "when": "final" }
}

when поддерживает только "final" — хук срабатывает один раз, когда задача переходит в конечное состояние, и его тело запроса совпадает с полезной нагрузкой, которую возвращает GET /v1/tasks/{taskId}. Хуки могут повторяться, поэтому дедуплицируйте по taskId и оставляйте медленный опрос как запасной вариант на случай, если какая-то доставка потеряется.

Ветвитесь по телу ответа, а не по HTTP-коду. Ошибка рендеринга всё равно возвращает HTTP 200; информация об ошибке находится в data.status == "fail", подробности — в data.error. Только отказы уровня запроса (неверные поля, отсутствующий ключ, неаутентифицированный доступ) используют 4xx и возвращают {"code":400,"error_code":"INVALID_REQUEST","message":"...","data":null}.

Идемпотентность. Каждая отправка создаёт новую оплачиваемую задачу, поэтому сохраняйте taskId в момент его получения и при повторах опрашивайте именно этот ID. Никогда не отправляйте задачу повторно только из-за тайм-аута одного запроса опроса.

Что я проверил

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

• Почти пустое тело запроса → reference_image_urls: missing required field ...; duration: missing required field .... Следовательно, prompt, reference_image_urls и duration обязательны.
• duration: 99999 → maximum: got 99,999, want 15; duration: 1 → minimum: got 1, want 3; duration: 4.5 → got number, want integer. Duration — целое число от 3 до 15.
• reference_image_urls с 8 элементами → maxItems: got 8, want 7. Верхний предел — 7.
• size: "9000p" → value must be one of '1280*720', '1280*960', '1280*1280', '960*1280', '720*1280', '1920*1080', '1920*1440', '1808*1808', '1440*1920', '1080*1920'.
• aspect_ratio и resolution → оба возвращают additional properties ... not allowed. Это не поля q3-ad; используйте size.
• reference_audio_urls с корректным по форме массивом → additional properties 'reference_audio_urls' not allowed. (Если передать не массив, сначала срабатывает отдельная проверка медиа — «must be an array» — что вводит в заблуждение: поля действительно нет в схеме.) У этого тарифа нет голосового референсного входа; аудио генерируется нативно.

Это интеграционная справка, поэтому она не содержит заявлений о качестве — я не запускал платный рендеринг для этой статьи. О том, как выглядит успешный output[0].url, см. страницу модели ниже, где размещён собственный пример этого эндпоинта: реальный MP4 со звуковой дорожкой.

Связанные руководства

• Страница модели Vidu Q3 Ad reference-to-video — спецификации, примеры рекламных промптов и форма для онлайн-пробы.
• Руководство по API Vidu Q4 reference-to-video — более высокий тариф: до 4K, 1–15 референсных изображений и голосовое поле reference_audio_urls, которого нет у q3-ad.
• Руководство по API Seedance 2.5 reference-to-video — ещё один эндпоинт reference-to-video, удобный для сравнения моделей.
• Промпты для кинематографичных движений камеры в AI-видео — подходящий язык кадра для поля prompt.
• Быстрый старт hiapi и цены.

Частые вопросы

Как сделать фрагмент вертикальным или горизонтальным? Через size, а не aspect_ratio. Для вертикального используйте 720*1280 или 1080*1920, для горизонтального — 1280*720 или 1920*1080.

Можно ли предоставить озвучку или звуковой референс? В этом тарифе нет — reference_audio_urls будет отклонён. Q3-ad генерирует нативное аудио самостоятельно. Если вам нужно управлять аудио с помощью референсного фрагмента, используйте тариф reference-to-video Vidu Q4.

Сколько изображений продукта можно отправить? От одного до семи, в reference_image_urls, и ссылайтесь на них в промпте по порядковому номеру («флакон с референсного изображения 2»).

Задача вернула 200, но видео нет — почему? Смотрите data.status. "fail" возвращается с HTTP 200, причина в data.error; только некорректно сформированные запросы получают 4xx.

Сколько это стоит? Оплата по выходным секундам, уровень size (класс 720 или класс 1080) определяет цену за секунду. Минимум — 3-секундный фрагмент. Актуальные тарифы см. в разделе цен.