Google의 Gemini 3.1 Flash Lite는 2026년 3월 3일에 출시되었으며, Gemini 라인업에서 가장 빠르고 저렴한 모델입니다. 백만 입력 토큰당 $0.25, 백만 출력 토큰당 $1.50의 비용으로, 예산을 초과하지 않고 대규모 AI가 필요한 개발자를 위해 만들어졌습니다.
이 가이드에서는 액세스 권한을 얻고, API 키를 설정하고, 요청을 시작하는 방법을 정확히 보여줍니다. 10분 안에 작동하는 코드를 만들 수 있습니다.
요약
빠른 설정:
- Google AI Studio로 이동
- 프로젝트를 생성하고 API 키 생성
- SDK 설치:
pip install google-generativeai - 모델
gemini-3.1-flash-lite를 사용하여 첫 번째 요청 보내기 - 더 쉬운 디버깅 및 팀 협업을 위해 Apidog에서 테스트
가격: 입력 토큰 1백만 개당 $0.25, 출력 토큰 1백만 개당 $1.50
속도: Gemini 2.5 Flash보다 2.5배 빠름
무료 티어: 미리 보기 기간 동안 입력 토큰 1백만 개 무료
Gemini 3.1 Flash Lite란 무엇인가요?
Gemini 3.1 Flash Lite는 고용량 애플리케이션을 위해 설계된 Google의 최신 AI 모델입니다. Gemini 2.5 Flash보다 2.5배 빠르고 출력 속도가 45% 향상되었으며, GPQA Diamond 벤치마크에서 86.9%, MMMU Pro 벤치마크에서 76.8%를 기록했습니다.
이 모델에는 요청별로 조정할 수 있는 사고 수준이 포함되어 있습니다. 간단한 작업에는 낮게 설정하고, 복잡한 추론에는 높게 설정하세요. 이러한 유연성을 통해 다양한 워크로드를 처리하면서 비용을 최적화할 수 있습니다.
개인 개발자는 Google AI Studio를 통해, 기업은 Vertex AI를 통해 사용할 수 있습니다.
사전 요구 사항
시작하기 전에 다음 사항을 확인하세요:
- Google 계정
- Python 3.7+ 또는 Node.js 14+ 설치
- REST API에 대한 기본적인 이해
- (선택 사항) API 테스트를 위한 Apidog 설치
1단계: Google AI Studio 계정 생성
Google AI Studio는 개발을 위해 Gemini 모델에 액세스하는 가장 빠른 방법입니다.
- aistudio.google.com으로 이동
- Google 계정으로 로그인
- 서비스 약관 동의
- AI Studio 대시보드로 이동합니다.
인터페이스에는 사용 가능한 모델, API 사용량 및 빠른 시작 템플릿이 표시됩니다. Flash Lite는 모델 드롭다운에서 gemini-3.1-flash-lite로 나타납니다.
2단계: API 키 생성
API 키를 사용하면 Gemini API에 대한 요청을 인증할 수 있습니다.
- 오른쪽 상단 모서리에 있는 API 키 가져오기를 클릭하세요.
- 새 프로젝트에서 API 키 생성(또는 기존 프로젝트 선택)을 선택하세요.
- Google이 새 Cloud 프로젝트를 생성하고 키를 생성합니다.
- API 키를 복사하세요. `AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX`와 같이 생겼습니다.
- 안전하게 보관하세요. 다시 볼 수 없습니다.
보안 팁: API 키를 버전 관리에 커밋하지 마세요. 환경 변수 또는 비밀 관리 도구를 사용하세요.
3단계: SDK 설치
Google은 Python 및 Node.js용 공식 SDK를 제공합니다.
Python
pip install google-generativeai
Node.js
npm install @google/generative-ai
SDK는 인증, 요청 형식 지정 및 응답 구문 분석을 처리합니다. 원한다면 REST API를 직접 사용할 수도 있습니다.
4단계: 첫 번째 요청 보내기
Flash Lite에 간단한 프롬프트를 보내봅시다.
Python 예제
import google.generativeai as genai
import os
# Configure API key
genai.configure(api_key=os.environ.get('GOOGLE_API_KEY'))
# Initialize the model
model = genai.GenerativeModel('gemini-3.1-flash-lite')
# Generate content
response = model.generate_content('Explain REST APIs in one sentence.')
print(response.text)
Node.js 예제
const { GoogleGenerativeAI } = require("@google/generative-ai");
// Initialize with API key
const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
async function run() {
// Get the model
const model = genAI.getGenerativeModel({ model: "gemini-3.1-flash-lite" });
// Generate content
const result = await model.generateContent("Explain REST APIs in one sentence.");
const response = await result.response;
const text = response.text();
console.log(text);
}
run();
cURL 예제 (REST API)
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-lite:generateContent?key=YOUR_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [{
"parts": [{
"text": "Explain REST APIs in one sentence."
}]
}]
}'
이 예제 중 하나를 실행하면 몇 초 안에 응답을 받을 수 있습니다. 모델은 프롬프트에 답하는 명확하고 간결한 텍스트를 반환합니다.
5단계: Apidog으로 테스트
Apidog는 시각적 인터페이스, 팀 협업 및 자동 문서화를 통해 API 테스트를 더 쉽게 만듭니다.
Gemini API에 Apidog를 사용하는 이유?
- 시각적 요청 빌더 - cURL 명령어를 작성할 필요 없음
- 환경 변수 - 개발/운영 API 키 간에 쉽게 전환
- 응답 유효성 검사 - 프로덕션에 도달하기 전에 오류 포착
- 팀 공유 - 팀과 API 컬렉션 공유
- 자동 문서화 - 요청에서 문서 생성
구문 강조 표시, 응답 시간 및 상태 코드가 포함된 응답이 오른쪽 패널에 표시됩니다.
환경 변수로 저장
- Apidog에서 환경(Environments)으로 이동
- 새 환경 생성 (예: "Gemini Dev")
- 변수 추가:
GOOGLE_API_KEY= 실제 API 키 - 요청에서
{{GOOGLE_API_KEY}}사용
이제 요청을 변경하지 않고도 환경을 전환할 수 있습니다. 개발, 스테이징 및 프로덕션 키를 관리하는 데 완벽합니다.
요청 형식 이해
Gemini API는 특정 JSON 구조를 사용합니다.
기본 요청 구조
{
"contents": [{
"parts": [{
"text": "Your prompt here"
}]
}]
}
사고 수준 포함
{
"contents": [{
"parts": [{
"text": "Generate API documentation for a user authentication endpoint"
}]
}],
"generationConfig": {
"thinkingLevel": "high"
}
}
사고 수준: low, medium, high
- 낮음(Low): 빠르고 간단한 응답
- 중간(Medium): 균형 잡힌 추론
- 높음(High): 심층 분석, 복잡한 작업
시스템 지침 포함
{
"systemInstruction": {
"parts": [{
"text": "You are an API documentation expert. Write clear, concise docs."
}]
},
"contents": [{
"parts": [{
"text": "Document this endpoint: POST /api/users"
}]
}]
}
시스템 지침은 대화 내의 모든 요청에서 모델의 동작을 안내합니다.
응답 형식
API는 이 구조를 가진 JSON을 반환합니다:
{
"candidates": [{
"content": {
"parts": [{
"text": "REST APIs are interfaces that let applications communicate over HTTP using standard methods like GET, POST, PUT, and DELETE."
}],
"role": "model"
},
"finishReason": "STOP",
"index": 0,
"safetyRatings": [...]
}],
"usageMetadata": {
"promptTokenCount": 8,
"candidatesTokenCount": 25,
"totalTokenCount": 33
}
}
주요 필드:
candidates[0].content.parts[0].text- 생성된 응답usageMetadata- 청구를 위한 토큰 수finishReason- 생성이 중지된 이유 (STOP, MAX_TOKENS, SAFETY)
일반적인 사용 사례
1. API 문서 생성
import google.generativeai as genai
genai.configure(api_key=os.environ.get('GOOGLE_API_KEY'))
model = genai.GenerativeModel('gemini-3.1-flash-lite')
endpoint_spec = """
POST /api/v1/users
Creates a new user account
Body: { "email": string, "password": string, "name": string }
"""
response = model.generate_content(
f"Generate comprehensive API documentation for this endpoint:\n{endpoint_spec}",
generation_config={"thinkingLevel": "medium"}
)
print(response.text)
2. 요청 유효성 검사
def validate_api_request(request_body):
model = genai.GenerativeModel('gemini-3.1-flash-lite')
prompt = f"""
Validate this API request body and list any issues:
{request_body}
Check for:
- Missing required fields
- Invalid data types
- Security concerns
"""
response = model.generate_content(prompt)
return response.text
# Example usage
request = '{"email": "test@example.com", "password": "123"}'
validation_result = validate_api_request(request)
print(validation_result)
3. 오류 메시지 생성
def generate_user_friendly_error(error_code, technical_message):
model = genai.GenerativeModel('gemini-3.1-flash-lite')
prompt = f"""
Convert this technical error into a user-friendly message:
Error Code: {error_code}
Technical: {technical_message}
Make it clear, actionable, and non-technical.
"""
response = model.generate_content(
prompt,
generation_config={"thinkingLevel": "low"}
)
return response.text
# Example
friendly_error = generate_user_friendly_error(
"AUTH_TOKEN_EXPIRED",
"JWT token validation failed: exp claim is in the past"
)
print(friendly_error)
요청 제한 및 할당량
Flash Lite는 미리 보기 기간 동안 넉넉한 제한을 제공합니다:
무료 티어:
- 입력 토큰 1백만 개 무료
- 분당 15회 요청
- 일일 1,500회 요청
유료 티어:
- 입력 토큰 1백만 개당 $0.25
- 출력 토큰 1백만 개당 $1.50
- 분당 60회 요청
- 일일 제한 없음
Google AI Studio의 사용량 및 청구(Usage & Billing)에서 사용량을 모니터링하세요.
오류 처리
일반적인 오류를 우아하게 처리하세요:
import google.generativeai as genai
from google.api_core import exceptions
genai.configure(api_key=os.environ.get('GOOGLE_API_KEY'))
model = genai.GenerativeModel('gemini-3.1-flash-lite')
def safe_generate(prompt):
try:
response = model.generate_content(prompt)
return response.text
except exceptions.ResourceExhausted:
return "요청 제한을 초과했습니다. 1분 후에 다시 시도하세요."
except exceptions.InvalidArgument as e:
return f"유효하지 않은 요청: {str(e)}"
except exceptions.PermissionDenied:
return "API 키가 유효하지 않거나 만료되었습니다."
except Exception as e:
return f"예기치 않은 오류: {str(e)}"
result = safe_generate("Explain APIs")
print(result)
일반적인 오류:
400 Bad Request- 유효하지 않은 JSON 또는 누락된 필수 필드401 Unauthorized- 유효하지 않은 API 키429 Too Many Requests- 요청 제한 초과500 Internal Server Error- Google 서버에 문제가 발생했습니다.
문제 해결
"API 키가 유효하지 않습니다."
다음 사항을 확인하세요:
- API 키가 올바르게 복사되었는지 (추가 공백 없음)
- Google Cloud Console에서 API 키가 활성화되었는지
- 프로젝트에서 결제가 활성화되었는지
- 올바른 환경 변수 이름을 사용하고 있는지
"모델을 찾을 수 없습니다."
정확한 모델 이름을 사용하고 있는지 확인하세요:
# 올바른 예
model = genai.GenerativeModel('gemini-3.1-flash-lite')
# 잘못된 예
model = genai.GenerativeModel('gemini-flash-lite')
model = genai.GenerativeModel('gemini-3.1-flash')
"요청 제한을 초과했습니다."
분당 요청 제한에 도달했습니다. 해결 방법:
- 지수 백오프 재시도 로직 추가
- 여러 프롬프트를 단일 요청으로 일괄 처리
- 더 높은 제한을 위해 유료 티어로 업그레이드
- 요청 큐잉 구현
느린 응답
Flash Lite는 빠르지만, 지연이 발생한다면:
- 네트워크 연결 확인
- 간단한 작업에는 낮은 사고 수준 사용
- 프롬프트 길이 줄이기
- 긴 출력의 경우 스트리밍 응답 고려
고급: 스트리밍 응답
긴 출력의 경우 토큰이 생성되는 대로 스트리밍하세요:
import google.generativeai as genai
genai.configure(api_key=os.environ.get('GOOGLE_API_KEY'))
model = genai.GenerativeModel('gemini-3.1-flash-lite')
prompt = "Write a detailed explanation of REST API authentication methods"
response = model.generate_content(prompt, stream=True)
for chunk in response:
print(chunk.text, end='', flush=True)
스트리밍은 인지되는 성능을 향상시킵니다. 사용자는 완전한 응답을 기다리지 않고 즉시 출력을 볼 수 있습니다.
비용 최적화 팁
1. 유사한 요청 일괄 처리
# 비용이 많이 듬: 3개의 개별 요청
response1 = model.generate_content("Explain GET")
response2 = model.generate_content("Explain POST")
response3 = model.generate_content("Explain PUT")
# 더 저렴함: 1개의 결합된 요청
combined_prompt = """
이 HTTP 메서드를 설명하세요:
1. GET
2. POST
3. PUT
"""
response = model.generate_content(combined_prompt)
2. 낮은 사고 수준 사용
# 간단한 분류를 위해
response = model.generate_content(
"Is this email spam? 'Buy now!'",
generation_config={"thinkingLevel": "low"}
)
# 복잡한 분석을 위해
response = model.generate_content(
"Analyze this API design and suggest improvements...",
generation_config={"thinkingLevel": "high"}
)
3. 캐싱 구현
반복되는 쿼리에 대한 응답을 캐싱하세요. 간단한 인메모리 캐시는 일반적인 요청에 대해 50% 이상의 비용을 절감할 수 있습니다.
4. 프롬프트 다듬기
불필요한 맥락 제거:
# 장황함 (더 많은 토큰)
prompt = "I would like you to please explain to me what REST APIs are and how they work in detail"
# 간결함 (더 적은 토큰)
prompt = "Explain REST APIs"
보안 고려 사항
1. API 키 보호
- 환경 변수 또는 비밀 관리자에 저장
- 정기적으로 키 회전
- 개발/스테이징/운영용으로 별도의 키 사용
- API 키를 절대 기록하지 마세요
2. 사용자 입력 유효성 검사
def safe_prompt(user_input):
# 잠재적인 주입 시도 제거
cleaned = user_input.replace("Ignore previous instructions", "")
cleaned = cleaned[:1000] # 길이 제한
return f"사용자 질문: {cleaned}"
3. 민감한 데이터 필터링
민감한 정보를 API로 보내지 마세요:
import re
def sanitize_for_ai(text):
# 이메일 주소 제거
text = re.sub(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', '[EMAIL]', text)
# 전화번호 제거
text = re.sub(r'\b\d{3}[-.]?\d{3}[-.]?\d{4}\b', '[PHONE]', text)
# 신용 카드 제거
text = re.sub(r'\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b', '[CARD]', text)
return text
4. 요청 제한 구현
오용으로부터 API 키 보호:
from collections import defaultdict
import time
class RateLimiter:
def __init__(self, max_requests=10, window=60):
self.max_requests = max_requests
self.window = window
self.requests = defaultdict(list)
def allow_request(self, user_id):
now = time.time()
# 오래된 요청 제거
self.requests[user_id] = [
req_time for req_time in self.requests[user_id]
if now - req_time < self.window
]
if len(self.requests[user_id]) < self.max_requests:
self.requests[user_id].append(now)
return True
return False
limiter = RateLimiter(max_requests=10, window=60)
def generate_with_limit(user_id, prompt):
if not limiter.allow_request(user_id):
return "요청 제한을 초과했습니다. 나중에 다시 시도하세요."
model = genai.GenerativeModel('gemini-3.1-flash-lite')
response = model.generate_content(prompt)
return response.text
Flash Lite와 다른 Gemini 모델 비교
| 특징 | Flash Lite | Flash | Pro |
|---|---|---|---|
| 입력 가격 | $0.25/1M | $0.50/1M | $1.25/1M |
| 출력 가격 | $1.50/1M | $3.00/1M | $7.50/1M |
| 속도 | 2.5배 빠름 | 빠름 | 표준 |
| 컨텍스트 창 | 32K 토큰 | 1M 토큰 | 2M 토큰 |
| 최적의 용도 | 고용량, 비용 민감 | 균형 잡힌 | 복잡한 추론 |
다음 경우 Flash Lite를 선택하세요:
- 빠른 응답이 필요할 때
- 비용이 중요할 때
- 요청이 32K 토큰 미만일 때
- 품질 요구 사항이 보통일 때
다음 경우 Flash를 선택하세요:
- 큰 컨텍스트 창이 필요할 때
- 비용보다 품질이 더 중요할 때
다음 경우 Pro를 선택하세요:
- 최대 추론 능력이 필요할 때
- 비용이 문제가 되지 않을 때
- 매우 큰 문서를 다룰 때
Apidog 워크플로 통합
Apidog 사용자는 Flash Lite를 API 개발 워크플로에 통합할 수 있습니다:
1. 테스트 케이스 자동 생성
Flash Lite를 사용하여 API 사양에서 테스트 케이스를 생성하세요:
def generate_test_cases(endpoint_spec):
model = genai.GenerativeModel('gemini-3.1-flash-lite')
prompt = f"""
이 API 엔드포인트에 대한 포괄적인 테스트 케이스를 생성하세요:
{json.dumps(endpoint_spec, indent=2)}
포함:
- 해피 패스 테스트
- 엣지 케이스
- 오류 시나리오
- 경계 조건
테스트 케이스의 JSON 배열 형식으로.
"""
response = model.generate_content(prompt)
return json.loads(response.text)
2. API 응답 유효성 검사
응답이 예상 스키마와 일치하는지 확인:
def validate_response(response_data, expected_schema):
model = genai.GenerativeModel('gemini-3.1-flash-lite')
prompt = f"""
이 API 응답을 스키마와 비교하여 유효성 검사:
응답: {json.dumps(response_data, indent=2)}
스키마: {json.dumps(expected_schema, indent=2)}
불일치 또는 문제를 나열하세요.
"""
response = model.generate_content(
prompt,
generation_config={"thinkingLevel": "low"}
)
return response.text
3. 모의 데이터 생성
실제와 같은 테스트 데이터 생성:
def generate_mock_data(schema, count=10):
model = genai.GenerativeModel('gemini-3.1-flash-lite')
prompt = f"""
이 스키마와 일치하는 {count}개의 실제와 같은 모의 데이터 항목을 생성하세요:
{json.dumps(schema, indent=2)}
JSON 배열로 반환하세요.
"""
response = model.generate_content(prompt)
return json.loads(response.text)
자주 묻는 질문
Gemini 3.1 Flash Lite는 무료인가요?
미리 보기 기간 동안 첫 1백만 개의 입력 토큰은 무료입니다. 그 후에는 입력 토큰 1백만 개당 $0.25, 출력 토큰 1백만 개당 $1.50가 부과됩니다.
Flash Lite는 다른 모델에 비해 얼마나 빠른가요?
Flash Lite는 첫 토큰 생성 시간에서 Gemini 2.5 Flash보다 2.5배 빠르며, 출력 속도에서 45% 더 빠릅니다. 사용 가능한 모델 중 가장 빠른 모델 중 하나입니다.
Flash Lite를 프로덕션에 사용할 수 있나요?
네. "미리 보기"로 표시되어 있지만, 이 모델은 프로덕션 사용에 충분히 안정적입니다. Latitude, Cartwheel, Whering과 같은 초기 사용자들은 이미 대규모로 이 모델을 사용하고 있습니다.
컨텍스트 창 크기는 얼마인가요?
Flash Lite는 최대 32,000개의 토큰 컨텍스트를 지원합니다. 대부분의 API 사용 사례에는 충분하지만, Flash(1백만 토큰) 또는 Pro(2백만 토큰)보다 작습니다.
사고 수준은 어떻게 작동하나요?
사고 수준은 모델이 적용하는 처리량을 제어합니다. 낮은 수준은 빠르고 간단합니다. 높은 수준은 느리지만 더 철저합니다. 분류에는 낮은 수준을, 복잡한 추론에는 높은 수준을 사용하세요.
Apidog와 함께 Flash Lite를 사용할 수 있나요?
네. Apidog는 Gemini를 포함한 모든 REST API와 함께 작동합니다. 더 쉬운 테스트, 팀 협업 및 문서화를 위해 Apidog에서 요청을 설정하세요.
요청 제한을 초과하면 어떻게 되나요?
429 오류가 발생합니다. 지수 백오프 재시도 로직을 구현하거나 더 높은 제한(분당 15회 요청 대신 60회)을 위해 유료 티어로 업그레이드하세요.
내 데이터가 모델 훈련에 사용되나요?
Google 정책에 따르면 API 요청은 모델 훈련에 사용되지 않습니다. 귀하의 데이터는 비공개로 유지됩니다.
Flash Lite를 미세 조정할 수 있나요?
아직은 아닙니다. 일부 Gemini 모델에는 미세 조정이 가능하지만, Flash Lite 출시 시점에는 지원되지 않습니다. 대신 시스템 지침을 사용하여 동작을 안내하세요.
Flash Lite는 GPT-4 Turbo와 어떻게 비교되나요?
Flash Lite는 더 빠르고 저렴하지만, GPT-4 Turbo는 복잡한 작업에 대해 더 강력한 추론 능력을 가지고 있습니다. 고용량 API 워크로드의 경우 Flash Lite가 비용과 속도 면에서 우위에 있습니다.
다음 단계
이제 Gemini 3.1 Flash Lite 사용을 시작하는 데 필요한 모든 것을 갖추었습니다:
- Google AI Studio에서 API 키 받기
- SDK를 설치하고 첫 번째 요청 실행
- 더 쉬운 개발을 위해 Apidog에서 테스트
- 오류 처리 및 재시도 로직 구현
- 비용 최적화를 위해 사용량 모니터링
이 모델은 프로덕션 준비가 되어 있습니다. 가격 책정은 AI를 대규모로 접근 가능하게 합니다. 속도는 사용자들을 만족시킵니다.
지금 빌딩을 시작하세요.