Gemini 中文指南
获取 API 密钥 ↗

OpenAI 兼容性

↓ 下载 MarkdownInteractions 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-4-hydrogen",
    messages=[
        {   "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Explain to me how AI works"
        }
    ]
)

print(response.choices[0].message)

思考 #

Gemini 模型经过训练可以思考复杂的问题,从而显着提高推理能力。 Gemini API 配有 思维参数 这可以对模型的思考程度进行精细控制。

不同的Gemini模型有不同的推理配置,您可以看到它们如何映射到OpenAI的推理工作,如下所示:

推理_努力(OpenAI)思维水平(Gemini 4)思维水平(Gemini 3.1 Flash-Lite)思维水平(Gemini 3 Flash)思考_预算(Gemini 2.5)
minimallowminimalminimal1,024
lowlowlowlow1,024
mediummediummediummedium8,192
highhighhighhigh24,576
xhighxhigh (gemini-4-hydrogen 仅)不支持不支持不支持

如果没有 reasoning_effort 指定后,Gemini 使用模型的默认值 水平或预算.

如果你想禁用思考,你可以设置 reasoning_effort 到 "none" 适用于 2.5 型号。对于 Gemini 2.5 Pro、Gemini 3 或 Gemini 4 型号,无法关闭推理。

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-4-hydrogen",
    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)

流式输出 #

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-4-hydrogen",
  messages=[
    {
        "role": "system",
        "content": "You are a helpful assistant."
    },
    {   "role": "user",
        "content": "Hello!"
    }
  ],
  stream=True
)

for chunk in response:
    print(chunk.choices[0].delta)

函数调用 #

函数调用让您更轻松地从生成模型获得结构化数据输出,并且 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-4-hydrogen",
  messages=messages,
  tools=tools,
  tool_choice="auto"
)

print(response)

图像理解 #

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-4-hydrogen",
  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])

生成图像 #

使用生成图像 gemini-2.5-flash-image 或 gemini-3-pro-image-preview。支持的参数包括 prompt, model, n, size, 和 response_format。此处或未列出的任何其他参数 extra_body 部分将被兼容层默默地忽略。

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()

生成视频 #

音频理解 #

分析音频输入:

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-4-hydrogen",
    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)

结构化输出 #

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-4-hydrogen",
    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)

嵌入 #

文本嵌入衡量文本字符串的相关性,可以使用以下命令生成 Gemini API。您可以使用 gemini-embedding-2 对于多模态嵌入或 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"
)

print(response.data[0].embedding)

Batch API #

您可以创建 批处理作业,提交它们,并使用 OpenAI 库检查它们的状态。

您需要准备 OpenAI 输入格式的 JSONL 文件。例如:

json
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-4-hydrogen", "messages": [{"role": "user", "content": "Tell me a one-sentence joke."}]}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gemini-4-hydrogen", "messages": [{"role": "user", "content": "Why is the sky blue?"}]}}

OpenAI 批处理兼容性支持创建批处理、监控作业状态和查看批处理结果。

目前不支持上传和下载的兼容性。相反,以下示例使用 genai 客户端用于上传和下载 文件,与使用Gemini时相同 Batch API.

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 嵌入端点的字段,以及 url 和 model JSONL 文件中的键:

python
# 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 兼容性说明书部分的完整示例。

弹性和优先级推理 #

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-4-hydrogen",
  messages=[
    {"role": "user", "content": "Write a short poem about clouds."}
  ],
  service_tier="priority" # Or service_tier="flex"
)

print(completion)

当没有明确指定时, service_tier 默认为 standard,相当于 default 适用于 OpenAI。了解有关推理层的更多信息 优化 文档。

启用 Gemini 功能 extra_body #

Gemini 支持多种功能,这些功能在 OpenAI 型号中不可用,但可以使用 extra_body 场。

参数类型端点说明
cached_content文本聊天对应Gemini的通用内容缓存。
thinking_config对象聊天对应Gemini的ThinkingConfig。
aspect_ratio文本图片输出纵横比(例如, "16:9", "1:1", "9:16").
generation_config对象图片Gemini 生成配置对象(例如, {"responseModalities": ["IMAGE"], "candidateCount": 2}).
safety_settings列表图片自定义安全阈值过滤器(例如, [{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"}]).
tools列表图片启用事实依据(例如, [{"google_search": {}}])。只为 gemini-3-pro-image-preview.

使用示例 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)

检索模型 #

检索 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-4-hydrogen")
print(model.id)

目前的限制 #

对 OpenAI 库的支持仍处于测试阶段,我们将扩展功能支持。

如果您对支持的参数、即将推出的功能有疑问,或者在开始使用 Gemini 时遇到任何问题,请加入我们的 开发者论坛.

后续步骤 #

试试我们的 OpenAI 兼容性 Colab 完成更详细的示例。

搜索标题、API 名称或正文内容