lunanting/ai-chatbot

Fork 0

Your Name be5b9aef12

Lint / build (20) (push) Has been cancelled

Details

Playwright Tests / test (push) Has been cancelled

Details

chore: sync latest workspace changes

2026-04-05 02:08:26 +08:00

17 KiB

Raw Permalink Blame History

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 为准

返回统一格式：

{
  "success": true,
  "data": {}
}

失败时：

{
  "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 查询白底图

请求

GET /api/external/standard-model-white-background?resourceType=white-background&sku={SKU}
X-API-Key: your-api-key

兼容老调用方式：

GET /api/external/standard-model-white-background?sku={SKU}
X-API-Key: your-api-key

成功响应示例

{
  "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 下载链接

固定角度顺序固定为：

leftFront45
rightFront45
leftBack45
rightBack45
front
back
left
right

单张图片对象字段：

字段	说明
`key`	固定图为固定角度 key，other 图为 `other-*`
`label`	图片说明
`fileName`	文件名
`fileSize`	文件大小，单位字节
`downloadUrl`	单张白底图下载链接

3.3 按 SPU 查询白底图 SKU 清单

请求

GET /api/external/standard-model-white-background?resourceType=white-background&spu={SPU}
X-API-Key: your-api-key

成功响应示例

{
  "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 查询任务-详情整套候选

请求

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[] 内的字段为准。

成功响应示例

{
  "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 查询任务-详情整套候选

请求

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

成功响应示例

{
  "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

调用方式：

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 查询白底图

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 清单

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 查询任务-详情整套候选

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 查询任务-详情整套候选

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

17 KiB Raw Permalink Blame History Unescape Escape

AI 生图平台素材接口文档

1. 基础信息

1.1 当前网络口径

1.2 响应诊断头

2. 通用请求规则

2.1 请求头

2.2 查询参数

3. 白底图查询

3.1 适用场景

3.2 按 SKU 查询白底图

3.3 按 SPU 查询白底图 SKU 清单

4. 任务-详情整套查询

4.1 适用场景

4.2 按 SPU 查询任务-详情整套候选

4.3 按 SKU 查询任务-详情整套候选

5. 下载说明

5.1 白底图

5.2 任务-详情整套

6. 错误码

6.1 通用错误

6.2 白底图分支错误

6.3 任务-详情分支错误

7. cURL 示例

7.1 按 SKU 查询白底图

7.2 按 SPU 查询白底图 SKU 清单

7.3 按 SPU 查询任务-详情整套候选

7.4 按 SKU 查询任务-详情整套候选

8. 接入建议

9. 当前联调状态

17 KiB

Raw Permalink Blame History