用途
X API 技能用于以编程方式与 X(Twitter)进行交互,涵盖发布、读取、搜索和分析。当用户希望以程序方式发布推文或推文串、读取时间线/提及/用户数据、搜索内容或趋势、构建 X 集成或机器人、进行互动分析,或说出“post to X”“tweet”“X API”“Twitter API”等指令时,可激活该技能。
认证方式
技能区分两种认证模式:
- OAuth 2.0 Bearer Token(App-Only):最适合读取密集型操作、搜索和公开数据。通过环境变量
X_BEARER_TOKEN配置,请求头使用Authorization: Bearer <token>。 - OAuth 1.0a(用户上下文):发布推文、管理账号、私信以及任何写入流程所必需。需要配置
X_CONSUMER_KEY、X_CONSUMER_SECRET、X_ACCESS_TOKEN、X_ACCESS_TOKEN_SECRET。旧版别名如X_API_KEY、X_API_SECRET、X_ACCESS_SECRET可能存在于旧设置中,但新流程建议使用X_CONSUMER_*和X_ACCESS_TOKEN_SECRET命名。
主要能力
技能提供以下核心操作的代码示例:
- 发布单条推文:向
https://api.x.com/2/tweets发送 POST 请求,携带{"text": "..."}。 - 发布推文串:通过循环发布,每条推文使用
reply.in_reply_to_tweet_id指向上一条推文 ID,返回推文 ID 列表。 - 读取用户时间线:请求
https://api.x.com/2/users/{user_id}/tweets,可指定max_results和tweet.fields(如created_at,public_metrics)。 - 搜索推文:请求
https://api.x.com/2/tweets/search/recent,支持查询语法如from:username -is:retweet。 - 拉取近期原创推文用于声音建模:查询
from:username -is:retweet -is:reply,获取created_at,public_metrics字段。 - 按用户名获取用户:请求
https://api.x.com/2/users/by/username/{username},可指定user.fields。 - 上传媒体并发布:媒体上传使用 v1.1 端点
https://upload.twitter.com/1.1/media/upload.json,获取media_id_string后,在发布推文时通过media.media_ids附带。
速率限制
X API 的速率限制因端点、认证方式和账号层级而异,且会随时间变化。技能建议:在硬编码假设前查看当前 X 开发者文档;在运行时读取 x-rate-limit-remaining 和 x-rate-limit-reset 响应头;自动退避而非依赖代码中的静态表。示例代码展示了当剩余次数低于 5 时,根据重置时间计算等待秒数。
错误处理
技能提供针对发布推文的错误处理示例:状态码 201 表示成功并返回推文 ID;429 表示速率受限,读取 x-rate-limit-reset 并抛出异常;403 表示禁止访问,提示检查权限;其他状态码抛出包含状态码和响应文本的异常。
安全
技能强调:绝不硬编码令牌,使用环境变量或 .env 文件;绝不提交 .env 文件,将其加入 .gitignore;令牌泄露后轮换,在 developer.x.com 重新生成;不需要写入权限时使用只读令牌;安全存储 OAuth 密钥,不要放在源代码或日志中。
与内容引擎集成
技能建议结合 brand-voice 和 content-engine 生成平台原生内容,然后通过 X API 发布。流程包括:在需要匹配声音时拉取近期原创推文;构建或复用 VOICE PROFILE;使用 content-engine 生成 X 原生格式内容;验证长度和推文串结构;除非用户明确要求立即发布,否则返回草稿供审批;仅在审批后通过 X API 发布;通过 public_metrics 跟踪互动。
相关技能
- brand-voice:从真实的 X 和站点/来源材料构建可复用的声音档案。
- content-engine:为 X 生成平台原生内容。
- crosspost:将内容分发到 X、LinkedIn 和其他平台。
- connections-optimizer:在起草网络驱动外联前重组 X 图谱。
限制
资料未提供具体的速率限制数值、账号层级要求、价格或收费信息、支持的平台版本范围,以及除示例外的完整端点列表。这些内容暂未提供。