요약
Gemini 4 Hydrogen API는 Google의 Gemini API와 CometAPI 같은 지원되는 서드파티 게이트웨이를 통해 사용할 수 있습니다. 먼저 경로를 선택하세요: Google을 사용하면 공급자별 기능과 계정 제어를, CometAPI를 사용하면 통합 모델 게이트웨이 또는 OpenAI 호환 클라이언트를 활용할 수 있습니다. 작은 텍스트 요청부터 시작하고, 그다음 스트리밍, 대화 이력, 파일, 도구를 추가하세요.
Python 3.10 이상, 선택한 경로의 키, 그리고 gemini-4-hydrogen 접근 권한이 필요합니다. 선택 사항인 JavaScript 예시는 Node.js 22 이상을 사용합니다. 자격 증명은 튜토리얼 전반에 걸쳐 서버 환경에 보관하세요.
핵심 요점
- Gemini 4 Hydrogen API의 모델 ID는
gemini-4-hydrogen을 사용합니다. - Google과 CometAPI는 자격 증명과 과금이 분리되어 있습니다. 선택한 엔드포인트에 맞는 키를 사용하세요.
- 기본은 네이티브 GenerateContent로 시작하세요; 기존 챗 클라이언트에 맞을 때는 CometAPI의 OpenAI 호환 인터페이스를 사용하세요.
- 다중 턴 이력에는 서명 등 전체 모델 응답을 보관한 뒤 후속 응답이나 도구 결과를 반환하세요.
- 경로를 선택할 때 실제 토큰 사용량과 완료된 작업을 비교하세요. 표준 토큰-가격 예시는 가격 섹션에 있습니다.
Gemini 4 Hydrogen API란?
Google은 2026년 11월 12일에 Hydrogen을 소개했습니다. 이 API는 프롬프트와 지원되는 파일을 받아, 애플리케이션이 처리할 수 있는 생성 텍스트 또는 구조화된 함수 호출을 반환합니다. 모델을 직접 호스팅할 필요는 없습니다.
텍스트 전용 요청부터 시작해 반환된 텍스트, 종료 이유, 토큰 사용량을 확인한 후 도구나 파일을 추가하세요. 이 작업이 정상 동작하면, 전체 워크플로를 한 번에 만들기보다 대화 상태나 읽기 전용 비즈니스 도구를 추가하세요.
Gemini 4 Hydrogen API 사양
| 사양 | Google 문서화 모델 기능 |
|---|---|
| 모델 ID | gemini-4-hydrogen |
| 입력 | 텍스트, 이미지, 오디오, 비디오, 지원 문서 |
| 출력 | 텍스트(도구 사용 시 구조화된 함수 호출 파트 포함) |
| 통합 컨텍스트 예산 | 입력과 출력을 합산해 1,048,576 토큰 |
| 단일 포그라운드 출력 세그먼트 | 추론과 함수 호출 포함 최대 65,536 토큰 |
| 애플리케이션 기능 | 사고(Thinking) 수준 제어, 구조화 출력, 함수 호출 |
이는 모델의 기능이며, 모든 게이트웨이가 모든 공급자 기능을 노출함을 보장하지는 않습니다. 아래 예시는 표준 요청 필드와 짧은 포그라운드 생성을 사용합니다.
Google 공식 API vs CometAPI
두 경로 모두 Gemini 요청을 지원하지만, 엔드포인트, 자격 증명, 과금 시스템이 다릅니다. 공급자별 기능이 필요하면 Google을, 통합 게이트웨이나 기존 호환 클라이언트가 있으면 CometAPI를 사용하세요.
| 결정 기준 | Google Gemini Developer API | CometAPI Gemini 통합 |
|---|---|---|
| 네이티브 API 호스트 | generativelanguage.googleapis.com | api.cometapi.com |
| 이 가이드의 API 키 | GEMINI_API_KEY | COMETAPI_KEY |
| 계정 및 과금 | Google을 통해 관리 | CometAPI를 통해 관리 |
| 최적의 시작점 | Google 고유 기능 및 계정 제어 | 통합 모델 접근 또는 기존 OpenAI 호환 클라이언트 |
두 경로를 비교할 때는 프롬프트와 출력 예산을 동일하게 유지해야 결과 비교가 유의미합니다. JavaScript와 OpenAI 호환 예시는 명시적으로 CometAPI에 맞춰 구성되어 있습니다.
Gemini 4 Hydrogen API는 어떻게 단계별로 사용하나요?
1단계: API 키 만들기
CometAPI의 경우, 계정을 만들고 API 토큰 콘솔에서 키를 생성하세요. Google에 직접 접근하려면 Google AI Studio에서 Gemini API 키를 생성하세요. 모델 접근 권한과 선택한 계정의 과금 또는 사용 가능한 할당량을 확인하세요.
키는 안전하게 보관하세요. CometAPI 키로는 Google 엔드포인트에 인증할 수 없고, Google 키로는 CometAPI 요청을 인증할 수 없습니다.
선택한 경로에 해당하는 키를 Bash에서 설정하세요. 둘 중 하나만 필요합니다.
export COMETAPI_KEY="YOUR_COMETAPI_KEY"
# Or, for direct Google access:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
Windows에서는 PowerShell에서 해당 키를 설정하세요.
$env:COMETAPI_KEY = "YOUR_COMETAPI_KEY"
# Or, for direct Google access:
$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"
2단계: cURL로 첫 요청 보내기
Bash 터미널에서 CometAPI를 통해 네이티브 텍스트 요청을 전송하세요.
curl "https://api.cometapi.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $COMETAPI_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Explain how an AI coding agent works in five steps."
}
]
}
],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {
"thinkingLevel": "MEDIUM"
}
}
}'
또는 같은 네이티브 요청을 Google에 직접, Google API 키로 전송하세요.
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Explain how an AI coding agent works in five steps."
}
]
}
],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {
"thinkingLevel": "MEDIUM"
}
}
}'
요청이 성공하면 세 가지를 확인하세요: 가시 텍스트는 candidates[0].content.parts, 완료 상태는 finishReason, 토큰 사용량은 usageMetadata입니다. 더 많은 애플리케이션 코드를 추가하기 전에 인증 또는 요청 오류를 해결하세요.
3단계: Python 클라이언트 구성 및 요청 보내기
Python 예제에서 사용하는 패키지를 설치하세요.
python -m pip install requests openai
헬퍼를 hydrogen_client.py로 저장하세요. PROVIDER는 CometAPI의 경우 cometapi로 두고, 직접 Gemini Developer API를 쓰려면 google로 변경하세요. 이후 네이티브 예제는 이 파일을 import하여 선택한 경로를 유지합니다.
선택한 엔드포인트를 구성하고 재사용 가능한 요청/텍스트 헬퍼를 정의하세요.
import os
import requests
MODEL = "gemini-4-hydrogen"
PROVIDER = "cometapi" # Change to "google" for direct access.
ROUTES = {
"cometapi": ("https://api.cometapi.com", "COMETAPI_KEY"),
"google": ("https://generativelanguage.googleapis.com", "GEMINI_API_KEY"),
}
BASE_URL, KEY_NAME = ROUTES[PROVIDER]
API_KEY = os.environ[KEY_NAME]
URL = f"{BASE_URL}/v1beta/models/{MODEL}:generateContent"
def generate(payload):
response = requests.post(
URL,
headers={"x-goog-api-key": API_KEY},
json=payload,
timeout=120,
)
response.raise_for_status()
return response.json()
def visible_text(data):
candidates = data.get("candidates") or []
if not candidates:
raise ValueError("No candidate returned; inspect promptFeedback.")
candidate = candidates[0]
parts = candidate.get("content", {}).get("parts", [])
text = "".join(
part.get("text", "") for part in parts
if not part.get("thought", False)
)
if not text:
raise ValueError(
f"No visible text; inspect parts and finishReason: "
f"{candidate.get('finishReason')}"
)
return text
다음 내용을 hydrogen.py로 헬퍼와 같은 위치에 저장하세요. 이는 답변, 완료 이유, 사용량을 출력하여 토큰 한도로 중단된 출력과 완료된 답변을 구분할 수 있게 합니다.
구성된 공급자를 사용해 텍스트 요청을 전송하세요.
from hydrogen_client import generate, visible_text
data = generate({
"contents": [{"role": "user", "parts": [{
"text": "Explain API rate limiting in three sentences."
}]}],
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"},
},
})
print(visible_text(data))
candidate = data["candidates"][0]
print("Finish reason:", candidate.get("finishReason"))
print("Usage:", data.get("usageMetadata", {}))
선택한 API 키를 설정한 터미널에서 스크립트를 실행하세요.
python hydrogen.py
답변을 읽은 뒤, finishReason을 확인해 생성이 중단된 이유를 확인하세요. usageMetadata에서 요청이 사용한 토큰 수를 확인하세요. MAX_TOKENS는 HTTP 요청이 성공하더라도 응답이 불완전할 수 있음을 의미합니다.
JavaScript 또는 OpenAI 호환 클라이언트 사용
애플리케이션에 맞는 예제를 선택하세요. Node.js 예제는 네이티브 Gemini 요청을 전송합니다. 이미 OpenAI SDK를 사용 중이라면 아래 Python 예제로 이동하세요.
Node.js로 JavaScript 사용
다음을 hydrogen.js로 저장하고 node hydrogen.js를 실행하세요. 동일한 네이티브 요청 형태를 전송하고 모든 가시 텍스트 파트를 추출합니다.
Node.js에서 네이티브 GenerateContent 요청을 전송하세요.
const apiKey = process.env.COMETAPI_KEY;
if (!apiKey) throw new Error("Set COMETAPI_KEY before running this script.");
const baseUrl = "https://api.cometapi.com";
const model = "gemini-4-hydrogen";
async function main() {
const response = await fetch(
`${baseUrl}/v1beta/models/${model}:generateContent`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-goog-api-key": apiKey
},
body: JSON.stringify({
contents: [
{
role: "user",
parts: [
{
text: "Explain how an AI coding agent works."
}
]
}
],
generationConfig: {
maxOutputTokens: 4096,
thinkingConfig: {
thinkingLevel: "MEDIUM"
}
}
})
}
);
if (!response.ok) {
throw new Error(
`API error: ${response.status} ${await response.text()}`
);
}
const data = await response.json();
const candidate = data.candidates?.[0];
const text = (candidate?.content?.parts || [])
.filter(part => !part.thought)
.map(part => part.text || "")
.join("");
if (!text) {
throw new Error(`No visible text; finishReason=${candidate?.finishReason}`);
}
console.log(text);
}
main().catch(console.error);
OpenAI SDK를 사용하는 Python
애플리케이션이 이미 OpenAI SDK를 사용한다면, CometAPI는 POST /v1/chat/completions도 제공합니다. 가장 간단한 마이그레이션은 API 키, 기본 URL, 모델 ID를 변경하는 것입니다. 일반적인 챗 워크플로에는 이 경로를 사용하고, 공급자별 Gemini 필드가 필요할 때는 Gemini 네이티브 엔드포인트를 사용하세요.
CometAPI를 통해 Chat Completions 요청을 생성하세요.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1"
)
response = client.chat.completions.create(
model="gemini-4-hydrogen",
messages=[
{
"role": "user",
"content": "Explain how an AI coding agent works."
}
]
)
print(response.choices[0].message.content)
네이티브 예제는 contents와 generationConfig를 사용하고, Chat Completions는 messages와 자체 요청 필드를 사용합니다. 지원하지 않는 네이티브 필드를 SDK 호출에 섞어 넣지 말고, 각 요청은 하나의 형식을 유지하세요.
고급 Gemini 4 Hydrogen API 기능
다음 예제는 설정 섹션의 hydrogen_client.py를 재사용하므로, PROVIDER에 설정한 공급자에서 그대로 동작합니다. 아래 스트리밍 예제는 별도의 CometAPI Chat Completions 클라이언트를 사용하며, 기존 OpenAI 호환 애플리케이션에 적합합니다.
추론과 구조화 출력 구성
generationConfig에서 thinkingConfig.thinkingLevel을 LOW, MEDIUM, HIGH, XHIGH로 설정하세요. 추론과 가시 답변 모두에 여유가 있도록 출력 예산을 선택하세요. 애플리케이션이 JSON을 기대한다면, 자연어 포맷팅 요청에만 의존하지 말고 responseMimeType과 responseSchema를 사용하세요.
네이티브 요청의 출력 예산과 추론 수준을 설정하세요.
{
"generationConfig": {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"}
}
}
CometAPI를 통한 스트리밍
스트리밍은 완전한 답변을 기다리지 않고 생성된 콘텐츠를 점진적으로 반환합니다. 챗 인터페이스, 코딩 어시스턴트, 지연 체감이 중요한 애플리케이션에 유용합니다.
CometAPI 문서에는 stream=true로 Chat Completions 스트리밍이 설명되어 있습니다. 아래 Python 예제는 스트리밍 응답에서 발생할 수 있는 choices 없는 청크를 처리합니다.
OpenAI 호환 엔드포인트를 통해 도착하는 대로 텍스트를 출력하세요.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1"
)
stream = client.chat.completions.create(
model="gemini-4-hydrogen",
messages=[
{
"role": "user",
"content": (
"Write a Python function that validates an email "
"address and explain the main checks."
)
}
],
stream=True
)
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if delta and delta.content:
print(delta.content, end="", flush=True)
print()
네이티브 클라이언트의 경우, CometAPI 문서에는 Server-Sent Events로 streamGenerateContent가 설명되어 있습니다. 이 경로는 Chat Completions 델타가 아니라 GenerateContent 응답 객체를 반환합니다. 파서는 경로에 맞게 유지하세요. 네이티브 Gemini 엔드포인트와 OpenAI 호환 게이트웨이 간에 스트리밍 동작이 다를 수 있습니다. 기존 스트리밍 클라이언트를 마이그레이션하기 전에 애플리케이션에서 사용하는 정확한 Hydrogen 경로를 테스트하세요.
다중 턴 대화 이력 보존
다음 요청에 이전 사용자/모델 턴을 함께 전송하세요. 가시 텍스트만 재구성하지 말고 모델의 전체 content 객체를 보관해, 다음 턴을 위한 반환 메타데이터를 유지하세요. 예제를 hydrogen_history.py로 공유 헬퍼 옆에 저장하세요.
첫 번째 모델 응답 전체를 보존하면서 관련된 두 요청을 수행하세요.
from hydrogen_client import generate, visible_text
history = [{"role": "user", "parts": [{
"text": "Suggest a simple queue-based background job architecture."
}]}]
config = {
"maxOutputTokens": 4096,
"thinkingConfig": {"thinkingLevel": "MEDIUM"},
}
first = generate({"contents": history, "generationConfig": config})
print(visible_text(first))
candidate = first["candidates"][0]
if candidate.get("finishReason") != "STOP":
raise RuntimeError("The first turn did not finish normally.")
history.append(candidate["content"])
history.append({"role": "user", "parts": [{
"text": "Now identify three failure scenarios in that design."
}]})
second = generate({"contents": history, "generationConfig": config})
print(visible_text(second))
print("Finish reason:", second["candidates"][0].get("finishReason"))
python hydrogen_history.py를 실행하세요. 두 번째 답변은 첫 턴의 설계를 다루어야 합니다. 이 예제에서는 이전 대화 프리픽스를 변경하지 마세요. 장기간 실행 애플리케이션은 별도의 축약 및 컨텍스트 한도 정책이 필요합니다.
이미지와 PDF 전송
Hydrogen은 이미지 및 문서 이해를 지원합니다. Gemini 네이티브 요청 형식에서는 텍스트 지시와 함께 inlineData 파트를 추가하세요. 스크린샷 분석, 아키텍처 다이어그램, 스캔 양식, 보고서 추출에 유용합니다.
이 예제를 analyze_file.py로 hydrogen_client.py 옆에 저장하세요. 하나의 로컬 이미지 또는 PDF를 전송하므로 두 입력에 동일한 코드를 재사용할 수 있습니다. 첫 요청에는 작은 파일을 사용하세요. Base64는 요청 크기를 증가시킵니다.
공유 네이티브 클라이언트를 사용해 로컬 PNG, JPEG 또는 PDF를 분석하세요.
import base64
import sys
from pathlib import Path
from hydrogen_client import generate, visible_text
path = Path(sys.argv[1])
mime_types = {
".png": "image/png", ".jpg": "image/jpeg",
".jpeg": "image/jpeg", ".pdf": "application/pdf",
}
mime_type = mime_types.get(path.suffix.lower())
if mime_type is None:
raise ValueError("Choose a PNG, JPEG, or PDF file.")
data = generate({
"contents": [{"role": "user", "parts": [
{"text": "Summarize this file and identify the key findings."},
{"inlineData": {
"mimeType": mime_type,
"data": base64.b64encode(path.read_bytes()).decode("ascii"),
}},
]}],
"generationConfig": {"maxOutputTokens": 4096},
})
print(visible_text(data))
자신의 문서나 이미지를 사용해 파일 예제를 실행하세요.
python analyze_file.py report.pdf
python analyze_file.py diagram.png
파일 바이트는 선언된 MIME 타입과 일치해야 합니다. 파일 확장자를 바꾼다고 파일이 변환되지는 않습니다. 업로드가 거부되면 다시 시도하기 전에 크기 또는 형식 제한에 대한 오류를 확인하세요. Google에 호스팅된 파일 URI가 서드파티 게이트웨이를 통해 접근 가능하다고 가정하지 마세요.
애플리케이션 제어 도구 연결
함수 호출을 통해 모델이 애플리케이션이 수행하는 작업을 요청할 수 있습니다. 모델은 구조화된 함수 호출을 반환하고, 애플리케이션은 인자를 검증한 후 함수를 실행하고 결과를 다시 보냅니다.
이 예제는 작고 가상의 주문 데이터베이스를 사용합니다. 공유 클라이언트 옆에 order_agent.py로 저장하세요. 왕복을 구현하고, 루프를 최대 네 번으로 제한하며, 반환된 서명을 포함해 모델의 전체 content를 턴 사이에 보존합니다.
로컬 데모 데이터베이스에 대해 제한된 함수 호출 루프를 실행하세요.
from hydrogen_client import generate, visible_text
orders = {"DEMO-1001": {"status": "shipped", "carrier": "Example Carrier"}}
tools = [{"functionDeclarations": [{
"name": "lookup_order",
"description": "Retrieve a demonstration order by its order ID.",
"parameters": {
"type": "OBJECT",
"properties": {"order_id": {"type": "STRING"}},
"required": ["order_id"],
},
}]}]
history = [{"role": "user", "parts": [{
"text": "Use lookup_order to check the status of DEMO-1001."
}]}]
for _ in range(4):
data = generate({
"contents": history,
"tools": tools,
"generationConfig": {"maxOutputTokens": 4096},
})
candidates = data.get("candidates") or []
if not candidates or not candidates[0].get("content"):
raise RuntimeError("No model content returned.")
model_content = candidates[0]["content"]
calls = [
part["functionCall"] for part in model_content.get("parts", [])
if "functionCall" in part
]
if not calls:
print(visible_text(data))
break
history.append(model_content) # Preserve all parts and signatures.
results = []
for call in calls:
args = call.get("args", {})
order_id = args.get("order_id") if isinstance(args, dict) else None
if call.get("name") != "lookup_order":
raise ValueError("Unexpected function name.")
if not isinstance(order_id, str) or not order_id:
raise ValueError("order_id must be a non-empty string.")
result = orders.get(order_id, {"error": "Order not found"})
reply = {"name": call["name"], "response": result}
if "id" in call:
reply["id"] = call["id"]
results.append({"functionResponse": reply})
history.append({"role": "user", "parts": results})
else:
raise RuntimeError("Tool-call limit reached before a final answer.")
python order_agent.py를 실행하세요. 최종 답변은 DEMO-1001의 로컬 레코드를 반영해야 합니다. 실제 서비스에서는 주문에 접근하기 전에 사용자를 인가하세요. 모델이 선택한 주문 ID가 권한의 증거는 아닙니다.
Gemini 4 Hydrogen API 가격은 얼마인가요?
아래 요율은 2026년 11월 17일 기준 USD/백만 토큰입니다. 배치, 우선순위, 캐시된 입력, 별도 과금되는 도구 사용이 아닌, 표준 비캐시 입력/출력을 비교합니다.
| 토큰 유형 | Google Global Standard | CometAPI의 Gemini 4 Hydrogen API |
|---|---|---|
| 입력 토큰 / 100만 | $1.50 | $1.20 |
| 출력 토큰 / 100만 | $7.50 | $6.00 |
입력 토큰 100,000개와 과금 대상 출력 토큰 10,000개의 경우, CometAPI 추정치는 0.1 × $1.20 + 0.01 × $6.00 = $0.18입니다. 동일 볼륨을 Google의 표준 요율로 계산하면 $0.225로, 20% 차이입니다. 출력 사용량에는 추론 토큰이 포함되므로, 실제 워크플로를 추정할 때 계정의 과금 사용량을 확인하세요.
Gemini 4 Hydrogen API로 어떻게 마이그레이션하나요?
Gemini 3.8 Flash에서 무엇이 달라지나요?
모델 ID를 바꾸기 전에 추론 설정, 컨텍스트 예산, 클라이언트가 각 요청에 함께 보내는 대화 이력을 확인하세요.
| 통합 세부사항 | Gemini 3.8 Flash | Gemini 4 Hydrogen |
|---|---|---|
| 기본 사고 수준 | MEDIUM | HIGH |
| 컨텍스트 산정 | 입력과 출력 제한이 분리됨 | 입력/출력을 하나의 통합 예산으로 산정 |
| 다중 턴 상태 | 기존 클라이언트의 이력 처리를 검토 | 모델의 전체 파트와 서명을 보존; 프리픽스 편집은 별도 처리 필요 |
문서화된 마이그레이션 변경 사항은 애플리케이션이 기본값에 의존하거나 이력을 축약하거나 여러 도구 턴을 수행할 때 특히 중요합니다. 추론을 명시적으로 설정하고, 프로덕션 모델을 변경하기 전에 짧은 기존 워크플로를 테스트하세요.
기존 통합 업데이트
새 모델 ID로 테스트 구성을 만들되, 해당 키와 엔드포인트는 함께 유지하세요. 두 구성 모두 같은 대표 워크플로를 실행해 동작을 비교하세요.
- 새로운 텍스트 요청을 보내고 완료 이유와 토큰 사용량을 확인하세요.
- 완전한 모델 응답 객체를 사용해 다중 턴 작업과 도구 왕복을 재현하세요.
- 한계 섹션에 나열된 비호환 제어를 제거한 후 요청 결과를 비교하세요.
- 롤백 경로를 새로운 대화에서 점검하세요. 다른 모델이 Hydrogen의 저장된 추론 메타데이터를 수용한다고 가정하지 마세요.
마이그레이션이 워크로드에 도움이 되는지 결정
작업의 품질과 지연 목표를 충족하고, 완료된 작업당 허용 가능한 비용이라면 새 구성을 채택하세요. 현재 클라이언트가 이미 목표를 충족한다면, 모든 요청을 이전하기 전에 제한된 파일럿으로 이점을 입증하세요. 평가 중에는 프롬프트, 입력, 채점 기준을 일관되게 유지하세요.
Gemini 4 Hydrogen API 제한 사항
Hydrogen 개발자 가이드에는 기존 클라이언트에 영향을 주는 제한이 설명되어 있습니다. 동일한 거부 페이로드를 재시도하기보다 요청 구성에서 이를 해결하세요.
- 지원되지 않는 필드: thinkingBudget, MINIMAL로 설정된 thinkingLevel, frequencyPenalty, presencePenalty, 1보다 큰 candidateCount를 제거하세요.
- 무시되는 샘플링 설정: 사용자 정의 temperature, topP, topK는 Hydrogen 출력에 영향을 주지 않습니다.
- 캐싱: 명시적 cachedContent는 지원되지 않습니다. 안정적인 프롬프트 프리픽스는 암묵적 캐싱을 사용할 수 있으나, 게이트웨이별 캐시 할인은 보장되지 않습니다.
- 긴 출력: 이 가이드의 샘플 클라이언트는 동기 요청만 구현합니다. 백그라운드 긴 디코드나 공급자별 연속 워크플로는 다루지 않습니다.
- 대화 변경: 이전 프롬프트나 도구 정의를 수정하면 추론 상태가 무효화될 수 있습니다. 프리픽스를 보존하거나 선택한 경로의 문서화된 프리픽스 불일치 동작을 구현하세요.
일반 설정 점검
| 증상 | 첫 점검 사항 |
|---|---|
| 401 또는 403 | 자격 증명이 엔드포인트에 해당하고 선택한 모델에 접근 권한이 있는지 확인하세요. |
| 400 | 오류 본문을 읽고, 지원되지 않는 필드, 잘못된 JSON, 대화 메타데이터를 점검하세요. |
| 가시 텍스트 없음 | promptFeedback, candidate parts, finishReason을 확인하세요. 응답이 차단되었거나, 불완전하거나, 도구를 요청 중일 수 있습니다. |
| MAX_TOKENS | 텍스트가 불완전할 수 있다고 보고, 수용 전에 출력 예산을 검토하세요. |
| 파일 요청 거부 | 실제 MIME 타입과 선택한 경로의 페이로드 한도를 확인하세요. |
예상치 못한 장애가 발생하면 모델, 경로, 상태, 타임스탬프, 요청 ID(가능한 경우)를 기록하세요. 일상 로그에는 API 키와 민감한 파일 내용을 남기지 마세요.
자주 묻는 질문(FAQ)
Gemini 4 Hydrogen API 레이트 리밋 오류는 어떻게 재시도해야 하나요?
HTTP 429의 경우 동시성을 줄이고 지터가 있는 지수 백오프로 재시도하되, 최대 시도 횟수는 고정하세요. 게이트웨이가 제공하는 경우 요청 ID를 보관하세요. 잘못된 요청이나 인증 실패는 그대로 재시도하지 마세요. CometAPI의 오류 및 재시도 가이드는 일시적 실패와 이를 구분합니다. 타임아웃은 처리 시작 후 발생할 수 있으므로, 애플리케이션 측 작업의 중복 실행을 방지하세요.
웹 앱에서 Gemini 4 Hydrogen API를 직접 호출해도 되나요?
요청은 반드시 여러분의 백엔드를 통해 라우팅하세요. 프런트엔드 JavaScript에 포함된 키는 코드가 번들되거나 최소화되어 있어도 방문자가 추출할 수 있습니다. 백엔드가 사용자 인증, 사용량 제한 적용, 모델 요청 전송을 담당하게 하세요. 스트리밍의 경우, 업스트림 API 키를 노출하지 않고 증가 응답을 브라우저로 중계하세요.
중단된 Gemini 4 Hydrogen 스트림은 어떻게 처리하나요?
응답이 완료될 때까지 수신한 텍스트를 부분 결과로 취급하세요. 새 요청은 새 생성을 시작하며, 동일 토큰에서 자동으로 중단된 스트림을 재개하지 않습니다. 부분 출력을 재시도 답변과 분리 보관하고, 불완전한 JSON이나 미완성 도구 인자에서 동작을 실행하지 마세요. 두 생성을 묵시적으로 이어붙이지 말고, 사용자에게 눈에 띄는 재시도 동작을 제공하세요.
결론
대표 작업을 첫 수용 기준으로 삼으세요: 요청이 성공하고, 애플리케이션이 의도한 결과를 추출하며, 기록된 토큰 사용량이 예산에 맞아야 합니다. 기능을 한 번에 하나씩 추가하고 이 검사를 통합 테스트에 포함하세요. 작은 단위로 관찰 가능한 클라이언트가, 실패 원인 추적이 어려운 큰 워크플로보다 확장하기 쉽습니다.

