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

# generateContent

> POST /v1beta/models/{model}:generateContent —— Gemini 原生协议

Gemini 原生协议,支持多模态输入(图片 / PDF / 音频 / 视频)与函数调用。

## 请求

```bash theme={null}
curl "https://openp.ai/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $OPENPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "用中文介绍一下傅立叶变换"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 2048,
      "topP": 0.95
    }
  }'
```

### 路径变量

| 变量        | 说明                                      |
| --------- | --------------------------------------- |
| `{model}` | Gemini 模型 ID,如 `gemini-3.1-pro-preview` |

### 主要字段

| 字段                                  | 类型      | 说明                             |
| ----------------------------------- | ------- | ------------------------------ |
| `contents`                          | array   | 对话内容,`role` 为 `user` / `model` |
| `systemInstruction`                 | object  | system prompt                  |
| `generationConfig.temperature`      | number  | 0-2                            |
| `generationConfig.topP`             | number  |                                |
| `generationConfig.topK`             | integer |                                |
| `generationConfig.maxOutputTokens`  | integer | 最大输出                           |
| `generationConfig.candidateCount`   | integer | 1-8                            |
| `generationConfig.stopSequences`    | array   |                                |
| `generationConfig.responseMimeType` | string  | `application/json` 启用结构化输出     |
| `generationConfig.responseSchema`   | object  | JSON Schema 强约束                |
| `generationConfig.thinkingConfig`   | object  | `{ thinkingBudget: 8000 }`     |
| `tools`                             | array   | 函数 / 检索工具                      |
| `toolConfig`                        | object  | `function_calling_config`      |
| `safetySettings`                    | array   | 安全过滤等级                         |

### parts 类型

```json theme={null}
{"role": "user", "parts": [
  {"text": "看这张图"},
  {"inline_data": {"mime_type": "image/png", "data": "<base64>"}},
  {"file_data": {"mime_type": "application/pdf", "file_uri": "https://..."}}
]}
```

## 响应

```json theme={null}
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "傅立叶变换是..."}]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [...]
    }
  ],
  "promptFeedback": {"safetyRatings": [...]},
  "usageMetadata": {
    "promptTokenCount": 15,
    "candidatesTokenCount": 412,
    "totalTokenCount": 427,
    "cachedContentTokenCount": 0,
    "thoughtsTokenCount": 0
  }
}
```

`finishReason`:`STOP` / `MAX_TOKENS` / `SAFETY` / `RECITATION` / `OTHER`。

## 函数调用

```json theme={null}
{
  "contents": [{"role": "user", "parts": [{"text": "北京天气"}]}],
  "tools": [{
    "functionDeclarations": [{
      "name": "get_weather",
      "description": "Get weather for a city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }]
  }]
}
```

响应中包含 `functionCall`:

```json theme={null}
{
  "candidates": [{
    "content": {"role": "model", "parts": [
      {"functionCall": {"name": "get_weather", "args": {"city": "北京"}}}
    ]}
  }]
}
```

执行后追加 `functionResponse`:

```json theme={null}
{"role": "user", "parts": [{
  "functionResponse": {
    "name": "get_weather",
    "response": {"city": "北京", "temp": 18, "desc": "晴"}
  }
}]}
```

## 思考模式

```json theme={null}
{
  "contents": [{"role": "user", "parts": [{"text": "证明哥德巴赫猜想"}]}],
  "generationConfig": {
    "thinkingConfig": { "thinkingBudget": 8000 }
  }
}
```

或使用带 `-thinking` 后缀的模型 ID:`gemini-2.5-pro-thinking`。

## 结构化输出

```json theme={null}
{
  "contents": [{"role": "user", "parts": [{"text": "返回一个 user JSON"}]}],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
      },
      "required": ["name", "age"]
    }
  }
}
```