Gemini 官方格式 - 数字先锋API文档

# Gemini 官方格式 API 文档

## 1. 接口地址

### Base URL
```text
https://api.cxsee.com
```

### 生成内容（Generate Content）
```http
POST /v1beta/models/{model}:generateContent
```

完整示例：
```text
https://api.cxsee.com/v1beta/models/gemini-2.5-pro:generateContent
```

---

## 2. 认证方式

使用 Bearer Token：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

---

## 3. 支持模型（当前已验证）

- `gemini-2.5-pro`

> 后续如新增模型，请以平台公告为准。

---

## 4. 请求参数（Gemini 官方格式）

### 请求体结构
```json
{
  "contents": [
    {
      "parts": [
        { "text": "你的问题" }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingBudget": 128,
      "includeThoughts": true
    }
  }
}
```

### 字段说明

- `contents` *(必填)*：对话内容数组
  - `parts[].text`：用户输入文本
- `generationConfig` *(选填)*：生成配置
  - `thinkingConfig.thinkingBudget` *(选填)*：思考预算（token）
  - `thinkingConfig.includeThoughts` *(选填)*：是否返回思考内容（`true` 时响应中可能包含 `thought: true` 的片段）

---

## 5. 请求示例（cURL）

### 基础调用
```bash
curl --location --request POST "https://api.cxsee.com/v1beta/models/gemini-2.5-pro:generateContent" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "contents": [
      {
        "parts": [
          { "text": "Explain how AI works in a few words" }
        ]
      }
    ]
  }'
```

### 开启思考输出
```bash
curl --location --request POST "https://api.cxsee.com/v1beta/models/gemini-2.5-pro:generateContent" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "contents": [
      {
        "parts": [
          { "text": "Explain how AI works in a few words" }
        ]
      }
    ],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingBudget": 128,
        "includeThoughts": true
      }
    }
  }'
```

---

## 6. 成功响应示例（200）

```json
{
  "candidates": [
    {
      "content": {
        "parts": [
          { "text": "In a few words, AI works by: Finding patterns in data to make predictions." }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 19,
    "totalTokenCount": 109,
    "thoughtsTokenCount": 81
  },
  "modelVersion": "gemini-2.5-pro",
  "responseId": "xxxx"
}
```

---

## 7. 错误码说明

- `400 Bad Request`：请求参数格式错误
- `401 Unauthorized`：API Key 无效或缺失
- `403 Forbidden`：无权限访问该模型
- `404 Not Found`：接口路径错误
- `405 Method Not Allowed`：请求方法错误（例如用 GET 调 POST 接口）
- `429 Too Many Requests`：请求频率超限
- `500/502/503`：服务端临时异常

---

## 8. 使用建议

1. **务必保护 API Key**，不要出现在前端代码或公开仓库。
2. 如果开启 `includeThoughts: true`，会增加 token 消耗。
3. 建议客户端设置超时与重试机制（指数退避）。
4. 生产环境请记录 `responseId` 便于问题排查。

---

## 9. 兼容性说明

本平台提供 **Gemini 官方请求/响应格式兼容** 的网关能力。
如需 OpenAI 兼容格式，可使用：
- `POST /v1/chat/completions`

---

上一篇：Claude Chat（OpenAI 兼容）下一篇：Responses（联网搜索）