Google은 2026년 8월 13일, 3.6 Flash 출시 3주 만에 Gemini 3.7 Flash를 출시했으며 이를 “가장 지능적인 워크호스 모델”이라고 부릅니다. 개발자 관점의 핵심은 에이전트 코딩 점수의 큰 향상(DeepSWE v1.1: 49.0% → 65.3%), 3.6 Flash 출시 가격의 절반인 초기 가격, 그리고 변경되지 않은 API 표면입니다. 이미 Gemini를 사용 중이라면 모델 ID만 바꾸면 됩니다. 그렇지 않다면, Google이 제공한 역대 가장 낮은 가격으로 이 수준의 성능을 도입할 수 있는 진입점입니다.
이 가이드는 API 키 발급, cURL 첫 호출, Python 및 Node.js 포팅, 응답 스트리밍, generationConfig 조정, 그리고 Apidog를 사용한 요청 검증까지 다룹니다. 코드 루프에서 반복적으로 토큰을 소모하지 않고 프롬프트를 개선하는 것이 목표입니다. 공식 발표 기준 사양은 1M 토큰 컨텍스트, 64k 출력, 멀티모달 입력, 함수 호출, 도구로서의 검색, 컴퓨터 사용입니다.
이전 세대를 기반으로 개발했다면 요청 형식은 Gemini 3 Flash 미리보기 API 가이드와 동일한 흐름을 따릅니다. 이 글에서는 3.7 Flash 워크플로우에서 확인해야 할 부분에 집중합니다.
요약
- 모델 ID:
gemini-3.7-flash - 동기 엔드포인트:
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent - 인증 헤더:
x-goog-api-key: <KEY> - 초기 가격은 2026년 12월 31일까지 입력 토큰 100만 개당 $0.75, 출력 토큰 100만 개당 $3.75입니다. 2027년 1월 1일부터는 각각 $1.50, $7.50으로 두 배가 됩니다.
- 입력 컨텍스트는 1M 토큰, 출력 제한은 64k 토큰입니다.
- 입력은 텍스트, 이미지, 비디오, 오디오, PDF를 지원하며 출력은 텍스트입니다.
- 3.6 Flash 대비 주요 벤치마크 변화:
- DeepSWE: 49.0% → 65.3%
- FrontierCode: 34.4% → 43.6%
- AutomationBench: 17.0% → 30.4%
- WebDev Arena Elo: 1538 → 1588
- 스트리밍은
:streamGenerateContent?alt=sse를 사용합니다. - 애플리케이션 코드 전에 Apidog에서 요청 본문, 환경 변수, SSE 응답을 먼저 검증하세요.
Gemini 3.7 Flash의 용도
Flash 모델은 일반적으로 최고 수준의 지능보다 속도와 가격을 우선합니다. Gemini 3.7 Flash는 이 절충점을 좁힌 모델입니다. 3.6 Flash 대비 DeepSWE v1.1은 49.0%에서 65.3%로, FrontierCode 1.1 Main은 34.4%에서 43.6%로, AutomationBench는 17.0%에서 30.4%로 상승했습니다. WebDev Arena Elo도 1538에서 1588로 50점 올랐습니다.
다음 워크로드에 우선 적용해 보세요.
- 에이전트 루프: AutomationBench 점수 상승은 다단계 계획과 도구 호출이 필요한 흐름에 유용하다는 신호입니다.
- 코드 생성 및 디버깅: DeepSWE와 FrontierCode 개선은 코드 리뷰, 버그 수정, 구현 보조 작업에 직접 연결됩니다.
- 문서 처리: GDP.pdf는 22.0%에서 34.0%로 상승했습니다. PDF에서 구조화된 데이터를 추출하는 작업에 적합합니다.
-
비용 제약이 있는 멀티모달 입력: 텍스트, 이미지, 비디오, 오디오, PDF를 같은
contents배열로 보낼 수 있습니다.
법률 도메인 Harvey LAB-AA 점수 90.7%와 업데이트된 CBRN·사이버 보호 기능은 Gemini 3.7 Flash의 새로운 기능에서 확인할 수 있습니다. 또한 Axios 보도에 따르면 Google은 다음 플래그십보다 Flash 업데이트를 의도적으로 먼저 출시하고 있습니다.
API 키 얻기
Gemini API 호출 경로는 크게 두 가지입니다.
AI Studio: 빠른 프로토타이핑
- aistudio.google.com/apikey를 엽니다.
- API 키 가져오기를 클릭합니다.
- Google Cloud 프로젝트를 선택합니다.
- 생성된 키를 복사합니다.
이 키는 generativelanguage.googleapis.com에 바로 사용할 수 있습니다. 무료 등급은 프로토타입 제작에 충분한 할당량을 제공하며 Gemini 3.7 Flash는 160개 이상의 국가에서 사용할 수 있습니다.
Vertex AI: 운영 환경
GCP 인프라 위에서 운영한다면 Vertex AI를 사용하세요.
- 인증: API 키 대신 OAuth(서비스 계정 또는 단기 토큰)
- 엔드포인트:
aiplatform.googleapis.com - 운영 기능: IAM, 감사 로그, 리전별 엔드포인트
모델 ID와 요청 본문은 같고 URL 및 인증 방식만 달라집니다. 일반적으로 AI Studio에서 시작한 뒤 실제 운영 트래픽 전에 Vertex AI로 이동하는 흐름이 적합합니다.
키는 환경 변수로 관리하세요.
export GEMINI_API_KEY="AIza..."
운영 환경에서는 키를 하드코딩하거나 ?key= 쿼리 매개변수로 전달하지 마세요. 쿼리 문자열은 서버 로그에 남을 수 있습니다.
엔드포인트 및 인증
동기 요청 엔드포인트:
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent
스트리밍 엔드포인트:
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:streamGenerateContent?alt=sse
AI Studio API 키 인증은 다음 헤더 하나면 됩니다.
x-goog-api-key: $GEMINI_API_KEY
cURL에서 첫 요청 보내기
다음 요청으로 연결과 요청 스키마를 먼저 확인하세요.
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Review this SQL for injection risk: SELECT * FROM orders WHERE id = ${orderId}"
}]
}],
"generationConfig": {
"temperature": 0.3,
"maxOutputTokens": 1024
}
}'
응답은 candidates 배열을 반환합니다. 각 후보에는 텍스트 또는 함수 호출을 담는 parts, 그리고 종료 상태인 finishReason이 포함된 content 객체가 있습니다.
토큰 사용량은 최상위 usageMetadata에서 확인합니다. 출력 토큰 비용이 입력 토큰보다 5배 높으므로, 특히 maxOutputTokens와 실제 출력량을 관찰하세요.
Google API는 OpenAI의 messages가 아니라 role과 parts를 포함한 contents 구조를 사용합니다. 다른 제공자에서 포팅할 때 가장 먼저 수정해야 할 부분입니다.
Python 빠른 시작
SDK를 설치하거나 업데이트합니다.
pip install --upgrade google-generativeai
시스템 지침과 생성 설정을 포함한 기본 호출입니다.
import os
import google.generativeai as genai
genai.configure(api_key=os.environ["GEMINI_API_KEY"])
model = genai.GenerativeModel(
model_name="gemini-3.7-flash",
system_instruction="You are a code reviewer. Flag issues as blocking or non-blocking.",
generation_config={
"temperature": 0.3,
"max_output_tokens": 2048,
},
)
response = model.generate_content(
"Review this Flask route for security issues:\n\n"
"@app.route('/user/<id>')\n"
"def get_user(id):\n"
" return db.execute(f'SELECT * FROM users WHERE id = {id}')"
)
print(response.text)
print("input tokens:", response.usage_metadata.prompt_token_count)
print("output tokens:", response.usage_metadata.candidates_token_count)
PDF 입력 예시
멀티모달 입력도 같은 contents 흐름으로 처리합니다. PDF는 Files API를 통해 업로드한 뒤 파트로 전달할 수 있습니다.
invoice = genai.upload_file("q3-invoice.pdf")
response = model.generate_content([
invoice,
"Extract the invoice number, total, and due date as JSON.",
])
print(response.text)
GDP.pdf 벤치마크 개선은 이와 같은 복잡한 문서에서 구조화된 정보를 추출하는 워크로드와 관련이 있습니다.
Node.js 빠른 시작
Node.js에서는 @google/generative-ai SDK를 사용합니다.
import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const model = genAI.getGenerativeModel({
model: "gemini-3.7-flash",
generationConfig: {
temperature: 0.3,
maxOutputTokens: 2048,
responseMimeType: "application/json",
responseSchema: {
type: "object",
properties: {
severity: {
type: "string",
enum: ["blocking", "non-blocking"],
},
issues: {
type: "array",
items: { type: "string" },
},
},
required: ["severity", "issues"],
},
},
});
const result = await model.generateContent(
"Review this Express handler: app.get('/search', (req, res) => res.send(eval(req.query.q)))"
);
console.log(JSON.parse(result.response.text()));
responseSchema는 구조화된 응답이 필요한 자동화 흐름에서 중요합니다. 모델 출력을 파싱 가능한 객체 형태로 제한할 수 있어 다운스트림 코드가 자유 형식 텍스트를 직접 처리하지 않아도 됩니다.
responseSchema를 적용하려면 반드시 다음 설정도 함께 사용해야 합니다.
responseMimeType: "application/json"
스트리밍
채팅 UI나 사용자 대면 애플리케이션에서는 스트리밍을 사용하세요.
Python SDK에서는 stream=True를 추가합니다.
stream = model.generate_content(
"Explain the N+1 query problem with a concrete ORM example.",
stream=True,
)
for chunk in stream:
if chunk.text:
print(chunk.text, end="", flush=True)
원시 HTTP를 사용하는 경우 다음 엔드포인트를 호출합니다.
:streamGenerateContent?alt=sse
각 SSE data: 행에는 부분적인 candidates 페이로드가 들어갑니다. 최종 청크에는 usageMetadata가 포함되므로, 정확한 토큰 집계는 스트림이 끝난 뒤 수행하세요.
generationConfig 조정
가장 자주 조정하게 되는 설정입니다.
| 매개변수 | 유형 | 기능 |
|---|---|---|
maxOutputTokens |
정수 | 출력 토큰의 하드 캡입니다. 최대 64k이며 비용 제어에 가장 직접적입니다. |
temperature |
숫자 | 0~2 범위입니다. 코드·추출 작업에는 0.2~0.4, 창의적 텍스트에는 0.7 이상을 사용합니다. |
responseMimeType |
문자열 | JSON 출력을 강제하려면 application/json으로 설정합니다. |
responseSchema |
객체 | JSON MIME 유형과 함께 사용하면 출력 구조를 제한합니다. |
topP |
숫자 | 핵 샘플링 cutoff입니다. 의도적으로 조정할 이유가 없다면 기본값을 유지하세요. |
stopSequences |
배열 | 특정 문자열에서 생성을 중지합니다. 구분자 기반 파싱에 유용합니다. |
초기 요금 기준 출력 토큰은 100만 개당 $3.75이며, 2027년 1월부터는 $7.50입니다. 출력 한도를 64k로 고정하지 말고 작업에 필요한 크기로 제한하세요. 워크로드별 토큰 계산은 Gemini 3.7 Flash 가격 분석에서 확인할 수 있습니다.
generationConfig 외에도 요청 본문은 다음을 지원합니다.
-
tools: 함수 선언, 도구로서의 검색, 컴퓨터 사용 -
toolConfig: 도구 호출 방식 제어
도구 사용은 3.7 Flash가 크게 개선된 영역입니다. 함수 선언, 병렬 호출, 응답 루프 패턴은 Gemini 3.7 Flash 함수 호출 튜토리얼을 참고하세요.
앱 코드 작성 전에 Apidog에서 엔드포인트 테스트하기
Python이나 Node.js 코드 안에서 프롬프트를 반복하면 편집, 재실행, 로그 확인을 계속해야 하고 매번 토큰 비용도 발생합니다. 먼저 API 클라이언트에서 요청 형태를 고정한 뒤 코드로 옮기면 반복 속도를 높일 수 있습니다.
Apidog에서 Gemini 요청을 검증하는 절차는 다음과 같습니다.
-
프로젝트를 생성하고 Google API 문서에서 Generative Language API OpenAPI 스펙을 가져옵니다.
generateContent요청을 검색해 바로 찾을 수 있습니다. -
GEMINI_API_KEY라는 환경 변수를 추가하고x-goog-api-key헤더에 바인딩합니다. 키가 요청 본문에 노출되지 않도록 관리하세요. - 모델 ID를
gemini-3.7-flash값의 변수로 저장합니다. 이후gemini-3.6-flash와 비교할 때 저장된 모든 URL을 수정하지 않고 변수 하나만 바꾸면 됩니다. -
시각적 JSON 편집기에서
contents배열을 구성합니다. 중첩된parts를 확인하고 잘못된 요청 본문을 사전에 잡으세요. - 스트리밍 엔드포인트를 호출합니다. SSE 청크가 실시간으로 도착하는 과정과 응답 지연을 확인할 수 있습니다.
- 정상 응답을 예시로 저장합니다. 이후 테스트에서는 실제 API 대신 고정 데이터를 사용해 토큰 사용을 줄일 수 있습니다.
요청을 저장한 뒤에는 finishReason, 응답 스키마, usageMetadata의 토큰 수에 대한 어설션을 테스트 시나리오에 추가하세요. 수동 스모크 테스트를 프롬프트 변경마다 실행 가능한 회귀 테스트로 전환할 수 있습니다. 이 패턴은 QA 엔지니어를 위한 API 테스트 가이드에서 더 자세히 다룹니다.
오류 처리 및 속도 제한
Gemini 오류 응답은 최상위 error 객체에 code, status, message를 포함합니다.
| 코드 | 상태 | 의미 | 해결책 |
|---|---|---|---|
| 400 | INVALID_ARGUMENT |
잘못된 요청 본문, 역할, 빈 contents
|
전송 전에 요청 본문을 검증합니다. |
| 401 | UNAUTHENTICATED |
키 누락 또는 취소 |
GEMINI_API_KEY를 다시 설정하고 AI Studio 키 상태를 확인합니다. |
| 403 | PERMISSION_DENIED |
프로젝트 액세스 또는 결제 문제 | 프로젝트 설정과 결제 상태를 확인합니다. |
| 429 | RESOURCE_EXHAUSTED |
속도 제한 또는 일일 할당량 초과 | 지터가 있는 백오프를 적용하고 요청을 조정하거나 계층을 변경합니다. |
| 500 | INTERNAL |
일시적 서버 오류 | 지수 백오프로 재시도합니다. |
| 503 | UNAVAILABLE |
서비스 과부하 | 몇 초 후 재시도하고 Vertex에서는 다른 리전도 고려합니다. |
운영 환경에서는 다음 세 가지를 기본으로 적용하세요.
- 모든 호출을 재시도 헬퍼로 감싸고, 429 및 5xx에 지터가 있는 지수 백오프를 적용합니다.
- 속도 제한 수치를 코드에 임의로 고정하지 마세요. 계층별 제한은 바뀔 수 있으므로 Gemini API 가격 및 제한 페이지에서 현재 값을 확인하고 할당량 80% 지점에 알림을 설정하세요.
- 모델 ID를 환경 변수로 관리하세요. 3.7 Flash 전환 후 프롬프트 동작에 문제가 생기면 배포 없이
gemini-3.6-flash로 롤백할 수 있습니다.
FAQ
Gemini 3.7 Flash는 무료로 사용할 수 있나요?
AI Studio에는 프로토타이핑에 충분한 일일 할당량을 제공하는 무료 등급이 있습니다. 유료 초기 요금은 2026년 12월 31일까지 입력 토큰 100만 개당 $0.75입니다. 무료 등급과 제한 사항은 무료 Gemini API 액세스 가이드에서 확인할 수 있습니다.
AI Studio와 Vertex AI 호출의 차이는 무엇인가요?
모델과 요청 본문은 같지만 운영 경로가 다릅니다.
- AI Studio:
generativelanguage.googleapis.com, API 키 인증 - Vertex AI:
aiplatform.googleapis.com, OAuth 인증, IAM, 감사 로그, 리전별 엔드포인트
AI Studio에서 빠르게 시작하고 실제 트래픽 운영 단계에서 Vertex AI로 전환하세요.
Gemini 3.7 Flash에 이미지, 오디오, PDF를 보낼 수 있나요?
네. 텍스트, 이미지, 비디오, 오디오, PDF를 contents 배열의 파트로 보낼 수 있습니다. 데이터는 base64로 인라인하거나 Files API 참조로 전달합니다. 출력은 텍스트 전용입니다.
컨텍스트 윈도우와 출력 제한은 얼마나 되나요?
입력은 1M 토큰, 출력은 최대 64k 토큰입니다. 128k-needle 검색 점수 97.0%는 긴 컨텍스트 회상 성능을 보여주지만, 입력 토큰에도 비용이 발생하므로 긴 문서는 필요에 따라 청크로 나누는 것이 좋습니다.
Gemini 3.6 Flash에서 업그레이드해야 하나요?
에이전트와 코딩 워크로드라면 벤치마크 격차가 크므로 업그레이드를 검토할 만합니다. 모델 ID 교체만으로 시작할 수 있지만, 운영 트래픽 전환 전 회귀 테스트는 필요합니다. 동작 차이와 점검 항목은 3.6에서 3.7 Flash 마이그레이션 가이드를 참고하세요.
3.7 Flash가 스택에 적합한 위치
Gemini 3.7 Flash는 성능은 높아지고 초기 가격은 낮아진 모델입니다. 2026년 말까지는 DeepSWE에서 16점 더 높고 AutomationBench에서 거의 두 배 높은 점수를 보이는 모델을 3.6 Flash 출시 요금의 절반으로 사용할 수 있습니다.
권장하는 기본 전략은 다음과 같습니다.
- 에이전트 루프, 코드 작업, 문서 추출을 우선 3.7 Flash로 라우팅합니다.
- 초기 요금 종료 시점인 2026년 12월 31일을 비용 계획에 반영합니다.
- 모델 ID를 환경 변수로 관리해 3.6 Flash 롤백 경로를 유지합니다.
- cURL로 응답 형태를 확인합니다.
- Apidog에서 Gemini 스펙을 가져오고 키를 한 번 바인딩한 뒤, 동기·스트리밍·도구 호출 요청을 검증합니다.
- 요청이 안정화된 뒤 Python 또는 Node.js SDK 코드로 포팅합니다.
Top comments (0)