认证
所有请求都要带 API 密钥：Authorization: Bearer sk-imgweb-...
密钥在 账户页 的「API 密钥」里创建，形如 sk-imgweb- 加 32 位随机串。完整密钥只在创建时显示一次， 服务端只存哈希，丢了只能重建。
注意：密钥等同于账号权限，不要写进前端代码或提交到仓库。每个账号最多 10 个，可随时撤销。
快速开始
默认同步模式：请求会阻塞到出图完成（最长 180 秒），直接把图片放进 data 里返回。
curl
curl https://your-domain.com/api/v1/images/generations \
-H "Authorization: Bearer sk-imgweb-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst",
"prompt": "一只戴宇航头盔的橘猫，电影感布光",
"n": 1,
"size": "1024x1024",
"quality": "high"
}'200 OK
{
"created": 1778500000,
"task_id": "cmw9xz2cl0006qkykaqc7l7i7",
"data": [
{ "b64_json": "iVBORw0KGgoAAAANSUhEUg...", "revised_prompt": "..." }
]
}模型列表
GET/api/v1/models列出可用模型与尺寸
shell
curl https://your-domain.com/api/v1/models \
-H "Authorization: Bearer sk-imgweb-xxxxxxxx"返回每个模型的 id、支持的尺寸、质量选项、单次最大张数、单价积分。 前端和 API 用的是同一份数据，后台改了立刻生效。
生成图片
POST/api/v1/images/generations文生图
| 参数 | 类型 | 说明 |
|---|---|---|
model 必填 | string | gpt-image-2.5-flare / gpt-image-2.5-sunburst / gpt-image-2.6-flare / gpt-image-2.6-sunburst |
prompt 必填 | string | 提示词，支持中文，长度上限见系统设置 |
n | number | 1–4，默认 1 |
size | string | 1024x1024 / 1024x1536 / 1536x1024 / 1152x1536 / 1536x1152 / 864x1536 / 1536x864 |
quality | string | high（默认）/ medium / low / auto |
response_format | string | b64_json（默认）或 url（1 小时有效的签名链接） |
background | boolean | true 则立即返回任务 id，自己去轮询 |
timeout | number | 同步模式最长等待秒数，5–300，默认 180 |
异步模式
长任务建议用 background: true，立刻拿到任务 id 再轮询， 避免连接被网关掐断。
shell
curl https://your-domain.com/api/v1/images/generations \
-H "Authorization: Bearer sk-imgweb-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "model":"gpt-image-2.6-flare", "prompt":"...", "background": true }'
# → 202 { "id": "cmw...", "status": "queued" }要 URL 而不是 base64
传 response_format: "url"， 返回一个带签名的媒体地址，1 小时内可直接下载，不需要登录态。
200 OK
{
"created": 1778500000,
"task_id": "cmw...",
"data": [
{
"url": "https://your-domain.com/media/outputs/o8/xxx.webp?exp=1778503600&sig=...",
"revised_prompt": "..."
}
]
}图生图
在 image 里传 base64 或 data URL，最多 4 张（受模型max_ref_images 限制）。传了参考图就自动走图生图。
shell
curl https://your-domain.com/api/v1/images/generations \
-H "Authorization: Bearer sk-imgweb-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst",
"prompt": "把背景换成雨夜霓虹街道",
"image": ["data:image/png;base64,iVBORw0KGgo..."]
}'参考图会落到和你网页上传同一套存储里，按 sha256 去重， 重复的图不会重复占磁盘。
查询任务
GET/api/v1/tasks/{id}状态、进度、产出
shell
curl https://your-domain.com/api/v1/tasks/cmw9xz2cl0006qkykaqc7l7i7 \
-H "Authorization: Bearer sk-imgweb-xxxxxxxx"status 取值：queued / running / succeeded / failed / canceled。 失败时 error 里带 code 和 message，积分已自动退回。
账户信息
GET/api/v1/me余额 / 今日用量
返回 balance_credits、today_tasks、active_tasks。轮询这个接口做余额预警成本很低。
错误码
所有失败都返回 OpenAI 风格的错误体：
4xx / 5xx
{
"error": {
"message": "积分不足，还需 6 积分",
"type": "insufficient_credits",
"code": "INSUFFICIENT_CREDITS"
}
}| HTTP | code | 处理 |
|---|---|---|
| 400 | VALIDATION_ERROR | 参数不合法，看 message |
| 401 | UNAUTHENTICATED | 密钥缺失 / 无效 / 已撤销 |
| 402 | INSUFFICIENT_CREDITS | 积分不足，去充值 |
| 404 | NOT_FOUND | 模型或任务不存在 |
| 429 | RATE_LIMITED / TOO_MANY_TASKS | 退避后重试 |
| 502 | UPSTREAM_ERROR | 生成服务异常，积分已自动退回，可重试 |
限流与计费
| 项 | 规则 |
|---|---|
| 请求频率 | 60 次 / 分钟 / 密钥 |
| 并发 | 跟随账号设置（默认 3 个任务同时进行） |
| 每日上限 | 跟随账号设置（默认 300 张） |
| 计费 | 按张扣积分，与网页版同一份余额和单价 |
| 失败 | 生成服务失败 / 超时 / 没返回图，积分全额自动退回 |
提示：密钥的调用次数会记在账户页的列表里， 长时间不用可以撤销，撤销立即生效。