videos-search

视频搜索

需要 API 密钥：在 https://api.search.brave.com 获取

套餐：包含在 Search 套餐中。参见 https://api-dashboard.search.brave.com/app/subscriptions/subscribe

快速开始（cURL）

基本搜索

curl -s "https://api.search.brave.com/res/v1/videos/search?q=python+tutorial" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

使用参数

curl -s "https://api.search.brave.com/res/v1/videos/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=machine learning explained" \
  --data-urlencode "country=US" \
  --data-urlencode "search_lang=en" \
  --data-urlencode "count=20" \
  --data-urlencode "freshness=pm"

端点

GET https://api.search.brave.com/res/v1/videos/search
POST https://api.search.brave.com/res/v1/videos/search

身份验证：X-Subscription-Token: <API_KEY> 请求头

注意：支持 GET 和 POST 方法。POST 适用于较长的查询。

参数

参数	类型	必填	默认值	描述
q	string	是	-	搜索查询（1-400 个字符，最多 50 个单词）
country	string	否	US	搜索国家（2 个字母的国家代码或 ALL）
search_lang	string	否	en	语言偏好（至少 2 个字符的语言代码）
ui_lang	string	否	en-US	UI 语言（例如，“en-US”）
count	int	否	20	结果数量（1-50）
offset	int	否	0	页面偏移量（0-9）
safesearch	string	否	moderate	成人内容过滤（off/moderate/strict）
freshness	string	否	-	时间过滤（pd/pw/pm/py 或日期范围）
spellcheck	bool	否	true	自动更正查询
operators	bool	否	true	应用搜索运算符
include_fetch_metadata	bool	否	false	在结果中包含 fetched_content_timestamp

时间范围值

值	描述
pd	过去一天（24 小时）
pw	过去一周（7 天）
pm	过去一个月（31 天）
py	过去一年（365 天）
YYYY-MM-DDtoYYYY-MM-DD	自定义日期范围

响应格式

{
  "type": "videos",
  "query": {
    "original": "python tutorial",
    "spellcheck_off": false
  },
  "extra": {
    "might_be_offensive": false
  },
  "results": [
    {
      "type": "video_result",
      "title": "Python Tutorial for Beginners",
      "url": "https://www.youtube.com/watch?v=rfscVS0vtbw",
      "description": "Learn Python programming from scratch...",
      "age": "February 12, 2025",
      "page_age": "2025-02-12T00:00:00",
      "page_fetched": "2025-02-12T15:00:00Z",
      "thumbnail": {
        "src": "https://imgs.search.brave.com/...",
        "original": "https://i.ytimg.com/vi/rfscVS0vtbw/hqdefault.jpg"
      },
      "video": {
        "duration": "03:45:00",
        "views": 1523000,
        "creator": "freeCodeCamp",
        "publisher": "YouTube",
        "requires_subscription": false,
        "tags": ["python", "programming"],
        "author": {
          "name": "freeCodeCamp.org",
          "url": "https://www.youtube.com/@freecodecamp"
        }
      },
      "meta_url": {
        "scheme": "https",
        "netloc": "youtube.com",
        "hostname": "www.youtube.com",
        "favicon": "https://imgs.search.brave.com/...",
        "path": "\u203a watch"
      }
    }
  ]
}

响应字段

字段	类型	描述
type	string	始终为 "videos"
query.original	string	原始搜索查询
query.altered	string?	拼写检查修正后的查询（如果有更改）
query.cleaned	string?	清理/规范化后的查询
query.spellcheck_off	bool?	是否禁用了拼写检查
query.show_strict_warning	bool?	严格安全搜索是否屏蔽了成人内容结果
query.search_operators	object?	已应用的搜索运算符（applied、cleaned_query、sites）
extra.might_be_offensive	bool	结果是否可能包含冒犯性内容
results[].type	string	始终为 "video_result"
results[].url	string	视频的来源 URL
results[].title	string	视频标题
results[].description	string?	视频描述
results[].age	string?	人类可读的发布时间（例如 "6 months ago"）或绝对日期（例如 "February 12, 2025"）
results[].page_age	string?	来源提供的页面时间（ISO 日期时间）
results[].page_fetched	string?	页面上次抓取的 ISO 日期时间（例如 2025-02-12T15:00:00Z）
results[].fetched_content_timestamp	int?	抓取时间戳（仅在 include_fetch_metadata=true 时提供）
results[].video.duration	string?	时间字符串（格式不固定）
results[].video.views	int?	整数形式的观看次数
results[].video.creator	string?	频道/创作者名称
results[].video.publisher	string?	平台（YouTube、Vimeo 等）
results[].video.requires_subscription	bool?	视频是否需要订阅
results[].video.tags	list[str]?	与视频相关的标签
results[].video.author	object?	作者资料
results[].video.author.name	string	作者姓名
results[].video.author.url	string	作者资料 URL
results[].video.author.long_name	string?	作者完整名称
results[].video.author.img	string?	作者资料图片 URL
results[].thumbnail.src	string	提供的缩略图 URL
results[].thumbnail.original	string?	原始缩略图 URL
results[].meta_url.scheme	string?	URL 协议方案
results[].meta_url.netloc	string?	网络位置
results[].meta_url.hostname	string?	转为小写的域名
results[].meta_url.favicon	string?	网站图标 URL
results[].meta_url.path	string?	URL 路径

搜索运算符

使用搜索运算符来筛选结果：

• site:youtube.com - 限定在特定网站中搜索
• "exact phrase" - 匹配确切短语
• -exclude - 排除词语

设置 operators=false 可禁用运算符解析。

使用场景

• 视频内容研究：按主题查找教程、讲解视频和评论。使用 video.duration、video.views 和 video.creator 元数据，以编程方式筛选和排列结果。需要专用视频索引、更丰富的元数据（时长、观看次数、创作者、标签）以及每次请求最多 50 条结果时，优先使用 videos-search 而不是 web-search。
• 最新视频监控：使用 freshness=pd 或 freshness=pw，追踪热门话题或特定主题下新发布的视频内容。
• 特定平台搜索：使用 site:youtube.com 或 site:vimeo.com 运算符，针对特定视频平台搜索。
• 视频元数据提取：获取观看次数、时长、创作者信息和标签，用于分析、内容整理或推荐系统。

注意事项

• 分页：将 offset（0-9）与 count 配合使用可获取更多结果
• 最多结果数：每次请求最多返回 50 条结果