Gemini 4 Argon은 Free tier에서 호출할 수 없다. 결제 계정을 연결해 유료 티어로 올린 다음, google-genai SDK의 client.interactions.create에 model="gemini-4-argon"을 넘겨 호출한다. 이 Gemini 4 Argon API 사용법 개발자 가이드는 Gemini API로 이 모델을 처음 붙이는 개발자와, 기존 Gemini 모델 코드를 Argon으로 옮기려는 개발자를 대상으로 한다.
기존 코드를 모델 문자열만 바꿔 옮기면 문제가 생긴다. 명시적 컨텍스트 캐싱 호출은 지원되지 않고, temperature·top_p·top_k는 무시된다. 마이그레이션 항목은 별도 절에서 정리했다. 모든 내용은 2026-10-24 기준 Google 공식 문서를 근거로 한다.
목차
Gemini 4 Argon 적용 대상과 지원 범위
Gemini 4 Argon 모델 사양 페이지에 따르면 모델 코드는 gemini-4-argon이고 버전은 Stable이다. 페이지의 최신 업데이트 표기는 October 2026이다.
Google Cloud의 Gemini 4 Argon 출시 공지(2026-10-14 게시)는 제공 경로를 넷으로 적는다. Gemini platform의 API(모델 ID gemini-4-argon), Google AI Studio, Google Antigravity, 그리고 웹·데스크톱·모바일의 Gemini for business다. 이 글은 그중 Gemini API 호출만 다룬다.
입력은 Text, Image, Video, Audio, PDF를 받고 출력은 Text만 낸다. 토큰 한도는 다음처럼 읽어야 한다.
- 컨텍스트 창: 입력, thinking, 출력이 1,048,576 토큰짜리 창 하나를 같이 쓴다.
- 최대 출력: 동기 호출 기본값은 65,536이다.
- long decode: background 실행을 쓰면 최대 1,048,576까지 늘어난다.
지원 기능은 모델 페이지의 Capabilities 표 기준으로 아래와 같다.
| 구분 | 항목 |
|---|---|
| 지원 | Thinking(low, medium, high), Function calling, Structured outputs, Code execution, File search, URL context |
| 지원 | Search grounding, Grounding with Google Maps |
| 조건부 지원 | Caching(Implicit only), Computer use(Preview), Agentic video understanding(defaults to static) |
| 소비 옵션 | Batch API, Flex inference, Priority inference |
| 미지원 | Live API, Image generation, Audio generation |
확인된 버전은 모델 버전(Stable)뿐이다. Interactions API를 쓰는 SDK의 최소 버전은 이 글의 출처 범위에서 확인하지 않았으므로, 설치할 때 -U 옵션으로 최신 패키지를 받는 쪽을 기준으로 한다.
시작 전 준비: 유료 티어, API 키, SDK

준비는 결제 → 키 → SDK 순서로 진행한다. Gemini 4 Argon 신규 기능 안내에는 "Gemini 4 Argon is not available on the Free tier."라는 문장이 있다. 키와 SDK만 준비하고 결제를 건너뛰면 Argon 호출은 처리되지 않는다.
1단계: 유료 티어 결제 설정
Gemini API 결제 가이드에 따르면 새 계정은 Free Tier에서 시작하고, 새 사용자의 기본 결제 방식은 Prepay다. 설정 순서는 다음과 같다.
- AI Studio의 API keys 페이지나 Projects 페이지에서 Free Tier 프로젝트를 찾는다.
- 해당 행 Billing Tier 열의 ‘Set up billing’을 누른다.
- Google 결제 계정을 처음 만드는 경우 국가를 고르고 약관에 동의한다. 기존 결제 계정이 있으면 그중 하나를 선택한다.
- 연락처와 결제 수단을 입력한다.
마지막 단계를 마치면 계정 상태에 따라 결과가 셋으로 갈린다.
- 최소 $5를 선결제해야 설정이 끝나는 경우(Prepay)
- Prepay와 Postpay 중 하나를 고르는 경우
- 새 Prepay 시스템이 모든 사용자에게 적용될 때까지(2026-03-23 시작) 과도기적으로 Postpay가 배정되는 경우
Prepay 계정은 크레딧 잔액이 0보다 커야 요청이 처리된다. 원문 표현은 "The Gemini API will only serve requests if you have a positive Prepay credit balance."다.
확인 방법: Projects 페이지의 Billing Tier 열에서 프로젝트의 tier와 billing plan이 바뀌었는지 본다. AI Studio의 Billing 페이지에서도 상태를 확인한다.
2단계: API 키 발급과 환경변수 설정
Gemini API 빠른 시작 문서에 따르면 Google AI Studio는 새 사용자에게 프로젝트와 API 키를 자동으로 만들어 준다. API keys 페이지에서 그 키를 복사하면 된다. 별도 키가 필요하면 ‘Create API key’를 누르고 대화상자를 따라 키와 프로젝트 쌍을 추가한다.
키를 고를 때는 1단계에서 결제를 연결한 프로젝트의 키인지 확인한다. 키는 GEMINI_API_KEY 환경변수에 넣고, SDK는 언어에 맞게 설치한다.
export GEMINI_API_KEY="YOUR_API_KEY"
pip install -U google-genai
npm install @google/genai
확인 방법: 셸에서 echo $GEMINI_API_KEY로 값이 들어갔는지 보고, pip show google-genai로 패키지 설치 여부를 확인한다. 실제 인증 성공 여부는 다음 절의 첫 호출로 판단한다.
Gemini 4 Argon API 기본 호출과 thinking_level 설정
기본 호출은 클라이언트를 만들고 interactions.create에 model과 input을 넘기는 구조다. genai.Client()는 인자 없이 생성하며, 키는 앞 단계에서 넣은 환경변수를 쓴다. 아래 코드는 latest-model 페이지의 Python 예제 그대로다.
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-argon",
input="Write a three.js script that renders a realistic 3D black hole with gravitational lensing."
)
print(interaction.output_text)
output_text는 SDK가 제공하는 속성으로, 최종 응답 텍스트를 바로 꺼낸다. 출력이 비어 있지 않은 텍스트로 나오면 결제·키·SDK 설정이 모두 맞는 상태다.
thinking_level 고르기
Argon은 thinking 수준을 low, medium, high 중에서 고른다. 지정하지 않으면 medium이 기본값이다. 공식 표의 설명은 다음과 같다.
| 수준 | 특성 | 용도 |
|---|---|---|
low |
Fewest tokens, lowest latency | 지연 시간이 우선인 작업 |
medium (기본값) |
Balanced | Recommended for most tasks |
high |
Most tokens, slowest first token | Complex reasoning, hard math and science |
문서는 세 수준을 모두 실제 작업에 돌려 보라고 권한다("test your workload at all three"). 아래 helper는 같은 프롬프트를 수준별로 호출하고 토큰 사용량을 함께 출력한다. generation_config의 thinking_level 키는 long decode 공식 예제에 쓰인 형태를 따른다.
from google import genai
client = genai.Client()
def ask(prompt: str, level: str = "medium"):
# level: "low" | "medium" | "high"
return client.interactions.create(
model="gemini-4-argon",
input=prompt,
generation_config={"thinking_level": level},
)
prompt = "Write a three.js script that renders a realistic 3D black hole with gravitational lensing."
for level in ("low", "medium", "high"):
interaction = ask(prompt, level)
print(level, interaction.status)
print(interaction.usage) # ← 수준별 토큰 사용량 비교용
수준이 높을수록 thinking에 토큰을 더 쓰므로 출력 한도와 비용에 직접 영향을 준다. 출력 한도 문제는 바로 이어서 다룬다.
max_output_tokens 정하기
max_output_tokens는 thinking과 출력을 합친 양에 걸리는 hard limit이다. 합계가 이 값에 닿으면 응답이 그 자리에서 멈춘다. 공식 권장은 상황별로 이렇다.
- 일반 작업: 기본값 65,536을 유지하거나 값을 아예 지정하지 않는다.
- 32K 미만으로 설정해 둔 기존 앱: 최소 32,768로 올린다. Argon이 한도 중 더 많은 양을 thinking에 쓸 수 있기 때문이다.
- 64K를 넘는 출력이 필요한 작업: 다음 절의 long decode를 쓴다.
64K 토큰을 넘는 출력: Gemini long decode

동기 호출의 최대 출력은 65,536 토큰이다. 하나의 응답을 그보다 길게 받으려면 background 실행과 함께 max_output_tokens를 65,536보다 크게 지정한다. 이 경우 단일 응답이 최대 1M 토큰까지 이어진다.
복잡한 추론·코딩 작업의 권장 설정은 background: true와 max_output_tokens 131,072 또는 262,144다. 설정 가능한 상한은 1,048,576에서 입력 토큰 수를 뺀 값이다. 입력이 길수록 출력에 쓸 수 있는 공간이 줄어드는 구조다.
모델은 최대 64K 토큰짜리 hop 단위로 생성한다. 각 hop은 앞 hop이 멈춘 지점에서 이어지고, hop마다 interaction.steps에 model_output step이 하나씩 추가된다. 완료 후에는 모든 model_output step의 텍스트를 이어 붙여야 전체 응답이 된다.
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-argon",
input="Write a complete, rigorous proof of the prime number theorem.",
background=True,
generation_config={
"max_output_tokens": 262144,
"thinking_level": "high",
},
)
while interaction.status in ("in_progress", "queued"):
time.sleep(5)
interaction = client.interactions.get(id=interaction.id)
# Each hop adds a model_output step, so join the text of all of them.
text = "".join(
content.text
for step in interaction.steps
if step.type == "model_output"
for content in step.content
if content.type == "text"
)
print(text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
코드의 흐름은 세 부분으로 나뉜다. background=True로 작업을 시작하고, 상태가 in_progress 또는 queued인 동안 5초 간격으로 client.interactions.get을 호출한다. 루프를 빠져나오면 model_output step 중 type이 text인 content만 골라 합친다.
어려운 프롬프트는 응답까지 몇 분이 걸린다. 공식 권장은 background 실행을 쓰거나 HTTP 클라이언트 타임아웃을 최소 15분으로 잡는 것이다. 동기 호출로 긴 작업을 보내는 코드라면 타임아웃 값부터 점검한다.
성공 판정은 응답의 status, 텍스트 위치, usage 세 가지를 본다. 빠른 시작 문서의 REST 응답 예시(예제 모델은 gemini-3.8-flash)에 나오는 최상위 필드는 다음과 같다.
interaction (object: "interaction")
├── id
├── status ← 성공 시 "completed"
├── model
├── created
├── usage
│ ├── total_tokens
│ ├── total_input_tokens
│ └── total_output_tokens
└── steps[]
└── type == "model_output"
└── content[].text ← 응답 텍스트
REST로 직접 호출한다면 status가 "completed"인지 먼저 확인한다. 응답 텍스트는 steps 배열에서 type이 "model_output"인 step의 content[].text에 있다. output_text는 SDK 예제에서 쓰는 속성이므로, REST 응답 JSON에서 같은 이름의 필드를 찾을 필요는 없다.
SDK 사용 시에는 interaction.output_text로 최종 텍스트를 바로 확인한다. background 작업은 빠른 시작 문서의 예제처럼 interactions.get으로 폴링하면서 상태를 분기한다. 이 예제는 "completed"면 output_text를 출력하고, "failed"면 error를 출력한 뒤 루프를 끝낸다. long decode 예제를 실무에 옮길 때도 failed 분기를 두면 실패한 작업을 놓치지 않는다.
long decode는 폴링이 끝난 뒤 interaction.status와 interaction.usage를 출력해 확인한다. 이어 붙인 텍스트가 중간에서 끊겨 있다면 max_output_tokens 한도에 닿았을 가능성부터 본다. usage의 total_output_tokens와 지정한 한도를 비교하면 판단 근거가 된다.
결제 쪽 실패는 HTTP 상태 코드로 드러난다. Prepay 잔액이 $0이 되면 요청이 HTTP 402 Payment Required로 실패한다. 이 코드를 받았다면 코드 문제가 아니라 AI Studio Billing 페이지의 잔액을 확인할 차례다.
기존 모델에서 Gemini 4 Argon으로 옮길 때 바꿀 점
Gemini 4 Argon 마이그레이션 체크리스트는 여덟 항목으로 구성된다. 그중 두 항목은 기존 코드가 그대로는 기대대로 동작하지 않는 변경이다. 명시적 캐싱은 지원되지 않고, 샘플링 파라미터는 무시된다.
반드시 바꿀 항목
- 모델 ID 교체: 대상 모델 문자열을
gemini-4-argon으로 바꾼다. - 명시적 캐싱 제거: Argon은
cachedContents/caches.create방식의 explicit caching을 지원하지 않는다. 요청에서cached_content를 만들거나 참조하는 호출을 모두 뺀다. 대신 4,096 토큰 이상 프롬프트에는 implicit caching이 기본으로 켜지고, 캐시 적중 시 입력 토큰이 95% 할인된다. - 샘플링 파라미터 제거:
temperature,top_p,top_k는 요청에 넣어도 무시된다. 문서 권고는 요청에서 지우는 것이다. 이전 모델에서 이 값으로 출력 성향을 조정했다면, Argon에서는 그 조정이 적용되지 않는다는 점을 감안해 결과를 다시 검증한다.
검토할 항목
max_output_tokens재검토: 명시적으로 낮게 잡아 두었다면 최소 32,768로 올린다.- thinking 수준 설정:
low·medium·high를 작업에 맞춰 고르고 세 수준을 모두 테스트한다. - 긴 출력은 background로: 64K를 넘는 작업은
background를 true로,max_output_tokens를 65,536보다 크게 설정한다. - 클라이언트 타임아웃 상향: background를 쓰지 않는다면 HTTP 타임아웃을 15분 이상으로 잡는다.
- 대화 상태를 서버에 유지: 멀티턴과 function calling 대화는
previous_interaction_id로 상태를 이어 간다.
explicit caching을 전제로 비용을 계산해 둔 서비스라면 마이그레이션 후 비용 구조가 달라진다. Argon에서는 implicit caching만 적용되므로 `cached_content` 관련 코드를 제거하고, 4,096 토큰 이상 프롬프트의 캐시 적중 여부를 기준으로 비용을 다시 추정한다.
요금은 2026-12-01부터 2배로 오른다. Gemini API 가격 책정 페이지 기준, 100만 토큰당 단가는 다음과 같다. 출력 단가에는 thinking 토큰이 포함된다.
| 티어 | 입력 (~11-30 → 12-01~) | 출력 (~11-30 → 12-01~) | 캐싱 (~11-30 → 12-01~) |
|---|---|---|---|
| Standard | $2.00 → $4.00 | $10.00 → $20.00 | $0.10 → $0.20 |
| Batch | $1.00 → $2.00 | $5.00 → $10.00 | $0.05 → $0.10 |
| Flex | $1.00 → $2.00 | $5.00 → $10.00 | $0.05 → $0.10 |
| Priority | $3.60 → $7.20 | $18.00 → $36.00 | $0.18 → $0.36 |
캐싱 단가는 implicit caching에만 해당한다. Free Tier 항목은 Not available이며, 위 네 티어의 "Used to improve products" 표기는 No다.
그라운딩은 별도 과금이다. Grounding with Google Search와 Grounding with Google Maps 모두 월 5,000건까지 무료이고, 이후 1,000건당 $14다. 무료 5,000건은 Gemini 3 이상 모델 전체가 공유하는 한도라서, 다른 모델에서 이미 쓴 건수도 함께 차감된다.
Prepay 결제 계정의 크레딧 잔액이 $0에 닿으면 그 결제 계정에 연결된 모든 프로젝트의 API 키가 동시에 멈춘다. 크레딧을 추가할 때까지 모든 요청이 HTTP 402 Payment Required로 실패한다. 운영 서비스와 실험 프로젝트가 같은 결제 계정에 묶여 있다면 잔액을 넉넉히 유지하거나 결제 계정을 분리한다.
레이트 리밋(RPM/TPM)과 장문 입력에 대한 가격 구간은 이 글의 조사 범위에 들어 있지 않다. 두 항목은 적용 전에 공식 가격·한도 문서에서 따로 확인한다.
기본 호출 이후 이어서 다룰 주제
결제·키·기본 호출·long decode까지 갖췄다면 Gemini Interactions API의 대화 상태 관리가 다음 단계다. 마이그레이션 체크리스트가 권하는 previous_interaction_id로 멀티턴과 function calling 흐름을 서버 측에서 이어 가는 방식은 별도 주제로 정리할 만큼 분량이 있다.
비용 측면에서는 Gemini 4 Argon 가격 인상 이후 Batch·Flex 티어로 옮길 작업을 가려내는 일이 남는다. 오류 처리 측면에서는 Gemini API 402 Payment Required와 background 작업의 failed 상태를 함께 다루는 재시도 설계가 이어지는 주제이고, structured outputs와 Google Search 그라운딩을 Argon에 붙이는 방법도 google-genai SDK 기반 실습으로 연결된다.
관련 글
- Gemini 3.5 I/O 2026 신기능 7가지 — API 파라미터 변경과 마이그레이션 실무 가이드 – Google I/O 2026에서 발표된 Gemini 3.5 Flash의 핵심 변경 사항을 정리한다. temperature 파라미터 제거, …
- Gemini Live API 음성 챗봇 구현 — 3.1 Flash Live 오디오 스트리밍 실전 가이드 – Gemini 3.1 Flash Live 모델에 Python SDK로 연결하고, raw PCM 오디오를 송수신하며, VAD 설정과 Funct…
- Gemini 3.8 Live 사용법: 3.1 마이그레이션과 VAD·함수 호출 설정 – 모델 문자열만 gemini-3.8-live로 바꾸면 끝난다는 생각은 틀렸다. thinking_level 제거, proactive_audio…