Google은 2026년 9월 2일, 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 개발자 가이드에서 취합한 체크리스트입니다. 각 항목에는 두 가지 API 형태(Google이 현재 주요 경로로 취급하는 Interactions API와 대부분의 3.7 Flash 코드가 여전히 사용하는 레거시 generateContent 엔드포인트)에 대한 이전 및 이후 코드 조각이 있습니다. 모든 코드 조각은 Apidog에 붙여넣어 프로덕션에 적용하기 전에 라이브 엔드포인트에 대해 전송될 수 있습니다. 모델 개요를 먼저 보려면 Gemini 3.8 Flash란 무엇인가부터 시작하십시오.
목록에 들어가기 전에 한 가지 덧붙이자면. Google은 3.8 Flash가 "더 열심히 작동하도록" 설계되었다고 말합니다. 즉, 복잡한 작업에서 더 작은 추론 단계를 거치고, 작업을 확인하며, 도구를 반복적으로 호출합니다. 이것이 대부분의 성능 향상 원천이자, 마이그레이션 시 단순히 구성 차이(config diff)뿐만 아니라 토큰 예산 검토가 필요한 이유입니다.
무엇이 바뀌고 무엇이 바뀌지 않는가
| 영역 | 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일부터 둘 다 $1.50 / $7.50 |
| 사고 수준 | 낮음, 중간, 높음 | 동일; minimal은 유효성 검사 오류를 반환; 기본값은 medium |
| 작업당 토큰 | 기준 | 평균 출력 토큰 +30% (인공 분석) |
| 함수 결과 | 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.7 Flash보다 30% 더 많다고 측정했습니다. 동일한 요율에서 작업당 비용은 $0.40에서 $0.58로 증가했습니다. 이들의 지수 점수는 56에서 59로 상승했으며, τ³-Banking의 도구 사용 정확도는 12포인트 상승하여 45%가 되었습니다.
따라서 더 많은 토큰을 사용하여 작업당 더 많은 기능을 얻는 것이 거래입니다. 작업량이 짧거나, 지연 시간에 민감하거나, 이미 3.7 Flash에서 평가를 통과하고 있다면 현재 상태를 유지할 수 있습니다. 전체 3.8 Flash vs 3.7 Flash 비교는 작업량별 의사 결정 매트릭스를 제공합니다. 마이그레이션할 예정이라면 계속 읽으십시오.
1단계: 두 가지 형태 모두에서 모델 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, 두 가지 경로 모두:
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 가이드가 두 가지 형태를 모두 다루고 있습니다. 이전 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):
{"generation_config": {"thinking_level": "minimal"}}
이후 (3.8 Flash):
{"generation_config": {"thinking_level": "low"}}
레거시 형태, 이후:
{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}
Google의 사고(thinking) 문서는 low를 지연 시간 설정으로, medium을 복잡한 코드 및 에이전트 작업의 기본값으로 설명합니다. 경로별 사용 레벨은 별도의 문서에 설명되어 있으며, 마이그레이션 목적상 low는 minimal의 직접적인 대체제입니다.
2. temperature, top_p, top_k 제거
모든 Gemini 3 모델에 대한 Google의 지침은 온도를 기본값인 1.0으로 유지하는 것입니다. 이를 낮추면 "루프 또는 성능 저하가 발생할 수 있습니다". 많은 3.7 Flash 구성에는 이전 세대에서 남은 temperature: 0.2가 포함되어 있습니다. 샘플링 키를 설정하는 대신 삭제하십시오.
이전:
{"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 이상은 다중 후보를 지원하지 않습니다. 키를 삭제하고, candidates[1] 이상을 인덱싱하는 모든 코드를 삭제하십시오.
이전:
{"generationConfig": {"candidateCount": 2}}
이후:
{"generationConfig": {}}
여러 후보를 샘플링하여 최적의 것을 선택했다면, 3.8 Flash에서는 더 높은 사고 수준이 이를 대체하며, 이는 단일 응답 내에서 검증을 수행합니다.
5. 모든 함수 결과에 call_id와 name 추가
이것이 두 번째 큰 변경 사항입니다. 3.8 Flash에서는 다시 보내는 모든 함수 결과에 호출의 id와 함수 name이 모두 포함되어야 합니다. 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를 제공합니다. 처음 두 가지를 그대로 다시 복사하십시오. 레거시 형태에서는 functionResponse 부분이 모델의 functionCall 부분에 있는 id와 일치하는 id 필드에 동일한 값을 name 및 response와 함께 가집니다. Google의 함수 호출 참조에는 표준 예제가 있으며, 3.8 Flash 함수 호출 가이드는 3.8 Flash가 3.7 Flash보다 작업당 도구를 더 많이 호출하는 이유를 포함하여 전체 두 턴 루프를 설명합니다.
6. 사고 서명(thought signatures)을 받은 그대로 다시 전달
Gemini 3 모델은 응답 부분에 사고 서명을 첨부합니다. 다음 턴을 직접 구성할 때, 모든 부분 유형(텍스트뿐만 아니라)에 대해 서명을 포함하여 모든 부분을 변경하지 않고 반환하십시오. 이를 제거하거나 다시 직렬화하면 다음 단계에서 모델의 연속성이 저하됩니다.
Interactions API는 서버가 상태를 유지하도록 허용할 때 이 작업을 제거합니다. 즉, previous_interaction_id를 전달하면 Google이 기록을 보관합니다. 상태 비저장 호출에 대해 store: false를 설정하면, 다시 직접 기록을 소유하게 되며 사고 블록과 서명을 다시 보내야 합니다. 레거시 generateContent에서는 항상 기록을 소유하므로, 마지막 응답의 잘린 복사본에서 contents를 재구성하는 모든 코드를 감사하십시오.
7. 경로당 더 많은 토큰 예산 책정
이 항목은 잡아낼 오류가 없기 때문에 놓치기 쉽습니다. Artificial Analysis의 +30% 출력 토큰 수치는 높은 사고 수준에서 이들의 지수에 걸쳐 평균입니다. Google의 공식 문구에 따르면 이 모델은 "설계상 더 길고 복잡한 작업에서 더 많은 토큰을 사용할 수 있으며", 사용량은 "특히 더 높은 노력 수준에서" 증가합니다.
전역적으로가 아닌 경로별로 계획하십시오:
- 지연 시간에 민감한 엔드포인트:
low. AA는 낮은 수준에서 작업당 0.8분, 높은 수준에서 2.5분, 작업당 비용은 $0.24 대 $0.58로 측정했습니다. - 기본 경로:
medium, 동일한 지수에서 작업당 약 $0.41. - 에이전트 루프: 작업당 더 많은 도구 호출 턴을 예상하므로, 토큰뿐만 아니라 턴 수로 루프를 제한하십시오.
65,536 출력 토큰 제한도 다시 검토하십시오. 사고(thinking)를 통해 40k 토큰을 반환하던 3.7 Flash 프롬프트는 이제 제한에 더 가까워질 수 있습니다. 요금을 모델링하는 경우, 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에 분할 마스크를 요청했다면, 유용한 출력을 반환하기보다는 실패할 것으로 예상해야 합니다. 모델 페이지에 따르면 이미지 생성, 오디오 생성 및 Live API도 3.8 Flash에서 지원되지 않습니다.
Apidog에서 회귀 계획 구축
두 가지 호환되지 않는 변경 사항과 토큰 사용량 변화가 있는 마이그레이션은 일회성 curl이 아닌 반복 가능한 비교가 필요합니다. 다음은 Apidog에서 사용하는 설정입니다. Apidog는 API 클라이언트이자 테스트 러너이므로 요청을 보내고, 응답을 확인하며, 실행을 예약할 수 있기 때문에 작동합니다. 모델을 실행하지는 않습니다.
환경 및 변수.
GEMINI_API_KEY를 비밀 변수로 저장하고 MODEL 변수를 사용하여 Gemini 환경을 생성하십시오. `generateContent` 요청의 URL과 Interactions 요청의 `model` 필드에 `{{MODEL}}`을 사용하여, 동일하게 저장된 요청이 두 모델 중 하나에 대해 실행되도록 하십시오.
골든 프롬프트.
실제 경로를 나타내는 10~20개의 프롬프트를 저장하십시오: 짧은 채팅 턴, 구조화된 출력 추출, 모의 도구를 사용한 두 턴 함수 호출, 하나의 PDF 및 하나의 비디오 입력. 각 프롬프트는 테스트 시나리오에서 하나의 요청입니다.
어설션.
요청당 세 가지를 추가하십시오:
- 상태는 200이고, 응답 본문은 JSON 스키마와 일치해야 합니다. 구조화된 출력 경로의 경우, 다운스트림에서 구문 분석하는 필드에 대해 어설션하십시오.
usageMetadata.thoughtsTokenCount는 경로당 설정한 상한선(예:low경로에서 8,000)을 유지해야 합니다. 이는medium으로 조용히 돌아간 구성을 포착하는 방어 장치입니다.usageMetadata.totalTokenCount는 7번 항목의 경로 예산 내에 있어야 합니다.
병렬 비교.
시나리오를 복제하고, 하나에는 MODEL을 gemini-3.7-flash로, 다른 하나에는 gemini-3.8-flash로 설정한 다음 둘 다 실행하십시오. Apidog의 테스트 보고서는 어설션별 통과/실패와 응답 본문을 보여주므로, 프롬프트당 토큰 차이를 로그에서 재구성하는 대신 한 화면에서 확인할 수 있습니다. 함수 호출 시나리오의 경우, 다시 보낸 call_id가 이전 단계의 function_call에서 온 id와 같다는 어설션을 추가하십시오.
예약.
3.8 Flash 시나리오를 예약된 실행으로 전환하여 출시 기간 동안 매일 토큰 상한이 확인되도록 하십시오. 예약된 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"}
세 가지 규칙이 플래그를 안전하게 만듭니다:
- 마이그레이션된 요청 형태를 두 모델 모두에서 유지하십시오. 1번부터 6번 항목(`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보다 비용이 더 많이 드나요?
토큰당은 아닙니다. 둘 다 2026년 12월 31일까지 100만 개당 $0.75 입력 / $3.75 출력이며, 2027년 1월 1일에는 둘 다 $1.50 / $7.50로 인상됩니다. 작업당으로 보면, 3.8 Flash는 설계상 더 많은 토큰을 사용합니다. Artificial Analysis는 높은 사고 수준에서 이들의 지수에서 약 30% 더 많은 출력 토큰을 측정했습니다.
thinking_level: "minimal"을 그대로 두면 어떻게 되나요?
3.8 Flash에서 요청이 유효성 검사 오류와 함께 실패합니다. `low`로 교체하십시오. 사고 수준 가이드는 각 나머지 수준이 무엇을 하는지, 그리고 차이를 측정하는 방법을 설명합니다.
3.8 Flash를 사용하려면 Interactions API로 이동해야 하나요?
아니요. `generateContent`는 레거시로 설명되지만 지원 종료 날짜 없이 완전히 지원되며, 3.8 Flash는 이를 통해 작동합니다. Interactions API는 `previous_interaction_id`를 통해 서버 측 대화 상태를 추가하며, 이는 6번 항목의 사고 서명 기록을 제거합니다.
3.7 Flash는 사용 중단되나요?
Google은 "완전히 지원된다"고 말하며 지원 중단 날짜를 발표하지 않았습니다. 이것이 구성 플래그 롤백을 실현 가능하게 만듭니다.
3.7 Flash에 맞게 조정한 온도를 그대로 유지할 수 있나요?
모든 Gemini 3 모델에 대한 Google의 권장 사항은 온도를 1.0으로 유지하는 것입니다. 이미 3.7 Flash에서 이를 재정의하고 있었다면, 이 마이그레이션이 이를 제거하고 평가를 확인해야 할 시점입니다. 구조화된 출력은 결정론적 형태를 위한 지원되는 경로입니다.
단계별 출시
마이그레이션 자체는 작습니다: 하나의 ID 변경, 네 가지 구성 삭제 또는 이름 변경, 두 가지 도구 루프 필드, 그리고 서명 감사. 시간이 걸리는 부분은 경로당 토큰 예산이 유지됨을 증명하는 것이며, 이는 테스트 문제입니다. 골든 프롬프트를 저장하고, 스키마 및 토큰 상한에 대해 어설션하고, 수치가 안정될 때까지 3.7과 3.8 Flash를 병렬로 실행한 다음, 한 번에 한 경로씩 플래그를 전환하십시오. 경로가 회귀하면 플래그는 코드 변경 없이 3.7 Flash로 되돌리고, 개선된 경로는 유지됩니다.