Dev Spec v2 · ← 返回文档首页

03 接口规格

前缀 /api/pix/v1；JSON；金额以"分"为单位；错误格式沿用底座约定。匿名会话通过 X-Anon-Id 请求头识别（前端首次访问时生成并存储在本地）。

1. 定制会话

方法 路径 说明
GET /styles?subject=pet&region=global 风格列表（名称、样片、可选商品）
POST /sessions {"subject":"pet","style_id":"pet.renaissance_noble"} → {"session_id"}
POST /sessions/{id}/uploads 申请预签名上传：{"files":[{"name","size","content_type"}]}，1~3 张，单张 ≤ 20MB
POST /sessions/{id}/uploads/{uid}/complete 同步检查（≤ 3 秒）→ {"accepted":false,"reason":"NO_PET","hint":"..."}
POST /sessions/{id}/consent {"text_version":"2026-09-v1","relation":"own_pet"}
POST /sessions/{id}/generate 开始生成 4 张；未完成授权返回 CONSENT_REQUIRED
GET /sessions/{id} 状态、进度、已展示的预览（带水印图 URL）
POST /sessions/{id}/reroll {"style_id": "可选，换风格"}；免费次数用完返回 REROLL_PAYMENT_REQUIRED 和支付链接
POST /sessions/{id}/select {"preview_id":"..."}
GET /sessions/{id}/mockups?preview_id= 各 SKU 的效果图与是否可印刷

上传检查的 reason：TOO_SMALL、BLURRY、NO_PET、NO_FACE（老照片、双人）、MULTI_SUBJECT、UNSAFE。

2. 结账与订单

方法 路径 说明
POST /checkout 见下 → 返回支付链接（global：代理商户；cn：实物返回微信支付参数；iOS 小程序里的电子版返回"小程序虚拟支付"参数，由前端上报的平台决定；同一订单同时有电子版和实物时拆成两笔支付）
GET /orders/{id} 需要登录或凭邮件里的订单令牌访问
GET /orders/{id}/downloads 电子版下载链接（1 小时有效，可反复获取，30 天内）
POST /orders/{id}/items/{item_id}/claims 售后：{"reason":"damaged","photos":["upl_..."]} → 按规则立即返回处理结果 
// POST /checkout
{
  "session_id": "ses_...",
  "items": [
    {"sku": "digital_hd", "qty": 1},
    {"sku": "canvas_12x16", "qty": 1}
  ],
  "email": "a@b.com",
  "ship_to": {"name": "...", "line1": "...", "city": "...", "postal": "...", "country": "US"},
  "gift": {"recipient_name": "Mom", "message": "Happy birthday!", "hide_price": true}
}

服务端校验：SKU 在该区域可售、可配送到该国家、所选预览对这个 SKU 满足印刷分辨率（否则返回 SKU_NOT_PRINTABLE）。

3. 回调

路径 说明
POST /hooks/pay/{provider} 由 core.billing 验签和幂等处理，发出 payment.succeeded → 订单进入 paid
POST /hooks/fulfill/printify 代发平台的订单状态和发货事件 → 更新订单行、推送物流单号（验证签名）

4. 管理后台 /api/pix/admin/v1

方法 路径 说明
GET/POST /styles 风格管理；上线前必须附带保真度测试结果
POST /styles/{id}/fidelity-test 对测试集运行保真度测试（见 04）
GET /catalog / POST /catalog/sync 商品目录
GET /exceptions 异常队列（底座统一页面也能看到）
POST /items/{id}/resolve 处理异常：reprint / refund / resubmit
GET /stats/daily 预览数、转化率、客单价、贡献毛利、AI 成本、异常率

5. 任务载荷

# pix.gen
generate_previews(session_id: str, round: int, n: int = 4) -> None
restore_photo(session_id: str) -> None
render_item(order_item_id: str) -> None         # 放大 + 印刷文件 / 高清原图
# core.cpu
submit_fulfillment(order_item_id: str) -> None  # 调用代发接口

这些任务只调用模型网关和存储（不需要 GPU），因此可以运行在普通的 CPU worker 上。

本文档由 02_写真_开发spec/03_接口规格.md 生成 · 2026-09-27 · 打印可用 Ctrl/Cmd+P 另存为 PDF