ai-chatbot/SPU搜索获取图片接口文档.md

AI 生图平台白底图接口文档

用途：AI 生图平台输入 SKU 后，直接从素材库获取该 SKU 对应的白底图。 当前主域名：https://sc.jiansun.vip 旧域名：https://3d.yydd.ai，保留兼容并跳转到新域名

1. 基础信息

• 接口基地址：https://sc.jiansun.vip/api/external/
• 鉴权方式：请求头 X-API-Key
• 返回格式：application/json
• 适用范围：仅适用于 标准模型 类型素材

2. 接口说明

2.1 按 SKU 查询白底图

请求

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

请求参数

参数	类型	必填	说明
sku	string	是	SKU 名称。接口按大小写不敏感查询。

请求头

参数	类型	必填	说明
X-API-Key	string	是	外部接口访问密钥

3. 成功响应

响应示例

{
  "success": true,
  "data": {
    "sku": "text001452",
    "materialId": "484bd047-c956-48cf-a0f4-401f696aef8d",
    "productModel": "TEXT0014",
    "whiteBackground": {
      "fixed": [
        {
          "key": "leftFront45",
          "label": "左前45°",
          "fileName": "左前45°.png",
          "fileSize": 68,
          "downloadUrl": "https://3d.yydd.ai/api/external/download?token=xxx"
        },
        {
          "key": "rightFront45",
          "label": "右前45°",
          "fileName": "右前45°.png",
          "fileSize": 68,
          "downloadUrl": "https://3d.yydd.ai/api/external/download?token=xxx"
        }
      ],
      "other": [
        {
          "key": "other",
          "label": "其他图片",
          "fileName": "01-other-1.png",
          "fileSize": 68,
          "downloadUrl": "https://3d.yydd.ai/api/external/download?token=xxx"
        }
      ]
    },
    "downloadUrls": {
      "zip": "https://3d.yydd.ai/api/external/download?token=xxx"
    }
  }
}

3.1 字段说明

字段	类型	说明
data.sku	string	实际命中的 SKU 名称
data.materialId	string	素材 ID
data.productModel	string	所属 SPU / 型号
data.whiteBackgroundUploaded	boolean	是否已有白底图
data.whiteBackgroundComplete	boolean	固定 8 张是否已补齐
data.whiteBackgroundFixedCount	number	当前已上传的固定角度图数量
data.whiteBackgroundOtherCount	number	当前已上传的 other 图片数量
data.whiteBackgroundCount	number	当前白底图总数
data.missingViews	array	当前仍缺少的固定角度图
data.whiteBackground.fixed	array	当前已有的固定角度白底图，按固定顺序返回已存在项
data.whiteBackground.other	array	其他图片，可为空数组
data.downloadUrls.zip	string	当前 SKU 白底图整包 ZIP 下载链接

3.2 fixed 固定图顺序

固定图返回顺序固定为：

1. leftFront45：左前45°
2. rightFront45：右前45°
3. leftBack45：左后45°
4. rightBack45：右后45°
5. front：正视图
6. back：后视图
7. left：左视图
8. right：右视图

3.3 单张图片对象字段

字段	类型	说明
key	string	固定图为固定角度 key；其他图固定为 other
label	string	图片说明
fileName	string	文件名
fileSize	number	文件大小，单位字节
downloadUrl	string	单张图片下载链接

4. 下载方式

4.1 下载单张白底图

直接请求响应里的 downloadUrl 即可：

GET https://3d.yydd.ai/api/external/download?token=xxx

返回内容为对应图片文件，例如：

• image/png
• image/jpeg

4.2 下载整包白底图 ZIP

直接请求：

GET https://3d.yydd.ai/api/external/download?token=xxx

当 token 对应的是白底图 ZIP 时，返回：

• Content-Type: application/zip
• 文件名：{SKU}_白底图.zip

5. 错误响应

5.1 SKU 不存在

{
  "success": false,
  "error": {
    "code": "SKU_NOT_FOUND",
    "message": "未找到对应的标准模型 SKU"
  }
}

5.2 SKU 数据重复

{
  "success": false,
  "error": {
    "code": "SKU_NOT_UNIQUE",
    "message": "该 SKU 存在重复数据，暂无法对外提供白底图"
  }
}

5.3 白底图不存在

{
  "success": false,
  "error": {
    "code": "WHITE_BACKGROUND_NOT_FOUND",
    "message": "该 SKU 暂无白底图"
  }
}

5.4 API Key 无效

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key 无效或缺失"
  }
}

6. 接入建议

• 推荐主流程：先查接口 → 拿到 fixed / other → 按需下载单张图
• 如果业务需要一次性拉全量，也可以直接使用 downloadUrls.zip
• sku 查询支持大小写不敏感，但建议调用方统一按大写传参，便于排查
• 接口不再要求固定 8 张必须补齐；只要该 SKU 已有任意白底图，就会返回当前已有图片
• 下载链接为带 token 的受控链接，建议由服务端调用，不建议直接暴露到前端页面

7. cURL 示例

7.1 查询白底图

curl -X GET \
  "https://3d.yydd.ai/api/external/standard-model-white-background?sku=TEXT001452" \
  -H "X-API-Key: 5073534d7a59babbc45397a8eac5943b"

7.2 下载单张图片

curl -L \
  "https://3d.yydd.ai/api/external/download?token=xxx" \
  -o left-front-45.png

7.3 下载整包 ZIP

curl -L \
  "https://3d.yydd.ai/api/external/download?token=xxx" \
  -o TEXT001452_白底图.zip

8. 当前联调结论

已验证：

• 旧任务平台接口 GET /api/external/product-assets 正常
• 旧下载接口 GET /api/external/download?token=... 正常
• 新白底图接口 GET /api/external/standard-model-white-background 正常
• 新白底图单图下载正常

如果后续还要继续开放更多素材接口，建议继续复用当前这套：

• X-API-Key
• /api/external/*
• token 下载链接