twitterapi-io 只读技能

twitterapi.io（只读）

由 twitterapi.io 团队维护的只读技能。它仅覆盖公开的 X/Twitter 数据：从不登录 X 账户，不处理 cookie、密码或代理，从不发帖、点赞、关注或发送消息。

twitterapi.io 是一个独立的第三方 REST API，用于获取公开的 X 数据，与 X Corp. 无关。如果需要 X 官方的 API，请访问 https://developer.x.com。

何时使用此技能

• 使用 X 搜索操作符（from:、since_time:、min_faves:、lang: …）搜索帖子
• 查找用户资料、关注者、关注
• 获取用户的近期帖子、回复、引用帖子、转发者、帖子上下文
• 趋势、列表、社区
• 构建面板、研究数据集或监控公开数据

核心信息

基础 URL	https://api.twitterapi.io
认证请求头	x-api-key: YOUR_KEY（来自 https://twitterapi.io/dashboard）
文档	https://docs.twitterapi.io
定价	按调用付费，详见 https://twitterapi.io/pricing
托管 MCP 服务器	https://mcp.twitterapi.io/mcp（12 个只读工具）

安全性

从环境变量 TWITTERAPI_IO_KEY 读取 API 密钥。切勿硬编码、打印或提交。如果缺失，请要求用户在面板上创建一个。

最小示例

curl -s "https://api.twitterapi.io/twitter/user/info?userName=jack" \
  -H "x-api-key: $TWITTERAPI_IO_KEY"

import os, requests

BASE = "https://api.twitterapi.io"
HEADERS = {"x-api-key": os.environ["TWITTERAPI_IO_KEY"]}

r = requests.get(f"{BASE}/twitter/tweet/advanced_search",
                 headers=HEADERS,
                 params={"query": "from:jack", "queryType": "Latest"},
                 timeout=30)
r.raise_for_status()
for t in r.json().get("tweets", []):
    print(t["createdAt"], t["text"][:80])

读取端点

不同端点的参数名称可能不同（有些是驼峰式，有些是蛇形命名）。请完全按所示复制。

功能	方法	路径及关键参数
根据用户名查询用户	GET	/twitter/user/info?userName=
扩展资料	GET	/twitter/user_about?userName=
根据 ID 批量查询用户	GET	/twitter/user/batch_info_by_ids?userIds=
搜索用户	GET	/twitter/user/search?query=
最新帖子	GET	/twitter/user/last_tweets?userName=（或 userId=）
提及	GET	/twitter/user/mentions?userName=
关注者	GET	/twitter/user/followers?userName=&pageSize=200
关注	GET	/twitter/user/followings?userName=
根据 ID 查询帖子	GET	/twitter/tweets?tweet_ids=
回复	GET	/twitter/tweet/replies?tweetId=
引用帖子	GET	/twitter/tweet/quotes?tweetId=
转发者	GET	/twitter/tweet/retweeters?tweetId=
帖子上下文	GET	/twitter/tweet/thread_context?tweetId=
高级搜索	GET	/twitter/tweet/advanced_search?query=&queryType=Latest
趋势	GET	/twitter/trends?woeid=1
列表帖子	GET	/twitter/list/tweets?listId=
列表成员	GET	/twitter/list/members?list_id=
社区帖子	GET	/twitter/community/tweets?community_id=
账户余额	GET	/oapi/my/info

模式

分页

列表端点会返回 has_next_page 和 next_cursor。将 next_cursor 传回作为 cursor；当 has_next_page 为假时停止。始终设置一个页数限制，以防 bug 导致无限翻页。

错误

• 400 → 缺少必需参数或搜索查询无效（响应的 detail 字段会说明如何修复）
• 401 / 403 → x-api-key 缺失或错误
• 402 → 积分不足；停止并告知用户充值（不要重试）
• 429 → 请求频率受限；带退避重试
• 5xx → 临时性错误；带退避重试

成本意识

每次调用都会计费。在可能长时间运行的循环（例如获取大账户的所有关注者、查询数月的帖子）之前，请估算调用次数并确认用户同意。

反模式

• 不要规范化参数名称；直接从表格中复制
• 不要对 402 错误重试
• 不要记录或提交 API 密钥