Gemini OpenAI 兼容接口使用说明

本文根据 Google 官方文档 OpenAI 兼容性 | Gemini API 精简整理，只保留接入思路和常用写法。

Gemini API 提供了 OpenAI 兼容层。它的核心用途是：如果你的项目已经使用 OpenAI SDK，可以尽量少改代码，把请求转到 Gemini 模型。

最重要的三个变化：

API Key 使用 GEMINI_API_KEY。
SDK 的 baseURL / base_url 改成 Gemini OpenAI 兼容端点。
model 改成 Gemini 模型名，例如官方文档当前示例中的 gemini-3.5-flash。

适合什么场景

这个兼容层适合：

已经接入 OpenAI SDK，希望快速试用 Gemini。
想在同一套 Chat Completions 调用里切换模型供应商。
只需要聊天、流式、函数调用、结构化输出、embedding 等通用能力。
想保留现有应用层封装，减少迁移成本。

不适合把它理解成“完整复制 OpenAI API”。如果要使用 Gemini 独有能力，或者 OpenAI 兼容层没有覆盖的参数，优先看 Gemini 原生 API 或 Google Gen AI SDK。

基础参数

Gemini OpenAI 兼容端点：

https://generativelanguage.googleapis.com/v1beta/openai/

REST Chat Completions 路径：

https://generativelanguage.googleapis.com/v1beta/openai/chat/completions

环境变量建议：

export GEMINI_API_KEY="your_api_key_here"

不要把 API Key 放到前端代码里。浏览器应用应该通过自己的后端转发请求。

JavaScript 最小用法

安装 OpenAI SDK 后，初始化时只需要换 apiKey 和 baseURL：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const completion = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    { role: "system", content: "你是一个简洁的技术助手。" },
    { role: "user", content: "用三点说明 HTTP/2 的价值。" },
  ],
});

console.log(completion.choices[0]?.message?.content);

如果你的代码原来已经封装了 OpenAI client，通常只需要把初始化配置做成可切换：

const client = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

Python 最小用法

Python 也一样，改 api_key 和 base_url：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

completion = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {"role": "system", "content": "你是一个简洁的技术助手。"},
        {"role": "user", "content": "用三点说明 HTTP/2 的价值。"},
    ],
)

print(completion.choices[0].message.content)

REST 调用

如果不想用 SDK，可以直接请求兼容端点：

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [
      {"role": "user", "content": "用一句话解释什么是向量数据库。"}
    ]
  }'

流式输出

前端聊天、CLI、长回答生成通常需要流式输出。OpenAI SDK 里加上 stream: true：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const stream = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [{ role: "user", content: "写一段 100 字以内的 Docusaurus 简介。" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

REST 也可以在请求体里加入：

{
  "model": "gemini-3.5-flash",
  "messages": [
    {"role": "user", "content": "解释什么是 streaming response。"}
  ],
  "stream": true
}

函数调用

Gemini 的 OpenAI 兼容层支持函数调用。你可以把工具描述放进 tools：

const completion = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [{ role: "user", content: "北京今天适合跑步吗？" }],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "查询城市天气",
        parameters: {
          type: "object",
          properties: {
            city: {
              type: "string",
              description: "城市名称",
            },
          },
          required: ["city"],
        },
      },
    },
  ],
});

console.log(completion.choices[0]?.message?.tool_calls);

实际应用里还需要你自己执行工具函数，再把工具结果继续发回模型。兼容层只负责让模型选择工具和生成调用参数。

结构化输出

当你需要稳定 JSON，可以使用 OpenAI SDK 的结构化输出写法。典型场景包括信息抽取、分类、表单解析和 API 参数生成。

最小思路是：

明确定义 schema。
让模型按 schema 返回。
在服务端再次校验 JSON。

不要只靠提示词保证格式。生产环境仍然需要校验、重试和错误处理。

Embeddings

文档也说明了兼容层支持 embeddings。Google 文档当前提到：

gemini-embedding-2-preview：多模态嵌入。
gemini-embedding-001：文本嵌入。

示例写法和 OpenAI SDK 类似：

const embedding = await client.embeddings.create({
  model: "gemini-embedding-001",
  input: "Docusaurus 是一个适合写技术文档的静态站点生成器。",
});

console.log(embedding.data[0].embedding.length);

注意事项

baseURL 必须指向 Gemini 的 OpenAI 兼容端点，不要漏掉 /openai/。
model 必须使用 Gemini 模型名，不能直接照搬 OpenAI 模型名。
兼容层覆盖常用接口，但不是所有 OpenAI 参数都保证生效。
浏览器端不要直连 Gemini API，避免泄露 Key。
如果需要 Gemini 原生能力，优先使用 Gemini API 或 Google Gen AI SDK。
生产环境要加超时、重试、日志、限流和响应校验。

小结

Gemini OpenAI 兼容接口的价值在于迁移成本低。已经用 OpenAI SDK 的项目，通常只需要替换 API Key、base URL 和模型名，就能快速接入 Gemini。

它适合做快速验证、供应商切换、通用聊天和常见工具调用；如果要深度使用 Gemini 独有能力，还是应该直接阅读 Gemini API 的原生文档。

适合什么场景​

基础参数​

JavaScript 最小用法​

Python 最小用法​

REST 调用​

流式输出​

函数调用​

结构化输出​

Embeddings​

注意事项​

小结​