gongxiangp2/docs/脉象平台SPU素材下载接口文档.md

脉象平台 SPU 素材下载接口文档

版本日期：2026-07-01

1. 接口说明

脉象平台传入一个搜索关键词，通常是 SPU，素材平台按首页搜索栏同口径模糊匹配，并返回命中结果中的：

• 买家秀图片
• 视频类素材

接口不会返回 3D场景、任务-详情、标准模型、实拍图片、任务-3D原图 等其它素材类型。

返回结构中，buyerShow 为买家秀图片，放在前面；videos 为视频类素材，放在后面。

2. 请求地址

GET https://sc.jiansun.vip/api/external/maixiang-spu-assets?spu={SPU}

示例：

GET https://sc.jiansun.vip/api/external/maixiang-spu-assets?spu=GBGJ-DNZ0366

3. 鉴权方式

使用请求头 X-API-Key 鉴权。

X-API-Key: your-api-key-here

注意：

• API Key 必须放在请求头中。
• 不支持把 API Key 放在 URL 参数中。
• 正式 API Key 请通过单独的安全方式提供，不要写入代码仓库或公开文档。

4. 请求参数

参数	类型	必填	说明
spu	string	是	搜索关键词。通常传 SPU，接口会自动去掉首尾空格并转为大写，然后使用与首页搜索栏一致的模糊匹配。

说明：

• 只支持单个关键词查询。
• 匹配方式与素材库首页搜索栏一致：会模糊匹配 SPU / 任务号 / 报告标题 / 店铺 / 场景 / 作者 / SKU 名称 / 上传人姓名。
• 即使命中其它类型素材，接口也只返回 买家秀图片 和视频类素材。
• 组合 SPU 中的 + 会被保留，例如 GBSFY-AD0297+GBSFY-CZ0102。

5. 返回素材范围

5.1 买家秀图片

只返回素材类型为：

• 买家秀图片

5.2 视频类素材

返回以下视频类素材：

• 淘系-主图视频
• 安装视频
• 淘系-逛逛视频
• 抖音-千川素材
• 抖音-账号维护
• 主图视频
• 种草视频
• 视频
• VIDEO

6. 视频类素材保护期限制

视频类素材（安装视频除外）从上传之日起有 15 天保护期。保护期内，外部接口不会返回 720P 预览视频地址和视频片段地址。

视频类型	15天保护期	保护期内返回行为
淘系-主图视频	有	不返回 previewUrl、previewClipUrl、downloadUrl
淘系-逛逛视频	有	不返回 previewUrl、previewClipUrl、downloadUrl
抖音-千川素材	有	不返回 previewUrl、previewClipUrl、downloadUrl
抖音-账号维护	有	不返回 previewUrl、previewClipUrl、downloadUrl
安装视频	无限制	始终返回全部字段

保护期内返回的额外字段

当视频处于保护期内，接口会在该视频对象中增加以下字段，用于告知调用方当前状态：

字段	类型	说明
videoBlocked	boolean	始终为 true（保护期内）
videoBlockReason	string	固定值 VIDEO_WAIT_PERIOD
videoRemainingDays	number	剩余保护天数
videoBlockMessage	string	中文提示，如"视频类素材上传后满 15 天才能预览和下载，当前还需约 5 天"
videoAvailableAt	string | null	预计可访问时间，ISO 8601 格式
previewUrl	null	保护期内统一为 null
previewClipUrl	null	保护期内统一为 null
downloadUrl	null	保护期内统一为 null

说明：封面图（coverUrl）不受保护期限制，保护期内仍正常返回，建议脉象用封面图替代视频播放器占位。

7. 请求示例

curl -X GET \
  'https://sc.jiansun.vip/api/external/maixiang-spu-assets?spu=GBGJ-DNZ0366' \
  -H 'X-API-Key: your-api-key-here'

8. 成功响应示例

{
  "success": true,
  "data": {
    "spu": "GBGJ-DNZ0366",
    "buyerShow": {
      "total": 1,
      "items": [
        {
          "materialId": "buyer-material-id",
          "productModel": "GBGJ-DNZ0366",
          "materialType": "买家秀图片",
          "categoryName": "顾家",
          "shopName": "顾家",
          "sceneName": "客厅",
          "fileName": "buyer-show.zip",
          "fileSize": 1024000,
          "uploadedAt": "2026-05-13T10:00:00.000Z",
          "coverUrl": "https://s3.jiansun.vip/gongxiangpan/example-cover.webp",
          "previewUrls": [
            "https://s3.jiansun.vip/gongxiangpan/example-1.webp",
            "https://s3.jiansun.vip/gongxiangpan/example-2.webp"
          ],
          "downloadUrl": "https://sc.jiansun.vip/api/external/download?token=xxx"
        }
      ]
    },
    "videos": {
      "total": 2,
      "items": [
        {
          "materialId": "video-normal-id",
          "productModel": "GBGJ-DNZ0366",
          "materialType": "安装视频",
          "categoryName": "顾家",
          "shopName": "顾家",
          "sceneName": "客厅",
          "fileName": "install-video.mp4",
          "fileSize": 2048000,
          "duration": 18,
          "uploadedAt": "2026-05-13T10:05:00.000Z",
          "coverUrl": "https://s3.jiansun.vip/gongxiangpan/video-cover.jpg",
          "previewUrl": "https://s3.jiansun.vip/gongxiangpan/video-preview.mp4",
          "previewClipUrl": "https://s3.jiansun.vip/gongxiangpan/video-clip-10s.mp4",
          "downloadUrl": "https://sc.jiansun.vip/api/external/download?token=yyy"
        },
        {
          "materialId": "video-blocked-id",
          "productModel": "GBGJ-DNZ0366",
          "materialType": "抖音-千川素材",
          "categoryName": "顾家",
          "shopName": "顾家",
          "sceneName": "客厅",
          "fileName": "blocked-video.mp4",
          "fileSize": 3584000,
          "duration": 30,
          "uploadedAt": "2026-06-28T10:05:00.000Z",
          "coverUrl": "https://s3.jiansun.vip/gongxiangpan/video-cover-2.jpg",
          "previewUrl": null,
          "previewClipUrl": null,
          "videoBlocked": true,
          "videoBlockReason": "VIDEO_WAIT_PERIOD",
          "videoRemainingDays": 12,
          "videoBlockMessage": "视频类素材上传后满 15 天才能预览和下载，当前还需约 12 天",
          "videoAvailableAt": "2026-07-13T10:05:00.000Z",
          "downloadUrl": null
        }
      ]
    }
  }
}

9. 响应字段说明

9.1 顶层字段

字段	类型	说明
success	boolean	请求是否成功
data.spu	string	本次查询的标准化关键词，通常是 SPU
data.buyerShow.total	number	买家秀图片数量
data.buyerShow.items	array	买家秀图片列表
data.videos.total	number	视频素材数量
data.videos.items	array	视频素材列表

9.2 买家秀图片字段

字段	类型	说明
materialId	string	素材 ID
productModel	string	SPU 型号
materialType	string	素材类型，固定为 买家秀图片
categoryName	string	店铺/分类名称
shopName	string	店铺名称
sceneName	string	场景名称
fileName	string	下载包文件名
fileSize	number	文件大小，单位 byte
uploadedAt	string	上传时间，ISO 8601 格式
coverUrl	string | null	封面或首图预览地址
previewUrls	string[]	预览图地址数组
downloadUrl	string	正式下载链接，下载买家秀 ZIP 包

9.3 视频字段

通用字段（保护期内外均返回）：

字段	类型	说明
materialId	string	素材 ID
productModel	string	SPU 型号
materialType	string	视频素材类型
categoryName	string	店铺/分类名称
shopName	string	店铺名称
sceneName	string	场景名称
fileName	string	视频文件名
fileSize	number	文件大小，单位 byte
duration	number | null	视频时长，单位秒
uploadedAt	string	上传时间，ISO 8601 格式
coverUrl	string | null	视频封面地址，保护期内仍正常返回

受保护期影响的字段：

字段	类型	保护期外	保护期内
previewUrl	string | null	720P 预览视频地址	null
previewClipUrl	string | null	10 秒预览视频地址	null
downloadUrl	string | null	正式下载链接	null

保护期内额外字段：

字段	类型	说明
videoBlocked	boolean	始终为 true（保护期内）
videoBlockReason	string	固定值 VIDEO_WAIT_PERIOD
videoRemainingDays	number	剩余保护天数
videoBlockMessage	string	中文提示文本
videoAvailableAt	string | null	预计可访问时间，ISO 8601 格式

说明：视频超过 15 天保护期后，previewUrl、previewClipUrl、downloadUrl 正常返回，且不会出现 videoBlocked 等额外字段。

10. 错误响应

10.1 缺少 SPU

HTTP 状态码：400

{
  "success": false,
  "error": {
    "code": "MISSING_SPU",
    "message": "SPU 为必填项"
  }
}

10.2 API Key 无效或缺失

HTTP 状态码：401

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

10.3 没有找到买家秀或视频素材

HTTP 状态码：404

{
  "success": false,
  "error": {
    "code": "SPU_ASSETS_NOT_FOUND",
    "message": "该 SPU 下暂无买家秀图片或视频素材"
  }
}

10.4 服务异常

HTTP 状态码：500

{
  "success": false,
  "error": {
    "code": "SERVER_ERROR",
    "message": "服务器内部错误"
  }
}

11. 错误码汇总

HTTP 状态	code	说明
400	MISSING_SPU	缺少 SPU 参数
401	INVALID_API_KEY	API Key 无效或缺失
404	SPU_ASSETS_NOT_FOUND	该 SPU 下暂无买家秀图片或视频素材
500	SERVER_ERROR	服务器内部错误

12. 对接注意事项

• 同一 SPU 命中多条素材时，接口会全部返回，并按上传时间倒序排列。
• 如果只有买家秀图片，没有视频，接口仍返回 200，videos.total 为 0。
• 如果只有视频，没有买家秀图片，接口仍返回 200，buyerShow.total 为 0。
• 如果首页搜索能搜到该关键词，但命中的素材没有 买家秀图片 或视频类素材，接口仍返回 404。
• downloadUrl 是正式下载链接，脉象平台可直接请求该链接下载文件。
• previewUrl、previewClipUrl、coverUrl、previewUrls 是预览地址，不等同于正式下载地址。
• 不建议脉象平台解析 downloadUrl 里的 token，只需要把它当成完整 URL 使用。
• 视频保护期处理：脉象平台应检查视频对象是否存在 videoBlocked: true 字段：
  • 如果存在，说明该视频仍在 15 天保护期内，previewUrl、previewClipUrl、downloadUrl 均为 null。建议使用 coverUrl 展示封面图，并显示 videoBlockMessage 提示用户。
  • 如果不存在该字段，说明视频不受保护期限制（已超过 15 天 或 是安装视频），所有字段正常返回。
  • 保护期到期后（超过 videoAvailableAt），再次请求时接口将正常返回全部字段，不再包含 videoBlocked 相关字段。
• coverUrl 始终可用于展示，不受保护期限制。