Как использовать veo-3.1-lite/image-to-video через API hiapi

Veo 3.1 Lite превращает одно опорное изображение и текстовый промпт в короткое видео, а на hiapi он доступен через тот же асинхронный API задач, который используется всеми моделями платформы. В этом руководстве описан реальный рабочий процесс: получение ключа, вызов POST /v1/tasks, получение результата, а также детали, которые важны при переходе от одноразового скрипта к продакшену (колбэки, идемпотентность, обработка ошибок).

Что вы создаёте и что подготовить заранее

Вы отправляете URL изображения и промпт модели veo-3.1-lite/image-to-video и получаете URL .mp4-файла, размещённого на стороне сервиса. Всё работает через единый эндпоинт задач hiapi, поэтому одинаковая структура запроса подходит для любой видео- и имидж-модели платформы — меняются только model id и поля input.

Перед началом:

1. Создайте аккаунт hiapi и получите API-ключ в консоли. Ключ выглядит как sk-....
2. Подготовьте публично доступный URL изображения — API загружает его на серверной стороне, поэтому пути localhost или приватные бакеты не подойдут.
3. Перед выполнением реальных (не тестовых) запросов проверьте текущую цену veo-3.1-lite/image-to-video на странице тарифов, поскольку стоимость зависит от длительности и разрешения.

Бесплатного уровня или режима без ключа нет — каждый вызов требует Authorization: Bearer sk-<your-key>.

Минимальный рабочий пример

API задач hiapi — это два вызова: создать задачу, а затем либо опрашивать её, либо позволить колбэку сообщить о завершении. Ниже приведён Python-код версии с опросом, использующий только requests и time:

import time
import requests

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

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
        "duration": 6,
        "aspect_ratio": "16:9",
    },
}

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until it's done
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        video_url = task["output"][0]["url"]
        print("done:", video_url)
        break
    if status == "fail":
        raise RuntimeError(task.get("error"))
    time.sleep(5)

Если вы просто хотите увидеть формат передачи по сети, вот та же операция в виде сырого curl:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/image-to-video",
    "input": {
      "prompt": "the camera slowly pushes in as steam rises from the cup",
      "image_url": "https://example.com/your-reference-image.jpg",
      "duration": 6,
      "aspect_ratio": "16:9"
    }
  }'

# then poll:
curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-your-key-here"

В схеме input есть несколько моментов, которые стоит знать особо, поскольку она строже, чем у универсальных эндпоинтов в духе «передавай что угодно» — лишние поля отклоняются напрямую, а не игнорируются молча:

• prompt и image_url — единственные два обязательных поля. image_url в единственном числе — эта модель принимает ровно одно опорное изображение, а не массив.
• duration принимает только 4, 6 или 8 (секунд) — никаких других целых чисел.
• aspect_ratio принимает auto, 16:9 или 9:16.
• resolution принимает 720p или 1080p.
• Необязательные дополнения: seed (целое число для воспроизводимости), generate_audio (булево значение), negative_prompt (строка).

Обратите внимание, что id модели — это голый id, то есть veo-3.1-lite/image-to-video — не добавляйте к нему префиксы или пространства имён.

Как только status становится "success", выходное видео находится в data.output[0].url. Этот URL временный (содержит expireAt), поэтому скачайте или переразместите файл сразу, а не сохраняйте горячую ссылку.

Особенности продакшена: колбэки, идемпотентность и ошибки

Опрос каждые 5 секунд подходит для скрипта, но расточителен на сервере, обрабатывающем много задач одновременно. Для продакшен-трафика предпочтительнее колбэки: передайте объект callback в том же запросе создания задачи, и hiapi отправит финальный результат POST-запросом на ваш эндпоинт вместо того, чтобы вы его опрашивали.

payload = {
    "model": "veo-3.1-lite/image-to-video",
    "input": {
        "prompt": "the camera slowly pushes in as steam rises from the cup",
        "image_url": "https://example.com/your-reference-image.jpg",
    },
    "callback": {
        "url": "https://yourapp.example.com/hooks/hiapi",
        "when": "final",
    },
}

Ключевая настройка здесь — when: "final": это означает, что уведомление придёт один раз, когда задача достигнет терминального состояния (success или fail), а не при каждом промежуточном изменении состояния. Ваш обработчик webhook должен проверить id задачи и затем найти локальную запись задачи, созданную при исходном вызове POST /v1/tasks.

Идемпотентность. Если ваш сервис может повторять вызов создания задачи (таймауты, доставка хотя бы один раз и т. п.), добавьте заголовок Idempotency-Key длиной до 255 байт:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Idempotency-Key: order-42-veo-submit" \
  -H "Content-Type: application/json" \
  -d '{...}'

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

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

Обработка ошибок. Неверный или отозванный ключ возвращает HTTP 401 и error.code: "permission_denied" — проверяйте это отдельно, а не предполагайте, что любой не-2xx ответ означает сбой самой генерации видео. Некорректный input (отсутствует prompt, duration вне перечисления, нераспознанные поля) возвращает HTTP 400 и error_code: "INVALID_REQUEST" с сообщением, указывающим конкретное проблемное поле — его стоит выводить прямо в своих логах, а не проглатывать, потому что сообщение подскажет, что именно исправить. После принятия задачи сбой на стороне генерации выражается в виде status: "fail" и объекта error в ответе опроса/колбэка — считайте это повторяемым, только если сообщение указывает на временную проблему вышестоящего сервиса, а не на проблему схемы.

Связанные ресурсы

• Документация модели veo-3.1-lite/image-to-video — полный справочник параметров этой конкретной модели
• Создание задачи и Получение деталей задачи — два эндпоинта, на которых построено это руководство
• Документация по аутентификации — формат ключа и требования к заголовкам
• Veo 3.1 Image-to-Video: руководство по коротким видео — разбор сценариев использования, если вам нужен более высокоточный вывод не-lite модели
• Тарифы — текущие ставки за секунду с разбивкой по длительности и разрешению

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

Нужно ли передавать image_url как data URI или base64? Нет — image_url должен быть публичным HTTP(S) URL, который может загрузить сервер hiapi. Эта модель не принимает изображения в кодировке base64.

Можно ли сгенерировать видео без опорного изображения? С veo-3.1-lite/image-to-video — нет: это модель «изображение в видео», и image_url обязателен. Если вам нужна генерация только из текста, используйте модель «текст в видео»; страница не-lite модели Veo 3.1 перечисляет доступные для неё режимы.

Почему запрос всё равно возвращает 400, хотя я передал все обязательные поля? Проверьте лишние поля — схема входа этой модели отклоняет всё, чего нет в списке разрешённых (prompt, image_url, duration, aspect_ratio, resolution, seed, generate_audio, negative_prompt). Сообщение об ошибке укажет точное поле, которое оно не распознало.

Сколько на самом деле занимает генерация? Это зависит от длительности и текущей глубины очереди — именно поэтому правильный подход — опрос с коротким интервалом или колбэк, а не предположение о фиксированном времени ожидания.

Может ли в выходном файле быть аудио? Да, через булево значение generate_audio — смотрите документацию модели, чтобы узнать текущие значения по умолчанию и их влияние на стоимость.

Что будет, если мой эндпоинт колбэка недоступен, когда задача завершится? Не полагайтесь только на приход колбэка — сохраняйте taskId, возвращённый вызовом создания, и если колбэк не пришёл в разумное время, переключитесь на опрос GET /v1/tasks/<id>.