twitterapi-io

twitterapi.io

由 twitterapi.io 团队维护的官方技能。此技能中的路径、参数和请求体字段均已根据线上后端验证。

何时使用此技能

当用户需要以下任一操作时触发：

• 获取推文、用户资料、关注者／正在关注的用户、趋势、回复、引用推文、转推者、文章
• 高级推文搜索（X 操作符、日期范围、互动筛选条件）
• 近实时监控用户或筛选规则
• 发布／删除／点赞／转推／收藏／引用推文／回复／关注／发送私信／安排推文
• 更新资料／头像／横幅、上传媒体
• 创建／加入／退出社区、管理列表、举报内容
• 任何涉及 twitterapi.io、api.twitterapi.io、x-api-key、login_cookies 或无需 OAuth 的 X API 的内容

核心信息

基础 URL	https://api.twitterapi.io
前缀	大多数端点使用 /twitter/...；实时监控／Webhook 使用 /oapi/x_user_stream/... 和 /oapi/tweet_filter/...；余额查询使用 /oapi/my/info
身份验证请求头	x-api-key: YOUR_KEY
控制面板	https://twitterapi.io/dashboard
文档	https://docs.twitterapi.io
速率限制	每个客户端约 200 req/s
定价	每 1k 条推文约 $0.15，每 1k 个资料约 $0.18，最低 $0.00015

⚠️ 两条容易踩坑的规则

规则 1 — 参数命名因端点而异

没有通用的 snake_case 或 camelCase 规则。示例（均正确）：

• /twitter/user/followers?userName=（camel）
• /twitter/user/verifiedFollowers?user_id=（snake）
• /twitter/user/articles?username=（全小写）
• /twitter/tweets?tweet_ids=（snake），但 /twitter/tweet/replies?tweetId=（camel）
• /twitter/list/tweets_timeline?listId=（camel），但 /twitter/list/members?list_id=（snake）

请从 references/endpoints.md 中复制准确的参数名称。不要统一格式。

规则 2 — 写入操作的请求体需要包含三项，而非两项

每个写入端点都需要：

1. login_cookies（复数，不是 login_cookie）——来自 /twitter/user_login_v2 的 base64 编码 JSON
2. proxy（HTTP/SOCKS 代理 URL——在控制面板中配置）
3. 特定操作所需的字段，几乎总是 snake_case（tweet_id、user_id）

此外还要注意这些字段名称陷阱：

• create_tweet_v2 的文本字段是 tweet_text（不是 text）；回复字段是 reply_to_tweet_id（不是 in_reply_to_tweet_id）
• update_profile_v2 使用 description（不是 bio）
• bookmarks_v2 使用 count（不是 pageSize）
• send_dm_to_user：user_id + text；可选的 media_id（单数）
• 添加监控使用 x_user_name；移除监控使用 id_for_user（不同端点的字段不同！）

完整的请求体结构请参阅 references/write-operations.md。

规则 3 — 响应结构因端点而异

• 使用 data 包装：user/info、user_about、last_tweets、tweet_timeline、trends、check_follow_relationship → r["data"]["..."]
• 带外层结构的扁平响应：followers、followings、replies、mentions、community/tweets → r["followers"]、r["tweets"] 等
• 不带外层结构的扁平响应：advanced_search、thread_context、user/search、get_tweets_from_all_community → 直接返回 {tweets[], has_next_page, next_cursor}
• 命名的顶层字段：community/info → r["community_info"]；batch_info_by_ids → r["users"]
• oapi/my/info → {recharge_credits, total_bonus_credits}（无状态包装）

建议进行防御式访问：r.get("tweets", r.get("data", {}).get("tweets", []))。

安全

切勿将 API 密钥硬编码。请从环境变量 TWITTERAPI_IO_KEY 中读取。若缺失，请询问用户。

最简可用示例

curl -s "https://api.twitterapi.io/twitter/user/info?userName=elonmusk" \
  -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/user/info",
                 headers=HEADERS,
                 params={"userName": "elonmusk"},
                 timeout=30)
r.raise_for_status()
d = r.json()["data"]
print(f"{d['userName']} — {d['followers']:,} followers")

端点速查

读取操作（仅需 API 密钥）。准确的参数名称——请照原样复制。

能力	方法	路径和关键参数
按屏幕名称获取用户	GET	/twitter/user/info?userName=
扩展简介	GET	/twitter/user_about?userName=
按 ID 批量获取用户	GET	/twitter/user/batch_info_by_ids?userIds=
搜索用户	GET	/twitter/user/search?query=（不是 keyword）
最近推文	GET	/twitter/user/last_tweets?userName=（或 userId=）
按 ID 获取时间线	GET	/twitter/user/tweet_timeline?userId=
用户文章	GET	/twitter/user/articles?username=（全小写）
用户提及	GET	/twitter/user/mentions?userName=
关注者	GET	/twitter/user/followers?userName=&pageSize=200
已认证的关注者	GET	/twitter/user/verifiedFollowers?user_id=（snake_case）
正在关注	GET	/twitter/user/followings?userName=
检查关注关系	GET	/twitter/user/check_follow_relationship?source_user_name=&target_user_name=
按 ID 获取推文	GET	/twitter/tweets?tweet_ids=（snake_case）
推文回复	GET	/twitter/tweet/replies?tweetId=
回复（可排序）	GET	/twitter/tweet/replies/v2?tweetId=&queryType=Latest
引用推文	GET	/twitter/tweet/quotes?tweetId=
转推者	GET	/twitter/tweet/retweeters?tweetId=
话题串上下文	GET	/twitter/tweet/thread_context?tweetId=
文章内容	GET	/twitter/article?tweet_id=（snake_case）
高级搜索	GET	/twitter/tweet/advanced_search?query=
批量高级搜索	POST	/twitter/tweet/bulk_advanced_search 请求体 {queries:[{query,queryType?,cursor?}]}
趋势	GET	/twitter/trends?woeid=1&count=30
Space 详情	GET	/twitter/spaces/detail?space_id=（snake_case）
列表推文（带筛选条件）	GET	/twitter/list/tweets?listId=
列表推文时间线	GET	/twitter/list/tweets_timeline?listId=
列表成员 / 关注者	GET	/twitter/list/{members,followers}?list_id=（snake_case）
社区信息	GET	/twitter/community/info?community_id=
社区推文 / 成员 / 版主	GET	/twitter/community/{tweets,members,moderators}?community_id=
所有社区的 firehose	GET	/twitter/community/get_tweets_from_all_community?query=（必填！）
账户余额	GET	/oapi/my/info

实时监控（/oapi/x_user_stream/*）。各端点的字段名称不同！

能力	方法	路径和请求体
添加监控	POST	/oapi/x_user_stream/add_user_to_monitor_tweet 请求体 {x_user_name} ← 不是 user_id
列出监控项	GET	/oapi/x_user_stream/get_user_to_monitor_tweet（加上 query_type 0/1/2）
移除监控	POST	/oapi/x_user_stream/remove_user_to_monitor_tweet 请求体 {id_for_user} ← 与添加时的字段不同

Webhook 筛选规则（/oapi/tweet_filter/*）：

能力	方法	路径和请求体
添加规则	POST	/oapi/tweet_filter/add_rule 请求体 {tag, value, interval_seconds?=60}（范围 0.05–86400）
列出规则	GET	/oapi/tweet_filter/get_rules
更新规则	POST	/oapi/tweet_filter/update_rule 请求体 {rule_id, tag, value, interval_seconds?, is_effect?}
删除规则	DELETE	/oapi/tweet_filter/delete_rule 请求体 {rule_id}（JSON 请求体，不是查询参数）

写入操作——需要在请求体中提供 login_cookies + proxy。login_cookies 是从 /twitter/user_login_v2 获取的 base64(json(cookie_dict))。

能力	方法	路径	关键请求体字段（除 login_cookies+proxy 外）
登录 → cookies	POST	/twitter/user_login_v2	{user_name, email, password, totp_secret?, proxy}
创建推文	POST	/twitter/create_tweet_v2	tweet_text（必填）；可选 reply_to_tweet_id、quote_tweet_id、community_id、media_ids[]、schedule_for
删除	POST	/twitter/delete_tweet_v2	tweet_id
点赞 / 取消点赞	POST	/twitter/{like,unlike}_tweet_v2	tweet_id
转推	POST	/twitter/retweet_tweet_v2	tweet_id
收藏 / 取消收藏	POST	/twitter/{bookmark,unbookmark}_tweet_v2	tweet_id
列出收藏	POST	/twitter/bookmarks_v2	可选 count（默认 20，不是 pageSize）、cursor
关注 / 取消关注	POST	/twitter/{follow,unfollow}_user_v2	user_id
发送私信	POST	/twitter/send_dm_to_user	user_id、text、可选 media_id（单数）、reply_to_message_id
举报	POST	/twitter/report_v2	（tweet_id 或 user_id）、reason（枚举，见 endpoints.md）
上传媒体	POST	/twitter/upload_media_v2	multipart：file、可选 media_category、is_long_video
更新个人资料	PATCH	/twitter/update_profile_v2	JSON：至少包含 name、description（不是 bio！）、location、url 中的一个
更新头像/横幅	PATCH	/twitter/update_{avatar,banner}_v2	multipart：file
创建社群	POST	/twitter/create_community_v2	name、description（均必填）
加入 / 离开社群	POST	/twitter/{join,leave}_community_v2	community_id
删除社群	POST	/twitter/delete_community_v2	community_id、community_name（均必填）
添加列表成员	POST	/twitter/list/add_member_v2	list_id、user_id

准确的参数列表、响应结构和边缘情况，请参阅 references/endpoints.md。

常见模式

游标分页 — 使用 has_next_page

def iter_followers(user_name):
    cursor = ""
    while True:
        r = requests.get(f"{BASE}/twitter/user/followers",
                         headers=HEADERS,
                         params={"userName": user_name, "cursor": cursor, "pageSize": 200},
                         timeout=30).json()
        yield from r.get("followers", [])
        if not r.get("has_next_page"):
            break
        cursor = r.get("next_cursor") or ""

错误处理

# FastAPI-style 4xx/5xx
{ "detail": "tweet_id is required" }
{ "detail": [{"type":"missing","loc":["body","file"]}] }  # 422 on multipart

# Semantic 200 errors
{ "status": "error", "msg": "No active monitoring subscription" }

• 401 → x-api-key 无效或 login_cookies 已过期
• 402 → 在控制面板充值余额
• 429 → 请求频率受限；采用指数退避
• 400/422 → 查看 detail — 其中会指出缺失或错误的字段
• 500 → 临时错误；加入抖动后重试。如果重复出现，则参数名称有误

成本注意事项

在可能需要长时间分页的循环之前（大型账号的关注者、多年范围的高级搜索），预先估算成本；如果费用可能超过几美元，请与用户确认。以 $0.15/1k 的价格抓取 1 亿关注者，费用将超过 $15k。

反模式

• 不要假设所有参数都遵循统一的大小写规则 — 请查阅 endpoints.md
• 不要使用 login_cookie（单数）— 正确的是复数形式 login_cookies
• 不要在写入请求体中遗漏 proxy — 每个写入操作都需要它
• 不要为 create_tweet_v2 发送 text — 请使用 tweet_text
• 不要在 update_profile_v2 中使用 bio — 请使用 description
• 不要在 create_tweet_v2 中使用 in_reply_to_tweet_id — 正确的是 reply_to_tweet_id
• 不要向 upload_media_v2 / update_avatar_v2 / update_banner_v2 发送 JSON — 它们使用 multipart/form-data
• 不要在 bookmarks_v2 中使用 pageSize — 正确的是 count
• 不要在监控添加请求中发送 user_id — 应使用 x_user_name；移除请求使用 id_for_user
• 不要记录或提交 API 密钥、login_cookies、代理或 totp_secret
• 不要使用 developer.twitter.com / 官方 X OAuth — 此 API 可替代它们
• 不要轮询 /user/last_tweets 来实现“实时”监控 — 请使用 /oapi/tweet_filter/add_rule + webhook