Gemini 4 Hydrogen API 사용법: Google·Ofox 연결과 응답 검증

Google에 직접 요청할 때는 gemini-4-hydrogen과 Google API 키를 사용합니다. Ofox Chat Completions에서는 google/gemini-4-hydrogen과 Ofox 키를 사용합니다. 엔드포인트, 인증 정보, 응답 파서는 선택한 경로에 맞춰야 합니다. 프로토콜을 바꿀 때 모델 이름만 수정해서는 충분하지 않습니다.

Google은 2026년 11월 12일 개발자용 Hydrogen을 공개했습니다. 유료 등급에서만 API를 사용할 수 있는 Carbon과 달리 Hydrogen은 Google의 무료·유료 등급을 지원합니다. 다만 무료 이용은 프로젝트 자격, 인증 상태, 현재 한도에 따라 달라집니다. 이 글은 2026년 11월 13일 확인한 문서와 Ofox 카탈로그를 기준으로, 경로 선택부터 텍스트 응답 하나를 저장하고 검증하는 과정까지 안내합니다.

이 글은 Ofox가 발행합니다. 요청 형식을 확인하고 합성 데이터로 응답 검사 로직을 테스트했지만, 유료 Hydrogen 추론을 실행하거나 속도·답변 품질을 측정하지는 않았습니다. 예제는 독자가 실행할 수 있는 요청이며, 특정 계정의 실제 호출이 이미 성공했다는 주장이 아닙니다. 모델을 고르는 단계라면 Carbon·Hydrogen·Argon 비교를 참고하세요. 링크한 Google 원문 자료는 영어입니다.

키를 만들기 전에 연결 경로 선택하기

아래 두 예제는 서로 다른 서비스를 통해 같은 모델 계열에 접근합니다. 계정에 맞는 하나를 실행하면 됩니다. 튜토리얼을 끝내기 위해 두 경로를 모두 실행할 필요는 없습니다.

Google은 새로운 연동에 Interactions를 권장하며 GenerateContent도 계속 지원합니다. 현재 Ofox 공개 카탈로그는 Hydrogen에 OpenAI·Gemini 프로토콜을 표시하고, OpenAI 경로의 /v1/chat/completions를 명시합니다. 이 글은 그 경로를 사용합니다. Google Interactions 예제의 Base URL만 Ofox로 바꾸면 동작한다는 뜻은 아닙니다.

Ofox에는 Gemini 네이티브 프로토콜 문서도 있습니다. 이는 별도의 요청 규격입니다. 일반 프로토콜 문서에 명시적 캐시 같은 기능이 있다고 해서 모든 Gemini 모델이 지원하는 것은 아닙니다. 도구, 스트리밍, 멀티모달 입력을 추가하기 전에 프로토콜부터 정하세요.

2026년 11월 13일 캡처한 공식 발표입니다. 출시 사실을 보여 주며, API 테스트나 성능 측정 결과가 아닙니다. 영어 원문.

Google 프로젝트와 무료 등급 인증 준비하기

Google 예제를 사용하려면 AI Studio API 키 페이지에서 요청을 귀속시킬 프로젝트를 확인합니다. 신규 사용자는 기본 프로젝트를 받을 수 있고, 기존 Cloud 프로젝트는 AI Studio로 가져와야 할 수 있습니다. 원하는 프로젝트의 키를 생성하거나 선택한 다음, 해당 프로젝트의 등급과 남은 할당량을 확인하세요. 다른 프로젝트의 키도 인증에는 성공할 수 있지만, 사용하는 할당량이 달라집니다.

Hydrogen이 무료 등급에 제공된다고 해서 새 프로젝트가 모두 즉시 사용 가능한 것은 아닙니다. Google의 프로젝트 인증 안내는 추가 프로젝트나 AI Studio 외부에서 만든 프로젝트 등에 인증이 필요할 수 있다고 설명합니다. 해당 요청은 403과 FREE_TIER_VERIFICATION_REQUIRED를 반환합니다.

정확히 이 오류가 발생했다면 다음과 같이 처리합니다.

1. 오류의 인증 링크를 열거나 AI Studio Projects 페이지에서 Verify project를 선택합니다. 프로젝트 번호가 현재 키의 소속 프로젝트와 같은지 확인합니다.
2. 지원되는 실제 휴대전화로 Google 기기 인증을 진행합니다. 필요한 프로젝트 권한이 없다면 관리자에게 인증을 요청하세요.
3. 인증 완료를 확인한 뒤 아래의 작은 요청을 한 번 다시 실행합니다.

같은 프로젝트에서 키를 새로 만들어도 프로젝트 단위 인증 요건은 사라지지 않습니다. 유료 결제 설정은 별도 비용이 발생하는 대안이며 모든 Hydrogen 사용자에게 필수인 첫 단계가 아닙니다. 일반적인 403만 보고 결제를 변경하지 말고 구체적인 원인을 먼저 읽으세요.

AI Studio의 현재 속도 제한을 확인합니다. Google은 키가 아닌 프로젝트 단위로 제한하며, 요청 수와 토큰 제한은 서로 다른 시점에 걸릴 수 있습니다. 한 프로젝트의 키 두 개가 독립된 할당량 두 개를 만들지는 않습니다. 모든 계정에 적용되는 무료 RPM 수치는 제시하지 않습니다. 프로젝트와 모델에 실제로 표시되는 한도를 사용하세요.

키는 서버 환경 변수 GEMINI_API_KEY 또는 배포 환경의 비밀 관리 서비스에 보관합니다. 브라우저 코드나 저장소에 넣지 마세요. 현재 키 문서는 승인 키와 표준 키를 구분합니다. AI Studio에서 새로 만든 키는 기본적으로 승인 키입니다. 제한 없는 표준 키는 거부되지만, 제한을 명시한 표준 키는 계속 사용할 수 있습니다.

아래 프로그램은 GEMINI_API_KEY를 명시적으로 읽습니다. 두 환경 변수가 동시에 있으면 GOOGLE_API_KEY를 우선하는 SDK 자동 선택을 피하기 위해서입니다. macOS/Linux에서는 export GEMINI_API_KEY="YOUR_GOOGLE_KEY", PowerShell에서는 $env:GEMINI_API_KEY="YOUR_GOOGLE_KEY"를 사용합니다. 로컬 터미널에서 값을 바꾸고 공유 셸 기록에 키를 남기지 마세요. 설정한 터미널 세션에서 프로그램도 실행해야 합니다.

Python으로 Google 요청 보내기

현재 SDK에는 Python 3.11 이상을 사용하고 격리 환경을 만듭니다. 로컬 검사는 Python 3.11과 google-genai 3.3.0으로 수행했으며, 패키지가 선언한 최소 Python 버전도 3.11입니다. 이전 google-generativeai가 아닌 google-genai를 사용합니다.

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 키를 만들거나 선택하고 서버 또는 로컬 터미널의 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.io/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은 한 번만 들어가야 합니다. Base URL은 https://api.ofox.io/v1이며, 전체 REST 주소에는 /chat/completions가 추가됩니다.

예제는 temperature, top_p, 공급자별 사고 확장 필드를 의도적으로 생략합니다. Google 네이티브 generation_config는 OpenAI Chat Completions 파라미터가 아닙니다. 붙여 넣으면 게이트웨이가 전달할 것이라고 가정하지 마세요. 특정 Ofox 경로에서 사고를 설정하려면 해당 경로에 문서화된 파라미터 매핑을 먼저 확인합니다. 아래 네이티브 4단계 표는 임의의 호환 필드가 작동한다는 증거가 아닙니다.

curl 종료 코드가 0이 아니면 HTTP 또는 전송 작업이 실패한 것입니다. 저장된 오류 본문을 확인하고 로그 공유 전 키를 제거하세요. 타임아웃은 클라이언트의 대기 상한이지 응답 시간 예측이 아닙니다. 타임아웃이 발생해도 공급자 처리가 멈췄다는 뜻은 아니므로 유료 요청을 즉시 연속 재전송하지 마세요.

사용한 프로토콜에 맞춰 응답 검증하기

HTTP 200에도 미완료 상호작용, 도구 요청, 사용할 텍스트가 없는 결과가 담길 수 있습니다. 반대로 다른 API의 필드를 읽으면 정상 응답도 비어 보입니다. Google SDK는 편의 속성 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가 올바른 종료 이유일 수 있지만, 이 텍스트 전용 검사에서는 최종 답변이 없으므로 실패로 처리합니다.

사고 노력과 출력 길이를 구분하기

Hydrogen 네이티브 API는 네 가지 사고 수준을 지원합니다. 기본값은 high이고 Carbon과 Argon은 medium입니다. Google 사고 문서가 설명하는 것은 추론 노력이지 고정 글자 수가 아닙니다.

이는 테스트 시작점이며 Ofox 벤치마크 결과가 아닙니다. 수준을 비교할 때 입력과 통과 기준을 같게 유지하세요. 정확한 모델, 수준, 응답 상태, 시간, usage, 통과·실패 이유를 기록합니다. 한 번에 하나만 변경하세요. 보이는 답변이 짧다고 사고 토큰도 적다는 뜻은 아닙니다.

Hydrogen은 입력·사고·출력에 1,048,576토큰을 공유합니다. 입력 백만과 별도 출력 백만을 제공하는 것이 아닙니다. 기본 동기식 사고·출력 예산은 65,536이며 스트리밍 여부와 관계없이 단일 응답이 이 한도를 지원합니다. 더 긴 출력에는 Long Decode 문서의 이어받기 또는 백그라운드 실행이 필요합니다.

첫 검사부터 출력 상한을 백만으로 설정하지 마세요. 이후 백그라운드 실행을 사용한다면 작업 ID를 보관하고 대기 상태와 최종 상태를 명시적으로 처리합니다. background=true만 설정해서는 기본 출력 상한이 늘지 않습니다. 이 튜토리얼은 짧은 포그라운드 요청을 검증하며, 장시간 작업 제어기를 구현하지는 않습니다.

Hydrogen의 출력은 텍스트입니다. 모델 카드에는 이미지·동영상·오디오·PDF 입력이 있지만 네이티브 이미지 생성, 오디오 생성, Live API 지원은 나열되어 있지 않습니다. 이미지를 읽고 분석하는 것과 새 이미지를 생성하는 것은 다릅니다. 텍스트 기준 동작을 확인한 뒤 지원 입력을 하나 추가하세요.

실패한 계층부터 문제 해결하기

진단 기록에는 엔드포인트, 모델 문자열, 프로젝트 또는 계정, SDK 버전, 정확한 오류를 함께 남깁니다. 공유 전 인증 정보는 삭제하세요. 필드 하나가 틀렸다고 전체 구성을 다시 만들 필요는 없습니다.

Ofox 응답은 Ofox 오류 처리 안내, Google 분류는 공식 문제 해결 문서를 참고하세요. Argon API 오류 가이드도 경로·할당량·파싱 문제를 구분하는 예시지만, 모델별 설정은 Hydrogen 기본값이 아닙니다.

도구를 추가할 때는 선택한 API의 네이티브 도구 필드로 선언하세요. 프롬프트에서 임의의 호출 형식을 출력하라고 요구하는 것만으로 실행기가 인식하지는 않습니다. 프로토콜에 필요한 대화 기록과 서명을 유지해야 합니다. 서명이 구체적인 원인이라면 thought signature 누락 진단을 참고하세요.

재현 가능한 기준 설정 남기기

저장된 응답, 올바른 완료 신호, 세 항목 요구를 충족하는 텍스트, 의도한 프로젝트 또는 계정의 usage 기록이 있으면 다음 기능을 추가할 준비가 된 것입니다. 모델, 경로, SDK 버전, 설정도 함께 기록하고 비밀 정보는 제외하세요.

이후 실제 작업 프롬프트, 지원 파일 입력, 스트리밍, 선언된 도구 중 하나만 추가합니다. 새 버전이 실패하면 기존 기준 테스트를 다시 실행하세요. 연결 자체의 회귀와 새 기능에서 생긴 문제를 구분할 수 있습니다.

더 어려운 작업을 Carbon에 맡길지 판단하려면 Gemini 4 모델 선택 가이드를 보세요. Carbon의 별도 접근 요건과 첫 호출 설정은 Carbon API 연결 가이드에 있습니다. Hydrogen 호출 성공은 현재 통합의 증거이지, 계정·파라미터·파서를 모든 서비스에 그대로 옮길 수 있다는 증거는 아닙니다.