视频素材检索（智能剪辑）

按一句自然语言画面描述或关键词，从有版权的视频素材库中检索可直接用于剪辑的片段，返回片内最匹配的时间段（segments）、取片直链、时长 / 画幅 / 帧率等信息。同步返回，无需轮询。

适用于智能剪辑 / 自动成片：按分镜描述逐个检索素材，再拼接到时间线。

检索接口

基本信息

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

请求参数（Body）

参数名	类型	必填	默认值	说明
query	string	是	—	画面描述（自然语言）或关键词
top_k	integer	否	10	返回结果数量，最大 50
diversity	boolean	否	false	去同质化，避免返回大量雷同镜头
request_id	string	否	—	uuid，回显于响应，便于幂等与追溯
filters	object	否	—	剪辑向过滤，见下表

filters 字段

参数名	类型	说明
min_duration	number	片段最短时长（秒），剪辑铺底用
max_duration	number	片段最长时长（秒）
orientation	string	画幅方向：landscape（横屏）/ portrait（竖屏）/ square（方形），匹配成片画幅
min_width	integer	分辨率宽度下限（像素）
exclude_ids	array<integer>	排除的素材 id（同一成片已用过的，去重）

请求示例

curl -X POST https://api.ai-mcn.tv:10000/task/video_clip_search \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "日落海边礁石上一人持相机拍摄的剪影",
    "top_k": 10,
    "diversity": true,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "filters": {
      "min_duration": 3,
      "orientation": "landscape",
      "min_width": 1920
    }
  }'

成功响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "recalled": 84,
    "results": [
      {
        "clip_id": 2693564728807342,
        "score": 0.87,
        "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/00005200.jpg",
        "duration": 12.4,
        "width": 3840,
        "height": 2160,
        "fps": 25,
        "orientation": "landscape",
        "segments": [
          { "start": 2.0, "end": 8.5, "best": 5.2, "score": 0.91 }
        ],
        "matched": { "facets": { "time_of_day": ["dusk"], "scene": ["coast"] } },
        "note": "黄昏时分，海边岩石岸旁，一人持相机拍摄海面。"
      }
    ]
  }
}

响应字段说明

字段	类型	说明
recalled	integer	召回总数（过滤前），可观测
results[].clip_id	integer	素材 id
results[].score	number	相关性分（精排后，降序排列）
results[].url	string	取片临时直链（mp4，带 24 小时过期签名 ?expires=&sign=；过期后重新检索获取新链接）
results[].cover_url	string	关键帧预览图
results[].duration	number	时长（秒）
results[].width / height	integer	分辨率（像素）
results[].fps	number	帧率
results[].orientation	string	画幅方向
results[].segments	array	片内匹配时间段（按 score 降序，首段即最佳段）
results[].segments[].start / end	number	段起止（秒），可直接进时间线
results[].segments[].best	number	段内最匹配时间点（秒）
results[].matched.facets	object	命中的画面属性（场景 / 时段等），透明展示
results[].note	string	素材文字描述

错误码

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

使用限制

• top_k 最大为 50，超出自动钳制。
• 本接口为单条 query；多镜位需求请并发多次调用（批量入参为后续能力）。
• 仅检索有版权素材库，不区分素材质量等级。
• 取片直链 url 带 24 小时过期签名；过期后重新检索获取新链接（cover_url 预览图不过期）。
• 片内时间段 segments 基于 1.5 秒间隔的关键帧采样，定位精度约 ±1.5 秒。