TweetAPI 文档

通过面向开发者的 REST API，获取全面的公开 Twitter/X 数据。

发送第一个 API 请求

注册即可获得一次性 100 次免费试用请求，每分钟最多 10 次。无需信用卡或付费套餐，试用额度不会过期。

1. 创建 TweetAPI 账户（页面仅提供英文版），系统会自动准备免费 API 访问权限。
2. 前往 API Keys（页面仅提供英文版），选择 Create Key，输入名称并保存完整密钥。完整密钥仅在创建时显示；如果没有保存，请创建一个新密钥。
3. 打开下方已填好参数的请求，选择密钥并点击 Try It!，即可查询公开用户资料。此请求不需要额外的 X 账户授权。
4. 确认响应状态为 200，并返回包含 data 的 JSON 对象。Playground 调用的是真实 API，会消耗请求额度。
5. 要在自己的应用中使用 API，请设置以下环境变量，然后运行其中一个示例。

打开已填好参数的 Playground （Playground 目前仅提供英文界面。）

在本地运行同一个请求

将 YOUR_API_KEY 替换为已保存的完整密钥。在运行代码的同一终端中设置环境变量。请在服务端保管密钥，不要将其放入前端代码或提交到 Git。

macOS / Linux:

export TWEETAPI_API_KEY='YOUR_API_KEY'

PowerShell:

$env:TWEETAPI_API_KEY = 'YOUR_API_KEY'

cURL (Bash)

curl --fail-with-body \
  'https://api.tweetapi.com/tw-v2/user/by-username?username=elonmusk' \
  -H "X-API-Key: ${TWEETAPI_API_KEY:?Set TWEETAPI_API_KEY first}"

Python SDK

使用 pip install tweetapi 安装 SDK。将以下代码保存为 quickstart.py，然后运行 python quickstart.py。

import os
from tweetapi import TweetAPI

client = TweetAPI(api_key=os.environ["TWEETAPI_API_KEY"])
user = client.user.get_by_username(username="elonmusk")
print(user["data"])

Node.js SDK（Node.js 18 及以上版本）

使用 npm install tweetapi-node 安装 SDK。将以下代码保存为 quickstart.mjs，然后运行 node quickstart.mjs。

import TweetAPI from "tweetapi-node";

const apiKey = process.env.TWEETAPI_API_KEY;
if (!apiKey) throw new Error("Set TWEETAPI_API_KEY first");
const client = new TweetAPI({ apiKey });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data);

第一个请求失败时

• 环境变量未设置或返回 401：请将 TWEETAPI_API_KEY 设置为完整密钥，而不是密钥列表中隐藏了部分字符的预览值。
• 账户仍在准备中：在设置页面选择 Check again。如果仍无法使用，请联系支持团队。
• 429：请查看错误消息。如果达到每分钟请求上限，请降低请求频率并采用有次数限制的退避重试；如果额度已耗尽，请查看 Billing（页面仅提供英文版）。
• 503：服务暂时不可用。如有 Retry-After 响应头，请遵循其指示并限制重试次数。

基础 URL

所有 API 请求都应发送到：

https://api.tweetapi.com/tw-v2/

身份验证

在 X-API-Key 请求头中包含你的 API 密钥：

headers: {
  'X-API-Key': 'YOUR_API_KEY'
}

调用 API 前须知

• 响应采用 JSON 格式。
• 套餐限制按 API 密钥执行，包括请求额度和每分钟请求上限。
• 集合类端点在支持时使用基于游标的分页。
• 发布、互动、资料、私信和 X Chat 端点除了 TweetAPI 密钥外，还可能需要账号授权字段。请查看各端点页面，确认准确的必填参数。
• 429 响应可能表示套餐请求额度已用完，也可能表示超过每分钟上限。重试前请检查错误消息。TweetAPI 的 tw-v2 端点目前不返回 Retry-After 或 X-RateLimit-* 响应头。

TweetAPI SDK

TweetAPI 为 Python 和 Node.js 提供持续维护的 SDK，支持完整类型、自动重试和内置分页。

Python

pip install tweetapi

from tweetapi import TweetAPI

client = TweetAPI(api_key="YOUR_API_KEY")
user = client.user.get_by_username(username="elonmusk")
print(user["data"]["followerCount"])

在 GitHub 上查看

Node.js / TypeScript

npm install tweetapi-node

import TweetAPI from "tweetapi-node";

const client = new TweetAPI({ apiKey: "YOUR_API_KEY" });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data.followerCount);

在 GitHub 上查看

开发者资源

• 用于代码生成器、API 工具和契约感知集成的 OpenAPI 规范（页面仅提供英文版）
• 包含全部 82 个已记录操作的完整 Postman 集合（页面仅提供英文版）
• 使用公开资料、搜索和推文详情请求安全入门的只读 Postman 快速开始集合（页面仅提供英文版）

这些资源目前仅提供英文版。

主要功能

• 公开数据访问：用户资料、推文/帖子、粉丝和互动指标
• 互动功能：发布推文，以及管理点赞、转推、书签和私信
• 搜索：使用文档中列出的查询参数搜索推文、用户和媒体
• 按请求获取最新数据（页面仅提供英文版）：应用发送请求时，获取当前帖子、资料和指标（英文文档）
• 分页：集合类端点支持基于游标的分页
• 媒体支持：完整支持图片、视频和 GIF

可用端点

用户端点

• 按用户名获取用户
• 按 ID 获取用户
• 按多个 ID 批量获取用户
• 粉丝和关注列表
• 用户推文和回复
• 订阅信息

推文端点

• 推文详情和对话线程
• 引用推文和转推
• 推文翻译
• 互动指标

互动端点

• 创建、回复和删除帖子
• 点赞和收藏推文
• 转推和引用推文
• 列表管理

列表与社区端点

• 列表详情和成员
• 社区信息
• 时间线推文

搜索端点

• 搜索推文、用户和媒体
• 高级搜索运算符
• 筛选和排序选项

套餐限制

当前公开套餐的每分钟请求上限如下：

• Free：每分钟 10 个请求
• Pro：每分钟 60 个请求
• Ultra：每分钟 120 个请求
• Mega：每分钟 180 个请求

私有、旧版或定制套餐的限制可能不同。如果因每分钟上限收到 429，应使用次数受限的指数退避并降低并发数。用完套餐请求额度后，短时间重试无法解决问题；请在控制台查看当前用量和订阅选项。

按量付费（PAYG）备用余额

客户可以在 Billing 中手动购买一次性 PAYG 充值：10,000 单位为 $5 USD，20,000 单位为 $10 USD，40,000 单位为 $20 USD，100,000 单位为 $50 USD。充值不会自动续费。TweetAPI 会先使用可用的免费套餐或订阅额度，然后自动使用有效的 PAYG 余额。取消订阅后，有效的 PAYG 单位仍可使用。仅使用 PAYG 时，每分钟最多 60 个请求；如果有效套餐的速率上限更高，则继续采用更高的上限。

PAYG 单位在付款成功结算后 365 天到期。充值到账后，整个尚未到期的钱包将采用现有到期日与结算后 365 天两者中较晚的日期。已经到期的单位不会恢复。如果充值到账时钱包已到期，仅在原到期日前完成付款并不能保证延期。如果你在到期前付款但到账延迟，请联系 support@tweetapi.com，要求审核并更正确认的处理错误，或提供其他适当补救。Billing 页面和付款确认会以 UTC 显示最终到期时间。

单位衡量的是 API 使用量，而不是返回的推文数量。大多数计量调用消耗 1 个单位；/tw-v2/xchat/send 消耗 10 个单位，/tw-v2/auth/login 消耗 500 个单位。HTTP 200–499 的计量响应会计费，但 400、401、403 和 429 除外。可计费的空结果、分页请求，以及每次单独提交的重试或重复请求都会消耗单位。

退款会按比例撤销单位，并向上取整到完整单位。付款争议会撤销相关购买的全部单位，但会扣除已因退款撤销的单位。余额赤字会锁定 PAYG，但不会锁定仍然有效的订阅。充值会先偿还赤字，再增加可用单位。如有错误扣费、单位未到账或付款争议，请联系 support@tweetapi.com；申请补救不以购买更多单位为前提。请查看条款与退款信息（页面仅提供英文版）（英文）。法律规定的强制性权利不受限制。

错误处理

TweetAPI 使用标准 HTTP 状态码表示成功或失败。

常见错误代码

错误响应格式

所有错误都采用一致的格式：

{
  "statusCode": 400,
  "message": "Invalid username parameter"
}

最佳实践

1. 始终检查响应状态码
2. 记录错误响应以便调试
3. 为重试实现指数退避
4. 妥善处理速率限制

安全最佳实践

• 切勿公开分享 API 密钥或将其提交到版本控制系统。
• 定期轮换密钥以增强安全性。
• 在应用中使用环境变量存储 API 密钥。
• 通过控制台监控用量，以检测异常活动。

支持

如需帮助或有任何问题：

• 发送邮件至 support@tweetapi.com
• 在 Telegram 上联系 @tweetapi 支持团队