Google 原生协议

# Google 原生协议调用文档

Google 原生接口采用 GenerateContent 协议，通过 `contents` 和 `parts` 提交输入内容，返回 Google 格式的生成结果，支持非流式响应和 SSE 流式响应。
> 该协议仅支持gemini系列模型

本文示例模型为 `gemini-3.5-flash`。

## 接口信息

| 项目     | 内容                                                        |
| -------- | ----------------------------------------------------------- |
| 基础地址 | `https://aiproxy-api.cloudcare.cn`                          |
| 普通生成 | `POST /v1beta/models/{model}:generateContent`               |
| 流式生成 | `POST /v1beta/models/{model}:streamGenerateContent?alt=sse` |
| 鉴权     | `x-goog-api-key: <平台 API Key>`                            |
| 请求类型 | `Content-Type: application/json`                            |

也支持 `/v1/models/{model}:generateContent` 和对应的流式入口。模型名称写在 URL 中，请求体无需添加 `model`。

调用示例使用环境变量 `AIPROXY_API_KEY` 传递平台 API Key。请将 `YOUR_API_KEY` 替换为实际密钥。

```bash
export AIPROXY_API_KEY='YOUR_API_KEY'
```

同时支持 `Authorization: Bearer <平台 API Key>` 鉴权。每次请求使用一种鉴权方式。

## 非流式调用

### 请求示例

```bash
curl 'https://aiproxy-api.cloudcare.cn/v1beta/models/gemini-3.5-flash:generateContent' \
  -H "x-goog-api-key: ${AIPROXY_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "systemInstruction": {
      "parts": [{"text": "你是一个专业的技术助手，请使用中文回答。"}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "简要解释什么是可观测性。"}]}
    ],
    "generationConfig": {"maxOutputTokens": 512}
  }'
```

### 响应示例

以下为响应结构示例，内容及用量数值仅供参考。

```json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "可观测性是通过系统输出理解其内部状态的能力。"}]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 30,
    "candidatesTokenCount": 40,
    "totalTokenCount": 70
  }
}
```

读取 `candidates[].content.parts[]` 中的文本。响应也可能包含非文本内容或思考部分，需按 part 类型处理；受到安全策略限制时，候选内容可能为空。

## 请求参数

| 参数                                  | 类型    | 必填 | 说明                                      |
| ------------------------------------- | ------- | ---- | ----------------------------------------- |
| `contents`                            | array   | 是   | 当前输入及必要的对话历史                  |
| `contents[].role`                     | string  | 否   | 用户使用 `user`，模型历史回复使用 `model` |
| `contents[].parts`                    | array   | 是   | 内容片段列表，文本使用 `{"text":"内容"}`  |
| `systemInstruction`                   | object  | 否   | 系统指令，以 `parts` 组织                 |
| `generationConfig.maxOutputTokens`    | integer | 否   | 输出 Token 上限                           |
| `generationConfig.temperature`        | number  | 否   | 采样随机性，支持范围由模型决定            |
| `tools`                               | array   | 否   | 可调用的工具定义                          |
| `toolConfig`                          | object  | 否   | 工具调用策略，需要模型支持                |
| `safetySettings`                      | array   | 否   | 上游支持的安全设置                        |
| `generationConfig.topP`               | number  | 否   | 核采样参数，需模型支持                    |
| `generationConfig.topK`               | integer | 否   | 候选 Token 采样数量，需模型支持           |
| `generationConfig.stopSequences`      | array   | 否   | 停止序列                                  |
| `generationConfig.responseMimeType`   | string  | 否   | 如 `application/json`                     |
| `generationConfig.responseJsonSchema` | object  | 否   | JSON 输出结构，需模型支持                 |
| `generationConfig.thinkingConfig`     | object  | 否   | 思考设置，支持字段及范围由模型决定        |

字段格式参见 [Google GenerateContent API](https://ai.google.dev/api/generate-content)。图片、音频和工具调用等扩展能力由实际模型和渠道决定。

## 流式调用

### 请求示例

```bash
curl -N 'https://aiproxy-api.cloudcare.cn/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse' \
  -H "x-goog-api-key: ${AIPROXY_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "介绍日志、指标和链路追踪的区别。"}]}
    ]
  }'
```

### 响应示例

以下为 SSE 数据片段，省略部分元数据。

```text
data: {"candidates":[{"content":{"role":"model","parts":[{"text":"日志记录"}]},"index":0}]}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"离散事件。"}]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":20,"candidatesTokenCount":30,"totalTokenCount":50}}
```

流式由 URL 中的 `streamGenerateContent` 决定，请求体不需要设置 `stream: true`。逐事件处理 `candidates`，拼接文本片段；Google 原生流不使用 OpenAI 的 `[DONE]` 结束标记。

## 多轮对话

通过 `contents` 按时间顺序传入历史消息和当前问题，模型回复的角色为 `model`。请求体示例：

```json
{
  "contents": [
    {"role": "user", "parts": [{"text": "什么是可观测性？"}]},
    {"role": "model", "parts": [{"text": "可观测性是通过系统输出理解其内部状态的能力。"}]},
    {"role": "user", "parts": [{"text": "给出一个订单服务的应用例子。"}]}
  ],
  "generationConfig": {"maxOutputTokens": 512}
}
```

工具调用记录及模型返回的 `thoughtSignature` 应随原始内容保留在后续请求中。

## 结构化输出

通过 `responseMimeType` 和 `responseJsonSchema` 指定 JSON 输出格式及结构。以下示例适用于支持结构化输出的模型。

```json
{
  "contents": [{
    "role": "user",
    "parts": [{"text": "订单服务发生超时，请提取服务名和问题摘要。"}]
  }],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseJsonSchema": {
      "type": "object",
      "properties": {
        "service": {"type": "string"},
        "summary": {"type": "string"}
      },
      "required": ["service", "summary"]
    }
  }
}
```

结构化结果以 JSON 字符串形式返回于候选内容的 `parts[].text` 中，由客户端解析。`responseJsonSchema` 与 `responseSchema` 不同时设置；可用 Schema 特性由模型决定，业务字段值由客户端校验。参见 [Google Structured Outputs](https://ai.google.dev/gemini-api/docs/generate-content/structured-output)。

## 工具调用

### 声明工具

通过 `tools[].functionDeclarations` 声明函数。以下为 `generateContent` 请求体示例，适用于支持工具调用的模型。

```json
{
  "contents": [{"role": "user", "parts": [{"text": "查询订单 A1001 的状态。"}]}],
  "tools": [{
    "functionDeclarations": [{
      "name": "lookup_order",
      "description": "根据订单编号查询订单状态",
      "parameters": {
        "type": "OBJECT",
        "properties": {"order_id": {"type": "STRING"}},
        "required": ["order_id"]
      }
    }]
  }]
}
```

### 返回工具执行结果

候选内容包含 `functionCall` 时，客户端读取函数名及 `args`，校验参数后执行函数。后续请求保留原始 `contents`、模型返回的完整候选 `content`，并追加以下工具结果消息：

```json
{
  "role": "user",
  "parts": [{
    "functionResponse": {
      "name": "lookup_order",
      "response": {"status": "shipped"}
    }
  }]
}
```

上述对象为 `contents` 数组中的工具结果消息。后续工具调用应保留工具定义、关联 ID 及模型返回的 `thoughtSignature`。函数由客户端执行，平台负责转发工具调用及结果。流程参见 [Google Function Calling](https://ai.google.dev/gemini-api/docs/function-calling)。

## 图片输入

图片输入适用于支持图片理解的模型。通过 `inlineData` 传入图片的 MIME 类型及 Base64 编码：

```json
{
  "contents": [{
    "role": "user",
    "parts": [
      {"text": "描述这张图片。"},
      {"inlineData": {"mimeType": "image/jpeg", "data": "替换为图片的完整Base64编码"}}
    ]
  }]
}
```

`data` 为原始 Base64 编码，不包含 Data URL 前缀。MIME 类型应与文件一致。上游对媒体大小和格式的限制仍然适用；平台的内容生成接口不提供配套的 Google Files 上传接口。

## 响应状态与流式解析

| 字段或情况                         | 处理方式                               |
| ---------------------------------- | -------------------------------------- |
| `candidates[].finishReason = STOP` | 该候选正常结束                         |
| `MAX_TOKENS`                       | 可能达到生成长度限制，检查输出预算     |
| `SAFETY` 或其他限制原因            | 内容受到限制，应检查结束原因及安全信息 |
| `promptFeedback.blockReason`       | 请求提示被阻止，可能没有候选内容       |
| `parts[].thought = true`           | 思考内容，应与面向用户的回答分开处理   |
| `parts[].functionCall`             | 进入工具调用流程                       |
| 候选为空或没有文本                 | 先检查阻止原因、非文本 part 和错误信息 |

这些字段的定义见 [GenerateContent 响应说明](https://ai.google.dev/api/generate-content#GenerateContentResponse)。

客户端应按 SSE 空行边界组装完整事件，再解析 `data:` 中的 JSON，并按候选索引分别累计文本。HTTP 200 仅表示响应已开始；异常断流时应标记未完成，并保留已收到的结果。

## 用量统计

| 字段                                    | 含义                      |
| --------------------------------------- | ------------------------- |
| `usageMetadata.promptTokenCount`        | 输入 Token 数             |
| `usageMetadata.candidatesTokenCount`    | 候选输出 Token 数         |
| `usageMetadata.thoughtsTokenCount`      | 思考 Token 数，若返回     |
| `usageMetadata.cachedContentTokenCount` | 缓存命中 Token 数，若返回 |
| `usageMetadata.totalTokenCount`         | 总 Token 数               |

流式用量以最后一次返回的统计为准，各事件中的累计值无需重复相加。平台输出用量统计包含候选输出与思考 Token。

此入口覆盖内容生成，不包含 Google Files、Live/WebSocket、`countTokens` 或 Vertex AI OAuth 等服务。

## 错误处理

错误码及处理方式请参阅 [错误响应汇总](https://mrdoc.cloudcare.cn/doc/1042/)。