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结束。只对完成的请求计费。