# yt-dlp 的 Python API

可运行的 Python 示例，涵盖下载、元数据、AI 数据集及可续跑的批处理。

规范链接： https://flashdata.dev/zh/docs/guides/yt-dlp-python-api
FlashData 核查于 2026-11-13

- [开始使用Python](https://flashdata.dev/zh/docs/guides/yt-dlp-python-api/reference.md#first-call) — 安装并进行一个呼叫
- [查找最终文件](https://flashdata.dev/zh/docs/guides/yt-dlp-python-api/reference.md#completion) — 转移和处理后
- [拿起下载进程](https://flashdata.dev/zh/docs/guides/yt-dlp-python-api/reference.md#worker) — 可下载 .py
- [处理一个收藏](https://flashdata.dev/zh/docs/guides/yt-dlp-python-api/reference.md#batch) — 源头结果和恢复

<a id="setup"></a>

## 安装 Python 库


**在 Python 3.11+ 环境中运行**

```bash
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
```

**同时安装 Deno、FFmpeg 和 ffprobe。** 这些示例在 Linux、macOS 或 Windows 上本地运行，无需 API 密钥。确保下载进程可通过 PATH 找到这些可执行文件。

- [安装外部依赖](https://flashdata.dev/zh/docs/guides/how-to-use-yt-dlp/reference.md#install)
- [上游项目的嵌入用法](https://github.com/yt-dlp/yt-dlp#embedding-yt-dlp)

<a id="first-call"></a>

## 下载第一个视频


**下载一张视频**

```python
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget

options = {
    "js_runtimes": {"deno": {}},
    "impersonate": ImpersonateTarget(),
    "concurrent_fragment_downloads": 1,
    "noplaylist": True,
    "outtmpl": "downloads/%(id)s.%(ext)s",
    "format": "bv*[height<=1080]+ba/b[height<=1080]",
}
with YoutubeDL(options) as downloader:
    downloader.download(["https://www.youtube.com/watch?v=jNQXAC9IVRw"])
```

此示例在本地保存分辨率最高为 1080p 的媒体，并可合并单独的视频流和音频流。输出容器取决于选中的源格式。

**Python 不会继承 CLI 设置。** 即使终端命令已经配置了 Deno、浏览器模拟和请求间隔，也要在 Python 选项中设置。

download() 取出 URL 列表并返回状态代码。 extract_info(url, download=True) 返回提取信息以及下载。使用背景管理员清洁地关闭例子，并创建一个新例子为独立工作而不是在线上分享可变状态。

> **Python 选项不是机械翻译旗帜**
> --write-info-json 地图以写infojson; --no-playlist 地图以 noplaylist。音频转换使用后处理器列表。查看 YoutubeDL 的参数文档或上流 cli_to_api.py 助理，而不是猜测选项名称。

<a id="metadata"></a>

## 阅读无媒体的数据


**出口小型数据记录**

```python
import json
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget

url = "https://www.youtube.com/watch?v=jNQXAC9IVRw"
options = {
    "js_runtimes": {"deno": {}},
    "impersonate": ImpersonateTarget(),
    "noplaylist": True,
    "sleep_interval_requests": 3,
}
with YoutubeDL(options) as downloader:
    info = downloader.sanitize_info(downloader.extract_info(url, download=False))

record = {key: info.get(key) for key in (
    "id", "webpage_url", "title", "channel_id", "duration", "upload_date"
)}
print(json.dumps(record, ensure_ascii=False, indent=2))
```

download=False 仍然执行网络请求。 sanitize_info 使结果 JSON 兼容；它不会编写秘密或将结果减少到这些字段。

提取的字段可能是缺席或零。使用 get() 可选的代数据，并且不要假设每个来源都有一个长度、频道 ID 或完整的格式列表。平板播放列表列表也与完全解决的视频不同。对于公众的回应，仅项目您打算展示的领域。

避免即时进行的数据提取，随后每个来源的相同下载提取，除非您的应用程序需要额外的规划步骤。它将源源请求复制。如果您需要持久的工作，请存储源代码和输出政策；从元数据中签署的媒体URL不是原始来源的持久替代品。

<a id="options"></a>

## Python 选项参考


| 任务 | Python 選擇 | 细节 |
| --- | --- | --- |
| 输出目录和文件名 | "outtmpl": "downloads/%(id)s.%(ext)s" | 保持源识别和动态扩展。 |
| 硬 1080p 天花板 | "format": "bv*[height<=1080]+ba/b[height<=1080]" | 允许源代码，如果没有匹配限制，则失败。 |
| 甲状腺 侧面 | "writeinfojson": True | 将完整的提取数据与媒体相结合。 |
| 完整的ID检查点 | "download_archive": "archive.txt" | 每份输出政策一份档案，而不是支票存储。 |
| 严格的错误 | "ignoreerrors": False | 让呼叫者记录失败，而不是处理后处理问题作为成功。 |
| 丹尼尔时间 | "js_runtimes": {"deno": {}} | 安装 Deno 在下载进程，并在PATH上显示其二进制。 |
| 浏览器 印象 | "impersonate": ImpersonateTarget() | Python 等于 --impersonate=""; 输入目标类，并安装 curl-cffi。 |
| 现有 Cookie 文件 | "cookiefile": "private/youtube-cookies.txt" | 使用私人会话证书，只有在需要访问时。 |

**MP3 转换选项**

```python
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
```

转换 audio_options 到 YoutubeDL. 后处理器 FFmpeg 转换为目标比特率 192 kbps; 它不会改善源的原始质量。

- [Python 参数参考](https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/YoutubeDL.py)
- [将 CLI 选项转换为 Python 选项](https://github.com/yt-dlp/yt-dlp/blob/master/devscripts/cli_to_api.py)

<a id="dataset"></a>

## 视频 + 音频 + 录像带为 AI 数据集


使用此输出政策，当目标是训练数据集而不是下载进程示例的1080p收藏时，它要求最佳视频和 bestaudio,允许FFmpeg将它们融入MP4中，并在媒体旁边保存可用的英语录像和代数据。

**一个数据集项目在Python**

```python
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget

url = "https://www.youtube.com/watch?v=jNQXAC9IVRw"
options = {
    "js_runtimes": {"deno": {}},
    "impersonate": ImpersonateTarget(),
    "noplaylist": True,
    "format": "bestvideo+bestaudio/best",
    "merge_output_format": "mp4",
    "postprocessors": [{
        "key": "FFmpegVideoRemuxer",
        "preferedformat": "mp4",
    }],
    "outtmpl": "dataset/%(id)s/%(id)s.%(ext)s",
    "writeinfojson": True,
    "writesubtitles": True,
    "writeautomaticsub": True,
    "subtitleslangs": ["en"],
    "subtitlesformat": "vtt/best",
    "sleep_interval_requests": 2,
    "sleep_interval_subtitles": 5,
    "sleep_interval": 5,
    "max_sleep_interval": 10,
    "concurrent_fragment_downloads": 1,
    "retries": 3,
    "fragment_retries": 3,
}
with YoutubeDL(options) as downloader:
    downloader.download([url])
```

需要 FFmpeg/ffprobe、Deno 和夜间 [默认 curl-cffi] 安装，而 remuxer 的偏好格式参数则以此方式在 yt-dlp 的 API 中播放。

ImpersonateTarget() 选择任何可用的浏览器目标，匹配 --impersonate="”。通过对象，而不是从 CLI 合成中复制的空行。 curl-cffi 必须安装在这个 Python 环境中。目前,Deno 仍然运行 JavaScript 解决方案；定制不取代它。

MP4是输出容器；所选择的视频仍然可以是AV1或 VP9。如果您的训练解码器需要 H.264/AAC,在合并或记录一个单独的 FFmpeg 转码之前，请应用明确的编码政策。可用的字幕被收回，而不是从演讲中产生。

| 媒體結束後 | 数据集记录需要什么 |
| --- | --- |
| 查看最后的MP4与 ffprobe | Video/audio编码器，长度，尺寸，文件路径和比特计算。 |
| 查看 标签 侧面 单独 | 语言, supplied/automatic 轨道，时间表，以及文件是否实际存在。 |
| 没有可用的匹配容器 | 保持媒体并标记文本缺席；如果需要的话，将音频发送到您的转写阶段。 |
| 第429章 打了 | 退出标题在IP冷却后退出标题；不要重新下载完成的媒体。 |

对于一个集合，请使用这个数据集政策的单独档案，并保存所需的侧面图的存储库。不要重复使用以前的 1080p 或媒体仅存档：它可能会在收集新需要的录像之前删除视频。使用 after_move 以便媒体准备，然后在发布完整的数据集项目之前验证文本和代数据。

- [CLI 命令示例和数据集存储](https://flashdata.dev/zh/docs/guides/how-to-use-yt-dlp/reference.md#dataset)
- [平静 Python 数据和录像](https://flashdata.dev/zh/docs/guides/yt-dlp-429-too-many-requests/reference.md#python)

<a id="completion"></a>

## 知道最后文件什么时候准备好


进展霍克报告状态=完成，意味着转会完成。FFmpeg 可能仍然需要将视频和音频合并，转换音频文件，或移动输出。视频仅流达到 100% 不是完成事件，您的申请应该发布。

| 阶段 | 你所知道的 | 应用状态 |
| --- | --- | --- |
| 下载 | 一些媒体比特正在到来。 | 跑步 |
| 转换：完成 | 此转移已结束；处理仍可追踪。 | 处理 |
| after_move 后处理器 | 文件已通过了配置后处理和最终转移。 | 地点文件准备 |
| 升级和完整性检查 | 您的目的地有对象和记录验证。 | 交付 |

下面的完整示例记录了一个自定义的邮件处理器在 after_move 并在那里阅读 info["filepath"]。它检查文件是否存在并不被泄露。此避免猜测最终延伸与 prepare_filename(),可以提到一个预转换名称。

> **完成的本地下载不是完成的云交付**
> 如果下一步上传文件，请单独保持上传状态。 下载档案可以在下一个运行中错过源，即使上传之前失败。

<a id="worker"></a>

## 完整剧本：单视频下载进程


此分類上一篇: download_video.py它接受视频 ID 或 watch/Shorts/live/embed URL 并拒绝 playlist/channel 输入。每个邀请都使用一个YouTubeDL例子，有限的下载退款和集合地点档案。重复完成的源返回被错过，而不是假设新的文件创建。

- [首頁 download_video.py](https://flashdata.dev/examples/yt-dlp/download_video.py)

**download_video.py**

```python
import argparse
import json
import re
from pathlib import Path
from urllib.parse import parse_qs, urlparse

from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget
from yt_dlp.postprocessor.common import PostProcessor
from yt_dlp.utils import DownloadError, PostProcessingError


def watch_url(value):
    """Accept a video ID or a single YouTube video URL, never a playlist."""
    video_id = value
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", value):
        parsed = urlparse(value)
        parts = parsed.path.strip("/").split("/")
        host = (parsed.hostname or "").lower()
        if parsed.scheme not in {"http", "https"}:
            raise ValueError("Use a YouTube watch URL or 11-character video ID")
        if host in {"youtu.be", "www.youtu.be"}:
            video_id = parts[0]
        elif host in {"youtube.com", "www.youtube.com", "m.youtube.com"}:
            if parsed.path == "/watch":
                video_id = parse_qs(parsed.query).get("v", [""])[0]
            elif len(parts) == 2 and parts[0] in {"shorts", "live", "embed"}:
                video_id = parts[1]
            else:
                video_id = ""
        else:
            video_id = ""
    if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id):
        raise ValueError("Expected one YouTube video, not a channel or playlist")
    return "https://www.youtube.com/watch?v=" + video_id


class FinalFile(PostProcessor):
    def __init__(self):
        super().__init__()
        self.result = None

    def run(self, info):
        path = Path(info["filepath"]).resolve()
        if not path.is_file() or path.stat().st_size == 0:
            raise PostProcessingError("Final media file is missing or empty")
        self.result = {
            "status": "completed", "video_id": info["id"],
            "title": info.get("title"), "duration": info.get("duration"),
            "path": str(path), "bytes": path.stat().st_size,
        }
        return [], info


def download_video(source, output="downloads"):
    url = watch_url(source)
    folder = Path(output).resolve()
    folder.mkdir(parents=True, exist_ok=True)
    final_file = FinalFile()
    options = {
        "js_runtimes": {"deno": {}},
        "impersonate": ImpersonateTarget(),
        "concurrent_fragment_downloads": 1,
        "noplaylist": True,
        "format": "bv*[height<=1080]+ba/b[height<=1080]",
        "outtmpl": str(folder / "%(id)s.%(ext)s"),
        "download_archive": str(folder / "archive.txt"),
        "writeinfojson": True,
        "ignoreerrors": False,
        "retries": 3, "fragment_retries": 3, "socket_timeout": 30,
        "sleep_interval_requests": 1,
        "sleep_interval": 5, "max_sleep_interval": 10,
    }
    with YoutubeDL(options) as downloader:
        downloader.add_post_processor(final_file, when="after_move")
        downloader.extract_info(url, download=True)
    if final_file.result is None:
        return {"status": "skipped", "source": url,
                "reason": "No new file recorded; check the archive"}
    return {**final_file.result, "source": url}


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("source", help="YouTube video URL or ID")
    parser.add_argument("--output", default="downloads")
    args = parser.parse_args()
    try:
        result = download_video(args.source, args.output)
    except (DownloadError, ValueError, OSError) as error:
        raise SystemExit(f"Job failed: {error}") from error
    print(json.dumps(result, ensure_ascii=False, indent=2))
```

完整的脚本也可以从上面的下载链接中获取，它只拥有本地输出；在下一个应用程序阶段添加解码检查和上传记录。

**运行一份工作**

```bash
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads
```

完成的记录包含可通源URL、视频ID、最终路径和比特大小。被打破的记录意味着没有新的最终文件的呼叫回归；将其与存档和现有存档相匹配，如果您需要证明文件仍然存在。仅此地，档案不检查用户是否随后删除或移动媒体。

捕获 extractor/download/post-processing 故障的 DownloadError, 拒绝输入的 ValueError 和 地方文件系统故障的 OSError。将这些类作为您的应用程序日志中的单独类。错误消息是有用的诊断，但它们的文本不是每个YouTube失败的稳定的结构化税率。

<a id="batch"></a>

## 完整剧本：可重复的包下载进程


放下 download_batch.py 在 download_video.py 旁边。创建一个 UTF-8 urls.txt 与一个视频 URL 或 ID 每行。故意运行序列，因此一个过程拥有档案和输出目录。它写下完成、失败或失败的结果，每一次尝试输入和输出，当任何项目失败时，则不零。

- [首頁 download_batch.py](https://flashdata.dev/examples/yt-dlp/download_batch.py)

**download_batch.py**

```python
import argparse
import json
from datetime import datetime, timezone
from pathlib import Path

from yt_dlp.utils import DownloadError
from download_video import download_video


def run_batch(manifest, output):
    folder = Path(output).resolve()
    folder.mkdir(parents=True, exist_ok=True)
    sources = list(dict.fromkeys(
        line.strip()
        for line in Path(manifest).read_text(encoding="utf-8-sig").splitlines()
        if line.strip() and not line.lstrip().startswith("#")
    ))
    counts = {"completed": 0, "skipped": 0, "failed": 0}
    with (folder / "attempts.jsonl").open("a", encoding="utf-8") as log:
        for source in sources:
            try:
                result = download_video(source, folder)
            except (DownloadError, ValueError, OSError) as error:
                result = {"source": source, "status": "failed",
                          "error_type": type(error).__name__, "error": str(error)}
            result["recorded_at"] = datetime.now(timezone.utc).isoformat()
            log.write(json.dumps(result, ensure_ascii=False) + "\n")
            log.flush()
            counts[result["status"]] += 1
    return counts


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("manifest", help="UTF-8 file, one video URL or ID per line")
    parser.add_argument("--output", default="collection")
    args = parser.parse_args()
    counts = run_batch(args.manifest, args.output)
    print(json.dumps(counts, indent=2))
    raise SystemExit(1 if counts["failed"] else 0)
```

附件仅 attempts.jsonl 保持退出作为单独的尝试。 在一个显明内复制线被删除；下载档案处理完成 ID 经过运行。

**运行或重复相同的行**

```bash
python download_batch.py urls.txt --output collection
```

每次记录后流动，以便中断不会让每个结果都被打破到结束。图书馆记录其档案和您的应用程序写试图记录之间仍然有一小窗口。如果发生事故，下一轮可以报告失败。对于一个服务，将 filesystem/archive 与可持续的工作数据库相匹配，而不是声称这个文本文件示例是交易性的。

保持 attempts.jsonl 隐私：错误可能包括源和请求详细信息。 根据状态报告总数，检查失败的项目，并在解决共享环境问题后重新播放相同的显而易见。

<a id="service"></a>

## 生产：条，期限和存储


YouTubeDL 是同步的。运行它直接在一个无与伦比的网页交易员的区块，交易员的事件路径；即使一个线条下载不会使浏览器请求适合一个大下载的寿命。接受工作，坚持其来源/选项，让下载进程产生最终结果。

- 在执行之前创建一个可持续的工作 ID. 存储视频 ID、输出政策、尝试号码和目的地。
- 使用工作日志和有限的下载进程游泳池。 不要在竞争对手的工作中分享YouTubeDL例子。
- 使用单独的过程，当您需要硬墙时钟期限或取消; socket_timeout限制个人网络操作，而不是整个工作。
- 如果曝光用户输入超过 HTTP,接受支持的YouTube视频识别器，而不是任意的URL,输出路径，抽象论点或壳牌剪辑。
- 记录本地文件准备和云上传完成单独；保持足够的状态，以恢复上传而不再下载。
- 保持 FFmpeg、运行时间、 yt-dlp 和插件版本与您的部署。

一个简单的下载进程游泳池比无限 asyncio.gather 呼叫周围的许多下载更好。协调整个过程的整体工作；每个下载器的睡眠设置不调节整个服务。保持工作企图的单独退休预算，以便申请退休不会增加下载者的退休数量。

<a id="diagnostics"></a>

## 解决Python下载进程的问题


| 问题 | 检查项 |
| --- | --- |
| 工作在CLI,失败在Python | 比较实际选项。 YoutubeDL 不自动加载您的 CLI 配置文件。 |
| 进展说结束，文件缺失 | 使用 after_move 边界，检查后处理错误。 |
| 重复回归的源头 | 阅读收藏档案；在更改输出政策时使用不同的档案。 |
| 下载进程挂得比socket_timeout更长 | 一个工作可以完成许多 operations/retries. 需要时添加过程级的期限。 |
| 403 或机器人在服务器上检查 | 更新 nightly 版，检查 Deno,减少竞争力，并在路线被拒绝时测试替换输出IP。 |
| 429 在 数据 / 转写工作 | 停止受影响的IP,速度extraction/subtitle请求，并在代数据之间添加延迟 - 只有工作。 |

- [403 诊断工作流](https://flashdata.dev/zh/docs/guides/yt-dlp-403-forbidden/reference.md)
- [会议和Bot-check工作流](https://flashdata.dev/zh/docs/guides/yt-dlp-sign-in-not-a-bot/reference.md)
- [429 恢复和 Python 包装](https://flashdata.dev/zh/docs/guides/yt-dlp-429-too-many-requests/reference.md)
- [查看保存的媒体](https://flashdata.dev/zh/docs/guides/how-to-use-yt-dlp/reference.md#verify)

<a id="managed-downloads"></a>

## 当产量属于云管道时


如果您想要拥有下载器，上述工作流将为您提供对文件、格式和处理的控制权。如果您的应用程序需要完成的存储媒体,FlashData提供跟踪的YouTube下载工作，机器人处理，代理路由和退出。您的申请提交源和输出设置，然后保留工作身份证和交付记录。

- [比较两种操作模式](https://flashdata.dev/zh/docs/guides/flashdata-vs-yt-dlp/reference.md)
- [YouTube 视频批量下载](https://flashdata.dev/zh/products/youtube-download#bulk-downloads)
- [下载Demo](https://flashdata.dev/zh/products/youtube-download#playground)
- [下载 API 参考](https://flashdata.dev/zh/docs/sources/youtube_download/reference.md)
