图片生成 API · 文档

异步任务式图片生成：创建任务（请求体透传给上游）→ 后台队列生成 → 轮询任务状态 → 拿结果图。 所有写操作立即返回任务 ID（202），不阻塞等待出图。

1. 鉴权

每个 /api/v1/* 请求都要带请求头 X-API-Key，它的值就是你的上游服务商 key。

• 不做白名单校验：服务端不验证这个 key，而是把它原样转发给上游做鉴权（Authorization: Bearer <key>）。key 对不对由上游服务商判定（错了任务会 failed，并把上游返回写进 error）。
• 任务归属：任务按 sha256(key) 分组，你只能看到用同一个 key 创建的任务（别人的返回 404）。明文 key 不会出现在任何响应里。
• 缺少该请求头 → 401（除非服务端配置了默认回退 key）。

2. 通用约定

状态码

3. 任务状态机

pending → running → succeeded / failed

4. 创建文生图任务

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"
  }'

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

5. 创建图片编辑任务

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"

{ "id": "…", "status": "pending", "endpoint": "edits", "created_at": "…" }

6. 列出任务

{
  "items": [ { /* TaskOut，见 §10 */ } ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

7. 查询任务详情

{
  "id": "c69550f6-f94f-4e3d-89dc-7cbf5ca429fb",
  "endpoint": "generations",
  "status": "succeeded",
  "retry_count": 0,
  "request_summary": { "model": "gpt-image-2", "size": "1024x1024", "prompt_chars": 42 },
  "result": [ { "file_url": "https://api.你的域名.com/outputs/generated_c69550f6_1.png" } ],
  "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:08.112Z",
  "updated_at": "2026-06-30T01:16:08.112Z"
}

{
  "id": "…", "status": "failed", "retry_count": 3,
  "result": null,
  "error": "upstream 401: invalid api key",
  "error_status": 401,
  ...
}

8. 下载结果图（鉴权）

9. 静态图 / 健康检查

10. 数据结构

TaskOut

result 项

11. 完整流程示例

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) 轮询直到终态
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:
    print("failed:", t["error_status"], t["error"])

Python（图生图 / 编辑：multipart 上传参考图）

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

# 参考图用字段名 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)
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("edited.png", "wb").write(requests.get(url).content)
else:
    print("failed:", t["error_status"], t["error"])