内容
<div align="center">
<img src="https://github.com/vibheksoni/youtube-ai/raw/main/assets/YTAI.png" alt="YTAI" width="320">
# YTAI：Python YouTube SDK、CLI 及 MCP 服务器
搜索、元数据、字幕、评论、频道和下载 — 无需 API 密钥。
[](https://pypi.org/project/youtube-ai/)
[](https://pypi.org/project/youtube-ai/)
[](LICENSE)
[](https://github.com/vibheksoni/youtube-ai)
[](https://pypi.org/project/youtube-ai/)
`curl_cffi` 用于 TLS 伪装 · `FastMCP` 用于代理工具 · `FastAPI` 用于 HTTP API · `Rich` 用于 CLI
</div>
> YTAI 是一个独立项目。它与 YouTube 或 Google 无关，也不被其认可。请根据适用的条款、版权法和当地法规使用。
## 目录
- [功能](#功能)
- [安装](#安装)
- [快速开始](#快速开始)
- [下载](#下载)
- [MCP 服务器](#mcp-服务器)
- [FastAPI 服务器](#fastapi-服务器)
- [文档](#文档)
- [测试](#测试)
- [限制](#限制)
- [致谢](#致谢)
## 功能
- 使用筛选器和分页搜索视频、频道和播放列表
- 检索元数据、点赞数、字幕、相关视频和评论
- 获取带有语言选择和 XML 备用的带时间戳的字幕
- 查看频道、最近上传的视频和热门视频
- 下载带有音频、仅视频、仅音频或指定时间范围的完整视频
- 使用范围传输和每个块重试恢复中断的下载
- 在 SQLite 中缓存响应，并使用特定于操作的 TTL
- 使用 Python SDK、Rich 支持的 `ytai` CLI、九个只读 MCP 工具或 FastAPI 服务
## 安装
要求：
- Python 3.10 或更新版本
- 不需要单独安装 FFmpeg 进行下载；YTAI 通过 `imageio-ffmpeg` 捆绑 FFmpeg
从 PyPI 安装：
```bash
pip install youtube-ai
```
或从源代码克隆并安装：
```bash
git clone https://github.com/vibheksoni/youtube-ai.git
cd youtube-ai
pip install -e .
```
运行测试时安装开发依赖项：
```bash
pip install -e ".[dev]"
```
FFmpeg 在安装 YTAI 时会自动在 Windows、macOS 和 Linux 上捆绑。如果您更喜欢系统构建，当 `ffmpeg` 在 `PATH` 中时，它将被使用。要固定二进制文件路径，请将 `YTAI_FFMPEG_PATH` 设置为其完整路径：
```powershell
$env:YTAI_FFMPEG_PATH = "C:\tools\ffmpeg\bin\ffmpeg.exe"
```
`YTAI_API_KEY` 是在无法获取实时配置时可选的离线备用方案。它从环境中读取，并且永远不会存储在仓库中。
有关环境设置和首次运行的指南，请继续阅读[入门](docs/getting-started.md)。
## 快速开始
将 `YouTubeClient` 用作上下文管理器，以便干净地关闭其 HTTP 会话：
```python
from youtube_ai import YouTubeClient
with YouTubeClient() as client:
results = client.search("python tutorial", limit=5, filter_type="video")
for item in results["results"]:
print(item["title"], item["url"])
video = client.get_video("dQw4w9WgXcQ")
print(video["details"]["title"])
print(video["details"]["likes"])
transcript = client.get_transcript("dQw4w9WgXcQ", language_codes=("en",))
for segment in transcript["snippets"][:5]:
print(f"{segment['start']:.1f}s: {segment['text']}")
```
常见的 CLI 命令：
```bash
ytai search "python tutorial" --limit 10 --filter video
ytai video dQw4w9WgXcQ
ytai transcript dQw4w9WgXcQ --lang en
ytai comments dQw4w9WgXcQ --limit 20
```
请参阅 [Python API 参考](docs/api-reference.md) 和 [CLI 参考](docs/cli-reference.md)，以获取完整的签名和命令。
## 下载
在下载前检查可用的质量、编解码器、流大小和模式：
```bash
ytai download-options dQw4w9WgXcQ
```
下载带有音频的完整视频：
```bash
ytai download dQw4w9WgXcQ --quality 720p --output ./downloads
```
仅视频、仅音频和剪辑是可选的：
```bash
ytai download dQw4w9WgXcQ --quality 1080p --video-only
ytai download dQw4w9WgXcQ --audio-only
ytai download dQw4w9WgXcQ --quality 360p --start 30 --end 90
```
SDK 还公开了 `VideoQuality`、`DownloadMode`、`get_download_options()` 和 `download_video()`。请参阅 [下载 API](docs/api-reference.md#download_video) 和 [下载示例](examples/download_video.py)。
## MCP 服务器
启动 FastMCP 服务器：
```bash
python mcp/server.py
```
它公开了九个只读工具，用于搜索、视频数据、字幕、流媒体格式、评论、频道和热门视频。媒体下载故意仅通过 SDK 和 CLI 提供。
请参阅 [MCP 服务器设置](docs/mcp-server.md)，获取客户端配置和工具参数。
## FastAPI 服务器
启动版本化 HTTP API：
```bash
ytai-api
```
Swagger UI 可在 `http://127.0.0.1:8000/docs` 访问。该 API 涵盖搜索、视频数据、字幕、评论、格式、下载选项、频道和热门视频。请参阅 [FastAPI 服务器指南](docs/api-server.md)，获取路由、curl 示例、配置、验证和部署指南。
## 文档
- [入门](docs/getting-started.md)：先决条件、安装和首次工作流
- [API 参考](docs/api-reference.md)：公共类、函数、枚举和返回形状
- [CLI 参考](docs/cli-reference.md)：每个 `ytai` 命令和选项
- [MCP 服务器](docs/mcp-server.md)：服务器设置、工具、参数和错误
- [FastAPI 服务器](docs/api-server.md)：HTTP 路由、OpenAPI 文档、配置和示例
- [示例](examples/)：可运行的搜索、元数据、字幕、评论、频道、下载和 MCP 脚本
## 测试
端到端套件调用真正的 YouTube InnerTube 和 Google Video 边界。它涵盖搜索、字幕、评论、频道、MCP 工具、CLI 命令、下载模式、剪辑、恢复范围和 ffmpeg 输出流。
```bash
pytest tests/test_e2e.py -v
```
## 限制
- 私有、仅限成员访问和大多数年龄受限的内容在未经身份验证的情况下不可用。
- InnerTube 端点和渲染器结构可能会在不通知的情况下更改。
- 频道上传目前返回可用的第一个页面。
- 自适应完整视频下载和剪辑使用捆绑的 FFmpeg 可执行文件（或配置时使用 `YTAI_FFMPEG_PATH`）。
- 目前不检索播放列表内容。
## 致谢
YTAI 承认这些公共项目作为协议细节、格式映射和实现思想的参考：
- [YouTube.js](https://github.com/LuanRT/YouTube.js)
- [innertube-go](https://github.com/raHULK777/innertube-go)
- [youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api)
- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
## 许可证
MIT，如 `pyproject.toml` 中声明。
