Skip to main content
本文档介绍如何通过 OpenAI 风格的 /v1/images/generations 和 /v1/images/edits 接口调用 Gemini 图像生成模型。

​
支持的模型

模型说明最大分辨率特点
gemini-3-pro-image-preview高质量图像生成4K (4096×4096)支持复杂提示词理解、参考图编辑
gemini-2.5-flash-image快速图像生成1K (1024×1024)低延迟，适合原型验证

​
文生图 /v1/images/generations

​
基础请求

curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "一只熊猫在图书馆看书，电影级光影",
    "n": 1,
    "size": "1K",
    "aspect_ratio": "1:1",
    "response_format": "b64_json"
  }'

​
请求参数

参数类型必填说明
modelstring✅模型名称
promptstring✅图像描述文本
ninteger❌生成数量，默认 1（仅支持 1）
sizestring❌分辨率，见下方说明
response_formatstring❌b64_json 或 url，默认 b64_json
aspect_ratiostring❌宽高比，如 1:1、16:9、9:16

​
分辨率与计费档位

size 参数支持两种格式：
  1. 档位格式（推荐）："1K"、"2K"、"4K"
  2. 数字格式：如 "1024x1024"，用于兼容历史写法（仅作为推断档位和宽高比的“提示”，最终像素由上游按栅格表决定）
系统会根据 size 以及 aspect_ratio 自动计算标准分辨率档位（1K / 2K / 4K），并映射到上游 Gemini 的 imageConfig.imageSize：
档位含义建议用途
1K约 1K 级别像素（最长边约 1K）预览、小图、移动端壁纸
2K约 2K 级别像素高清插画、桌面壁纸
4K约 4K 级别像素超高清、精修图、打印或大屏展示
各宽高比在不同档位下的具体像素栅格（例如 1K/2K/4K 下 16:9、9:16、2:3 等对应的精确分辨率），请参考《Gemini 图像生成》文档中的 “分辨率与宽高比” 小节。
gemini-2.5-flash-image 最高仅支持 1K 分辨率。

​
宽高比设置

两种方式控制图像比例： 
// 方式 1：只通过 size（数字）推断
{"size": "1024x1024"}  // 自动推断为 1K + 1:1

// 方式 2：推荐写法——档位 + 显式指定 aspect_ratio（优先级更高）
{"size": "2K", "aspect_ratio": "16:9"}
当前支持的宽高比包括： 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9

​
响应结构

{
  "created": 1700000000,
  "data": [
    {
      "b64_json": "<BASE64_IMAGE_DATA>",
      "revised_prompt": "优化后的提示词（如有）"
    }
  ]
}

​
Python SDK 示例

from openai import OpenAI

client = OpenAI(
    base_url="https://models.kapon.cloud/v1",
    api_key="oh-xxxxxxxxxxxxxxxx",
)

resp = client.images.generate(
    model="gemini-3-pro-image-preview",
    prompt="赛博朋克风格的未来城市，霓虹灯倒映在雨水中",
    size="2048x2048",
    response_format="b64_json",
)

# 获取 base64 图片数据
image_b64 = resp.data[0].b64_json

​
参考图编辑 /v1/images/edits

通过上传参考图实现图像编辑、风格迁移等功能。

​
基础请求

curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gemini-3-pro-image-preview" \
  -F "prompt=将这张图片转换为油画风格" \
  -F "response_format=b64_json" \
  -F "image=@/path/to/image.png"

​
多参考图请求

curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gemini-3-pro-image-preview" \
  -F "prompt=保持第一张图的构图，参考第二张的色调" \
  -F "response_format=b64_json" \
  -F "size=2048x2048" \
  -F "image=@/path/base.png" \
  -F "image[]=@/path/ref1.png" \
  -F "image[]=@/path/ref2.png"

​
请求参数

参数类型必填说明
modelstring✅模型名称
promptstring✅编辑指令
imagefile✅基准图（主图）
image[]file[]❌参考图，最多 14 张
sizestring❌输出分辨率，默认自动从基准图推断（支持 1K、2K、4K 或 widthxheight）
aspect_ratiostring❌显式指定宽高比，如 1:1、16:9、9:16
response_formatstring❌b64_json 或 url
maskfile❌蒙版图（局部编辑时使用）

​
自动分辨率推断

当未指定 size 时，系统会自动从基准图推断输出分辨率：
  • 读取基准图（image 字段）的实际尺寸
  • 按模型最大能力限制输出（如 gemini-2.5-flash-image 最大 1024）
  • 保持原图宽高比
  • 自动推断功能仅对 gemini-3-pro-image-preview 生效；
  • 当显式传入 aspect_ratio 时，会优先使用该宽高比，并结合 size（或基准图尺寸推断的档位）映射到上游的 imageConfig.aspectRatio 与 imageConfig.imageSize。

​
计费说明

采用混合计费模式：
计费项说明
文本输入按提示词的 tokens 数量计费
图像输出每张图片 1290 image tokens
示例计算（Gemini 3 Pro Image 1K）： 
输入：50 tokens × 输入价格
输出：1 张 × 1290 tokens × 输出价格

​
错误处理

错误码说明解决方案
400参数错误检查 prompt、size 格式
413图片过大压缩参考图至 10MB 以内
429超出限额检查配额或等待重试

​
与原生 API 对比

如需使用 Gemini 原生协议（generateContent），请参阅 Gemini 原生图像 API。
特性OpenAI 风格原生 API
学习成本低（兼容 OpenAI SDK）中
功能完整度覆盖常用场景完整