Руководство
Как использовать gemini-omni-flash/text-to-video через HiAPI API: руководство по curl и Python
На этой странице
Что делает этот эндпоинт и когда его использовать
gemini-omni-flash/text-to-video — это генеративный эндпоинт на HiAPI, который преобразует текстовый промпт — при необходимости с опорой на изображение первого кадра — в короткий видеоролик. Вы отправляете запрос, HiAPI возвращает задачу, которую можно опрашивать, а после её завершения вы получаете URL видео, которое можно скачать или воспроизводить потоком.
Этот эндпоинт подходит для следующих сценариев:
- Быстрые концептуальные ролики. Генерация коротких маркетинговых тизеров, раскадровок или материалов для переходов в соцсетях прямо по одному-двум предложениям описания.
- Движение по изображению. У вас уже есть статичный кадр — фото продукта, дизайн персонажа, иллюстрация — и вы хотите его оживить, а не генерировать с нуля.
- Пакетная генерация в конвейере. Поскольку генерация асинхронна, вы можете из бэкенд-воркера одновременно отправить множество задач, а затем собрать результаты, не удерживая соединение запроса.
Он не подходит для длинных видео, попиксельно точного монтажа или детерминированного воспроизведения конкретных кадров. Считайте его быстрым генеративным черновиком: дешёвая итерация, достаточная для просмотра, полностью автоматизируемая от начала до конца.
Всё нижеследующее использует один и тот же интерфейс HiAPI — один API key, один базовый URL, одна структура запроса — поэтому написанный здесь код без повторного изучения аутентификации или опроса можно перенести на другие генеративные эндпоинты.
Перед отправкой первого запроса
Прежде чем первый вызов завершится успешно, нужно подготовить четыре вещи.
1. API key
Создайте key в аккаунте HiAPI и сохраните его в переменной окружения, а не в исходном коде:
export HIAPI_API_KEY="your_key_here"
2. Базовый URL и путь эндпоинта
Все запросы отправляются на базовый URL HiAPI, а идентификатор модели находится в пути. Рассматривайте базовый URL в коде как единственную константу, чтобы менять его в одном месте:
export HIAPI_BASE_URL="https://api.hiapi.ai"
3. JSON-тело запроса
Запрос — это POST с Content-Type: application/json и bearer token в заголовке Authorization. Если вы не передаёте изображение первого кадра по URL, здесь нет ни form-encoding, ни multipart-загрузки.
4. Изображение первого кадра (необязательно)
Если вы планируете генерацию с опорой на изображение, сначала убедитесь, что оно доступно по публичному HTTPS URL. Пути локальной файловой системы не работают — API загружает изображение на сервере.
Практический совет по контролю затрат: этот эндпоинт тарифицируется по сгенерированному результату — уровень разрешения и длительность ролика учитываются. Актуальные цены смотрите на панели тарифов HiAPI, поэтому перед масштабированием пакетных задач проверьте их там. Важная привычка: сначала прототипируйте с минимальными настройками, а повышайте их, когда промпт начнёт давать желаемый результат.
Построение запроса на генерацию
Запрос концептуально состоит из трёх частей: путь модели, промпт (и, возможно, изображение) и параметры генерации. Структура выглядит так:
{
"prompt": "Медленный наезд камеры на стеклянную кофейную чашку, пока вверх поднимается пар, утренний свет, малая глубина резкости",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}
Промпт
Поле prompt содержит описание кадра. Пишите его как заметки режиссёра: субъект, движение камеры, свет и атмосфера. Конкретные глаголы движения («медленный наезд камеры», «камера панорамирует влево», «пар поднимается вверх») направляют результат надёжнее, чем простое нагромождение прилагательных.
Необязательный первый кадр
Поле image необязательно. Если его опустить, модель сгенерирует весь ролик исключительно по тексту. Если его указать, ролик начнётся с этого кадра, а промпт опишет, что должно произойти дальше. Это самый мощный рычаг для согласованности: текстовый промпт при каждом запуске заново воображает сцену, а фиксированный первый кадр сохраняет композицию стабильной между итерациями.
Если передаёте оба, убедитесь, что они согласованы. Первый кадр с пейзажем пустыни в сочетании с промптом о городской улице под дождём даст путаный результат — модели придётся примирять две противоречивые инструкции.
Где размещать параметры
resolution, duration и audio находятся на верхнем уровне того же JSON-тела, что и prompt, image. Не нужно запоминать вложенный объект options. Держите тело запроса плоским и читаемым — при отладке пакетных задач это сильно упрощает логирование и сравнение запросов.
Выбор разрешения и длительности
Два параметра одновременно определяют внешний вид результата и стоимость задачи: уровень разрешения и длительность ролика.
Уровни разрешения
HiAPI предоставляет этот эндпоинт на нескольких уровнях разрешения. Более низкий уровень — подходящее значение по умолчанию на этапе разработки промпта: рендеринг быстрее, и вы можете итеративно подбирать формулировки, не платя за детали, которые всё равно выбросите. Как только промпт начнёт надёжно давать нужную композицию, поднимите уровень для финального рендера.
Практический рабочий процесс:
- Составьте черновик промпта на минимальном уровне.
- Сгенерируйте два-три варианта и сравните.
- Зафиксируйте промпт, затем отрендерите заново на более высоком уровне.
Длительность ролика
Длительность указывается в секундах, и этот эндпоинт рассчитан на короткие ролики. Держите её умеренной: короткий ролик делает отдельную задачу быстрее, снижает стоимость повторной попытки при сбое и, если позже понадобится более длинная последовательность, позволяет склеить несколько роликов. Если для кадра нужно восемь секунд экранного времени, две генерации по четыре секунды обычно легче контролировать, чем одну длинную.
Как это соотносится с бюджетом
Этот эндпоинт тарифицируется по произведённому результату — более высокое разрешение и большая длительность увеличивают тарифицируемый объём одной задачи. Поскольку цены рассчитываются за единицу генерации и уровни со временем меняются, читайте актуальные цифры на панели тарифов HiAPI вместо жёстко заданных ожиданий. Правило планирования, которое действует при любом изменении цен: умножьте ожидаемое число задач на объём результата, прототипируйте с минимальными настройками и только потом повышайте разрешение.
Управление нативным звуком
Флаг audio определяет, будет ли возвращаемое видео нести нативную звуковую дорожку, сгенерированную вместе с изображением.
{
"prompt": "Дождь барабанит по жестяной крыше, дверь медленно со скрипом открывается",
"audio": true
}
Что меняется при включении
При audio: true модель генерирует звуки, соответствующие описанной в промпте сцене — фоновые шумы, атмосферные текстуры и звуковые события, подразумеваемые действием. Выходное видео будет содержать аудиопоток, поэтому скачанный файл уже полный и не требует отдельной обработки звуковых эффектов.
Что меняется при выключении
При audio: false вы получаете видео без звука. Это подходит, когда:
- Вы наложите на ролик свою музыку или закадровый голос в редакторе.
- Ролик — фоновый элемент в более крупной композиции.
- Вы итерируете только по изображению и не хотите включать генерацию аудио в цикл.
Как писать промпты для аудио
Если аудио включено, описывайте звуковую сцену так же, как изображение. Звуковые подсказки в промпте — шум дождя, шаги, механические звуки, конкретная атмосфера помещения — дают аудиомодели опору. Чисто визуальный промпт всё равно сгенерирует звук, но это будет общий фоновый шум, а не звуки, соответствующие кадру.
Одна деталь, которую стоит проверить пораньше: аудио заметно меняет характер ролика. Сгенерируйте один и тот же промпт по разу с включённым и выключенным флагом, посмотрите оба результата и решите, какой режим реально нужен проекту, прежде чем строить на нём пакетные задачи.
Работа с жизненным циклом асинхронной задачи
Генерация видео занимает больше времени, чем типичный HTTP-запрос должен оставаться открытым, поэтому эндпоинт асинхронный. Каждый вызов проходит один и тот же трёхшаговый цикл.
Шаг 1: отправка
Выполните POST с JSON-телом на эндпоинт. Успешная отправка сразу возвращает идентификатор задачи — обычно id задачи — и статус, показывающий, что задача в очереди или обрабатывается. На этом этапе ещё ничего не отрендерено.
Шаг 2: опрос
Получив id задачи, запрашивайте эндпоинт статуса с фиксированным интервалом. Каждый опрос возвращает текущий статус: queued, processing, completed или failed. Нужно обрабатывать все четыре состояния. Простой экспоненциальный backoff — начиная примерно с двух секунд с верхним пределом интервала — не даёт заваливать API запросами при длинных задачах и при этом быстро ловит короткие.
Шаг 3: получение
Когда статус сообщает о завершении, ответ несёт URL готового видео и метаданные задачи. Скачайте его, сохраните или передайте URL фронтенду. Если статус сообщает о сбое, извлеките сообщение об ошибке из ответа и решите, повторять ли попытку с изменённым промптом или выставить сбой наружу.
Защитные механизмы, которые стоит встроить
- Верхний предел тайм-аута. Ограничьте общее время опроса (например, несколькими минутами) и помечайте задачу как неудачную в своём коде, а не зацикливайтесь бесконечно.
- Максимальное число опросов. Защита от неконтролируемого цикла, когда статус никак не проясняется.
- Сохранение id задачи. Записывайте его в базу данных или лог сразу после получения. Если процесс упадёт посреди опроса, вы сможете восстановиться, а не генерировать заново и платить дважды.
- Идемпотентная отправка. Не отправляйте повторно из-за сетевого сбоя, пока не убедитесь, что первый запрос не прошёл; дублирующиеся задачи расходуют реальный результат.
Один раз правильно реализуйте этот цикл — и он подойдёт для всех асинхронных эндпоинтов HiAPI.
Рабочие примеры на curl и Python
curl: отправка, опрос, получение
Задайте key и базовый URL из переменных окружения, затем отправьте запрос:
curl -sS -X POST "$HIAPI_BASE_URL/v1/models/gemini-omni-flash/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Медленный наезд камеры на стеклянную кофейную чашку, пока вверх поднимается пар, утренний свет, малая глубина резкости",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}'
Ответ содержит id задачи. Возьмите из ответа эндпоинт статуса и опрашивайте его:
curl -sS "$HIAPI_BASE_URL/v1/tasks/<TASK_ID>" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Повторяйте, пока статус не станет completed, затем извлеките URL видео из тела ответа и скачайте его:
curl -sS -o clip.mp4 "<VIDEO_URL>"
Python: тот же цикл в обёртке
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}
def generate_video(prompt, image_url=None, resolution="720p",
duration=5, audio=False, timeout=300):
payload = {
"prompt": prompt,
"resolution": resolution,
"duration": duration,
"audio": audio,
}
if image_url:
payload["image"] = image_url
resp = requests.post(
f"{BASE}/v1/models/gemini-omni-flash/text-to-video",
headers=HEADERS, json=payload, timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["id"]
print(f"submitted: {task_id}")
deadline = time.time() + timeout
interval = 2
while time.time() < deadline:
status_resp = requests.get(
f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30
)
status_resp.raise_for_status()
data = status_resp.json()
state = data.get("status")
if state == "completed":
return data["video_url"]
if state == "failed":
raise RuntimeError(f"job failed: {data}")
time.sleep(interval)
interval = min(interval * 1.5, 10)
raise TimeoutError(f"job {task_id} did not finish in {timeout}s")
if __name__ == "__main__":
url = generate_video(
"Медленный наезд камеры на стеклянную кофейную чашку, пока вверх "
"поднимается пар, утренний свет, малая глубина резкости",
)
print("video ready:", url)
Скрипт отправляет текстовую задачу, опрашивает с backoff, применяет верхний предел тайм-аута и возвращает URL готового видео. Передайте image_url=, чтобы привязать генерацию к первому кадру, или установите audio=True, чтобы включить нативный звук. Отсюда можно поместить generate_video в очередь воркера, маршрут FastAPI или пакетный цикл — функция самодостаточна и не хранит состояния, кроме созданного ею id задачи.
Частые точки отказа и как их избежать
Большинство неудачных интеграций наступает на одну из пяти проблем.
Отказ при отправке из-за неверных параметров
Самая частая причина — API не может разобрать тело запроса: отсутствует prompt, длительность вне поддерживаемого диапазона или строка разрешения не поддерживается. Сверьтесь со справкой по эндпоинту, чтобы узнать допустимые значения, и проверяйте их локально. Небольшая утилита, проверяющая допустимые значения перед вызовом, экономит один сетевой обмен и избавляет от путаных ошибок.
Изображение первого кадра недоступно
API загружает image на сервере, поэтому URL, работающий в браузере, всё равно может не пройти — приватные бакеты, подписанные ссылки с истечением срока и защита от хотлинкинга вызывают эту проблему. Используйте публично читаемый HTTPS URL и до отправки проверьте, что он разрешается извне вашей сети.
Преждевременное прекращение опроса
Два варианта одной и той же ошибки: сдаться и счесть задачу неудачной при первом ответе processing, либо опрашивать слишком агрессивно и упереться в ограничение частоты. Решите обе проблемы циклом с backoff и верхним пределом, показанным выше: опрашивайте по расписанию, считайте нетерминальные состояния нормальными и выбрасывайте исключение только при явном сбое или тайм-ауте.
Потеря id задачи
Если процесс умирает после отправки, но до сохранения результата, задача уже оплачена, но недоступна. Сразу после отправки записывайте id задачи в постоянное хранилище и при запуске проверяйте, не осталось ли незавершённых id, прежде чем отправлять новые задачи.
Слишком большой объём результата при масштабировании
Генерация больших пакетов с высоким разрешением и большой длительностью быстро раздувает объём результата, а сгенерированные файлы дорого хранить и медленно отдавать. Прототипируйте в малом масштабе, финально рендерите один раз и держите правила жизненного цикла хранения в порядке. Поскольку тарификация привязана к сгенерированному результату, самое дешёвое исправление почти всегда — более короткий цикл прототипирования с меньшими настройками.
Пройдите этот список в среде предварительного развёртывания — и ваш путь в продакшене будет гладким.
Похожие статьи
Все статьи →-
Руководство
Практическое руководство по gpt-6.2-sol: 5 ценных способов применения текстовой модели в бизнесе
-
Руководство
Практическое руководство по gpt-6.2-astra: интеграция и ключевые моменты реализации для 5 ценных текстовых сценариев
Чек-лист для разработчиков: от выбора сценариев до внедрения в инженерию
-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий