概览

异步任务式图片生成：创建任务（立即返回 202 和任务 ID）→ 后台队列调用上游生成 → 轮询任务状态 → 通过 file_url 拿结果图。所有写操作都不阻塞等待出图。

基本信息

端点总览

快速开始

三步：创建任务 → 轮询到终态 → 下载 file_url。创建与轮询必须使用同一个 key（任务按 key 归属隔离）。

curl

# 1) 创建任务，拿到 id
ID=$(curl -s -X POST http://localhost:8000/api/v1/tasks/generations \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"a red apple","size":"1024x1024"}' \
  | python -c "import sys,json;print(json.load(sys.stdin)['id'])")

# 2) 轮询直到 status 变为 succeeded / failed
curl -s -H "X-API-Key: $KEY" http://localhost:8000/api/v1/tasks/$ID

Python · 文生图

import time, requests
BASE, KEY = "http://localhost:8000", "<你的key>"
h = {"X-API-Key": KEY}

r = requests.post(f"{BASE}/api/v1/tasks/generations", headers=h,
                  json={"model": "gpt-image-2", "prompt": "a red apple", "size": "1024x1024"})
tid = r.json()["id"]

while True:
    t = requests.get(f"{BASE}/api/v1/tasks/{tid}", headers=h).json()
    if t["status"] in ("succeeded", "failed"):
        break
    time.sleep(2)

if t["status"] == "succeeded":
    url = t["result"][0]["file_url"]          # 已是完整 URL，下载无需鉴权
    open("out.png", "wb").write(requests.get(url).content)
else:
    # 注意：失败时响应里没有 result 键，请勿直接 t["result"]
    print("failed:", t["error_status"], t["error"])

Python · 图生图（纯 JSON）

带参考图的请求发到 generations 也可以：服务端检测到图后自动按编辑（edits）执行。参考图可以直接给 URL，也可以给 base64。

r = requests.post(f"{BASE}/api/v1/tasks/generations", headers=h, json={
    "model": "gpt-image-2",
    "prompt": "给人物加一顶帽子",
    "size": "1024x1024",
    "image_urls": ["https://cdn.example.com/raw.jpg"],   # 或 data:image/...;base64,
})
print(r.json()["endpoint"])   # "edits" —— 带图请求自动按编辑执行

Python · 图生图（multipart 上传本地文件）

# 参考图放任意文件字段（惯用 image[]，可多张）；其余参数放 data
files = [("image[]", ("raw.jpg", open("raw.jpg", "rb"), "image/jpeg"))]
data = {"model": "gpt-image-2", "prompt": "给人物加一顶帽子", "size": "1024x1024"}
r = requests.post(f"{BASE}/api/v1/tasks/edits", headers=h, files=files, data=data)

鉴权与任务归属

每个 /api/v1/* 请求都要带 key：请求头 X-API-Key: <key>，或等价的 Authorization: Bearer <key>。

key 如何被接受

按服务端部署配置，以下任一条件满足即可通过鉴权：

都不满足时返回 401（缺 key 或 invalid API key）。开发模式（服务端未配置白名单）下任何非空 key 都被接受；若服务端没有配置自己的上游 key，你的 key 会被转发给上游做鉴权。

任务归属

• 任务按 sha256(key) 分组：同一个 key 在任何设备/工具上都能看到同一份任务列表，换 key 查询别人的任务返回 404。
• 明文 key 不会出现在任何响应里。

key 的存储安全

失败时的错误信息

上游返回错误时，任务 error 字段写入的是脱敏后的概括语（如 upstream authentication failed），不是上游原始响应；上游 HTTP 状态码写进 error_status。上游返回 401/403 时不重试、直接判失败。完整对照表见「数据结构」。

管理端点

/api/v1/upstreams*（上游 provider 管理）在服务端配置了管理 key（ADMIN_API_KEY）后仅接受该 key，普通业务 key 访问返回 401。普通 API 使用者无需关心。

通用约定

接口（/api/v1/*）的错误响应统一为 {"error": {"code": <数字或稳定错误标识>, "message": "..."}}；分辨率校验会返回 resolution_size_mismatch / unsupported_model_resolution，其余常规错误通常使用 HTTP 状态码；静态文件路径（/outputs / /inputs）的 404 为纯文本。

状态码

限流

创建任务（及同步 /v1/images/* 端点）按调用方 key 限流，默认每 key 每分钟 10 次（滑动窗口，部署可调）。超限返回 429 + Retry-After: 60。查询类接口（列表/详情/下载）不限流。

幂等创建

创建任务时带请求头 Idempotency-Key（或 JSON 字段 idempotency_key，头优先，超过 200 字节截断）：同一调用方 key 下重复提交相同幂等键时直接返回既有任务的 {id, status, endpoint, created_at}（仍是 202，status 可能已是 running/succeeded/failed），不会重复入队。该字段不会转发给上游。

任务生命周期

pending → running → succeeded / failed

状态说明

重试策略

创建生成任务

两个端点都同时接受 application/json 和 multipart/form-data（按 Content-Type 自动识别）。带参考图的请求一律按编辑执行、发往上游 /images/edits——发给 generations 也会自动转；反之 edits 不带图直接 400。所以通常只需记住：有图 = 编辑，无图 = 文生图。

请求字段（JSON）

参考图规则

• JSON：image_urls / reference_images / images:[{"image_url":...}] 三种写法等价；元素可为 http(s) URL（直接透传上游）、data:image/...;base64, 或裸 base64。
• 裸 base64 有门槛：长度 ≥ 256 字符且解码后 ≥ 64 字节，否则该元素被静默忽略。
• multipart：所有文件字段都会被当作参考图收集（字段名不限，惯用 image[]）；按文件内容嗅探格式，仅接受 png / jpeg / webp / gif。
• 单任务上限 16 张，超出返回 400。
• base64 / 上传文件会落盘为 /inputs 公开 URL 再发上游，最终统一改写为 images:[{"image_url":"完整URL"}]。服务本身需以公网地址可达（或部署方配置 PUBLIC_INPUT_BASE_URL），上游才拉得到图。

自带上游

可为单个任务指定自己的上游（不走服务端默认上游/网关）：

• 请求头 X-Upstream-Base-URL 或 JSON 字段 upstream_base_url：上游地址。会被规范化——去掉 query/fragment 和结尾的 /images/generations|edits，路径为空时自动补 /v1。
• 请求头 X-Upstream-API-Key 或 JSON 字段 upstream_api_key：上游 key。地址与 key 需配对提供：只给 key 不给地址 → 400；只给地址不给 key，在配置了服务白名单的部署下也 → 400（开发模式下会回落用调用方 key）。
• 生产环境拒绝解析到内网/回环地址的上游。

请求示例

文生图（JSON）

curl -X POST http://localhost:8000/api/v1/tasks/generations \
  -H "X-API-Key: <你的key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red apple on a wooden table, studio light",
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png"
  }'

图生图（JSON，自动转 edits）

curl -X POST http://localhost:8000/api/v1/tasks/generations \
  -H "X-API-Key: <你的key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "给人物加一顶帽子",
    "size": "16:9",
    "resolution": "2k",
    "image_urls": ["https://cdn.example.com/raw.jpg"]
  }'

图片编辑（multipart 上传本地文件）

curl -X POST http://localhost:8000/api/v1/tasks/edits \
  -H "X-API-Key: <你的key>" \
  -F "model=gpt-image-2" \
  -F "prompt=给人物加一顶帽子" \
  -F "size=1024x1024" \
  -F "image[][email protected];type=image/jpeg"

响应 202

{
  "id": "c69550f6-f94f-4e3d-89dc-7cbf5ca429fb",
  "status": "pending",
  "endpoint": "generations",
  "created_at": "2026-06-30T01:16:08.087Z"
}

只有这四个字段（精简摘要，完整字段需再查详情）。endpoint 反映任务实际执行方式：带参考图时为 "edits"，即便你调的是 generations 端点。

查询任务

列出任务

offset 模式响应

{
  "items": [ { /* TaskOut，见「数据结构」 */ } ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

游标模式（推荐深分页）

首页传空值 ?cursor=，后续页传上一次响应的 next_cursor（不透明字符串）。响应不含 total/offset；next_cursor 为空字符串表示没有更多数据。cursor 非法返回 400。

{
  "items": [ ... ],
  "limit": 20,
  "next_cursor": "eyJjIjoi…"
}

任务详情

响应 200（succeeded 示例）

{
  "id": "c69550f6-f94f-4e3d-89dc-7cbf5ca429fb",
  "endpoint": "edits",
  "status": "succeeded",
  "retry_count": 0,
  "request_summary": { "endpoint": "edits", "model": "gpt-image-2", "size": "1024x1024",
                       "prompt_chars": 42, "input_images": 1, "stream": false },
  "forwarded_request": { /* 实际发给上游的 JSON（含完整 prompt 与托管图 URL） */ },
  "result": [ { "file_url": "https://api.你的域名.com/outputs/3f9a…e7b2.png", "source": "b64_json" } ],
  "upstream_response": { /* 脱敏后的上游响应快照（base64 替换为占位符） */ },
  "error": null,
  "error_status": null,
  "created_at": "2026-06-30T01:16:08.087Z",
  "started_at": "2026-06-30T01:16:08.096Z",
  "finished_at": "2026-06-30T01:16:12.112Z",
  "updated_at": "2026-06-30T01:16:12.112Z"
}

failed 示例

{
  "id": "…", "status": "failed", "retry_count": 3,
  "error": "upstream authentication failed",
  "error_status": 401,
  ...
}

获取结果图

鉴权下载

公开静态地址

• 只能精准 URL 访问：请求目录、以 / 结尾的路径或不存在的文件一律 404，没有目录列举。
• /inputs/<name>（参考图托管地址）规则相同。

文件生命周期

特殊情况：若上游直接返回图床 URL 且服务端未回源缓存，file_url 会是上游图床的外部地址（不指向本服务），其有效期由上游决定。

健康检查与监控

健康检查

{ "status": "ok", "db": "ok", "queue_pending": 0, "version": "go-rewrite" }

Prometheus 指标

数据结构

TaskOut

result 项

request_summary

error 文案对照