生图

模型

packages/ai/src/catalog.ts 按展示顺序列出生图模型，DEFAULT_IMAGE_MODEL 为 flux-2-klein-4b。

五种画幅都接近一百万像素：1:1 为 1024×1024，4:3 为 1024×768，3:4 为 768×1024，16:9 为 1280×720，9:16 为 720×1280。一次请求生成 1 到 4 张，按张计价。

工作室流程

1. /app/image 提交提示词、模型、画幅、数量以及可选的参考图资源 ID。
2. 服务端按模型限制校验并计价，把积分预占、任务与 outbox 消息一起写入。
3. 队列消费者领取租约并调用提供方，Workers AI 通过 AI 绑定执行。
4. 每张结果先校验确为图片，再写入 R2 的 {userId}/ai/{assetId}.webp，并出现在媒体库中。
5. 成功则保留预占；可重试的失败会再次尝试，最多 ai.maxAttempts 次；最终失败只退还一次积分。

工作室轮询 GET /api/ai/tasks/{id} 直到任务结束。POST /api/ai/tasks/{id}/cancel 可取消排队中的任务并退还积分。

任务接口

{
  "requestId": "6f0c1d4e-0d1b-4b64-a8d6-0f7d0c9a2b11",
  "model": "flux-2-klein-4b",
  "prompt": "雨天窗边温馨的阅读角，电影感摄影",
  "ratio": "4:3",
  "count": 4,
  "references": []
}

• requestId 是每次操作新生成的 UUID。重复提交同一个 ID 会返回同一个任务，不会再扣费。
• prompt 为 1 到 2,048 个字符。references 最多 4 个媒体库资源 ID，并受所选模型限制。
• 成功返回 201 与任务。拒绝时返回 402（积分不足）、429（未完成任务过多）或 503（已达每日预算）。

参考图与媒体库

POST /api/ai/uploads 接受最大 10 MiB 的 PNG、JPEG 或 WebP，作为上传文件存入媒体库，数量受每用户 ai.uploadLimit 限制。参考图通过资源 ID 传递，服务端重新读取所有者自己的文件，而不是信任客户端传来的字节。GET /api/ai/assets/{id}/content 流式读取自己的资源（加 ?download 作为附件下载），DELETE /api/ai/assets/{id} 会同时从 R2 与 D1 删除。

提示词优化

POST /api/ai/prompt/enhance，正文为 { "prompt": "..." }，通过 Workers AI 把粗略想法扩写成详细描述。免费，每个用户每分钟最多 20 次。

新增或修改模型

1. 在 IMAGE_MODELS 中添加条目：key、名称、能力、积分、提示词与参考图上限、画幅、提供方、提供方模型 ID、预估 costUsd，以及是否支持指定尺寸。
2. 价格必须高于成本：毛利检查要求 积分 × 最便宜的积分单价 ≥ costUsd × (1 + ai.minGrossMargin)。
3. 接入新的提供方时，在 packages/ai 中实现 ImageProvider，并在 apps/web/src/modules/ai/mode.ts 中选择它。
4. 运行 pnpm test:unit，并分别在 Mock 与 Live 模式下各生成一次。