01快速开始
生成一张图只需一个 POST 请求。Turnstile 人机验证在服务端自动完成，调用方无需关心。高并发下推荐使用 异步模式。
# 同步生成（等待出图，典型 20~45 秒）
curl -X POST https://YOUR-DOMAIN/v1/generate \
-H "Content-Type: application/json" \
-d '{"prompt":"a cute orange cat","aspect_ratio":"1:1"}'
# 返回
{
"id": "sync",
"status": "completed",
"image_url": "https://pub-xxx.r2.dev/images/xxx.png",
"error": null
}图片托管在 Cloudflare R2，URL 可直接访问或下载。
02接口总览
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/generate | POST | 生成图片（同步等待，高并发排队） |
/v1/generate/async | POST | 异步生成，立即返回任务 ID，高并发推荐 |
/v1/tasks/{id} | GET | 查询异步任务结果 |
/v1/stats | GET | 用量统计（总量 + 实时并发 + 日/月 + 平均耗时） |
/v1/gallery | GET | 最近完成的 N 条作品（画廊） |
/v1/meta | GET | 站点配置（sitekey、尺寸） |
/v1/healthz | GET | 健康检查（含实时并发/排队） |
/docs | GET | Swagger 交互文档 |
03生成图片
POST/v1/generate
提交后等待直到出图或失败；高并发下请求会进入有界队列（上限 queue_capacity），队列满返回 429。适合低频、需要立即拿结果的场景。
请求体（application/json）：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | 是 | 图像提示词，1–2000 字符 |
aspect_ratio | string | 否 | 画幅，默认 1:1，见下方 |
download | bool | 否 | 默认 false；true 时返回图片 base64 |
支持画幅（实时见 /v1/meta）：
| aspect_ratio | 尺寸 |
|---|---|
1:1 | 1024 × 1024 |
3:4 | 768 × 1024 |
4:3 | 1024 × 768 |
9:16 | 576 × 1024 |
16:9 | 1024 × 576 |
响应（HTTP 200，以 status 判断成功/失败）：
{
"id": "sync",
"status": "completed", // completed | error | queued
"image_url": "https://pub-...r2.dev/images/xxx.png",
"image_base64": null, // download=true 时
"error": null // 失败/排队时含原因
}04异步生成（高并发推荐）
POST/v1/generate/async
请求体与同步一致。立即返回任务信息，适合并发/批量场景：
{
"id": "b0b712c0-...",
"status": "pending", // pending → processing → completed | error
"image_url": null,
"error": null
}用返回的 id 轮询 /v1/tasks/{id}，直到 completed 或 error。
05查询任务状态
GET/v1/tasks/{task_id}
返回结构同上，另含 created_at、duration_sec；未找到返回 404。任务持久化在 SQLite，服务重启后历史仍可查（内存中的排队任务除外）。
curl https://YOUR-DOMAIN/v1/tasks/b0b712c0-9826-4cb1-8604-d710cc58438a06错误与状态
| HTTP | 场景 | 说明 |
|---|---|---|
| 200 | 生成完成 | status: completed，含 image_url |
| 200 | 业务失败 / 排队 | status: error 或 queued |
| 429 | 队列已满 | 并发过高被限流，稍后重试 |
| 422 | 参数校验 | 非法 aspect_ratio / 空 prompt 等 |
| 404 | 任务不存在 | 查询异步任务时 |
常见 error：turnstile 求解失败（人机验证未通过，可重试）、生成超时、生成失败（上游拒绝该 prompt，多为内容安全拦截）。
07用量统计
GET/v1/stats
总量 + 实时并发 + 平均出图耗时 + 按日/月拆分（持久化，重启不丢）：
{
"total_requests": 128,
"total_images": 120,
"total_errors": 8,
"avg_duration_sec": 26.5, // 平均出图耗时
"processing": 3, // 当前并发
"queued": 12, // 排队中
"queue_capacity": 2000, // 队列上限
"uptime_human": "1天0小时",
"daily": [{ "day": "2026-08-13", "images": 120, ... }],
"monthly": [{ "month": "2026-08", "images": 120, ... }]
}GET/v1/gallery?limit=50
最近完成的 N 条作品，用于画廊展示。
08站点信息
GET/v1/meta
{
"sitekey": 0x...,
"aspect_ratios": { "1:1": "1024x1024", "3:4": "768x1024", ... }
}09健康检查
GET/v1/healthz
{ "status": "ok", "cf_solver": "up", "processing": 3, "queued": 12 }CF 求解子服务宕机时 status 变为 degraded。