Back to Details

videos-search

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Videos Search

视频搜索

Requires API Key: Get one at https://api.search.brave.com
Plan: Included in the Search plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe
需要API Key：可在 https://api.search.brave.com 获取
套餐：包含在搜索套餐中，详情查看 https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Quick Start (cURL)

快速入门（cURL）

Basic Search

基础搜索

bash
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}"
bash
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}"

With Parameters

带参数搜索

bash
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"
bash
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"

Endpoint

接口端点

http
GET https://api.search.brave.com/res/v1/videos/search
POST https://api.search.brave.com/res/v1/videos/search
Authentication: 
X-Subscription-Token: <API_KEY>
header
Note: Both GET and POST methods are supported. POST is useful for long queries.
http
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适用于长查询场景。

Parameters

参数

ParameterTypeRequiredDefaultDescription
q
stringYes-Search query (1-400 chars, max 50 words)
country
stringNo
US
Search country (2-letter country code or 
ALL
)
search_lang
stringNo
en
Language preference (2+ char language code)
ui_lang
stringNo
en-US
UI language (e.g., "en-US")
count
intNo
20
Number of results (1-50)
offset
intNo
0
Page offset (0-9)
safesearch
stringNo
moderate
Adult content filter (
off
/
moderate
/
strict
)
freshness
stringNo-Time filter (
pd
/
pw
/
pm
/
py
or date range)
spellcheck
boolNo
true
Auto-correct query
operators
boolNo
true
Apply search operators
include_fetch_metadata
boolNo
false
Include 
fetched_content_timestamp
in results
参数类型必填默认值描述
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
字段

Freshness Values

新鲜度可选值

ValueDescription
pd
Past day (24 hours)
pw
Past week (7 days)
pm
Past month (31 days)
py
Past year (365 days)
YYYY-MM-DDtoYYYY-MM-DD
Custom date range
值描述
pd
过去1天（24小时）
pw
过去1周（7天）
pm
过去1个月（31天）
py
过去1年（365天）
YYYY-MM-DDtoYYYY-MM-DD
自定义日期范围

Response Format

响应格式

json
{
  "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"
      }
    }
  ]
}
json
{
  "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"
      }
    }
  ]
}

Response Fields

响应字段

FieldTypeDescription
type
stringAlways 
"videos"
query.original
stringThe original search query
query.altered
string?Spellcheck-corrected query (if changed)
query.cleaned
string?Cleaned/normalized query
query.spellcheck_off
bool?Whether spellcheck was disabled
query.show_strict_warning
bool?True if strict safesearch blocked adult results
query.search_operators
object?Applied search operators (
applied
, 
cleaned_query
, 
sites
)
extra.might_be_offensive
boolWhether results may contain offensive content
results[].type
stringAlways 
"video_result"
results[].url
stringSource URL of the video
results[].title
stringVideo title
results[].description
string?Video description
results[].age
string?Human-readable age (e.g. "6 months ago") or absolute date (e.g. "February 12, 2025")
results[].page_age
string?Page age from source (ISO datetime)
results[].page_fetched
string?ISO datetime when page was last fetched (e.g. 
2025-02-12T15:00:00Z
)
results[].fetched_content_timestamp
int?Fetch timestamp (only with 
include_fetch_metadata=true
)
results[].video.duration
string?Time string (variable format)
results[].video.views
int?View count as integer
results[].video.creator
string?Channel/creator name
results[].video.publisher
string?Platform (YouTube, Vimeo, etc.)
results[].video.requires_subscription
bool?Whether video requires a subscription
results[].video.tags
list[str]?Tags relevant to the video
results[].video.author
object?Author profile
results[].video.author.name
stringAuthor name
results[].video.author.url
stringAuthor profile URL
results[].video.author.long_name
string?Extended author name
results[].video.author.img
string?Author profile image URL
results[].thumbnail.src
stringServed thumbnail URL
results[].thumbnail.original
string?Original thumbnail URL
results[].meta_url.scheme
string?URL protocol scheme
results[].meta_url.netloc
string?Network location
results[].meta_url.hostname
string?Lowercased domain name
results[].meta_url.favicon
string?Favicon URL
results[].meta_url.path
string?URL path
字段类型描述
type
string固定为 
"videos"
query.original
string原始搜索查询词
query.altered
string?拼写纠错后的查询词（如有修改）
query.cleaned
string?清理/标准化后的查询词
query.spellcheck_off
bool?拼写检查是否已禁用
query.show_strict_warning
bool?严格安全搜索拦截了成人结果时返回true
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格式 datetime）
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?Favicon URL
results[].meta_url.path
string?URL路径

Search Operators

搜索运算符

Use search operators to refine results:
  • site:youtube.com
    - Limit to specific site
  • "exact phrase"
    - Match exact phrase
  • -exclude
    - Exclude term
Set 
operators=false
to disable operator parsing.
使用搜索运算符可优化搜索结果：
  • site:youtube.com
    - 限定搜索指定站点
  • "exact phrase"
    - 精确匹配短语
  • -exclude
    - 排除指定关键词
设置
operators=false
可禁用运算符解析。

Use Cases

适用场景

  • Video content research: Find tutorials, explainers, and reviews by topic. Use the 
    video.duration
    , 
    video.views
    , and 
    video.creator
    metadata to filter and rank results programmatically. Prefer videos-search over web-search when you need a dedicated video index with richer metadata (duration, views, creator, tags) and up to 50 results per request.
  • Fresh video monitoring: Use 
    freshness=pd
    or 
    freshness=pw
    to track newly published video content on trending topics or specific subjects.
  • Platform-specific search: Use 
    site:youtube.com
    or 
    site:vimeo.com
    operators to target specific video platforms.
  • Video metadata extraction: Get view counts, durations, creator info, and tags for analytics, content curation, or recommendation systems.
  • 视频内容调研：按主题查找教程、讲解视频、评测内容。可通过
    video.duration
    、
    video.views
    、
    video.creator
    元数据编程筛选和排序结果。当你需要带有更丰富元数据（时长、播放量、创作者、标签）的专属视频索引，且单请求最多支持返回50条结果时，优先使用视频搜索而非网页搜索。
  • 最新视频监测：使用
    freshness=pd
    或
    freshness=pw
    追踪热门话题或特定主题下新发布的视频内容。
  • 指定平台搜索：使用
    site:youtube.com
    或
    site:vimeo.com
    运算符定向搜索特定视频平台。
  • 视频元数据提取：获取播放量、时长、创作者信息、标签用于数据分析、内容策划或推荐系统。

Notes

注意事项

  • Pagination: Use 
    offset
    (0-9) with 
    count
    for more results
  • Max results: Up to 50 results per request
  • 分页：结合
    offset
    （0-9）和
    count
    参数获取更多结果
  • 最大返回结果数：单请求最多返回50条结果