请求参数
Header 参数
Authorizationstring必填API Key，格式为 Bearer <key>。
示例：
Bearer sk-zerofa-xxxContent-Typestring必填示例：
application/jsonBody 参数application/json
modelstring必填文生图模型，可在下方查看可用模型。
示例：
your-image-model-idpromptstring必填画面描述；描述越具体，输出越可控。
示例：
一只戴宇航头盔的柴犬，扁平插画imagestring | string[]可选参考图，可传单个 URL/data URI，也可传 URL/data URI 数组。
示例：
https://.../reference.pngimagesstring[] | object[]可选多参考图推荐字段。可传 URL/data URI 字符串数组，也兼容 {image_url} 对象数组。
示例：
["https://.../a.png","https://.../b.png"]ninteger可选生成张数，默认为 1。
示例：
1sizestring可选输出尺寸，格式为宽x高。gpt-image 系列必须使用下方推荐尺寸；非法尺寸会返回 400 和最接近的合法值，网关不会自动调整。其他模型使用其自身支持的尺寸。
示例：
1024x1024qualitystring可选画质档由模型决定。gpt-image 支持 low、medium、high、auto；dall-e-3 支持 standard、hd；不受支持的值会被忽略并使用上游默认设置。
示例：
highresponse_formatstring可选url（默认）返回图片链接；b64_json 返回 base64。
示例：
urloutput_formatstring可选输出编码格式：png、jpeg 或 webp。仅支持该能力的模型会改变实际编码。
示例：
webpbackgroundstring可选背景模式：auto、opaque 或 transparent；由模型能力决定。
示例：
transparentstreamboolean可选启用 OpenAI Images SSE 响应。跨厂商同步上游返回终态 completed 事件。
示例：
truepartial_imagesinteger可选请求 0–3 张中间预览图，仅 stream=true 有效；上游快速完成或不支持分片时可能返回 0 张。
示例：
2图像模型有两种计费方式：多数按图片张数和分辨率计费；部分模型按 input、output 和 cached token 计费。具体方式以本站模型卡片和定价页为准。
推荐尺寸（gpt-image 系列）
宽高必须为 16 的倍数，长边不超过 3840，长短边比不超过 3:1，总像素为 655,360–8,294,400。竖版可交换宽高。
| 比例 | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 4:3 | 1360x1024 | 2048x1536 | 3312x2480 |
| 3:2 | 1536x1024 | 2048x1360 | 3504x2336 |
| 16:9 | 1824x1024 | 2048x1152 | 3840x2160 |
| 21:9 | 2384x1024 | 2048x880 | 3840x1648 |
图生图与多参考图（本站 / new-api 通用）
在 /v1/images/generations 的文生图请求上增加 image 或 images 即可切换到参考生图。多图统一推荐使用 images；该 JSON 结构可直接调用本站，也可经 OpenAI 兼容的 new-api 渠道转发。
多参考图生成
curl https://zerofa.ai/v1/images/generations \
-H "Authorization: Bearer sk-zerofa-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "your-image-model-id",
"prompt": "融合人物、服装和场景参考，生成一张电影海报",
"images": [
"https://example.com/person.png",
"https://example.com/outfit.png",
"data:image/png;base64,..."
],
"size": "2048x2048",
"response_format": "url"
}'参考图支持公网 URL 和 data URI。数组顺序会保留，建议在提示词中明确“图片1/图片2”的用途。最大参考图数量、尺寸和输出能力以具体模型为准；厂商专属高级字段请使用原生透传入口并查看官方文档。
响应
data 数组中的每项代表一张图片，包含 url 或 b64_json，取决于 response_format。url 为临时链接，需要长期保存时请及时下载。
图像编辑（图生图）
POST
/v1/images/edits通过 multipart/form-data 上传参考图并提供 prompt。除 OpenAI 标准 mask 外，还支持 bbox_list=[[[x1,y1,x2,y2]], ...] 矩形区域扩展：每个外层元素对应一张输入图，坐标为原图绝对像素，每张图最多两个框，mask 与 bbox_list 不能同时使用。OpenAI 路由会将首图坐标转换为 Mask，Wan 2.7 原生使用 bbox_list；不支持区域编辑的模型会明确报错。输出尺寸由上游决定，可能与请求 size 不完全一致。
图像编辑 · curl
curl https://zerofa.ai/v1/images/edits \
-H "Authorization: Bearer sk-zerofa-xxx" \
-F "model=your-image-model-id" \
-F "prompt=把背景换成夜晚的星空" \
-F "size=1024x1024" \
-F "image=@source.png;type=image/png"
# 精确矩形区域编辑：bbox_list 按 image/image[] 的顺序对齐
curl https://zerofa.ai/v1/images/edits \
-H "Authorization: Bearer sk-zerofa-xxx" \
-F "model=wan2.7-image-pro" \
-F "prompt=替换框选区域内的物体" \
-F "image=@source.png;type=image/png" \
-F 'bbox_list=[[[120,80,640,720]]]'JSON 多参考图 · OpenAI / new-api 兼容
curl https://zerofa.ai/v1/images/edits \
-H "Authorization: Bearer sk-zerofa-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "your-image-model-id",
"prompt": "融合两张参考图的构图和材质",
"images": [
{"image_url": "https://example.com/reference-1.png"},
{"image_url": "data:image/png;base64,..."}
],
"input_fidelity": "high",
"output_format": "webp",
"response_format": "url"
}'JSON edits 支持 images[].image_url（公网 URL 或 data URI）；平台不提供 Files API，因此不支持 file_id。需要上传本地文件时请使用 multipart/form-data。
流式图片响应
stream=true 返回 OpenAI Images 标准 SSE 事件。统一路由会始终返回 image_generation.completed 或 image_edit.completed；partial_image 事件取决于供给链路能力，不保证出现。
SSE
curl -N https://zerofa.ai/v1/images/generations \
-H "Authorization: Bearer sk-zerofa-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "your-image-model-id",
"prompt": "一只戴宇航头盔的柴犬，扁平插画",
"stream": true,
"partial_images": 2
}'
# 终态事件：event: image_generation.completed
# data: {"type":"image_generation.completed","b64_json":"..."}OpenAI 编辑接口工具模型
同一个 POST /v1/images/edits 也可调用抠图和图片超分。使用 background-removal-1 输出透明 PNG；使用 image-upscale、image-upscale-2x 或 image-upscale-4x 执行超分。
图片超分目标参数优先级为 size > long_side/short_side > scale > 默认 2 倍。size、scale、long_side 和 short_side 是 ZeroFA 兼容扩展。
抠图与图片超分 · OpenAI Images Edits
# Background removal
curl https://zerofa.ai/v1/images/edits \
-H "Authorization: Bearer sk-zerofa-xxx" \
-F "model=background-removal-1" \
-F "prompt=Remove the background and preserve the subject" \
-F "image=@source.png;type=image/png"
# Image upscale: size > long_side/short_side > scale > default 2x
curl https://zerofa.ai/v1/images/edits \
-H "Authorization: Bearer sk-zerofa-xxx" \
-F "model=image-upscale" \
-F "prompt=Upscale while preserving all details" \
-F "image=@source.png;type=image/png" \
-F "size=2048x1536" \
-F "response_format=url"异步生成
除同步生成外，也可以提交异步图片任务并轮询结果。
POST
/v1/images/generations/tasks提交任务时不扣费。Body 与 /v1/images/generations 一致，并立即返回 id 和 submitted 状态。
① 提交
curl https://zerofa.ai/v1/images/generations/tasks \
-H "Authorization: Bearer sk-zerofa-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "your-image-model-id",
"prompt": "一只戴宇航头盔的柴犬，扁平插画",
"size": "3840x2160"
}'
# → {"id":"<task-id>","model":"your-image-model-id","status":"submitted"}GET
/v1/images/generations/tasks/{id}每隔几秒轮询任务，直到 succeeded 或 failed。成功时返回 OpenAI 风格 data；首次成功结果按实际张数扣费，重复轮询不会重复扣款。失败或超时不扣费，临时图片 URL 请及时下载。
② 轮询
curl https://zerofa.ai/v1/images/generations/tasks/<task-id> \
-H "Authorization: Bearer sk-zerofa-xxx"
# running → {"id":"...","status":"running"}
# succeeded → {"id":"...","status":"succeeded",
# "data":[{"url":"https://.../4k.png"}]}可用模型
文生图模型见 模型广场 并筛选图像类型。价格根据 model、size 和计费方式变化。
请求与响应体
用下面的示例确认请求格式与返回结构。需要在线发起请求时，点击页面顶部“调试”拉起在线运行面板。
curl https://zerofa.ai/v1/images/generations \
-H "Authorization: Bearer sk-zerofa-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "your-image-model-id",
"prompt": "一只戴宇航头盔的柴犬，扁平插画",
"n": 1,
"size": "1024x1024",
"response_format": "url"
}'响应 · 200
{
"created": 1715961234,
"data": [
{ "url": "https://.../generated.png" }
]
}