youtube
YouTube 数据 API 与托管 OAuth 集成。搜索视频、管理播放列表、访问频道数据以及与评论互动。当用户想要与 YouTube 互动时，请使用此技能。对于其他第三方应用程序，请使用 api-gateway 技能 (https://clawhub.ai/byungkyu/api-gateway)。
安装 / 下载方式
TotalClaw CLI推荐
totalclaw install totalclaw:totalclaw~youtube-api-skillcURL直接下载，无需登录
curl -fsSL https://skills.taituai.com/api/skills/totalclaw%3Atotalclaw~youtube-api-skill/file -o youtube-api-skill.md## 概述（中文）
YouTube 数据 API 与托管 OAuth 集成。搜索视频、管理播放列表、访问频道数据以及与评论互动。当用户想要与 YouTube 互动时，请使用此技能。对于其他第三方应用程序，请使用 api-gateway 技能 (https://clawhub.ai/byungkyu/api-gateway)。
## 原文
# YouTube
Access the YouTube Data API v3 with managed OAuth authentication. Search videos, manage playlists, access channel information, and interact with comments and subscriptions.
## Quick Start
```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
```
## Base URL
```
https://gateway.maton.ai/youtube/{native-api-path}
```
Replace `{native-api-path}` with the actual YouTube Data API endpoint path. The gateway proxies requests to `www.googleapis.com` and automatically injects your OAuth token.
## Authentication
All requests require the Maton API key in the Authorization header:
```
Authorization: Bearer $MATON_API_KEY
```
**Environment Variable:** Set your API key as `MATON_API_KEY`:
```bash
export MATON_API_KEY="YOUR_API_KEY"
```
### Getting Your API Key
1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key
## Connection Management
Manage your Google OAuth connections at `https://ctrl.maton.ai`.
### List Connections
```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
```
### Create Connection
```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
```
### Get Connection
```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
```
**Response:**
```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": {}
}
}
```
Open the returned `url` in a browser to complete OAuth authorization.
### Delete Connection
```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
```
### Specifying Connection
If you have multiple YouTube connections, specify which one to use with the `Maton-Connection` header:
```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
```
If omitted, the gateway uses the default (oldest) active connection.
## API Reference
### Search
#### Search Videos, Channels, or Playlists
```bash
GET /youtube/youtube/v3/search
```
Query parameters:
- `part` - Required: `snippet`
- `q` - Search query
- `type` - Filter by type: `video`, `channel`, `playlist`
- `maxResults` - Results per page (1-50, default 5)
- `order` - Sort order: `date`, `rating`, `relevance`, `title`, `viewCount`
- `publishedAfter` - Filter by publish date (RFC 3339)
- `publishedBefore` - Filter by publish date (RFC 3339)
- `channelId` - Filter by channel
- `videoDuration` - `short` (<4min), `medium` (4-20min), `long` (>20min)
- `pageToken` - Pagination token
**Example:**
```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"
```
**Response:**
```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"
}
}
]
}
```
### Videos
#### Get Video Details
```bash
GET /youtube/youtube/v3/videos?part=snippet,statistics,contentDetails&id={videoId}
```
Parts available:
- `snippet` - Title, description, thumbnails, channel info
- `statistics` - View count, likes, comments
- `contentDetails` - Duration, dimension, definition
- `status` - Upload status, privacy status
- `player` - Embedded player HTML
**Example:**
```bash
curl -s -X GET "https://gateway.maton.ai/youtube/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ" -H "Authorization: Bearer $MATON_API_KEY"
```
#### Get My Videos (Uploaded)
```bash
GET /youtube/youtube/v3/search?part=snippet&forMine=true&type=video&maxResults=25
```
#### Rate Video (Like/Dislike)
```bash
POST /youtube/youtube/v3/videos/rate?id={videoId}&rating=like
```
Rating values: `like`, `dislike`, `none`
#### Get Trending Videos
```bash
GET /youtube/youtube/v3/videos?part=snippet,statistics&chart=mostPopular®ionCode=US&maxResults=10
```
#### Get Video Categories
```bash
GET /youtube/youtube/v3/videoCategories?part=snippet®ionCode=US
```
### Channels
#### Get Channel Details
```bash
GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&id={channelId}
```
#### Get My Channel
```bash
GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&mine=true
```
**Response:**
```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"
}
}
}
]
}
```
#### Get Channel by Username
```bash
GET /youtube/youtube/v3/channels?part=snippet,statistics&forUsername={username}
```
### Playlists
#### List My Playlists
```bash
GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&mine=true&maxResults=25
```
#### Get Playlist
```bash
GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&id={playlistId}
```
#### Create Playlist
```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"
}
}
```
Privacy values: `public`, `private`, `unlisted`
#### Update Playlist
```bas