> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube 搜索 API

> 搜索 YouTube，返回匹配的视频、频道和播放列表。

搜索 YouTube，返回匹配的视频、频道和播放列表。需设置 `engine=youtube` 并在 `q` 中传入查询词；两者均为必填。可选地按国家（`gl`）和界面语言（`hl`）收窄，或在 `sp` 中传入 YouTube 筛选 token 以实现分页和上传日期、时长、结果类型等高级筛选。适合用于查找某个话题的视频内容、跟踪某频道的近期上传，或评估某主题的视频覆盖度。

注意：该接口通过 AIsa 映射路径 `/apis/v1/youtube/search` 提供服务；上游提供商的原生路径并未直接挂载。

<Note>
  **第一次用？** 把任意 MCP 客户端指向 `https://mcp.aisa.one/mcp` —— Claude Code、
  Codex、Cursor、VS Code 都可以。鉴权走 OAuth：客户端打开浏览器，你点一次
  Allow，不需要粘贴任何 key。各客户端的具体命令和每次调用的价格见
  [aisa.one/zh-cn/mcp](https://aisa.one/zh-cn/mcp#connect)。
</Note>

[在你的 agent 里把这个端点跑起来 →](https://aisa.one/mcp?from=/zh/api-reference/search/get_youtube-search)


## OpenAPI

````yaml openapi/zh/youte-search.json GET /youtube/search
openapi: 3.0.3
info:
  title: YouTube Search API
  description: SearchApi.io YouTube 搜索端点
  version: 1.0.0
servers:
  - url: https://api.aisa.one/apis/v1
    description: YouTube Search API Server
security:
  - bearerAuth: []
paths:
  /youtube/search:
    get:
      tags:
        - YouTube Search
      summary: YouTube 搜索
      description: >-
        搜索 YouTube，返回匹配的视频、频道和播放列表。需设置 `engine=youtube` 并在 `q`
        中传入查询词；两者均为必填。可选地按国家（`gl`）和界面语言（`hl`）收窄，或在 `sp` 中传入 YouTube 筛选 token
        以实现分页和上传日期、时长、结果类型等高级筛选。适合用于查找某个话题的视频内容、跟踪某频道的近期上传，或评估某主题的视频覆盖度。注意：该接口通过
        AIsa 映射路径 `/apis/v1/youtube/search` 提供服务；上游提供商的原生路径并未直接挂载。
      operationId: get_youtube_search
      parameters:
        - name: engine
          in: query
          required: true
          schema:
            type: string
            enum:
              - youtube
          description: SearchApi 引擎标识符。此 YouTube 端点使用 `youtube`。
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: 搜索查询。运行时和上游 SearchApi 必填。
        - name: sp
          in: query
          required: false
          schema:
            type: string
          description: YouTube 筛选 token（分页或高级筛选）
        - name: gl
          in: query
          required: false
          schema:
            type: string
          description: 国家/地区代码（例如 us、jp）
        - name: hl
          in: query
          required: false
          schema:
            type: string
          description: 界面语言
      responses:
        '200':
          description: YouTube 搜索成功响应
          content:
            application/json:
              schema:
                type: object
                description: SearchApi 通过 AIsa 封装器返回的 YouTube 搜索结果载荷。
                additionalProperties: true
                properties:
                  search_metadata:
                    type: object
                    additionalProperties: true
                    properties:
                      id:
                        type: string
                      status:
                        type: string
                      created_at:
                        type: string
                      request_time_taken:
                        type: number
                      parsing_time_taken:
                        type: number
                      total_time_taken:
                        type: number
                      request_url:
                        type: string
                      html_url:
                        type: string
                      json_url:
                        type: string
                  search_parameters:
                    type: object
                    additionalProperties: true
                  search_information:
                    type: object
                    additionalProperties: true
                    properties:
                      total_results:
                        type: integer
                  videos:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                      properties:
                        position:
                          type: integer
                        id:
                          type: string
                        title:
                          type: string
                        link:
                          type: string
                        description:
                          type: string
                        thumbnail:
                          type: string
                        published_time:
                          type: string
                        length:
                          type: string
                        views:
                          oneOf:
                            - type: integer
                            - type: string
                        channel:
                          type: object
                          additionalProperties: true
                        is_live:
                          type: boolean
                        badges:
                          type: array
                          items:
                            type: string
                  channels:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                      properties:
                        position:
                          type: integer
                        id:
                          type: string
                        title:
                          type: string
                        link:
                          type: string
                        description:
                          type: string
                        thumbnail:
                          type: string
                        subscribers:
                          type: string
                  shorts:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                      properties:
                        position:
                          type: integer
                        section_title:
                          type: string
                        items:
                          type: array
                          items:
                            type: object
                            additionalProperties: true
                  sections:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                      properties:
                        position:
                          type: integer
                        section_title:
                          type: string
                        items:
                          type: array
                          items:
                            type: object
                            additionalProperties: true
                  playlists:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  ads:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  pagination:
                    type: object
                    additionalProperties: true
                    properties:
                      next_page_token:
                        type: string
        '400':
          description: 请求参数无效
        '401':
          description: 未授权 / API 密钥无效
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.