两行代码拿到一条帖子
没有密钥要传，也没有客户端要配置。构造出来直接调用。
from xcrap import Xcrap
with Xcrap() as xcrap:
tweet = xcrap.tweet("https://x.com/jack/status/20")
print(tweet.text) # just setting up my twttr
print(tweet.metrics.likes) # 308067Python 客户端
同一批 HTTP 接口之上的一层轻薄、带类型的封装。它做的事用 fetch 都能做；它只是省下你重写错误类、重试和格式协商的功夫。
安装
pip install xcrap-sdk或者，用你实际在用的：
uv add xcrap-sdkpoetry add xcrap-sdkpdm add xcrap-sdk
环境要求 · Python 3.9 或更高版本。一个依赖：httpx。
-
永远不需要密钥
没有要注册的东西，没有要塞进环境变量的东西，也没有谁不小心提交上去之后要轮换的东西。
-
一路都有类型
每个方法、每种响应形状都有完整声明，字段名写错是一条红波浪线，而不是运行时的意外。
-
内建 markdown
一个选项就能把任何响应变成可直接用于提示词的 markdown，并附上它会占用多少上下文的估算。
Markdown，附带 token 成本
每个读取方法都接受一个 markdown 选项。响应会以可直接放进提示词的字符串返回，客户端同时记录这段字符串大概要花多少 token，好让你在花掉之前先核对预算。
# Markdown, ready to drop into a prompt.
md = xcrap.tweet("https://x.com/jack/status/20", markdown=True)
# How many tokens that will cost, before you spend them.
print(xcrap.last_meta.markdown_tokens)
长贴与时间线
长贴会展开并按顺序返回，从第一条而不是最后一条开始。时间线通过游标自动翻页，你不必自己保存它们。
thread = xcrap.thread(
"https://x.com/naval/status/1002103360646823936",
)
print(thread.count) # 31
for post in thread.tweets:
print(post.text)
# And a timeline paginates itself.
for post in xcrap.iter_user_tweets("naval", limit=200):
print(post.id)
搜索，支持 X 自己的运算符
按你在 X 里输入的样子传入查询，运算符照写。返回一页结果和下一页的游标。搜索是所有方法中额度最紧的，一个精确的查询胜过五个宽泛的查询。
page = xcrap.search(
"from:nasa mars",
feed="latest", # or "top", "photos", "videos"
since="2026-01-01",
)
for post in page.tweets:
print(post.author.screen_name, post.text)
# The next page, when there is one.
if page.next_cursor:
xcrap.search("from:nasa mars", cursor=page.next_cursor)
错误是类型，不是状态码
每一种失败都是一个可以按名字捕获的类。404 表示帖子被删或不公开，429 带着距离窗口重置还有多少秒，而网络故障和拒绝是可以区分开的。
from xcrap import Xcrap, XcrapNotFound, XcrapRateLimited
try:
xcrap.tweet("https://x.com/jack/status/1")
except XcrapNotFound:
return None
except XcrapRateLimited as error:
# The client already knows when the window resets.
time.sleep(error.retry_after)
raise全部方法
它们都接受 format 和 markdown 选项，返回的形状也和 HTTP API 完全一致。
tweet(url, **opts)- 一条帖子，完整解析：正文、作者、数据、媒体、投票，以及被引用的帖子。
thread(url, **opts)- 从长贴中的任意一条出发，按发布顺序展开整个长贴。
search(query, **opts)- 匹配查询的帖子——最新、热门、图片或视频——可限定日期范围。
replies(url, **opts)- 某条帖子的一页直接回复，按最多点赞或最新排序。
user(handle, **opts)- 一份主页：简介、各项计数、注册时间、认证、位置和网站。
user_tweets(handle, **opts)- 某个账号的一页帖子，附带下一页的游标。
iter_user_tweets(handle, limit=…)- 同上，但以生成器形式替你跟进游标，到达上限时停止。
user_history(handle, **opts)- 一次调用获取某账号最多一千条帖子，从新到旧，可限定日期范围。
followers(handle, **opts)- 关注某个账号的一页账号。
following(handle, **opts)- 某个账号所关注的一页账号。
trends(**opts)- 正在流行的内容，X 给出数量时一并带上。
media(url, **opts)- 所有附件，涵盖 X 编码出的每一档码率，以直链形式给出。
download_media(url, **opts)- 把其中一个文件以字节流返回，而不是给一个链接。
bulk(urls, **opts)- 一次请求最多五十条帖子。失效链接只会让它自己那一条失败。