产品设计平台成品图回传接口

更新时间：2026-06-15

当前口径

当前产品设计平台回传到素材库的接口，只处理「标准模型」素材类型下的「白底图」录入。

注意：SPU、SKU、产品条码是三个不同概念，不能混用。SPU 是产品款，SKU 是 SPU 下的具体子项；产品条码是后续素材库逐步收敛的唯一业务定位值，应唯一绑定到一个 SKU；白底图在素材库当前结构中挂在 SKU 上，所以产品平台必须同时提供 SPU、SKU 和产品条码。

后续如果要增加「任务-详情」「主图」「详情图」或其它素材类型，需要另开扩展接口或启用通用素材导入接口，不和本次标准模型白底图入口混在一起。

鉴权

请求头：X-API-Key
产品设计平台使用独立 API Key：产品设计平台素材回传
API Key：8b283411c67895dec884f6c18d1f8c4e

标准模型白底图回传

方法：POST
路径：/api/external/standard-model-white-background/by-spu
Content-Type：multipart/form-data

字段

字段	必填	说明
`clientRequestId`	是	产品平台生成的请求唯一号；同一批图片重试必须保持不变
`barcode` / `productBarcode`	是	产品条码，素材库后续会逐步以它作为唯一业务定位值；同一有效条码只能绑定一个 SKU
`spu` / `productModel`	是	SPU，素材库用于定位或新建标准模型素材
`skuName` / `sku` / `skuCode`	是	SKU，素材库用于定位或新建该 SPU 下的 SKU；不能用 SPU 代替
`sourceType`	是	图片来源，只能传 `实拍`、`渲染`、`AI`
`productCategoryName`	条件必填	当 SPU 在标准模型内不存在、需要新建 SPU 时必填
`materialType`	否	如传，只能传 `标准模型`
`platformName`	否	来源平台或业务平台备注
`sourceSystem`	否	来源系统标识，建议传 `product-design-platform`
`productId`	否	产品平台内部产品 ID，用于排查追踪
`skuBatchNo`	否	产品平台批次号，用于排查追踪

图片字段

至少上传 1 张白底图。固定视角字段如下，按已有图片传即可，不要求一次传满 8 张。

字段	含义
`whiteBgLeftFront45`	左前 45 度
`whiteBgRightFront45`	右前 45 度
`whiteBgLeftBack45`	左后 45 度
`whiteBgRightBack45`	右后 45 度
`whiteBgFront`	正面
`whiteBgBack`	背面
`whiteBgLeft`	左侧
`whiteBgRight`	右侧
`whiteBgOtherImages`	其它补充图，可重复传多个文件

入库规则

素材库先在「标准模型」内按 spu/productModel 找 SPU。
如果 SPU 已存在，就只在这个已有 SPU 下处理 SKU。
如果该 SPU 下已有传入的 skuName/sku/skuCode，白底图录入这个已有 SKU。
如果该 SPU 下没有这个 SKU，则在该 SPU 下新建 SKU，再录入白底图。
如果 SPU 不存在，则要求产品平台传 productCategoryName；素材库会新建一条「标准模型」SPU，再在其下新建传入的 SKU，然后录入白底图。
如果标准模型内存在多个相同 SPU，接口返回冲突，不会猜测写入哪一条。
如果传入 SKU 名已经被其它标准模型 SPU 占用，接口返回冲突，不会跨 SPU 复用或覆盖。
如果传入产品条码已绑定到其它 SKU，接口返回冲突，不会把同一个条码写到多个 SKU。
如果传入产品条码还没有绑定，接口会把它绑定到本次最终确定的 SKU，方便后续逐步切到按条码唯一定位。
clientRequestId 做幂等：同一个请求号、同一批内容重复提交会返回同一结果；同一个请求号换了内容会返回冲突。

成功返回

{
  "success": true,
  "data": {
    "materialId": "material-uuid",
    "skuId": "sku-uuid",
    "barcode": "690000000001",
    "barcodeBindingId": "barcode-binding-uuid",
    "resolvedSpu": "SPU001",
    "resolvedSkuName": "SKU001",
    "createdMaterial": false,
    "createdSku": false,
    "createdBarcodeBinding": true,
    "uploadedAt": "2026-06-15T08:00:00.000Z",
    "traceId": "trace-uuid",
    "whiteBackgroundUploaded": true,
    "uploadedFixedCount": 1,
    "fixedCount": 1,
    "otherCount": 0,
    "whiteBackgroundCount": 1,
    "isComplete": false
  }
}

createdMaterial 表示本次是否新建了标准模型 SPU；createdSku 表示本次是否新建了 SKU。

常见错误码

错误码	含义
`INVALID_API_KEY`	API Key 无效或缺失
`INVALID_CLIENT_REQUEST_ID`	`clientRequestId` 为空
`MATERIAL_TYPE_UNSUPPORTED`	当前接口只支持标准模型白底图
`INVALID_BARCODE`	产品条码为空
`INVALID_SPU`	SPU 为空或格式化后为空
`INVALID_SKU`	SKU 为空；白底图不能在没有 SKU 的情况下录入
`INVALID_SOURCE_TYPE`	`sourceType` 不是 `实拍`、`渲染`、`AI`
`MISSING_REQUIRED_VIEWS`	没有上传任何有效白底图
`PRODUCT_CATEGORY_REQUIRED`	新建标准模型 SPU 时缺少 `productCategoryName`
`SPU_NOT_UNIQUE`	标准模型内存在多个相同 SPU
`SKU_NAME_OCCUPIED`	传入 SKU 已被其它标准模型 SPU 占用
`BARCODE_OCCUPIED`	产品条码已绑定到其它 SKU
`IDEMPOTENCY_CONFLICT`	同一个 `clientRequestId` 被用于不同请求内容

给产品设计平台的对接要求

产品平台请对接 POST /api/external/standard-model-white-background/by-spu，请求头传 X-API-Key: 8b283411c67895dec884f6c18d1f8c4e；回传时必须明确传 spu/productModel、skuName/sku/skuCode 和 barcode/productBarcode，不要把 SPU、SKU、产品条码混用；SPU 是产品款，SKU 是 SPU 下的具体子项，产品条码是后续素材库逐步收敛的唯一业务定位值，应该唯一绑定到一个 SKU；如果素材库标准模型里已有这个 SPU，就在已有 SPU 下找对应 SKU，有则录入，没有则新建 SKU 后录入，并把产品条码绑定到这个 SKU；如果素材库没有这个 SPU，就必须同时传 productCategoryName，素材库会先新建标准模型 SPU，再新建 SKU、绑定产品条码并录入白底图。本次接口只支持标准模型白底图，至少传 1 张白底图文件，sourceType 只能是 实拍、渲染、AI，每次提交要带稳定唯一的 clientRequestId 用于重试幂等。

6.3 KiB Raw Permalink Blame History Unescape Escape