Appearance
图像生成与编辑(Token 计费)
通过 OpenAI 兼容接口使用 gpt-image-2 token 计费通道进行图像生成与编辑
本文适用于 gpt-image-2 token 计费通道,以及需要更完整 OpenAI Images API 兼容能力的账号。
如果你的账号开通的是按张计费 SKU,请优先参考 图像生成与编辑(按张计费)。按张计费 SKU 只承诺稳定尺寸、quality=low/auto、PNG、URL 输出和 n=1。
INFO
本文不适用按张计费逆向渠道准入验收。按张渠道验收以按张计费文档中的稳定参数、edit 能力和异步任务标准为准。
快速开始
bash
curl -X POST "https://aiapi.fhddos.com/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:
python
from openai import OpenAI
client = OpenAI(base_url="https://aiapi.fhddos.com/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 | 否 | 终端用户标识 |
WARNING
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 |
具体可用尺寸仍以账号实际路由到的通道能力为准。
响应体
json
{
"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:
python
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 指定底图:
bash
curl -X POST "https://aiapi.fhddos.com/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" }
]
}'多参考图示例:
bash
curl -X POST "https://aiapi.fhddos.com/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 上传
bash
curl -X POST "https://aiapi.fhddos.com/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 | 否 | 终端用户标识 |
INFO
images[].image_url 和 images[].file_id 二选一。部分兼容渠道会由平台在内部改写为 multipart 请求以保证可执行,不影响对外接口形态。
异步图片任务
平台提供托管异步图片任务接口。异步接口不是 OpenAI 官方后台任务协议,而是平台先创建 image_ 任务,再由后台 worker 执行同步图像请求,最后通过轮询接口返回托管图片 URL。
文生图任务
bash
curl -X POST "https://aiapi.fhddos.com/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"
}'查询任务:
bash
curl -X GET "https://aiapi.fhddos.com/v1/images/generations/{id}" \
-H "Authorization: Bearer $TOKEN"改图任务
bash
curl -X POST "https://aiapi.fhddos.com/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 |
单张预估只用于成本预估,实际账单以消费日志和控制台「模型价格」页面为准。
TIP
按张计费和 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。账号实际可用参数仍以控制台开通能力和运行时错误返回为准。
OpenAPI
yaml
openapi: 3.0.0
info:
title: gpt-image-2 Token Billing API
description: gpt-image-2 图像生成与编辑 — token 计费 OpenAI 兼容接口
version: 1.0.0
servers:
- url: https://aiapi.fhddos.com
description: Fhddos 生产环境
security:
- BearerAuth: []
paths:
/v1/images/generations:
post:
tags:
- gpt-image-2
summary: 文生图
description: 使用 gpt-image-2 从文本生成图像
operationId: createGptImage2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GenerationRequest'
examples:
basic:
summary: 基础文生图
value:
model: gpt-image-2
prompt: A futuristic skyline at dusk
size: 1024x1024
quality: medium
with-url-output:
summary: 请求返回 URL
value:
model: gpt-image-2
prompt: A clean studio product photo of a matte white ceramic mug
size: 1024x1024
quality: low
response_format: url
responses:
'200':
description: 图像生成成功
content:
application/json:
schema:
$ref: '#/components/schemas/ImageResponse'
example:
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
components:
schemas:
GenerationRequest:
type: object
required:
- prompt
- model
description: gpt-image-2 文生图请求体(对齐 types.ImageGenerationRequestDoc)
properties:
prompt:
type: string
description: 图像描述文本
model:
type: string
enum:
- gpt-image-2
description: 模型名称
background:
type: string
enum:
- transparent
- opaque
- auto
description: 背景模式。transparent 输出带 alpha 通道的 PNG
moderation:
type: string
enum:
- low
- auto
description: 内容审核级别
'n':
type: integer
minimum: 1
default: 1
description: 生成数量。部分兼容渠道仅支持 n=1,详见文档「渠道差异」
output_compression:
type: integer
minimum: 0
maximum: 100
description: 压缩率,仅 jpeg/webp 生效
output_format:
type: string
enum:
- png
- jpeg
- webp
description: 输出格式。webp 为官方字段但当前不支持
partial_images:
type: integer
minimum: 0
description: 官方字段。gpt-image-2 不支持流式,此字段不会生效
quality:
type: string
enum:
- low
- medium
- high
- auto
default: low
description: 图像质量。平台默认 low(未传时自动填充)
response_format:
type: string
enum:
- url
- b64_json
default: b64_json
description: url 时平台转存对象存储后返回可访问 URL
size:
type: string
default: 1024x1024
example: 1024x1024
description: >-
图像尺寸,格式 widthxheight 或 auto。约束:16 的倍数、单边 ≤ 3840px、总像素
655360–8294400、长短边比 ≤ 3:1
stream:
type: boolean
default: false
description: '官方字段。gpt-image-2 标注 Streaming: Not supported,传入会返回普通 JSON'
user:
type: string
description: 终端用户标识
ImageResponse:
type: object
description: 对齐 types.ImageResponse
properties:
created:
type: integer
description: 创建时间戳
background:
type: string
description: 实际使用的背景模式
data:
type: array
items:
$ref: '#/components/schemas/ImageResponseData'
output_format:
type: string
description: 实际输出格式
quality:
type: string
description: 实际质量等级
size:
type: string
description: 实际输出尺寸
usage:
$ref: '#/components/schemas/Usage'
ImageResponseData:
type: object
description: 对齐 types.ImageResponseDataInner
properties:
url:
type: string
description: 图片 URL(response_format=url 时)
b64_json:
type: string
description: Base64 编码图片(response_format=b64_json 时)
revised_prompt:
type: string
description: 模型优化后的提示词
size:
type: string
description: 单张图片尺寸
error:
$ref: '#/components/schemas/ImageGenerationError'
description: 单张图片生成失败时的错误信息(组图场景)
Usage:
type: object
properties:
input_tokens:
type: integer
output_tokens:
type: integer
total_tokens:
type: integer
ImageGenerationError:
type: object
properties:
code:
type: string
message:
type: string
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'Authorization: Bearer <your-api-key>'