介绍
# YouTube
通过受管理的 OAuth 身份验证访问 YouTube Data API v3。搜索视频、管理播放列表、获取频道信息，并与评论和订阅进行互动。
## 快速开始
```bash # Search for videos python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/youtube/youtube/v3/search?part=snippet&q=coding+tutorial&type=video&maxResults=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 基础 URL
``` https://gateway.maton.ai/youtube/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 YouTube Data API 端点路径。网关会将请求代理到 `www.googleapis.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization 请求头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取 API 密钥
1. 登录或在 [maton.ai](https://maton.ai) 创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Google OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=youtube&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'youtube'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "youtube", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 指定连接
如果您有多个 YouTube 连接，请使用 `Maton-Connection` 请求头指定使用哪一个：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/youtube/youtube/v3/channels?part=snippet&mine=true') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认的（最早的）活动连接。
## API 参考
### 搜索
#### 搜索视频、频道或播放列表
```bash GET /youtube/youtube/v3/search ```
查询参数： - `part` - 必需：`snippet` - `q` - 搜索查询 - `type` - 按类型过滤：`video`（视频）、`channel`（频道）、`playlist`（播放列表） - `maxResults` - 每页结果数（1-50，默认 5） - `order` - 排序顺序：`date`（日期）、`rating`（评分）、`relevance`（相关性）、`title`（标题）、`viewCount`（观看次数） - `publishedAfter` - 按发布日期过滤 (RFC 3339) - `publishedBefore` - 按发布日期过滤 (RFC 3339) - `channelId` - 按频道过滤 - `videoDuration` - `short`（<4分钟）、`medium`（4-20分钟）、`long`（>20分钟） - `pageToken` - 分页令牌
**示例：**
```bash curl -s -X GET "https://gateway.maton.ai/youtube/youtube/v3/search?part=snippet&q=machine+learning&type=video&maxResults=10&order=viewCount" -H "Authorization: Bearer $MATON_API_KEY" ```
**响应：** ```json { "kind": "youtube#searchListResponse", "nextPageToken": "CAUQAA", "pageInfo": { "totalResults": 1000000, "resultsPerPage": 10 }, "items": [ { "kind": "youtube#searchResult", "id": { "kind": "youtube#video", "videoId": "abc123xyz" }, "snippet": { "publishedAt": "2024-01-15T10:00:00Z", "channelId": "UCxyz123", "title": "Machine Learning Tutorial", "description": "Learn ML basics...", "thumbnails": { "default": {"url": "https://i.ytimg.com/vi/abc123xyz/default.jpg"} }, "channelTitle": "Tech Channel" } } ] } ```
### 视频
#### 获取视频详情
```bash GET /youtube/youtube/v3/videos?part=snippet,statistics,contentDetails&id={videoId} ```
可用部分： - `snippet` - 标题、描述、缩略图、频道信息 - `statistics` - 观看次数、点赞数、评论数 - `contentDetails` - 时长、尺寸、定义 - `status` - 上传状态、隐私状态 - `player` - 嵌入式播放器 HTML
**示例：**
```bash curl -s -X GET "https://gateway.maton.ai/youtube/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ" -H "Authorization: Bearer $MATON_API_KEY" ```
#### 获取我的视频（已上传）
```bash GET /youtube/youtube/v3/search?part=snippet&forMine=true&type=video&maxResults=25 ```
#### 对视频进行评分（喜欢/不喜欢）
```bash POST /youtube/youtube/v3/videos/rate?id={videoId}&rating=like ```
评分值：`like`（喜欢）、`dislike`（不喜欢）、`none`（无）
#### 获取热门视频
```bash GET /youtube/youtube/v3/videos?part=snippet,statistics&chart=mostPopular®ionCode=US&maxResults=10 ```
#### 获取视频类别
```bash GET /youtube/youtube/v3/videoCategories?part=snippet®ionCode=US ```
### 频道
#### 获取频道详情
```bash GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&id={channelId} ```
#### 获取我的频道
```bash GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&mine=true ```
**响应：** ```json { "items": [ { "id": "UCxyz123", "snippet": { "title": "My Channel", "description": "Channel description", "customUrl": "@mychannel", "publishedAt": "2020-01-01T00:00:00Z", "thumbnails": {...} }, "statistics": { "viewCount": "1000000", "subscriberCount": "50000", "videoCount": "100" }, "contentDetails": { "relatedPlaylists": { "uploads": "UUxyz123" } } } ] } ```
#### 通过用户名获取频道
```bash GET /youtube/youtube/v3/channels?part=snippet,statistics&forUsername={username} ```
### 播放列表
#### 列出我的播放列表
```bash GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&mine=true&maxResults=25 ```
#### 获取播放列表
```bash GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&id={playlistId} ```
#### 创建播放列表
```bash POST /youtube/youtube/v3/playlists?part=snippet,status Content-Type: application/json
{ "snippet": { "title": "My New Playlist", "description": "A collection of videos", "defaultLanguage": "en" }, "status": { "privacyStatus": "private" } } ```
隐私值：`public`（公开）、`private`（私密）、`unlisted`（不公开）
#### 更新播放列表
```bash PUT /youtube/youtube/v3/playlists?part=snippet,status Content-Type: application/json
{ "id": "PLxyz123", "snippet": { "title": "Updated Playlist Title", "description": "Updated description" }, "status": { "privacyStatus": "public" } } ```
#### 删除播放列表
```bash DELETE /youtube/youtube/v3/playlists?id={playlistId} ```
### 播放列表项
#### 列出播放列表项
```bash GET /youtube/youtube/v3/playlistItems?part=snippet,contentDetails&playlistId={playlistId}&maxResults=50 ```
#### 将视频添加到播放列表
```bash POST /youtube/youtube/v3/playlistItems?part=snippet Content-Type: application/json
{ "snippet": { "playlistId": "PLxyz123", "resourceId": { "kind": "youtube#video", "videoId": "abc123xyz" }, "position": 0 } } ```
#### 从播放列表中移除
```bash DELETE /youtube/youtube/v3/playlistItems?id={playlistItemId} ```
### 订阅
#### 列出我的订阅
```bash GET /youtube/youtube/v3/subscriptions?part=snippet&mine=true&maxResults=50 ```
#### 检查是否订阅频道
```bash GET /youtube/youtube/v3/subscriptions?part=snippet&mine=true&forChannelId={channelId} ```
#### 订阅频道
```bash POST /youtube/youtube/v3/subscriptions?part=snippet Content-Type: application/json
{ "snippet": { "resourceId": { "kind": "youtube#channel", "channelId": "UCxyz123" } } } ```
#### 取消订阅
```bash DELETE /youtube/youtube/v3/subscriptions?id={subscriptionId} ```
### 评论
#### 列出视频评论
```bash GET /youtube/youtube/v3/commentThreads?part=snippet,replies&videoId={videoId}&maxResults=100 ```
#### 为视频添加评论
```bash POST /youtube/youtube/v3/commentThreads?part=snippet Content-Type: application/json
{ "snippet": { "videoId": "abc123xyz", "topLevelComment": { "snippet": { "textOriginal": "Great video!" } } } } ```
#### 回复评论
```bash POST /youtube/youtube/v3/comments?part=snippet Content-Type: application/json
{ "snippet": { "parentId": "comment123", "textOriginal": "Thanks for your comment!" } } ```
#### 删除评论
```bash DELETE /youtube/youtube/v3/comments?id={commentId} ```
## 代码示例
### JavaScript
```javascript const headers = { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` };
// Search videos const results = await fetch( 'https://gateway.maton.ai/youtube/youtube/v3/search?part=snippet&q=tutorial&type=video&maxResults=10', { headers } ).then(r => r.json());
// Get video details const video = await fetch( 'https://gateway.maton.ai/youtube/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ', { headers } ).then(r => r.json());
// Create playlist await fetch( 'https://gateway.maton.ai/youtube/youtube/v3/playlists?part=snippet,status', { method: 'POST', headers: { ...headers, 'Content-Type': 'application/json' }, body: JSON.stringify({ snippet: { title: 'My Playlist', description: 'Videos I like' }, status: { privacyStatus: 'private' } }) } ); ```
### Python
```python import os import requests
headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
# Search videos results = requests.get( 'https://gateway.maton.ai/youtube/youtube/v3/search', headers=headers, params={'part': 'snippet', 'q': 'tutorial', 'type': 'video', 'maxResults': 10} ).json()
# Get video details video = requests.get( 'https://gateway.maton.ai/youtube/youtube/v3/videos', headers=headers, params={'part': 'snippet,statistics', 'id': 'dQw4w9WgXcQ'} ).json()
# Create playlist response = requests.post( 'https://gateway.maton.ai/youtube/youtube/v3/playlists?part=snippet,status', headers=headers, json={ 'snippet': {'title': 'My Playlist', 'description': 'Videos I like'}, 'status': {'privacyStatus': 'private'} } ) ```
## 注意事项
- 视频 ID 为 11 个字符（例如 `dQw4w9WgXcQ`） - 频道 ID 以 `UC` 开头（例如 `UCxyz123`） - 播放列表 ID 以 `PL`（用户）或 `UU`（上传内容）开头 - 使用 `pageToken` 对大型结果集进行分页 - `part` 参数是必需的，决定了返回的数据 - 配额成本因端点而异 - 搜索很昂贵（100 单元），读取很便宜（1 单元） - 某些写入操作需要频道验证 - 重要：使用 curl 命令时，如果 URL 包含括号（`fields[]`、`sort[]`、`records[]`），请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递到 `jq` 或其他命令时，在某些 shell 环境中，像 `$MATON_API_KEY` 这样的环境变量可能无法正确展开。您在进行管道传输时可能会收到“Invalid API key”错误。
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 YouTube 连接或请求无效 | | 401 | Maton API 密钥无效或缺失 | | 403 | 禁止访问 - 配额已超出或权限不足 | | 404 | 未找到视频、频道或播放列表 | | 429 | 速率受限（每个账户每秒 10 次请求）| | 4xx/5xx | 来自 YouTube API 的透传错误 |
### 故障排除：API 密钥问题
1. 检查 `MATON_API_KEY` 环境变量是否已设置：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 故障排除：应用名称无效
1. 确保您的 URL 路径以 `youtube` 开头。例如：
- 正确：`https://gateway.maton.ai/youtube/youtube/v3/search` - 错误：`https://gateway.maton.ai/v3/search`
## 资源
- [YouTube Data API 概述](https://developers.google.com/youtube/v3) - [搜索](https://developers.google.com/youtube/v3/docs/search/list) - [视频](https://developers.google.com/youtube/v3/docs/videos) - [频道](https://developers.google.com/youtube/v3/docs/channels) - [播放列表](https://developers.google.com/youtube/v3/docs/playlists) - [播放列表项](https://developers.google.com/youtube/v3/docs/playlistItems) - [订阅](https://developers.google.com/youtube/v3/docs/subscriptions) - [评论](https://developers.google.com/youtube/v3/docs/comments) - [配额计算器](https://developers.google.com/youtube/v3/determine_quota_cost) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])