通用素材检索

按一句自然语言或关键词，从有版权素材库检索视频 / 图片 / 音频三态素材，返回整条原始素材的下载直链、预览图、规格与标签。同步返回，无需轮询。适用于按关键词找素材并直接下载使用。视频与图片检索还可以用 stock_sources 同步附带 Pexels 的免费可商用素材，结果放在单独的 pexels_results 字段。

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

检索接口

基本信息

项目	值
请求方法	`POST`
请求路径	`/task/material_search`
Content-Type	`application/json`
鉴权方式	`Authorization` 请求头（直接传 API Key）
返回方式	同步返回检索结果（非异步任务）
计费	1 积分 / 次（失败自动退还；响应带 `task_id` 供任务查询。检索返回的素材即获持久授予——此后可经素材直链重签免费无限次取新链；附带 Pexels 补充不另计费，Pexels 素材不进授予、也不能重签）

请求参数（Body）

参数名	类型	必填	默认值	说明
`scope`	`string`	是	—	素材类型：`clip`（视频）/ `image`（图片）/ `audio`（音频），单次单一类型
`query`	`string`	是	—	自然语言描述或关键词
`top_k`	`integer`	否	`20`	返回结果数量，最大 `50`
`diversity`	`boolean`	否	`false`	去同质化，避免返回大量雷同素材
`request_id`	`string`	否	—	uuid，回显于响应，便于幂等与追溯
`stock_sources`	`array<string>`	否	—	外部图库补充源，目前只支持 `["pexels"]`。`scope` 为 `clip` / `image` 时同步检索 Pexels，结果放在单独的 `pexels_results` 字段并另回 `pexels_status`，`results` 不变（见下方 Pexels 补充结果）；`scope=audio` 不适用。不传则不查

请求示例

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": ["城市", "夜景", "航拍", "车流"]
      }
    ]
  }
}

附带 Pexels 补充的示例

请求：

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,
    "stock_sources": ["pexels"]
  }'

响应（节选：results 与 pexels_results 各列 1 条）：

{
  "code": 200,
  "msg": "success",
  "data": {
    "request_id": null,
    "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": ["城市", "夜景", "航拍", "车流"]
      }
    ],
    "pexels_status": "ok",
    "pexels_results": [
      {
        "id": "pexels:video:36590293",
        "source_id": "36590293",
        "rank": 1,
        "page_url": "https://www.pexels.com/video/36590293/",
        "author": "Photographer Name",
        "author_url": "https://www.pexels.com/@photographer",
        "download_url": "https://videos.pexels.com/video-files/36590293/example_3840_2160_30fps.mp4",
        "preview_url": "https://videos.pexels.com/video-files/36590293/example_640_360_30fps.mp4",
        "cover_url": "https://images.pexels.com/videos/36590293/example.jpeg",
        "duration": 19,
        "width": 3840,
        "height": 2160,
        "fps": 29.97,
        "orientation": "landscape",
        "tags": []
      }
    ],
    "task_id": "123456789012345678"
  }
}

响应字段说明

顶层：

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

💡 score 判读：score 为召回融合分（0~1），不同模态尺度不同、不可跨模态比较——视频/图片走图文跨模态向量（分值天然偏低），音频走文本同模态向量（分值天然偏高）。经验口径：视频/图片 score > 0.2 即效果不错；音频 score > 0.45 即效果不错。低于该档的结果多为弱相关兜底，建议按此阈值做二次筛选或截断。

视频（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 属性标签

Pexels 补充结果

请求带 stock_sources: ["pexels"] 时，响应在顶层多出两个字段；results、total、recalled 与不带该参数时完全一致。

字段	类型	说明
`pexels_status`	`string`	`ok` 有结果 / `empty` 无命中 / `unavailable` 暂不可用（稍后重试；自有结果照常返回、照常计费）/ `not_applicable` 不适用（`scope=audio`）/ `disabled` 服务端未开启
`pexels_results`	`array`	Pexels 结果，按 Pexels 的返回顺序排列；`pexels_status` 不是 `ok` 时为空数组

pexels_results 每条的字段：

字段	类型	说明
`id`	`string`	`pexels:video:<数字>` / `pexels:image:<数字>`（字符串，与自有素材的数字 id 不同形）
`source_id`	`string`	Pexels 上的素材 id
`rank`	`integer`	在 Pexels 结果中的名次，从 1 起（不带 `score`，与自有素材的分数不可比）
`page_url`	`string`	素材在 Pexels 的页面
`author` / `author_url`	`string`	摄影师名与主页
`download_url`	`string`	视频：分辨率最高的 mp4；图片：原图。直接指向 Pexels CDN，不带过期签名
`preview_url`	`string`	仅视频：约 360p 的 mp4 预览
`cover_url`	`string`	仅视频：封面图
`thumb_url`	`string`	仅图片：中尺寸图
`duration` / `fps` / `orientation`	—	仅视频：时长（秒）、帧率、画幅方向
`width` / `height`	`integer`	分辨率（像素）
`note`	`string`	仅图片：Pexels 的图片描述
`tags`	`array<string>`	Pexels 标签（常为空）

⚠️ 使用 Pexels 素材须展示署名：在你的产品或作品中使用这些素材时，请显著展示指向 Pexels 的链接（如「Photos and videos provided by Pexels」），并尽量署名摄影师（author / author_url）。不得原样转售 Pexels 素材，也不得把它们再分发到其他图库或壁纸平台。详见 Pexels License。

错误码

错误码	HTTP 状态码	说明	解决方案
`400`	400	请求参数或请求体格式错误（如 `scope` 非法、`query` 为空、`top_k` 超限、`stock_sources` 取值非法）	检查请求参数
`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；批量需求请并发多次调用。
Pexels 补充只适用于 clip / image，pexels_results 至多 top_k 条。
Pexels 暂不可用（如限流、超时）时请求照常成功：自有结果正常返回、正常计费，pexels_status 为 unavailable。

🤝 加入同和新媒体矩阵，解锁内部成员权益：矩阵成员（internal）可使用 custom 域全库素材检索（视频 / 图片 / 音频，含概念素材与非商用素材，支持仅可商用过滤）与内部专属音色。前往创作者网络申请加入，审核通过后管理员将为你开通内部权限。