Как использовать API видеогенерации по референсу vidu-q4-preview (curl + Python)

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

Выполните вызов видеогенерации по референсу в асинхронном API /v1/tasks от hiapi, объединяя несколько референсных стоп-кадров — и, при желании, аудиофрагменты — в ролик длительностью 3–16 секунд с разрешением до 4K. Достаточно отправить один POST, затем опрашивать (или получать callback) до завершения задачи и скачать MP4.

Сначала получите ключ в консоли hiapi; каждый запрос ниже использует Authorization: Bearer sk-<your-key>.

Видеогенерация по референсу vs видеогенерация из изображения. Этот эндпоинт объединяет 1–15 стоп-кадров — передайте стоп-кадр персонажа, стоп-кадр сцены и стоп-кадр реквизита, и он скомпонует их в один кадр. Если у вас есть только один первый кадр, который нужно оживить, используйте вместо этого vidu-q4-preview/image-to-video; он принимает единственный image_url и отклоняет reference_image_urls.

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

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vidu-q4-preview/reference-to-video",
    "input": {
      "prompt": "персонаж с референсного изображения 1 идёт мимо кафе с референсного изображения 2, тёплый утренний свет, медленный наезд камеры",
      "reference_image_urls": [
        "https://your-cdn.com/person.jpg",
        "https://your-cdn.com/cafe.jpg"
      ],
      "resolution": "1080p",
      "duration": 5,
      "aspect_ratio": "16:9"
    }
  }'

Этот POST возвращает идентификатор задачи, а не видео:

{ "code": 200, "data": { "taskId": "task_abc123" } }

Опрашивайте GET /v1/tasks/<taskId>, пока data.status не станет success, затем читайте MP4 из data.output[0].url:

curl https://api.hiapi.ai/v1/tasks/task_abc123 \
  -H "Authorization: Bearer sk-<your-key>"

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [
      { "url": "https://temp.hiapi.ai/....mp4", "expireAt": 1760000000 }
    ]
  }
}

URL вывода временный — он содержит expireAt (истекает через несколько дней) — поэтому сразу скачайте его содержимое, не используйте горячие ссылки.

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

import time
import requests

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

def submit() -> str:
    payload = {
        "model": "vidu-q4-preview/reference-to-video",
        "input": {
            "prompt": (
                "персонаж с референсного изображения 1 идёт мимо кафе "
                "с референсного изображения 2, тёплый утренний свет, "
                "медленный наезд камеры"
            ),
            "reference_image_urls": [
                "https://your-cdn.com/person.jpg",
                "https://your-cdn.com/cafe.jpg",
            ],
            "resolution": "1080p",
            "duration": 5,
            "aspect_ratio": "16:9",
        },
    }
    r = requests.post(BASE, json=payload, headers=HEADERS, timeout=60)
    r.raise_for_status()
    body = r.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: str, timeout_s: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=40)
        task = r.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(interval)
    raise TimeoutError(task_id)

def download(url: str, path: str) -> None:
    with requests.get(url, stream=True, timeout=120) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(1 << 16):
                f.write(chunk)

task_id = submit()
url = wait(task_id)
download(url, "out.mp4")

Один момент нужно усвоить: неудачный рендеринг всё равно возвращается с HTTP 200, причина в data.status: "fail" и data.error.code / data.error.message. Ошибка генерации — это не HTTP-ошибка, поэтому ветвитесь по телу ответа, а не по коду состояния.

Добавление голосового референса

Поле для голоса — reference_audio_urls — массив до 3 аудиофрагментов. Аудио задаёт тембр; ваш prompt по-прежнему несёт текст и управляет синхронизацией губ.

{
  "model": "vidu-q4-preview/reference-to-video",
  "input": {
    "prompt": "ведущий с референсного изображения 1 говорит голосом из референсного аудио 1: 'С возвращением на канал.'",
    "reference_image_urls": ["https://your-cdn.com/presenter.jpg"],
    "reference_audio_urls": ["https://your-cdn.com/voice.mp3"],
    "resolution": "1080p",
    "duration": 8
  }
}

Ловушка с именем поля: интуитивное voice_reference_urls будет отклонено (валидатор допускает только reference_audio_urls). См. таблицу проверок ниже.

Продакшен: callback и идемпотентность

Для серверных рабочих процессов вы обычно не хотите держать цикл опроса постоянно. Добавьте верхнеуровневый callback (на одном уровне с input, а не внутри него), и hiapi отправит POST о завершённой задаче на ваш URL:

{
  "model": "vidu-q4-preview/reference-to-video",
  "input": { "prompt": "...", "reference_image_urls": ["..."] },
  "callback": { "url": "https://your-app.com/hooks/vidu", "when": "final" }
}

• when поддерживает только "final" — вы получите одно уведомление в терминальном состоянии (успех или ошибка), и никогда не получите промежуточных уведомлений о прогрессе.
• Тело callback такое же, как полезная нагрузка, возвращаемая GET /v1/tasks/<id>.
• Доставка повторяется несколько раз и может дублироваться, поэтому дедуплицируйте по taskId и делайте обработчик идемпотентным.
• Оставьте опрос как запасной вариант на случай, если ваш эндпоинт временно недоступен.

Сохраните taskId в момент его получения. Если ваш опросчик столкнётся с временной сетевой ошибкой, повторно опрашивайте сохранённый id — никогда не отправляйте задачу заново, иначе вы заплатите за второй рендер.

Что я проверил (контракт схемы)

Я проверял живой эндпоинт намеренно недопустимыми значениями (бесплатно — за отклонённые запросы не взимается плата, и недопустимые значения никогда не создают задачу). Валидатор строг и возвращает плоский ответ { "code": 400, "error_code": "INVALID_REQUEST", "message": ... }:

Что вы отправляете	Что возвращается
resolution: "9999p"	resolution: value must be one of '540p', '720p', '1080p', '2k', '4k'
duration: 999	duration: maximum: got 999, want 16
aspect_ratio: "banana"	aspect_ratio: value must be one of '16:9', '9:16', '1:1', '4:3', '3:4'
voice_reference_urls: [...]	additional properties 'voice_reference_urls' not allowed
четыре reference_audio_urls	reference_audio_urls: maxItems: got 4, want 3
пропущен reference_image_urls	missing required field "reference_image_urls"

Таким образом, подтверждённая структура входных данных:

Поле	Обязательно	Значения
prompt	Да	Текст
reference_image_urls	Да	1–15 URL изображений
reference_audio_urls	Нет	до 3 URL аудио (поле для голоса)
resolution	Нет	540p / 720p / 1080p / 2k / 4k
duration	Нет	целое число 3–16 (секунды)
aspect_ratio	Нет	16:9 / 9:16 / 1:1 / 4:3 / 3:4

duration — это целое число (5), а не строка — в отличие от некоторых других видеомоделей в hiapi, которые ожидают "6". Передача дополнительных ключей — грубая ошибка (additional properties ... not allowed), поэтому не копируйте поля из схемы видеогенерации из изображения.

Замечания по выходным данным перед скачиванием

• Даже если вы не отправляли reference_audio_urls, каждый фрагмент содержит дорожку AAC. Слова о звуке в prompt управляют фоновой дорожкой, поэтому не предполагайте, что «без голосового референса = беззвучный файл».
• Вывод 4K в Vidu Q4 Preview поставляется в HEVC/H.265. Он воспроизводится в большинстве нативных плееров, но многие браузеры не могут воспроизводить H.265 MP4 встроенно внутри тега <video> — если вам нужно встраивать в веб-страницу, перекодируйте в H.264. Более низкие уровни возвращают стандартный H.264.

Модель предварительного просмотра — считайте перечисления снимками

vidu-q4-preview/reference-to-video — это предварительная модель: сегодня она доступна для вызова, но не указана в /v1/models, и схема предварительного просмотра может измениться. Перед массовой обработкой повторно запустите проверку с недопустимыми значениями (как в таблице выше), чтобы убедиться, что перечисления всё ещё действительны. Авторитетная спецификация — это правила, которые фактически применяет валидатор, плюс страница модели.

Связанное

• Страница модели vidu-q4-preview/reference-to-video — актуальная спецификация и стоимость за запрос.
• Рецепты prompt для видеогенерации по референсу Vidu Q4 Preview — пять готовых к копированию prompt и сгенерированные ими реальные фрагменты, которые дадут вам идеи, что вставлять в prompt (это руководство охватывает вызов; та страница охватывает prompt).
• vidu-q4-preview/image-to-video — эндпоинт анимации одного кадра; используйте его, когда у вас есть только один стоп-кадр, а не набор изображений для объединения.
• Цены hiapi — видеогенерация по референсу оплачивается посекундно и дорожает с ростом разрешения.

Часто задаваемые вопросы

Видеогенерация по референсу — это то же самое, что видеогенерация из изображения? Нет. Видеогенерация по референсу объединяет 1–15 стоп-кадров (и, при желании, до 3 аудиофрагментов) в один составной кадр; видеогенерация из изображения оживляет единственный первый кадр. Это отдельные эндпоинты с разными входными данными — видеогенерация по референсу даже отклоняет поле image_url видеогенерации из изображения, и наоборот.

Как добавить голос? Прикрепите reference_audio_urls (до 3 фрагментов) и укажите это в prompt («...голосом из референсного аудио 1»). Имя поля должно быть точно reference_audio_urls; voice_reference_urls и другие имена будут отклонены.

Какая максимальная длительность фрагмента, который я могу запросить? 16 секунд. duration — целое число от 3 до 16.

Обязательно ли опрашивать? Нет — добавьте callback: { "url": ..., "when": "final" }, чтобы получить одно уведомление в терминальном состоянии. Дедуплицируйте по taskId и оставьте опрос как запасной вариант.

Сколько стоит 4K-фрагмент? Оплата посекундная, тариф растёт с разрешением, 4K — самый высокий уровень — см. Цены hiapi. Практичный рабочий процесс — сначала итерировать в 720p и перерендеривать в 4k только окончательные версии.