ZeroFA API

图像生成

根据文本提示词生成图片。接口兼容 OpenAI，ZeroFA 根据 model 路由到 gpt-image、即梦、通义万相等图像上游。

POSThttps://zerofa.ai/v1/images/generations

请求参数

Header 参数
Authorizationstring必填
API Key，格式为 Bearer <key>。
示例：Bearer sk-zerofa-xxx
Content-Typestring必填
示例：application/json
Body 参数application/json
modelstring必填
文生图模型，可在下方查看可用模型。
示例：gpt-image-2
promptstring必填
画面描述；描述越具体，输出越可控。
示例：一只戴宇航头盔的柴犬，扁平插画
ninteger可选
生成张数，默认为 1。
示例：1
sizestring可选
输出尺寸，格式为宽x高。gpt-image 系列必须使用下方推荐尺寸；非法尺寸会返回 400 和最接近的合法值，网关不会自动调整。其他模型使用其自身支持的尺寸。
示例：1024x1024
qualitystring可选
画质档由模型决定。gpt-image 支持 low、medium、high、auto；dall-e-3 支持 standard、hd；不受支持的值会被忽略并使用上游默认设置。
示例：high
response_formatstring可选
url（默认）返回图片链接；b64_json 返回 base64。
示例：url
图像模型有两种计费方式：多数按图片张数和分辨率计费；部分模型（如 gpt-image-2）按 input、output 和 cached token 计费。具体方式以模型卡片和定价页为准。
推荐尺寸（gpt-image 系列）

宽高必须为 16 的倍数，长边不超过 3840，长短边比不超过 3:1，总像素为 655,360–8,294,400。竖版可交换宽高。

比例1K2K4K
1:11024x10242048x20482880x2880
4:31360x10242048x15363312x2480
3:21536x10242048x13603504x2336
16:91824x10242048x11523840x2160
21:92384x10242048x8803840x1648

响应

data 数组中的每项代表一张图片，包含 url 或 b64_json，取决于 response_format。url 为临时链接，需要长期保存时请及时下载。

图像编辑（图生图）

POST/v1/images/edits

通过 multipart/form-data 上传参考图并提供 prompt。支持 image、image[]、可选 mask、model、prompt、n、size 和 quality。输出尺寸由上游决定，可能与请求 size 不完全一致。

图像编辑 · curl
curl https://zerofa.ai/v1/images/edits \
  -H "Authorization: Bearer sk-zerofa-xxx" \
  -F "model=doubao-seedream-4-5-251128" \
  -F "prompt=把背景换成夜晚的星空" \
  -F "size=1024x1024" \
  -F "image=@source.png;type=image/png"

异步生成

除同步生成外，也可以提交异步图片任务并轮询结果。

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": "gpt-image-2",
    "prompt": "一只戴宇航头盔的柴犬，扁平插画",
    "size": "3840x2160"
  }'
# → {"id":"<task-id>","model":"gpt-image-2","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": "gpt-image-2",
    "prompt": "一只戴宇航头盔的柴犬，扁平插画",
    "n": 1,
    "size": "1024x1024"
  }'
响应 · 200
{
  "created": 1715961234,
  "data": [
    { "url": "https://.../generated.png" }
  ]
}