Gemini 3.5 Flash API는 2026년 5월 19일 모델 출시와 함께 공개되었습니다. 현재 3.5 제품군 중 유일하게 Flash 버전만 사용할 수 있으며, Pro 버전은 6월에 출시됩니다. 이 가이드에서는 Flash를 위한 완벽한 개발자 설정 과정을 안내합니다: 키 얻기, 첫 호출, 다중 모드 입력 처리, 스트리밍, 도구 사용, 그리고 Apidog를 이용한 전체 기능의 올바른 테스트.
Gemini API를 이전에 사용해 본 적이 있다면 패턴은 변경되지 않았습니다. 유일하게 새로운 부분은 모델 이름 문자열인 gemini-3.5-flash입니다. 처음 사용하는 경우에도 약 10분 안에 Flash 요청을 작동시킬 수 있습니다.
Gemini 3.5 Flash API로 얻을 수 있는 것
첫째 날에 중요한 세 가지:
gemini-3.5-flash: 지금 바로 사용 가능, 빠르고 저렴하며 다중 모드 지원- 동일한 OpenAPI 스타일 엔드포인트: 이미 Gemini 3 또는 3.1을 호출하는 프로젝트에 바로 적용 가능
- AI Studio의 무료 등급: 신용 카드 없이 하루 약 1,500회 요청
Flash API를 통해 제공되는 기능:
- 100만 토큰 입력 컨텍스트, 6만 4천 토큰 출력
- 텍스트 + 이미지 입력, 텍스트 + 구조화된 출력
- 네이티브 함수 호출 및 도구 사용 (MCP Atlas 83.6%)
- 스트리밍 응답 (다른 최신 모델보다 초당 출력 토큰 약 4배 빠름)
- Google의 MRCR v2 표에서 최상위권의 긴 컨텍스트 검색 점수
- 차트 및 문서 추론 (CharXiv 84.2%)
토큰당 요금 및 배치 모드 할인에 대한 자세한 가격 정보는 Gemini 3.5 Flash 가격 가이드를 참조하세요.
1단계: Gemini 3.5 Flash API 키 받기
무료 할당량을 원하시는지 유료 스케일을 원하시는지에 따라 두 가지 경로가 있습니다.
경로 A, Google AI Studio (무료 등급)
- aistudio.google.com으로 이동
- Google 계정으로 로그인
- 왼쪽 탐색 메뉴에서 API 키 받기 클릭
- 기존 프로젝트를 선택하거나 새 프로젝트 생성
- API 키 생성 클릭 후 복사
이는 무료 Gemini API 키 가이드에서 다룬 것과 동일한 흐름입니다. 이 키는 무료 일일 할당량으로 gemini-3.5-flash에 즉시 작동합니다.
경로 B, Vertex AI (프로덕션)
청구 및 감사 로그가 있는 프로덕션 워크로드의 경우:
- Google Cloud Console에서 Vertex AI API 활성화
aiplatform.user권한으로 서비스 계정 생성- JSON 자격 증명 다운로드
gcloud auth application-default login또는 JSON 파일을 통해 인증
Vertex는 약간 다른 SDK 패턴으로 Flash를 라우팅합니다. 대부분의 팀은 AI Studio에서 시작하여 조직 제어가 필요할 때 마이그레이션합니다.
2단계: SDK 설치
공식 Google GenAI SDK는 Python, Node.js, Go, Java용으로 제공됩니다. 언어를 선택하세요:
# Python
pip install -U google-genai
# Node.js
npm install @google/genai
# Go
go get google.golang.org/genai
REST 엔드포인트를 직접 호출하는 경우 SDK가 전혀 필요하지 않습니다. 아래 curl 예시를 참조하세요.
3단계: 첫 번째 Flash 호출하기
Python
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="Explain how OAuth 2.0 PKCE flow works in 3 short paragraphs."
)
print(response.text)
Node.js
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const response = await ai.models.generateContent({
model: "gemini-3.5-flash",
contents: "Explain how OAuth 2.0 PKCE flow works in 3 short paragraphs.",
});
console.log(response.text);
curl
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts": [{"text": "Explain how OAuth 2.0 PKCE flow works in 3 short paragraphs."}]
}]
}'
이것이 Flash의 기본 경로입니다. 여기서부터 실제로 필요한 기능을 추가할 수 있습니다.
스트리밍 응답
Flash의 출력은 빠릅니다. 스트리밍은 사용자가 그 속도를 체감할 수 있게 합니다.
Python
stream = client.models.generate_content_stream(
model="gemini-3.5-flash",
contents="Write a 5-step tutorial on writing a REST API client in Go."
)
for chunk in stream:
print(chunk.text, end="", flush=True)
Node.js
const stream = await ai.models.generateContentStream({
model: "gemini-3.5-flash",
contents: "Write a 5-step tutorial on writing a REST API client in Go.",
});
for await (const chunk of stream) {
process.stdout.write(chunk.text);
}
원시 REST 호출의 경우 엔드포인트가 :generateContent에서 :streamGenerateContent로 변경됩니다.
Flash를 이용한 다중 모드 입력
Gemini 3.5 Flash는 텍스트와 함께 이미지를 처리합니다. CharXiv 추론 점수 84.2%는 실제이며, 이 모델에서 차트 이해가 실제로 작동합니다.
Python (디스크의 이미지)
import os
from google import genai
from google.genai import types
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
with open("dashboard.png", "rb") as f:
image_bytes = f.read()
response = client.models.generate_content(
model="gemini-3.5-flash",
contents=[
types.Part.from_bytes(data=image_bytes, mime_type="image/png"),
"Extract every metric in this dashboard as a JSON object."
]
)
print(response.text)
지원되는 MIME 타입: image/png, image/jpeg, image/webp, image/heic, image/heif. PDF 및 동영상도 types.Part.from_uri()를 통해 작동합니다.
Flash를 이용한 함수 호출 및 도구 사용
도구 호출은 Flash가 이전 버전과 차별화되는 지점입니다. MCP Atlas 점수 83.6%는 Flash가 3.1 세대보다 더 안정적으로 올바른 도구를 선택한다는 것을 의미합니다.
Python
from google.genai import types
weather_tool = types.Tool(
function_declarations=[{
"name": "get_current_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["city"]
}
}]
)
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="What's the weather in Singapore right now?",
config=types.GenerateContentConfig(tools=[weather_tool])
)
for part in response.candidates[0].content.parts:
if part.function_call:
print(f"Call: {part.function_call.name}")
print(f"Args: {dict(part.function_call.args)}")
Flash는 이름과 인수를 포함하는 function_call 객체를 반환합니다. 함수를 로컬에서 실행하고, 결과를 다시 보내고, 대화를 계속합니다. 이 패턴은 팀에서 이미 Gemini 3 Flash API와 함께 사용하는 것과 일치합니다.
구조화된 출력 (JSON 모드)
응답 MIME 타입과 스키마를 설정하여 Flash에서 JSON 출력을 강제할 수 있습니다:
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="List 3 popular API testing tools with their pricing.",
config=types.GenerateContentConfig(
response_mime_type="application/json",
response_schema={
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"price_per_month": {"type": "number"},
"free_tier": {"type": "boolean"}
},
"required": ["name", "free_tier"]
}
}
)
)
import json
data = json.loads(response.text)
모든 호출에서 유효성 검사된 JSON. 정규식 파싱이나 재시도 루프가 필요 없습니다.
가격 (2026년 5월 기준)
gemini-3.5-flash의 종량제 요금:
| 등급 | 입력 | 출력 |
|---|---|---|
| 표준 | ~$1.50 / 100만 토큰 | ~$9.00 / 100만 토큰 |
| 캐시된 입력 | 할인 요율 | 해당 없음 |
| 배치 모드 | ~50% 할인 | ~50% 할인 |
배치 워크로드의 경우, Gemini API 배치 모드는 실시간 지연 시간이 필요 없는 작업에 대해 50% 할인을 제공합니다. 규모 확장을 결정하기 전에 확인해 볼 가치가 있습니다.
일일 SaaS 워크로드 및 에이전트 루프에 대한 실제 비용 시나리오를 포함한 전체 가격 계산은 Flash 가격 분석을 참조하세요. 공식 Google 참조 자료는 Gemini 개발자 API 가격을 참조하세요.
Apidog로 Gemini 3.5 Flash 통합 테스트하기
작동하는 SDK 호출은 첫 번째 단계일 뿐입니다. 프로덕션 통합은 스트리밍 청크, 도구 호출 유효성 검사, 다중 모드 페이로드, 오류 재시도, 속도 제한과 같은 복잡한 부분을 처리해야 합니다. 여기서 적절한 테스트 설정이 빛을 발합니다.
Apidog는 단일 작업 공간에서 Gemini Flash API의 전체 표면을 처리합니다:
- Flash 엔드포인트를 요청으로 저장: 전체 URL을 붙여넣고,
x-goog-api-key를 첨부한 다음, 전송 버튼을 누르세요. - 모델 버전 간 리플레이: 동일한 요청에서
gemini-3.5-flash를 이전gemini-3-flash로 교체하고, 출력을 비교하세요. - 스트림 응답 인라인 표시: Apidog는 스트리밍된 청크가 도착하는 즉시 청크별 타이밍과 함께 렌더링합니다.
- JSON 스키마 출력 유효성 검사: 프롬프트를 변경할 때 발생하는 불일치를 어설션으로 확인합니다.
- Flash 엔드포인트 모의: API 할당량을 소모하지 않고 다운스트림 코드 테스트를 위한 모의 응답을 생성합니다.
- 에이전트 루프를 위한 테스트 시나리오 구축: 단계별 도구 호출 유효성 검사를 통해 여러 Flash 호출을 연결합니다.
시작하려면 Apidog를 다운로드하고, Flash 엔드포인트를 가리키는 새 요청을 생성한 다음, 이 게시물 앞부분에 있는 curl 스니펫을 가져오세요. 전체 설정은 약 2분 정도 걸립니다.
오류 처리 및 속도 제한
Flash의 오류 모델은 간단합니다. 중요한 코드:
- 400: 잘못된 요청 (대부분 잘못 구성된
contents배열 또는 지원되지 않는 MIME 타입) - 401: 잘못된 API 키
- 403: 할당량 소진 또는 모델 비활성화
- 429: 속도 제한 (대기 후 재시도)
- 500/503: 서버 측 오류, 지수 백오프를 사용하여 재시도
재시도 루프로 Flash 호출을 감싸세요:
import time
from google import genai
def call_with_retry(client, model, prompt, max_retries=3):
for attempt in range(max_retries):
try:
return client.models.generate_content(model=model, contents=prompt)
except Exception as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)
무료 등급 할당량은 매일 초기화됩니다 (Flash의 경우 분당 15회 요청, 하루 약 1,500회). 프로덕션 등급 할당량은 분당 및 일일 단위로 초기화됩니다. 처리량이 많은 작업의 경우, 배치 모드 경로를 확인하거나 제한에 도달했을 때 Gemini 3 Flash로 계층화된 대체 방식을 사용하세요.
Gemini 3.1에서 3.5 Flash로 마이그레이션
대부분의 프로젝트는 정확히 하나의 문자열, 즉 모델 이름을 변경해야 합니다.
# Before
model="gemini-3.1-pro" # or gemini-3.1-flash
# After
model="gemini-3.5-flash"
교체 후 확인해야 할 사항:
- 도구 스키마 일치 여부 (대부분의 호출에서 일치하지만, 평가를 다시 실행하세요)
- 출력 속도 (Flash가 약 4배 빠르게 스트리밍되므로 스트리밍 UI에 스로틀링이 필요할 수 있습니다)
- 토큰 예산 (동일한 1M / 64K 상한이지만 모델이 더 조밀하여 특정 프롬프트가 더 적은 출력 토큰을 사용할 수 있습니다)
- 거부 패턴 (안전 가드레일이 더 엄격합니다; 특이 사례에서 다른 거부 유형을 예상하세요)
더 심층적인 마이그레이션 설명은 Gemini 3.1 Pro API 가이드에서 SDK 패턴을 다루고 있으며, 모든 것이 계속 적용됩니다.
일반적인 Flash 패턴
긴 컨텍스트 문서 분석
with open("large_report.pdf", "rb") as f:
pdf_bytes = f.read()
response = client.models.generate_content(
model="gemini-3.5-flash",
contents=[
types.Part.from_bytes(data=pdf_bytes, mime_type="application/pdf"),
"Summarize the financial outlook from this report in 5 bullet points."
]
)
Flash의 100만 토큰 컨텍스트는 청킹 없이 전체 PDF를 처리합니다.
도구 호출을 이용한 에이전트 루프
conversation = [{"role": "user", "parts": [{"text": "Book me a flight to Tokyo"}]}]
while True:
response = client.models.generate_content(
model="gemini-3.5-flash",
contents=conversation,
config=types.GenerateContentConfig(tools=[flight_search_tool, booking_tool])
)
part = response.candidates[0].content.parts[0]
if not part.function_call:
print(part.text)
break
result = execute_tool(part.function_call)
conversation.append({"role": "model", "parts": [part]})
conversation.append({"role": "user", "parts": [{"function_response": result}]})
이것은 Flash의 Terminal-Bench 2.1 점수(76.2%)가 측정하는 루프 패턴입니다. 실제 에이전트 실행이 작동합니다.
자주 묻는 질문 (FAQ)
Gemini 3.5 Flash API에 무료 등급이 있나요? 네, Google AI Studio를 통해 일일 할당량(하루 약 1,500회 요청)이 제공됩니다. 신용 카드는 필요 없습니다.
Flash는 OpenAI 호환 엔드포인트를 지원하나요? 네. Google은 /v1beta/openai/에서 OpenAI 호환 심을 제공합니다. base_url을 설정하고 Gemini 키를 사용하여 모든 OpenAI SDK를 연결할 수 있습니다. 모델 이름은 gemini-3.5-flash로 유지됩니다.
LangChain 또는 LlamaIndex와 Flash를 함께 사용할 수 있나요? 네, 둘 다 네이티브 Gemini 통합을 제공합니다. 각 래퍼에서 model="gemini-3.5-flash"를 전달하세요.
Gemini 3.5 Pro는 언제 출시되나요? Google의 출시 발표에 따르면 2026년 6월입니다. 그때까지 Flash는 유일하게 사용 가능한 3.5 변형입니다.
Flash의 최대 이미지 크기는 얼마인가요? 권장 크기는 3072×3072입니다. 더 큰 이미지는 리샘플링됩니다. OCR 작업이 많은 경우, Gemini 2.0 Flash OCR 워크플로우를 참조하세요. 동일한 패턴이 적용됩니다.
Apidog에서 스트리밍 엔드포인트를 어떻게 테스트하나요? 요청을 열고, 엔드포인트 접미사로 :streamGenerateContent를 설정하면 Apidog가 도착하는 SSE 청크를 렌더링합니다. 불완전한 응답 디버깅에 유용합니다.
API 로그는 어디서 볼 수 있나요? AI Studio의 "활동" 섹션 또는 프로덕션 배포의 경우 Vertex AI의 "로그 탐색기"에서 확인할 수 있습니다.
먼저 만들 것
Flash로 첫 주에 배포할 가치가 있는 시작 프로젝트 목록:
- PDF Q&A 봇: 100만 컨텍스트 창에 PDF를 넣고 질문하며, 인용된 답변 반환
- 차트-JSON 파이프라인: 대시보드 스크린샷을 입력하고 구조화된 데이터 추출
- 고객 지원 에이전트: CRM에 대한 함수 호출, 무인 실행
- 코드 리뷰 어시스턴트: 다중 파일 diff 컨텍스트, 심각도 등급을 포함한 구조화된 출력
- 내부 검색 에이전트: 100만 컨텍스트와 내부 API에 대한 도구 호출 결합
각 프로젝트에 대해 동일한 테스트 흐름이 적용됩니다: 프롬프트를 구축하고, SDK 호출로 래핑하고, Apidog로 응답 형태를 검증한 다음, 배포합니다.