# 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`
- `task-detail` 分支返回的预览图直链，当前默认资源域名使用 `https://s3.jiansun.vip`
- `https://s3.yydd.ai` 当前只保留为备用资源域名；除非单独通知切换，否则调用方继续以 `https://s3.jiansun.vip` 为准

返回统一格式：

```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": "左前45°.png",
          "fileSize": 123456,
          "downloadUrl": "https://sc.jiansun.vip/api/external/download?token=xxx"
        },
        {
          "key": "rightFront45",
          "label": "右前45°",
          "fileName": "右前45°.png",
          "fileSize": 123456,
          "downloadUrl": "https://sc.jiansun.vip/api/external/download?token=yyy"
        }
      ],
      "other": [
        {
          "key": "other-1",
          "label": "其他图片1",
          "fileName": "detail-1.png",
          "fileSize": 123456,
          "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 下载链接 |

固定角度顺序固定为：

1. `leftFront45`
2. `rightFront45`
3. `leftBack45`
4. `rightBack45`
5. `front`
6. `back`
7. `left`
8. `right`

单张图片对象字段：

| 字段 | 说明 |
|---|---|
| `key` | 固定图为固定角度 key，other 图为 `other-*` |
| `label` | 图片说明 |
| `fileName` | 文件名 |
| `fileSize` | 文件大小，单位字节 |
| `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": {
          "downloadUrl": "https://sc.jiansun.vip/api/external/download?token=xxx",
          "fileName": "右前45°.png",
          "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` |

说明：

- 这个接口主要给 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[*].downloadUrl` / `whiteBackground.other[*].downloadUrl`
- 整包 ZIP：`downloadUrls.zip`

调用方式：

```http
GET https://sc.jiansun.vip/api/external/download?token=xxx
```

### 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` 查整套候选
- `task-detail` 返回多个候选时，建议调用方按 `uploadedAt` 再做一次前端展示排序或筛选。
- `task-detail` 使用的是预览图直链，不适合再按源文件 zip 的思路处理。

## 9. 当前联调状态

截至 `2026-03-21`，正式环境已部署并验证通过的内容：

- `/api/external/standard-model-white-background` 已支持 `white-background` 和 `task-detail`
- 不传 `resourceType` 时，白底图老调用方式保持兼容
- `task-detail` 已支持 `spu` / `sku` 两种查询
- 返回中已补充 `shopName`
- `任务-详情` 整套字段 `isFullSet` 已改为按主图 / SKU 图 / 详情图自动判定
- 对外文档默认资源域名已统一到 `https://s3.jiansun.vip`，同时保留 `https://s3.yydd.ai` 作为备用说明
- 相关测试已通过：`standard-model-white-background-route`、`task-detail-full-set`、`url-rewrite`
- 构建验证已通过：`npm run build`
- 正式环境健康检查已通过：`/api/health`
- 正式环境真实调用已验证：
  - `resourceType=task-detail&spu=CTG0290` 返回 `200`
  - `resourceType=task-detail&sku=DNZ025802` 返回 `200`
  - 白底图 `spu=CTG0149` 返回 `200`