WuYongJie/gongxiangp2
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
gongxiangp2/docs/AI生图白底图以及详情页面接口文档.md

21 KiB
Raw Permalink Blame History

AI 生图平台素材接口文档

用途：AI 生图平台统一通过同一条接口，查询 标准模型白底图 或 任务-详情整套预览直链 当前主域名：https://sc.jiansun.vip 当前资源基地址：https://s3.jiansun.vip/gongxiangpan 当前资源对象前缀：由壹点AI/public-display/... 历史旧资源域名：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
  • white-background 分支里返回的 previewUrl，新预览默认走 https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/white-background/...
  • task-detail 分支返回的预览图直链，当前默认走 https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/task-detail/...
  • /uploads/... 只作为源文件下载、内网访问或少量历史预览兼容路径，不作为新预览默认路径
  • 历史旧资源域名 https://s3.yydd.ai 不再作为默认对接口径
  • 当前对外读取仍使用素材平台现有 S3/MinIO 资源链路，不使用七牛云存储桶作为对接口径
  • 七牛云 bucket / CDN 只是备用迁移方案，当前未投入使用；接口返回、图片排查和对外联调都不要把 scqny.jiansun.vip 或 scqnycdn.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": "TEXT001452-旗舰店-左前45°.webp",
          "fileSize": 123456,
          "previewUrl": "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/white-background/484bd047-c956-48cf-a0f4-401f696aef8d/sku-id-1/TEXT001452-leftFront45.webp",
          "downloadUrl": "https://sc.jiansun.vip/api/external/download?token=xxx"
        },
        {
          "key": "rightFront45",
          "label": "右前45°",
          "fileName": "TEXT001452-旗舰店-右前45°.webp",
          "fileSize": 123456,
          "previewUrl": "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/white-background/484bd047-c956-48cf-a0f4-401f696aef8d/sku-id-1/TEXT001452-rightFront45.webp",
          "downloadUrl": "https://sc.jiansun.vip/api/external/download?token=yyy"
        }
      ],
      "other": [
        {
          "key": "other-1",
          "label": "其他图片1",
          "fileName": "01-detail-1.webp",
          "fileSize": 123456,
          "previewUrl": "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/white-background/484bd047-c956-48cf-a0f4-401f696aef8d/sku-id-1/other/01-detail-1.webp",
          "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 下载链接

白底图字段补充说明：

  • previewUrl 是预览专用小图，优先给页面展示或 AI 平台取图使用。
  • downloadUrl 是原图下载链接，当前仍走 token 下载接口。
  • 对于后续新上传白底图，正式存储和下载格式统一为 image/webp，并保留透明通道。
  • 历史白底图如果还没有派生预览图，previewUrl 可能临时回退到原图路径或 /uploads/... 兼容路径。

固定角度顺序固定为：

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

单张图片对象字段：

字段 说明
key 固定图为固定角度 key，other 图为 other-*
label 图片说明
fileName 文件名
fileSize 文件大小，单位字节
previewUrl 单张白底图预览链接，优先返回 1500 限制的透明 WebP
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": {
          "previewUrl": "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/white-background/484bd047-c956-48cf-a0f4-401f696aef8d/sku-id-1/TEXT001452-rightFront45.webp",
          "downloadUrl": "https://sc.jiansun.vip/api/external/download?token=xxx",
          "fileName": "TEXT001452-旗舰店-右前45°.webp",
          "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

skuList[].previewImage 内字段说明：

  • previewUrl：用于展示的小预览图，优先返回 1500 限制的透明 WebP。
  • downloadUrl：用于下载原图。
  • fileName / fileSize：对应下载原图的信息。

说明：

  • 这个接口主要给 AI 平台先展示 SKU 列表用。
  • 选定 SKU 后，再调用“按 SKU 查询白底图”接口拿完整白底图信息。

4. 任务-详情整套查询

4.1 适用场景

  • resourceType=task-detail
  • 按 SPU 查询时，直接按 任务-详情 素材类型查询，不要求先存在 标准模型
  • 按 SKU 查询时，需要先通过 标准模型 SKU 解析出所属 SPU，再按该 SPU 查询 任务-详情 候选
  • 只返回：
    • materialType='任务-详情'
    • 同时拥有主图、SKU 图、详情图
    • deletedAt=null 的候选素材
  • 返回的是预览图直链数组，不是 zip，也不是 token 下载链接
  • 返回顺序按 uploadedAt 倒序，也就是最新上传的排前面
  • 当前默认返回的资源直链基地址是 https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/...
  • 历史旧资源域名 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/由壹点AI/public-display/task-detail/material-2/main/main-1.webp"
          ],
          "sku": [
            "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/task-detail/material-2/sku/sku-1.webp"
          ],
          "detail": [
            "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/task-detail/material-2/detail/detail-1.webp"
          ],
          "all": [
            "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/task-detail/material-2/main/main-1.webp",
            "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/task-detail/material-2/sku/sku-1.webp",
            "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/task-detail/material-2/detail/detail-1.webp"
          ]
        }
      }
    ]
  }
}

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/由壹点AI/public-display/task-detail/material-2/main/main-1.webp"
          ],
          "sku": [
            "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/task-detail/material-2/sku/sku-1.webp"
          ],
          "detail": [
            "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/task-detail/material-2/detail/detail-1.webp"
          ],
          "all": [
            "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/task-detail/material-2/main/main-1.webp",
            "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/task-detail/material-2/sku/sku-1.webp",
            "https://s3.jiansun.vip/gongxiangpan/由壹点AI/public-display/task-detail/material-2/detail/detail-1.webp"
          ]
        }
      }
    ]
  }
}

候选素材字段说明

字段 说明
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 分支返回的是全部候选，不是只返回一条。
  • 预览链接可以直接打开或下载。
  • 历史 任务-详情 会按同一套资产规则判断，不再依赖人工勾选；正常新链路会返回主图 / SKU 图 / 详情图预览直链，如果极少数历史素材缺少预览资产，返回数组可能为空，需要素材平台补预览后再对接。
  • 顶层 categoryName / shopName 是便捷字段；如果要给用户展示候选素材的真实店铺，请优先使用 candidates[].shopName。

5. 下载说明

5.1 白底图

白底图会同时返回两类链接：

  • 预览图：
    • whiteBackground.fixed[*].previewUrl
    • whiteBackground.other[*].previewUrl
    • skuList[*].previewImage.previewUrl
  • 下载图：
    • whiteBackground.fixed[*].downloadUrl
    • whiteBackground.other[*].downloadUrl
  • 整包 ZIP：downloadUrls.zip

其中：

  • previewUrl 适合 AI 平台直接展示，默认优先返回缩放后的小 WebP。
  • downloadUrl 适合下载、归档或获取原图级文件。

单张下载调用方式：

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

补充说明：

  • 对于后续新上传白底图，downloadUrl 对应文件格式为 image/webp。
  • 原图级 WebP 保留透明通道，预览级 WebP 同样保留透明通道。
  • 历史白底图如果尚未生成预览图，previewUrl 可能暂时回退到原图。

5.2 任务-详情整套

任务-详情返回的是可直接访问的预览图直链数组：

  • downloadUrls.main
  • downloadUrls.sku
  • downloadUrls.detail
  • downloadUrls.all

这一分支不返回 zip，也不需要再调下载 token 接口。

补充说明：

  • 当前默认回包中的预览图资源基地址为 https://s3.jiansun.vip/gongxiangpan
  • 新任务详情预览路径默认位于 /gongxiangpan/由壹点AI/public-display/task-detail/...
  • 历史旧资源域名 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 查整套候选
  • 白底图展示时优先使用 previewUrl，不要再用 downloadUrl 当图片预览地址。
  • 白底图如果要下载原图、归档原图或打包原图，继续使用 downloadUrl / downloadUrls.zip。
  • task-detail 返回多个候选时，建议调用方按 uploadedAt 再做一次前端展示排序或筛选。
  • task-detail 使用的是预览图直链，不适合再按源文件 zip 的思路处理。

9. 当前联调状态

截至 2026-07-09，当前项目对应代码和配置口径为：

  • /api/external/standard-model-white-background 已支持 white-background 和 task-detail
  • 不传 resourceType 时，白底图老调用方式保持兼容
  • task-detail 已支持 spu / sku 两种查询
  • 返回中已补充 shopName
  • 白底图已采用 previewUrl / downloadUrl 双轨语义
  • 后续新上传白底图将统一转为 WebP 存储，并额外生成预览级 WebP
  • 任务-详情 整套字段 isFullSet 已改为按主图 / SKU 图 / 详情图自动判定
  • 对外文档默认资源基地址已统一到 https://s3.jiansun.vip/gongxiangpan
  • 当前 public-display 资源路径包含对象前缀 由壹点AI/public-display/...
  • 当前对外读取不使用七牛云存储桶