Как подключить API Gemini 4 Hydrogen через Google или Ofox

Для прямого обращения к Google используйте gemini-4-hydrogen и API-ключ Google. Для Chat Completions через Ofox — google/gemini-4-hydrogen и ключ Ofox. Конечная точка, учётные данные и разбор ответа должны соответствовать выбранному способу подключения. При смене протокола недостаточно заменить только имя модели.

Google открыл Hydrogen для разработчиков 12 ноября 2026 года. В отличие от Carbon, API которого доступен только на платном уровне, Hydrogen поддерживает бесплатный и платный уровни Google. Однако бесплатный доступ зависит от права проекта на использование модели, проверки проекта и действующих лимитов. Руководство основано на документации и каталоге Ofox, проверенных 13 ноября 2026 года, и охватывает путь от выбора подключения до сохранения и проверки одного текстового ответа.

Это руководство публикует Ofox. Мы проверили форматы запросов и протестировали проверку ответов на синтетических данных, но не выполняли платные запросы к Hydrogen и не измеряли скорость или качество ответов. Примеры предназначены для самостоятельного запуска и не означают, что конкретная учётная запись уже прошла реальную проверку. Для выбора модели прочитайте сравнение Carbon, Hydrogen и Argon. Оригинальные документы Google по ссылкам доступны на английском.

Выберите способ подключения до создания ключа

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

Google рекомендует Interactions для новых интеграций, сохраняя поддержку GenerateContent. Текущий публичный каталог Ofox указывает для Hydrogen протоколы OpenAI и Gemini и явно перечисляет /v1/chat/completions для OpenAI. В статье используется этот документированный путь. Из этого не следует, что пример Google Interactions заработает через Ofox после простой замены базового URL.

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

Снимок официального объявления от 13 ноября 2026 года. Он подтверждает публикацию анонса, а не выполнение запроса или измеренную производительность. Источник на английском.

Подготовьте проект Google и проверьте бесплатный доступ

Для примера Google откройте страницу API-ключей AI Studio и определите проект, которому будет принадлежать запрос. Новым пользователям может предоставляться проект по умолчанию; существующие Cloud-проекты иногда нужно импортировать в AI Studio. Создайте или выберите ключ нужного проекта, затем проверьте его уровень и доступную квоту. Ключ другого проекта тоже может пройти аутентификацию, но расходовать будет другую квоту.

Поддержка бесплатного уровня не означает немедленную готовность любого нового проекта. В руководстве Google по проверке проектов дополнительные проекты и проекты, созданные вне AI Studio, указаны среди случаев, когда может требоваться проверка. Такие запросы возвращают 403 с FREE_TIER_VERIFICATION_REQUIRED.

Если вы получили именно эту ошибку:

1. Откройте ссылку проверки из сообщения или выберите Verify project на странице Projects в AI Studio. Номер проекта должен совпадать с проектом вашего ключа.
2. Пройдите проверку устройства Google на поддерживаемом физическом смартфоне. Если прав проекта недостаточно, попросите администратора выполнить проверку.
3. Дождитесь подтверждения и один раз повторите небольшой запрос ниже.

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

Проверьте действующие лимиты в AI Studio. Google ограничивает использование по проекту, а не по ключу. Ограничения числа запросов и токенов могут срабатывать независимо. Два ключа одного проекта не создают две самостоятельные квоты. Универсальное число бесплатных запросов в минуту здесь не приводится: ориентируйтесь на лимиты своего проекта и модели.

Храните ключ в серверной переменной окружения GEMINI_API_KEY либо загружайте через менеджер секретов среды развёртывания. Не помещайте его в браузерный код и репозиторий. Актуальная документация ключей различает ключи авторизации и стандартные ключи. Новые ключи AI Studio по умолчанию являются ключами авторизации. Стандартные ключи без ограничений отклоняются, а стандартные ключи с явно заданными ограничениями по-прежнему могут работать.

Программа ниже явно читает GEMINI_API_KEY. Это исключает автоматический приоритет SDK, при котором одновременно заданный GOOGLE_API_KEY был бы выбран первым. В macOS/Linux используйте export GEMINI_API_KEY="YOUR_GOOGLE_KEY", в PowerShell — $env:GEMINI_API_KEY="YOUR_GOOGLE_KEY". Подставьте ключ в локальном терминале и не сохраняйте секреты в общей истории команд. Запускайте программу в той же сессии терминала, где задана переменная.

Отправьте запрос в Google из Python

Для текущего SDK используйте Python 3.11 или новее и создайте изолированное окружение. Локальные проверки выполнялись с google-genai 3.3.0 на Python 3.11; минимальная версия Python, заявленная пакетом, — 3.11. Пример использует google-genai, а не старый пакет google-generativeai.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade 'google-genai>=2.34.0'
python -m pip show google-genai

В Windows PowerShell активируйте окружение командой .venv\Scripts\Activate.ps1. Указанная минимальная версия пакета включает поддержку продолжения ответа в переднем плане для Python, хотя этот короткий тест укладывается в бюджет одного ответа Hydrogen. Сохраните следующий код в hydrogen_google.py:

import json
import os
from pathlib import Path
from google import genai

key = os.environ.get("GEMINI_API_KEY")
if not key:
    raise SystemExit("Set GEMINI_API_KEY for the intended Google project.")

client = genai.Client(api_key=key)
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Give exactly three short bullet points about avoiding duplicate API retries.",
    store=False,
    generation_config={
        "thinking_level": "low",
        "max_output_tokens": 65536,
    },
)
Path("hydrogen-google.json").write_text(
    json.dumps(interaction.model_dump(mode="json"), indent=2),
    encoding="utf-8",
)
print("Saved hydrogen-google.json")
print("Interaction:", interaction.id)
print("Status:", interaction.status)

Выполните python hydrogen_google.py. Команда отправляет настоящий запрос в проект ключа; использование платного уровня оплачивается. Программа сохраняет ответ, даже если полезного текста не получено. Прежде чем считать тест успешным, запустите проверку ниже.

Промпт намеренно короткий и использует уровень low. Значение 65 536 — общий максимум токенов рассуждения и видимого ответа, а не требование сгенерировать столько текста и не гарантированный расход. Слишком маленький предел может не оставить места для текста после рассуждения. Для проверки подключения держите ввод коротким и смотрите фактический usage, не приравнивая максимум к потреблению.

store=False задаёт разовую интеракцию без сохранённого состояния. Не переносите эту настройку без изменений в фоновую задачу или диалог с previous_interaction_id. Это также не общая гарантия отсутствия любых журналов у провайдера. Условия хранения описаны в обзоре Interactions.

Отправьте запрос через Ofox Chat Completions

Создайте или выберите ключ по инструкции настройки и использования API-ключа и сохраните его как OFOX_API_KEY на сервере или в локальном терминале. Для macOS/Linux используйте export OFOX_API_KEY="YOUR_OFOX_KEY", для PowerShell — $env:OFOX_API_KEY="YOUR_OFOX_KEY", подставив значение локально. Перед запуском проверьте баланс и текущую страницу модели Hydrogen на английском. Бесплатная квота Google не оплачивает запросы Ofox, а баланс Ofox — обращения к конечной точке Google.

Полный снимок публичного каталога содержал 133 модели, включая google/gemini-4-hydrogen. Это подтверждает запись и заявленные протоколы на дату проверки, но не успешную генерацию и не одинаковое поведение всех аккаунтов, провайдеров или будущих конфигураций.

Сохраните запрос в hydrogen-ofox-request.json:

{
  "model": "google/gemini-4-hydrogen",
  "messages": [
    {
      "role": "user",
      "content": "Give exactly three short bullet points about avoiding duplicate API retries."
    }
  ],
  "max_tokens": 65536,
  "stream": false
}

Отправьте его из терминала с помощью curl:

curl --silent --show-error --fail-with-body --max-time 900 \
  'https://api.ofox.ai/v1/chat/completions' \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @hydrogen-ofox-request.json \
  --output hydrogen-ofox.json

Запрос соответствует документации Ofox по Chat Completions и параметрам. При последующей настройке OpenAI-совместимого SDK не дублируйте /v1: базовый URL — https://api.ofox.ai/v1, а полный REST-адрес дополнительно содержит /chat/completions.

В примере намеренно отсутствуют temperature, top_p и специфичные для провайдера расширения рассуждения. Нативный объект Google generation_config не является параметром OpenAI Chat Completions. Не вставляйте его в запрос, предполагая, что шлюз автоматически передаст его дальше. Для настройки рассуждения через конкретный путь Ofox сначала проверьте документированное соответствие параметров. Таблица четырёх нативных уровней ниже не доказывает поддержку произвольного совместимого поля.

Ненулевой код завершения curl означает ошибку HTTP или передачи. Прочитайте сохранённое тело ошибки, удалив ключи перед передачей журналов другим людям. Тайм-аут — ограничение ожидания клиента, а не прогноз задержки. Не запускайте сразу серию повторных платных запросов после тайм-аута: прекращение ожидания клиентом не доказывает остановку обработки у провайдера.

Проверьте ответ с учётом протокола

HTTP 200 может содержать незавершённую интеракцию, вызов инструмента или результат без полезного текста. При этом корректный ответ покажется пустым, если читать поля другого API. SDK Google предоставляет удобное свойство interaction.output_text, но сохранённый ресурс использует steps. Chat Completions использует choices.

Сохраните полный проверяющий скрипт в check_hydrogen.py. Он читает только локальный файл, не обращается к сети и не повторяет генерацию.

import json
import sys
from pathlib import Path

def validate(payload, route):
    if "error" in payload:
        raise ValueError("API error: " + json.dumps(payload["error"]))
    if route == "google":
        if payload.get("status") != "completed":
            raise ValueError("Interaction is not completed: " + str(payload.get("status")))
        text = "".join(
            part.get("text", "")
            for step in payload.get("steps", [])
            if step.get("type") == "model_output"
            for part in step.get("content", [])
            if part.get("type") == "text"
        )
    elif route == "ofox":
        choices = payload.get("choices") or []
        if not choices:
            raise ValueError("No Chat Completions choices in response")
        choice = choices[0]
        if choice.get("finish_reason") != "stop":
            raise ValueError("Text did not finish normally: " + str(choice.get("finish_reason")))
        text = (choice.get("message") or {}).get("content") or ""
    else:
        raise ValueError("Route must be google or ofox")
    if not isinstance(text, str) or not text.strip():
        raise ValueError("No usable text; inspect the saved JSON")
    return text

def main():
    if len(sys.argv) != 3:
        raise SystemExit("Usage: python check_hydrogen.py google|ofox response.json")
    payload = json.loads(Path(sys.argv[2]).read_text(encoding="utf-8"))
    try:
        text = validate(payload, sys.argv[1])
    except ValueError as exc:
        raise SystemExit(str(exc))
    print("Response ID:", payload.get("id"))
    print("Usage:", json.dumps(payload.get("usage")))
    print(text)

if __name__ == "__main__":
    main()

Для Google выполните python check_hydrogen.py google hydrogen-google.json, для Ofox — python check_hydrogen.py ofox hydrogen-ofox.json. При успехе выводятся ID ответа, usage и текст. Прочитайте текст и убедитесь, что в нём ровно три коротких уместных пункта. Скрипт проверяет завершение протокола и непустой текст, но не фактическую правильность совета модели.

Мы проверили логику локально на синтетических завершённых, пустых, ошибочных, незавершённых и инструментальных ответах, включая текст в нескольких выходных шагах Google. Это подтверждает поведение проверки, а не реальную аутентификацию, квоту, задержку или качество. Причина завершения tool_calls может быть корректной для приложения с инструментами; этот текстовый тест её отклоняет, поскольку окончательного ответа ещё нет.

Выберите усилие рассуждения отдельно от длины ответа

Нативный API Hydrogen поддерживает четыре уровня рассуждения. Значение по умолчанию — high; у Carbon и Argon — medium. Документация Google по thinking описывает усилия на рассуждение, а не фиксированное число слов.

Это отправные точки для тестов, а не результаты бенчмарка Ofox. Сравнивайте уровни на одинаковых входных данных и критериях приёмки. Фиксируйте точную модель, уровень, статус, время, usage и причину успеха или отказа. Меняйте по одной настройке. Более короткий видимый ответ не доказывает меньший расход токенов рассуждения.

Hydrogen разделяет 1 048 576 токенов между вводом, рассуждением и выводом. Это не миллион входных токенов плюс отдельный миллион для ответа. Стандартный синхронный бюджет рассуждения и вывода составляет 65 536; такой предел поддерживается одним ответом как с потоковой передачей, так и без неё. Более длинные ответы требуют продолжения или фонового выполнения, описанных в Long Decode.

Не устанавливайте миллион выходных токенов для первого теста. При последующем фоновом выполнении сохраняйте ID задачи и явно обрабатывайте ожидающие и конечные состояния. Само по себе background=true не увеличивает стандартный предел вывода. Это руководство проверяет короткий запрос в переднем плане, а не реализует диспетчер длительных задач.

Hydrogen генерирует текст. Карточка модели перечисляет изображения, видео, аудио и PDF на входе, но не нативную генерацию изображений, аудио или поддержку Live API. Анализ изображения и создание нового изображения — разные возможности. Добавляйте поддерживаемый тип ввода после успешной базовой проверки текста.

Исправляйте сбой на соответствующем уровне

Сохраняйте вместе конечную точку, строку модели, проект или аккаунт, версию SDK и точную ошибку. Удаляйте учётные данные перед передачей записи. Если неверно одно поле, не нужно пересобирать всю интеграцию.

Для Ofox используйте руководство обработки ошибок, для Google — официальный справочник устранения неполадок. Разбор ошибок API Argon тоже показывает разделение ошибок подключения, квоты и парсинга, но его настройки конкретной модели не являются стандартами Hydrogen.

При добавлении инструментов объявляйте их через нативные поля выбранного API. Просьба в промпте напечатать самодельный формат вызова не означает, что исполнитель инструментов его распознает. Сохраняйте требуемую историю разговора и подписи. Если ошибка связана именно с подписью, воспользуйтесь диагностикой отсутствующей thought signature.

Сохраните воспроизводимую базовую конфигурацию

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

Затем добавьте одно изменение: реальный рабочий промпт, поддерживаемый файл, потоковую выдачу или объявленный инструмент. Если новая версия не работает, повторите исходный тест. Так можно отличить регрессию доступа от проблемы новой функции.

Если следующую сложную задачу предполагается передать Carbon, сравните модели по руководству выбора Gemini 4. Другие условия доступа и настройки первого вызова Carbon разобраны в руководстве подключения Carbon API. Успешный запрос Hydrogen подтверждает работоспособность вашей интеграции, но не возможность без изменений перенести аккаунт, параметры и парсер в любой другой сервис.