Posts 模块（帖子）¶

posts 模块提供帖子的发布、删除和互动功能，包括点赞、取消点赞、转发和取消转发。

目录¶

posts create — 发布帖子
posts delete — 删除帖子
posts like — 点赞帖子
posts unlike — 取消点赞
posts retweet — 转发帖子
posts unretweet — 取消转发
posts check-status — 检测发帖能力

posts create — 发布帖子¶

发布新帖子（推文），支持纯文字、带图片/视频，以及回复现有帖子。

语法¶

x-api [全局 flags] posts create \
  --text <STRING> \
  [--media-ids <ID,ID,...>] \
  [--reply-to <TWEET_ID>]

参数¶

参数	类型	必填	说明
`--text <STRING>`	string	是	帖子文字内容，最大 280 字符（中文每个字算 1 字符）
`--media-ids <ID,...>`	string	否	逗号分隔的媒体 ID 列表（来自 `upload image` 命令），最多 4 张图片
`--reply-to <TWEET_ID>`	string	否	回复的帖子 ID（作为回复发布）

字符限制：Twitter 的 280 字符限制适用于所有语言。URL 自动缩短为 23 字符。

纯文字示例¶

x-api --cookies-file cookies.txt posts create \
  --text "Hello from x-api! #rust #automation"

输出：

{"success":true,"data":{"tweet_id":"1811234567890123456","text":"Hello from x-api! #rust #automation","author_id":"6253282","created_at":"2026-04-17T10:45:00Z","url":"https://x.com/i/status/1811234567890123456"},"error":null,"meta":{"module":"posts","action":"create","elapsed_ms":612,"timestamp":"2026-04-17T10:45:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

带图片示例¶

# 先上传图片
media_id=$(x-api --cookies-file cookies.txt upload image \
  --file screenshot.png --category tweet-image | jq -r '.data.media_id_string')

# 发布带图片的帖子
x-api --cookies-file cookies.txt posts create \
  --text "看看这个截图" \
  --media-ids "$media_id"

回复帖子示例¶

x-api --cookies-file cookies.txt posts create \
  --text "同意！Rust 的类型系统真的很强大。" \
  --reply-to 1811234567890123456

失败示例¶

{"success":false,"data":null,"error":{"code":"CONTENT_VIOLATION","message":"帖子内容被 Twitter 检测为垃圾内容或违规","retryable":false,"retry_after_secs":null,"docs_url":null,"recovery_actions":["修改帖子内容后重试","检查是否包含违禁词或链接"],"issue_url":null,"details":{"http_status":403}},"meta":{"module":"posts","action":"create","elapsed_ms":389,"timestamp":"2026-04-17T10:46:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

data 字段说明¶

字段	类型	说明
`tweet_id`	string	新帖子的 ID（snowflake）
`text`	string	实际发布的文字内容
`author_id`	string	发布者的用户 ID
`created_at`	string	发布时间（ISO 8601 UTC）
`url`	string	帖子直达链接

常见错误¶

错误码	原因	解决方法
`INVALID_ARGS`	文字超过 280 字符	截断文本
`INVALID_ARGS`	图片数量超过 4 张	最多 4 个 media-id
`CONTENT_VIOLATION`	内容被判定为违规	修改内容
`DUPLICATE`	重复发布相同内容	Twitter 防重复发帖，修改内容
`MEDIA_UPLOAD_FAILED`	media_id 无效或已过期	重新上传图片

posts delete — 删除帖子¶

删除指定的帖子。只能删除自己发布的帖子。

语法¶

x-api [全局 flags] posts delete --id <TWEET_ID>

参数¶

参数	类型	必填	说明
`--id <TWEET_ID>`	string	是	要删除的帖子 ID

成功示例¶

x-api --cookies-file cookies.txt posts delete --id 1811234567890123456

输出：

{"success":true,"data":{"tweet_id":"1811234567890123456","deleted":true},"error":null,"meta":{"module":"posts","action":"delete","elapsed_ms":298,"timestamp":"2026-04-17T10:45:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

失败示例¶

{"success":false,"data":null,"error":{"code":"NOT_FOUND","message":"帖子 1811234567890123456 不存在或已被删除","retryable":false,"retry_after_secs":null,"docs_url":null,"recovery_actions":["确认帖子 ID 是否正确","确认帖子是否属于当前账号"],"issue_url":null,"details":{"http_status":404}},"meta":{"module":"posts","action":"delete","elapsed_ms":201,"timestamp":"2026-04-17T10:46:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

data 字段说明¶

字段	类型	说明
`tweet_id`	string	已删除的帖子 ID
`deleted`	bool	固定为 `true`

posts like — 点赞帖子¶

对指定帖子点赞。

语法¶

x-api [全局 flags] posts like --id <TWEET_ID>

参数¶

参数	类型	必填	说明
`--id <TWEET_ID>`	string	是	要点赞的帖子 ID

幂等性说明¶

重复点赞行为：Twitter API 对重复点赞返回成功（不报错）。CLI 同样返回 success: true。因此可以安全地重复调用 posts like，不会产生副作用。

成功示例¶

x-api --cookies-file cookies.txt posts like --id 1811234567890123456

输出：

{"success":true,"data":{"tweet_id":"1811234567890123456","liked":true},"error":null,"meta":{"module":"posts","action":"like","elapsed_ms":215,"timestamp":"2026-04-17T10:45:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

失败示例¶

{"success":false,"data":null,"error":{"code":"NOT_FOUND","message":"帖子不存在或已删除","retryable":false,"retry_after_secs":null,"docs_url":null,"recovery_actions":["确认帖子 ID 是否正确"],"issue_url":null,"details":{"http_status":404}},"meta":{"module":"posts","action":"like","elapsed_ms":187,"timestamp":"2026-04-17T10:46:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

data 字段说明¶

字段	类型	说明
`tweet_id`	string	已点赞的帖子 ID
`liked`	bool	固定为 `true`

posts unlike — 取消点赞¶

取消对指定帖子的点赞。

语法¶

x-api [全局 flags] posts unlike --id <TWEET_ID>

参数¶

参数	类型	必填	说明
`--id <TWEET_ID>`	string	是	要取消点赞的帖子 ID

幂等性说明¶

重复取消点赞同样返回成功，与 posts like 行为对称。

成功示例¶

x-api --cookies-file cookies.txt posts unlike --id 1811234567890123456

输出：

{"success":true,"data":{"tweet_id":"1811234567890123456","liked":false},"error":null,"meta":{"module":"posts","action":"unlike","elapsed_ms":231,"timestamp":"2026-04-17T10:45:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

posts retweet — 转发帖子¶

纯转发（Repost / GraphQL CreateRetweet）。不是引用转发（Quote）；带评论的引用请用 posts create 的引用能力。

协议 body 仅 variables.tweet_id。网页对推广/广告帖可能附带 engagement_request/impression_id，CLI/core 不发送这些字段。

语法¶

x-api [全局 flags] posts retweet --id <TWEET_ID>

参数¶

参数	类型	必填	说明
`--id <TWEET_ID>`	string	是	要转发的帖子 ID

成功示例¶

x-api --cookies-file cookies.txt posts retweet --id 1811234567890123456

输出（外层 envelope 表示 HTTP/客户端层 Ok；业务成败看 data.success）：

{"success":true,"data":{"success":true,"source_tweet_id":"1811234567890123456","retweet_id":"1811234567890123999","error_msg":"","http_status":200},"error":null,"meta":{"module":"posts","action":"retweet","elapsed_ms":334,"timestamp":"2026-04-17T10:45:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

业务失败示例（已转发 / GraphQL 错误，HTTP 仍可能为 200）¶

{"success":true,"data":{"success":false,"source_tweet_id":"1811234567890123456","retweet_id":null,"error_msg":"You have already retweeted this Tweet.","http_status":200},"error":null,"meta":{"module":"posts","action":"retweet","elapsed_ms":198,"timestamp":"2026-04-17T10:46:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

data 字段说明（`RetweetResult`）¶

字段	类型	说明
`success`	bool	业务是否成功
`source_tweet_id`	string	被转发的原帖子 ID
`retweet_id`	string \| null	产生的转发帖子 ID（成功时有值）
`error_msg`	string	失败原因
`http_status`	number	上游 HTTP 状态码

posts unretweet — 取消转发¶

取消对指定帖子的转发（GraphQL DeleteRetweet）。

成功判定与网页一致：HTTP 200 且 data.unretweet.source_tweet_results.result 存在；GraphQL errors（即便 HTTP 200）→ data.success=false。

语法¶

x-api [全局 flags] posts unretweet --id <TWEET_ID>

参数¶

参数	类型	必填	说明
`--id <TWEET_ID>`	string	是	原帖子 ID（非转发产生的 retweet_id）

成功示例¶

x-api --cookies-file cookies.txt posts unretweet --id 1811234567890123456

输出：

{"success":true,"data":{"success":true,"tweet_id":"1811234567890123456","error_msg":"","http_status":200},"error":null,"meta":{"module":"posts","action":"unretweet","elapsed_ms":287,"timestamp":"2026-04-17T10:45:00Z","cli_version":"1.0.0","schema_version":"1.0"}}

data 字段说明（`DeleteTweetResult`）¶

字段	类型	说明
`success`	bool	业务是否成功
`tweet_id`	string	原帖子 ID
`error_msg`	string	失败原因
`http_status`	number	上游 HTTP 状态码

posts clear-bookmarks — 清空所有书签¶

语法¶

x-api posts clear-bookmarks

无参数。一次性清空当前账号所有书签，不可撤销。

成功示例¶

$ x-api --cookies-file cookies.txt posts clear-bookmarks
{"success":true,"data":{"success":true,"message":"Done","error_msg":"","http_status":200},"meta":{"module":"posts","action":"clear-bookmarks","duration_ms":890}}

data 字段说明¶

字段	类型	说明
`success`	bool	是否成功
`message`	string	服务端返回的状态消息（成功时为 `"Done"`）

⚠️ 不可撤销：此操作会立即清空所有书签。

posts check-status — 检测发帖能力¶

语法¶

x-api posts check-status

无参数。只读拉取一次 HomeTimeline 判定当前账号能否发帖，不发帖、不消耗写配额、不触发写风控。

成功示例（账号被永久只读封禁）¶

$ echo "$COOKIES" | x-api posts check-status --cookies-stdin
{"success":true,"data":{"status":"ReadOnlySuspended","writable":false,"reason":"After careful review, we determined your account broke the X Rules. Your account is permanently in read-only mode...","http_status":200},"meta":{"module":"posts","action":"check-status","elapsed_ms":1900}}

data 字段说明¶

字段	类型	说明
`status`	string	账号状态枚举，见下表
`writable`	bool	是否可发帖（等价于 `status == "Writable"`）
`reason`	string	封禁横幅正文或错误消息，正常时为空串
`http_status`	u16	HomeTimeline 请求的 HTTP 状态码

status 取值¶

值	含义	判据
`Writable`	可正常发帖	未检测到封禁/锁定信号
`ReadOnlySuspended`	永久只读封禁，不能发/转/赞，需申诉	HomeTimeline 注入 `component == "suspended-prompt"` 横幅
`Locked`	账号被锁定，需完成验证	GraphQL error 326
`LoginInvalid`	登录态失效（cookies/ct0/auth_token 无效或过期）	HTTP 401 或 error 32/89
`HardSuspended`	账号被停用（硬封，读也受限）	error 64
`Unknown`	无法判定	返回了非预期结构

⚠️ 边界：软性写限流（日限 error 344、反爬 226）只读探测不到，这类只有真正发帖才会暴露，本命令会返回 Writable。要 100% 确认写权限，需实际发一条帖看返回码。

常见错误汇总¶

错误码	触发命令	典型场景
`INVALID_ARGS`	create	文字超过 280 字符，或 media-ids 超过 4 个
`NOT_FOUND`	delete/like/unlike/retweet/unretweet	帖子不存在或已删除
`DUPLICATE`	retweet	重复转发同一帖子
`CONTENT_VIOLATION`	create	内容被判定为违规
`MEDIA_UPLOAD_FAILED`	create	media_id 无效或过期
`AUTH_FAILED`	所有命令	cookies 过期
`RATE_LIMIT`	所有命令	请求过于频繁

Posts 模块（帖子）¶

目录¶

posts create — 发布帖子¶

语法¶

参数¶

纯文字示例¶

带图片示例¶

回复帖子示例¶

失败示例¶

data 字段说明¶

常见错误¶

posts delete — 删除帖子¶

语法¶

参数¶

成功示例¶

失败示例¶

data 字段说明¶

posts like — 点赞帖子¶

语法¶

参数¶

幂等性说明¶

成功示例¶

失败示例¶

data 字段说明¶

posts unlike — 取消点赞¶

语法¶

参数¶

幂等性说明¶

成功示例¶

posts retweet — 转发帖子¶

语法¶

参数¶

成功示例¶

业务失败示例（已转发 / GraphQL 错误，HTTP 仍可能为 200）¶

data 字段说明（RetweetResult）¶

posts unretweet — 取消转发¶

语法¶

参数¶

成功示例¶

data 字段说明（DeleteTweetResult）¶

posts clear-bookmarks — 清空所有书签¶

语法¶

成功示例¶

data 字段说明¶

posts check-status — 检测发帖能力¶

语法¶

成功示例（账号被永久只读封禁）¶

data 字段说明¶

status 取值¶

常见错误汇总¶

data 字段说明（`RetweetResult`）¶

data 字段说明（`DeleteTweetResult`）¶