HiAPI
Блог

Руководство

Вызов veo-3.1/image-to-video через HiAPI API: руководство по curl и Python

Nov 12, 2026
Обложка: слои бумаги цвета слоновой кости, смещённые друг относительно друга, между ними прослойка ржаво-красного цвета, тени прямые.
На этой странице

Что ожидает эндпоинт veo-3.1 для преобразования изображения в видео

Прежде чем писать первую строку кода, полезно разобраться, что это за вызов. veo-3.1/image-to-video не возвращает видео непосредственно в том HTTP-ответе, в котором вы отправляете подсказку. Это эндпоинт асинхронной задачи: вы описываете желаемое видео, платформа принимает задачу, а затем вы возвращаетесь за результатом.

Концептуально запрос состоит из двух совершенно разных частей:

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

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

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

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

Ментальная модель из двух частей

Держите эту схему в голове при чтении следующих разделов:

  1. Вход → подготовленный и проверенный первый кадр.
  2. Параметры → аудио, разрешение, длительность.
  3. Задача → отправка, получение идентификатора, опрос, получение результата.

Каждый раздел ниже соответствует одному из этих блоков.

Подготовка первого кадра

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

Что проверить перед отправкой

  • Изображение действительно открывается. Обрезанная загрузка или повреждённый файл — самая частая причина непонятных сбоев на последующих этапах. Перед отправкой чего-либо убедитесь, что оно корректно декодируется.
  • Формат принимается платформой. Если ваш источник — скриншот, фото с телефона или экспорт из дизайн-инструмента, приведите его к широко поддерживаемому формату перед загрузкой. Один раз преобразовать заранее проще, чем потом отлаживать.
  • Размер разумный. Слишком маленькие или сильно растянутые изображения дают модели мало материала. Если источник слишком мал, рассмотрите увеличение или выбор лучшего кадра.
  • Композиция — хорошая отправная точка. Поскольку это первый кадр, генерируемое движение будет продолжаться от него. Выбирайте кадр, на котором субъект хорошо виден и композицию которого вы рады видеть в начале фрагмента.

Держите отдельно от параметров

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

# Структура псевдокода, а не полный клиент
def prepare_first_frame(path):
    image = load_and_validate(path)   # декодировать, проверить формат, проверить размер
    ref = upload_or_encode(image)     # создать то, на что может сослаться API-вызов
    return ref

def build_request(first_frame_ref, options):
    return {
        "first_frame": first_frame_ref,
        # аудио / разрешение / длительность здесь
    }

Такое разделение окупается при отладке. Если задача завершилась неудачей, вы можете отдельно перезапустить prepare_first_frame и убедиться, что сторона изображения в порядке, прежде чем трогать какие-либо параметры генерации.

Проверяйте рано, падайте громко

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

Настройка параметров генерации: аудио, разрешение и длительность

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

Аудио

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

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

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

Разрешение

Разрешение определяет пиксельные размеры итогового видео. Выбирайте его исходя из того, где видео будет показано и сколько деталей требуется контенту, а не просто «максимально доступное значение». Фрагменту, который будет отображаться в маленьком встроенном плеере, нет пользы генерироваться в размере, многократно превышающем возможности панели отображения. Если платформа публикует набор поддерживаемых значений, выбирайте из него явно и проверяйте на клиенте, чтобы неподдерживаемые значения быстро завершались ошибкой.

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

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

Соберите параметры в объект

Поместите все три в одну структуру параметров, чтобы было одно место для просмотра и одно место для изменения:

options = {
    "audio": True,          # генерировать звуковую дорожку
    "resolution": "...",    # одно из поддерживаемых значений
    "duration": 8,          # количество секунд генерируемого видео
}

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

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

Теперь соедините обе части и отправьте. Начните с командной строки, потому что curl делает форму запроса видимой и даёт способ быстро протестировать изменения перед написанием кода.

Запрос

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

curl -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_frame": "<ссылка на изображение из шага загрузки>",
    "audio": true,
    "resolution": "<поддерживаемое значение>",
    "duration": 8
  }'

Несколько соглашений, которые стоит взять в привычку:

  • Храните ключ в переменной окружения ($HIAPI_API_KEY), а не вставляйте его в команду. Эта привычка напрямую перенесётся в ваш код на Python и не даст ключу попасть в историю оболочки.
  • Отправляйте JSON с явным заголовком Content-Type.
  • В теле запроса отделяйте ссылку на изображение от числовых и булевых параметров, повторяя модель из двух частей из первого раздела.

Чтение ответа

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

Читайте в два шага. Сначала убедитесь, что HTTP-статус означает принятие, а не ошибку клиента. Затем разберите тело ответа и извлеките идентификатор задачи:

curl -s -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | tee submit.json

Записав ответ в submit.json, вы получаете что-то для проверки и для передачи на шаг опроса. Если отправка не удалась, тело ответа с ошибкой — ваша первая и лучшая подсказка: проверьте, указывает ли оно на ссылку на изображение или на какой-то параметр, затем исправьте именно эту половину и отправьте снова.

Опрос асинхронной задачи до готовности видео

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

Жизненный цикл

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

  • Всё ещё обрабатывается — продолжайте ждать.
  • Успех — прочитайте местоположение вывода и скачайте или сохраните видео.
  • Сбой — остановитесь и выбросьте ошибку.

Опрашивайте ответственно

Две привычки делают опрос надёжнее:

  1. Ждите между проверками. Плотный цикл, долбящий эндпоинт статуса, тратит запросы без всякой пользы; генерация требует реального времени. Используйте фиксированный интервал или мягкую задержку с нарастанием.
  2. Установите крайний срок. Никогда не опрашивайте бесконечно. Выберите максимальное число попыток или максимальное затраченное время и считайте превышение этого предела сбоем, о котором можно ясно сообщить.
# Набросок цикла опроса
for i in $(seq 1 60); do
  status=$(curl -s "https://api.hiapi.ai/v1/jobs/<job_id>" \
    -H "Authorization: Bearer $HIAPI_API_KEY")
  echo "$status"
  # выйти, когда поле статуса сообщает об успехе или сбое
  sleep 5
done

Точные строки статусов и пути эндпоинтов считайте тем, что нужно сверять с текущей документацией API, а не допущениями, зашитыми в скрипт.

При успехе

Когда задача сообщает об успехе, ответ содержит местоположение итогового видео. Скачайте его вовремя и сохраните в постоянное место — к результатам задач на любой асинхронной платформе следует относиться как к тому, что нужно забрать сейчас, а не лениво подгружать спустя долгое время. Записывайте идентификатор задачи вместе с сохранённым файлом, чтобы любой вывод можно было проследить до породившего его запроса.

Тот же запрос на Python

Версия на Python не должна быть второй реализацией — это должен быть тот же запрос, выраженный один раз и переиспользуемый. Цель — одна функция отправки и опроса, построенная на той же ссылке на изображение и том же объекте параметров, которые вы проверили ранее.

Одно тело запроса, один клиент

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
})

def build_body(first_frame_ref, options):
    return {"first_frame": first_frame_ref, **options}

def submit(body):
    r = session.post(f"{BASE}/veo-3.1/image-to-video", json=body, timeout=60)
    r.raise_for_status()
    data = r.json()
    return data["job_id"]

def poll(job_id, interval=5, max_attempts=60):
    for _ in range(max_attempts):
        r = session.get(f"{BASE}/jobs/{job_id}", timeout=30)
        r.raise_for_status()
        data = r.json()
        state = data.get("status")
        if state in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"Задача {job_id} не завершилась вовремя")

def image_to_video(first_frame_ref, options):
    job_id = submit(build_body(first_frame_ref, options))
    result = poll(job_id)
    if result["status"] == "failed":
        raise RuntimeError(result.get("error", "Задача завершилась сбоем"))
    return result  # содержит местоположение итогового видео

Почему именно такая форма

  • Один Session. Переиспользование сессии концентрирует заголовки аутентификации в одном месте и переиспользует соединения между отправкой и каждым опросом.
  • Один build_body. Запрос curl и запрос Python — это одно и то же тело: те же ключи, те же значения. Когда вы меняете какой-то параметр, вы меняете его в одном месте.
  • Явные таймауты и крайние сроки. Оба вызова задают таймауты, а poll ограничен числом попыток, поэтому зависшая задача никогда не подвесит ваш процесс.
  • Сбои видны сразу. raise_for_status при отправке немедленно ловит ошибки уровня запроса; явная ветка сбоя в image_to_video ловит сбои уровня задачи.

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

Диагностика неудачных вызовов преобразования изображения в видео

Когда вызов не выдаёт видео, сузьте круг, спросив, какой этап дал сбой. Модель запроса из двух частей даёт вам чёткий контрольный список.

Этап 1: отправка отклонена

Если сам вызов отправки возвращает ошибку, значит, ничего не сгенерировано — это хорошая новость, потому что проблема в запросе.

  • Проблема со ссылкой на изображение. Самая частая единственная причина. Отдельно перезапустите шаг подготовки изображения и убедитесь, что он выдаёт корректное, читаемое изображение правильного формата и ссылку, принимаемую API. В первую очередь проверяйте обрезанные загрузки и неподдерживаемые форматы.
  • Недопустимые значения параметров. Неподдерживаемое разрешение или длительность вне диапазона будут отклонены при отправке. Проверяйте параметры по поддерживаемым значениям из документации перед отправкой.
  • Аутентификация и заголовки. Убедитесь, что ключ действительно отправляется (Authorization: Bearer ...), а тело отправляется как JSON. При ручном построении запроса в curl пустое или искажённое тело легко упустить.

Этап 2: задача отправлена, но завершилась сбоем

Если отправка принята, но опрос закончился сбоем, значит, запрос оформлен правильно, а проблема в содержимом или в самой задаче.

  • Прочитайте ошибку задачи. Ответ со сбоем объяснит, что пошло не так, лучше любых догадок. Записывайте его как есть.
  • Посмотрите на первый кадр. Исходное изображение без чёткого субъекта, с экстремальной обрезкой или сильными искажениями даёт модели мало материала. Подставьте более чистый кадр и повторите.
  • Пересмотрите параметры. Большую длительность или необычную комбинацию настроек стоит перепроверить с более простой конфигурацией, чтобы изолировать проблемный параметр.

Этап 3: опрос никогда не заканчивается

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

Эффективный процесс отладки

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

Теперь у вас есть полный цикл: подготовить первый кадр, задать аудио, разрешение и длительность, отправить асинхронно и опрашивать до завершения — один и тот же запрос независимо от того, запускаете ли вы его через curl или Python.

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

Все статьи →

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

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

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