> ## 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 接口通过文本提示词生成图片。 Gemini 原生图片生成使用 `contents[].parts[].text` 传入提示词，并通过 `generationConfig.imageConfig` 设置图片比例和分辨率。生成结果以 Base64 形式返回在 `candidates[].content.parts[].inlineData` 中。 ## 接口地址 ```http theme={null} POST https://{your-domain}/v1beta/models/{model}:generateContent ``` 可用图片模型可能随上游调整。调用前请通过 `GET /v1/models` 查询当前 API Key 可用的模型，并选择支持图片输出的 Gemini 模型。支持模型包括： ```text theme={null} gemini-2.5-flash-image gemini-2.5-flash-image-preview gemini-3.1-flash-image gemini-3.1-flash-image-preview gemini-3-pro-image-preview ``` ## 鉴权 推荐使用 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 ``` ## 请求结构 | 字段 | 类型 | 必填 | 说明 | | ------------------------------------------ | ------ | -- | -------------------------------------------------- | | `contents` | array | 是 | 对话内容数组。图片生成时通常只需要一条用户消息。 | | `contents[].role` | string | 否 | 建议设置为 `user`。 | | `contents[].parts[].text` | string | 是 | 图片生成提示词，可使用中文或英文。 | | `generationConfig.responseModalities` | array | 建议 | 只需要图片时传 `["IMAGE"]`；需要文字和图片时传 `["TEXT", "IMAGE"]`。 | | `generationConfig.imageConfig.aspectRatio` | string | 否 | 图片宽高比，例如 `1:1`、`3:2`、`4:3`、`9:16` 或 `16:9`。 | | `generationConfig.imageConfig.imageSize` | string | 否 | 图片分辨率，例如 `1K`、`2K` 或 `4K`；实际支持范围取决于模型。 | 常见宽高比包括： ```text theme={null} 1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9 ``` 不同模型支持的比例和分辨率可能不同。若请求返回参数错误，请先确认当前模型能力。预览模型也可能调整或下线，生产环境不要写死未经验证的模型名称。 ## curl 示例 ```bash theme={null} curl --request POST \ --url 'https://{your-domain}/v1beta/models/gemini-3.1-flash-image:generateContent' \ --header 'x-goog-api-key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "contents": [ { "role": "user", "parts": [ { "text": "生成一座漂浮在日出云海上方的天文研究岛微缩模型，采用高细节等距视角和手工黏土 3D 风格。画面为宽幅 16:9 构图，不要人物、文字、标志或水印。" } ] } ], "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": { "aspectRatio": "16:9", "imageSize": "1K" } } }' ``` ## 请求体 ```json theme={null} { "contents": [ { "role": "user", "parts": [ { "text": "生成一座漂浮在日出云海上方的天文研究岛微缩模型，采用高细节等距视角和手工黏土 3D 风格。画面为宽幅 16:9 构图，不要人物、文字、标志或水印。" } ] } ], "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": { "aspectRatio": "16:9", "imageSize": "1K" } } } ``` ## 响应示例 ```json theme={null} { "candidates": [ { "content": { "parts": [ { "inlineData": { "mimeType": "image/jpeg", "data": "/9j/4AAQSkZJRgABAQEBLAEs..." } } ], "role": "model" }, "finishReason": "STOP" } ], "usageMetadata": { "promptTokenCount": 38, "candidatesTokenCount": 1584, "totalTokenCount": 1622 }, "modelVersion": "gemini-3.1-flash-image" } ``` 图片数据位于 `candidates[0].content.parts[]` 中包含 `inlineData` 的片段。`inlineData.mimeType` 表示实际图片格式，`inlineData.data` 是不带 Data URI 前缀的 Base64 字符串。 ## Python 示例 ```python theme={null} import base64 from pathlib import Path import requests api_key = "YOUR_API_KEY" model = "gemini-3.1-flash-image" url = f"https://{{your-domain}}/v1beta/models/{model}:generateContent" payload = { "contents": [ { "role": "user", "parts": [ {"text": "生成一幅雨后城市街道的电影感夜景，16:9 构图，不要文字或水印。"}, ], } ], "generationConfig": { "responseModalities": ["IMAGE"], "imageConfig": { "aspectRatio": "16:9", "imageSize": "1K", }, }, } resp = requests.post( url, headers={ "x-goog-api-key": api_key, "Content-Type": "application/json", }, json=payload, timeout=300, ) resp.raise_for_status() parts = resp.json()["candidates"][0]["content"]["parts"] image = next(part["inlineData"] for part in parts if "inlineData" in part) suffix = ".png" if image["mimeType"] == "image/png" else ".jpg" Path(f"generated-image{suffix}").write_bytes(base64.b64decode(image["data"])) ``` ## JavaScript 示例 ```javascript theme={null} import { writeFile } from "node:fs/promises"; const apiKey = "YOUR_API_KEY"; const model = "gemini-3.1-flash-image"; 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: "生成一幅雨后城市街道的电影感夜景，16:9 构图，不要文字或水印。" }, ], }, ], generationConfig: { responseModalities: ["IMAGE"], imageConfig: { aspectRatio: "16:9", imageSize: "1K", }, }, }), } ); if (!response.ok) { throw new Error(await response.text()); } const result = await response.json(); const image = result.candidates[0].content.parts.find( (part) => part.inlineData ).inlineData; const extension = image.mimeType === "image/png" ? "png" : "jpg"; await writeFile(`generated-image.${extension}`, Buffer.from(image.data, "base64")); ``` ## 最佳实践 | 建议 | 说明 | | ---------- | ---------------------------------------------- | | 明确描述构图 | 在提示词中写明主体、环境、镜头、光线、风格和宽高比。 | | 明确排除项 | 不需要人物、文字、标志或水印时，在提示词中直接说明。 | | 及时解码图片 | Base64 响应体较大，收到后应及时解码保存，不要长期记录完整响应。 | | 提高客户端超时 | 图片生成耗时通常高于文本请求，建议将超时设置为数分钟。 | | 校验 MIME 类型 | 保存文件时以 `inlineData.mimeType` 为准，不要假定一定返回 JPEG。 | ## 常见问题 | 场景 | 表现 | 处理方式 | | ---------------------- | ------------------- | ----------------------------------------------- | | 返回 `model_not_allowed` | 当前 API Key 无法使用该模型 | 调用 `GET /v1/models` 确认模型权限。 | | 返回参数错误 | 模型不支持请求的比例或分辨率 | 改用模型支持的 `aspectRatio` 和 `imageSize`。 | | 响应中没有图片 | 模型未生成图片或响应模态配置不正确 | 确认模型支持图片输出，并传入 `responseModalities: ["IMAGE"]`。 | | JSON 响应过大 | 高分辨率图片以 Base64 内嵌返回 | 提高客户端响应体限制，避免在日志中打印完整正文。 | | 图片中文字不准确 | 生成模型对精确排版和文字还原能力有限 | 减少画面文字，重要文字通过后期排版添加。 |