Gemini 4 Neon API 사용법: 모델 ID, 사고 수준, 첫 요청 검증까지
Gemini API 유료 프로젝트에서 gemini-4-neon을 호출하는 방법입니다. high와 xhigh 사고 수준 선택, 사고 토큰과 캐시 토큰 사용량 확인, Carbon과 다른 오류 해결법을 정리합니다.
Gemini 4 Neon을 호출하려면 유료 등급 Gemini API 프로젝트에서 model: "gemini-4-neon"을 보내면 됩니다. Neon에는 무료 등급이 없습니다. 기본 사고 수준은 high이며 low, medium, xhigh도 받습니다. 입력, 사고, 출력은 하나의 1,048,576토큰 컨텍스트 창을 함께 씁니다. Google의 Neon 가이드는 새 코드를 Interactions API로 시작하지만 generateContent도 동작합니다. 요청이 성공했다고 볼 수 있는 것은 interaction이 completed 상태이고(또는 candidate가 STOP으로 끝나고), 보이는 텍스트가 있으며, 사고 토큰을 포함해 청구될 내용이 사용량 기록에 나타날 때뿐입니다.
Google은 2026년 11월 18일 gemini-4-neon을 정식 버전(GA)으로 출시했습니다. 이 가이드는 2026년 11월 19일 기준 Google 문서와 대조했습니다. Neon에만 해당하는 내용에 집중합니다. 프로젝트 설정, API 키, 결제는 다른 유료 Gemini 4 모델과 같으므로 Gemini 4 Carbon API 설정 가이드에서 한 번 자세히 다루었고, 여기서는 요약만 합니다.
이 글에는 두 가지 한계가 있습니다.
- Neon은 Ofox에서 사용할 수 없습니다. 2026년 11월 19일 Ofox 모델 목록(
GET https://api.ofox.io/v1/models)을 확인한 결과,google/gemini-4-hydrogen과google/gemini-4-argon은 있었지만 Neon은 없었고https://ofox.io/models/google/gemini-4-neon은 404를 반환했습니다. 아래 예제는 모두 Google 네이티브 엔드포인트와 Google API 키를 사용합니다. 이 블로그는 Ofox가 발행합니다. - Neon을 실제로 호출하지는 않았습니다. 이 가이드를 쓸 때 Google 키가 없었습니다. 요청 본문은 Google이 공개한 명세(Neon 가이드, Interactions 및
generateContent레퍼런스, 사고·캐싱·긴 출력 문서)와 대조했습니다. 응답 검사기는 합성 응답 15개로 오프라인 테스트했습니다. 이것으로 파서 로직은 검증되지만 인증, 지연 시간, 답변 품질은 검증되지 않습니다.
Gemini 4 Neon API 핵심 사양
아래 값은 모두 Google의 What’s new in Gemini 4 Neon 가이드, 가격 페이지, Neon 모델 카드(모두 영어)에서 가져왔으며 2026년 11월 19일에 확인했습니다.
| 항목 | Neon 값 |
|---|---|
| 모델 ID | gemini-4-neon(-preview 접미사 없음) |
| 이용 조건 | Gemini API 유료 등급만 가능. Google AI Pro·Ultra 요금제에서는 Google AI Studio에서도 사용 가능 |
| API | Interactions API(Google 빠른 시작에서 사용)와 generateContent |
| 사고 수준 | low, medium, high(기본값), xhigh. minimal은 거부됨 |
| 컨텍스트 | 1,048,576토큰. 입력, 사고, 출력이 공유 |
| 동기 출력 | hop(한 번의 생성 구간)당 기본값과 상한 모두 65,536토큰. 스트리밍·비스트리밍 공통 |
| 더 긴 출력 | 백그라운드 실행 또는 클라이언트 측 이어쓰기. 최대 1M에서 입력을 뺀 양 |
| 표준 가격(100만 토큰당 USD) | 입력 $3.00, 캐시 입력 $0.15, 출력(사고 포함) $15.00 |
| 캐싱 | 암시적 캐싱만 지원. 프롬프트 4,096토큰부터 적용. 명시적 cachedContents는 미지원 |
| 샘플링 | temperature, top_p, top_k는 범위 안이면 무시, 범위 밖이면 400 반환 |
| 지식 기준일 | 2026년 3월(모델 카드) |
Carbon에는 11월 30일에 끝나는 출시 기념 가격이 있지만 Neon에는 없습니다. 사고 수준별 작업당 비용은 Gemini 4 Neon 가격 분석을 참고하세요.
Carbon, Hydrogen 요청과 무엇이 다른가
Google은 다른 Gemini 4 모델에서 Neon으로 전환할 때 “요청 스키마를 변경할 필요가 없다”고 밝혔습니다. 필드는 그대로이고, 바뀌는 것은 값과 그 주변의 제한입니다. 이미 Carbon이나 Hydrogen 설정 가이드대로 동작하는 코드가 있다면 다음 차이를 반영해야 합니다.
| 영역 | Carbon | Hydrogen | Neon |
|---|---|---|---|
| 모델 ID | gemini-4-carbon | gemini-4-hydrogen | gemini-4-neon |
| 무료 등급 | 없음 | 있음 | 없음 |
| 기본 사고 수준 | medium | high | high |
xhigh | 미지원 | 지원 | 지원 |
| 비스트리밍 hop | 원시 REST 호출 시 hop당 32,768토큰 | 65,536 | 65,536 |
| 샘플링 파라미터 | 무시 | 범위 안은 무시, 범위 밖은 400 | 범위 안은 무시, 범위 밖은 400 |
| 표준 가격(입력/출력) | 11월 30일까지 $2 / $10, 이후 $4 / $20 | $1.50 / $7.50 | $3 / $15 고정 |
출처: Carbon, Hydrogen, Neon 각각의 “What’s new” 가이드와 Choosing a model 페이지(영어). 32,768과 65,536 hop 비교는 Google의 Hydrogen 가이드에 나와 있습니다.
실무에서는 세 가지 결과로 이어집니다.
- Carbon에서 옮기면 호출당 기본 지출이 늘어납니다. Carbon의 기본값은
medium, Neon은high입니다.thinking_level을 한 번도 지정하지 않은 코드는 아무것도 바꾸지 않아도 Neon에서 더 많이 사고합니다. 코드 리뷰에서 동작이 보이도록 수준을 명시적으로 지정하세요. - Hydrogen에서 옮길 때는 요청이 아니라 키 때문에 실패할 수 있습니다. Hydrogen 연동은 무료 등급 프로젝트에서 돌아가고 있을 수 있는데, 같은 키로는 Neon에 접근할 수 없습니다. 페이로드를 디버깅하기 전에 키가 어느 프로젝트에 속하는지 먼저 확인하세요.
- Neon용으로 작성한 코드는 Carbon에서 실패할 수 있습니다.
xhigh는 Neon과 Hydrogen에서는 유효하지만 Carbon과 Argon에서는 유효하지 않습니다. 단계별로 모델을 나눠 쓴다면 사고 수준을 전역 상수로 두지 말고 라우팅의 일부로 관리하세요. 각 모델이 언제 제값을 하는지는 Neon과 Carbon 비교에서 다룹니다.
1단계: 키가 유료 프로젝트에 속하는지 확인하기
Neon을 쓰려면 네 가지가 맞아야 합니다. Gemini API를 사용할 수 있는 Google 계정, Google AI Studio의 프로젝트, 그 프로젝트에 속한 API 키, 그리고 같은 프로젝트에서 활성화된 유료 등급 결제입니다. Google 결제 가이드는 무료 등급에서 유료 등급으로 옮기는 것을 프로젝트에 결제 계정을 연결하는 작업으로 설명하며, Projects 페이지에서 각 프로젝트의 결제 등급을 볼 수 있습니다. Google AI Pro나 Ultra 요금제가 있으면 AI Studio에서 Neon을 쓸 수 있지만, 그것을 API 키의 프로젝트가 유료 등급이라는 증거로 여기지는 마세요. 프로젝트 등급은 Projects 페이지에서 확인하세요.
단계별 설명(Cloud 프로젝트 가져오기, 키 유형과 제한, 선불과 후불)은 Carbon 설정 가이드의 첫 번째 섹션에 있으며 Neon에도 그대로 적용됩니다. Google 원문 자료는 API 키 가이드와 결제 가이드(모두 영어)입니다.
키는 환경 변수에 두고, 값을 출력하지 않은 채 로드되었는지만 확인합니다.
export GEMINI_API_KEY="..." # 셸이나 시크릿 관리자에서 설정하고, 절대 커밋하지 마세요
python3 -c 'import os; print("Key configured:", bool(os.environ.get("GEMINI_API_KEY")))'
True는 값이 존재한다는 뜻일 뿐입니다. 프로젝트가 Neon에 접근할 수 있는지는 첫 요청으로 확인합니다.
2단계: Interactions API로 첫 요청 보내기
Google의 Neon 빠른 시작은 Interactions API를 사용하므로 새 코드는 여기서 시작하세요. 현재 SDK를 설치합니다(패키지 이름은 google-genai, 가져오기는 from google import genai이며, 예전 google-generativeai 패키지가 아닙니다).
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade google-genai
다음 코드를 neon_first_call.py로 저장합니다.
import json
import os
from pathlib import Path
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
interaction = client.interactions.create(
model="gemini-4-neon",
input="List exactly three checks for confirming a new API integration works.",
store=False,
generation_config={
"thinking_level": "low",
"max_output_tokens": 65536,
},
)
Path("neon-response.json").write_text(
json.dumps(interaction.model_dump(mode="json"), indent=2), encoding="utf-8"
)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
print(interaction.output_text)
이 요청에는 의도적으로 정한 설정이 세 가지 있습니다.
thinking_level: "low": 접근 확인 비용을 낮춥니다. 지정하지 않으면 Neon은high로 사고합니다.low로 경로를 확인한 다음, 실제 워크로드에 필요한 수준을 설정하세요(5단계).max_output_tokens: 65536: Neon 문서상의 기본값이자 hop당 상한입니다. 사고와 보이는 출력을 합친 상한일 뿐, 청구액 예측이 아닙니다. Google은 예전 앱의 8,192 같은 낮은 상한을 그대로 가져오지 말라고 권합니다. 비용을 줄이고 싶다면 사고 수준을 낮추세요.store=False: 이번 일회성 호출을 저장 대상에서 제외합니다.background=True나previous_interaction_id를 쓸 예정이라면 저장을 켜 둔 채(기본값) 두세요. 둘 다 저장된 interaction이 필요합니다. 유료 등급에서 Google은 저장된 interaction을 55일간 보관합니다.
같은 요청을 REST로 쓰면 다음과 같습니다. 실제로 무엇이 전송되는지 확인할 때 유용합니다.
curl --silent --show-error --max-time 900 \
"https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-neon",
"input": "List exactly three checks for confirming a new API integration works.",
"store": false,
"generation_config": {
"thinking_level": "low",
"max_output_tokens": 65536
}
}' \
--output neon-response.json
Interactions API에서 generation_config 안의 필드 이름은 Python, JavaScript, REST 모두 snake_case입니다. output_text는 SDK가 제공하는 편의 속성입니다. 원시 REST 응답에서는 텍스트가 유형이 model_output인 steps 항목 안, 유형이 text인 content 항목에 들어 있습니다.
--max-time을 900초로 둔 것은 어려운 프롬프트에는 최소 15분을 확보하라는 Google의 마이그레이션 권고를 따른 것입니다. 간단한 프롬프트를 low로 보내면 훨씬 빨리 돌아와야 합니다. 클라이언트에서 시간 초과가 나더라도 서버는 요청을 처리(그리고 청구)했을 수 있으니, 확인하기 전에 자동 재시도를 걸지 마세요.
3단계: 클라이언트가 이미 generateContent를 쓴다면 그대로 써도 됩니다
generateContent는 Neon에서도 계속 지원됩니다. 애플리케이션이 이미 candidates를 파싱하고 있다면 모델 문자열과 사고 설정만 바꾸면 될 수도 있습니다. 표기 방식이 다르다는 점에 주의하세요. generateContent REST는 camelCase를 씁니다.
curl --silent --show-error --max-time 900 \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-4-neon:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role": "user", "parts": [{"text": "List exactly three checks for confirming a new API integration works."}]}],
"generationConfig": {
"thinkingConfig": {"thinkingLevel": "low"},
"maxOutputTokens": 65536
}
}' \
--output neon-response.json
Python SDK에서는 다음과 같습니다.
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-neon",
contents="List exactly three checks for confirming a new API integration works.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(thinking_level="low"),
max_output_tokens=65536,
),
)
print(response.text)
print("Thinking tokens:", response.usage_metadata.thoughts_token_count)
Google의 사고 가이드(영어)에 따라 두 형식 모두 수준 값은 소문자 문자열("low", "xhigh")입니다. 두 API를 섞지 마세요. generation_config.thinking_level은 Interactions 본문에, generationConfig.thinkingConfig.thinkingLevel은 generateContent 본문에 들어갑니다. 두 API 사이에서 코드를 복사한 뒤 400이 나면 필드 구조부터 확인하세요. 예전 thinkingBudget(thinking_budget)도 제거하세요. Gemini 4에서는 지원 중단되었고, 사고 수준과 함께 보내면 400이 반환됩니다.
코드 경로마다 API를 하나만 선택하세요. Interactions API는 서버 측 상태(previous_interaction_id)와 백그라운드 실행을 제공합니다. generateContent에서는 기록을 직접 관리해야 하며, 이전 모델 턴을 사고 서명(thought signature)까지 포함해 변경 없이 다시 보내야 합니다.
4단계: 호출을 믿기 전에 상태, 텍스트, 사용량 확인하기
HTTP 200만으로는 부족합니다. interaction이 completed가 아닌 상태로 돌아올 수 있고, generateContent의 candidate가 사고에 예산을 모두 쓰고 MAX_TOKENS로 끝날 수도 있습니다. 두 경우 모두 보이는 텍스트가 전혀 없을 수 있습니다. Google의 긴 출력 가이드(영어)는 Interactions 상태별 조치를 다음과 같이 안내합니다.
| 상태 | 의미 | 조치 |
|---|---|---|
queued, in_progress | 아직 실행 중(백그라운드 호출) | 같은 id로 interactions.get을 폴링 |
completed | 완료 | model_output 텍스트를 이어 붙이고 usage 확인 |
requires_action | 모델이 도구 호출을 요청함 | 도구를 실행하고 이 id로 결과 전송 |
requires_continuation | 포그라운드 hop이 65,536 상한에 도달했지만 예산이 남음 | SDK는 기본적으로 자동 이어쓰기. REST에서는 previous_interaction_id와 continuation_token을 붙여 다음 hop 전송 |
incomplete | max_output_tokens를 모두 사용함. 텍스트가 비어 있을 수 있음 | 이어서 실행하거나 max_output_tokens를 높여 다시 전송 |
failed | 서버가 완료하지 못함 | 한 번 재시도. 다시 실패하면 지원 문의용으로 id 보관 |
cancelled | 직접 취소함 | usage에서 청구된 내용 확인 |
generateContent에서는 finishReason 값이 이에 해당합니다. STOP은 성공, MAX_TOKENS는 상한 도달, CONTINUATION은 다음 hop이 필요하다는 뜻입니다(최신 SDK는 자동으로 이어 갑니다).
아래 검사기는 두 API 중 어느 쪽에서 저장한 응답이든 읽습니다. 네트워크 호출을 하지 않으며 재시도도 하지 않습니다.
import json
import sys
from pathlib import Path
PENDING = {"queued", "in_progress"}
def check_interaction(p):
status = p.get("status")
if status in PENDING:
raise ValueError(f"Still {status}: poll interactions.get with this id later")
if status != "completed":
raise ValueError(f"Interaction status is {status}, not completed (see the status table)")
text = "".join(
c.get("text", "")
for s in p.get("steps", [])
if s.get("type") == "model_output"
for c in s.get("content", [])
if c.get("type") == "text"
)
u = p.get("usage") or {}
usage = {
"input": u.get("total_input_tokens"),
"cached_input": u.get("total_cached_tokens"),
"output": u.get("total_output_tokens"),
"thinking": u.get("total_thought_tokens"),
"tool_use": u.get("total_tool_use_tokens"),
"total": u.get("total_tokens"),
}
return text, usage
def check_generate_content(p):
cands = p.get("candidates") or []
if not cands:
reason = (p.get("promptFeedback") or {}).get("blockReason")
raise ValueError(f"No candidates (prompt block reason: {reason})")
c = cands[0]
reason = c.get("finishReason")
if reason != "STOP":
raise ValueError(f"finishReason is {reason}, not STOP")
text = "".join(
part.get("text", "")
for part in (c.get("content") or {}).get("parts", [])
if not part.get("thought")
)
u = p.get("usageMetadata") or {}
usage = {
"input": u.get("promptTokenCount"),
"cached_input": u.get("cachedContentTokenCount", 0),
"output": u.get("candidatesTokenCount"),
"thinking": u.get("thoughtsTokenCount"),
"tool_use": u.get("toolUsePromptTokenCount", 0),
"total": u.get("totalTokenCount"),
}
return text, usage
def check(payload):
if "error" in payload:
raise ValueError("API error: " + json.dumps(payload["error"]))
if "candidates" in payload or "promptFeedback" in payload:
text, usage = check_generate_content(payload)
elif "status" in payload or "steps" in payload:
text, usage = check_interaction(payload)
else:
raise ValueError("Unrecognised response shape")
if not text.strip():
raise ValueError("Completed, but no visible text")
return text, usage
if __name__ == "__main__":
path = sys.argv[1] if len(sys.argv) > 1 else "neon-response.json"
payload = json.loads(Path(path).read_text(encoding="utf-8"))
try:
text, usage = check(payload)
except ValueError as exc:
raise SystemExit(str(exc))
print("Usage:", json.dumps(usage))
print(text)
python3 check_neon.py neon-response.json을 실행합니다. 통과하면 정규화된 사용량 한 줄과 보이는 답변이 출력됩니다. 그다음 답변 자체도 읽어 보세요. 관련 있는 확인 항목 세 개가 있어야 하며, 거절이나 중간에 잘린 문장이어서는 안 됩니다.
테스트한 내용. 위에 실린 검사기를 그대로 손으로 작성한 픽스처 15개에 실행했습니다. 텍스트가 두 개의 model_output 단계에 나뉘어 있고 사고 단계가 하나 있는 완료된 interaction, 같은 interaction을 google-genai SDK의 Interaction 모델과 model_dump(mode="json")에 통과시킨 버전(2단계에서 저장하는 형태), in_progress, incomplete, requires_action, requires_continuation, failed 상태와 완료되었지만 텍스트가 빈 interaction, API 오류 본문, 그리고 generateContent 응답으로 STOP(제외해야 할 사고 파트 포함), MAX_TOKENS, CONTINUATION, MALFORMED_FUNCTION_CALL로 끝난 것, 차단된 프롬프트, 사고만 있는 답변입니다. 형식이 올바른 성공 사례 3개는 통과했고 나머지 12개는 예상한 메시지로 종료되었습니다. 픽스처는 문서에 나온 필드 이름을 따랐으며, 실제로 수집한 Neon 출력은 아닙니다.
Neon에서 중요한 사용량 필드
Neon의 두 가지 비용 요인인 사고와 캐시 적중은 사용량 기록에 드러납니다.
| 의미 | Interactions usage | generateContent usageMetadata |
|---|---|---|
| 입력 토큰 | total_input_tokens | promptTokenCount |
| 캐시 적중 입력 | total_cached_tokens | cachedContentTokenCount |
| 보이는 출력 | total_output_tokens | candidatesTokenCount |
| 사고 | total_thought_tokens | thoughtsTokenCount |
| 도구 사용 프롬프트 토큰 | total_tool_use_tokens | toolUsePromptTokenCount |
| 합계 | total_tokens | totalTokenCount |
필드 이름은 Google의 Interactions 및 generateContent API 레퍼런스(모두 영어)에서 가져왔습니다. Google 레퍼런스의 예시(Neon이 아닌 이전 모델)는 사고가 보이는 출력과 따로 보고된다는 것을 보여 줍니다. 한 문장 답변에서 출력 23토큰과 함께 사고 49토큰이 기록되었습니다. Neon에서 사고는 출력 단가인 $15.00로 청구됩니다. Google은 사고를 포함해 모델이 처리하는 모든 토큰을 계산하며, 그라운딩을 쓰면 내부 시스템 지침과 함수 선언도 포함됩니다. 그래서 high나 xhigh에서는 보이는 답변이 짧아도 출력 요금이 크게 나올 수 있습니다. 호출마다 thinking과 output을 나란히 기록하세요. 청구액이 이상해 보일 때 가장 먼저 볼 것이 이 두 값입니다.
5단계: 작업별로 사고 수준 고르기
Google 가이드는 네 가지 수준을 대략 이렇게 설명합니다(요약).
| 수준 | Google의 설명 | 대표 용도 |
|---|---|---|
low | 토큰이 가장 적고 지연 시간이 가장 짧음 | 빠른 채팅, 대량 처리, 저비용 접근 확인 |
medium | 토큰 사용이 적고 응답이 빠름 | 대화형 코딩, UI 프로토타이핑, 지연에 민감한 도구 호출 |
high(기본값) | 지능과 속도의 균형 | 대부분의 복잡한 코딩, 에이전트 실행, 멀티모달 지식 작업 |
xhigh | 토큰이 가장 많고 추론이 가장 깊음 | 어려운 다단계 엔지니어링, high로 부족한 분석·과학 문제 |
Google이 권하는 방법은 상한 때문에 답이 잘리지 않도록 max_output_tokens를 높게 잡고 네 수준 모두로 작업을 평가한 뒤, 품질 기준을 충족하는 가장 낮은 수준을 쓰는 것입니다. xhigh를 요청하는 방법은 다음과 같습니다.
interaction = client.interactions.create(
model="gemini-4-neon",
input="Audit this retry queue for race conditions and rewrite the lock logic.",
generation_config={"thinking_level": "xhigh"},
)
Neon에 특히 해당하는 주의 사항이 두 가지 있습니다.
xhigh와 65,536 상한은 서로 영향을 줍니다. 이 상한은 사고와 출력을 합친 양에 적용됩니다. Google의 사고 가이드는 텍스트나 JSON 추출 같은 단순한 프롬프트에서xhigh가 과하게 사고해max_output_tokens를 다 써 버릴 수 있다고 경고합니다.MAX_TOKENS나 보이는 텍스트가 거의 없는incompleteinteraction이 나오면 먼저 작업을 살펴보세요. 단순한 작업이면 수준을 낮춥니다. 정말 어려운 작업이면 수준은 유지하고, 백그라운드 실행과 더 큰max_output_tokens로 여유를 주세요(아래 백그라운드 실행 섹션 참고). 비용을 아끼려고max_output_tokens를 줄이지는 마세요. Google에 따르면 그렇게 하면 답이 잘리고, 이미 진행된 사고에 대한 비용은 그대로 청구됩니다.- Google의 비용 주장은 특정 수준에서 측정된 것입니다. Google의 Neon 발표에 따르면 기본값인
high에서 Neon은 Artificial Analysis Intelligence Index에서 높은 점수를 내면서 작업당 비용은 Carbon보다 32% 낮았고, Neon의 가장 높은 지능 점수는xhigh에서 나왔습니다. Google은 이 32%를 AA Intelligence Index와 연결하지만, Carbon의 어떤 사고 수준, 어떤 요금 기간, 어떤 AA 데이터 스냅숏과 비교했는지는 밝히지 않습니다. 2026년 11월 19일에 확인한 AA 수치로는 32%가 재현되지 않으며, 비교 내용은 Neon 요금 분석에 정리했습니다. 이는 Google이 발표한 벤치마크 결과이지 여러분의 워크로드에 대한 예측이 아닙니다. 위의 사용량 필드로 자신의 작업을 직접 측정하세요.
previous_interaction_id는 대화 기록만 이어 갑니다. generation_config, tools, system_instruction은 이어지지 않으므로, thinking_level 없이 보낸 후속 턴은 Neon 기본값인 high로 돌아갑니다. 턴마다 수준을 다시 보내세요.
cachedContents 대신 암시적 캐싱 사용하기
Neon은 암시적 캐싱만 지원합니다. caches.create로 캐시를 만들거나 cached_content를 보내는 코드를 옮겨 온다면 해당 필드를 제거하세요. Google 캐싱 가이드에 따르면 명시적 캐싱은 Interactions API에서도, Gemini 4 모델에서도 지원되지 않습니다.
암시적 캐싱은 4,096토큰 이상인 프롬프트에 자동으로 적용됩니다. 적중한 부분은 입력 100만 토큰당 $3.00가 아닌 $0.15로 청구되어 95% 할인됩니다. 적중을 강제할 수는 없지만 Google의 캐싱 가이드(영어)는 확률을 높이는 두 가지 방법을 제시합니다.
- 크고 공통된 내용(시스템 지침, 저장소 구조도, 참고 문서)은 프롬프트 앞부분에, 요청마다 달라지는 질문은 끝에 둡니다.
- 같은 접두사를 가진 요청은 시간 간격을 좁혀 보냅니다.
멀티턴 채팅과 에이전트 루프에 대해 Google은 Gemini 4 전용 규칙을 덧붙입니다. 새 요청이 최소 2,050토큰을 추가해야(모델 출력, 사고, 함수 결과 포함) 이전 요청 전체가 캐시됩니다. 추가분이 그보다 적으면 이전 요청의 마지막 2,050토큰이 표준 입력 요금으로 다시 처리됩니다. Google은 대부분의 에이전트 턴이 이 기준을 넘는다고 설명합니다.
그런 다음 추측이 아니라 데이터로 확인하세요. 긴 접두사를 공유하는 두 번째 이후 요청에서는 total_cached_tokens(Interactions) 또는 cachedContentTokenCount(generateContent)가 0이 아니어야 합니다. 계속 0이라면 맨 앞에 넣고 있을지 모르는 타임스탬프나 요청 ID까지 포함해, 접두사가 바이트 단위로 같은지 확인하세요.
64K보다 긴 출력: 백그라운드 실행
Neon의 동기 응답 한 번은 사고와 출력을 합쳐 65,536토큰에서 멈춥니다. 긴 명세서, 대규모 리팩터링 계획, 전체 테스트 스위트처럼 긴 결과물에는 Google이 백그라운드 실행을 권합니다.
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-neon",
input="Write a complete migration specification and test plan for this service.",
background=True,
generation_config={"max_output_tokens": 262144, "thinking_level": "high"},
)
while interaction.status in ("queued", "in_progress"):
time.sleep(5)
interaction = client.interactions.get(id=interaction.id)
# 64K 단위 이어쓰기 hop 전체의 텍스트를 이어 붙입니다.
text = "".join(
content.text
for step in interaction.steps
if step.type == "model_output"
for content in step.content
if content.type == "text"
)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
print(text)
서버가 64K 단위 hop으로 이어서 생성하기 때문에 텍스트는 여러 model_output 단계에 나뉘어 도착합니다. 모두 이어 붙이세요(위 검사기도 같은 방식입니다). 백그라운드 interaction은 최대 24시간 실행될 수 있으며, failed로 끝나면 상태 표대로 한 번 재시도합니다. 놓치기 쉬운 점이 두 가지 더 있습니다. max_output_tokens 없이 background만 설정하면 서버는 여전히 65,536토큰 후에 멈춥니다. 또 백그라운드 실행에는 저장이 필요하므로 store=False와 함께 쓰지 마세요. 상한은 1,048,576에서 입력 토큰 수를 뺀 값입니다. interaction을 저장할 수 없는 경우의 클라이언트 측 이어쓰기는 Google의 긴 출력 가이드(영어)에서 다룹니다.
자주 발생하는 Gemini 4 Neon API 오류와 해결법
무엇이든 바꾸기 전에 엔드포인트, 정확한 모델 ID, 프로젝트, SDK 버전, 전체 오류 본문(키 제외)을 기록하세요. 가장 먼저 실패한 계층부터 고칩니다.
| 증상 | Neon에서 가능한 원인 | 해결법 |
|---|---|---|
| Hydrogen에서는 되는 키로 접근 또는 할당량 오류 발생 | 키가 무료 등급 프로젝트에 속함. Neon은 유료 등급 전용 | 유료 결제가 활성화된 프로젝트의 키 사용(1단계) |
| 모델을 찾을 수 없음 | 오타, -preview 같은 임의의 접미사, 또는 Neon을 라우팅하지 않는 게이트웨이 | generativelanguage.googleapis.com에 gemini-4-neon 사용 |
thinking_level에서 400 | minimal 전송(Gemini 4에서 거부), Interactions와 generateContent 필드 구조 혼용, 또는 예전 thinkingBudget을 수준과 함께 전송 | low/medium/high/xhigh 사용, 필드 이름을 엔드포인트에 맞추기, thinkingBudget 제거 |
| 샘플링 파라미터로 400 검증 오류 | temperature, top_p, top_k가 범위를 벗어남 | 샘플링 파라미터 제거. 범위 안의 값도 어차피 무시됨 |
| 캐시 코드를 옮긴 뒤 요청 실패 | 예전 cached_content / cachedContents 참조가 남아 있음(명시적 캐싱 미지원) | 제거하고 암시적 캐싱에 맡기기 |
MAX_TOKENS, incomplete 또는 빈 텍스트 | 낮은 max_output_tokens를 사고가 다 써 버림 | 65,536으로 되돌리거나, 긴 작업은 백그라운드 실행을 쓰거나, 의도적으로 사고 수준 낮추기 |
MALFORMED_FUNCTION_CALL | 도구를 선언하지 않고 원시 텍스트 JSON으로 도구 호출을 내보내라고 모델에 지시함 | 함수 호출(function calling)로 도구를 선언하거나 구조화된 출력 사용 |
| 멀티턴 도구 사용 중 서명 오류 | 사고 서명이 누락되었거나 병렬 호출 사이에 복사됨 | previous_interaction_id를 쓰거나 이전 턴을 변경 없이 반환. 사고 서명 누락 오류 해결법 참고 |
| 어려운 프롬프트에서 클라이언트 시간 초과 | high/xhigh 추론에는 몇 분이 걸림 | HTTP 시간 제한을 15분 이상으로 늘리거나 백그라운드 실행 사용 |
| 429 | 유료 등급에도 속도 제한이 적용됨 | 동시 요청을 줄이고 백오프. 429 재시도 가이드(영어) 참고 |
대부분의 행은 Google의 Neon 마이그레이션 체크리스트에서 그대로 가져왔습니다. 형제 모델에서 라우팅, 할당량, 응답을 진단하는 실제 예시는 Gemini 4 Argon API 오류 해결 가이드를 참고하세요. 다만 그 글의 Argon 전용 값(기본 사고 수준, 선택 가능한 수준)은 Neon에 적용되지 않습니다. Carbon·Neon·Hydrogen의 오류(답이 비거나 잘리는 경우 포함)는 Gemini 4 Carbon·Neon·Hydrogen 오류 가이드에 정리했습니다.
Ofox로 Gemini 4 Neon을 호출할 수 있나요?
2026년 11월 19일 기준으로는 불가능합니다. Ofox 모델 목록에는 Gemini 4 Hydrogen과 Argon은 있었지만 Neon은 없었으며, Neon 모델 페이지 경로는 404를 반환했습니다. 위 코드를 Ofox Base URL로 향하게 하지 마세요. Interactions 엔드포인트와 Ofox 키는 서로 다른 시스템이고, 애초에 Neon으로 가는 경로가 없습니다.
나중에 다시 확인하려면 Ofox 모델 목록(Ofox 키로 GET https://api.ofox.io/v1/models)이나 ofox.ai/models에서 google/gemini-4-neon을 찾아보세요. 목록에 나타나면 해당 모델 페이지에 지원 프로토콜과 현재 가격이 표시됩니다. Ofox에서 Gemini 모델의 요청 형식은 Ofox Gemini API 문서에 있습니다. 엔드포인트와 인증은 그 문서를 따르고, 이 글의 Google 네이티브 코드가 그대로 동작하리라고 가정하지 마세요.
지금 Ofox에서 Gemini 4 모델이 필요하다면 Gemini 4 Hydrogen이 목록에 있으며, 설정 가이드에서 Ofox 경로도 다룹니다. Google이 벤치마크 비교 대상으로 삼은 경쟁 플래그십 모델과 Neon의 비교는 Gemini 4 Neon vs Claude Opus 5.5 vs GPT-6.2 Sol을 참고하세요.
첫 호출 검수 체크리스트
Neon 연동을 완료로 처리하기 전에, 비밀 정보가 없는 다음 기록을 남기세요.
- 모델 ID
gemini-4-neon, 엔드포인트, SDK 버전, 프로젝트 식별자. - 검사기를 통과한 저장된 응답 1개:
completed또는STOP, 비어 있지 않은 텍스트. - 사고 토큰과 캐시 입력 토큰을 따로 기록한 사용량 줄.
- 보낸
thinking_level과max_output_tokens. 기본값에 기대지 않고 코드에 명시한 값. - 겪은 오류와 그것을 고친 변경 사항.
이 기준선이 갖춰지면 도구, 긴 문서, 백그라운드 작업을 하나씩 추가하세요. 무언가 실패했을 때 새로 추가한 부분이 원인이라는 것을 알 수 있습니다.
관련 문서
- Ofox Gemini API 문서: Ofox에서 제공하는 Gemini 모델의 요청 형식
- Ofox 오류 처리 가이드: Ofox 경로에서 오류를 읽고 재시도하는 방법
- Ofox 속도 제한: 현재 기본 제한과 상향 요청 방법
- Google: What’s new in Gemini 4 Neon(영어): 공식 모델 가이드와 마이그레이션 체크리스트


