通用素材检索

按一句自然语言或关键词，从有版权素材库检索视频 / 图片 / 音频三态素材，返回整条原始素材的下载直链、预览图、规格与标签。同步返回，无需轮询。适用于按关键词找素材并直接下载使用。

与视频素材检索（智能剪辑）的区别：智能剪辑返回片内最匹配的时间段（segments）用于拼接时间线；通用检索返回整条素材的下载链。

检索接口

基本信息

项目	值
请求方法	POST
请求路径	/task/material_search
Content-Type	application/json
鉴权方式	Authorization 请求头（直接传 API Key）
返回方式	同步返回检索结果（非异步任务）

请求参数（Body）

参数名	类型	必填	默认值	说明
scope	string	是	—	素材类型：clip（视频）/ image（图片）/ audio（音频），单次单一类型
query	string	是	—	自然语言描述或关键词
top_k	integer	否	20	返回结果数量，最大 50
diversity	boolean	否	false	去同质化，避免返回大量雷同素材
request_id	string	否	—	uuid，回显于响应，便于幂等与追溯

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/material_search \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "clip",
    "query": "城市夜景航拍",
    "top_k": 20,
    "diversity": true,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

成功响应示例（scope=clip）

{
  "code": 200,
  "msg": "success",
  "data": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "recalled": 64,
    "total": 20,
    "results": [
      {
        "id": 2693564728807342,
        "score": 0.87,
        "download_url": "https://cdn.example.com/nmcn/material/video_clip/raw/2693564728807342.mp4?expires=1750086000&sign=Xa1b2C3d4E5f6G7h8I9j0k",
        "cover_url": "https://cdn.example.com/nmcn/material/video_clip/keyframe/2693564728807342/cover.jpg",
        "preview_url": "https://cdn.example.com/nmcn/material/video_clip/preview/2693564728807342.mp4",
        "duration": 12.4,
        "width": 3840,
        "height": 2160,
        "fps": 25,
        "orientation": "landscape",
        "note": "城市夜晚航拍，鳞次栉比的高楼与车流光轨。",
        "tags": ["城市", "夜景", "航拍", "车流"]
      }
    ]
  }
}

响应字段说明

顶层：

字段	类型	说明
request_id	string	回显请求中的 request_id
recalled	integer	召回总数（过滤前），可观测
total	integer	本次返回结果数
results	array	结果列表，按 score 降序；字段随 scope 不同（见下）

视频（scope=clip）结果字段：

字段	类型	说明
id	integer	素材 id
score	number	相关性分（精排后，降序）
download_url	string	整条原片下载临时直链（mp4，带 24 小时过期签名 ?expires=&sign=）
cover_url	string	封面图（不过期）
preview_url	string	低码率预览代理（不过期）
duration	number	时长（秒）
width / height	integer	分辨率（像素）
fps	number	帧率
orientation	string	画幅方向：landscape / portrait / square
note	string	素材文字描述
tags	array<string>	AI 属性标签

图片（scope=image）结果字段：

字段	类型	说明
id	integer	素材 id
score	number	相关性分
download_url	string	原图下载临时直链（带 24 小时过期签名）
thumb_url	string	缩略图（不过期）
width / height	integer	分辨率（像素）
note	string	素材文字描述
tags	array<string>	AI 属性标签

音频（scope=audio）结果字段：

字段	类型	说明
id	integer	素材 id
score	number	相关性分
download_url	string	原曲下载临时直链（mp3，带 24 小时过期签名）
accompaniment_url	string	伴奏（off-vocal）下载直链（带签名，仅 audio_type=song 有）
cover_url	string	封面图（不过期）
title	string	歌名
author	string	歌手 / 创作者
duration	number	时长（秒）
audio_type	string	song（歌曲）/ pure（纯音乐）
note	string	素材文字描述
tags	array<string>	AI 属性标签

错误码

错误码	HTTP 状态码	说明	解决方案
400	400	请求参数或请求体格式错误（如 scope 非法、query 为空、top_k 超限）	检查请求参数
6502	401	鉴权失败	检查 Authorization 请求头中的 API Key
6401	6401	上游检索服务不可用	稍后重试
6402	6402	上游检索服务超时	稍后重试

使用限制

• top_k 最大为 50，超出自动钳制。
• 单次检索单一 scope（不跨模态混排）；需多模态请分别调用。
• 下载直链 download_url（含音频 accompaniment_url）带 24 小时过期签名；过期后重新检索获取新链接。预览类 cover_url / thumb_url / preview_url 不过期。
• 本接口为单条 query；批量需求请并发多次调用。