Руководство
Как вызвать gemini-omni-1.1-flash через HiAPI API: руководство по curl и Python
На этой странице
Что нужно подготовить перед первым запросом
Прежде чем писать код, убедитесь в четырёх вещах. Каждая из них избавит вас от лишнего цикла отладки.
API-ключ
Каждый запрос к HiAPI требует аутентификации с помощью API-ключа. Сгенерируйте его в консоли вашей учётной записи и убедитесь, что он не попадает в систему контроля версий. В примерах ниже ключ читается из переменной окружения, чтобы он не попал в историю shell или в закоммиченные файлы:
export HIAPI_API_KEY="your_key_here"
Базовый URL и путь эндпоинта
Базовый URL одинаков для всех моделей HiAPI; меняется только идентификатор модели. Путь эндпоинта и HTTP-метод берите из справочной документации API, а не переписывайте из статей в блогах, поскольку пути версионируются и могут меняться. Держите базовый URL константой в клиенте, чтобы в будущем при изменении нужно было поменять только одну строку.
Идентификатор модели
gemini-omni-1.1-flash передаётся как строка в теле запроса. Копируйте его точно — дефисы и суффикс версии важны. При опечатке ошибка обычно будет ошибкой валидации, а не маршрутизации, что может сбить с толку; см. раздел об отладке ниже.
Добавьте страницу модели в закладки
Страница модели gemini-omni-1.1-flash — это авторитетный источник, где указано, какие параметры существуют, какие значения они принимают и какова структура ответа. Считайте её справочником, который нужно сверять перед каждым изменением, а не материалом для одноразового прочтения.
Когда эти четыре пункта готовы, можно отправлять вызов.
Отправка минимального запроса через curl
Начните с самого маленького возможного запроса. Его цель — не получить хороший результат, а убедиться, что ваш ключ, эндпоинт и структура тела запроса согласованы. Как только он заработает, каждое последующее изменение будет инкрементальным.
curl -X POST "$HIAPI_BASE_URL/<endpoint-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "Камера медленно приближается к керамической чашке на деревянном столе, мягкий утренний свет"
}
}'
Что означает каждая часть:
- Метод и URL — вызов выполняется методом
POSTна путь эндпоинта, полученный из справочной документации API, с добавленным в начало базовым URL. - Заголовок
Authorization— содержит bearer-токен. Отсутствие или пустота этой переменной — самая частая причина 401. - Заголовок
Content-Type— должен бытьapplication/json. Без него сервер может вообще не разобрать тело запроса. model— точная строка идентификатора модели.input— объект с параметрами генерации. Сюда помещается промпт; сюда же добавляются разрешение и длительность, как описано ниже.
Если вызов возвращает идентификатор задачи или ответ о принятии в обработку, а не окончательный результат, это нормально — генерация асинхронна. Сохраните этот идентификатор; он понадобится на этапе опроса.
Перенос того же вызова в Python
Версия на Python должна отправлять точно такое же JSON-тело запроса. Сохранение идентичности нагрузки делает перенос достоверным: если curl работает, а Python — нет, проблема в вашем коде на Python, а не в понимании API.
import json
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<endpoint-path>"
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "Камера медленно приближается к керамической чашке на деревянном столе, мягкий утренний свет"
},
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=30)
response.raise_for_status()
print(response.json())
Несколько привычек, которые стоит выработать сразу:
- Собирайте URL из констант, а не разбрасывайте конкатенацию строк по всему коду.
- Задавайте явный таймаут. Без него зависший запрос может бесконечно блокировать рабочий процесс.
- Вызывайте
raise_for_status(), чтобы ошибочные ответы проявлялись как исключения, а не молча разбирались как тело успешного ответа. - Сериализуйте через
json.dumps, а не полагайтесь на form-encoding, который не сможет правильно сформировать вложенный объектinput.
Когда это заработает, у вас появится многоразовая структура запроса. В следующих двух разделах добавляются параметры, которые реально управляют результатом.
Настройка разрешения и длительности в запросе
Разрешение и длительность — это обычные поля внутри объекта input, на одном уровне с промптом. Концептуально нагрузка выглядит так:
{
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": "...",
"resolution": "<supported-value>",
"duration": "<supported-value>"
}
}
Ключевое правило: не задавайте эти значения жёстко по памяти или по руководству, прочитанному несколько месяцев назад. Поддерживаемые значения меняются с обновлениями модели, а передача неподдерживаемого значения вызывает ошибку валидации, которая выглядит как ошибка нагрузки. Прежде чем задавать их, всегда сверяйтесь с текущими принимаемыми значениями на странице модели.
Практичный шаблон
Храните значения в конфигурации, а не в коде:
payload = {
"model": "gemini-omni-1.1-flash",
"input": {
"prompt": prompt,
"resolution": settings.resolution,
"duration": settings.duration,
},
}
Это даёт три преимущества. Вы можете настраивать качество результата, не меняя логику. Во время разработки можно гонять дешёвые тесты с низким разрешением и повышать его только при финальном рендере. Когда платформа добавляет поддерживаемое значение, вы меняете одно поле конфигурации, а не обыскиваете всю кодовую базу.
Есть ещё две менее очевидные ловушки, о которых стоит сказать. Во-первых, разрешение и длительность обычно связаны со стоимостью — тарификация, как правило, привязана к объёму результата, поэтому более длинные и более качественные фрагменты не бесплатны. Во-вторых, если поле необязательное, опускайте его, а не отправляйте пустую строку или null; некоторые валидаторы отклоняют явный null, даже если само поле необязательно.
Работа с асинхронной генерацией: сначала отправка, затем опрос
Генерация требует времени, поэтому API использует схему «отправить и опрашивать». Ваш клиент должен рассматривать их как две отдельные операции с разной семантикой повторов.
Шаг 1: отправка
Вызов отправки — это уже построенный вами запрос. Он возвращает идентификатор этой задачи — в зависимости от эндпоинта это может быть task ID, job ID или похожее поле. Разбирайте его защитно:
created = response.json()
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier in response: {created}")
Шаг 2: опрос
Затем опрашивайте эндпоинт статуса с этим идентификатором, пока задача не достигнет терминального состояния. Надёжный цикл обладает четырьмя свойствами: максимальное время ожидания, задержка с экспоненциальным ростом, проверка терминальных состояний и проверка на неудачу.
import time
def wait_for_job(job_id, timeout=600, initial_delay=2, max_delay=30):
deadline = time.time() + timeout
delay = initial_delay
while time.time() < deadline:
status = fetch_status(job_id) # GET on the status endpoint
state = status.get("status")
if state in ("succeeded", "completed"):
return status
if state in ("failed", "error", "cancelled"):
raise RuntimeError(f"Job {job_id} ended in state {state}: {status}")
time.sleep(delay)
delay = min(delay * 2, max_delay)
raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")
Почему эти детали важны
- Экспоненциальная задержка не даёт непрерывно бомбардировать эндпоинт статуса задачи, которая ещё стоит в очереди и требует минуту на рендер.
- Жёсткий дедлайн не даёт зависшей задаче навсегда заблокировать рабочий процесс. При таймауте записывайте ID задачи, чтобы проверить её вручную.
- Явные терминальные состояния означают, что вы никогда не зациклитесь на непредусмотренном состоянии. Неизвестное состояние трактуйте как «продолжать ждать», но логируйте его один раз.
- Раздельные стратегии повторов: повторять вызов отправки рискованнее, чем вызов статуса, поскольку это может создать дублирующиеся задачи. Опрос можно повторять смело; отправку повторяйте только при явных ошибках передачи.
Диагностика типичных сбоев
Большинство сбоев сводится к нескольким категориям. Проверяйте их в этом порядке, потому что последующие симптомы часто вызываются предыдущими проблемами.
Ошибки аутентификации
Симптом: 401 или 403.
Что проверить первым: действительно ли ключ присутствует в окружении, где работает процесс? Печать len(API_KEY) ловит классический случай, когда переменная не задана и bearer-токен пустой. Затем убедитесь, что формат заголовка — Bearer <key> с одним пробелом, а ключ не отозван и не привязан к другому проекту.
Ошибки формата нагрузки
Симптом: 400 с жалобой на тело запроса или отсутствующее поле.
Что проверить первым: сравните своё тело запроса с рабочим запросом curl. Частые причины — отсутствие заголовка Content-Type: application/json, отправка form-encoded данных вместо JSON, плоская структура объекта input, тогда как API ожидает вложенность (или наоборот), а также случайное преобразование типов — числовая duration, отправленная как строка в кавычках, может не пройти валидацию.
Неподдерживаемые значения параметров
Симптом: 400 или 422 с указанием конкретного поля, например resolution или duration.
Что проверить первым: страницу модели, где перечислены текущие поддерживаемые значения. Почти всегда это устаревшее жёстко заданное значение, а не дефект кода. Если ранее рабочее значение теперь падает, сначала предположите, что модель обновилась, и перечитайте документацию, прежде чем винить сервис.
Опечатки в идентификаторе модели
Симптом: ошибка валидации или «не найдено», при этом ваш промпт не упоминается.
Что проверить первым: выведите строку model и сравните её посимвольно с документацией. Лишний пробел в конце или перепутанный порядок в номере версии легко пропустить.
Таймауты и временные сбои
Симптом: таймаут соединения, 429 или ответ 5xx. Что проверить первым: задан ли у вас таймаут. Добавьте таймаут, а затем добавьте ограниченные повторы с экспоненциальной задержкой только для 429 и 5xx — не повторяйте ошибки 4xx, кроме 429, потому что запрос будет падать одинаково каждый раз. Для длинных задач помните, что итоговый результат получается через опрос; таймаут вызова отправки не означает, что генерация провалилась.
Технически корректно, но результат не тот
Запрос успешен, но результат не соответствует ожиданиям. Это проблема промпта, а не API. Сделайте промпт конкретным в отношении субъекта, движения камеры, освещения и ритма, и меняйте только одну переменную за раз, чтобы можно было атрибутировать различия.
Обёртка в переиспользуемую клиентскую функцию
Цель обёртки проста: ваша бизнес-логика не должна содержать идентификаторы моделей, имена параметров или циклы опроса. Все детали, связанные с моделью, должны быть сосредоточены в одном месте.
def generate_video(prompt, *, resolution=None, duration=None, timeout=600):
payload = {
"model": "gemini-omni-1.1-flash",
"input": {"prompt": prompt},
}
if resolution is not None:
payload["input"]["resolution"] = resolution
if duration is not None:
payload["input"]["duration"] = duration
created = post_json(ENDPOINT, payload)
job_id = created.get("id") or created.get("job_id")
if not job_id:
raise RuntimeError(f"No job identifier: {created}")
return wait_for_job(job_id, timeout=timeout)
Что это вам даёт
- Смена модели — одна строка. Когда появляется более новая модель, вы меняете константу и параметры по умолчанию; места вызова не затрагиваются.
- Необязательные параметры обрабатываются корректно. Опущенные значения не отправляются, что избегает описанной выше проблемы с отклонением null.
- Опрос невидим для вызывающего кода. Вызывающий код либо получает результат, либо исключение, но никогда — ID задачи, которым нужно управлять самому.
- Тестирование становится простым. Вы можете отдельно замокать
post_jsonиwait_for_job, изолированно тестируя построение нагрузки и логику опроса.
Послойная организация
Держите структуру плоской и явной: транспортный уровень (HTTP, заголовки, таймауты, повторы), уровень модели (построение нагрузки для gemini-omni-1.1-flash) и уровень задач (отправка и опрос). Единая функция generate_video объединяет их, а каждый уровень достаточно мал, чтобы при проблеме его было легко осмыслить.
Сначала через curl убедитесь в правильности конфигурации подключения, затем переходите в Python для реальной работы, при изменении параметров всегда сверяйтесь со страницей модели и прячьте цикл опроса за интерфейсом, чтобы он никогда не просочился в код приложения.
Похожие статьи
Все статьи →-
Руководство
kling-image-4.0 на практике: 5 ценных сценариев применения и ключевые моменты интеграции
-
Руководство
Как использовать qwen-image-2.0-pro через HiAPI API: curl, Python и один рабочий запрос
Практическое интеграционное упражнение для разработчиков: первый успешный вызов, разбор структуры запроса и устранение неполадок
-
Руководство
Как вызвать API преобразования текста в видео veo-3.1: примеры на curl и Python
Практическое руководство по интеграции для разработчиков