图像生成与编辑（Token 计费） - {{brandName}} 用户文档

本文适用于 gpt-image-2 token 计费通道，以及需要更完整 OpenAI Images API 兼容能力的账号。如果你的账号开通的是按张计费 SKU，请优先参考图像生成与编辑（按张计费）。按张计费 SKU 只承诺稳定尺寸、quality=low/auto、PNG、URL 输出和 n=1。

本文不适用按张计费逆向渠道准入验收。按张渠道验收以按张计费文档中的稳定参数、edit 能力和异步任务标准为准。

快速开始

curl -X POST "https://models.kapon.cloud/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A futuristic skyline at dusk",
    "size": "1024x1024",
    "quality": "medium",
    "response_format": "b64_json"
  }'

Python SDK:

from openai import OpenAI

client = OpenAI(base_url="https://models.kapon.cloud/v1", api_key="$TOKEN")

result = client.images.generate(
    model="gpt-image-2",
    prompt="A futuristic skyline at dusk",
    size="1024x1024",
    quality="medium",
    response_format="b64_json",
)
print(result.data[0].b64_json)

文生图 `/v1/images/generations`

参数表

参数	类型	必填	说明
`prompt`	string	是	图像描述文本
`model`	string	是	固定 `gpt-image-2`
`n`	integer	否	生成数量，默认 1；部分兼容渠道仅支持 `n=1`
`size`	string	否	`widthxheight` 或 `auto`，默认 `1024x1024`
`quality`	string	否	`low` / `medium` / `high` / `auto`；平台默认 `low`
`background`	string	否	`transparent` / `opaque` / `auto`
`output_format`	string	否	`png` / `jpeg`；`webp` 为官方字段但不保证所有渠道可用
`output_compression`	integer	否	0-100，仅 JPEG / WebP 生效
`response_format`	string	否	`url` / `b64_json`，默认 `b64_json`
`moderation`	string	否	`low` / `auto`
`user`	string	否	终端用户标识

stream 和 partial_images 是 OpenAI 官方定义的字段，但 gpt-image-2 官方标注不支持流式图片生成。传入时不会返回可用图片流事件。

分辨率规则

token 计费通道按 OpenAI 兼容能力处理尺寸。size 参数格式为 widthxheight 或 auto，常见约束如下：

约束	规则
最大边长	任一边不超过 3840 px
最小总像素	width x height 不低于 655,360
最大总像素	width x height 不超过 8,294,400
对齐要求	宽和高都必须是 16 的倍数
宽高比限制	长边 : 短边不超过 3:1

常用值：

`size`	用途
`auto`	模型根据 prompt 自动选择尺寸
`1024x1024`	通用方图
`1536x1024`	横版 3:2
`1024x1536`	竖版 2:3
`2048x2048`	2K 方图
`2048x1152`	2K 横版 16:9
`1152x2048`	2K 竖版 9:16

具体可用尺寸仍以账号实际路由到的通道能力为准。

响应体

{
  "created": 1762789802,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUg...",
      "revised_prompt": "A futuristic skyline at dusk with neon lights"
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 4096,
    "total_tokens": 4108
  }
}

字段	说明
`created`	创建时间戳
`data[].b64_json`	Base64 编码图片，`response_format=b64_json` 时返回
`data[].url`	图片 URL，`response_format=url` 时返回
`data[].revised_prompt`	模型优化后的提示词
`usage`	token 用量；token 计费通道会优先按平台记录或上游返回的 usage 结算

URL 输出

设置 response_format=url 可获取图片 URL：

result = client.images.generate(
    model="gpt-image-2",
    prompt="A clean studio product photo of a matte white ceramic mug",
    size="1024x1024",
    quality="low",
    response_format="url",
)
print(result.data[0].url)

平台对 URL 输出采用本地托底策略：

请求图片结果。
将图片转存到平台对象存储。
在 data[].url 返回可访问 URL。

行为是确定性的：

若平台已配置对象存储，返回 data[].url。
若未配置对象存储，返回 image_url_not_available。
不会静默降级为 b64_json。

改图 `/v1/images/edits`

JSON 请求体

通过 images[].image_url 或 images[].file_id 指定底图：

curl -X POST "https://models.kapon.cloud/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "换种风格",
    "size": "1024x1024",
    "quality": "medium",
    "images": [
      { "image_url": "https://example.com/base-image.png" }
    ]
  }'

多参考图示例：

curl -X POST "https://models.kapon.cloud/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "参考第 1 张的主体轮廓、第 2 张的配色和第 3 张的材质，生成一张干净的电商主图",
    "size": "1024x1024",
    "quality": "high",
    "images": [
      { "image_url": "https://example.com/reference-subject.png" },
      { "image_url": "https://example.com/reference-color.png" },
      { "image_url": "https://example.com/reference-texture.png" }
    ]
  }'

Multipart 上传

curl -X POST "https://models.kapon.cloud/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-2" \
  -F "image=@base.png" \
  -F "mask=@mask.png" \
  -F "prompt=在天空中加入热气球"

改图参数表

参数	类型	必填	说明
`prompt`	string	是	编辑指令
`model`	string	是	固定 `gpt-image-2`
`images`	array	否	输入图像列表，最多 14 张
`images[].image_url`	string	否	图像的公开可访问 URL
`images[].file_id`	string	否	通过 Files API 上传后获得的文件 ID
`mask`	object	否	蒙版，结构同图像引用
`size`	string	否	输出尺寸，默认 `1024x1024`
`quality`	string	否	`low` / `medium` / `high` / `auto`，默认 `low`
`background`	string	否	`transparent` / `opaque` / `auto`
`input_fidelity`	string	否	`high` / `low`
`output_format`	string	否	`png` / `jpeg`
`output_compression`	integer	否	0-100
`moderation`	string	否	`low` / `auto`
`response_format`	string	否	`url` / `b64_json`
`n`	integer	否	生成数量，默认 1
`user`	string	否	终端用户标识

images[].image_url 和 images[].file_id 二选一。部分兼容渠道会由平台在内部改写为 multipart 请求以保证可执行，不影响对外接口形态。

异步图片任务

平台提供托管异步图片任务接口。异步接口不是 OpenAI 官方后台任务协议，而是平台先创建 image_<ULID> 任务，再由后台 worker 执行同步图像请求，最后通过轮询接口返回托管图片 URL。

文生图任务

curl -X POST "https://models.kapon.cloud/v1/images/generations/async" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean studio product photo of a matte white ceramic mug",
    "size": "1024x1024",
    "quality": "low",
    "response_format": "url"
  }'

查询任务：

curl -X GET "https://models.kapon.cloud/v1/images/generations/{id}" \
  -H "Authorization: Bearer $TOKEN"

改图任务

curl -X POST "https://models.kapon.cloud/v1/images/edits/async" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-2" \
  -F "prompt=将这张图片转换为干净的电商主图" \
  -F "response_format=url" \
  -F "image=@/path/to/base.png"

状态	说明
`pending`	排队中
`in_progress`	后台执行中
`completed`	已完成，读取 `data[].url`
`failed`	失败，读取 `error.code` / `error.message`

异步任务要求平台已配置公开可访问的对象存储。未配置时，创建任务会返回 storage_not_configured。

计费

token 计费通道按平台记录或上游返回的 token 用量结算：

类型	价格口径
text input	按输入文本 token
cached text input	按缓存命中输入 token
image input	改图或多模态图片输入 token
image output	图片输出 token

单张预估只用于成本预估，实际账单以消费日志和控制台「模型价格」页面为准。

按张计费和 token 计费的折扣、单价、账单字段不同。对账时以消费日志中的实际金额为准，不要把展示用 token bucket 当成额外账单行。

错误码

错误码	说明
`image_url_not_available`	请求 URL 输出但平台未配置对象存储
`n_not_supported`	当前通道不支持 `n>1`，请拆分请求
`unsupported_image_input`	异步改图暂不支持该输入形式
`content_policy_violation`	内容审核未通过
`suspected_black_image_from_upstream`	返回疑似纯黑图，已拦截

OpenAPI 参考

本文档的交互式 API 参考覆盖 token 计费通道的完整请求体和响应体 schema。账号实际可用参数仍以控制台开通能力和运行时错误返回为准。

Authorizations

Authorization

string

header

required

Authorization: Bearer

Body

application/json

gpt-image-2 文生图请求体（对齐 types.ImageGenerationRequestDoc）

prompt

string

required

图像描述文本

model

enum<string>

required

模型名称

Available options:

gpt-image-2

background

enum<string>

背景模式。transparent 输出带 alpha 通道的 PNG

Available options:

transparent,

opaque,

auto

moderation

enum<string>

内容审核级别

Available options:

low,

auto

integer

default:1

生成数量。部分兼容渠道仅支持 n=1，详见文档「渠道差异」

Required range: x >= 1

output_compression

integer

压缩率，仅 jpeg/webp 生效

Required range: 0 <= x <= 100

output_format

enum<string>

输出格式。webp 为官方字段但当前不支持

Available options:

png,

jpeg,

webp

partial_images

integer

官方字段。gpt-image-2 不支持流式，此字段不会生效

Required range: x >= 0

quality

enum<string>

default:low

图像质量。平台默认 low（未传时自动填充）

Available options:

low,

medium,

high,

auto

response_format

enum<string>

default:b64_json

url 时平台转存对象存储后返回可访问 URL

Available options:

url,

b64_json

size

string

default:1024x1024

图像尺寸，格式 widthxheight 或 auto。约束：16 的倍数、单边 ≤ 3840px、总像素 655360–8294400、长短边比 ≤ 3:1

Example:

"1024x1024"

stream

boolean

default:false

官方字段。gpt-image-2 标注 Streaming: Not supported，传入会返回普通 JSON

user

string

终端用户标识

Response

200 - application/json

图像生成成功

对齐 types.ImageResponse

created

integer

创建时间戳

background

string

实际使用的背景模式

data

object[]

Show child attributes

output_format

string

实际输出格式

quality

string

实际质量等级

size

string

实际输出尺寸

usage

object

Show child attributes

​快速开始

​文生图 /v1/images/generations

​参数表

​分辨率规则

​响应体

​URL 输出

​改图 /v1/images/edits

​JSON 请求体

​Multipart 上传

​改图参数表

​异步图片任务

​文生图任务

​改图任务

​计费

​错误码

​OpenAPI 参考

Authorizations

Body

Response

快速开始

文生图 `/v1/images/generations`

参数表

分辨率规则

响应体

URL 输出

改图 `/v1/images/edits`

JSON 请求体

Multipart 上传

改图参数表

异步图片任务

文生图任务

改图任务

计费

错误码

OpenAPI 参考