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

本文适用于已开通 gpt-image-2 按张计费 SKU 的文生图、改图和异步图片任务请求。接口路径、认证方式和 OpenAI Images API 保持兼容，但按张计费 SKU 只承诺本文列出的稳定参数。如果你的账号使用 token 计费通道，或需要 medium / high、b64_json、JPEG/WebP、1024x1024 等官方兼容能力，请参考图像生成与编辑（Token 计费）。

同一个请求模型仍然是 gpt-image-2。实际按张还是按 token 结算，取决于账号在控制台开通的模型价格和计费 SKU。

计费模式

模式	适用场景	计费依据
按张计费	稳定低成本文生图、改图和异步图片任务	成功返回并可解码的图片张数 x 对应分辨率 SKU 单价
Token 计费	官方完整兼容能力、复杂参数、改图	平台记录或上游返回的 token 用量

按张计费下，usage.* 可能被记录用于排查，但不作为客户账单的稳定计费依据。

快速开始

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 clean studio product photo of a matte white ceramic mug",
    "size": "1024x1536",
    "response_format": "url",
    "quality": "low",
    "output_format": "png",
    "n": 1
  }'

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 clean studio product photo of a matte white ceramic mug",
    size="1024x1536",
    response_format="url",
    quality="low",
    output_format="png",
    n=1,
)
print(result.data[0].url)

文生图请求参数

POST /v1/images/generations 和 POST /v1/images/generations/async 只承诺以下参数和值：

参数	类型	必填	稳定值	说明
`model`	string	是	`gpt-image-2`	固定模型名
`prompt`	string	是	非空文本	图片描述
`size`	string	是	见下方分辨率 SKU	决定 1K / 2K / 4K 计费档
`response_format`	string	否	`url`	建议显式传入；按张计费稳定响应只承诺 URL
`quality`	string	否	`low` / `auto`	省略时按 `low` 处理；`auto` 按稳定低成本档处理
`output_format`	string	否	`png`	建议显式传入；按张计费稳定输出只承诺 PNG
`n`	integer	否	`1`	仅支持单张生成

按张计费 SKU 不承诺官方 Images API 的完整参数全集。未列出的参数或未列出的取值不属于按张计费渠道验收标准；接入按张计费基础池的新渠道必须在网关或渠道适配层返回稳定参数错误，不能依赖上游静默接受。

改图请求参数

POST /v1/images/edits 和 POST /v1/images/edits/async 使用 multipart/form-data。按张计费 SKU 只承诺以下参数和值：

参数	类型	必填	稳定值	说明
`model`	string	是	`gpt-image-2`	固定模型名
`image`	file 或 file[]	是	1 至 10 张 PNG 图片	基础 edit 使用 1 张图；多参考图最多 10 张
`mask`	file	否	PNG mask	支持 1 张输入图 + 1 张 mask 的 mask edit
`prompt`	string	是	非空文本	编辑描述
`size`	string	是	见下方分辨率 SKU	决定 1K / 2K / 4K 计费档
`response_format`	string	否	`url`	建议显式传入；按张计费稳定响应只承诺 URL
`quality`	string	否	`low` / `auto`	省略时按 `low` 处理
`output_format`	string	否	`png`	建议显式传入；按张计费稳定输出只承诺 PNG
`n`	integer	否	`1`	仅支持单张结果

能力范围：

能力	标准
基础 edit	1 张参考图 + `prompt`
mask edit	1 张参考图 + 1 张 PNG mask + `prompt`
多参考图 edit	最多 10 张参考图 + `prompt`

curl -X POST "https://models.kapon.cloud/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-2" \
  -F "image=@base.png" \
  -F "prompt=将图片转换为干净的电商主图" \
  -F "size=1024x1536" \
  -F "response_format=url" \
  -F "quality=low" \
  -F "output_format=png" \
  -F "n=1"

分辨率 SKU

文生图、基础改图、mask 改图和多参考图改图使用同一组按张计费稳定尺寸。

SKU	`size`	实际尺寸	比例
1K	`1024x1536`	`1024x1536`	2:3
1K	`1536x1024`	`1536x1024`	3:2
2K	`2048x2048`	`2048x2048`	1:1
2K	`2048x1152`	`2048x1152`	16:9
2K	`1152x2048`	`1152x2048`	9:16
2K	`2048x1536`	`2048x1536`	4:3
2K	`1536x2048`	`1536x2048`	3:4
2K	`2048x1024`	`2048x1024`	2:1
2K	`1024x2048`	`1024x2048`	1:2
2K	`2048x1280`	`2048x1280`	8:5
2K	`1280x2048`	`1280x2048`	5:8
4K	`1280x3840`	`1280x3840`	1:3
4K	`3840x1280`	`3840x1280`	3:1
4K	`3840x2160`	`3840x2160`	16:9
4K	`2160x3840`	`2160x3840`	9:16

SKU 说明：

1K、2K、4K 是平台的计费 SKU 分类，不等同于严格的总像素、短边分辨率或标准 UHD 定义。
1280x3840 因长边达到 3840 像素，归入 4K SKU。
size=auto 不是按张计费稳定能力。
1024x1024 不在按张计费稳定尺寸列表内；如需方图，请使用 token 计费通道或联系平台确认账号能力。

响应体

成功响应至少包含 data[].url：

{
  "created": 1762789802,
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}

字段	说明
`created`	创建时间戳
`data[].url`	图片 URL，可能是远程 URL 或 data URL
`usage`	可选诊断字段，不作为按张计费账单依据

按张计费稳定响应要求：

data[].url 必须存在。
图片必须可以完整下载或解码。
实际 MIME 为 image/png。
固定尺寸必须与请求的 size 精确一致。
默认或显式 n=1 时只返回一张图片。

异步图片任务

按张计费 SKU 也可使用平台托管的异步任务接口。异步接口先创建 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": "1024x1536",
    "response_format": "url",
    "quality": "low",
    "output_format": "png",
    "n": 1
  }'

文生图轮询结果：

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 "image=@base.png" \
  -F "prompt=将图片转换为干净的电商主图" \
  -F "size=1024x1536" \
  -F "response_format=url" \
  -F "quality=low" \
  -F "output_format=png" \
  -F "n=1"

改图轮询结果：

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

接口	方法	路径	成功要求
文生图异步提交	POST	`/v1/images/generations/async`	返回 `task_id`
文生图异步查询	GET	`/v1/images/generations/{id}`	最终 `status=completed`，返回 1 张 URL 图片
改图异步提交	POST	`/v1/images/edits/async`	返回 `task_id`
改图异步查询	GET	`/v1/images/edits/{id}`	最终 `status=completed`，返回 1 张 URL 图片

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

异步任务完成后按成功图片张数结算。完成态响应中的 usage 如存在，仅用于排查和对账辅助。

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

不支持参数

以下参数或取值不属于按张计费稳定承诺：

参数或值	说明
`size=auto`	不是按张计费稳定能力
非分辨率 SKU 表内的 `size`	不属于当前统一尺寸标准
edit 请求中非分辨率 SKU 表内的 `size`	不属于当前统一 edit 尺寸标准
`quality=medium` / `quality=high`	不属于按张计费稳定档位，可能脱离按张 SKU 口径
`output_format=jpeg` / `output_format=webp`	当前只承诺 PNG，其他格式可能脱离按张稳定输出
`output_compression`	依赖 JPEG / WebP 输出，当前不开放
`n>1`	请拆成多次 `n=1` 请求
`background`	不作为按张计费稳定参数
`moderation`	不作为按张计费稳定参数
`user`	不作为按张计费稳定参数
`input_fidelity`	不作为按张计费稳定参数
`stream=true`	不返回可用图片流事件
`partial_images`	不返回可解码的局部图片事件
`response_format=b64_json`	按张计费稳定响应只承诺 URL

常见错误

按张计费渠道验收中，标准外参数应按 HTTP 400 参数错误处理。实际 error.code 可能取决于平台校验或渠道适配，常见错误如下：

错误码	说明
`invalid_request_error`	参数不属于按张计费稳定能力，例如尺寸、质量档、输出格式不支持
`n_not_supported`	`n>1`，需改为 `n=1` 或拆分请求
`image_url_not_available`	请求 URL 输出但平台未配置对象存储
`content_policy_violation`	内容审核未通过
`suspected_black_image_from_upstream`	返回疑似纯黑图，已拦截

OpenAPI 参考

本文顶部的交互式 API 参考展示文生图入口；同一个按张计费 OpenAPI schema 也包含改图和异步任务接口。需要完整 OpenAI 兼容 schema 时，请查看 Token 计费文档。

Authorizations

Authorization

string

header

required

Authorization: Bearer

Body

application/json

gpt-image-2 按张计费文生图请求体

model

enum<string>

required

固定模型名

Available options:

gpt-image-2

prompt

string

required

图片描述文本

Minimum string length: 1

size

enum<string>

required

按张计费稳定分辨率 SKU

Available options:

1024x1536,

1536x1024,

2048x2048,

2048x1152,

1152x2048,

2048x1536,

1536x2048,

2048x1024,

1024x2048,

2048x1280,

1280x2048,

1280x3840,

3840x1280,

3840x2160,

2160x3840

response_format

enum<string>

建议显式传入；按张计费稳定响应只承诺 URL

Available options:

url

quality

enum<string>

default:low

按张计费稳定质量档

Available options:

low,

auto

output_format

enum<string>

建议显式传入；按张计费稳定输出只承诺 PNG

Available options:

png

integer

default:1

按张计费稳定模式仅支持单张生成

Required range: 1 <= x <= 1

Response

图像生成成功

按张计费稳定响应

data

object[]

required

Required array length: 1 element

Show child attributes

created

integer

创建时间戳

usage

object

可选诊断字段，不作为按张计费账单依据

Show child attributes

​计费模式

​快速开始

​文生图请求参数

​改图请求参数

​分辨率 SKU

​响应体

​异步图片任务

​不支持参数

​常见错误

​OpenAPI 参考

Authorizations

Body

Response

计费模式

快速开始

文生图请求参数

改图请求参数

分辨率 SKU

响应体

异步图片任务

不支持参数

常见错误

OpenAPI 参考