lunanting/ai-chatbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-chatbot/SPU详情接口文档.md
Your Name fe8a8564e7
Some checks failed
Lint / build (20) (push) Has been cancelled
Details
Playwright Tests / test (push) Has been cancelled
Details
Update agent visibility fixes and local docs
2026-03-21 02:01:56 +08:00

13 KiB
Raw Blame History

AI 生图平台素材接口文档

用途：AI 生图平台统一通过同一条接口，查询 标准模型白底图 或 任务-详情整套预览下载链接。
当前主域名：https://sc.jiansun.vip
当前资源公网域名：https://s3.jiansun.vip
旧应用域名：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

返回统一格式：

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

失败时：

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误说明"
  }
}

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 同时传入，接口优先按 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 下载链接

固定角度顺序固定为：

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

请求

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='任务-详情'
    • isFullSet=true
    • deletedAt=null 的候选素材
  • 返回的是预览图直链数组，不是 zip，也不是 token 下载链接
  • 返回顺序按 uploadedAt 倒序，也就是最新上传的排前面

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

请求

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

成功响应示例

{
  "success": true,
  "data": {
    "resourceType": "task-detail",
    "spu": "SPU001",
    "sku": null,
    "categoryName": "旗舰店",
    "shopName": "旗舰店",
    "candidateCount": 2,
    "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 查询所有整套 任务-详情 候选

成功响应示例

{
  "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": [],
          "sku": [],
          "detail": [],
          "all": []
        }
      }
    ]
  }
}

候选素材字段说明

字段 说明
materialId 任务-详情素材 ID
taskNo 任务号
productModel 对应 SPU
categoryName 店铺
shopName 店铺，当前与 categoryName 相同
sceneName 场景
uploadedAt 上传时间，ISO 8601 格式
isFullSet 是否整套，返回结果中固定为 true
downloadUrls.main 主图预览直链数组
downloadUrls.sku SKU 图预览直链数组
downloadUrls.detail 详情图预览直链数组
downloadUrls.all main + sku + detail 合并后的数组

说明：

  • task-detail 分支返回的是全部候选，不是只返回一条。
  • 预览链接可以直接打开或下载。
  • 历史 任务-详情 如果没有标记 isFullSet=true，不会被返回。

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 接口。

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 SPU_NOT_FOUND 未找到对应的标准模型 SPU
404 SKU_NOT_FOUND 未找到对应的标准模型 SKU
409 SKU_NOT_UNIQUE SKU 重复，暂无法对外提供任务-详情整套素材
404 TASK_DETAIL_NOT_FOUND 该 SPU 或该 SKU 所属 SPU 下暂无任务-详情素材
404 FULL_SET_NOT_FOUND 有任务-详情素材，但没有任何一条被标记为整套

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-18，本地代码已完成并验证通过的内容：

  • /api/external/standard-model-white-background 已支持 white-background 和 task-detail
  • 不传 resourceType 时，白底图老调用方式保持兼容
  • task-detail 已支持 spu / sku 两种查询
  • 返回中已补充 shopName
  • 任务-详情 整套字段 isFullSet 已接入接口返回逻辑
  • 本地构建 npm run build 已通过