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

​
异步模式（适用于 Gemini 图像模型 / Imagen 文生图）

针对 Gemini 图像模型与 Imagen 文生图，本网关提供 Sora 风格的异步任务接口：
  • 创建文生图任务：POST /v1/images/generations/async
  • 创建改图任务：POST /v1/images/edits/async
  • 查询任务状态：GET /v1/images/generations/{id} / GET /v1/images/edits/{id}
异步模式强制要求配置对象存储（S3/OSS），用于上传生成图片并返回 24 小时有效的临时 URL。 同时，异步模式下 response_format 固定为 url（即使传入 b64_json 也会忽略）。 创建任务的响应中 task_id 为兼容字段，等同于 id。 改图异步任务仅支持 Gemini 图像模型（gemini-*-image*），Imagen 暂不支持编辑。 更多细节请参考《图像生成（异步接口）》。

​
只返回图像 URL（response_format=url）

在同步接口（/v1/images/generations、/v1/images/edits）中，将 response_format 设置为 url 可让返回体只包含图片 URL（data[].url），同时会清空 data[].b64_json。
  • 若返回的数据本身已包含 URL：本网关会直接透传 URL，并清空 b64_json。
  • 若返回的是 b64_json：本网关会尝试将图片上传到已配置的 storage（如 S3/R2/OSS/图床等），再返回 URL；若未配置 storage，将返回错误（error.code=image_url_not_available）。
  • 异步接口（/async）同样是“只返回 URL”，并且强制要求对象存储（S3/OSS），返回的是 24 小时有效的临时签名 URL。
同步文生图（URL-only）示例： 
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",
    "response_format": "url"
  }'

​
异步文生图示例

# 1) 创建任务
curl -X POST "$BASE_URL/v1/images/generations/async" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A futuristic cityscape at sunset with flying cars",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

# 2) 轮询查询（将返回 data[0].url）
curl -X GET "$BASE_URL/v1/images/generations/{id}" \
  -H "Authorization: Bearer $TOKEN"

​
支持的模型

模型说明最大分辨率特点
gemini-3-pro-image-preview高质量图像生成4K (4096×4096)支持复杂提示词理解、参考图编辑
gemini-2.5-flash-image / gemini-2.5-flash-image-preview快速图像生成1K (1024×1024)低延迟，适合原型验证
Imagen 系列（imagen-*）仅支持文生图（/v1/images/generations），不支持改图。

​
文生图 /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），并映射到对应的分辨率配置：
档位含义建议用途
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": "优化后的提示词（如有）"
    }
  ]
}
当 response_format=url 时，响应将返回 data[].url，并且 b64_json 会为空： 
{
  "created": 1700000000,
  "data": [
    {
      "url": "https://example.com/xxx.png"
    }
  ]
}

​
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"

​
通过 URL 传入参考图

支持通过 image_urls[] 参数直接传入图片 URL，无需上传文件： 
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_urls[]=https://example.com/base.png" \
  -F "image_urls[]=https://example.com/style-ref.png"
  • image_urls[] 中的第一个 URL 作为基准图，其余作为参考图
  • 可与 image/image[] 混用，总计最多 14 张
  • 仅支持公网可访问的 HTTP/HTTPS 图片 URL
  • 不支持 localhost 和内网 IP 地址

​
请求参数

参数类型必填说明
modelstring✅模型名称
promptstring✅编辑指令
imagefile❌基准图（主图），与 image_urls[] 二选一
image[]file[]❌参考图，最多 14 张
image_urls[]string[]❌图片 URL 列表，第一个作为基准图，其余作为参考图；与 image/image[] 可混用
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（或基准图尺寸推断的档位）进行分辨率配置。

​
计费说明

采用混合计费模式：
计费项说明
文本输入按提示词的 tokens 数量计费
图像输出1K/2K 档：1120 tokens/张；4K 档：2000 tokens/张
示例计算（Gemini 3 Pro Image 1K）： 
输入：50 tokens × 输入价格
输出：1 张 × 1120 tokens × 输出价格

​
错误处理

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

​
与原生 API 对比

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