구글은 2026년 9월 2일에 Gemini 3.8 Flash를 출시했으며, API 모델 ID는 미리보기 접미사 없이 일반 문자열 gemini-3.8-flash입니다. 이 모델은 2026년 12월 31일까지 3.7 Flash의 초기 가격인 백만 입력 토큰당 $0.75, 백만 출력 토큰당 $3.75를 유지합니다. 구글은 이를 "더 열심히 작동하는" 모델로 설명합니다. 즉, 복잡한 작업에서 더 많은 추론 단계를 거치고 도구를 더 자주 호출하여 토큰 요금 청구서에 반영됩니다.
이 가이드는 작동하는 통합을 위한 전체 경로를 다룹니다: AI 스튜디오에서 키를 얻는 방법, Interactions API(현재 Gemini 3.x의 구글 기본 API)를 통한 첫 요청 전송 방법, 대부분의 기존 코드가 여전히 사용하는 레거시 generateContent 동등 기능, 각 API에서 thinking_level의 위치, 스트리밍, 그리고 추론 비용이 예상치 못하게 발생하는 것을 방지하기 위해 thoughtsTokenCount를 읽는 방법까지 포함합니다. 모든 호출은 JSON을 사용하는 순수 HTTP이므로, 애플리케이션 코드에 통합하기 전에 Apidog에서 각각을 구축하고 확인할 수 있습니다.
모델 개요, 벤치마크 및 변경 사항에 대해서는 Gemini 3.8 Flash란 무엇인가를 먼저 참조하십시오. 구글의 출시 게시물에는 공식적인 설명이 담겨 있습니다.
Gemini 3.8 Flash API 한 눈에 보기
| 항목 | 값 |
|---|---|
| 모델 ID | gemini-3.8-flash |
| 기본 엔드포인트 | POST /v1beta/interactions |
| 레거시 엔드포인트 | POST /v1beta/models/gemini-3.8-flash:generateContent |
| 인증 헤더 | x-goog-api-key |
| 컨텍스트 / 출력 | 1,048,576 입력 토큰 / 65,536 출력 토큰 |
| 입력 | 텍스트, 이미지, 비디오, 오디오, PDF (텍스트 출력만 해당) |
| 추론 수준 | low, medium (기본), high; minimal은 오류 반환 |
| 가격 (2026년 12월 31일까지 초기) | 1백만 토큰당 $0.75 / $3.75; 2027년 1월 1일부터 $1.50 / $7.50 |
코드를 작성하기 전에 두 가지 세부 사항에 주목해야 합니다. 기본 추론 수준은 Gemini 3 Pro에서와 같이 high가 아니라 medium입니다. 그리고 추론 토큰은 공식 가격 책정 페이지에 따라 출력 요율로 청구되므로, 선택하는 수준은 품질뿐만 아니라 비용에 대한 결정이기도 합니다. 가격 분석은 작업당 숫자를 통해 설명합니다.
1단계: AI 스튜디오에서 API 키 얻기
Google AI Studio를 열고 Google 계정으로 로그인한 다음, 키 페이지에서 API 키를 생성하십시오. 이 키는 무료 등급에서 즉시 작동하며, 속도 제한이 있고 Google은 무료 등급 데이터가 "제품 개선에 사용된다"고 명시하고 있습니다. 프로덕션 제한을 위해 Tier 1으로 이동하려면 결제 계정을 연결하십시오.
키를 코드에 붙여넣는 대신 내보내십시오:
export GEMINI_API_KEY="AIza..."
공식 Python SDK는 환경에서 GEMINI_API_KEY를 읽으므로 genai.Client()에는 인수가 필요하지 않습니다. pip install google-genai로 설치하십시오.
2단계: Interactions API를 사용한 첫 호출
구글은 이제 Interactions API를 Gemini 3.x 모델을 호출하는 주요 방법으로 취급합니다. 요청은 하나의 JSON 객체로 구성됩니다: 모델, input, 그리고 thinking_level이 포함된 선택적 generation_config입니다.
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.8-flash",
"input": "Explain HTTP caching in 3 sentences.",
"generation_config": {"thinking_level": "medium"}
}'
응답은 단일 메시지가 아닌 실행 단계 목록입니다. 모델의 추론 및 도구 호출이 단계로 나타나며, 마지막 단계는 텍스트를 포함하는 model_output입니다. Python에서는 SDK가 이를 자동으로 처리해줍니다:
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="Explain HTTP caching in 3 sentences.",
generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)
temperature, top_p, top_k는 제외하십시오. 모든 Gemini 3 모델에 대한 구글의 지침은 temperature를 기본값인 1.0으로 유지하는 것입니다. 이를 낮추면 "루프 또는 성능 저하를 유발할 수 있기" 때문입니다. 이전 모델에서 구성을 복사했다면, 해당 줄이 가장 먼저 삭제해야 할 부분입니다.
3단계: previous_interaction_id를 사용한 다중 턴 대화
Interactions API는 기본적으로 서버에 대화 상태를 유지합니다. 대화를 계속하려면 이전 응답의 id를 previous_interaction_id로 보내고 새로운 사용자 입력만 포함하십시오. 대화 기록을 다시 보낼 필요는 없습니다.
follow_up = client.interactions.create(
model="gemini-3.8-flash",
input="Now give one example of a Cache-Control header.",
previous_interaction_id=interaction.id,
)
print(follow_up.output_text)
규정 준수 규칙에 서버 측 저장소가 금지되어 있다면 store: false로 설정하십시오. 이 경우 모델의 추론 블록과 추론 서명을 매 턴마다 받은 그대로 다시 보내는 것을 포함하여 상태를 직접 관리해야 합니다. 이는 3.8 Flash의 함수 호출 가이드에서 다루는 도구 사용 시 발생하는 문제와 동일한 규칙입니다.
4단계: 레거시 generateContent 경로
프로덕션 환경의 대부분의 Gemini 코드는 여전히 generateContent를 호출합니다. Google은 이를 레거시라고 부르지만, 서비스 종료일 없이 "완전히 지원"되므로 당장 코드를 다시 작성할 필요는 없습니다. 저희의 Gemini 3.7 Flash API 가이드는 이 경로만 다루었습니다. 3.8 Flash의 형태는 동일하며, 추론 설정은 Interactions와는 다른 위치에 있습니다.
generateContent에서 수준은 카멜케이스(camelCase)로 generationConfig.thinkingConfig.thinkingLevel 아래에 위치합니다:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"parts": [{"text": "Explain HTTP caching in 3 sentences."}]}],
"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}
}'
Python 등가 코드는 타입이 지정된 구성 객체를 사용합니다:
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="Explain HTTP caching in 3 sentences.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(thinking_level="low")
),
)
print(response.text)
thinking_budget을 정수로 사용했던 구성에서 오셨다면, 이를 문자열 열거형으로 교체하십시오. candidate_count 또한 Gemini 3 이상 버전에서는 없어졌습니다. 각 변경 사항에 대한 변경 전후 JSON이 포함된 전체 체크리스트는 3.7에서 3.8 Flash 마이그레이션 가이드에 있습니다.
다음은 두 API 간의 전환에 대해 문서를 다시 읽을 필요 없이 비교할 수 있도록 동일한 관심사를 나란히 정리한 것입니다:
| 관심사 | Interactions API | 레거시 generateContent |
|---|---|---|
| 추론 수준 | generation_config.thinking_level |
generationConfig.thinkingConfig.thinkingLevel |
| 대화 상태 | previous_interaction_id (서버 측) |
전체 contents 배열 재전송 |
| 도구 결과 | call_id + name을 포함한 function_result |
id + name을 포함한 functionResponse (동일 값, 필드 이름 다름) |
| 최종 텍스트 | model_output 단계 (SDK에서는 output_text) |
candidates[0].content.parts[].text |
| 추론 서명 | store: false가 아닌 경우 자동으로 처리됨 |
받은 모든 부분을 정확히 다시 전달 |
5단계: 스트리밍 및 추론 비용 확인
채팅 인터페이스의 경우, 메서드 이름을 streamGenerateContent로 바꾸고 ?alt=sse를 추가하여 서버 전송 이벤트를 받으십시오. 각 이벤트당 부분적인 candidates 청크가 제공됩니다:
curl -N "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents":[{"parts":[{"text":"List three HTTP caching headers."}]}]}'
스트리밍 여부와 관계없이 모든 generateContent 응답은 usageMetadata 객체로 끝납니다. 모든 호출에서 이를 확인하십시오:
"usageMetadata": {
"promptTokenCount": 12,
"candidatesTokenCount": 84,
"thoughtsTokenCount": 310,
"totalTokenCount": 406
}
thoughtsTokenCount는 3.8 Flash에서 주목해야 할 숫자입니다. 추론 토큰은 초기 기간 동안 백만 개당 $3.75의 출력 토큰으로 청구되며, Google은 모델이 "특히 높은 노력 수준에서 성능을 극대화하기 위해 더 많은 토큰을 사용할 수 있다"고 명시합니다. Artificial Analysis는 high 수준에서 인덱스 실행 시 작업당 약 48,000개의 출력 토큰을 측정했으며, 이는 3.7 Flash보다 30% 더 많은 수치로, 토큰당 가격 변동 없이 작업당 비용을 $0.40에서 $0.58로 증가시켰습니다. medium 및 low 실행에서는 작업당 각각 $0.41 및 $0.24가 나왔습니다. 추론 수준 가이드는 이러한 숫자를 경로별 전략으로 전환합니다.
모델이 무엇을 추론했는지 확인하려면 thinkingConfig 내부에 "includeThoughts": true를 추가하십시오. 추론 요약은 "thought": true 플래그가 지정된 부분으로 돌아오며, 보이는 답변을 구성할 때 이 부분은 건너뛰십시오.
첫 시간 안에 겪게 될 오류
thinking_level: "minimal" 유효성 검사 실패. Gemini 3.8 Flash는 low, medium, high만 지원합니다. minimal을 보내면 "Thinking level MINIMAL is not supported for this model. Please retry with other thinking level." 메시지와 함께 400 INVALID_ARGUMENT가 반환되며 (2026년 9월 3일 라이브 호출로 확인됨), 해결책은 low로 한 단어 변경하는 것입니다. 이전 3.x 구성 및 복사된 코드 조각이 일반적인 원인입니다.
429 오류는 버그가 아니라 등급 제한에 도달했음을 의미합니다. 속도 제한 페이지는 등급에 대해 설명합니다: 무료 등급은 속도 제한이 있으며, Tier 1은 결제 계정을 연결하면 잠금 해제되고, Tier 2는 $100 지출과 3일이 필요하며, Tier 3는 $1,000와 30일이 필요합니다. 모델당 분당 요청 수와 분당 토큰 수는 계정의 AI Studio 속도 제한 페이지에서만 표시되므로, 블로그 게시물의 숫자를 신뢰하기보다 해당 페이지를 확인하십시오. 429 오류가 발생하면 잠시 기다렸다가 다시 시도하십시오. 낮은 볼륨에서 429 오류가 반복되면 등급을 업그레이드하십시오. 오프라인 작업의 경우, 배치 API가 더 나은 해결책입니다. 배치 API는 50% 할인된 가격($0.375 / 백만 토큰당 $1.875, 초기 기간 동안)으로 실행되며, Tier 1에서 3M, Tier 2에서 400M, Tier 3에서 1B의 자체 대기열 토큰 제한이 있습니다. Gemini 배치 모드 가이드는 요청 형태를 보여줍니다.
함수 결과에 call_id 누락. 도구를 사용하는 경우, 모든 function_result (Interactions)는 3.8 Flash에서 call_id와 name을 모두 포함해야 하며, 모든 레거시 functionResponse는 일치하는 id와 name을 포함해야 합니다. 둘 중 하나라도 누락되면 턴이 실패합니다.
배포 전에 Apidog에서 두 엔드포인트를 모두 테스트하기
두 요청이 터미널에서 작동하면, 전체 팀이 실행할 수 있는 곳으로 옮기십시오. Apidog를 다운로드하고 프로젝트를 생성한 다음, 위에 언급된 두 엔드포인트를 저장된 요청으로 추가하십시오. 다음 네 가지 습관이 도움이 됩니다:
- 요청에서 키를 분리하십시오.
GEMINI_API_KEY를 환경 변수로 추가하고x-goog-api-key헤더에서{{GEMINI_API_KEY}}로 참조하십시오. 저장된 요청에는 절대로 비밀 키가 포함되지 않으며, 무료 등급 키와 유료 키 간 전환은 환경 변경 한 번으로 가능합니다. - 상태 및 토큰 사용량에 대해 어설션하십시오. 상태가 200인지 확인하는 어설션을 추가한 다음,
usageMetadata.thoughtsTokenCount가 각 프롬프트에 대해 선택한 상한선 미만으로 유지되는지 JSON 경로 어설션을 추가하십시오. 이 상한선은 비용 회귀 알람입니다. 프롬프트 업데이트나 자동 모델 변경으로 추론 토큰이 증가하면 청구서 발행 전에 테스트가 실패합니다. SSE 테스트 가이드는 스트리밍 변형을 다루며, Apidog는 이를 원시 청크 대신 병합된 이벤트 스트림으로 렌더링합니다. - 동일한 프롬프트를 세 가지 수준으로 모두 보내십시오.
low,medium,high로 요청을 복제하고thoughtsTokenCount와 응답 시간을 나란히 비교하십시오. 이렇게 하면 인덱스 평균 대신 프롬프트에 대한 실제 수치를 얻을 수 있습니다. - 일정을 설정하십시오. 요청을 테스트 시나리오로 전환하고 일정에 따라 실행하여, 속도 제한 변경,
minimal제거와 같은 유효성 검사 변경, 또는 토큰 급증이 프로덕션 환경이 아닌 보고서에 나타나도록 하십시오. Apidog에서 API 테스트를 예약하는 방법은 설정 과정을 안내합니다.
Apidog는 모델을 실행하거나 SDK를 대체하지 않습니다. 대신, HTTP 호출에 대한 저장 가능하고 공유 가능하며 어설션 가능한 버전을 제공합니다. 이는 대부분의 팀이 문제가 발생하기 전까지 건너뛰는 부분입니다.
FAQ
새 프로젝트는 어떤 엔드포인트를 사용해야 합니까? Interactions API입니다. Google은 generateContent를 레거시라고 부르며 여전히 완전히 지원하지만, 새로운 기능은 Interactions에 먼저 출시되고 서버 측 상태는 다중 턴 코드를 더 짧게 만듭니다. 마이그레이션할 이유가 생길 때까지 기존 서비스에는 generateContent를 계속 사용하십시오.
Gemini 3.8 Flash를 호출하려면 유료 계정이 필요합니까? 아니요. 무료 AI Studio 키는 속도 제한 및 Google의 데이터 사용 약관과 함께 작동합니다. 무료 사용 가이드는 무료 등급이 제공하는 것과 제공하지 않는 것을 나열하며, Gemini 앱은 3.8 Flash를 위해 AI Pro 또는 Ultra 플랜을 필요로 한다는 사실도 포함합니다.
3.8 Flash가 3.7 Flash보다 느립니까? 토큰당으로는 그렇지 않습니다. Google의 Logan Kilpatrick은 거의 동일한 속도라고 말했으며, Artificial Analysis는 초당 약 300개의 출력 토큰을 측정했습니다. high 수준에서는 더 많은 토큰을 생성하기 때문에 작업당 시간이 더 오래 걸립니다 (실험에서 2.2분 대 2.5분).
계속 Gemini 3.7 Flash를 호출할 수 있습니까? 예. Google은 3.7 Flash가 "완전히 지원된다"고 말했으며, 서비스 중단 날짜를 발표하지 않았습니다. 3.8 Flash에 대한 추가 토큰 지출이 워크로드에 이득이 되지 않는다면, 현재 버전을 유지하는 것이 유효한 선택입니다.
3.8 Flash는 Live API 또는 이미지 생성을 지원합니까? 아니요. 텍스트만 출력합니다. 오디오 생성, 이미지 생성 및 Live API는 이 모델에서 지원되지 않습니다.
다음 단계
이제 두 가지 작동하는 호출 경로, 다중 턴 패턴 및 토큰 사용량 확인 기능을 갖추었습니다. 여기에서 함수 호출 가이드를 사용하여 도구를 연결하고, 추론 수준 게시물을 통해 경로별 수준을 결정하십시오. 만약 여전히 마이그레이션 여부를 결정 중이라면, 3.8 vs 3.7 Flash 비교에서 장단점을 설명합니다. 비용 변동이 테스트 실패로 나타나도록 Apidog 시나리오를 계속 실행하십시오.