# OpenAI 兼容性

Gemini 模型可使用 OpenAI 库（Python 和 TypeScript / Javascript）以及 REST API 进行访问，方法是更新三行代码并使用您的 [Gemini API 密钥](https://aistudio.google.com/apikey)。如果您尚未使用 OpenAI 库，我们建议您调用 [Gemini API 直接](/docs/get-started).

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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-4-hydrogen",
    messages: [
        {   role: "system",
            content: "You are a helpful assistant."
        },
        {
            role: "user",
            content: "Explain to me how AI works",
        },
    ],
});

console.log(response.choices[0].message);
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-4-hydrogen",
    "messages": [
      {
        "role": "user",
        "content": "Explain to me how AI works"
      }
    ]
  }'
```

发生了什么变化？只需三行！

* **`api_key="GEMINI_API_KEY"`**：替换“`GEMINI_API_KEY`“使用您实际的 Gemini API 密钥，您可以进入 [Google AI Studio](https://aistudio.google.com).

* **`base_url="https://generativelanguage.googleapis.com/v1beta/openai/"`:** 这告诉 OpenAI 库将请求发送到 Gemini API 端点而不是默认 URL。

* **`model="gemini-4-hydrogen"`**：选择兼容的Gemini型号
{% /tab %}
{% /tabs %}

## 思考  {% #thinking %}

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

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

| 推理_努力（OpenAI） | 思维水平（Gemini 4）                  | 思维水平（Gemini 3.1 Flash-Lite） | 思维水平（Gemini 3 Flash） | 思考_预算（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`          |
| `xhigh`       | `xhigh` (`gemini-4-hydrogen` 仅） | 不支持                         | 不支持                  | 不支持               |

如果没有 `reasoning_effort` 指定后，Gemini 使用模型的默认值 [水平或预算](/docs/thinking#thinking-levels).

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

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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-4-hydrogen",
    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);
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-4-hydrogen",
    "reasoning_effort": "low",
    "messages": [
      {
        "role": "user",
        "content": "Explain to me how AI works"
      }
    ]
  }'
```

Gemini思维模型也产生 [思想总结](/docs/thinking#summaries)。您可以使用 [`extra_body`](/docs/openai#extra-body) 字段以在您的请求中包含 Gemini 字段。

请注意 `reasoning_effort` 和 `thinking_level`/`thinking_budget` 功能重叠，因此不能同时使用。
{% /tab %}

{% tab filename="sample.py" label="Python" %}
```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": "user", "content": "Explain to me how AI works"}],
    extra_body={
      'extra_body': {
        "google": {
          "thinking_config": {
            "thinking_level": "high",
            "include_thoughts": True
          }
        }
      }
    }
)

print(response.choices[0].message)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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-4-hydrogen",
    messages: [{role: "user", content: "Explain to me how AI works",}],
    extra_body: {
      "google": {
        "thinking_config": {
          "thinking_level": "high",
          "include_thoughts": true
        }
      }
    }
});

console.log(response.choices[0].message);
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```shell
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer GEMINI_API_KEY" \
  -d '{
      "model": "gemini-4-hydrogen",
        "messages": [{"role": "user", "content": "Explain to me how AI works"}],
        "extra_body": {
          "google": {
            "thinking_config": {
              "thinking_level": "high",
              "include_thoughts": true
            }
          }
        }
      }'
```

Gemini 3 支持聊天完成 API 中思想签名的 OpenAI 兼容性。您可以在以下位置找到完整的示例 [思想签名](/docs/thought-signatures?generate-content=true#openai) 页。
{% /tab %}
{% /tabs %}

## 流式输出  {% #streaming %}

Gemini API 支持 [流式响应](/docs/text-generation#streaming-responses).

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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-4-hydrogen",
    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);
  }
}

await main();
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer GEMINI_API_KEY" \
  -d '{
      "model": "gemini-4-hydrogen",
      "messages": [
          {"role": "user", "content": "Explain to me how AI works"}
      ],
      "stream": true
    }'
```
{% /tab %}
{% /tabs %}

## 函数调用  {% #function-calling %}

函数调用让您更轻松地从生成模型获得结构化数据输出，并且 [Gemini API 支持](/docs/function-calling).

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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-4-hydrogen",
    messages: messages,
    tools: tools,
    tool_choice: "auto",
  });

  console.log(response);
}

await main();
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
  "model": "gemini-4-hydrogen",
  "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"
}'
```
{% /tab %}
{% /tabs %}

## 图像理解  {% #image-understanding %}

Gemini 型号本身就是多模态的，可提供一流的性能 [许多常见的视觉任务](/docs/image-understanding).

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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])
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
import OpenAI from "openai";
import fs from 'fs';

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

function encodeImage(imagePath = '') {
  try {
    const imageBuffer = fs.readFileSync(imagePath);
    return imageBuffer.toString('base64');
  } catch (error) {
    console.error("Error encoding image:", error);
    return '';
  }
}

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-4-hydrogen",
      messages: messages,
    });

    console.log(response.choices[0]);
  } catch (error) {
    console.error("Error calling Gemini API:", error);
  }
}

await main();
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
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-4-hydrogen\",
      \"messages\": [
        {
          \"role\": \"user\",
          \"content\": [
            { \"type\": \"text\", \"text\": \"What is in this image?\" },
            {
              \"type\": \"image_url\",
              \"image_url\": { \"url\": \"data:image/jpeg;base64,${base64_image}\" }
            }
          ]
        }
      ]
    }"
'
```
{% /tab %}
{% /tabs %}

## 生成图像  {% #generate-image %}

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

{% callout type="note" %}
您可以启用 **使用 Google 搜索提供事实依据** 并配置 **安全设置**
使用 `extra_body` 参数。请参阅 [`extra_body`](/docs/openai#extra-body) 可用参数部分。 事实依据和 Google 搜索仅适用于 Gemini 3 及更新型号。
{% /callout %}

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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()
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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);
}

await main();
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
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,
      }'
```
{% /tab %}
{% /tabs %}

## 生成视频  {% #generate-video %}

{% callout type="warning" %}
Veo 3.1 预览 (`veo-3.1-generate-preview`, `veo-3.1-fast-generate-preview`, 和 `veo-3.1-lite-generate-preview`）在 Gemini API 中是 [关闭](/docs/deprecations) 在 **十月 22, 2026**。迁移到 [Gemini Omni Flash](/docs/omni) (`gemini-omni-1.2-flash`）使用本机 Google GenAI SDK （[Interactions API](/docs/interactions-overview)）或可通过以下方式获得的 GA 模型 [Gemini Enterprise Agent Platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/veo/3-1-generate)
以避免服务中断。视频生成 `gemini-omni-1.2-flash` OpenAI 兼容的设备不支持 `/v1/videos` 端点。
{% /callout %}

## 音频理解  {% #audio-understanding %}

分析音频输入：

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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 = audioFile.toString('base64');

async function main() {
  const response = await client.chat.completions.create({
    model: "gemini-4-hydrogen",
    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);
}

await main();
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
注意：如果您收到 `Argument list too long` 错误，您的音频文件的编码对于curl 来说可能太长。

```bash
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-4-hydrogen\",
      \"messages\": [
        {
          \"role\": \"user\",
          \"content\": [
            { \"type\": \"text\", \"text\": \"Transcribe this audio file.\" },
            {
              \"type\": \"input_audio\",
              \"input_audio\": {
                \"data\": \"${base64_audio}\",
                \"format\": \"wav\"
              }
            }
          ]
        }
      ]
    }"
'
```
{% /tab %}
{% /tabs %}

## 结构化输出  {% #structured-output %}

Gemini模型可以以任何方式输出JSON对象 [您定义的结构](/docs/structured-output).

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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-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: zodResponseFormat(CalendarEvent, "event"),
});

const event = completion.choices[0].message.parsed;
console.log(event);
```
{% /tab %}
{% /tabs %}

## 嵌入  {% #embeddings %}

文本嵌入衡量文本字符串的相关性，可以使用以下命令生成 [Gemini API](/docs/embeddings)。您可以使用 `gemini-embedding-2` 对于多模态嵌入或 `gemini-embedding-001` 用于纯文本嵌入。

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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",
    input: "Your text string goes here",
  });

  console.log(embedding);
}

await main();
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
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"
  }'
```
{% /tab %}
{% /tabs %}

## Batch API  {% #batch %}

您可以创建 [批处理作业](/docs/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` 客户端用于上传和下载 [文件](/docs/files)，与使用Gemini时相同 [Batch API](/docs/batch-api#input-file).

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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 生成嵌入](/docs/batch-api#batch-embedding)。为此，请关闭 `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"
)
```

请参阅 [批量嵌入生成](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Get_started_OpenAI_Compatibility.ipynb)
OpenAI 兼容性说明书部分的完整示例。
{% /tab %}
{% /tabs %}

## 弹性和优先级推理  {% #inference %}

Gemini API 与 OpenAI 匹配 `service_tier` 名称和逻辑中的参数，强制执行限制并优雅地引导 Flex 和 Priority 推理层的流量。

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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。了解有关推理层的更多信息 [优化](/docs/optimization) 文档。
{% /tab %}
{% /tabs %}

## 启用 Gemini 功能 `extra_body` {% #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-example %}

这是一个使用示例 `extra_body` 设置 `cached_content`:

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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())
```
{% /tab %}
{% /tabs %}

## 列出型号  {% #list-models %}

获取可用 Gemini 型号的列表：

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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);
  }
}
await main();
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl https://generativelanguage.googleapis.com/v1beta/openai/models \
-H "Authorization: Bearer GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

## 检索模型  {% #retrieve-model %}

检索 Gemini 模型：

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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-4-hydrogen");
  console.log(model.id);
}

await main();
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl https://generativelanguage.googleapis.com/v1beta/openai/models/gemini-4-hydrogen \
-H "Authorization: Bearer GEMINI_API_KEY"
```
{% /tab %}
{% /tabs %}

## 目前的限制  {% #current-limitations %}

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

如果您对支持的参数、即将推出的功能有疑问，或者在开始使用 Gemini 时遇到任何问题，请加入我们的 [开发者论坛](https://discuss.ai.google.dev/c/gemini-api/4).

## 后续步骤  {% #whats-next %}

试试我们的 [OpenAI 兼容性 Colab](https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_OpenAI_Compatibility.ipynb) 完成更详细的示例。
