Google은 2026년 9월 2일, Gemini 3.7 Flash 출시 3주 후 동일한 출시 가격과 거의 동일한 속도로 Gemini 3.8 Flash를 출시했습니다. 모델 ID는 gemini-3.8-flash이며 미리보기 접미사는 없습니다. 모델 카드에는 “Gemini 3.7 Flash 기반”으로 설명되어 있어 일반 채팅 프롬프트는 대부분 한 줄만 교체하면 됩니다. 하지만 사고 매개변수, 샘플링 설정, 도구 루프를 사용하는 경우에는 아홉 가지를 확인해야 하며, 그중 두 가지는 3.7 Flash에서 발생하지 않던 오류를 일으킵니다.
이 가이드는 Google의 Gemini 3.8 Flash 새로운 기능 페이지와 Gemini 3 개발자 가이드를 바탕으로 작성한 마이그레이션 체크리스트입니다. Google이 주요 경로로 취급하는 Interactions API와, 기존 3.7 Flash 코드에서 많이 사용하는 레거시 generateContent 엔드포인트를 모두 다룹니다.
각 코드 조각은 Apidog에 붙여넣어 프로덕션에 적용하기 전에 실제 엔드포인트로 검증할 수 있습니다. 모델 개요가 필요하다면 Gemini 3.8 Flash란 무엇인가부터 확인해 보세요.
Google은 3.8 Flash를 “더 열심히 작동하도록” 설계했다고 설명합니다. 복잡한 작업에서 더 작은 추론 단계를 거치고, 결과를 검증하며, 도구를 반복 호출합니다. 이것이 성능 향상의 주요 원천인 동시에, 마이그레이션 시 구성 차이뿐 아니라 토큰 예산까지 검토해야 하는 이유입니다.
무엇이 바뀌고 무엇이 바뀌지 않는가
| 영역 | 3.7 Flash | 3.8 Flash |
|---|---|---|
| 모델 ID | gemini-3.7-flash |
gemini-3.8-flash |
| 컨텍스트 / 출력 | 1,048,576 / 65,536 | 동일 |
| 가격 (2026년 12월 31일까지) | 100만 토큰당 $0.75 / $3.75 | 동일 |
| 가격 (2027년 1월 1일부터) | 100만 토큰당 $1.50 / $7.50 | 동일 |
| 사고 수준 | 낮음, 중간, 높음 | 동일. minimal은 유효성 검사 오류, 기본값은 medium
|
| 작업당 토큰 | 기준 | 평균 출력 토큰 약 30% 증가(Artificial Analysis) |
| 함수 결과 |
call_id + name
|
두 필드 모두 필수 |
| 지원 상태 | 완전히 지원됨, 지원 중단 날짜 없음 | 현재 지원됨 |
가격은 Google의 Gemini API 가격 페이지를 기준으로 했습니다. 해당 페이지에서 3.6, 3.7, 3.8 Flash의 가격 행은 동일합니다.
0단계: 마이그레이션이 필요한지 결정하기
마이그레이션을 서두를 필요는 없습니다. Google의 출시 게시물에는 Gemini 3.7 Flash가 “완전히 지원된다”고 명시되어 있으며, 지원 종료 날짜도 발표되지 않았습니다.
토큰당 가격은 같지만 사용량은 달라질 수 있습니다. Artificial Analysis 측정에 따르면 높은 사고 수준에서 3.8 Flash는 작업당 약 48k 출력 토큰을 사용해 3 경우에는 3.7 Flash를 유지해도 됩니다.
- 작업이 짧은 경우
- 지연 시간에 민감한 경우
- 이미 3.7 Flash로 평가를 통과한 경우
작업 유형별 판단이 필요하다면 3.8 Flash와 3.7 Flash 비교의 의사 결정 매트릭스를 참고하세요.
1단계: 두 API 형태에서 모델 ID 교체하기
Interactions API
Google이 Gemini 3.x에서 주요 API로 취급하는 형태입니다.
{"model": "gemini-3.7-flash", "input": "..."}
{"model": "gemini-3.8-flash", "input": "..."}
레거시 generateContent
여전히 지원되며 지원 종료 날짜는 없습니다.
POST /v1beta/models/gemini-3.7-flash:generateContent
POST /v1beta/models/gemini-3.8-flash:generateContent
Python SDK
두 API 형태 모두에서 모델 ID만 gemini-3.8-flash로 변경합니다.
client.interactions.create(model="gemini-3.8-flash", input=..., generation_config={"thinking_level": "medium"})
client.models.generate_content(model="gemini-3.8-flash", contents=..., config=types.GenerateContentConfig(thinking_config=types.ThinkingConfig(thinking_level="low")))
Interactions API를 처음 사용한다면 3.8 Flash API 가이드에서 두 API 형태를 비교할 수 있습니다. 기존 3.7 Flash API 둘러보기는 generateContent에 초점을 둡니다.
아홉 가지 마이그레이션 체크리스트
1~4번은 즉시 확인할 구성 변경입니다. 5~6번은 도구 루프와 다중 턴 상태에 영향을 줍니다. 7~9번은 테스트를 통해 확인해야 하는 계획 및 미디어 변경입니다.
1. thinking_level: "minimal"을 "low"로 변경하기
3.8 Flash가 허용하는 값은 low, medium, high입니다. minimal을 보내면 유효성 검사 오류가 반환됩니다. 값을 생략하면 기본값은 medium입니다.
Gemini 3 Pro는 기본적으로 high를 사용하므로 Pro 설정을 그대로 복사해도 된다고 가정하지 마세요.
이전: 3.7 Flash Interactions API
{"generation_config": {"thinking_level": "minimal"}}
이후: 3.8 Flash Interactions API
{"generation_config": {"thinking_level": "low"}}
레거시 API
{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}
Google의 사고(thinking) 문서는 low를 지연 시간 중심 설정으로, medium을 복잡한 코드 및 에이전트 작업의 기본값으로 설명합니다.
마이그레이션 관점에서 low는 3.7 Flash의 minimal을 대체하는 값입니다. 자세한 경로별 설정은 Gemini 3.8 Flash 사고 수준 가이드를 참고하세요.
2. temperature, top_p, top_k 제거하기
Google은 모든 Gemini 3 모델에서 온도를 기본값인 1.0으로 유지할 것을 권장합니다. 값을 낮추면 루프가 발생하거나 성능이 저하될 수 있습니다.
이전 세대 설정을 물려받은 3.7 Flash 구성에는 다음과 같은 값이 남아 있을 수 있습니다.
이전
{"generationConfig": {"temperature": 0.2, "topP": 0.9, "topK": 40}}
이후
{"generationConfig": {"thinkingConfig": {"thinkingLevel": "medium"}}}
반복 가능한 JSON이 목적이었다면 낮은 온도 대신 구조화된 출력을 사용하세요. 3.8 Flash는 샘플링 설정을 변경하지 않고 스키마 기반 응답을 반환할 수 있습니다.
3. thinking_budget을 thinking_level로 교체하기
thinking_budget은 정수 토큰 제한이었지만, thinking_level은 문자열 열거형입니다. 둘 사이에 직접적인 산술 변환은 없습니다.
의도에 따라 선택하세요.
- 지연 시간 중심 경로:
low - 기본 경로:
medium - 가장 어려운 다단계 작업:
high
이전
{"generationConfig": {"thinkingConfig": {"thinkingBudget": 4096}}}
이후
{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}
사고 토큰은 계속 출력 토큰으로 청구되며 usageMetadata.thoughtsTokenCount에 표시됩니다. 따라서 비용 제어는 고정된 토큰 한도 대신 사고 수준 선택과 테스트 어설션으로 이동해야 합니다.
4. candidate_count 제거하기
Gemini 3 이상은 여러 후보 생성을 지원하지 않습니다. candidateCount를 삭제하고 candidates[1] 이상을 참조하는 코드도 제거하세요.
이전
{"generationConfig": {"candidateCount": 2}}
이후
{"generationConfig": {}}
여러 후보를 생성해 최적의 응답을 고르는 방식이었다면, 3.8 Flash에서는 더 높은 사고 수준을 사용하세요. 모델이 단일 응답 안에서 검증 단계를 수행합니다.
5. 모든 함수 결과에 call_id와 name 추가하기
3.8 Flash의 두 번째 주요 변경 사항입니다. 다시 전송하는 모든 함수 결과에는 호출의 ID와 함수 이름이 모두 있어야 합니다.
Google의 Gemini 3 가이드도 모든 FunctionResponse 객체에 call_id와 name을 포함하라고 안내합니다. 함수 이름만 반환하는 구현은 도구 결과 턴에서 실패합니다.
Interactions API, 이후
{
"previous_interaction_id": "<함수_호출 단계에서 온 ID>",
"input": [{
"type": "function_result",
"name": "get_weather",
"call_id": "<함수_호출 단계에서 온 ID>",
"result": [{"type": "text", "text": "{\"temp_c\": 24}"}]
}]
}
모델의 function_call 단계는 id, name, arguments를 제공합니다. id와 name을 그대로 복사해 함수 결과에 사용하세요.
레거시 API에서는 functionResponse의 id가 모델의 functionCall에 있는 ID와 일치해야 하며, name과 response도 함께 전송해야 합니다.
표준 예제는 Google의 함수 호출 참조에서 볼 수 있습니다. 전체 두 턴 루프와 3.8 Flash가 3.7 Flash보다 작업당 더 많은 도구를 호출하는 이유는 Gemini 3.8 Flash 함수 호출 가이드에서 확인할 수 있습니다.
6. 사고 서명을 받은 그대로 전달하기
Gemini 3 모델은 응답 부분에 사고 서명을 포함합니다. 다음 턴을 직접 구성한다면 텍스트뿐 아니라 모든 부분 유형의 서명을 변경하지 않고 되돌려 보내세요.
서명을 제거하거나 다시 직렬화하면 다음 단계에서 모델의 연속성이 저하될 수 있습니다.
Interactions API에서 previous_interaction_id를 전달하고 서버 측 상태 저장을 허용하면 이 작업을 직접 처리하지 않아도 됩니다. 반대로 상태 비저장 호출에서 store: false를 사용하면 대화 기록을 직접 관리해야 하므로 사고 블록과 서명도 다시 보내야 합니다.
레거시 generateContent에서는 항상 클라이언트가 기록을 관리합니다. 마지막 응답을 잘라서 contents를 재구성하는 코드를 특히 주의해서 검토하세요.
7. 경로별 토큰 예산 늘리기
이 변경은 오류를 발생시키지 않기 때문에 쉽게 놓칠 수 있습니다.
Artificial Analysis가 측정한 출력 토큰 약 30% 증가는 높은 사고 수준에서 지수 전반의 평균값입니다. Google도 이 모델이 설계상 길고 복잡한 작업에서 더 많은 토큰을 사용할 수 있으며, 특히 높은 노력 수준에서 사용량이 증가한다고 설명합니다.
전역 예산이 아니라 경로별로 계획하세요.
-
지연 시간 중심 엔드포인트:
lowArtificial Analysis는 작업당 약 0.8분, 비용 $0.24를 측정했습니다. -
기본 경로:
medium같은 지수에서 작업당 비용은 약 $0.41입니다. - 에이전트 루프: 도구 호출 턴 증가를 예상하고 토큰뿐 아니라 턴 수도 제한합니다.
출력 토큰 한도인 65,536도 다시 확인해야 합니다. 사고 토큰만 40k를 반환하던 3.7 Flash 프롬프트는 3.8 Flash에서 한도에 더 가까워질 수 있습니다.
비용 모델링에는 Gemini 3.8 Flash 가격 분석을 활용하세요.
8. PDF와 비디오에서 media_resolution_high 테스트하기
3.8 Flash는 텍스트, 이미지, 비디오, 오디오, PDF 입력을 지원합니다. 미디어 해상도 설정은 입력별 토큰 사용량을 바꾸며, 미디어 유형에 따라 비용도 달라집니다.
따라서 PDF에서 저렴한 설정이 긴 비디오에서는 비쌀 수 있습니다. 3.7 Flash의 전역 고해상도 설정을 그대로 복사하지 말고 다음을 직접 비교하세요.
- 대표적인 PDF 한 개를 각 해상도로 전송합니다.
- 대표적인 비디오 한 개를 각 해상도로 전송합니다.
-
usageMetadata.promptTokenCount를 비교합니다.
9. 모든 이미지 분할 호출 제거하기
이미지 분할은 Gemini 3 모델에서 지원되지 않습니다.
3.7 Flash 이전 파이프라인이 다른 Gemini 모델을 통해 분할을 처리한다면 해당 경로는 별도로 유지할 수 있습니다. 하지만 프롬프트에서 3.8 Flash에 분할 마스크를 요청하면 유용한 결과 대신 실패할 가능성이 높습니다.
Gemini 3.8 Flash 모델 페이지에 따르면 이미지 생성, 오디오 생성, Live API도 3.8 Flash에서 지원되지 않습니다.
Apidog에서 회귀 계획 만들기
호환되지 않는 구성 변경 두 가지와 토큰 사용량 변화가 있는 마이그레이션에는 일회성 curl보다 반복 가능한 비교 테스트가 필요합니다.
Apidog는 API 클라이언트이자 테스트 러너입니다. 요청을 전송하고, 응답을 검증하고, 테스트를 예약할 수 있습니다. 단, 모델 자체를 실행하는 도구는 아닙니다.
환경 및 변수
GEMINI_API_KEY를 비밀 변수로 저장하고 MODEL 변수로 Gemini 환경을 구성하세요.
-
generateContent요청 URL에{{MODEL}}사용 - Interactions API의
model필드에{{MODEL}}사용
이렇게 하면 같은 요청을 두 모델에 번갈아 실행할 수 있습니다.
골든 프롬프트
실제 사용 경로를 대표하는 10~20개의 프롬프트를 저장하세요.
- 짧은 채팅 턴
- 구조화된 출력 추출
- 모의 도구를 사용하는 두 턴 함수 호출
- PDF 입력
- 비디오 입력
각 프롬프트를 하나의 테스트 시나리오로 관리하면 모델 간 결과와 토큰 사용량을 비교하기 쉽습니다.
어설션
각 요청에는 다음 세 가지 어설션을 추가하세요.
- 응답 상태가
200인지 확인하고, 본문이 JSON 스키마와 일치하는지 검증합니다. 구조화된 출력 경로에서는 다운스트림에서 실제로 파싱하는 필드도 확인합니다. -
usageMetadata.thoughtsTokenCount가 경로별 상한을 넘지 않는지 확인합니다. 예를 들어low경로의 상한을 8,000으로 설정할 수 있습니다. 이 어설션은 구성이 조용히medium으로 되돌아가는 문제를 잡아냅니다. -
usageMetadata.totalTokenCount가 7번 단계에서 정한 경로별 예산 안에 있는지 확인합니다.
병렬 비교
테스트 시나리오를 복제한 뒤 다음처럼 실행하세요.
- 한 시나리오의
MODEL:gemini-3.7-flash - 다른 시나리오의
MODEL:gemini-3.8-flash
Apidog 테스트 보고서는 어설션별 통과·실패 결과와 응답 본문을 함께 보여줍니다. 프롬프트별 토큰 차이를 로그에서 다시 계산할 필요가 없습니다.
함수 호출 시나리오에는 다음 어설션도 추가하세요.
재전송한
call_id가 이전 단계의function_call에서 받은id와 같은가?
예약 실행
출시 기간에는 3.8 Flash 시나리오를 예약 실행으로 전환해 매일 토큰 상한을 확인하세요.
설정 방법은 Apidog 예약 API 테스트 가이드에서 확인할 수 있습니다.
로컬 앱에서 작업하려면 Apidog 다운로드 후 위의 curl 조각을 가져오면 됩니다.
롤백: 구성 플래그 뒤에 3.7 Flash 유지하기
3.7 Flash는 계속 지원되고 3.8 Flash와 가격도 같으므로 롤백 비용이 낮습니다. 모델 ID를 코드에 하드코딩하지 말고 구성으로 분리하세요.
{"gemini_model": "gemini-3.8-flash", "gemini_fallback_model": "gemini-3.7-flash"}
다음 세 가지 규칙을 적용하면 플래그 전환을 안전하게 운영할 수 있습니다.
-
두 모델에 동일한 요청 형태 사용
minimal제거, 샘플링 키 제거,thinking_budget에서thinking_level로 변경,candidate_count제거,call_id와name추가, 사고 서명 보존은 3.7 Flash에서도 유효합니다. 따라서 두 번째 코드 경로가 필요하지 않습니다. -
경로별로 단계적 배포
토큰 차이가 가장 작은
low지연 시간 경로부터 전환합니다. 병렬 시나리오가 며칠 동안 통과한 뒤 에이전트 루프를 마지막에 전환하세요. - 오류와 토큰을 함께 모니터링 3.8 Flash의 롤백 원인은 4xx 오류보다 비용이나 지연 시간 회귀일 가능성이 큽니다. 토큰 상한 어설션을 알림 시스템에 연결하세요.
자주 묻는 질문
Gemini 3.8 Flash가 3.7 Flash보다 비싼가요?
토큰당 가격은 같지… Wait this is Korean and should be "비싸지 않습니다." Need ensure no accidental. Continue.
토큰당 가격은 더 비싸지 않습니다. 두 모델 모두 2026년 12월 31일까지 입력 100만 토큰당 $0.75, 출력 100만 토큰당 $3.75입니다. 2027년 1월 1일부터는 둘 다 입력 $1.50, 출력 $7.50으로 인상됩니다.
다만 3.8 Flash는 설계상 더 많은 토큰을 사용할 수 있습니다. Artificial Analysis는 높은 사고 수준에서 약 30% 더 많은 출력 토큰을 측정했습니다.
thinking_level: "minimal"을 그대로 두면 어떻게 되나요?
3.8 Flash 요청이 유효성 검사 오류와 함께 실패합니다. low로 변경하세요. 각 사고 수준의 역할과 차이를 측정하는 방법은 Gemini 3.8 Flash 사고 수준 가이드를 참고하세요.
3.8 Flash를 사용하려면 Interactions API로 이전해야 하나요?
아니요. generateContent는 레거시 API로 분류되지만 지원 종료 날짜 없이 계속 지원되며 3.8 Flash에서도 작동합니다.
Interactions API는 previous_interaction_id를 통한 서버 측 대화 상태를 제공합니다. 이 기능을 사용하면 6번 항목의 사고 서명 기록을 직접 관리할 필요가 줄어듭니다.
3.7 Flash는 곧 사용 중단되나요?
Google은 3.7 Flash가 “완전히 지원된다”고 밝혔으며, 지원 중단 날짜를 발표하지 않았습니다. 따라서 구성 플래그를 이용한 롤백이 가능합니다.
3.7 Flash에 맞춘 낮은 온도를 그대로 유지해도 되나요?
Google의 모든 Gemini 3 모델 권장값은 온도 1.0입니다. 3.7 Flash에서 이를 재정의하고 있었다면 이번 마이그레이션에서 제거하고 평가를 다시 실행하세요.
결정론적인 형식이 필요하다면 낮은 온도 대신 구조화된 출력을 사용하세요.
단계별 출시
마이그레이션 코드 자체는 작습니다.
- 모델 ID 한 가지 변경
- 구성 네 가지 삭제 또는 이름 변경
- 도구 루프 필드 두 가지 추가
- 사고 서명 전달 여부 감사
시간이 걸리는 부분은 경로별 토큰 예산이 유지되는지 입증하는 작업입니다. 골든 프롬프트를 저장하고 스키마와 토큰 상한을 어설션하세요. 수치가 안정될 때까지 3.7과 3.8 Flash를 병렬 실행한 뒤 경로별로 플래그를 전환하면 됩니다.
회귀가 발생하면 코드 변경 없이 플래그를 3.7 Flash로 되돌리고, 개선된 경로만 계속 운영하세요.
Top comments (0)