# Shorts搜索（原始数据，推荐使用V2）/Shorts search (raw data, recommend V2) ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /api/v1/youtube/web_v2/get_shorts_search: get: summary: Shorts搜索（原始数据，推荐使用V2）/Shorts search (raw data, recommend V2) deprecated: false description: >- # [中文] ### ⚠️ 推荐使用 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中提取，路径通常为以下之一： ```python # 路径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 ``` ### 响应数据结构: ```json { "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: ```python # 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: ```json { "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... operationId: get_shorts_search_api_v1_youtube_web_v2_get_shorts_search_get tags: - YouTube-Web-V2-API - YouTube-Web-V2-API parameters: - name: search_query in: query description: 搜索关键字/Search keyword required: true example: Python编程 schema: type: string maxLength: 200 description: 搜索关键字/Search keyword title: Search Query - name: language_code in: query description: 语言代码（如zh-CN, en-US等）/Language code required: false example: en-US schema: type: string description: 语言代码（如zh-CN, en-US等）/Language code default: en-US title: Language Code - name: country_code in: query description: 国家代码（如US, CN等）/Country code required: false example: US schema: type: string description: 国家代码（如US, CN等）/Country code default: US title: Country Code - name: time_zone in: query description: 时区（如America/Los_Angeles, Asia/Shanghai等）/Time zone required: false example: America/Los_Angeles schema: type: string description: 时区（如America/Los_Angeles, Asia/Shanghai等）/Time zone default: America/Los_Angeles title: Time Zone - name: upload_time in: query description: 上传时间过滤 | Upload time filter for Shorts required: false schema: anyOf: - $ref: '#/components/schemas/YouTubeUploadTimeAPI' - type: 'null' description: 上传时间过滤 | Upload time filter for Shorts examples: hour: summary: 过去1小时 value: hour today: summary: 今天 value: today week: summary: 本周 value: week month: summary: 本月 value: month year: summary: 今年 value: year title: Upload Time - name: sort_by in: query description: 排序方式 | Sort by for Shorts required: false schema: anyOf: - $ref: '#/components/schemas/YouTubeSearchSortAPI' - type: 'null' description: 排序方式 | Sort by for Shorts examples: relevance: summary: 相关性 value: relevance upload_date: summary: 上传日期 value: upload_date view_count: summary: 观看次数 value: view_count rating: summary: 评分 value: rating title: Sort By - name: continuation_token in: query description: 翻页令牌/Pagination token required: false example: '' schema: anyOf: - type: string - type: 'null' description: 翻页令牌/Pagination token title: Continuation Token - name: filter_mixed_content in: query description: >- 是否过滤混合内容（长视频），默认True / Filter mixed content (long videos), default True required: false example: 'true' schema: type: boolean description: >- 是否过滤混合内容（长视频），默认True / Filter mixed content (long videos), default True default: true title: Filter Mixed Content responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ResponseModel' headers: {} x-apifox-name: OK '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' headers: {} x-apifox-name: Unprocessable Entity security: - HTTPBearer: [] x-apifox: schemeGroups: - id: FenCmggbUX6CsTgnkXo5O schemeIds: - HTTPBearer required: true use: id: FenCmggbUX6CsTgnkXo5O scopes: FenCmggbUX6CsTgnkXo5O: HTTPBearer: [] x-apifox-folder: YouTube-Web-V2-API x-apifox-status: released x-run-in-apifox: https://app.apifox.com/web/project/4705614/apis/api-419083086-run components: schemas: YouTubeUploadTimeAPI: type: string enum: - hour - today - week - month - year title: YouTubeUploadTimeAPI description: YouTube上传时间过滤 - API显示版本 x-apifox-folder: '' YouTubeSearchSortAPI: type: string enum: - relevance - upload_date - view_count - rating title: YouTubeSearchSortAPI description: YouTube搜索排序方式 - API显示版本 x-apifox-folder: '' ResponseModel: properties: code: type: integer title: Code description: HTTP status code | HTTP状态码 default: 200 request_id: anyOf: - type: string - type: 'null' title: Request Id description: Unique request identifier | 唯一请求标识符 message: type: string title: Message description: Response message (EN-US) | 响应消息 (English) default: Request successful. This request will incur a charge. message_zh: type: string title: Message Zh description: Response message (ZH-CN) | 响应消息 (中文) default: 请求成功，本次请求将被计费。 support: type: string title: Support description: Support message | 支持消息 default: 'Discord: https://discord.gg/aMEAS8Xsvz' time: type: string title: Time description: The time the response was generated | 生成响应的时间 time_stamp: type: integer title: Time Stamp description: The timestamp the response was generated | 生成响应的时间戳 time_zone: type: string title: Time Zone description: The timezone of the response time | 响应时间的时区 default: America/Los_Angeles docs: anyOf: - type: string - type: 'null' title: Docs description: >- Link to the API Swagger documentation for this endpoint | 此端点的 API Swagger 文档链接 cache_message: anyOf: - type: string - type: 'null' title: Cache Message description: Cache message (EN-US) | 缓存消息 (English) default: >- This response is cached and accessible via the URL below for 24 hours at no extra cost. The cache is for request tracing only — it doesn't affect the API's data freshness and won't be returned through the API again. cache_message_zh: anyOf: - type: string - type: 'null' title: Cache Message Zh description: Cache message (ZH-CN) | 缓存消息 (中文) default: >- 本次响应已缓存，可通过下方 URL 直接查看，有效期 24 小时，访问缓存链接无额外费用。缓存仅用于请求溯源，不影响接口数据的时效性，也不会再次通过接口返回。 cache_url: anyOf: - type: string - type: 'null' title: Cache Url description: The URL to access the cached result | 访问缓存结果的 URL router: type: string title: Router description: The endpoint that generated this response | 生成此响应的端点 default: '' params: type: string data: anyOf: - type: string - type: 'null' title: Data description: The response data | 响应数据 type: object title: ResponseModel x-apifox-orders: - code - request_id - message - message_zh - support - time - time_stamp - time_zone - docs - cache_message - cache_message_zh - cache_url - router - params - data x-apifox-ignore-properties: [] x-apifox-folder: '' HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError x-apifox-orders: - detail x-apifox-ignore-properties: [] x-apifox-folder: '' ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError x-apifox-orders: - loc - msg - type x-apifox-ignore-properties: [] x-apifox-folder: '' securitySchemes: HTTPBearer: type: bearer description: > ---- #### API Token Introduction: ##### Method 1: Use API Token in the Request Header (Recommended) - **Header**: `Authorization` - **Format**: `Bearer {token}` - **Example**: `{"Authorization": "Bearer your_token"}` - **Swagger UI**: Click on the `Authorize` button in the upper right corner of the page to enter the API token directly without the `Bearer` keyword. ##### Method 2: Use API Token in the Cookie (Not Recommended, Use Only When Method 1 is Unavailable) - **Cookie**: `Authorization` - **Format**: `Bearer {token}` - **Example**: `Authorization=Bearer your_token` #### Get API Token: 1. Register and log in to your account on the TikHub website. 2. Go to the user center, click on the API token menu, and create an API token. 3. Copy and use the API token in the request header. 4. Keep your API token confidential and use it only in the request header. ---- #### API令牌简介: ##### 方法一：在请求头中使用API令牌（推荐） - **请求头**: `Authorization` - **格式**: `Bearer {token}` - **示例**: `{"Authorization": "Bearer your_token"}` - **Swagger UI**: 点击页面右上角的`Authorize`按钮，直接输入API令牌，不需要`Bearer`关键字。 ##### 方法二：在Cookie中使用API令牌（不推荐，仅在无法使用方法一时使用） - **Cookie**: `Authorization` - **格式**: `Bearer {token}` - **示例**: `Authorization=Bearer your_token` #### 获取API令牌: 1. 在TikHub网站注册并登录账户。 2. 进入用户中心，点击API令牌菜单，创建API令牌。 3. 复制并在请求头中使用API令牌。 4. 保密您的API令牌，仅在请求头中使用。 scheme: bearer servers: - url: https://api.tikhub.io description: Production Environment security: [] ```