cmshoppe/docs/tasks/T-658a.md

---
id: T-658a
title: 商品套图多图参考 cmhub 接口与提交 payload
status: DONE
phase: 7
deps: [T-564]
created: 2026-07-17
---

# T-658a 商品套图多图参考 cmhub 接口与提交 payload

## 问题 / 背景

商品套图当前每个生图请求只提交一张源图，使用顶层 `image_base64`。不勾选「每张上传图分别作为主图生成」时，除第一张外的图片没有参与生成。cmhub 已提供 `images` 有序数组：第 1 张为主商品图，第 2 至第 8 张为参考图，每项使用 `image_base64` 或 `image_url` 二选一。

## 方案

- 在 `app/image_studio_generation.py` 中集中实现多图 payload 构造。
- 本地图片统一使用 `images` 数组中的 `image_base64`，不再提交顶层旧字段。
- 单图也使用单元素 `images` 数组；多图按主图、参考图顺序提交。
- 每个请求最多提交 8 张图片。裁剪责任在**客户端**：cmhub 对超过 8 张返回 `400 bad_request`，不会代为裁剪。上游列表由 T-658b 在 spec 期裁到「主图 + 最多 7 张参考」；本层在提交前做防御性校验，若仍超过 8 张视为程序 bug，按中文错误失败，不静默截断。
- 保留异步提交、`Idempotency-Key`、轮询、自动重试、失败退点和现有并发语义。
- 在提交前校验单图和总 payload 大小，避免 Base64 请求体过大；同一轮生成可按资产 ID缓存已编码内容，但必须有界。
- 为 cmhub 请求增加真实接口契约测试：数组结构、最大数量、字段互斥、空项、错误响应和点数返回。
- 若接口契约不满足，按中文错误提示失败，不静默回退到旧字段；是否支持旧服务端必须在发布前明确验证。
- **发布门槛**：T-658a/b/c/d 是一个发布单元。本任务落地而 T-658c（提示词一致性）未落地的中间版本，会出现「提示词声称单图、实际提交多图」的事实不符；在 T-658d 验收通过前不得打包发布安装程序。

## 验收要点

- 单图请求只有 `images=[{"image_base64": ...}]`，没有顶层 `image_base64`。
- 多图请求首元素是主图，后续是按顺序排列的参考图，最多 8 张。
- 不能同时提交旧字段和新字段；空数组、空图片项、超过上限按可识别错误处理。
- 每个生图请求的点数以 cmhub 返回值为准，确认现有点数展示没有按图片数量重复计算。
- 异步任务的幂等、轮询和重试回归测试通过。

## 边界（不改什么）

- 不修改 cmhub 服务端协议、计费、并发和轮询策略。
- 不修改提示词模板、数据库 schema、GUI 布局、蝦皮 CDP 流程。
- 不实现图片语义分组或多 SKU 自动识别。

## 验证

```bash
py -3.10 -m unittest tests.test_image_studio_generation
py -3.10 -m ruff check app tests main.py
py -3.10 -m compileall app main.py
git diff --check
```

## 执行记录

- 2026-07-17：将商品套图异步生图 payload 统一改为 `images` 数组，单图也不再发送顶层 `image_base64`；为后续参考图传入保留同一构造入口。
- 2026-07-17：新增最多8张、单图原文件10MiB、编码后总输入32MiB的请求前限制；超限使用中文错误阻断，超出数量以中文事件提示。
- 2026-07-17：补充单图 payload、图片顺序/8张裁剪及总大小超限的单元测试；同步架构/API 文档中的商品套图提交字段说明。
- 验证通过：`py -3.10 -m unittest tests.test_image_studio_generation`（11项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。