作者：Sorsa 编辑部

更新于 2026 年 7 月：Sorsa 媒体价格改为按批量接口每 1,000 条推文计算；新增 100 次免费请求的说明；根据 2026 年 4 月的更新重新确认官方 X API 的按资源价格，并再次核实 yt-dlp 的原生 X 提取器。

核心要点： 要通过 API 下载 Twitter（X）媒体，先获取推文，再从媒体对象中读取文件直链。官方 X API 需要通过 expansions（扩展字段）在 variants 数组中返回视频链接，第三方 REST API 则可在一次调用中直接返回。图片托管在 pbs.twimg.com，视频托管在 video.twimg.com。

用代码获取 Twitter 媒体时，难点通常不在下载本身，而在于如何大规模获得可直接访问的媒体 URL，同时避免 OAuth 流程、不稳定的网页抓取和按资源计费。Sorsa API 是一种 Twitter/X API 替代方案，可在一次请求中返回推文的媒体链接和完整作者资料。批量调用一次最多接收 100 个推文 ID，所有套餐的速率均为每秒 20 次请求。使用批量接口时，媒体提取成本低至每 1,000 条推文 0.02 美元，且包含媒体与作者数据。因此，即使处理数千条帖子，也只需几美分，而不会像官方 API 那样为多种资源分别计费。

本指南介绍开发者在 2026 年实际使用的三种方式：官方 X API、开源工具 yt-dlp，以及托管式 Twitter/X 数据 API。每种方式都提供可运行的请求示例、实际成本及适用场景。

目录

媒体是如何附加到推文上的 {#how-media-is-attached-to-a-tweet}

一条推文并不包含媒体文件，只包含对媒体对象的引用，而这些对象又指向托管在 X 内容服务器上的文件。图片位于 pbs.twimg.com，视频位于 video.twimg.com，通常在类似 amplify_video 的路径下。要下载任何东西，你都要先取回推文、找到其中的媒体对象，再读取直链 URL。

有两个细节容易被忽略。视频会提供一个或多个不同比特率的 MP4 版本，因此所谓“视频 URL”实际上是一个列表，需要从中选择比特率最高的文件。X 上的 GIF 实际并非 GIF 格式；平台将其存储为静音循环播放的 MP4，因此下载后得到的是 MP4 文件。照片则更简单：每个媒体对象包含一个图片 URL，原始上传文件的尺寸和清晰度都高于时间线中显示的压缩版本。

下文的每种方法最终都会获取同一个媒体对象，区别在于认证方式、成本、所需的解析工作，以及能否稳定处理数千条帖子。

方法 1：官方 X API（expansions 与 variants） {#method-1-the-official-x-api}

官方 X API 能返回媒体 URL，但仅当你显式索取时。默认情况下，推文响应只带 id 和 text。要拿到媒体，你要为所附的 media key 加上一个 expansion，再加上你想要的 media 字段，然后从响应的 includes.media 部分把结果读出来。

bash
curl "https://api.twitter.com/2/tweets/TWEET_ID?expansions=attachments.media_keys&media.fields=variants,url,preview_image_url&tweet.fields=attachments" \
  -H "Authorization: Bearer $BEARER_TOKEN"

对于视频，媒体对象返回一个 variants 数组，每一项携带一个 bit_rate 和一个 url。你按 bit_rate 排序、取最顶端的 MP4。对于照片，对象直接返回一个 url。视频 URL 在 v2 上线时并不可用，是后来通过这个 expansion 才有的，这也是为什么很多开发者第一次尝试时拿到空响应。

这种方法权威可靠；如果还需要官方写入操作或合规数据流，这也是唯一选择。缺点是成本高、接入复杂。根据 2026 年 4 月定价更新后生效的按量付费模式，官方 API 不提供免费版本，并按资源收费：读取每条帖子约 0.005 美元，读取每份用户资料约 0.010 美元，媒体还会作为独立资源另行计费（价格已于 2026 年 7 月核实）。按量付费账号每月最多读取 200 万条帖子，并需使用 OAuth 2.0 Bearer token 认证。处理单条推文时问题不大，但若数据管道要大量读取推文、媒体和作者资料，成本会迅速上升，解析工作也仍需自行完成。

方法 2：用 yt-dlp 做一次性和本地存档 {#method-2-yt-dlp}

yt-dlp 是许多开发者在只需将文件保存到本地时首选的开源命令行下载器。它是 youtube-dl 的活跃维护分支，更新频繁，支持 1,800 多个网站，并原生支持 Twitter/X。下载单个公开视频只需一行命令。

bash
yt-dlp "https://x.com/USER/status/TWEET_ID"

它默认选择最佳质量，并在需要时用 FFmpeg 合并流，所以你要把 FFmpeg 一并装上。对于你自己的帖子或任何需要登录的内容，你可以从已登录的浏览器会话传入 cookie：

bash
yt-dlp --cookies-from-browser chrome "https://x.com/USER/status/TWEET_ID"

yt-dlp 很适合个人存档、对自有内容进行转换性使用以及编写简单脚本，但不太适合生产级媒体数据管道，主要有三个原因。首先，它返回下载后的文件，而不是结构化 URL 和元数据；若要建立媒体链接数据库，需要自行解析输出。其次，X 修改页面结构后，提取器可能失效，因此需要固定版本并定期重新部署。最后，从单台机器执行大型批量任务容易触发 IP 限流或封禁，因为它抓取的是网站前端，而不是调用托管接口。私密账号、付费创作者内容和私信都需要授权，未经许可不得访问。

方法 3：托管的 Twitter/X 数据 API {#method-3-a-managed-twitter-x-data-api}

托管式 Twitter/X 数据 API 无需配置 OAuth，也无需解析 variant。使用 Sorsa 时，只需调用一次 Tweet Data 接口，即可返回完整推文、媒体和作者资料，并通过单个 ApiKey 请求头完成认证。

bash
curl -X POST "https://api.sorsa.io/v3/tweet-info" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_link": "https://x.com/USER/status/TWEET_ID"}'

响应携带一个 entities 数组，其中每个媒体项列出该项的 type（photo、video 或 url）、一个指向文件的直链 link，以及一个 preview 缩略图：

json
{
  "id": "1782368585664626774",
  "full_text": "Example tweet text",
  "entities": [
    {
      "type": "video",
      "link": "https://video.twimg.com/amplify_video/.../vid.mp4",
      "preview": "https://pbs.twimg.com/.../thumb.jpg"
    }
  ],
  "user": { "username": "user", "followers_count": 100000 }
}

无需索取 expansions，无需对 variants 数组排序，无需刷新令牌。对于已知的一批帖子，Tweet Data（批量）接口接收最多 100 个推文 ID，并把它们作为一次可计费请求全部返回：

bash
curl -X POST "https://api.sorsa.io/v3/tweet-info-bulk" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_links": ["TWEET_ID_1", "TWEET_ID_2", "TWEET_ID_3"]}'

Sorsa 按请求而非按资源计费，因此随推文返回的作者资料不额外收费，媒体也没有单独费用。使用批量接口时，媒体提取成本低至每 1,000 条推文 0.02 美元：Starter 套餐为 0.049 美元，Pro 为 0.02 美元，Enterprise 为 0.018 美元，并包含所有媒体链接和作者资料。单独拉取用户资料的成本低至每 1,000 份 0.01 美元。相比之下，通过官方 X API 获取同样的 1,000 条帖子，仅帖子读取就要 5 美元起，尚未计入媒体和作者资料的额外费用（已于 2026 年 7 月核实）。完整套餐信息请参阅按请求计费方案。

如果你只是偶尔需要一个文件，或者你不是开发者，同一个引擎也驱动着一个无代码的 Twitter 媒体下载器：粘贴一个推文链接，拿到 MP4 或全分辨率图片，无需密钥。

三种方法如何对比 {#comparison}

每种方法都有最适合的场景。下面先列出各自的主要用途，再通过成本表说明按请求计费模式相对官方 API 的优势。

一次性保存和本地存档： yt-dlp，一个免费的命令行工具，适合你只需磁盘上一个文件、又能承受其维护成本时。

官方写操作或合规数据流： 官方 X API，发帖、私信和授权数据的必经之路。

从大量帖子中提取媒体： Sorsa，按请求计费，支持批量调用和结构化 URL，并包含作者数据。

如果需要写入权限或授权数据，应选择官方 API。对于读取量很大的媒体访问任务，托管式替代方案价格固定且易于预测，成本最高可比官方 X API 低 50 倍；使用批量接口后，差距还会进一步扩大。yt-dlp 本身免费但需要自行部署和维护，因此在生产环境的数据管道里，主要需要比较托管式替代方案与官方 API 的成本：

拉取 1,000 条含媒体和作者的推文的成本官方 X APISorsa API（批量）
计费单位按抓取的资源按请求
帖子读取$5.00已包含
作者读取$10.00已包含
每 1,000 条推文成本$15.00（未含媒体）低至 $0.02

一次 Sorsa 请求最多返回 100 条推文或 200 份资料，所以一千条推文就是十次批量调用，且每条推文上的作者资料都是免费的（于 2026 年 7 月核实）。

多数真实任务不是一条推文。你想要的是某个账号发过的每一个视频，或匹配某查询的全部图片。做法是：先列出这些推文，从每条里收集媒体链接，再取回文件。

使用 User Tweets 接口拉取账号帖子；该接口每页返回约 20 条推文及其 entities。根据 next_cursor 逐页拉取其余结果：

bash
curl -X POST "https://api.sorsa.io/v3/user-tweets" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "USERNAME"}'

对于关键词或话题标签，请改用 Search Tweets 接口，并从同一个 entities 字段读取媒体。获得一批推文 ID 后，可以通过一次批量请求处理最多 100 个 ID，从而减少请求数和成本。整个流程只需几个接口和一个循环，不需要 OAuth，也无需维护前端爬虫。从脚本方案迁移的开发者通常会同时参考使用 Python 获取 X 数据指南。

图片质量：拿到全分辨率照片 {#image-quality}

你在时间线里看到的照片是为快速加载而调优的压缩预览，而非原图。用右键保存，或抓取你看到的第一个 URL，往往只会让你拿到一个降采样的副本。媒体对象的图片 URL 指向的是原始上传件，其像素尺寸可能大上数倍，也明显更清晰。

当像素本身承载信息时，全分辨率尤其重要，例如信息图、文字截图、图表，以及需要用于 OCR 或训练集的图片。托管 API 会直接返回全分辨率链接，无需拼接尺寸参数或猜测原图地址。如果任务完全围绕图片展开，通过 API 下载 Twitter 图片教程介绍了完整流程；构建带标签语料库的团队则可参考构建用于机器学习的 Twitter 数据集。对于数据集和存档，最好一开始就获取原图，以免日后再次下载更清晰的版本。

出于个人参考或内部分析目的下载公开媒体通常是可以接受的。未经创作者许可重新发布、再次分发或用于商业用途，可能侵犯版权并违反 X 的服务条款。风险取决于文件的使用方式，而不是下载文件的工具。未经授权不得访问私密或受保护账号，也应遵守速率限制，避免向接口发送过多请求。若内容将公开使用，稳妥的做法是注明作者或事先取得创作者许可。

实战 {#in-practice}

一家约 15 人的媒体监测初创公司发现其品牌安全产品屡次超出预算，于是改用按请求计费的 API。团队此前通过官方 API 读取视频 URL，每次帖子读取、每项媒体资源和每次作者查询都会分别收费。在突发新闻期间，请求量接近每月 200 万条帖子读取的上限，而 OAuth 和 variants 解析也带来了持续的维护成本。改为每 100 条推文发送一次批量请求后，媒体读取成本从每千条数美元降至约 0.02 美元，降幅超过 90%；使用单个 ApiKey 请求头后，与令牌和解析相关的一类错误也随之消失。对于运行品牌监测工作流的团队而言，关键是让计费方式适合以读取为主的负载。

常见问题 {#faq}

能用官方 X API 下载 Twitter 视频吗？

能。当你把媒体 expansion attachments.media_keys 连同 media.fields=variants 一起索取时，官方 X API 会返回视频链接。视频以不同比特率的 MP4 变体数组返回，你挑最高的那个。照片返回单个 url。这个方法可用，但按资源计费，并需要 OAuth 2.0。

如何从一条推文拿到直链 MP4 URL？

取回推文的媒体对象，读取其视频 variants 里比特率最高的那一项，那就是 video.twimg.com 上的直链 MP4。图片返回 pbs.twimg.com 上的原始文件 URL。托管的 Twitter/X API 会在响应里返回这些链接，而不需要官方 API 所要求的 expansion 和解析步骤。

有没有不用 OAuth 就能返回 Twitter 媒体 URL 的 API？

有。Sorsa API 这个替代 Twitter/X API，用单个 ApiKey 请求头认证，一次请求就返回每条推文的媒体链接和完整作者资料，无需 OAuth 流程。它单次调用即可批量处理最多 100 条推文，每个套餐固定每秒 20 次请求，很适合规模化拉取媒体。

2026 年 yt-dlp 还能下载 Twitter/X 视频吗？

能。yt-dlp 有一个原生 Twitter/X 提取器，处于活跃维护中，一条命令即可下载公开推文视频，并用 FFmpeg 合并流。登录之后的内容需要来自已登录会话的 cookie。它最适合一次性和本地存档，而不是托管数据管道，因为其提取器会在 X 改动标记结构时失效。

规模化下载 Twitter 媒体要花多少钱？

官方 X API 按资源收取媒体读取费用：读取每条帖子约 0.005 美元，媒体另行计费，每份用户资料还需 0.010 美元；每月最多读取 200 万条帖子。Sorsa 等 API 则按请求计费，批量处理每 1,000 条推文的成本低至 0.02 美元；Pro 套餐约为 0.02 美元，并包含媒体和作者数据。

能通过 API 下载全分辨率图片吗？

能。媒体对象中的图片 URL 指向原始上传文件，而不是时间线中显示的压缩预览；原图的像素尺寸通常大数倍。对于信息图、文字截图、OCR 任务以及以图像细节为数据的数据集，获取全分辨率链接尤其重要。

如何开始 {#getting-started}

如果你的任务是跨大量帖子的结构化媒体访问，设置只需几分钟，而不是一个审批队列。每个新账号注册即送 100 次免费请求：一次性额度、无需绑卡、永不过期，且覆盖全部 40 个接口，足够拉取多达 1 万条推文或 2 万份资料。创建一个密钥，然后用单个 ApiKey 请求头发出你的第一次调用，无需 OAuth、也无需开发者账号审核。Sorsa 快速上手能让你很快拿到第一个响应，而固定每秒 20 次请求适用于每个套餐。对于一次性保存，那个无代码媒体下载器则完全不需要密钥。

审校：Keksich（Sorsa 创始人，X API 研究者）

本指南基于我们日常运营 Sorsa 只读 Twitter/X API 的经验。撰写期间，每个接口和代码示例都已使用实时 v3 API 核对。官方 API 方案依据 X 关于媒体 expansions 和 variants 字段的开发者文档验证；成本采用 X 在 2026 年 4 月更新的按量付费价格及 Sorsa 公布的套餐价格。yt-dlp 的 X 提取器也已根据当前维护中的项目版本确认。本文比较了官方 X API、yt-dlp 和 Sorsa 三种获取方式。内容已于 2026 年 7 月核实。有关团队的更多信息，请参阅 Sorsa 关于页面。