Gemini 3.7 플래시 API 사용법?

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 워크플로우의 새로운 모든 것을 다룹니다.

다운로드 버튼

요약

모델 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`를 사용합니다. 요청 본문은 Google의 `contents`와 `generationConfig` 스키마를 유지합니다.
애플리케이션 코드를 작성하기 전에 Apidog에서 엔드포인트를 테스트하세요: 스펙을 가져오고, 키를 환경 변수로 저장하고, SSE 청크가 실시간으로 렌더링되는 것을 확인하세요.

Gemini 3.7 Flash의 용도

Flash 모델은 속도와 가격을 위해 약간의 최고 지능을 희생하며, 3.7은 이전 어떤 출시작보다 이 절충점을 더 좁혔습니다. 3주 간격으로는 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점 상승했습니다.

이 수치들을 워크로드 적합성에 대한 신호로 읽으세요. 다음 경우에 3.7 Flash를 사용하세요:

에이전트 루프를 실행하는 경우. AutomationBench 점수가 거의 두 배로 증가했으며, Google은 이 모델이 “다단계 계획 및 도구 호출에 대해 더 부지런히 생각한다”고 말합니다. 짧고 도구 의존적인 단계가 많은 에이전트 파이프라인이 목표 사용 사례입니다.
코드를 생성하거나 디버깅하는 경우. Google은 3.7이 디버깅에 더 뛰어나고 첫 시도에 배포 가능한 코드를 생성할 수 있는 능력이 더 뛰어나다고 주장합니다. DeepSWE 및 FrontierCode의 개선이 이를 뒷받침합니다.
문서를 처리하는 경우. GDP.pdf는 22.0%에서 34.0%로 상승했으며, PDF는 일등 입력 유형입니다. 긴 컨텍스트 검색도 견고합니다: 128k-needle 테스트에서 97.0%.
예산 내에서 멀티모달 입력이 필요한 경우. 텍스트, 이미지, 비디오, 오디오 및 PDF는 모두 동일한 contents 배열을 통해 입력됩니다.

법률 도메인 Harvey LAB-AA 점수 90.7%와 업데이트된 CBRN 및 사이버 보호 기능을 포함한 전체 기능 요약은 Gemini 3.7 Flash의 새로운 기능을 참조하세요. 알아둘 만한 맥락: Gemini 3.5 Pro는 여전히 지연되고 있으며, Axios는 Google이 다음 플래그십보다 Flash 업데이트를 의도적으로 먼저 출시하고 있다고 보도합니다.

API 키 얻기

두 가지 경로가 있으며, 동일하지 않습니다.

AI Studio (빠른 경로). aistudio.google.com/apikey를 열고, API 키 가져오기를 클릭하고, Google Cloud 프로젝트를 선택한 다음, 문자열을 복사하세요. 이 키는 `generativelanguage.googleapis.com`에 즉시 작동하며, 무료 등급은 프로토타입 제작에 충분한 할당량을 제공합니다. Gemini 3.7 Flash는 160개 이상의 국가에서 사용할 수 있습니다.

Vertex AI (운영 경로). 인프라가 GCP에 있다면 Vertex를 사용하세요. 인증은 API 키에서 OAuth(서비스 계정 또는 단기 토큰)로 전환되며, 호출은 `aiplatform.googleapis.com`을 통해 라우팅되고, IAM, 감사 로그 및 리전별 엔드포인트를 얻을 수 있습니다. 모델 ID와 요청 본문은 동일하게 유지되며, URL과 인증 메커니즘만 변경됩니다.

AI Studio에서 프로토타입을 만들고, 운영 트래픽 전에 Vertex로 이동하세요. 어떤 방법이든, 키를 한 번 내보내세요:

export GEMINI_API_KEY="AIza..."

운영 환경에서 키를 하드코딩하거나 `?key=` 쿼리 매개변수로 전달하지 마세요; 쿼리 문자열은 서버 로그에 남게 됩니다.

엔드포인트 및 인증

동기 호출을 위한 기본 엔드포인트:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent

스트리밍은 메서드 접미사를 교환하고 SSE 플래그를 추가합니다:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:streamGenerateContent?alt=sse

인증은 하나의 헤더입니다: `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배 비용이 듭니다. 스키마에 유의하세요: Google은 `role`과 `parts`를 가진 `contents`를 사용하며, OpenAI의 `messages` 형태가 아닙니다. 다른 공급자로부터 포팅하는 경우 이 매핑을 먼저 올바르게 설정하세요.

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)

멀티모달 입력은 동일한 `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 벤치마크 개선(22.0%에서 34.0%)은 바로 이 워크로드에서 나타납니다: 복잡한 실제 문서에서 구조화된 정보 추출.

Node.js 빠른 시작

Node SDK는 `@google/generative-ai`이며 Python 형태를 따릅니다:

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 라인은 보이는 것보다 더 중요합니다. 이는 후보를 파싱 가능한 객체로 강제하여, 다운스트림 코드가 자유 형식 텍스트를 건드리지 않도록 합니다. `responseMimeType: "application/json"`과 함께 사용하지 않으면 무시됩니다.

스트리밍

채팅 UI 및 사용자 대면 애플리케이션의 경우 스트리밍을 사용하세요. Python에서는 `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`를 호출하고 서버 전송 이벤트를 파싱하세요. 각 `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 스크립트 내에서 프롬프트 반복은 느리고 비용이 많이 듭니다: 편집, 재실행, 스크롤, 반복, 그리고 모든 주기마다 토큰 비용이 발생합니다. 더 빠른 루프는 먼저 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`와 A/B 테스트를 하고 싶을 때, 수많은 저장된 요청에서 URL을 편집하는 대신 하나의 변수만 변경하면 됩니다.
시각적 JSON 편집기에서 `contents` 배열을 구성합니다. 중첩된 파트가 깔끔하게 렌더링되며, 스키마 유효성 검사가 400 오류로 단일 토큰을 소모하기 전에 잘못된 본문을 잡아냅니다.
스트리밍 엔드포인트를 호출합니다. Apidog는 SSE 청크를 실시간으로 렌더링하므로, SDK가 응답을 볼 방식 그대로, 지연 시간을 포함하여 응답이 구성되는 것을 확인할 수 있습니다.
좋은 응답을 예시로 저장합니다. 나중에 테스트를 실행할 때 실제 API 대신 고정 데이터를 사용합니다. 이것이 전체 워크플로우에서 가장 큰 단일 토큰 절약 방법입니다.

요청이 저장되면, `finishReason`, 응답 스키마 및 `usageMetadata` 토큰 개수에 대한 어설션을 사용하여 테스트 시나리오로 연결합니다. 이는 수동 스모크 테스트를 모든 프롬프트 변경 시 실행할 수 있는 회귀 테스트 스위트로 전환합니다. QA 팀이 사용하는 동일한 패턴은 QA 엔지니어를 위한 API 테스트 가이드에 설명되어 있습니다.

오류 처리 및 속도 제한

Gemini 오류는 `code`, `status`, `message`를 포함하는 최상위 `error` 객체를 반환합니다. 다음은 발생할 수 있는 오류들입니다:

코드	상태	의미	해결책
400	`INVALID_ARGUMENT`	잘못된 본문, 잘못된 역할, 빈 `contents`.	보내기 전에 Apidog에서 본문을 검증하세요.
401	`UNAUTHENTICATED`	누락되었거나 취소된 키.	`GEMINI_API_KEY`를 다시 내보내고; AI Studio에서 키가 활성 상태인지 확인하세요.
403	`PERMISSION_DENIED`	프로젝트에 대한 액세스 또는 결제 부족.	프로젝트 설정 및 결제 상태를 확인하세요.
429	`RESOURCE_EXHAUSTED`	속도 제한 또는 일일 할당량 초과.	지터로 후퇴(back off), 요청 일괄 처리, 또는 계층 업그레이드.
500	`INTERNAL`	일시적인 서버 오류.	지수 백오프를 사용하여 다시 시도하세요.
503	`UNAVAILABLE`	서비스 과부하.	몇 초 후에 다시 시도하세요; Vertex에서는 다른 리전을 시도하세요.

운영 환경을 안정적으로 유지하는 세 가지 습관:

429 및 5xx 오류를 지터가 있는 지수 백오프로 처리하는 재시도 헬퍼로 모든 호출을 래핑하세요. SDK는 자체적으로 몇 번 재시도하지만, 얇은 래퍼는 여러분이 제어할 수 있는 로깅 및 회로 차단 기능을 제공합니다.
속도 제한 수치를 임의로 정하지 마세요. 제한은 계층별로 다르며 시간이 지남에 따라 변경됩니다; Gemini API 가격 및 제한 페이지에서 실시간 값을 확인하고 할당량의 80%에서 알림을 설정하세요.
모델 ID를 환경 변수 뒤에 고정하세요. 3.7의 동작 변경으로 프롬프트가 손상되면, `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는 `aiplatform.googleapis.com`에 OAuth를 사용하고 IAM, 감사 로깅 및 리전별 엔드포인트를 추가합니다. AI Studio에서 시작하여 트래픽이 실제가 되면 Vertex로 전환하세요.

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로 라우팅하고, 예산 계획을 위해 초기 요금 기간을 염두에 두며, 환경 변수 뒤에 3.6으로의 롤백 경로를 유지하세요.

위의 cURL 호출부터 시작하여 응답 형태를 확인한 다음, 애플리케이션 코드를 작성하기 전에 요청을 API 클라이언트로 이동하세요. Apidog를 다운로드하여 Gemini 스펙을 가져오고, 키를 한 번 바인딩하고, 단일 작업 공간에서 동기, 스트리밍 및 도구 호출 요청을 테스트하세요. 프롬프트가 올바르면, 와이어 트래픽이 어떻게 보이는지 이미 알고 있으므로 Python 또는 Node 포팅은 몇 분밖에 걸리지 않습니다.