HiAPI
Блог

Руководство

Как вызвать gemini-omni-1.1-flash через HiAPI API: руководство по curl и Python

Nov 17, 2026
Обложка в стиле абстрактной архитектуры: тёплые серые бетонные плоскости пересекаются в косом солнечном свете, со сланцево-синими тенями и узкими швами цвета шалфея.
На этой странице

Что нужно подготовить перед первым запросом

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

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)

Что это вам даёт

  1. Смена модели — одна строка. Когда появляется более новая модель, вы меняете константу и параметры по умолчанию; места вызова не затрагиваются.
  2. Необязательные параметры обрабатываются корректно. Опущенные значения не отправляются, что избегает описанной выше проблемы с отклонением null.
  3. Опрос невидим для вызывающего кода. Вызывающий код либо получает результат, либо исключение, но никогда — ID задачи, которым нужно управлять самому.
  4. Тестирование становится простым. Вы можете отдельно замокать post_json и wait_for_job, изолированно тестируя построение нагрузки и логику опроса.

Послойная организация

Держите структуру плоской и явной: транспортный уровень (HTTP, заголовки, таймауты, повторы), уровень модели (построение нагрузки для gemini-omni-1.1-flash) и уровень задач (отправка и опрос). Единая функция generate_video объединяет их, а каждый уровень достаточно мал, чтобы при проблеме его было легко осмыслить.

Сначала через curl убедитесь в правильности конфигурации подключения, затем переходите в Python для реальной работы, при изменении параметров всегда сверяйтесь со страницей модели и прячьте цикл опроса за интерфейсом, чтобы он никогда не просочился в код приложения.

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

Все статьи →

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

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

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