Twitter 流式 API 指南：WebSocket vs REST vs 过滤流 (2026)

什么是 Twitter 流式 API？

Twitter 流式 API（现为 X API）让开发者在推文发布的瞬间实时接收数据，而不是按计划轮询端点。对交易机器人、新闻聚合、社交监听仪表盘以及任何对延迟敏感的应用，流式都是响应式管道的基础。

X 的 v2 API 暴露两个流式端点：过滤流（按开发者定义的规则交付匹配推文）和采样流（返回所有公共推文约 1% 的随机样本）。两者都使用长连接 HTTP — 服务端保持连接打开，并在匹配推文出现时以换行分隔的 JSON 推送。

Twitter 历史上在 v1.1 提供过更早的流式接口。当前 X API 的具体打包与权限请始终通过最新文档与你的账户控制台确认。

流式协议在底层如何工作

X 的流式 API 不使用 WebSocket，而是基于 HTTP 流式 — 一个长连接 HTTP/1.1（或 HTTP/2）连接，服务端在不关闭响应的情况下增量发送数据。可以把它看作下载一个无穷长的文件。

你的客户端向过滤流端点发起 HTTP GET 请求。服务端以状态码 200 响应，并开始写入换行分隔的 JSON。每条推文作为单独一行到达。两条推文之间，X 大约每 20 秒发送一次保活换行（空行），让你的客户端能检测到停滞连接。

这种设计有后果。你的 HTTP 客户端必须支持分块传输编码与增量解析。标准的请求/响应库（如 fetch 或 axios）会缓冲整个响应再返回，这会让流式失去意义。你需要一个流式 HTTP 客户端 — 比如 Node.js 内置的 http 模块、Python 的 requests（stream=True），或 undici 等库。

• 协议：HTTP/1.1 分块传输编码（不是 WebSocket）
• 格式：换行分隔的 JSON，每行一条推文
• 保活：约每 20 秒发送一次空行
• 重连：客户端负责检测断开并按退避重试

流式 vs 轮询 vs WebSocket：延迟对比

轮询（REST） 是指你的应用按固定时间间隔调用搜索或时间线端点。无论有没有新数据都会消耗调用，且最坏延迟受限于轮询间隔。

HTTP 流式（X 的过滤流）会在推文匹配规则时推送数据。它降低了轮询开销，但你仍然需要确认当前权限、处理重连，并自行处理原始推文 JSON。

WebSocket 交付 也以推送方式实时传输数据，但走的是持久双向连接。WebSocket 是独立协议（RFC 6455），从 HTTP 升级开始，然后切换到帧式二进制/文本协议。它支持服务端推送、客户端推送、ping/pong 保活和内置关闭握手 — 这些 HTTP 流式都没有。

过滤流端点细节

过滤流（POST /2/tweets/search/stream/rules 设置规则，GET /2/tweets/search/stream 建立连接）是 X 的主要实时端点。按调用计费下你可获 1 个并发连接和每个项目最多 1,000 条规则（单条规则 1,024 字符）；企业版可扩展到 25,000+ 规则与多个并发连接。

每条规则可按关键词、用户名、话题标签、对话 ID 等匹配。当公共推文匹配任一规则时，会随附匹配的规则 ID 出现在你的流中。每条送达的推文除连接本身外另算一次 $0.005 读取。

需要了解的关键限制：

• 按调用计费下 1 个并发连接；多个并发连接需要企业版
• 尾延迟通常约 6–7 秒（p99，从发推到送达）
• 无历史回填 — 仅能拿到连接期间发布的推文
• 断连可能丢数据，除非有带外恢复路径
• 每条送达的推文按 $0.005 计量读取

代码示例：连接 X 过滤流（Node.js）

// Connect to X API filtered stream
const needle = require('needle');

const BEARER_TOKEN = process.env.X_BEARER_TOKEN;
const STREAM_URL = 'https://api.x.com/2/tweets/search/stream';

async function streamConnect() {
  const response = await needle('get', STREAM_URL, {
    headers: {
      Authorization: `Bearer ${BEARER_TOKEN}`,
    },
  });

  response.on('data', (data) => {
    try {
      const json = JSON.parse(data);
      console.log('[TWEET]', json.data?.text);
    } catch (e) {
      // Keep-alive newline — ignore
    }
  });

  response.on('err', (error) => {
    console.error('Stream error:', error);
    // Implement exponential backoff before reconnecting
    setTimeout(streamConnect, 5000);
  });
}

streamConnect();

X API 流式接入与层级（2026 年 4 月）

请通过最新的 X 文档与开发者控制台确认你账户当前的流式接入打包方式：

把旧截图和定价综述类文章当作历史参考。在围绕它们设计架构前，请直接确认当前权限。

请始终在 官方 X API 文档 确认当前定价 — 层级与限制变更频繁。

代码示例：TweetStream WebSocket 连接

// Connect to TweetStream WebSocket (from $199/mo)
const WS_URL = 'wss://ws.tweetstream.io/ws';
const API_KEY = process.env.TWEETSTREAM_API_KEY;

const ws = new WebSocket(WS_URL, [
  'tweetstream.v1',
  `tweetstream.auth.token.${API_KEY}`,
]);

ws.onmessage = (event) => {
  const envelope = JSON.parse(event.data);

  if (envelope.t === 'tweet' && envelope.op === 'content') {
    const { author, text } = envelope.d;
    console.log(`[${author.handle}] ${text}`);
  }

  if (envelope.t === 'tweet' && envelope.op === 'meta') {
    const { tokens, ocrTexts } = envelope.d;
    if (tokens?.length) {
      console.log('Detected tokens:', tokens.map(t => t.symbol));
    }
  }
};

Twitter 流式 API 的 WebSocket 替代方案

如果你需要低延迟的账号告警但又不想自己拥有整条流式管道，基于 WebSocket 的服务提供了替代方案。它们负责数据管道，并通过持久 WebSocket 连接交付推文，附带额外富化。

比如 TweetStream，以约 200 毫秒交付推文告警，附带自动代币检测、图片 OCR 文本提取与实时加密价格 — 这些都是你在原生 X API 之上要自建的能力。

• 推送式交付，典型延迟约 200 毫秒
• 持久 WebSocket 连接，自动重连
• 无需自建或维护流式基础设施
• 内置富化：OCR、代币检测、实时价格、Polymarket 赔率
• 起价 $199/月

何时选择流式替代方案

以下场景可考虑 WebSocket 替代方案：

• 交易或告警需要亚秒级交付
• 希望直接拿到富化数据（代币、价格、OCR），不想自建管道
• 官方 API 的打包或运维负担不合适
• 不想自己管理重连与回填逻辑
• 需要监控特定账号而非基于关键词的规则

用 TweetStream 更快上线

这篇文章讲的是这类工作流，但真正上线时不应该重新搭建推文接入、重连、代币检测、OCR 和下游投递。TweetStream 是更好的生产起点：账号级实时事件、富化 JSON 载荷、支持套餐的历史回放，以及可以直接用自己账号验证的 3 天试用。

常见问题

下一步

需要带富化（代币检测、OCR）的流式告警？先看 WebSocket 快速开始。想做与官方 X API 的详细对比，请看 Twitter API 替代方案。

参考来源

• X API 文档
• X API 速率限制参考
• 过滤流迁移指南

TweetStream 团队

最近更新：2026 年 3 月