559 lines
17 KiB
Markdown
559 lines
17 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`
|
||
- `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`
|