[中文]

⚠️ 推荐使用 V2 版本:

• 本接口返回 YouTube 原始数据结构，需要自行解析
• 清洗过的数据版本请使用 /get_shorts_search_v2 接口，返回结构化的 Shorts 列表数据，自动过滤非 Shorts 内容

用途:

• YouTube Shorts短视频专门搜索，使用原生YouTube API接口

特点:

• 🎬 专门搜索YouTube Shorts短视频（<60秒）
• 🔍 支持多种过滤条件和排序方式
• 📱 优化的移动端短视频内容
• ⚡ 智能过滤：首次请求可能返回混合内容（长视频+短视频），默认自动过滤长视频

重要说明 - YouTube Shorts搜索机制:

根据YouTube的搜索逻辑，Shorts搜索有以下特性：

1. 首次请求（无continuation_token）：可能返回混合内容（部分长视频 + 部分短视频）
2. 后续请求（有continuation_token）：仅返回纯短视频内容
3. 解决方案：
   • 方案A：使用 filter_mixed_content=true（默认），自动过滤掉长视频
   • 方案B：使用第一次返回的 continuation_token 进行第二次请求，获取纯Shorts内容
   • 方案C：设置 filter_mixed_content=false，获取原始混合内容

参数详解:

📌 必选参数 (Required Parameters):

search_query (string)

• 作用: 搜索关键字，用于匹配Shorts视频的标题、描述等内容
• 格式: 任意字符串
• 示例: "Python编程", "gaming", "cooking tutorial"
• 注意: 支持中英文及其他语言，空格会被自动处理

⚙️ 可选参数 - 基础设置 (Optional Parameters - Basic Settings):

language_code (string, 可选)

• 作用: 设置搜索结果的显示语言，影响返回内容的语言偏好
• 默认值: "en-US"
• 可用值:
  • "zh-CN" - 简体中文
  • "zh-TW" - 繁体中文
  • "en-US" - 英语（美国）
  • "en-GB" - 英语（英国）
  • "ja-JP" - 日语
  • "ko-KR" - 韩语
  • "es-ES" - 西班牙语
  • "fr-FR" - 法语
  • "de-DE" - 德语
  • 其他符合IETF BCP 47标准的语言代码
• 示例: language_code=zh-CN
• 影响: 会影响搜索算法的语言匹配和结果排序

country_code (string, 可选)

• 作用: 设置地区/国家代码，影响搜索结果的地域相关性和内容可用性
• 默认值: "US"
• 可用值:
  • "US" - 美国
  • "CN" - 中国
  • "JP" - 日本
  • "KR" - 韩国
  • "GB" - 英国
  • "DE" - 德国
  • "FR" - 法国
  • "CA" - 加拿大
  • 其他符合ISO 3166-1 alpha-2标准的国家代码
• 示例: country_code=JP
• 影响: 某些Shorts可能因地区限制而不可见

time_zone (string, 可选)

• 作用: 设置时区，影响时间相关过滤器（如"今天"、"本周"）的计算
• 默认值: "America/Los_Angeles"
• 可用值: 符合IANA时区数据库的时区标识符
  • "America/Los_Angeles" - 美国太平洋时区
  • "America/New_York" - 美国东部时区
  • "Asia/Shanghai" - 中国时区
  • "Asia/Tokyo" - 日本时区
  • "Europe/London" - 英国时区
  • "Europe/Paris" - 法国时区
• 示例: time_zone=Asia/Shanghai
• 影响: 结合upload_time参数使用时，决定"今天"等时间段的具体范围

filter_mixed_content (boolean, 可选)

• 作用: 控制是否自动过滤掉响应中的长视频（非Shorts内容）
• 默认值: true
• 可用值:
  • true - 自动过滤长视频，只返回Shorts（推荐）
  • false - 返回原始内容，可能包含长视频
• 示例: filter_mixed_content=true
• 使用场景:
  • true: 当你只需要纯Shorts内容时使用（推荐首次请求使用）
  • false: 当你需要分析YouTube原始返回的混合内容时使用（调试用）
• 注意: 只影响首次请求，使用continuation_token的请求本身就只返回Shorts

🎯 可选参数 - Shorts过滤条件 (Optional Parameters - Shorts Filters):

upload_time (string, 可选)

• 作用: 按上传时间过滤Shorts，只返回指定时间段内上传的视频
• 默认值: null (不过滤)
• 可用值:
  • "hour" - 过去1小时内上传
  • "today" - 今天上传（基于time_zone参数）
  • "week" - 本周上传（最近7天）
  • "month" - 本月上传（最近30天）
  • "year" - 今年上传（最近365天）
• 示例: upload_time=week
• 使用场景: 寻找最新、热门的Shorts内容
• 注意: 与time_zone参数配合使用，时间计算基于设定的时区

sort_by (string, 可选)

• 作用: 设置搜索结果的排序方式
• 默认值: null (YouTube默认相关性排序)
• 可用值:
  • "relevance" - 按相关性排序（YouTube默认算法）
  • "upload_date" - 按上传日期排序（最新优先）
  • "view_count" - 按观看次数排序（最多观看优先）
  • "rating" - 按评分排序（最高评分优先）
• 示例: sort_by=view_count
• 使用场景:
  • relevance: 寻找最相关的内容
  • upload_date: 寻找最新发布的Shorts
  • view_count: 寻找最受欢迎的Shorts
  • rating: 寻找质量最高的Shorts
• 优先级: sort_by的优先级高于upload_time，两者同时使用时以sort_by为准

📄 可选参数 - 翻页控制 (Optional Parameters - Pagination):

continuation_token (string, 可选)

• 作用: 用于获取下一页搜索结果的翻页令牌
• 默认值: null (获取第一页)
• 格式: YouTube返回的加密字符串
• 示例: continuation_token=EqcBEgPkuKzor4YybhmgGk...
• 获取方式: 从上一次请求的响应中提取（见"翻页机制详解"部分）
• 使用场景:
  • 首次搜索：不传此参数，获取第一页结果
  • 后续翻页：传入上次返回的token，获取下一页结果
• 注意:
  • Token有时效性，通常在数小时内有效
  • 使用continuation_token时，必须保持search_query等其他参数一致
  • 使用token的请求会自动返回纯Shorts内容（无需过滤）

翻页机制详解:

如何获取 continuation_token：

从响应JSON中提取，路径通常为以下之一：

# 路径1：在 onResponseReceivedCommands 中
response["data"]["onResponseReceivedCommands"][0]["appendContinuationItemsAction"]["continuationItems"][-1]["continuationItemRenderer"]["continuationEndpoint"]["continuationCommand"]["token"]

# 路径2：在 contents 中
response["data"]["contents"]["twoColumnSearchResultsRenderer"]["primaryContents"]["sectionListRenderer"]["contents"][-1]["continuationItemRenderer"]["continuationEndpoint"]["continuationCommand"]["token"]

使用流程：

1. 首次请求: 不传 continuation_token

   GET /api/v1/youtube_web/get_shorts_search?search_query=python
   

2. 提取token: 从响应中找到 continuation_token
3. 后续请求: 传入 continuation_token 获取下一页

   GET /api/v1/youtube_web/get_shorts_search?search_query=python&continuation_token=xxx
   

响应数据结构:

{
  "code": 200,
  "data": {
    "contents": {
      "twoColumnSearchResultsRenderer": {
        "primaryContents": {
          "sectionListRenderer": {
            "contents": [
              {
                "itemSectionRenderer": {
                  "contents": [
                    {
                      "gridShelfViewModel": {
                        // Shorts视频列表
                        "items": [...]
                      }
                    }
                  ]
                }
              },
              {
                "continuationItemRenderer": {
                  "continuationEndpoint": {
                    "continuationCommand": {
                      "token": "xxx"  // 下一页的token
                    }
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

返回:

• 专门针对Shorts的搜索结果，包含视频列表和翻页token

[English]

Purpose:

• YouTube Shorts specialized search using native YouTube API

Features:

• 🎬 Specialized search for YouTube Shorts (<60 seconds)
• 🔍 Support for multiple filter conditions and sorting options
• 📱 Optimized for mobile short-form content
• ⚡ Smart filtering: First request may return mixed content (long+short videos), automatically filters long videos by default

Important - YouTube Shorts Search Mechanism:

According to YouTube's search logic, Shorts search has these characteristics:

1. First request (no continuation_token): May return mixed content (some long videos + some short videos)
2. Subsequent requests (with continuation_token): Returns only pure Shorts content
3. Solutions:
   • Solution A: Use filter_mixed_content=true (default) to automatically filter long videos
   • Solution B: Use continuation_token from first response for second request to get pure Shorts
   • Solution C: Set filter_mixed_content=false to get original mixed content

Parameters:

• search_query: Search keyword
• language_code: Language code (zh-CN for Chinese, en-US for English)
• country_code: Country code affecting regional relevance
• time_zone: Time zone (e.g., America/Los_Angeles, Asia/Shanghai)
• filter_mixed_content: Whether to filter long videos from mixed content (default true)

Shorts-specific Filters:

Upload Time (upload_time):

• hour: Shorts uploaded in the past hour
• today: Shorts uploaded today
• week: Shorts uploaded this week
• month: Shorts uploaded this month
• year: Shorts uploaded this year

Sort By (sort_by):

• relevance: Relevance (default)
• upload_date: Upload date
• view_count: View count
• rating: Rating

Pagination Mechanism Explained:

How to get continuation_token:

Extract from response JSON, typically at one of these paths:

# Path 1: In onResponseReceivedCommands
response["onResponseReceivedCommands"][0]["appendContinuationItemsAction"]["continuationItems"][-1]["continuationItemRenderer"]["continuationEndpoint"]["continuationCommand"]["token"]

# Path 2: In contents
response["contents"]["twoColumnSearchResultsRenderer"]["primaryContents"]["sectionListRenderer"]["contents"][-1]["continuationItemRenderer"]["continuationEndpoint"]["continuationCommand"]["token"]

Usage Flow:

1. First request: Don't pass continuation_token

   GET /api/v1/youtube_web/get_shorts_search?search_query=python
   

2. Extract token: Find continuation_token in response
3. Next requests: Pass continuation_token to get next page

   GET /api/v1/youtube_web/get_shorts_search?search_query=python&continuation_token=xxx
   

Response Data Structure:

{
  "code": 200,
  "data": {
    "contents": {
      "twoColumnSearchResultsRenderer": {
        "primaryContents": {
          "sectionListRenderer": {
            "contents": [
              {
                "itemSectionRenderer": {
                  "contents": [
                    {
                      "gridShelfViewModel": {
                        // Shorts video list
                        "items": [...]
                      }
                    }
                  ]
                }
              },
              {
                "continuationItemRenderer": {
                  "continuationEndpoint": {
                    "continuationCommand": {
                      "token": "xxx"  // Token for next page
                    }
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

⚠️ Recommend using V2 version:

• This endpoint returns raw YouTube data structure that requires manual parsing
• For cleaned/structured data, use /get_shorts_search_v2 endpoint, which returns structured Shorts list and automatically filters non-Shorts content

Returns:

• Shorts-specific search results with video list and pagination token

[示例/Examples]

基础Shorts搜索（自动过滤长视频）

GET /youtube_web/get_shorts_search?search_query=Python编程

获取原始混合内容（包含长视频）

GET /youtube_web/get_shorts_search?search_query=Python编程&filter_mixed_content=false

搜索本周上传的Python相关Shorts

GET /youtube_web/get_shorts_search?search_query=python&upload_time=week

搜索观看次数最多的技术Shorts

GET /youtube_web/get_shorts_search?search_query=技术&sort_by=view_count

翻页获取更多Shorts

GET /youtube_web/get_shorts_search?search_query=编程&continuation_token=EqcBEgPkuKzor4YybhmgGk...