Руководство
Вызов veo-3.1/image-to-video через HiAPI API: руководство по curl и Python
На этой странице
Что ожидает эндпоинт veo-3.1 для преобразования изображения в видео
Прежде чем писать первую строку кода, полезно разобраться, что это за вызов. veo-3.1/image-to-video не возвращает видео непосредственно в том HTTP-ответе, в котором вы отправляете подсказку. Это эндпоинт асинхронной задачи: вы описываете желаемое видео, платформа принимает задачу, а затем вы возвращаетесь за результатом.
Концептуально запрос состоит из двух совершенно разных частей:
- Первый кадр. Это стартовый статичный кадр, с которого начинается генерация видео. Он задаёт композицию, субъект и восприятие начального момента. Всё последующее содержимое модель генерирует, отталкиваясь от этой отправной точки.
- Параметры генерации. Это параметры, управляющие тем, как создаётся видео — например, генерировать ли аудио, разрешение вывода и длительность фрагмента.
Такое разделение важно по двум причинам. Во-первых, оно упрощает диагностику сбоев: проблемы с изображением выглядят иначе, чем проблемы с параметрами, и вы хотите уметь их различать. Во-вторых, это означает, что ваш код следует организовать так же — одна часть логики отвечает за подготовку изображения, другая — за сборку набора параметров.
Вызывающая сторона должна как минимум предоставить: корректный первый кадр, а также решения по аудио, разрешению и длительности. Всё остальное — отправку задачи, отслеживание статуса, возврат итогового видео — берёт на себя жизненный цикл задачи платформы. Вашей интеграции нужно делать только три вещи: отправлять правильно оформленный запрос, запоминать возвращённый идентификатор задачи и опрашивать статус, пока задача не достигнет терминального состояния.
Один практический совет перед тем, как продолжить: поскольку вызов асинхронный, ваш код не должен предполагать, что видео доступно сразу после отправки. Спроектируйте процесс с учётом этого с самого начала — и дальнейшее руководство покажется естественным.
Ментальная модель из двух частей
Держите эту схему в голове при чтении следующих разделов:
- Вход → подготовленный и проверенный первый кадр.
- Параметры → аудио, разрешение, длительность.
- Задача → отправка, получение идентификатора, опрос, получение результата.
Каждый раздел ниже соответствует одному из этих блоков.
Подготовка первого кадра
Первый кадр — самый важный единственный вход в вызове преобразования изображения в видео, поэтому выделите для него отдельный шаг в конвейере, а не прячьте его внутри построителя запроса. 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, вы получаете что-то для проверки и для передачи на шаг опроса. Если отправка не удалась, тело ответа с ошибкой — ваша первая и лучшая подсказка: проверьте, указывает ли оно на ссылку на изображение или на какой-то параметр, затем исправьте именно эту половину и отправьте снова.
Опрос асинхронной задачи до готовности видео
Получив идентификатор задачи, рабочий процесс превращается в цикл: спрашивайте платформу о статусе задачи и останавливайтесь, когда задача достигнет терминального состояния.
Жизненный цикл
Задача преобразования изображения в видео проходит через небольшое число состояний. Она принимается и ставится в очередь, затем обрабатывается, и в итоге либо завершается успешно и выдаёт видео, либо завершается сбоем с ошибкой. Вашему коду опроса нужно различать только три вещи:
- Всё ещё обрабатывается — продолжайте ждать.
- Успех — прочитайте местоположение вывода и скачайте или сохраните видео.
- Сбой — остановитесь и выбросьте ошибку.
Опрашивайте ответственно
Две привычки делают опрос надёжнее:
- Ждите между проверками. Плотный цикл, долбящий эндпоинт статуса, тратит запросы без всякой пользы; генерация требует реального времени. Используйте фиксированный интервал или мягкую задержку с нарастанием.
- Установите крайний срок. Никогда не опрашивайте бесконечно. Выберите максимальное число попыток или максимальное затраченное время и считайте превышение этого предела сбоем, о котором можно ясно сообщить.
# Набросок цикла опроса
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.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий