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

# 文本生成

> 使用 Gemini 原生 generateContent / streamGenerateContent 完成普通文本对话、结构化输出和流式生成。

Gemini 原生格式适合希望直接使用 Gemini `contents[].parts[]`、`systemInstruction`、`generationConfig` 等字段的客户。平台会保留原生请求体并转发到可用的 Gemini 上游，响应保持 `candidates`、`finishReason`、`usageMetadata` 等 Gemini 风格字段。

<Note>
  如果客户已经按 OpenAI `messages` 结构接入，可以优先看「Gemini / OpenAI 兼容 / 文本生成」。如果客户需要最完整的 Gemini 原生参数、图片、视频或文档输入，建议使用本节原生格式。
</Note>

## 接口地址

非流式：

```http theme={null}
POST https://{your-domain}/v1beta/models/{model}:generateContent
```

流式：

```http theme={null}
POST https://{your-domain}/v1beta/models/{model}:streamGenerateContent?alt=sse
```

示例模型：

```text theme={null}
gemini-3.5-flash
```

## 鉴权

推荐使用 Google 风格 API Key 请求头：

```http theme={null}
x-goog-api-key: YOUR_API_KEY
Content-Type: application/json
```

平台也兼容 Bearer 请求头：

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

客户文档和示例建议统一使用 `x-goog-api-key`，这样与 Gemini 官方 REST / SDK 示例更接近；如果客户侧已有 OpenAI 网关鉴权封装，也可以使用 `Authorization: Bearer`。

## 请求结构

| 字段                                  | 类型      | 必填 | 说明                                |
| ----------------------------------- | ------- | -- | --------------------------------- |
| `contents`                          | array   | 是  | 对话内容数组。每个元素通常包含 `role` 和 `parts`。 |
| `contents[].role`                   | string  | 否  | 常用值为 `user` 或 `model`，多轮对话时可交替传入。 |
| `contents[].parts`                  | array   | 是  | 内容片段数组。文本生成通常只传 `text`。           |
| `contents[].parts[].text`           | string  | 是  | 用户输入、上下文或指令文本。                    |
| `systemInstruction.parts[].text`    | string  | 否  | 系统指令，用于指定角色、语气、输出格式、约束条件。         |
| `generationConfig.maxOutputTokens`  | integer | 否  | 最大输出 token 数。                     |
| `generationConfig.temperature`      | number  | 否  | 随机性，越高越发散。                        |
| `generationConfig.topP`             | number  | 否  | nucleus sampling 参数。              |
| `generationConfig.responseMimeType` | string  | 否  | 需要 JSON 时可传 `application/json`。   |

## 非流式文本生成

### curl

```bash theme={null}
curl --request POST \
  --url 'https://{your-domain}/v1beta/models/gemini-3.5-flash:generateContent' \
  --header 'x-goog-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "systemInstruction": {
      "parts": [
        {
          "text": "你是一个面向企业客户的中文技术顾问，回答要准确、简洁、可落地。"
        }
      ]
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请用三句话介绍 Gemini 原生文本生成接口，说明它适合什么场景。"
          }
        ]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 512,
      "temperature": 0.4,
      "topP": 0.9
    }
  }'
```

### 请求体

```json theme={null}
{
  "systemInstruction": {
    "parts": [
      {
        "text": "你是一个面向企业客户的中文技术顾问，回答要准确、简洁、可落地。"
      }
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请用三句话介绍 Gemini 原生文本生成接口，说明它适合什么场景。"
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512,
    "temperature": 0.4,
    "topP": 0.9
  }
}
```

### 响应示例

```json theme={null}
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Gemini 原生文本生成接口使用 contents 和 parts 组织输入，适合希望保持 Gemini 官方请求结构的客户。它可以用于普通问答、摘要、改写、分类、结构化提取等文本任务。相比 OpenAI 兼容格式，原生格式更便于继续扩展图片、视频、文档和 Gemini 专属生成参数。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 52,
    "candidatesTokenCount": 78,
    "totalTokenCount": 130
  }
}
```

## 流式文本生成

流式接口通过 SSE 返回 `data:` 事件。URL 必须使用 `:streamGenerateContent?alt=sse`，curl 建议加 `-N` 关闭本地缓冲。

### curl

```bash theme={null}
curl -N --request POST \
  --url 'https://{your-domain}/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse' \
  --header 'x-goog-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请流式输出一段中文说明，介绍企业如何接入 Gemini 原生文本生成。"
          }
        ]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 512
    }
  }'
```

### 请求体

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请流式输出一段中文说明，介绍企业如何接入 Gemini 原生文本生成。"
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512
  }
}
```

### 响应示例

```text theme={null}
data: {"candidates":[{"content":{"role":"model","parts":[{"text":"企业接入"}]},"finishReason":null,"index":0}],"usageMetadata":{"promptTokenCount":24,"totalTokenCount":24}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":" Gemini 原生文本生成时，先确认模型名称和 API Key 权限，然后按 generateContent 的 contents/parts 结构提交请求。"}]},"finishReason":null,"index":0}],"usageMetadata":{"promptTokenCount":24,"totalTokenCount":24}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"如果需要实时展示结果，可以切换到 streamGenerateContent 并按 SSE 事件逐段读取。"}]},"finishReason":null,"index":0}],"usageMetadata":{"promptTokenCount":24,"candidatesTokenCount":45,"totalTokenCount":69}}

data: {"candidates":[{"content":{"role":"model","parts":[]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":24,"candidatesTokenCount":45,"totalTokenCount":69}}
```

## 多轮对话

多轮对话可以把历史消息继续放在 `contents` 中。上一轮模型输出使用 `role: "model"`，下一轮用户追问使用 `role: "user"`。

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请介绍 Gemini 原生接口。"
        }
      ]
    },
    {
      "role": "model",
      "parts": [
        {
          "text": "Gemini 原生接口使用 contents 和 parts 组织输入，支持文本和多模态内容。"
        }
      ]
    },
    {
      "role": "user",
      "parts": [
        {
          "text": "请补充它和 OpenAI 兼容接口的区别。"
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 512
  }
}
```

## JSON 输出

需要模型尽量返回 JSON 时，可以通过系统指令和 `responseMimeType` 同时约束。

```json theme={null}
{
  "systemInstruction": {
    "parts": [
      {
        "text": "只返回 JSON，不要返回 Markdown。"
      }
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "把这句话分类：客户希望查看本月账单明细。返回字段 category 和 reason。"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "maxOutputTokens": 256
  }
}
```

## Python 示例

```python theme={null}
import requests

api_key = "YOUR_API_KEY"
model = "gemini-3.5-flash"
url = f"https://{{your-domain}}/v1beta/models/{model}:generateContent"

payload = {
    "contents": [
        {
            "role": "user",
            "parts": [
                {"text": "请用三句话介绍 Gemini 原生文本生成接口。"},
            ],
        }
    ],
    "generationConfig": {
        "maxOutputTokens": 512,
        "temperature": 0.4,
    },
}

resp = requests.post(
    url,
    headers={
        "x-goog-api-key": api_key,
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
resp.raise_for_status()
print(resp.json())
```

## JavaScript 示例

```javascript theme={null}
const apiKey = "YOUR_API_KEY";
const model = "gemini-3.5-flash";

const response = await fetch(
  `https://{your-domain}/v1beta/models/${model}:generateContent`,
  {
    method: "POST",
    headers: {
      "x-goog-api-key": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [
        {
          role: "user",
          parts: [
            { text: "请用三句话介绍 Gemini 原生文本生成接口。" },
          ],
        },
      ],
      generationConfig: {
        maxOutputTokens: 512,
        temperature: 0.4,
      },
    }),
  }
);

if (!response.ok) {
  throw new Error(await response.text());
}

console.log(await response.json());
```

## 常见问题

| 场景                           | 表现                        | 处理方式                                                         |
| ---------------------------- | ------------------------- | ------------------------------------------------------------ |
| 请求体里传了 `model`               | 上游可能忽略或报错                 | Gemini 原生模型写在 URL 路径中，请求体不需要 `model`。                        |
| 流式接口没有实时输出                   | 客户端拿到完整响应后才展示             | curl 使用 `-N`，服务端和前端按 SSE `data:` 事件逐段处理。                     |
| 返回 `model_not_allowed`       | API Key 没有模型权限            | 检查 `/v1/models` 或联系平台开通模型。                                   |
| 返回 `model_endpoint_mismatch` | 模型没有绑定 Gemini 原生 endpoint | 使用支持 `/v1beta/models/{model}:generateContent` 的 Gemini 模型。   |
| JSON 输出不稳定                   | 模型返回 Markdown 或自然语言       | 增加 `responseMimeType: "application/json"`，并在系统指令中要求只返回 JSON。 |