跳转到主要内容
通过异步任务 API 以 JSON 读取公开的 YouTube 数据。发送 taskType SOCIAL 并设置 platform youtube,用 action 选择要读取的内容。每次完成的请求消耗 0.5 积分。

请求

提交任务后,轮询 GET /v1/async/task/{id} 或通过 webhook 接收。参见异步任务。

操作

videoId 接受视频 ID 或 YouTube 视频 URL(观看页、youtu.be、Shorts 或嵌入)。channel 接受频道 ID(UC...)、@handle 或频道 URL。

参数

search 和 recent:
  • query:必填。搜索查询。
  • limit:可选整数,范围 1-50,默认 10。
  • type:video(默认)、all、shorts、channel、playlist 或 movie。
  • order:relevance(默认)、viewCount、date 或 rating。date 与 recent 一样按上传时间从新到旧排列。rating 将 YouTube 播放量最高的结果按点赞数排序。channel 和 playlist 搜索接受 relevance 或 viewCount。
  • publishedAfter:ISO 8601 时间,例如 2026-11-01T00:00:00Z。返回此时间之后发布的视频。
  • videoDuration:short(3 分钟以内)、medium(3-20 分钟)或 long(超过 20 分钟)。
  • features:live、4k、hd、subtitles、creative_commons、360、vr180、3d、hdr、location 和 purchased 中的任意值,以数组或逗号分隔的字符串发送。
  • exactSpelling:设为 true 时按原样搜索查询,不经 YouTube 拼写纠正。
  • pageToken:上一页的 nextPageToken。不带 publishedAfter、按 relevance 或 viewCount 排序的视频搜索会返回该值,每一页都会跳过之前各页已返回的视频。
  • regionCode 和 languageCode:搜索所用的 YouTube 地区(US、KR、JP)和界面语言(en、ko、ja)。
comments:
  • limit:可选整数,范围 1-500,默认 100。回复计入数量。
  • order:relevance(默认,YouTube 的热门评论)或 time(从新到旧)。
  • includeReplies:可选,默认 true。
channel_videos:
  • tab:videos(默认)、shorts 或 streams。
  • sort:latest(默认)、popular 或 oldest。
  • limit:可选整数,范围 1-50,默认 20。
transcript:
  • languages:按优先顺序排列的字幕语言,例如 ["en", "ko"]。未设置时依次读取视频的默认字幕、英文字幕和第一条字幕轨。
  • isGenerated:true 只读取自动生成的字幕,false 只读取上传者的字幕。
  • trackName:要读取的字幕轨名称。
  • translateTo:语言代码。YouTube 会把字幕翻译成该语言。
  • maxSegments:可选整数,范围 1-5,000,默认 2,000。

响应示例

结果字段

  • 每个响应都会原样返回 platform 和 action。列表带有 returnedCount。
  • search 和 recent 返回 videos。每个视频包含 position、videoId、url、title、description,频道的 channelId、channelTitle、channelHandle、channelUrl、channelThumbnail 和 channelIsVerified,以及 publishedAt、publishedTimeText、duration(ISO 8601)、durationSeconds、viewCount、likeCount、category、thumbnails、richThumbnail(动态预览)、badges 和 isFamilySafe。电影还会加上 movie,包含海报、类型、年份、演员和导演。
  • 搜索还会返回结果页显示的 channels、playlists、shorts 和 shelves,以及 totalResults(YouTube 的估计值);YouTube 纠正查询时会返回 didYouMean 或 showingResultsFor。
  • video 增加 tags、commentCount、subscriberCount、hasCaptions、chapters、mostReplayed、music、descriptionLinks 和 relatedVideos。上传者的章节排在前面,自动章节带有 autoGenerated: true。
  • comments 返回 comments,每条评论包含 commentId、parentId(顶层评论为 null)、text、authorDisplayName、authorChannelId、authorProfileImageUrl、authorIsVerified、authorIsChannelOwner、isPinned、isHearted、likeCount、replyCount、publishedAt 和 updatedAt。totalCount 是 YouTube 显示的数量,topLevelCount 和 replyCount 是 returnedCount 的拆分。
  • channel 返回 channelId、title、handle、description、country、publishedAt、subscriberCount、videoCount、viewCount、isVerified、keywords、links、thumbnails、bannerUrl、rssUrl 和 uploadsPlaylistId。
  • channel_videos 按 sort 的顺序返回 videos,并附带频道的 channelId 和 channelTitle。
  • transcript 返回字幕 text、带时间的 segments(start 和 duration,单位为秒)、读取的 language 和 availableLanguages。truncated: true 表示字幕在 maxSegments 处被截断。
  • 隐藏点赞数的视频带有 likesHidden: true,关闭评论的视频带有 commentsDisabled: true。会员专属视频带有 membersOnly: true,且没有 viewCount。
  • 不存在的视频、频道或字幕轨,或需要登录观看的内容(例如年龄限制视频),会使任务以 PAGE_UNAVAILABLE 结束。不能组合使用的参数会使任务以 BAD_PAYLOAD 结束。只对完成的请求计费。

相关