Как использовать gemini-omni-1.2-flash через HiAPI API: curl и Python

Как выглядит запрос к gemini-omni-1.2-flash

Прежде чем написать первую строку кода, полезно понять, из чего на самом деле состоит вызов gemini-omni-1.2-flash на HiAPI. Каждый отправляемый вами запрос — это JSON-объект, отправляемый на единственную конечную точку и аутентифицируемый с помощью вашего API-ключа HiAPI. Эта структура одинакова для разных моделей, то есть, освоив её для этой модели, вы сможете повторить тот же шаблон и в других местах.

На высоком уровне запрос содержит четыре категории информации:

• Идентификатор модели — строка gemini-omni-1.2-flash, сообщающая HiAPI, какой модели направить вашу задачу.
• Входные данные — то, что вы хотите, чтобы модель обработала. В зависимости от модальности это может быть промпт или поля структурного ввода.
• Параметры генерации — опции, формирующие вывод, например длительность и разрешение. Это те ручки, которые вы будете настраивать далее в этом руководстве.
• Метаданные запроса — любая информация, необходимая платформе для идентификации и отслеживания вашей задачи, например клиентская ссылка для сопоставления.

Структура ответа

Ответ предсказуем в той же мере. Синхронный вызов возвращает результат прямо в поле результата. Асинхронный вызов возвращает дескриптор задачи — идентификатор, который используется для запроса статуса и в конечном итоге для получения вывода. Заранее поняв, с каким из этих двух случаев вы имеете дело, вы сэкономите массу времени на отладку.

Почему структура важна

Большинство первых неудач при интеграции связаны со структурой запроса: отсутствующие поля, параметры неверного типа или ложное предположение о том, что вызов синхронный, хотя это не так. Если вы усвоите эту анатомию до написания кода, последующие примеры на curl и Python станут простым переводом, а не загадочными заклинаниями.

Полезная привычка: храните точное тело JSON, которое вы отправляете, в переменной или файле. Когда что-то пойдёт не так, вы захотите увидеть, что именно было отправлено, а не восстанавливать это по памяти.

Аутентификация в одну строку

Каждый запрос несёт ваш API-ключ в заголовке авторизации. Относитесь к ключу как к секрету: загружайте его из переменной окружения, а не вписывайте в код, и никогда не коммитьте в систему контроля версий. Одна эта дисциплина предотвращает самую распространённую ошибку безопасности в интеграциях API.

Отправьте свой первый рабочий запрос через curl

Самый быстрый способ убедиться, что ключ, конечная точка и структура запроса верны, — это вызов через curl. Он устраняет каждый слой абстракции между вами и API, поэтому если он работает, вы знаете, что проблема (если она есть) в вашем коде, а не в конфигурации окружения.

Шаг 1: сохраните ключ

Поместите API-ключ HiAPI в переменную окружения, чтобы он не попал в историю оболочки или общие скрипты:

export HIAPI_API_KEY="your_key_here"

Шаг 2: сформируйте тело запроса

Запишите тело JSON в файл. Это сохраняет команду curl читаемой и даёт вам переиспользуемый артефакт:

cat > request.json <<'EOF'
{
  "model": "gemini-omni-1.2-flash",
  "input": {
    "prompt": "Опишите, что вы хотите, чтобы сгенерировала модель."
  },
  "parameters": {
    "duration": 5,
    "resolution": "720p"
  }
}
EOF

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

Шаг 3: отправьте запрос

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

Шаг 4: прочитайте ответ

Если запрос синхронный, вы увидите сгенерированный результат в теле ответа. Если асинхронный, вы получите дескриптор задачи — идентификатор задачи плюс поле статуса. Запишите этот идентификатор; он понадобится вам при опросе.

Если ваш терминал это поддерживает, пропустите вывод через форматировщик JSON или сохраните его в файл для внимательного изучения:

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json > response.json

Шаг 5: убедитесь перед масштабированием

Не начинайте настраивать длительность, разрешение или пакетную обработку, пока этот голый вызов не завершится успешно и вы не сможете понять вывод. Первый «зелёный» запрос — это ваша базовая линия; всё последующее — это инкрементальные изменения, которые можно с ней сравнивать.

Перенос вызова на Python

Как только curl работает, перенос на Python — механическая работа. Цель — написать небольшой читаемый клиент, точно повторяющий запрос, чтобы при сбое вызова из Python можно было построчно сравнить его с версией на curl по каждому полю.

Минимальный клиент

import json
import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/generate"

payload = {
    "model": "gemini-omni-1.2-flash",
    "input": {
        "prompt": "Опишите, что вы хотите, чтобы сгенерировала модель."
    },
    "parameters": {
        "duration": 5,
        "resolution": "720p"
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, json=payload, timeout=60)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

На что обратить внимание

• json=payload сериализует словарь за вас — поэтому тело совпадает с файлом curl, а не является вручную склеенной строкой.
• raise_for_status() превращает не-2xx ответы в исключения, так что сбой сразу виден, а не молча возвращает тело ошибки, которое вы затем пытаетесь разобрать как результат.
• timeout=60 не даёт скрипту зависнуть навсегда при застрявшем соединении. Выбирайте значение в зависимости от того, сколько, по вашим ожиданиям, займёт генерация.

Обработка двух структур ответа

Поскольку вызов может вернуть либо результат, либо дескриптор задачи, ветвите логику по ответу, а не предполагайте одну структуру:

if "job_id" in data:
    print("Асинхронная задача запущена:", data["job_id"])
else:
    print("Результат готов")

Эта маленькая проверка — разница между клиентом, работающим в обоих режимах, и падением при первом же решении платформы выполнить вашу задачу асинхронно.

Поместите это в функцию

Оберните вызов в функцию с параметрами промпта, длительности и разрешения. Тогда при настройке запуск того же кода с разными параметрами станет тривиальным, а структура запроса будет определена в одном месте.

Асинхронные задачи и опрос результатов

Некоторые запросы gemini-omni-1.2-flash завершаются достаточно быстро, чтобы вернуть результат сразу. Другим нужно больше времени, и HiAPI вместо этого возвращает дескриптор задачи. Ваша интеграция должна обрабатывать оба случая, и именно асинхронный путь ломает большинство хрупких клиентов.

Распознавание асинхронного ответа

Асинхронный ответ содержит идентификатор задачи и статус. Вы получаете не готовый вывод, а обещание: работа принята и будет обработана. Ваша задача — вернуться и проверить.

Правильный опрос

Наивный подход — долбить конечную точку статуса в тесном цикле while True — имеет два недостатка: он расходует ваш бюджет лимита запросов и создаёт ненужную нагрузку на платформу, при этом не ускоряя получение результата.

Лучший шаблон использует ограниченную задержку с экспоненциальным ростом:

import time

def poll_job(job_id, base_delay=1.0, max_delay=10.0, max_wait=300.0):
    elapsed = 0.0
    delay = base_delay
    while elapsed < max_wait:
        status = get_job_status(job_id)
        if status["state"] == "succeeded":
            return status
        if status["state"] == "failed":
            raise RuntimeError(status.get("error", "job failed"))
        time.sleep(delay)
        elapsed += delay
        delay = min(delay * 2, max_delay)
    raise TimeoutError(f"job {job_id} did not finish in time")

Три правила опроса

• Начинайте с малого, растите медленно. Короткий начальный интервал дёшево ловит быстрые задачи; удвоение до предела не даёт медленным задачам проверяться слишком часто.
• Всегда задавайте максимальное время ожидания. Без него зависшая задача будет вечно подвешивать ваш процесс. Исключение по таймауту гораздо лучше молчаливого зависания.
• Различайте успех, ошибку и ожидание. Только два из них должны останавливать цикл, и только один должен возвращать результат.

Предпочитайте webhook, когда он доступен

При высокой нагрузке опрос каждой задачи плохо масштабируется. Там, где HiAPI предоставляет обратные вызовы по завершении, используйте их для получения результата вместо повторных запросов. Для интерактивных инструментов и низконагруженных скриптов опроса с задержкой вполне достаточно.

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

Выбор длительности и разрешения

Длительность и разрешение — два параметра, которые наиболее directly влияют на ваш вывод, а также на ваш счёт и время ожидания. Ни для одного из них нет единственно правильного значения; правильный выбор зависит от того, что вы создаёте. Важно выбирать их осознанно, а не копировать числа из примеров.

Длительность

Длительность управляет продолжительностью сгенерированного вывода. Большая длительность даёт больше контента, но требует больше вычислительных ресурсов для генерации, что влияет как на задержку, так и на то, как тарифицируется запрос (оплата основана на длительности вывода). Несколько практических рекомендаций:

• Начинайте с короткой при тестировании. Короткая длительность доказывает работоспособность конвейера от начала до конца, не тратя время на каждую итерацию.
• Согласуйте длительность с назначением. Короткий фрагмент для превью или миниатюры не нуждается в длине полного готового материала.
• Не удлиняйте спекулятивно. Генерируйте ту длину, которую реально будете использовать; обрезка после этого ничего вам не даёт.

Разрешение

Разрешение управляет точностью вывода. Более высокое разрешение означает больше деталей и больший объём полезной нагрузки, с соответствующим увеличением времени обработки и стоимости. Компромиссы, которые нужно взвесить:

• Превью и черновая работа не нуждаются в высоком разрешении — это проверка корректности, а не финальный продукт.
• Финальные материалы могут стоить более высокой настройки, особенно если вывод показывается в полном размере.
• Пропускная способность и хранилище тоже важны: выводы высокого разрешения тяжелее передавать и хранить.

Настраивайте одну переменную за раз

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

Рассматривайте стоимость как формулу, а не как число

Поскольку цены находятся на панели тарифов сайта, рассматривайте стоимость как функцию: общая стоимость масштабируется с длительностью вывода, а при более высоком разрешении — также с размером итогового вывода и объёмом обработки. Ваша задача — знать, какие параметры управляют этой функцией, и затем перед запуском в продакшен посмотреть текущие цены. Так ваши оценки останутся верными, даже если цены изменятся.

Распространённые ошибки и способы их устранения

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

1. Структура запроса

Симптом: ошибка валидации или сообщение об отсутствующем либо неожиданном поле.

Исправление: убедитесь, что тело — валидный JSON (завершающая запятая — классический виновник), что поле model точно равно gemini-omni-1.2-flash, и построчно сравните вашу полезную нагрузку с рабочим примером curl. Если curl работает, а Python нет, сравните тела двух запросов.

2. Параметры

Симптом: ошибка указывает на duration или resolution, либо размер вывода неожиданный.

Исправление: проверьте типы (число там, где нужно число, строка там, где нужна строка) и убедитесь, что значения в допустимых пределах. Если параметр молча игнорируется, проверьте, вложен ли он туда, где его ожидает API, а не на верхнем уровне.

3. Аутентификация

Симптом: ответ 401 или 403.

Исправление: убедитесь, что ключ присутствует в заголовке Authorization с префиксом Bearer, что переменная окружения действительно содержит значение (пустая строка выглядит очень похоже на неверный ключ) и что вы не скопировали в ключ окружающие пробелы или кавычки. Если вы подозреваете утечку ключа, перегенерируйте его.

4. Статус задачи

Симптом: вы опрашиваете, но никогда не видите успеха, или принимаете ожидающую задачу за неудачную.

Исправление: убедитесь, что опрашиваете правильный идентификатор задачи, что цикл распознаёт все статусы (pending, running, succeeded, failed) и что максимальное время ожидания достаточно велико для реальных задач. Логируйте каждый переход состояния, чтобы видеть, где он застревает.

5. Лимиты запросов и временные сбои

Симптом: ответ 429 или периодические ошибки 5xx.

Исправление: выполняйте повтор с задержкой и джиттером, а не сразу. Если вы опрашиваете много задач, снизьте параллелизм. Временные ошибки нормальны; клиент с разумными повторами их переживёт.

Одна дисциплина отладки

Когда что-то идёт не так, меняйте только одно и перезапускайте как можно меньший запрос. Сохраняйте исходное тело ответа — сообщения об ошибках обычно указывают точное поле или условие, и их внимательное чтение экономит больше времени, чем любые догадки.

Контрольный список для производственной интеграции

Скрипт, один раз отработавший на вашем ноутбуке, — это не интеграция. Перед запуском в продакшен закройте эти пробелы.

Повторы с задержкой

Оберните сетевые вызовы в стратегию повторов, обрабатывающую временные сбои — таймауты, сбросы соединения, ответы 429 и 5xx. Используйте экспоненциальную задержку с джиттером, ограничивайте число попыток и никогда не повторяйте запросы, провалившие валидацию; повтор ошибочного тела лишь быстрее провалится снова.

Таймауты повсюду

Задавайте явные таймауты для каждого HTTP-вызова. Различайте таймаут соединения и таймаут чтения и убедитесь, что таймаут запроса генерации не меньше времени, которое реально требуется для генерации, — но с верхней границей.

Идемпотентность вокруг задач

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

Логи, которые отвечают на вопросы

Для каждого запроса логируйте имя модели, значения параметров (длительность, разрешение), дескриптор задачи, переходы состояния и задержку. Никогда не логируйте API-ключи или полное содержимое промпта, которое может содержать конфиденциальные данные. Когда в 3 часа ночи что-то пойдёт не так, именно эти логи позволят вам точно восстановить произошедшее.

Наблюдаемость и оповещения

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

Гигиена конфигурации

Держите конечную точку, имя модели и параметры по умолчанию в конфигурации, а не разбросанными по коду. Загружайте API-ключ из менеджера секретов или переменной окружения. Если цены и лимиты важны для вашего планирования, сверяйтесь с панелью тарифов, а не вписывайте числа в код, поскольку они меняются.

Пройдя этот список, ваша интеграция gemini-omni-1.2-flash сможет обрабатывать реальный трафик, а не только первый тест. Начните с рабочего вызова curl, перенесите его на Python и стройте дальше оттуда.