YouTube

通过托管的 OAuth 身份验证访问 YouTube Data API v3。搜索视频、管理播放列表、获取频道信息，以及与评论和订阅功能进行交互。

快速开始

# 搜索视频
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/{原生API路径}

将{原生API路径}替换为实际的 YouTube Data API 端点路径。网关会将请求代理到www.googleapis.com并自动注入您的 OAuth 令牌。

身份验证

所有请求都要求在 Authorization 头部中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的 API 密钥设置为MATON_API_KEY：

export MATON_API_KEY="您的API密钥"

获取您的 API 密钥

1. 请登录或在以下地址创建账户：maton.ai
2. 前往maton.ai/settings
3. 复制您的 API 密钥

连接管理

请在以下网址管理您的 Google OAuth 连接https://ctrl.maton.ai。

列出连接

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

创建连接

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

获取连接

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

响应：

{
  "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 授权。

删除连接

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请求头指定要使用哪一个：

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 参考

搜索

搜索视频、频道或播放列表

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分钟），中等（4-20分钟），长（大于20分钟）
• pageToken- 分页令牌

示例：

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"

响应：

{
  "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": "机器学习教程",
        "description": "学习机器学习基础...",
        "thumbnails": {
          "default": {"url": "https://i.ytimg.com/vi/abc123xyz/default.jpg"}
        },
        "channelTitle": "科技频道"
      }
    }
  ]
}

视频

获取视频详情

GET /youtube/youtube/v3/videos?part=snippet,statistics,contentDetails&id={videoId}

可用部分：

• snippet- 标题、描述、缩略图、频道信息
• statistics- 观看次数、点赞数、评论数
• contentDetails- 时长、尺寸、清晰度
• 状态- 上传状态、隐私状态
• 播放器- 嵌入播放器 HTML

示例：

curl -s -X GET "https://gateway.maton.ai/youtube/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ" -H "Authorization: Bearer $MATON_API_KEY"

获取我的视频（已上传）

GET /youtube/youtube/v3/search?part=snippet&forMine=true&type=video&maxResults=25

评价视频（点赞/点踩）

POST /youtube/youtube/v3/videos/rate?id={videoId}&rating=like

评分值：点赞,点踩,无

获取热门视频

GET /youtube/youtube/v3/videos?part=snippet,statistics&chart=mostPopular&regionCode=US&maxResults=10

获取视频分类

GET /youtube/youtube/v3/videoCategories?part=snippet&regionCode=US

频道

获取频道详情

GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&id={channelId}

获取我的频道

GET /youtube/youtube/v3/channels?part=snippet,statistics,contentDetails&mine=true

响应：

{
  "items": [
    {
      "id": "UCxyz123",
      "snippet": {
        "title": "我的频道",
        "description": "频道描述",
        "customUrl": "@mychannel",
        "publishedAt": "2020-01-01T00:00:00Z",
        "thumbnails": {...}
      },
      "statistics": {
        "viewCount": "1000000",
        "subscriberCount": "50000",
        "videoCount": "100"
      },
      "contentDetails": {
        "relatedPlaylists": {
          "uploads": "UUxyz123"
        }
      }
    }
  ]
}

通过用户名获取频道

GET /youtube/youtube/v3/channels?part=snippet,statistics&forUsername={username}

播放列表

列出我的播放列表

GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&mine=true&maxResults=25

获取播放列表

GET /youtube/youtube/v3/playlists?part=snippet,contentDetails&id={playlistId}

创建播放列表

POST /youtube/youtube/v3/playlists?part=snippet,status
Content-Type: application/json

{
  "snippet": {
    "title": "我的新播放列表",
    "description": "视频合集",
    "defaultLanguage": "en"
  },
  "status": {
    "privacyStatus": "private"
  }
}

隐私状态值：公开、私密、不公开

更新播放列表

PUT /youtube/youtube/v3/playlists?part=snippet,status
Content-Type: application/json

{
  "id": "PLxyz123",
  "snippet": {
    "title": "更新后的播放列表标题",
    "description": "更新后的描述"
  },
  "status": {
    "privacyStatus": "public"
  }
}

删除播放列表

DELETE /youtube/youtube/v3/playlists?id={playlistId}

播放列表项目

列出播放列表项目

GET /youtube/youtube/v3/playlistItems?part=snippet,contentDetails&playlistId={playlistId}&maxResults=50

添加视频到播放列表

POST /youtube/youtube/v3/playlistItems?part=snippet
Content-Type: application/json

{
  "snippet": {
    "playlistId": "PLxyz123",
    "resourceId": {
      "kind": "youtube#video",
      "videoId": "abc123xyz"
    },
    "position": 0
  }
}

从播放列表中移除

DELETE /youtube/youtube/v3/playlistItems?id={playlistItemId}

订阅

列出我的订阅

GET /youtube/youtube/v3/subscriptions?part=snippet&mine=true&maxResults=50

检查对频道的订阅状态

GET /youtube/youtube/v3/subscriptions?part=snippet&mine=true&forChannelId={channelId}

订阅频道

POST /youtube/youtube/v3/subscriptions?part=snippet
Content-Type: application/json

{
  "snippet": {
    "resourceId": {
      "kind": "youtube#channel",
      "channelId": "UCxyz123"
    }
  }
}

取消订阅

DELETE /youtube/youtube/v3/subscriptions?id={subscriptionId}

评论

列出视频评论

GET /youtube/youtube/v3/commentThreads?part=snippet,replies&videoId={videoId}&maxResults=100

为视频添加评论

POST /youtube/youtube/v3/commentThreads?part=snippet
Content-Type: application/json

{
  "snippet": {
    "videoId": "abc123xyz",
    "topLevelComment": {
      "snippet": {
        "textOriginal": "视频很棒！"
      }
    }
  }
}

回复评论

POST /youtube/youtube/v3/comments?part=snippet
Content-Type: application/json

{
  "snippet": {
    "parentId": "comment123",
    "textOriginal": "感谢您的评论！"
  }
}

删除评论

DELETE /youtube/youtube/v3/comments?id={commentId}

代码示例

JavaScript

const headers = {
  'Authorization': `Bearer ${process.env.MATON_API_KEY}`
};

// 搜索视频
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());

// 获取视频详情
const video = await fetch(
  'https://gateway.maton.ai/youtube/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ',
  { headers }
).then(r => r.json());

// 创建播放列表
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: '我的播放列表', description: '我喜欢的视频' },
      status: { privacyStatus: 'private' }
    })
  }
);

Python

import os
import requests

headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}

# 搜索视频
results = requests.get(
    'https://gateway.maton.ai/youtube/youtube/v3/search',
    headers=headers,
    params={'part': 'snippet', 'q': 'tutorial', 'type': 'video', 'maxResults': 10}
).json()

# 获取视频详情
video = requests.get(
    'https://gateway.maton.ai/youtube/youtube/v3/videos',
    headers=headers,
    params={'part': 'snippet,statistics', 'id': 'dQw4w9WgXcQ'}
).json()

# 创建播放列表
response = requests.post(
    'https://gateway.maton.ai/youtube/youtube/v3/playlists?part=snippet,status',
    headers=headers,
    json={
        'snippet': {'title': '我的播放列表', 'description': '我喜欢的视频'},
        'status': {'privacyStatus': 'private'}
    }
)

注意事项

• 视频ID为11个字符（例如，dQw4w9WgXcQ）
• 频道ID以UC开头（例如，UCxyz123）
• 播放列表ID以PL（用户）或UU（上传）
• 使用pageToken用于对大型结果集进行分页
• 这个部分参数是必需的，用于决定返回什么数据
• 配额消耗因端点而异——搜索操作消耗高（100单位），读取操作消耗低（1单位）
• 某些写入操作需要进行频道验证
• 重要提示：使用curl命令时，如果URL包含方括号（fields[]、sort[]、records[]），请使用curl -g以禁用通配符解析
• 重要提示：当将curl输出通过管道传递给jq或其他命令时，环境变量如$MATON_API_KEY在某些shell环境中可能无法正确展开。通过管道传输时，您可能会收到“无效的API密钥”错误。

错误处理

故障排除：API密钥问题

1. 请检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

2. 通过列出连接来验证API密钥是否有效：

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数据API概览
• 搜索
• 视频
• 频道
• 播放列表
• 播放列表项目
• 订阅
• 评论
• 配额计算器
• Maton社区
• Maton支持