593 lines
19 KiB
Markdown
593 lines
19 KiB
Markdown
# AI 生图平台素材接口文档
|
||
|
||
> 用途：AI 生图平台统一通过同一条接口，查询 `标准模型白底图` 或 `任务-详情整套预览下载链接`
|
||
> 当前主域名：`https://sc.jiansun.vip`
|
||
> 当前资源主域名：`https://s3.jiansun.vip`
|
||
> 历史旧资源域名：`https://s3.yydd.ai`（仅用于识别历史链接，不再作为对接口径）
|
||
> 旧应用域名：`https://3d.yydd.ai`（仅保留兼容跳转）
|
||
|
||
## 1. 基础信息
|
||
|
||
- 接口基地址：`https://sc.jiansun.vip/api/external/`
|
||
- 鉴权方式：请求头 `X-API-Key`
|
||
- 请求方式：`GET`
|
||
- 返回格式：`application/json`
|
||
- 主接口路径：`/api/external/standard-model-white-background`
|
||
- 默认资源类型：`white-background`
|
||
|
||
### 1.1 当前网络口径
|
||
|
||
- 接口查询、鉴权和下载 token 入口统一使用 `https://sc.jiansun.vip`
|
||
- `white-background` 分支里返回的 `previewUrl`，当前默认也是 `https://sc.jiansun.vip/uploads/...`
|
||
- `task-detail` 分支返回的预览图直链，当前默认资源域名使用 `https://s3.jiansun.vip`
|
||
- 历史旧资源域名 `https://s3.yydd.ai` 不再作为默认对接口径
|
||
|
||
返回统一格式：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
失败时：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "ERROR_CODE",
|
||
"message": "错误说明"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2 响应诊断头
|
||
|
||
为便于调用方排查“接口慢”到底是服务端慢还是链路慢，当前接口额外返回以下响应头：
|
||
|
||
| 响应头 | 说明 |
|
||
|---|---|
|
||
| `X-Trace-Id` | 本次请求追踪 ID，排查时可提供给素材平台定位服务端日志 |
|
||
| `X-Server-Duration-Ms` | 服务端实际处理耗时，单位毫秒 |
|
||
| `Server-Timing` | 标准服务端耗时头，内容与上面一致 |
|
||
| `X-Resource-Type` | 本次实际走的资源分支 |
|
||
| `X-Request-Sku` | 本次实际识别后的 SKU；未传时不返回 |
|
||
| `X-Request-Spu` | 本次实际识别后的 SPU；未传时不返回 |
|
||
|
||
## 2. 通用请求规则
|
||
|
||
### 2.1 请求头
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `X-API-Key` | 是 | 外部接口访问密钥 |
|
||
|
||
### 2.2 查询参数
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `resourceType` | 否 | 资源类型。可选 `white-background` 或 `task-detail`。不传时默认 `white-background` |
|
||
| `sku` | 条件必填 | `sku` 和 `spu` 二选一即可 |
|
||
| `spu` | 条件必填 | `sku` 和 `spu` 二选一即可 |
|
||
|
||
补充说明：
|
||
|
||
- `sku`、`spu` 都按大小写不敏感查询，建议调用方统一传大写。
|
||
- 当前服务端会先把 `sku`、`spu` 标准化为大写后再做精确匹配，建议调用方直接传大写，避免自身重复大小写转换。
|
||
- 如果 `sku` 和 `spu` 同时传入，接口优先按 `spu` 处理。
|
||
- `shopName` 当前与 `categoryName` 含义一致，都是“店铺”。
|
||
|
||
## 3. 白底图查询
|
||
|
||
### 3.1 适用场景
|
||
|
||
- `resourceType=white-background`
|
||
- 不传 `resourceType` 时也走这一分支，兼容老调用方
|
||
- 支持两种查询方式：
|
||
- `sku`：直接拿到该 SKU 的完整白底图信息
|
||
- `spu`：先拿到该 SPU 下全部 SKU 清单，再让用户选 SKU
|
||
|
||
---
|
||
|
||
### 3.2 按 SKU 查询白底图
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/external/standard-model-white-background?resourceType=white-background&sku={SKU}
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
兼容老调用方式：
|
||
|
||
```http
|
||
GET /api/external/standard-model-white-background?sku={SKU}
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
**成功响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"resourceType": "white-background",
|
||
"sku": "TEXT001452",
|
||
"materialId": "484bd047-c956-48cf-a0f4-401f696aef8d",
|
||
"productModel": "TEXT0014",
|
||
"categoryName": "旗舰店",
|
||
"shopName": "旗舰店",
|
||
"whiteBackgroundUploaded": true,
|
||
"whiteBackgroundComplete": false,
|
||
"whiteBackgroundFixedCount": 2,
|
||
"whiteBackgroundOtherCount": 1,
|
||
"whiteBackgroundCount": 3,
|
||
"missingViews": [
|
||
{
|
||
"key": "leftBack45",
|
||
"label": "左后45°"
|
||
}
|
||
],
|
||
"whiteBackground": {
|
||
"fixed": [
|
||
{
|
||
"key": "leftFront45",
|
||
"label": "左前45°",
|
||
"fileName": "TEXT001452-旗舰店-左前45°.webp",
|
||
"fileSize": 123456,
|
||
"previewUrl": "https://sc.jiansun.vip/uploads/skus/484bd047-c956-48cf-a0f4-401f696aef8d/white-background/sku-id-1/preview/TEXT001452-%E6%97%97%E8%88%B0%E5%BA%97-%E5%B7%A6%E5%89%8D45%C2%B0.webp",
|
||
"downloadUrl": "https://sc.jiansun.vip/api/external/download?token=xxx"
|
||
},
|
||
{
|
||
"key": "rightFront45",
|
||
"label": "右前45°",
|
||
"fileName": "TEXT001452-旗舰店-右前45°.webp",
|
||
"fileSize": 123456,
|
||
"previewUrl": "https://sc.jiansun.vip/uploads/skus/484bd047-c956-48cf-a0f4-401f696aef8d/white-background/sku-id-1/preview/TEXT001452-%E6%97%97%E8%88%B0%E5%BA%97-%E5%8F%B3%E5%89%8D45%C2%B0.webp",
|
||
"downloadUrl": "https://sc.jiansun.vip/api/external/download?token=yyy"
|
||
}
|
||
],
|
||
"other": [
|
||
{
|
||
"key": "other-1",
|
||
"label": "其他图片1",
|
||
"fileName": "01-detail-1.webp",
|
||
"fileSize": 123456,
|
||
"previewUrl": "https://sc.jiansun.vip/uploads/skus/484bd047-c956-48cf-a0f4-401f696aef8d/white-background/sku-id-1/preview/other/01-detail-1.webp",
|
||
"downloadUrl": "https://sc.jiansun.vip/api/external/download?token=zzz"
|
||
}
|
||
]
|
||
},
|
||
"downloadUrls": {
|
||
"zip": "https://sc.jiansun.vip/api/external/download?token=zip-token"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明**
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `resourceType` | 固定为 `white-background` |
|
||
| `sku` | 实际命中的 SKU |
|
||
| `materialId` | 标准模型素材 ID |
|
||
| `productModel` | 所属 SPU |
|
||
| `categoryName` | 店铺 |
|
||
| `shopName` | 店铺，当前与 `categoryName` 相同 |
|
||
| `whiteBackgroundUploaded` | 是否已有白底图 |
|
||
| `whiteBackgroundComplete` | 固定 8 个角度是否已补齐 |
|
||
| `whiteBackgroundFixedCount` | 已有固定角度图数量 |
|
||
| `whiteBackgroundOtherCount` | 已有 other 图数量 |
|
||
| `whiteBackgroundCount` | 白底图总数 |
|
||
| `missingViews` | 还缺少的固定角度图 |
|
||
| `whiteBackground.fixed` | 固定角度白底图列表 |
|
||
| `whiteBackground.other` | 其他白底图列表 |
|
||
| `downloadUrls.zip` | 当前 SKU 白底图 ZIP 下载链接 |
|
||
|
||
白底图字段补充说明：
|
||
|
||
- `previewUrl` 是预览专用小图，优先给页面展示或 AI 平台取图使用。
|
||
- `downloadUrl` 是原图下载链接，当前仍走 token 下载接口。
|
||
- 对于后续新上传白底图，正式存储和下载格式统一为 `image/webp`，并保留透明通道。
|
||
- 历史白底图如果还没有派生预览图，`previewUrl` 会临时回退到原图路径。
|
||
|
||
固定角度顺序固定为：
|
||
|
||
1. `leftFront45`
|
||
2. `rightFront45`
|
||
3. `leftBack45`
|
||
4. `rightBack45`
|
||
5. `front`
|
||
6. `back`
|
||
7. `left`
|
||
8. `right`
|
||
|
||
单张图片对象字段：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `key` | 固定图为固定角度 key，other 图为 `other-*` |
|
||
| `label` | 图片说明 |
|
||
| `fileName` | 文件名 |
|
||
| `fileSize` | 文件大小，单位字节 |
|
||
| `previewUrl` | 单张白底图预览链接，优先返回 1500 限制的透明 WebP |
|
||
| `downloadUrl` | 单张白底图下载链接，下载的是原图级文件 |
|
||
|
||
---
|
||
|
||
### 3.3 按 SPU 查询白底图 SKU 清单
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/external/standard-model-white-background?resourceType=white-background&spu={SPU}
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
**成功响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"resourceType": "white-background",
|
||
"spu": "TEXT0014",
|
||
"materialId": "484bd047-c956-48cf-a0f4-401f696aef8d",
|
||
"categoryName": "旗舰店",
|
||
"shopName": "旗舰店",
|
||
"skuCount": 2,
|
||
"skuList": [
|
||
{
|
||
"skuName": "TEXT001452",
|
||
"skuId": "sku-id-1",
|
||
"hasWhiteBackground": true,
|
||
"whiteBackgroundCount": 2,
|
||
"previewImage": {
|
||
"previewUrl": "https://sc.jiansun.vip/uploads/skus/484bd047-c956-48cf-a0f4-401f696aef8d/white-background/sku-id-1/preview/TEXT001452-%E6%97%97%E8%88%B0%E5%BA%97-%E5%8F%B3%E5%89%8D45%C2%B0.webp",
|
||
"downloadUrl": "https://sc.jiansun.vip/api/external/download?token=xxx",
|
||
"fileName": "TEXT001452-旗舰店-右前45°.webp",
|
||
"fileSize": 123456
|
||
}
|
||
},
|
||
{
|
||
"skuName": "TEXT001453",
|
||
"skuId": "sku-id-2",
|
||
"hasWhiteBackground": false,
|
||
"whiteBackgroundCount": 0,
|
||
"previewImage": null
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明**
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `resourceType` | 固定为 `white-background` |
|
||
| `spu` | 实际命中的 SPU |
|
||
| `materialId` | 标准模型素材 ID |
|
||
| `categoryName` | 店铺 |
|
||
| `shopName` | 店铺，当前与 `categoryName` 相同 |
|
||
| `skuCount` | 该 SPU 下 SKU 数量 |
|
||
| `skuList[].skuName` | SKU 名称 |
|
||
| `skuList[].skuId` | SKU 记录 ID |
|
||
| `skuList[].hasWhiteBackground` | 是否已有任意白底图 |
|
||
| `skuList[].whiteBackgroundCount` | 当前固定角度白底图数量 |
|
||
| `skuList[].previewImage` | 右前 45° 预览图；如果没有该角度则为 `null` |
|
||
|
||
`skuList[].previewImage` 内字段说明：
|
||
|
||
- `previewUrl`：用于展示的小预览图，优先返回 1500 限制的透明 WebP。
|
||
- `downloadUrl`：用于下载原图。
|
||
- `fileName` / `fileSize`：对应下载原图的信息。
|
||
|
||
说明：
|
||
|
||
- 这个接口主要给 AI 平台先展示 SKU 列表用。
|
||
- 选定 SKU 后，再调用“按 SKU 查询白底图”接口拿完整白底图信息。
|
||
|
||
## 4. 任务-详情整套查询
|
||
|
||
### 4.1 适用场景
|
||
|
||
- `resourceType=task-detail`
|
||
- 按 `任务-详情` 素材类型直接查询，不再要求先存在 `标准模型`
|
||
- 只返回：
|
||
- `materialType='任务-详情'`
|
||
- 同时拥有主图、SKU 图、详情图
|
||
- `deletedAt=null`
|
||
的候选素材
|
||
- 返回的是**预览图直链数组**，不是 zip，也不是 token 下载链接
|
||
- 返回顺序按 `uploadedAt` 倒序，也就是最新上传的排前面
|
||
- 当前默认返回的资源直链域名是 `https://s3.jiansun.vip`
|
||
- 历史旧资源域名 `https://s3.yydd.ai` 不再作为默认示例地址
|
||
|
||
---
|
||
|
||
### 4.2 按 SPU 查询任务-详情整套候选
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/external/standard-model-white-background?resourceType=task-detail&spu={SPU}
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
注意：
|
||
|
||
- `task-detail` 响应顶层的 `categoryName` / `shopName` 是便捷字段，取本次返回候选列表中的第一条候选素材。
|
||
- 如果 AI 平台要展示候选素材的实际店铺，请优先读取 `candidates[].categoryName` 或 `candidates[].shopName`。
|
||
- 如果同一个 SPU 下有多条候选素材，且它们店铺不同，请以各自 `candidates[]` 内的字段为准。
|
||
|
||
**成功响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"resourceType": "task-detail",
|
||
"spu": "SPU001",
|
||
"sku": null,
|
||
"categoryName": "旗舰店",
|
||
"shopName": "旗舰店",
|
||
"candidateCount": 1,
|
||
"candidates": [
|
||
{
|
||
"materialId": "material-2",
|
||
"taskNo": "TASK202601141713525624",
|
||
"productModel": "SPU001",
|
||
"categoryName": "旗舰店",
|
||
"shopName": "旗舰店",
|
||
"sceneName": "客厅",
|
||
"uploadedAt": "2026-03-18T10:00:00.000Z",
|
||
"isFullSet": true,
|
||
"downloadUrls": {
|
||
"main": [
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/main-1.jpg"
|
||
],
|
||
"sku": [
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/sku-1.jpg"
|
||
],
|
||
"detail": [
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/detail-1.jpg"
|
||
],
|
||
"all": [
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/main-1.jpg",
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/sku-1.jpg",
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/detail-1.jpg"
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.3 按 SKU 查询任务-详情整套候选
|
||
|
||
**请求**
|
||
|
||
```http
|
||
GET /api/external/standard-model-white-background?resourceType=task-detail&sku={SKU}
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
**处理逻辑**
|
||
|
||
- 先通过 `SKU -> 标准模型 SPU`
|
||
- 再按这个 SPU 查询所有整套 `任务-详情` 候选
|
||
- 顶层 `categoryName` / `shopName` 是便捷字段，取本次返回候选列表中的第一条候选素材
|
||
- 如果 AI 平台要展示候选素材的实际店铺，请优先读取 `candidates[].categoryName` 或 `candidates[].shopName`
|
||
|
||
**成功响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"resourceType": "task-detail",
|
||
"spu": "SPU001",
|
||
"sku": "SKU001",
|
||
"categoryName": "旗舰店",
|
||
"shopName": "旗舰店",
|
||
"candidateCount": 1,
|
||
"candidates": [
|
||
{
|
||
"materialId": "material-2",
|
||
"taskNo": "TASK202601141713525624",
|
||
"productModel": "SPU001",
|
||
"categoryName": "旗舰店",
|
||
"shopName": "旗舰店",
|
||
"sceneName": "客厅",
|
||
"uploadedAt": "2026-03-18T10:00:00.000Z",
|
||
"isFullSet": true,
|
||
"downloadUrls": {
|
||
"main": [
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/main-1.jpg"
|
||
],
|
||
"sku": [
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/sku-1.jpg"
|
||
],
|
||
"detail": [
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/detail-1.jpg"
|
||
],
|
||
"all": [
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/main-1.jpg",
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/sku-1.jpg",
|
||
"https://s3.jiansun.vip/gongxiangpan/preview/detail-1.jpg"
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**候选素材字段说明**
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `materialId` | 任务-详情素材 ID |
|
||
| `taskNo` | 任务号 |
|
||
| `productModel` | 对应 SPU |
|
||
| `categoryName` | 店铺 |
|
||
| `shopName` | 店铺，当前与 `categoryName` 相同 |
|
||
| `sceneName` | 场景 |
|
||
| `uploadedAt` | 上传时间，ISO 8601 格式 |
|
||
| `isFullSet` | 是否整套；当前规则为“同时拥有主图、SKU 图、详情图” |
|
||
| `downloadUrls.main` | 主图预览直链数组 |
|
||
| `downloadUrls.sku` | SKU 图预览直链数组 |
|
||
| `downloadUrls.detail` | 详情图预览直链数组 |
|
||
| `downloadUrls.all` | `main + sku + detail` 合并后的数组 |
|
||
|
||
说明：
|
||
|
||
- `task-detail` 分支返回的是**全部候选**，不是只返回一条。
|
||
- 预览链接可以直接打开或下载。
|
||
- 历史 `任务-详情` 会按同一套资产规则判断，不再依赖人工勾选。
|
||
- 顶层 `categoryName` / `shopName` 是便捷字段；如果要给用户展示候选素材的真实店铺，请优先使用 `candidates[].shopName`。
|
||
|
||
## 5. 下载说明
|
||
|
||
### 5.1 白底图
|
||
|
||
白底图会同时返回两类链接：
|
||
|
||
- 预览图：
|
||
- `whiteBackground.fixed[*].previewUrl`
|
||
- `whiteBackground.other[*].previewUrl`
|
||
- `skuList[*].previewImage.previewUrl`
|
||
- 下载图：
|
||
- `whiteBackground.fixed[*].downloadUrl`
|
||
- `whiteBackground.other[*].downloadUrl`
|
||
- 整包 ZIP：`downloadUrls.zip`
|
||
|
||
其中：
|
||
|
||
- `previewUrl` 适合 AI 平台直接展示，默认优先返回缩放后的小 WebP。
|
||
- `downloadUrl` 适合下载、归档或获取原图级文件。
|
||
|
||
单张下载调用方式：
|
||
|
||
```http
|
||
GET https://sc.jiansun.vip/api/external/download?token=xxx
|
||
```
|
||
|
||
补充说明：
|
||
|
||
- 对于后续新上传白底图，`downloadUrl` 对应文件格式为 `image/webp`。
|
||
- 原图级 WebP 保留透明通道，预览级 WebP 同样保留透明通道。
|
||
- 历史白底图如果尚未生成预览图，`previewUrl` 可能暂时回退到原图。
|
||
|
||
### 5.2 任务-详情整套
|
||
|
||
任务-详情返回的是可直接访问的预览图直链数组：
|
||
|
||
- `downloadUrls.main`
|
||
- `downloadUrls.sku`
|
||
- `downloadUrls.detail`
|
||
- `downloadUrls.all`
|
||
|
||
这一分支**不返回 zip**，也**不需要再调下载 token 接口**。
|
||
|
||
补充说明：
|
||
|
||
- 当前默认回包中的预览图资源域名为 `https://s3.jiansun.vip`
|
||
- 历史旧资源域名 `https://s3.yydd.ai` 不再作为当前默认对接地址
|
||
|
||
## 6. 错误码
|
||
|
||
### 6.1 通用错误
|
||
|
||
| HTTP 状态码 | 错误码 | 说明 |
|
||
|---|---|---|
|
||
| 401 | `INVALID_API_KEY` | API Key 无效或缺失 |
|
||
| 400 | `MISSING_PARAM` | 没有传 `sku` 或 `spu` |
|
||
| 400 | `RESOURCE_TYPE_INVALID` | `resourceType` 不是 `white-background` 或 `task-detail` |
|
||
| 500 | `SERVER_ERROR` | 服务器内部错误 |
|
||
|
||
### 6.2 白底图分支错误
|
||
|
||
| HTTP 状态码 | 错误码 | 说明 |
|
||
|---|---|---|
|
||
| 404 | `SKU_NOT_FOUND` | 未找到对应的标准模型 SKU |
|
||
| 409 | `SKU_NOT_UNIQUE` | SKU 重复，暂无法对外提供白底图 |
|
||
| 404 | `SPU_NOT_FOUND` | 未找到对应的标准模型 SPU |
|
||
| 404 | `NO_SKUS` | 该 SPU 下没有 SKU 数据 |
|
||
| 404 | `WHITE_BACKGROUND_NOT_FOUND` | 该 SKU 暂无白底图 |
|
||
|
||
### 6.3 任务-详情分支错误
|
||
|
||
| HTTP 状态码 | 错误码 | 说明 |
|
||
|---|---|---|
|
||
| 404 | `SKU_NOT_FOUND` | 未找到对应的标准模型 SKU |
|
||
| 409 | `SKU_NOT_UNIQUE` | SKU 重复，暂无法对外提供任务-详情整套素材 |
|
||
| 404 | `TASK_DETAIL_NOT_FOUND` | 该 SPU 下，或该 SKU 所属 SPU 下暂无任务-详情素材 |
|
||
| 404 | `FULL_SET_NOT_FOUND` | 有任务-详情素材，但没有任何一条同时拥有主图、SKU 图、详情图 |
|
||
|
||
## 7. cURL 示例
|
||
|
||
### 7.1 按 SKU 查询白底图
|
||
|
||
```bash
|
||
curl -X GET \
|
||
"https://sc.jiansun.vip/api/external/standard-model-white-background?sku=TEXT001452" \
|
||
-H "X-API-Key: your-api-key"
|
||
```
|
||
|
||
### 7.2 按 SPU 查询白底图 SKU 清单
|
||
|
||
```bash
|
||
curl -X GET \
|
||
"https://sc.jiansun.vip/api/external/standard-model-white-background?resourceType=white-background&spu=TEXT0014" \
|
||
-H "X-API-Key: your-api-key"
|
||
```
|
||
|
||
### 7.3 按 SPU 查询任务-详情整套候选
|
||
|
||
```bash
|
||
curl -X GET \
|
||
"https://sc.jiansun.vip/api/external/standard-model-white-background?resourceType=task-detail&spu=SPU001" \
|
||
-H "X-API-Key: your-api-key"
|
||
```
|
||
|
||
### 7.4 按 SKU 查询任务-详情整套候选
|
||
|
||
```bash
|
||
curl -X GET \
|
||
"https://sc.jiansun.vip/api/external/standard-model-white-background?resourceType=task-detail&sku=SKU001" \
|
||
-H "X-API-Key: your-api-key"
|
||
```
|
||
|
||
## 8. 接入建议
|
||
|
||
- 老的白底图调用方可以不改，继续传 `sku` 即可。
|
||
- 如果是 AI 生图平台新流程，建议：
|
||
- 白底图：`spu -> sku -> 白底图详情`
|
||
- 任务-详情：直接按 `spu` 或 `sku` 查整套候选
|
||
- 白底图展示时优先使用 `previewUrl`，不要再用 `downloadUrl` 当图片预览地址。
|
||
- 白底图如果要下载原图、归档原图或打包原图，继续使用 `downloadUrl` / `downloadUrls.zip`。
|
||
- `task-detail` 返回多个候选时，建议调用方按 `uploadedAt` 再做一次前端展示排序或筛选。
|
||
- `task-detail` 使用的是预览图直链，不适合再按源文件 zip 的思路处理。
|
||
|
||
## 9. 当前联调状态
|
||
|
||
截至 `2026-03-24`，正式环境对应代码口径已更新为：
|
||
|
||
- `/api/external/standard-model-white-background` 已支持 `white-background` 和 `task-detail`
|
||
- 不传 `resourceType` 时，白底图老调用方式保持兼容
|
||
- `task-detail` 已支持 `spu` / `sku` 两种查询
|
||
- 返回中已补充 `shopName`
|
||
- 白底图已采用 `previewUrl` / `downloadUrl` 双轨语义
|
||
- 后续新上传白底图将统一转为 WebP 存储，并额外生成预览级 WebP
|
||
- `任务-详情` 整套字段 `isFullSet` 已改为按主图 / SKU 图 / 详情图自动判定
|
||
- 对外文档默认资源域名已统一到 `https://s3.jiansun.vip`
|
||
- 相关测试已通过：`standard-model-white-background`、`white-background-preview`、`standard-model-white-background-route`、`white-background-upload-route`
|