Gemini 3 Pro Image (Nano Banana Pro) API
Nano Banana 专业版 (GA) — Google Gemini 多模态图像生成. Thinking 推理 + 高保真文本渲染. 1K/2K 同价档, 4K 高端档.
- 模型名:
gemini-3-pro-image - 厂商: Google
- 类型: image
POST /v1beta/models/gemini-3-pro-image:generateContent
gemini-3-pro-image:原生内容生成,含必填项、嵌套响应和虚构示例。
基础调用
必填参数: contents
可用参数: contents, systemInstruction, generationConfig
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|
contents | array | 是 | 对话内容。 |
systemInstruction | object | 否 | 可选系统说明。 |
generationConfig | object | 否 | 可选生成参数;不要套用其他型号的数值上限。 |
## 使用与响应约定
- 必填项与嵌套结构见参数表。未给出数值默认值的可选项,使用该型号当前默认配置。
- 不同型号的上下文、输出预算、素材数量与规格有差异;本页不把未核实的上限写成统一限制。
- 缺失字段与明确的0不同;读取实际返回的状态、内容与用量。
- 示例中的 `example.invalid` 地址必须换成自己有权使用、可被服务读取的素材。
- 生成文件请及时保存;不要假设结果链接永久有效。
## 参考
参数术语参考[Google Image Generation官方说明](https://ai.google.dev/gemini-api/docs/image-generation);调用时使用本页平台域名和精确型号。文档核对日期:2026-11-07。
## 完整嵌套字段说明
数组元素用[]表示;必填标记以所在对象或相应内容块成立为前提。响应字段可能按场景缺失或为null,不应补成虚构的0。
### 请求头
| 字段路径 | 类型 | 所属对象内必填 | 含义 |
|---|---|---|---|
| `Content-Type` | string | 是 | 请求体格式为application/json。 |
### 请求体
| 字段路径 | 类型 | 所属对象内必填 | 含义 |
|---|---|---|---|
| `contents` | array[object] | 是 | 对话内容。 |
| `contents[].role` | string | 否 | 消息角色。 可选值:user, model |
| `contents[].parts` | array[object] | 是 | 顺序排列的内容块,至少包含一项。 |
| `contents[].parts[].text` | string | 否 | 文本内容。 |
| `contents[].parts[].inlineData` | object | 否 | 内联媒体。 |
| `contents[].parts[].inlineData.mimeType` | string | 否 | 媒体 MIME 类型。 |
| `contents[].parts[].inlineData.data` | string | 否 | 媒体的 Base64 字符串,不包含 data: 前缀。 |
| `contents[].parts[].fileData` | object | 否 | 可读取的媒体文件。 |
| `contents[].parts[].fileData.mimeType` | string | 否 | 媒体 MIME 类型。 |
| `contents[].parts[].fileData.fileUri` | string | 否 | 当前接口支持的文件 URI。 |
| `systemInstruction` | object | 否 | 可选系统说明。 |
| `systemInstruction.parts` | array[object] | 否 | 系统文本块。 |
| `systemInstruction.parts[].text` | string | 否 | 系统说明文本。 |
| `generationConfig` | object | 否 | 可选生成参数;不要套用其他型号的数值上限。 |
| `generationConfig.maxOutputTokens` | integer | 否 | 最大输出预算,支持值依型号。 最小值:1 |
| `generationConfig.responseModalities` | array[string] | 否 | 期望的输出模态。 可选值:TEXT, IMAGE |
| `generationConfig.imageConfig` | object | 否 | 可选图像配置,未填写时使用该型号默认值。 |
| `generationConfig.imageConfig.aspectRatio` | string | 否 | 画面比例;选择型号支持的值。 |
### 响应 200
| 字段路径 | 类型 | 所属对象内必填 | 含义 |
|---|---|---|---|
| `candidates` | array[object] | 否 | 生成候选;内容受限时可能为空,请检查反馈。 |
| `candidates[].index` | integer | 否 | 候选序号。 |
| `candidates[].content` | object | 否 | 输出内容。 |
| `candidates[].content.role` | string | 否 | 响应角色。 |
| `candidates[].content.parts` | array[object] | 是 | 顺序排列的内容块,至少包含一项。 |
| `candidates[].content.parts[].text` | string | 否 | 文本内容。 |
| `candidates[].content.parts[].inlineData` | object | 否 | 内联媒体。 |
| `candidates[].content.parts[].inlineData.mimeType` | string | 否 | 媒体 MIME 类型。 |
| `candidates[].content.parts[].inlineData.data` | string | 否 | 媒体的 Base64 字符串,不包含 data: 前缀。 |
| `candidates[].content.parts[].fileData` | object | 否 | 可读取的媒体文件。 |
| `candidates[].content.parts[].fileData.mimeType` | string | 否 | 媒体 MIME 类型。 |
| `candidates[].content.parts[].fileData.fileUri` | string | 否 | 当前接口支持的文件 URI。 |
| `candidates[].finishReason` | string | 否 | 结束原因。 |
| `candidates[].safetyRatings` | array[object] | 否 | 安全反馈项。 |
| `candidates[].safetyRatings[].category` | string | 否 | 反馈类别。 |
| `candidates[].safetyRatings[].probability` | string | 否 | 反馈级别。 |
| `usageMetadata` | object | 否 | 报告的用量,思考与缓存是分项。 |
| `usageMetadata.promptTokenCount` | integer | 否 | 输入 Token。 |
| `usageMetadata.candidatesTokenCount` | integer | 否 | 候选输出 Token。 |
| `usageMetadata.thoughtsTokenCount` | integer | 否 | 思考 Token。 |
| `usageMetadata.cachedContentTokenCount` | integer | 否 | 缓存命中 Token。 |
| `usageMetadata.totalTokenCount` | integer | 否 | 报告的总 Token。 |
| `modelVersion` | string | 否 | 服务端返回的模型版本。 |
| `responseId` | string | 否 | 响应标识。 |
| `promptFeedback` | object | 否 | 输入反馈。 |
| `promptFeedback.blockReason` | string | 否 | 内容受限的原因。 |
### 错误响应结构
| 字段路径 | 类型 | 所属对象内必填 | 含义 |
|---|---|---|---|
| `error` | object | 否 | 错误详情;以本次返回为准。 |
| `error.message` | string | 否 | 消息内容或可读错误说明,依所在对象区分。 |
| `error.type` | string | 否 | 类型标识;依所在对象及枚举取值区分。 |
| `error.code` | string | 否 | 错误码,可能为空。 |
请求示例
curl --request POST https://api.router.ai/v1beta/models/gemini-3-pro-image:generateContent \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "A fictional blue paper boat on a plain white background."
}
]
}
],
"generationConfig": {
"responseModalities": [
"TEXT",
"IMAGE"
]
}
}'