图像生成 (OpenAI 风格)

本文档介绍如何通过 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 "https://models.phanedge.cloud/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 "https://models.phanedge.cloud/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 "https://models.phanedge.cloud/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 "https://models.phanedge.cloud/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"
  }'

请求参数

参数	类型	必填	说明
`model`	string	✅	模型名称
`prompt`	string	✅	图像描述文本
`n`	integer	❌	生成数量，默认 1（仅支持 1）
`size`	string	❌	分辨率，见下方说明
`response_format`	string	❌	`b64_json` 或 `url`，默认 `b64_json`
`aspect_ratio`	string	❌	宽高比，如 `1:1`、`16:9`、`9:16`

分辨率与计费档位

size 参数支持两种格式：

档位格式（推荐）："1K"、"2K"、"4K"
数字格式：如 "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"
    }
  ]
}

封控但已计费的错误响应

当 Gemini 图像模型未产出图片，但上游已经返回 prompt/input token usage 且平台按 token 完成结算时，接口会保持错误响应，同时在顶层返回 usage，方便你把失败响应和消费日志对账。

{
  "error": {
    "message": "no image generated (request id: 20260608235925678097275ZgRxuG4y)",
    "type": "one_hub_error",
    "code": "no_image_generated"
  },
  "usage": {
    "input_tokens": 353,
    "output_tokens": 0,
    "total_tokens": 353,
    "output_tokens_details": null,
    "input_tokens_details": {
      "text_tokens": 95,
      "image_tokens": 258
    }
  }
}

仅当本次失败已经产生可计费 prompt/input tokens 时才会返回 usage。本地参数校验失败、额度不足、网络失败或上游未返回 usage 的普通失败不会返回该字段。上游安全字段（如 finish_reason、prompt_blocked、safetyRatings）会被清理，不会直接透出给客户端。

Python SDK 示例

from openai import OpenAI

client = OpenAI(
    base_url="https://models.phanedge.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 "https://models.phanedge.cloud/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 "https://models.phanedge.cloud/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 "https://models.phanedge.cloud/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 地址

请求参数

参数	类型	必填	说明
`model`	string	✅	模型名称
`prompt`	string	✅	编辑指令
`image`	file	❌	基准图（主图），与 `image_urls[]` 二选一
`image[]`	file[]	❌	参考图，最多 14 张
`image_urls[]`	string[]	❌	图片 URL 列表，第一个作为基准图，其余作为参考图；与 `image`/`image[]` 可混用
`size`	string	❌	输出分辨率，默认自动从基准图推断（支持 `1K`、`2K`、`4K` 或 `widthxheight`）
`aspect_ratio`	string	❌	显式指定宽高比，如 `1:1`、`16:9`、`9:16`
`response_format`	string	❌	`b64_json` 或 `url`
`mask`	file	❌	蒙版图（局部编辑时使用）

自动分辨率推断

当未指定 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）	中
功能完整度	覆盖常用场景	完整

快速开始

文本与多模态

图像生成

视频生成

帮助

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

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

异步文生图示例

支持的模型

文生图 `/v1/images/generations`

基础请求

请求参数

分辨率与计费档位

宽高比设置

响应结构

封控但已计费的错误响应

Python SDK 示例

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

基础请求

多参考图请求

通过 URL 传入参考图

请求参数

自动分辨率推断

计费说明

错误处理

与原生 API 对比

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

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

​异步文生图示例

​支持的模型

​文生图 /v1/images/generations

​基础请求

​请求参数

​分辨率与计费档位

​宽高比设置

​响应结构

​封控但已计费的错误响应

​Python SDK 示例

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

​基础请求

​多参考图请求

​通过 URL 传入参考图

​请求参数

​自动分辨率推断

​计费说明

​错误处理

​与原生 API 对比

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

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

异步文生图示例

支持的模型

文生图 `/v1/images/generations`

基础请求

请求参数

分辨率与计费档位

宽高比设置

响应结构

封控但已计费的错误响应

Python SDK 示例

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

基础请求

多参考图请求

通过 URL 传入参考图

请求参数

自动分辨率推断

计费说明

错误处理

与原生 API 对比