Руководство
Как генерировать видео с помощью gemini-omni-flash через HiAPI API
Пути запросов для генерации видео из текста и из изображения, выбор модели и практический чек-лист интеграции
На этой странице
Почему у gemini-omni-flash две конечные точки для видео
Перед написанием первой строки кода самое важное решение: какая из двух конечных точек для видео вам действительно нужна. gemini-omni-flash доступен в HiAPI как две отдельные модели, а не как одна конечная точка с флагом режима:
gemini-omni-flash/text-to-video— генерирует видео только по текстовому промпту.gemini-omni-flash/image-to-video— использует переданное исходное изображение как визуальный якорь и генерирует видео под управлением текстового промпта.
Разделение существует потому, что у этих двух задач разные входные данные, разные правила валидации и разные режимы сбоя. Для генерации видео из текста нужно проверить только строку промпта. Для генерации из изображения также нужно получить и декодировать ваше исходное изображение, поэтому появляется целый класс ошибок, которого вообще нет на текстовом пути (URL недоступен, формат не поддерживается, ресурс слишком большой).
Практическое правило: если у вас уже есть статичное изображение — фото продукта, кадр раскадровки, фотография — используйте генерацию из изображения, потому что модель будет отталкиваться от вашего визуального контента, а не создавать его с нуля. Если у вас есть только идея и нет никаких референсных материалов, используйте генерацию из текста.
С самого первого дня различайте эти два ID моделей в кодовой базе. Отношение к ним как к единому понятию «видео» с последующим добавлением флага if has_image — именно то, из-за чего интеграция в итоге обрастает запутанными payload'ами и непонятными багами.
Что остаётся неизменным
Обе конечные точки используют одинаковую схему аутентификации, одинаковый базовый URL, одинаковые общие соглашения о запросах/ответах и одинаковую модель тарификации (видео оплачивается по сгенерированному результату, а не по количеству запросов). Именно эти общие части делают возможным единый построитель запросов — подробнее ниже.
Что различается
Различаются только структура payload и валидация входных данных. Различия достаточно малы, чтобы поддерживать обе конечные точки без дублирования всего кода интеграции.
Предварительные требования и настройка API
Перед первым вызовом вам понадобятся три вещи.
1. Ключ API
Создайте ключ в своей учётной записи HiAPI и сохраните его как переменную окружения, а не хардкодьте:
export HIAPI_API_KEY="your_key_here"
Каждый запрос аутентифицируется через bearer token в заголовке Authorization. Нет отдельного шага подписи и нет nonce для каждого запроса.
2. Базовый URL и соглашение об именовании моделей
Все вызовы отправляются на один базовый URL HiAPI, а модель выбирается полем model в теле запроса. ID моделей следуют шаблону family/variant, поэтому видеомодели записываются как gemini-omni-flash/text-to-video и gemini-omni-flash/image-to-video. Чтобы переключить конечную точку, вы меняете одну строку, а не хост.
3. Инструмент для отправки запросов
curl достаточно для проверки связности, Python (с requests) достаточно для построения реальной интеграции. Ни тот, ни другой не требует проприетарного SDK — этот API представляет собой обычный JSON поверх HTTPS.
Проверка связности
Прежде чем генерировать какое-либо видео, обратитесь к лёгкой конечной точке (например, к списку доступных моделей), чтобы убедиться, что ключ работает и сетевой путь в порядке. Если этот шаг не удаётся, вы отлаживаете учётные данные или связность, а не генерацию видео — понимание того, что именно, сэкономит массу времени.
Краткий чек-лист:
- Ключ экспортирован в оболочке, которая будет выполнять запрос.
- Базовый URL зафиксирован и везде используется одинаково (никаких расхождений с завершающим слэшем между скриптами).
- Для каждого POST установлен
Content-Type: application/json. - Есть способ просмотреть сырой JSON-ответ без усечения.
Отправка запроса на генерацию видео из текста
Начните с минимально возможного запроса, у которого есть шанс на успех. Не заполняйте сразу все необязательные параметры — если минимальный запрос не проходит, вы знаете, что проблема структурная; если проходит, то каждое последующее добавление параметра можно отнести к отдельному изменению.
Минимальная структура
Запрос на генерацию видео из текста отправляет ID модели и промпт:
{
"model": "gemini-omni-flash/text-to-video",
"prompt": "Медленный наезд камеры на мокрой от дождя неоновой улице ночью, отражения на влажном асфальте, кинематографично"
}
Это полный payload. Отправьте его, убедитесь, что получен успешный объект ответа, и только после этого обогащайте содержимое.
Постепенное развитие запроса
После успешного минимального вызова добавляйте по одному параметру за раз и заново проверяйте после каждого добавления. Типичные дополнения на текстовом пути:
- Детализация промпта — субъект, движение, поведение камеры, освещение и атмосфера. Расплывчатый промпт даёт расплывчатое движение; описывайте, что движется и как движется камера.
- Длительность / длина вывода — видео оплачивается по сгенерированному результату, поэтому длина напрямую влияет на стоимость. Фиксируйте её явно, а не полагайтесь на значения по умолчанию, которые вы ещё не проверили.
- Соотношение сторон или разрешение (если модель поддерживает), чтобы соответствовать нижестоящему плееру или формату социальных сетей.
Как писать промпты, которые действительно важны
Качество генерации видео из текста в основном определяется конкретностью промпта. Три хорошие привычки:
- Описывайте движение, а не только содержимое. «Бумажный кораблик плывёт по водосточной канаве» даёт модели то, что можно анимировать; «бумажный кораблик» — нет.
- Указывайте камеру. Статичная, панорамирование, наезд, ручная — язык камеры устраняет массу неоднозначности.
- Ограничьтесь одной сценой. Описание нескольких планов в одном коротком ролике часто даёт смазанный результат.
Когда результат генерации из текста неудовлетворителен, сначала меняйте промпт, а уже потом трогайте любые технические параметры.
Отправка запроса на генерацию видео из изображения
Путь через изображение структурно совпадает с текстовым путём, только с одним дополнением: исходное изображение. Метод тестирования «сначала минимальное» здесь работает так же.
Минимальная структура
{
"model": "gemini-omni-flash/image-to-video",
"prompt": "Мягкий ручной дрейф, субъект слегка поворачивается к камере, мягкий оконный свет",
"image": "https://your-cdn.example.com/source-frame.jpg"
}
Здесь промпт описывает движение и поведение камеры относительно изображения, а не содержимое сцены — содержимое уже задано изображением. Это самая частая концептуальная ошибка: люди пишут полное описание сцены, а потом недоумевают, почему вывод игнорирует их исходный кадр.
Как передать исходное изображение
Изображение передаётся как ссылка, и сервис должен иметь возможность его получить. Отсюда два практических следствия:
- Ресурс должен быть публично доступен сервису, а не находиться за вашим localhost, VPN или бакетом с аутентификацией. Подписанный URL с коротким сроком действия подойдёт, если он ещё действителен на момент выполнения запроса.
- Формат и размер должны поддерживаться. Придерживайтесь распространённых веб-форматов и разумных размеров. TIFF на 40 MB — это заявка на отладку.
Если ваши изображения хранятся в приватном хранилище, генерируйте подписанный URL с коротким сроком действия во время запроса, а не пытайтесь сделать бакет публичным.
Практические отличия от текстового пути
- Роль промпта меняется с описания сцены на описание движения.
- Валидация получает дополнительный шаг получения ресурса, отсюда целый новый класс сбоев (см. раздел об отладке).
- Композиция вывода ограничена соотношением сторон исходного изображения, что влияет на планирование нижестоящего макета.
Сначала протестируйте URL изображения в браузере. Если он не загружается чисто у вас, то и у сервиса тоже.
Вызов API через curl и Python
Заставьте один и тот же запрос работать в двух местах: в терминале (для быстрой итерации и видимости сырых данных) и в вашей кодовой базе (для реального использования).
curl
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-flash/text-to-video",
"prompt": "Медленный наезд камеры на мокрой от дождя неоновой улице ночью, кинематографично"
}'
Замените строку model на gemini-omni-flash/image-to-video и добавьте поле image, чтобы попасть в другую конечную точку — больше ничего менять не нужно.
Используйте -sS, чтобы ошибки не проглатывались молча; при проверке ответа пропускайте его через форматтер JSON, чтобы вложенные поля были читаемыми.
Python
import os
import requests
BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": "Медленный наезд камеры на мокрой от дождя неоновой улице ночью, кинематографично",
}
resp = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=300)
resp.raise_for_status()
print(resp.json())
Две детали, которые стоит скопировать: читайте ключ из переменной окружения и задавайте достаточно щедрый таймаут. Генерация видео — не мгновенный запрос; таймаут по умолчанию в 10 секунд даёт ложные сбои, которые выглядят как ошибка API, а на самом деле ваш клиент просто сдался раньше времени.
Для генерации из изображения добавьте одну строку:
payload["model"] = "gemini-omni-flash/image-to-video"
payload["image"] = "https://your-cdn.example.com/source-frame.jpg"
При получении не-2xx кода состояния обязательно выводите или логируйте сырое тело ответа перед тем, как выбрасывать исключение. Текст ошибки обычно прямо называет проблемное поле.
Организация кода интеграции
После того как оба пути заработали, возникает соблазн оставить в кодовой базе две почти одинаковые функции. Чуть лучшая структура почти ничего не стоит и окупится в тот момент, когда вы добавите вторую видеомодель.
Два общих компонента
Один построитель запросов. Функция, которая принимает параметры на уровне намерения и возвращает словарь payload:
def build_video_payload(prompt, image_url=None, duration=None):
if image_url:
payload = {
"model": "gemini-omni-flash/image-to-video",
"prompt": prompt,
"image": image_url,
}
else:
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": prompt,
}
if duration:
payload["duration"] = duration
return payload
Выбор конечной точки становится результатом вопроса «есть ли у меня изображение?», что соответствует реальному продуктному решению. Вызывающий код никогда не касается ID моделей напрямую.
Один обработчик ответов. Функция, которая раздельно обрабатывает транспортные ошибки, ошибки payload и сбои на уровне модели, а затем возвращает нормализованный объект результата (статус, ссылка на видео, сырое тело ответа для логов). Все вызовы проходят через него, поэтому семантика ошибок у обеих конечных точек остаётся согласованной.
Почему это стоит делать
- ID модели меняется в одном месте. Когда вы перейдёте на другую видеомодель, отредактируете только построитель, а не пятнадцать точек вызова.
- Согласованная обработка ошибок. Сбой получения изображения и сбой валидации промпта отображаются в вашем UI одинаково.
- Тестирование без сети. Построитель — чистая функция; структуру payload можно юнит-тестировать дёшево.
- Видимость тарификации. Поскольку видео оплачивается по сгенерированному результату, единый обработчик — естественное место для записи длительности и размера вывода для отслеживания затрат.
Держите построитель тонким. Бизнес-логика о том, что генерировать, принадлежит вызывающему коду; построитель должен лишь знать, как выразить это намерение в форме API.
Отладка частых сбоев запросов
Почти все ранние сбои попадают в одну из трёх категорий. Сначала определите категорию, затем исправляйте.
Категория 1: структура запроса
Симптом: немедленный 4xx, сообщение об ошибке упоминает отсутствующее или неизвестное поле, или жалуется на некорректный формат JSON.
Проверяйте по порядку:
- Валиден ли JSON? Вставьте тело запроса в линтер. Оставшаяся от ручного редактирования payload висячая запятая — классика.
- Точен ли ID модели?
gemini-omni-flash/text-to-videoиgemini-omni-flash-text-to-video— не одна и та же строка. Опечатка здесь даёт ошибку «модель не найдена», которая читается как проблема аутентификации. - Полны ли заголовки? Установлены и
Authorization, иContent-Type: application/json. - Соответствует ли модель конечной точке? Отправка поля
imageна текстовую конечную точку не даст желаемого результата — это поле либо будет отклонено, либо проигнорировано, и в обоих случаях вы получите неверный результат.
Категория 2: входной ресурс (только путь через изображение)
Симптом: запрос принят, но сбоит во время обработки, или ошибка упоминает получение или декодирование изображения.
Проверяйте:
- Откройте URL изображения в окне приватного браузера без cookie. Если он не загружается у вас, то и у сервиса тоже.
- Убедитесь, что URL не является адресом localhost, хостом приватной сети или просроченной подписанной ссылкой.
- Убедитесь, что формат — распространённый веб-формат, а размер файла разумный.
- Убедитесь, что ответ действительно является изображением — CDN, возвращающий код 200 с HTML-страницей ошибки в теле, на удивление частая ловушка.
Категория 3: сам вызов модели
Симптом: запрос валиден, ресурс доступен, но генерация сбоит или отклоняется — обычно из-за политики содержимого или ёмкости.
Проверяйте:
- Сократите до минимального промпта и повторите. Если успешно, то переменной является ваш промпт.
- Проверьте, достаточно ли велик таймаут клиента — в логах таймаут клиента выглядит точно так же, как сбой сервера, если не проверить, был ли вообще получен ответ.
- Включите полное логирование запросов/ответов (с маскированием ключей), чтобы с первого взгляда различать эти три категории проблем.
Эффективный порядок отладки
Минимальный payload → проверка → добавление изображения → проверка → добавление необязательных параметров по одному → проверка. Когда что-то ломается, виновником является последнее сделанное изменение. Если придерживаться отладки одного переменного за раз, большая часть боли интеграции исчезает.
Начните с минимального рабочего вызова каждой конечной точки, оберните его в общий построитель и обработчик, затем постепенно расширяйте — этот путь позволит сохранять предсказуемость как генерации из текста, так и генерации из изображения по мере роста интеграции.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий