gongxiangp2/docs/视频素材查询接口文档.md

视频素材查询接口文档

版本日期：2026-07-01

1. 接口说明

供外部系统按 SPU / SKU / 条码 任一维度查询素材平台中的全部视频类素材。接口会自动识别传入的关键词类型，优先按条码精确匹配，无结果时回退到 SKU 模糊匹配，再无结果时回退到 SPU 模糊匹配。

2. 请求地址

GET https://sc.jiansun.vip/api/external/video-assets?keyword={SPU/SKU/条码}

示例：

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

3. 鉴权方式

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

X-API-Key: 2de6cc09849a711bd7d72bece8a31778

⚠️ 此 API Key 仅限对接方使用，请勿泄露或写入公开代码仓库。

4. 请求参数

参数	类型	必填	说明
keyword	string	是	查询关键词，支持 SPU、SKU 名称、条码。接口自动去掉首尾空格并转为大写后匹配

5. 查询逻辑

接口按以下优先级逐层搜索，上一层命中即停止：

优先级	匹配方式	匹配字段
1. 条码	精确匹配	MaterialSkuBarcode.barcode → Material
2. SKU	模糊匹配	MaterialSku.skuName → Material
3. SPU	模糊匹配	Material.productModel → Material

所有匹配结果按上传时间倒序返回，同一素材不会重复出现。

6. 返回视频类型

接口只返回以下视频类素材：

• 淘系-主图视频
• 安装视频
• 淘系-逛逛视频
• 抖音-千川素材
• 抖音-账号维护
• 主图视频（兼容旧类型）
• 种草视频（兼容旧类型）
• 视频（兼容旧类型）
• VIDEO（兼容旧类型）

7. 视频保护期说明

除 安装视频 外，所有视频类素材上传后有 15 天保护期。

场景	previewUrl	previewClipUrl	downloadUrl	coverUrl
保护期内	null	null	null	正常返回
保护期外 / 安装视频	正常返回	正常返回	正常返回	正常返回

保护期内，视频对象会额外包含以下字段用于展示状态：

字段	类型	说明
videoBlocked	boolean	固定为 true
videoBlockReason	string	固定为 VIDEO_WAIT_PERIOD
videoRemainingDays	number	剩余保护天数
videoBlockMessage	string	中文提示文本
videoAvailableAt	string	预计可访问时间

保护期到期后，以上字段自动消失，全部正常返回。

8. 请求示例

curl -X GET \
  'https://sc.jiansun.vip/api/external/video-assets?keyword=GBGJ-DNZ0366' \
  -H 'X-API-Key: 2de6cc09849a711bd7d72bece8a31778'

9. 成功响应示例

{
  "success": true,
  "data": {
    "keyword": "GBGJ-DNZ0366",
    "total": 2,
    "items": [
      {
        "materialId": "video-normal-id",
        "productModel": "GBGJ-DNZ0366",
        "materialType": "安装视频",
        "categoryName": "顾家",
        "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": "顾家",
        "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
      }
    ]
  }
}

10. 响应字段说明

10.1 顶层字段

字段	类型	说明
success	boolean	请求是否成功
data.keyword	string	本次查询的关键词
data.total	number	匹配的视频素材数量
data.items	array	视频素材列表

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

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

10.3 受保护期影响的字段

字段	保护期外	保护期内
previewUrl	720P 预览视频地址	null
previewClipUrl	10 秒片段地址	null
downloadUrl	源文件下载链接	null

10.4 保护期内额外字段

字段	类型	说明
videoBlocked	boolean	true
videoBlockReason	string	VIDEO_WAIT_PERIOD
videoRemainingDays	number	剩余天数
videoBlockMessage	string	中文提示
videoAvailableAt	string	预计可访问时间

11. 错误响应

11.1 缺少 keyword

HTTP 状态码：400

{
  "success": false,
  "error": {
    "code": "MISSING_KEYWORD",
    "message": "keyword 为必填项"
  }
}

11.2 API Key 无效

HTTP 状态码：401

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

11.3 未找到视频素材

HTTP 状态码：404

{
  "success": false,
  "error": {
    "code": "VIDEO_NOT_FOUND",
    "message": "未找到匹配的视频素材"
  }
}

11.4 服务异常

HTTP 状态码：500

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

12. 对接注意事项

• 同一个 keyword 命中多条素材时全部返回，按上传时间倒序排列。
• 对接方应检查视频对象是否存在 videoBlocked: true 字段：
  • 存在 → 保护期内，使用 coverUrl 展示封面，显示 videoBlockMessage 提示用户。
  • 不存在 → 正常素材，所有字段可用。
• coverUrl 始终可用于展示，不受保护期限制。
• downloadUrl 为正式下载链接，直接请求即可下载源文件。
• 不建议解析 downloadUrl 里的 token，当成完整 URL 使用即可。