> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hingnet.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI 兼容接口

> 使用 OpenAI 风格 API 调用 Gemini 模型

平台支持使用标准 OpenAI 接口调用 Gemini 模型，只需将 `model` 设为 Gemini 模型名即可。

## 支持的接口

| 接口               | 路径                       | 说明   |
| ---------------- | ------------------------ | ---- |
| Chat Completions | `/v1/chat/completions`   | 对话生成 |
| Embeddings       | `/v1/embeddings`         | 向量嵌入 |
| Images           | `/v1/images/generations` | 图像生成 |

## Chat Completions

```bash theme={null}
curl -X POST "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "system", "content": "你是一个助手"},
      {"role": "user", "content": "你好"}
    ]
  }'
```

### 流式输出

```bash theme={null}
curl -N "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{"role": "user", "content": "写一首诗"}],
    "stream": true
  }'
```

### 多模态

```bash theme={null}
curl -X POST "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "描述图片"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
      ]
    }]
  }'
```

### Chat 图像能力（gemini-2.5-flash-image-preview）

当你希望在对话中直接生成或编辑图片时，可使用 `gemini-2.5-flash-image-preview`：

```bash theme={null}
curl -X POST "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-image-preview",
    "messages": [
      {"role": "user", "content": "生成一张现代感办公室的插画"}
    ]
  }'
```

更多细节与流式示例请参考 [Chat 图像能力](/gemini/chat-image)。

### 工具调用

```bash theme={null}
curl -X POST "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{"role": "user", "content": "北京天气"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}
      }
    }]
  }'
```

### 思考模式

```bash theme={null}
curl -X POST "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{"role": "user", "content": "计算 23*47"}],
    "reasoning_effort": "medium"
  }'
```

## Embeddings

```bash theme={null}
curl -X POST "$BASE_URL/v1/embeddings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-004",
    "input": "文本内容"
  }'
```

## Images

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-3.0-generate-001",
    "prompt": "a cat reading",
    "size": "1024x1024"
  }'
```

## 参数映射

平台自动完成格式转换：

| OpenAI 参数          | Gemini 参数              |
| ------------------ | ---------------------- |
| `messages`         | `contents`             |
| `tools`            | `functionDeclarations` |
| `response_format`  | `responseMimeType`     |
| `reasoning_effort` | `thinkingConfig`       |
| `max_tokens`       | `maxOutputTokens`      |

## SDK 示例

### Python

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="your-token",
    base_url="https://models.hingnet.com.cn/v1"
)

# 对话
response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "你好"}]
)

# 流式
for chunk in client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "写诗"}],
    stream=True
):
    print(chunk.choices[0].delta.content or "", end="")

# 向量
embedding = client.embeddings.create(
    model="text-embedding-004",
    input="文本"
)
```

### Node.js

```javascript theme={null}
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'your-token',
  baseURL: 'https://models.hingnet.com.cn/v1'
});

const response = await client.chat.completions.create({
  model: 'gemini-2.5-flash',
  messages: [{ role: 'user', content: '你好' }]
});
```

## Gemini 专用入口

除统一入口外，也可使用 Gemini 专用的 OpenAI 兼容路径：

```
/v1beta/openai/chat/completions
/v1beta/openai/embeddings
/v1beta/openai/images/generations
```

两种入口行为一致，专用入口与 Google 官方文档路径对齐。