YouTube API
YouTube API 允许您通过单一统一接口搜索 YouTube 并获取视频元数据。每个端点返回结构化的 JSON 并附带积分使用跟踪。
端点
| 端点 | 描述 |
|---|---|
POST /api/v1/youtube/search | 使用过滤器搜索 YouTube（日期、时长、类型、画质） |
POST /api/v1/youtube/metadata | 获取视频的结构化元数据（观看数、点赞数、标签、描述） |
认证
| 请求头 | 值 | 必填 |
|---|---|---|
Authorization | Bearer YOUR_API_KEY | 是 |
Content-Type | application/json | 是 |
YouTube 搜索
Bash
POST https://api.scavio.dev/api/v1/youtube/search搜索 YouTube 并获取结构化结果。支持按上传日期、时长、结果类型、视频画质等进行过滤。
请求体
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
search | string | -- | 必填。 搜索查询（1-500个字符）。 |
upload_date | string | -- | 按上传日期过滤。可选值: last_hour, today, this_week, this_month, this_year |
type | string | -- | 按结果类型过滤。可选值: video, channel, playlist |
duration | string | -- | 按视频时长过滤。可选值: short（4分钟以下）, medium（4-20分钟）, long（20分钟以上） |
sort_by | string | relevance | 排序方式。可选值: relevance, date, view_count, rating |
hd | boolean | false | 仅限高清视频 |
4k | boolean | false | 仅限4K视频 |
subtitles | boolean | false | 仅限带字幕的视频 |
creative_commons | boolean | false | 仅限 Creative Commons 许可的视频 |
live | boolean | false | 仅限直播 |
hdr | boolean | false | 仅限 HDR 视频 |
360 | boolean | false | 仅限360度视频 |
3d | boolean | false | 仅限3D视频 |
location | boolean | false | 仅限带位置元数据的视频 |
vr180 | boolean | false | 仅限 VR180 视频 |
示例
curl -X POST 'https://api.scavio.dev/api/v1/youtube/search' \
-H 'Authorization: Bearer sk_live_your_key' \
-H 'Content-Type: application/json' \
-d '{
"search": "langchain tutorial",
"type": "video",
"duration": "medium",
"sort_by": "view_count",
"upload_date": "this_year"
}'响应示例
JSON
{
"data": {
"results": [
{
"videoId": "sVcwVQRHIc8",
"title": { "runs": [{ "text": "Learn RAG From Scratch - Python AI Tutorial" }] },
"longBylineText": { "runs": [{ "text": "freeCodeCamp.org" }] },
"publishedTimeText": { "simpleText": "1 year ago" },
"lengthText": { "simpleText": "2:33:11" },
"viewCountText": { "simpleText": "1,258,310 views" },
"thumbnail": { "thumbnails": [{ "url": "https://i.ytimg.com/vi/sVcwVQRHIc8/hq720.jpg", "width": 360, "height": 202 }] }
}
],
"search": "langchain tutorial"
},
"response_time": 1230,
"credits_used": 1,
"credits_remaining": 999
}视频元数据
Bash
POST https://api.scavio.dev/api/v1/youtube/metadata获取 YouTube 视频的结构化元数据，包括标题、描述、观看数、点赞数、评论数、标签、缩略图、上传日期、频道信息和可用格式。
请求体
| 参数 | 类型 | 描述 |
|---|---|---|
video_id | string | 必填。 YouTube 视频 ID（例如 dQw4w9WgXcQ）。 |
示例
curl -X POST 'https://api.scavio.dev/api/v1/youtube/metadata' \
-H 'Authorization: Bearer sk_live_your_key' \
-H 'Content-Type: application/json' \
-d '{"video_id": "sVcwVQRHIc8"}'响应示例
JSON
{
"data": {
"title": "Learn RAG From Scratch - Python AI Tutorial",
"description": "Learn how to implement RAG from scratch...",
"upload_date": 20240417,
"duration": 9191,
"view_count": 1258310,
"like_count": 23211,
"comment_count": 295,
"categories": ["Education"],
"tags": ["rag", "langchain", "python", "llm"],
"channel_id": "UC8butISFwT-Wl7EV0hUK0BQ",
"channel_url": "https://www.youtube.com/channel/UC8butISFwT-Wl7EV0hUK0BQ",
"uploader": "freeCodeCamp.org",
"uploader_id": "@freecodecamp",
"uploader_url": "https://www.youtube.com/@freecodecamp",
"video_id": "sVcwVQRHIc8",
"is_live": false,
"age_limit": 0,
"thumbnails": [
{
"url": "https://i.ytimg.com/vi/sVcwVQRHIc8/maxresdefault.jpg",
"width": 1280,
"height": 720
}
],
"formats": []
},
"response_time": 890,
"credits_used": 1,
"credits_remaining": 998
}响应格式
所有 YouTube 端点返回一致的响应包装:
| 字段 | 类型 | 描述 |
|---|---|---|
data | object | null | 响应数据载荷。结构取决于端点。搜索返回 {results, search}；元数据返回视频对象。如果上游请求失败则为 null。 |
response_time | number | 服务端响应时间（毫秒） |
credits_used | number | 此请求消耗的积分数 |
credits_remaining | number | 当前计费周期内剩余积分 |
错误响应
| 状态码 | 描述 |
|---|---|
401 | 未授权 -- API 密钥缺失或无效 |
429 | 超出您套餐的速率或用量限制 |
502 | 上游错误 -- 请短暂等待后重试 |
503 | 上游不可用 -- 请稍后重试 |
参阅 错误参考 获取完整错误代码及重试最佳实践。
相关文档
- 快速开始 -- 获取 API 密钥并发起第一个请求
- Google Search API -- 搜索 Google 并获取结构化 SERP 数据
- Amazon API -- 搜索商品并通过 ASIN 获取详情
- 速率限制 -- 各套餐等级的限制
- 错误 -- 错误代码及处理方式