OpenAI 호환성
OpenAI 호환성 (OpenAI compatibility)
Gemini 모델은 OpenAI 라이브러리(Python, TypeScript/JavaScript)와 REST API를 사용해 접근할 수 있어요. 세 줄의 코드만 바꾸고 Gemini API 키를 사용하면 돼요. 아직 OpenAI 라이브러리를 쓰지 않는다면 Gemini API를 직접 호출하는 것을 권장해요.
출처: 원문
본문
Gemini 모델은 OpenAI 라이브러리(Python, TypeScript/JavaScript)와 REST API를 사용해 접근할 수 있어요. 세 줄의 코드를 바꾸고 Gemini API 키를 사용하면 돼요. 아직 OpenAI 라이브러리를 쓰지 않는다면 Gemini API를 직접 호출하는 것을 권장해요.
Python
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
response = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[
{ "role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Explain to me how AI works"
}
]
)
print(response.choices[0].message)
JavaScript
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
const response = await openai.chat.completions.create({
model: "gemini-3.8-flash",
messages: [
{ role: "system",
content: "You are a helpful assistant."
},
{
role: "user",
content: "Explain to me how AI works",
},
],
});
console.log(response.choices[0].message);
REST
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "Explain to me how AI works"
}
]
}'
무엇이 바뀌었나요? 딱 세 줄이에요!
api_key="GEMINI_API_KEY": "GEMINI_API_KEY"를 Google AI Studio에서 받을 수 있는 실제 Gemini API 키로 바꾸세요.base_url="https://generativelanguage.googleapis.com/v1beta/openai/": 이렇게 하면 OpenAI 라이브러리가 기본 URL 대신 Gemini API 엔드포인트로 요청을 보내요.model="gemini-3.8-flash": 호환 가능한 Gemini 모델을 선택하세요.
Thinking
Gemini 모델은 복잡한 문제를 생각하도록 훈련되어 추론이 크게 개선돼요. Gemini API에는 모델이 얼마나 생각할지 세밀하게 제어하는 thinking 파라미터가 있어요.
서로 다른 Gemini 모델은 서로 다른 추론 구성을 가지며, OpenAI의 reasoning effort에 어떻게 매핑되는지는 다음과 같아요:
| reasoning_effort (OpenAI) | thinking_level (Gemini 3.1 Pro) | thinking_level (Gemini 3.1 Flash-Lite) | thinking_level (Gemini 3 Flash) | thinking_budget (Gemini 2.5) |
|---|---|---|---|---|
| minimal | low | minimal | minimal | 1,024 |
| low | low | low | low | 1,024 |
| medium | medium | medium | medium | 8,192 |
| high | high | high | high | 24,576 |
reasoning_effort를 지정하지 않으면 Gemini는 모델의 기본 level 또는 budget을 사용해요.
thinking을 비활성화하려면 2.5 모델에서 reasoning_effort를 "none"으로 설정할 수 있어요. Gemini 2.5 Pro나 3 모델에서는 추론을 끌 수 없어요.
Python
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
response = client.chat.completions.create(
model="gemini-3.8-flash",
reasoning_effort="low",
messages=[
{ "role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Explain to me how AI works"
}
]
)
print(response.choices[0].message)
JavaScript
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
const response = await openai.chat.completions.create({
model: "gemini-3.8-flash",
reasoning_effort: "low",
messages: [
{ role: "system",
content: "You are a helpful assistant."
},
{
role: "user",
content: "Explain to me how AI works",
},
],
});
console.log(response.choices[0].message);
REST
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"reasoning_effort": "low",
"messages": [
{
"role": "user",
"content": "Explain to me how AI works"
}
]
}'
Gemini thinking 모델은 생각 요약도 생성해요. 요청에 Gemini 필드를 포함하려면 extra_body 필드를 사용할 수 있어요.
reasoning_effort와 thinking_level/thinking_budget은 기능이 겹치므로 동시에 사용할 수 없다는 점을 참고하세요.
Python
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
response = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[{"role": "user", "content": "Explain to me how AI works"}],
extra_body={
'extra_body': {
"google": {
"thinking_config": {
"thinking_level": "low",
"include_thoughts": True
}
}
}
}
)
print(response.choices[0].message)
JavaScript
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
const response = await openai.chat.completions.create({
model: "gemini-3.8-flash",
messages: [{role: "user", content: "Explain to me how AI works",}],
extra_body: {
"google": {
"thinking_config": {
"thinking_level": "low",
"include_thoughts": true
}
}
}
});
console.log(response.choices[0].message);
REST
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"messages": [{"role": "user", "content": "Explain to me how AI works"}],
"extra_body": {
"google": {
"thinking_config": {
"thinking_level": "low",
"include_thoughts": true
}
}
}
}'
Gemini 3는 채팅 완성 API에서 생각 서명에 대한 OpenAI 호환성을 지원해요. 전체 예시는 생각 서명 페이지에서 찾을 수 있어요.
스트리밍
Gemini API는 스트리밍 응답을 지원해요.
Python
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
response = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[
{
"role": "system",
"content": "You are a helpful assistant."
},
{ "role": "user",
"content": "Hello!"
}
],
stream=True
)
for chunk in response:
print(chunk.choices[0].delta)
JavaScript
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
async function main() {
const completion = await openai.chat.completions.create({
model: "gemini-3.8-flash",
messages: [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
],
stream: true,
});
for await (const chunk of completion) {
console.log(chunk.choices[0].delta.content);
}
}
main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{"role": "user", "content": "Explain to me how AI works"}
],
"stream": true
}'
함수 호출
함수 호출은 생성형 모델에서 구조화된 데이터 출력을 쉽게 얻을 수 있게 해주며 Gemini API에서 지원돼요.
Python
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. Chicago, IL",
},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
},
"required": ["location"],
},
}
}
]
messages = [{"role": "user", "content": "What's the weather like in Chicago today?"}]
response = client.chat.completions.create(
model="gemini-3.8-flash",
messages=messages,
tools=tools,
tool_choice="auto"
)
print(response)
JavaScript
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
async function main() {
const messages = [{"role": "user", "content": "What's the weather like in Chicago today?"}];
const tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. Chicago, IL",
},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
},
"required": ["location"],
},
}
}
];
const response = await openai.chat.completions.create({
model: "gemini-3.8-flash",
messages: messages,
tools: tools,
tool_choice: "auto",
});
console.log(response);
}
main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "What's the weather like in Chicago today?"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. Chicago, IL"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
}
}
}
],
"tool_choice": "auto"
}'
이미지 이해
Gemini 모델은 네이티브 멀티모달이며 많은 일반적인 비전 작업에서 최고 수준의 성능을 제공해요.
Python
import base64
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
# Function to encode the image
def encode_image(image_path):
with open(image_path, "rb") as image_file:
return base64.b64encode(image_file.read()).decode('utf-8')
# Getting the base64 string
base64_image = encode_image("Path/to/agi/image.jpeg")
response = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is in this image?",
},
{
"type": "image_url",
"image_url": {
"url": f"data:image/jpeg;base64,{base64_image}"
},
},
],
}
],
)
print(response.choices[0])
JavaScript
import OpenAI from "openai";
import fs from 'fs/promises';
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
async function encodeImage(imagePath) {
try {
const imageBuffer = await fs.readFile(imagePath);
return imageBuffer.toString('base64');
} catch (error) {
console.error("Error encoding image:", error);
return null;
}
}
async function main() {
const imagePath = "Path/to/agi/image.jpeg";
const base64Image = await encodeImage(imagePath);
const messages = [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is in this image?",
},
{
"type": "image_url",
"image_url": {
"url": `data:image/jpeg;base64,${base64Image}`
},
},
],
}
];
try {
const response = await openai.chat.completions.create({
model: "gemini-3.8-flash",
messages: messages,
});
console.log(response.choices[0]);
} catch (error) {
console.error("Error calling Gemini API:", error);
}
}
main();
REST
bash -c '
base64_image=$(base64 -i "Path/to/agi/image.jpeg");
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d "{
\"model\": \"gemini-3.8-flash\",
\"messages\": [
{
\"role\": \"user\",
\"content\": [
{ \"type\": \"text\", \"text\": \"What is in this image?\" },
{
\"type\": \"image_url\",
\"image_url\": { \"url\": \"data:image/jpeg;base64,${base64_image}\" }
}
]
}
]
}"
'
이미지 생성
gemini-2.5-flash-image 또는 gemini-3-pro-image-preview로 이미지를 생성하세요. 지원 파라미터는 prompt, model, n, size, response_format이에요. 여기나 extra_body 섹션에 나열되지 않은 다른 파라미터는 호환 레이어가 조용히 무시해요.
Google 검색 접지를 활성화하고 안전 설정을 구성하려면 extra_body 파라미터를 사용하세요. 사용 가능한 파라미터는 extra_body 섹션을 참고하세요. Google 검색 접지는 Gemini 3 이상 모델에서만 사용할 수 있어요.
Python
import base64
from openai import OpenAI
from PIL import Image
from io import BytesIO
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
response = client.images.generate(
model="gemini-2.5-flash-image",
prompt="a portrait of a sheepadoodle wearing a cape",
response_format='b64_json',
n=1,
)
for image_data in response.data:
image = Image.open(BytesIO(base64.b64decode(image_data.b64_json)))
image.show()
JavaScript
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});
async function main() {
const image = await openai.images.generate(
{
model: "gemini-2.5-flash-image",
prompt: "a portrait of a sheepadoodle wearing a cape",
response_format: "b64_json",
n: 1,
}
);
console.log(image.data);
}
main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/openai/images/generations" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
"model": "gemini-2.5-flash-image",
"prompt": "a portrait of a sheepadoodle wearing a cape",
"response_format": "b64_json",
"n": 1,
}'
비디오 생성
Sora 호환 /v1/videos 엔드포인트를 통해 veo-3.1-generate-preview로 비디오를 생성하세요. 지원되는 최상위 파라미터는 prompt와 model이에요. duration_seconds, image, aspect_ratio 같은 추가 파라미터는 extra_body로 전달해야 해요. 사용 가능한 모든 파라미터는 extra_body 섹션을 참고하세요.
비디오 생성은 완료를 폴링할 수 있는 운영 ID를 반환하는 장기 실행 작업이에요.
Python
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
# Returns a Long Running Operation (status: processing)
response = client.videos.create(
model="veo-3.1-generate-preview",
prompt="A cinematic drone shot of a waterfall",
)
print(f"Operation ID: {response.id}")
print(f"Status: {response.status}")
JavaScript
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
async function main() {
// Returns a Long Running Operation (status: processing)
const response = await openai.videos.create({
model: "veo-3.1-generate-preview",
prompt: "A cinematic drone shot of a waterfall",
});
console.log(`Operation ID: ${response.id}`);
console.log(`Status: ${response.status}`);
}
main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/openai/videos" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-F "model=veo-3.1-generate-preview" \
-F "prompt=A cinematic drone shot of a waterfall"
비디오 상태 확인
비디오 생성은 비동기예요. GET /v1/videos/{id}를 사용해 상태를 폴링하고 완료되면 최종 비디오 URL을 검색하세요:
Python
import time
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
# Poll until video is ready
video_id = response.id # From the create call
while True:
video = client.videos.retrieve(video_id)
if video.status == "completed":
print(f"Video URL: {video.url}")
break
elif video.status == "failed":
print(f"Generation failed: {video.error}")
break
print(f"Status: {video.status}. Waiting...")
time.sleep(10)
JavaScript
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
async function main() {
// Poll until video is ready
const videoId = response.id; // From the create call
while (true) {
const video = await openai.videos.retrieve(videoId);
if (video.status === "completed") {
console.log(`Video URL: ${video.url}`);
break;
} else if (video.status === "failed") {
console.log(`Generation failed: ${video.error}`);
break;
}
console.log(`Status: ${video.status}. Waiting...`);
await new Promise(resolve => setTimeout(resolve, 10000));
}
}
main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/openai/videos/VIDEO_ID" \
-H "Authorization: Bearer GEMINI_API_KEY"
오디오 이해
오디오 입력을 분석하세요:
Python
import base64
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
with open("/path/to/your/audio/file.wav", "rb") as audio_file:
base64_audio = base64.b64encode(audio_file.read()).decode('utf-8')
response = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Transcribe this audio",
},
{
"type": "input_audio",
"input_audio": {
"data": base64_audio,
"format": "wav"
}
}
],
}
],
)
print(response.choices[0].message.content)
JavaScript
import fs from "fs";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});
const audioFile = fs.readFileSync("/path/to/your/audio/file.wav");
const base64Audio = Buffer.from(audioFile).toString("base64");
async function main() {
const response = await client.chat.completions.create({
model: "gemini-3.8-flash",
messages: [
{
role: "user",
content: [
{
type: "text",
text: "Transcribe this audio",
},
{
type: "input_audio",
input_audio: {
data: base64Audio,
format: "wav",
},
},
],
},
],
});
console.log(response.choices[0].message.content);
}
main();
REST
# **Note:** If you get an `Argument list too long` error, the encoding of your audio file might be too long for curl.
bash -c '
base64_audio=$(base64 -i "/path/to/your/audio/file.wav");
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d "{
\"model\": \"gemini-3.8-flash\",
\"messages\": [
{
\"role\": \"user\",
\"content\": [
{ \"type\": \"text\", \"text\": \"Transcribe this audio file.\" },
{
\"type\": \"input_audio\",
\"input_audio\": {
\"data\": \"${base64_audio}\",
\"format\": \"wav\"
}
}
]
}
]
}"
'
구조화 출력
Gemini 모델은 정의한 어떤 구조의 JSON 객체도 출력할 수 있어요.
Python
from pydantic import BaseModel
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
class CalendarEvent(BaseModel):
name: str
date: str
participants: list[str]
completion = client.beta.chat.completions.parse(
model="gemini-3.8-flash",
messages=[
{"role": "system", "content": "Extract the event information."},
{"role": "user", "content": "John and Susan are going to an AI conference on Friday."},
],
response_format=CalendarEvent,
)
print(completion.choices[0].message.parsed)
JavaScript
import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai"
});
const CalendarEvent = z.object({
name: z.string(),
date: z.string(),
participants: z.array(z.string()),
});
const completion = await openai.chat.completions.parse({
model: "gemini-3.8-flash",
messages: [
{ role: "system", content: "Extract the event information." },
{ role: "user", content: "John and Susan are going to an AI conference on Friday" },
],
response_format: zodResponseFormat(CalendarEvent, "event"),
});
const event = completion.choices[0].message.parsed;
console.log(event);
임베딩
텍스트 임베딩은 텍스트 문자열의 관련성을 측정하며 Gemini API로 생성할 수 있어요. gemini-embedding-2-preview를 멀티모달 임베딩에, gemini-embedding-001을 텍스트 전용 임베딩에 사용할 수 있어요.
Python
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
response = client.embeddings.create(
input="Your text string goes here",
model="gemini-embedding-2-preview"
)
print(response.data[0].embedding)
JavaScript
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/"
});
async function main() {
const embedding = await openai.embeddings.create({
model: "gemini-embedding-2-preview",
input: "Your text string goes here",
});
console.log(embedding);
}
main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/openai/embeddings" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
"input": "Your text string goes here",
"model": "gemini-embedding-2-preview"
}'
Batch API
OpenAI 라이브러리로 batch 작업을 만들고, 제출하고, 상태를 확인할 수 있어요.
OpenAI 입력 형식으로 JSONL 파일을 준비해야 해요. 예:
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": "Tell me a one-sentence joke."}]}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": "Why is the sky blue?"}]}}
OpenAI 호환 Batch는 batch 생성, 작업 상태 모니터링, batch 결과 보기를 지원해요.
업로드·다운로드 호환성은 현재 지원되지 않아요. 대신 다음 예시는 Gemini Batch API를 쓸 때처럼 파일 업로드·다운로드에 genai 클라이언트를 사용해요.
Python
from openai import OpenAI
# Regular genai client for uploads & downloads
from google import genai
client = genai.Client()
openai_client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
# Upload the JSONL file in OpenAI input format, using regular genai SDK
uploaded_file = client.files.upload(
file='my-batch-requests.jsonl',
config=types.UploadFileConfig(display_name='my-batch-requests', mime_type='jsonl')
)
# Create batch
batch = openai_client.batches.create(
input_file_id=batch_input_file_id,
endpoint="/v1/chat/completions",
completion_window="24h"
)
# Wait for batch to finish (up to 24h)
while True:
batch = client.batches.retrieve(batch.id)
if batch.status in ('completed', 'failed', 'cancelled', 'expired'):
break
print(f"Batch not finished. Current state: {batch.status}. Waiting 30 seconds...")
time.sleep(30)
print(f"Batch finished: {batch}")
# Download results in OpenAI output format, using regular genai SDK
file_content = genai_client.files.download(file=batch.output_file_id).decode('utf-8')
# See batch_output JSONL in OpenAI output format
for line in file_content.splitlines():
print(line)
OpenAI SDK는 Batch API로 임베딩 생성도 지원해요. 이렇게 하려면 create 메서드의 endpoint 필드를 임베딩 엔드포인트로 바꾸고, JSONL 파일의 url과 model 키도 바꾸세요:
# JSONL file using embeddings model and endpoint
# {"custom_id": "request-1", "method": "POST", "url": "/v1/embeddings", "body": {"model": "ggemini-embedding-001", "messages": [{"role": "user", "content": "Tell me a one-sentence joke."}]}}
# {"custom_id": "request-2", "method": "POST", "url": "/v1/embeddings", "body": {"model": "gemini-embedding-001", "messages": [{"role": "user", "content": "Why is the sky blue?"}]}}
# ...
# Create batch step with embeddings endpoint
batch = openai_client.batches.create(
input_file_id=batch_input_file_id,
endpoint="/v1/embeddings",
completion_window="24h"
)
전체 예시는 OpenAI 호환성 cookbook의 Batch 임베딩 생성 섹션을 참고하세요.
Flex와 Priority 추론
Gemini API는 OpenAI의 service_tier 파라미터를 이름과 로직에서 일치시켜, Flex와 Priority 추론 티어 양쪽에 대해 한도를 적용하고 트래픽을 우아하게 유도해요.
Python
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
completion = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[
{"role": "user", "content": "Write a short poem about clouds."}
],
service_tier="priority" # Or service_tier="flex"
)
print(completion)
명시적으로 할당하지 않으면 service_tier는 OpenAI의 default와 동일한 standard로 기본 설정돼요.
추론 티어에 대한 자세한 내용은 최적화 문서를 참고하세요.
extra_body로 Gemini 기능 활성화
OpenAI 모델에는 없지만 Gemini에서 지원하는 몇 가지 기능이 있으며 extra_body 필드로 활성화할 수 있어요.
| 파라미터 | 타입 | 엔드포인트 | 설명 |
|---|---|---|---|
| cached_content | Text | Chat | Gemini의 일반 콘텐츠 캐시에 해당. |
| thinking_config | Object | Chat | Gemini의 ThinkingConfig에 해당. |
| aspect_ratio | Text | Images | 출력 종횡비 (예: "16:9", "1:1", "9:16" ). |
| generation_config | Object | Images | Gemini 생성 구성 객체 (예: {"responseModalities": ["IMAGE"], "candidateCount": 2} ). |
| safety_settings | List | Images | 커스텀 안전 임계값 필터 (예: [{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"}] ). |
| tools | List | Images | 접지 활성화 (예: [{"google_search": {}}] ). gemini-3-pro-image-preview 전용. |
| aspect_ratio | Text | Video | 출력 비디오의 크기 (가로 16:9, 세로 9:16). 지정하지 않으면 size에서 매핑. |
| resolution | Text | Video | 출력 해상도 ( 720p , 1080p , 4K ). 참고: 1080p와 4K는 업샘플러 파이프라인을 트리거. |
| duration_seconds | Integer | Video | 생성 길이 (값: 4 , 6 , 8 ). reference_images , interpolation, extension 사용 시 반드시 8이어야 함. |
| frame_rate | Text | Video | 비디오 출력 프레임 레이트 (예: "24" ). |
| input_reference | Text | Video | 비디오 생성의 참조 입력. |
| extend_video_id | Text | Video | 확장할 기존 비디오의 ID. |
| negative_prompt | Text | Video | 제외할 항목 (예: "shaky camera" ). |
| seed | Integer | Video | 결정적 생성용 정수. |
| style | Text | Video | 시각 스타일 ( 기본 cinematic, 소셜 미디어 최적화용 creative). |
| person_generation | Text | Video | 사람 생성 제어 ( allow_adult , allow_all , dont_allow ). |
| reference_images | List | Video | 스타일/캐릭터 참조용 최대 3개 이미지 (base64 에셋). |
| image | Text | Video | 비디오 생성을 조건화하는 base64 인코딩 초기 입력 이미지. |
| last_frame | Object | Video | 보간용 최종 이미지 (첫 프레임으로 image 필요). |
extra_body 사용 예시
extra_body로 cached_content를 설정하는 예시예요:
Python
from openai import OpenAI
client = OpenAI(
api_key=MY_API_KEY,
base_url="https://generativelanguage.googleapis.com/v1beta/"
)
stream = client.chat.completions.create(
model="gemini-3.8-flash",
n=1,
messages=[
{
"role": "user",
"content": "Summarize the video"
}
],
stream=True,
stream_options={'include_usage': True},
extra_body={
'extra_body':
{
'google': {
'cached_content': "cachedContents/0000aaaa1111bbbb2222cccc3333dddd4444eeee"
}
}
}
)
for chunk in stream:
print(chunk)
print(chunk.usage.to_dict())
모델 목록
사용 가능한 Gemini 모델 목록을 가져오세요:
Python
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
models = client.models.list()
for model in models:
print(model.id)
JavaScript
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});
async function main() {
const list = await openai.models.list();
for await (const model of list) {
console.log(model);
}
}
main();
REST
curl https://generativelanguage.googleapis.com/v1beta/openai/models \
-H "Authorization: Bearer GEMINI_API_KEY"
모델 검색
Gemini 모델을 검색하세요:
Python
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
model = client.models.retrieve("gemini-3.8-flash")
print(model.id)
JavaScript
import OpenAI from "openai";
const openai = new OpenAI({
apiKey: "GEMINI_API_KEY",
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});
async function main() {
const model = await openai.models.retrieve("gemini-3.8-flash");
console.log(model.id);
}
main();
REST
curl https://generativelanguage.googleapis.com/v1beta/openai/models/gemini-3.8-flash \
-H "Authorization: Bearer GEMINI_API_KEY"
현재 제한 사항
OpenAI 라이브러리 지원은 기능 지원을 확장하는 동안 여전히 베타예요.
지원 파라미터, 예정 기능, Gemini 시작 시 문제에 대한 질문이 있으면 개발자 포럼에 참여하세요.
다음으로
더 상세한 예시를 보려면 OpenAI Compatibility Colab을 사용해 보세요.