Gemini Pro API는 Google AI Studio에서 생성한 키를 사용하여 Gemini API를 통해 액세스됩니다. 직접 REST 요청을 하려면 모델의 generateContent 엔드포인트를 호출하고, 기존 OpenAI SDK 통합을 사용하는 경우 Google의 OpenAI 호환 기본 URL을 가리키도록 클라이언트를 설정하고 gemini-3.1-pro-preview와 같은 현재 Gemini 모델 ID를 사용하세요. 중요한 점은 "Gemini Pro"가 제품군 검색어이지 영구적인 API 식별자가 아니라는 점입니다. 따라서 프로덕션 애플리케이션은 ID를 고정하기 전에 Google의 현재 모델 목록을 확인해야 합니다.
Gemini Pro API 설정 한눈에 보기
요청을 보내려면 다음 네 가지 값이 필요합니다:
| 설정 | 값 |
|---|---|
| API 키 | Google AI Studio에서 생성 |
| 네이티브 기본 호스트 | https://generativelanguage.googleapis.com |
| 네이티브 API 경로 | /v1beta/models/{model}:generateContent |
| OpenAI 호환 기본 URL | https://generativelanguage.googleapis.com/v1beta/openai/ |
| 예시 모델 ID | gemini-3.1-pro-preview |
Google의 Gemini API 빠른 시작 문서에는 API 키 생성 및 네이티브 요청 패턴이 설명되어 있습니다. OpenAI 호환성 가이드에는 이미 OpenAI Python 또는 JavaScript SDK를 사용하는 애플리케이션을 위한 호환성 기본 URL이 설명되어 있습니다.
Google이 Gemini 특화 기능을 노출하자마자 사용하려면 네이티브 Gemini SDK 또는 REST API를 사용하세요. 이미 OpenAI 스타일 클라이언트가 있고 마이그레이션 작업을 줄이려면 호환성 레이어를 사용하세요. 호환성은 유용하지만 모든 공급자별 옵션이 API 간에 완벽하게 매핑된다는 것을 보장하지는 않습니다.
Gemini용 Google API 키를 얻는 방법
Google AI Studio에서 키를 생성한 후, 소스 코드에 직접 넣지 않고 환경 변수에 저장하세요:
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
이것은 서버 측 자격 증명으로 취급하세요. Git에 커밋하거나, 로그에 출력하거나, 브라우저 JavaScript 또는 모바일 애플리케이션 번들에 포함하지 마세요. 프론트엔드에서 Gemini 출력이 필요한 경우, 사용자 요청을 자체 백엔드로 보내고 백엔드에서 Google API를 호출하도록 하세요.
프로덕션 서비스의 경우, Google Cloud 프로젝트의 소유자, 키 교체 주기, 개별 환경에 대한 별도 자격 증명, 요청 할당량 모니터링 위치도 결정해야 합니다. Google의 API 키 가이드에서는 Gemini API 키가 Google Cloud 프로젝트와 어떻게 연결되는지 설명합니다.
네이티브 Gemini API 엔드포인트 호출 방법
네이티브 REST 경로는 URL에 모델 ID를 포함합니다. 다음 예제는 현재 Pro 미리보기 모델에 간결한 마이그레이션 체크리스트를 반환하도록 요청합니다:
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"parts": [
{
"text": "Create a seven-step checklist for migrating a Python API from one region to two regions. Include rollback checks."
}
]
}
]
}'
응답에는 생성된 콘텐츠가 포함된 후보(candidates)가 포함됩니다. 실제 애플리케이션은 첫 번째 응답 객체를 직접 인덱싱하는 대신 빈 후보 목록, 차단된 콘텐츠, 타임아웃 및 2xx가 아닌 응답을 처리해야 합니다.
URL은 Google의 현재 Gemini API 예제에 표시된 경로이므로 v1beta를 사용합니다. 코드베이스 전체에 엔드포인트 문자열을 분산시키지 않고 새 버전을 테스트할 수 있도록 API 버전을 구성에 유지하세요.
네이티브 엔드포인트 구조
경로는 세 부분으로 구성됩니다:
/v1beta/models/{model}:generateContent
v1beta는 API 버전입니다.{model}은 Google의 Gemini 모델 페이지에 있는 정확한 모델 ID입니다.generateContent는 생성 메서드입니다.
404 응답은 종종 모델 ID, API 버전 또는 메서드가 일치하지 않음을 의미합니다. 인증 코드를 변경하기 전에 전체 경로를 현재 모델 문서와 비교하세요.
OpenAI 호환 클라이언트로 Gemini 사용 방법
애플리케이션에서 이미 OpenAI Python 패키지를 사용하고 있다면 설치하고 API 키, 기본 URL 및 모델 ID를 변경하세요:
pip install openai
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
response = client.chat.completions.create(
model="gemini-3.1-pro-preview",
messages=[
{
"role": "system",
"content": "You are a concise software architecture reviewer.",
},
{
"role": "user",
"content": "Review a queue worker design and list the top five failure modes.",
},
],
)
print(response.choices[0].message.content)
이는 기존 채팅 완성 추상화가 있는 팀에게 가장 빠른 방법입니다. 또한 평가 도구를 재사용하기 쉽게 만듭니다: 프롬프트와 응답 검사를 일정하게 유지한 다음 공급자 구성을 교체하면 됩니다.
두 공급자가 동일한 SDK 호출을 허용한다고 해서 동일한 동작을 가정하지 마세요. 시스템 명령, 도구 스키마, 멀티모달 입력, 안전 처리, 스트리밍 이벤트, 토큰 계산 및 오류 페이로드가 다를 수 있습니다. 프로덕션 트래픽을 변경하기 전에 공급자별 테스트를 실행하세요.
Gemini 모델 ID 선택 및 관리 방법
gemini-pro와 같은 마케팅 이름을 애플리케이션 로직에 직접 배치하지 마세요. Google에서 사용 가능한 모델 ID는 미리보기 모델이 도입, 승격 및 폐기됨에 따라 변경됩니다. 이 가이드가 확인된 시점에 Google의 공식 모델 페이지에는 gemini-3.1-pro-preview가 Pro 클래스 모델 식별자로 나열되어 있었습니다.
대신 구성 레이어를 사용하세요:
import os
GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview")
이렇게 작은 선택만으로도 모델 업그레이드가 코드 재작성이 아닌 배포 변경이 됩니다. 더 큰 서비스의 경우 이러한 필드를 함께 저장하세요:
{
"provider": "google",
"base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
"model": "gemini-3.1-pro-preview",
"timeout_seconds": 60
}
새 모델을 프로덕션에 투입하기 전에:
- ID가 Google의 현재 모델 문서 또는 모델 API에 표시되는지 확인하세요.
- 모델이 미리보기, 안정화 또는 폐기 예정인지 확인하세요.
- 답변 품질 및 도구 호출 정확성에 대한 자체 평가 세트를 실행하세요.
- 대표적인 프롬프트로 지연 시간, 토큰 사용량 및 실패율을 측정하세요.
- 모든 트래픽을 전환하기 전에 대체 모델 또는 명확한 실패 경로를 추가하세요.
속도 제한은 단일 보편적인 숫자가 아닙니다. 모델 및 사용량 계층에 따라 다르므로 Google의 Gemini API 속도 제한 문서를 읽고 프로젝트에 적용된 제한을 모니터링하세요.
공급자 전환 가능한 백엔드 구축 방법
OpenAI 호환 인터페이스는 코드 변경을 줄일 수 있지만, 공급자 전환은 자체 애플리케이션이 계약을 정의할 때 가장 잘 작동합니다. 공급자 구성을 비즈니스 로직 외부에 유지하고 실제로 필요한 출력을 정규화하세요.
import os
from openai import OpenAI
PROVIDERS = {
"gemini": {
"api_key": os.environ["GEMINI_API_KEY"],
"base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
"model": os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview"),
},
"novita": {
"api_key": os.environ["NOVITA_API_KEY"],
"base_url": "https://api.novita.ai/openai",
"model": os.getenv("NOVITA_MODEL", "xiaomimimo/mimo-v2.5-pro"),
},
}
def generate(provider_name: str, prompt: str) -> str:
provider = PROVIDERS[provider_name]
client = OpenAI(
api_key=provider["api_key"],
base_url=provider["base_url"],
)
response = client.chat.completions.create(
model=provider["model"],
messages=[{"role": "user", "content": prompt}],
)
return response.choices[0].message.content or ""
이 예제는 차이점을 숨기는 대신 의도적으로 노출합니다. 각 공급자는 자체 자격 증명, 기본 URL 및 모델 ID를 유지합니다. 애플리케이션은 하나의 정규화된 문자열을 수신하는 반면, 공급자별 테스트는 도구 또는 멀티모달 입력과 같은 더 풍부한 동작을 다룰 수 있습니다.
Novita AI의 LLM API 문서는 지원되는 모델에 대해 OpenAI 호환 API 형태를 사용합니다. 이는 팀이 전체 클라이언트 레이어를 재구축하지 않고 Gemini를 오픈소스 모델과 비교하려는 경우 유용할 수 있습니다.
Gemini가 에이전트 백엔드에 어떻게 적합한지
에이전트 백엔드는 최소한 두 가지 별도의 책임을 가집니다:
- 추론: 모델이 무엇을 말할지 또는 어떤 도구를 호출할지 결정합니다.
- 실행: 제어된 런타임이 파일, 셸, 브라우저 또는 애플리케이션 작업을 수행합니다.
Gemini API는 추론 측면을 처리할 수 있습니다. 실행 경계로 취급되어서는 안 됩니다. 모델이 셸 명령을 제안하는 경우, 애플리케이션은 여전히 도구 호출을 검증하고, 권한을 부여하고, 격리된 환경에서 실행하고, 결과를 캡처하고, 어떤 컨텍스트를 모델로 다시 보낼지 결정해야 합니다.
Novita Agent Sandbox는 격리된 에이전트 실행 워크플로우를 위해 설계되었습니다. 실용적인 아키텍처는 Gemini를 추론에 사용하는 동시에 샌드박스가 코드 또는 브라우저 작업을 별도로 처리하도록 할 수 있습니다:
사용자 요청
-> 에이전트 서비스
-> 추론 및 도구 선택을 위한 Gemini API
-> 제안된 작업에 대한 정책 검사
-> 격리된 실행을 위한 Agent Sandbox
-> 에이전트 서비스로 반환된 도구 결과
-> 최종 응답을 위한 Gemini API
이러한 분리는 모델을 교체 가능하게 만들고 신뢰할 수 없는 실행을 애플리케이션 서버로부터 멀어지게 합니다. 또한 백엔드에 타임아웃, 네트워크 정책, 파일 제한, 감사 로깅 및 사용자 권한 부여를 적용할 수 있는 단일 지점을 제공합니다.
첫 번째 버전에서는 몇 가지 좁은 도구만 노출하고, 해당 인수에 대한 JSON 스키마를 정의하고, 알 수 없는 필드를 거부하고, 실행 시간과 출력 크기에 하드 제한을 설정하세요. 권한 모델이 명확해진 후에야 더 광범위한 컴퓨터 사용 또는 브라우저 기능을 추가하세요.
오픈소스 모델이 더 적합한 경우
Gemini Pro 모델은 애플리케이션에 Google의 모델 기능과 관리형 API가 필요할 때 강력한 옵션입니다. 오픈소스 모델은 두 번째 공급자가 필요하거나, 가시적인 업스트림 릴리스에 대한 모델 동작을 평가하려는 경우, 또는 다른 인프라와 함께 OpenAI 호환 엔드포인트를 통해 사용 가능한 모델을 선호하는 경우 더 적합할 수 있습니다.
MiMo-V2.5-Pro는 Novita AI에서 제공하는 현재 옵션 중 하나입니다. Xiaomi의 업스트림 모델 카드는 이를 오픈소스 Mixture-of-Experts 모델로 설명하는 반면, Novita AI는 호스팅된 모델 ID xiaomimimo/mimo-v2.5-pro를 제공합니다. Google 호환성 엔드포인트와 Novita AI 모두 OpenAI 스타일 클라이언트로 호출할 수 있기 때문에, 이전 섹션의 공급자 전환 가능 패턴은 동일한 프롬프트와 승인 검사로 이를 평가할 수 있습니다.
레이블만으로 선택하지 마세요. 실제 워크로드에서 작은 평가 세트를 구축하세요: 코드 리뷰 코멘트, 지원 질문, 검색 기반 답변, 도구 호출 또는 긴 문서. 라우팅 결정을 내리기 전에 현재 공급자 대시보드를 사용하여 출력 품질, 지연 시간, 오류 동작 및 비용을 비교하세요.
일반적인 Gemini API 오류
400: 잘못된 요청
JSON 형태, 메시지 역할, 도구 정의 및 매개변수 이름을 확인하세요. 다른 OpenAI 호환 공급자가 허용하는 옵션이 Google의 호환성 레이어에서 허용되지 않을 수 있습니다.
401 또는 403: 인증 또는 권한 실패
GEMINI_API_KEY가 프로세스 환경에 존재하고 의도한 Google Cloud 프로젝트에 속하는지 확인하세요. 또한 프로젝트와 선택한 모델이 계정 및 리전에서 사용 가능한지 확인하세요.
404: 모델 또는 메서드를 찾을 수 없음
정확한 모델 ID를 현재 Gemini 모델 목록과 비교하세요. 네이티브 REST 호출의 경우 API 버전과 :generateContent 접미사를 확인하세요. OpenAI 호환 호출의 경우 기본 URL이 /v1beta/openai/로 끝나는지 확인하세요.
429: 속도 제한 초과
지수 백오프와 지터(jitter)로 재시도하되, 재시도를 용량 계획의 대체 수단으로 취급하지 마세요. 버스트성이 있는 작업을 대기열에 넣고, 동시 요청을 제한하고, 프로젝트의 현재 사용량 계층 및 모델별 제한을 검사하세요.
SDK는 작동하지만 공급자를 전환한 후 출력이 다름
호환성은 요청 인터페이스를 다루지만 동일한 모델 동작을 보장하지는 않습니다. 모든 공급자 및 모델 버전에 대해 프롬프트, 구조화된 출력 및 도구 호출 테스트를 다시 실행하세요.
결론
Gemini 특화 기능에 대한 가장 명확한 경로를 원한다면 네이티브 Gemini API로 시작하세요. 이미 OpenAI 스타일 백엔드가 있거나 빠른 공급자 평가가 필요한 경우 OpenAI 호환 엔드포인트로 시작하세요. 두 경우 모두 API 키를 서버 측에 유지하고, 모델 ID를 구성에 넣고, 정확한 모델 버전을 테스트하고, 모델 추론을 에이전트 실행과 분리하세요.
탄력적인 프로덕션 설계를 위해 동일한 애플리케이션 소유 인터페이스 뒤에 최소한 하나의 대체 모델을 유지하세요. 이렇게 하면 팀이 Novita AI에서 오픈소스 옵션을 실질적으로 테스트하고, 모델 수명 주기 변경을 처리하고, 에이전트 실행을 격리된 샌드박스로 라우팅하여 모든 책임을 하나의 API 호출에 결합하지 않을 수 있습니다.
FAQ
gemini-pro라는 모델 ID가 여전히 있나요?
gemini-pro가 현재 ID라고 가정하지 마세요. "Gemini Pro API"는 Google의 상위 기능 Gemini 모델에 대한 검색어로 일반적으로 사용되지만, 애플리케이션은 현재 Gemini 모델 페이지의 정확한 ID를 사용해야 합니다. 이 가이드는 확인된 예시로 gemini-3.1-pro-preview를 사용합니다.
Gemini용 Google API 키는 어디서 얻나요?
Google AI Studio에서 Gemini API 키를 생성하세요. 소스 코드나 프론트엔드 JavaScript가 아닌 GEMINI_API_KEY와 같은 서버 측 비밀 변수에 저장하세요.
Gemini API 엔드포인트는 무엇인가요?
네이티브 호스트는 https://generativelanguage.googleapis.com입니다. 콘텐츠 생성 요청은 /v1beta/models/{model}:generateContent를 사용합니다. Google의 OpenAI 호환 기본 URL은 https://generativelanguage.googleapis.com/v1beta/openai/입니다.
Gemini Studio API와 Gemini API가 다른가요?
Google AI Studio는 개발자가 실험하고 키를 생성하는 데 사용하는 웹 인터페이스입니다. 애플리케이션 요청은 Gemini API로 전송됩니다. "Gemini Studio API"에 대한 검색은 일반적으로 이 AI Studio-API 워크플로우를 의미합니다.
Google Bard API와 Gemini API가 동일한가요?
Gemini는 현재 API 및 모델 브랜드입니다. Google Bard API에 대한 이전 검색은 오래된 Bard 예제 대신 현재 Gemini API 문서, 엔드포인트 및 모델 ID를 사용해야 합니다.
OpenAI SDK를 Gemini와 함께 사용할 수 있나요?
네. Google은 OpenAI 호환성 엔드포인트를 문서화합니다. 클라이언트 기본 URL을 Google의 호환성 URL로 설정하고, Gemini API 키를 제공하고, 지원되는 Gemini 모델 ID를 선택하세요. 완전한 동작 동등성에 의존하기 전에 공급자별 기능을 테스트하세요.
Gemini가 AI 에이전트를 위해 코드를 실행할 수 있나요?
Gemini는 코드에 대해 추론하고 도구 호출을 제안할 수 있지만, 실행은 제어된 런타임에서 이루어져야 합니다. 모델 호출을 Agent Sandbox와 같은 격리된 환경과 분리하고, 실행하기 전에 모든 요청된 작업을 검증하세요.
