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 경로는 모델 ID를 URL에 포함합니다. 이 예제는 현재 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."
}
]
}
]
}'
응답에는 생성된 콘텐츠가 포함된 후보가 포함됩니다. 실제 애플리케이션은 첫 번째 응답 객체를 직접 인덱싱하는 대신 빈 후보 목록, 차단된 콘텐츠, 시간 초과, 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 속도 제한 문서s를 읽고 프로젝트에 적용된 제한을 모니터링하세요.
제공자 전환 가능한 백엔드 구축 방법
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 = OpenA(
api_key=rovider["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 문서](https://novita.ai/docs/guides/llm-api)는 지원되는 모델에 대해 OpenAI 호환 API 형태를 사용합니다. 이는 팀이 전체 클라이언트 계층을 재구축하지 않고 Gemini를 오픈 소스 모델과 비교하려 할 때 유용할 수 있습니다.
## Gemini가 에이전트 백엔드에 적합한 방범
에이전트 백엔드는 최소 두 가기의 별도 책임이 있습니다.
1. **추론:** 모델이 무엇을 말할지 또는 어떤 도구를 호출할지 결정합니다.
2. **실행:** 제어된 런타임이 파일, 셸, 브라우저 또는 애플리케이션 작업을 수행합니다.
Gemin API는 추론 측면을 처리할 수 있습니다. 실행 경계로 취급해서는 안 됩니다. 모델이 셸 명령을 제안하면 애플리케이션은 여전히 도구 호출을 검증하고, 권한을 부여하고, 격리된 환경에 실해하고, 결를 포착하고, 모델로 보낼 컨텍스톨를 결졍해야 합니다.
[Novit Agent Sandbox](https://novita.ai/docs/guides/sandbox-overview)는 격리된 에이전트 실행 워크플로우를 위해 설계되었습니다. 실제 아키텍처는 Gemini를 추론에 사용하고 샌드박스가 코드 또는 브라우저 작업을 별도로 처리하도록 할 수 있습니다.
```text
사용자 요청
-> 에이전트 서비스
-> 추론 및 도구 선택을 위한 Gemini API
-> 제안된 작업에 대한 정책 검사
-> 격리된 실행을 위한 Agent Sandbox
-> 도구 결과가 에이전트 서비스로 반환
-> 최정 응답을 위한 Gemin API
``
이 분리는 모델을 교체 가능하게 만들고 신�할 수 없는 실행을 애플리케이션 서버에서 격리합니다. 또한 백엔드가 시간 초과, 네트워크 정책, 파일 제한, 감사 로깅, 사용자 권한 부여를 적용할 수 있는 한 곳을 제공합니다.
첫 번째 버전에서는 몇 가지 좁은 도구만 노출하고, 인수에 대한 JSON 스키마를 정의하고, 알려지지 않은 필드를 거부하고, 실행 시간과 출력 크기에 대한 하드 제한을 설정합니다. 권한 모델이 명확해진 후에만 광범위한 컴퓨터 사용 또는 브라우저 기능을 추가하세요.
## 오� 소스 모델이 더 적합한 경우
Gemini Pro 모델은 애플리케이션에 Google의 모델 기능과 관리되는 API가 필요할 때 좋은 선택입니다. 오픈 소스 모델은 두 번째 제공자가 필요하거나, 가시적인 업스트림 릴리스에 대한 모델 동작을 평가하려고 하거나, 다른 인프라와 함께 OpenAI 호환 엔드포인트를 통해 사용 가능한 모델을 선호할 때 더 적합할 수 있습니다.
[MiMo-V2.5-Pro](https://novita.ai/models/model-detail/xiaomimimo-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를 [현재 Gemin 모델 목록](https://ai.google.dev/gemini-api/docs/models)과 비교하세요. 네이티브 REST 호출의 경우 API 버전과 `:generateContent` 접미사를 확인하세요. OpenA 호환 호출의 경우 기본 URL이 `/v1beta/openai/`로 끝나든지 확인하세요.
### 429: 속도 제한 초과
지수적 백오프와 지터로 재시도하지만, 재시도를 용량 계획의 대체제로 취급하지 마세요. 버스트 작업을 대기열에 넣고, 동시 요청을 제한하며, 프로젝트의 현재 사용 등급과 모델별 제한을 검사하세요.
### 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는 개발자가 실험하고 키를 생성하기 위해 사용하는 웹 인테페이스입니다. 애플리케이션 요청은 Gemin 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와 같은 격리된 환경과 분리하고, 요청된 모든 행동을 실해 전에 검증하세요.
### Gemini API 가격에 무료 등급이 있나요?
네. Google은 새 계정이 무료 등급으로 시작하며, 특정 모델에 대해 무료 등급 속도 제한까지 Gemini API 및 AI Studio에서 액세스할 수 있다고 밝힙니다. 유료 등급으로 전환하려면 AI Studio에서 결제를 설정해야 합니다. 정확한 토큰 가격은 Google의 [가격 테이블](https://ai.google.dev/gemini-api/docs/pricing)을 확인하세요. 요금은 모델별로 다릅니다. `gemini-3.1-pro-preview`의 경우 현재 테이블에는 유료 표준 가격이 나열되어 있으며 무료 등급 토큰 요금이 없습니다.
## 추천 아티클
- [Deepseek R1 0528 vs Gemini 2.5 Pro 0506: 에이전트 파워 대 로직 마스터리](/deepseek-r1-0528-vs-gemini-2-5-pro-0506/)
- [제공자 전환을 위한 최고의 LLM API 플랫폼](https://blogs.novita.ai/best-llm-api-platform-for-switching-providers/)
- [코딩 에이전트란 무엇인가? 아키텍쳐, 도구 및 안전](https://blogs.novita.ai/what-are-coding-agents/)
- [Novita AI의 MiMo 2.5 API: OpenAI 호환 채팅 API](https://blogs.novita.ai/xiaomi-mimo-v2-5-pro-api/)
