接口参考

本页由 proto descriptor 与 docs/llms-metadata.json 自动生成，不会与契约漂移。 面向 AI 的等价内容见 llms-full.txt； 原始 proto 与其它语言的 stub 生成见 grpc/llms-full.txt。

通用约定

• 一端点一 RPC：写方法入参覆盖该端点全部可写字段；没有字段级 setter，也没有跨端点聚合。 Login 是唯一例外（跨端点状态机，需原子地产出并验证会话）。
• 完整状态往返：除 Login 外每个请求的首个字段都是 state，响应也带回刷新后的 state。
• proto3 optional：标 optional 的字段区分「不传」与「传空值」，不要用 "" / 0 / 空集合代替未传。
• 鉴权：gRPC metadata x-twitter-api-key + 请求消息里的 state。

AndroidApi

AndroidApi is the Android client-protocol surface. One endpoint = one RPC; Login is the sanctioned cross-endpoint exception (a login state machine that must atomically mint + verify session credentials).

Login

Login runs the full Android cold-start login and returns the complete AndroidAccountState. The caller MUST persist the returned device — later RPCs must not regenerate it.

• Python：x.android.AndroidClient.login
• 类型：write，幂等：否
• 状态：✅ 已验收（2026-08-11）
• 成功判据：返回的 AndroidAccountState.session 中 user_id / screen_name 与登录账号一致，且服务端已用 account/settings.json 正面复核同一账号。HTTP 2xx 或响应里出现某个 token 字段都不作为成功判据。
• 副作用：在 X 平台创建一个新的登录会话，可能触发风控与设备绑定；消耗账号的登录频次配额
• 说明：跨端点登录状态机，是「一端点一 RPC」的唯一受控例外。调用方必须持久化返回的完整状态（含设备），后续 RPC 禁止重新生成设备。

请求 LoginRequest

字段	类型	约束	说明
username (#1)	string	-	-
password (#2)	string	-	-
totp (#3)	string	-	totp is the current 2FA code; empty when the account has no 2FA.
version (#4)	string	optional	version selects the client build (default latest); optional.
proxy (#5)	string	optional	proxy dials upstream through this URL (http/https/socks5); optional.
attest_account_id (#6)	string	optional	attest_account_id binds attestation during the guest phase; optional.

响应 LoginResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-

MediaApi

MediaApi is the Android media-upload surface (upload.x.com).

UploadMedia

UploadMedia runs the segmented INIT→APPEND→FINALIZE flow and returns a media_id for CreatePost. Returns the refreshed state (attest re-minted).

• Python：account.media.upload
• 类型：write，幂等：否
• 状态：🔷 已实现，未真机验收
• 成功判据：响应 media_id 非空。
• 副作用：在 X 媒体服务上创建一份待引用的媒体对象
• 说明：尚未真机验收。分段 INIT→APPEND→FINALIZE 全流程在单个 RPC 内完成。media_id 有有效期，应尽快用于 CreatePost。

请求 UploadMediaRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
data (#2)	bytes	-	raw image bytes
mime_type (#3)	string	-	default image/jpeg
media_category (#4)	string	-	default tweet_image

响应 UploadMediaResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
media_id (#2)	string	-	-

PostsApi

PostsApi is the Android post-authoring + engagement surface (api.x.com GraphQL).

CreatePost

CreatePost publishes text (+ optional media_ids from UploadMedia).

• Python：account.posts.create
• 类型：write，幂等：否
• 状态：✅ 已验收（2026-08-11）
• 成功判据：响应 tweet.tweet_id 非空。
• 副作用：在目标账号下公开发布一条推文
• 说明：media_ids 来自 MediaApi/UploadMedia。重复调用会产生多条推文，重试前必须先确认上一次是否已成功。

请求 CreatePostRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
text (#2)	string	-	-
media_ids (#3)	string	repeated	-

响应 CreatePostResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
tweet (#2)	Tweet（见消息定义）	-	-

DeletePost

DeletePost deletes a tweet by id.

• Python：account.posts.delete
• 类型：write，幂等：是
• 状态：✅ 已验收（2026-08-11）
• 成功判据：RPC 正常返回且未抛出 gRPC 错误。
• 副作用：永久删除目标推文，不可恢复
• 说明：对已删除的推文重复调用不会产生新的副作用。

请求 DeletePostRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
tweet_id (#2)	string	-	-

响应 DeletePostResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-

Like

Like favorites a tweet.

• Python：account.posts.like
• 类型：write，幂等：是
• 状态：🔷 已实现，未真机验收
• 成功判据：RPC 正常返回且未抛出 gRPC 错误。
• 副作用：在目标推文上留下本账号的点赞记录，对方可见
• 说明：尚未真机验收。重复点赞不会叠加。

请求 EngageRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
tweet_id (#2)	string	-	-

响应 EngageResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)

Quote

Quote posts text quoting a tweet (returns the new tweet).

• Python：account.posts.quote
• 类型：write，幂等：否
• 状态：🔷 已实现，未真机验收
• 成功判据：响应 tweet.tweet_id 非空。
• 副作用：公开发布一条引用推文
• 说明：尚未真机验收。

请求 QuoteRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
quoted_tweet_id (#2)	string	-	-
text (#3)	string	-	-
media_ids (#4)	string	repeated	-

响应 CreatePostResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
tweet (#2)	Tweet（见消息定义）	-	-

Reply

Reply posts text as a reply to a tweet (returns the new tweet).

• Python：account.posts.reply
• 类型：write，幂等：否
• 状态：🔷 已实现，未真机验收
• 成功判据：响应 tweet.tweet_id 非空。
• 副作用：在目标推文下公开发布一条回复
• 说明：尚未真机验收。

请求 ReplyRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
in_reply_to_tweet_id (#2)	string	-	-
text (#3)	string	-	-
media_ids (#4)	string	repeated	-

响应 CreatePostResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
tweet (#2)	Tweet（见消息定义）	-	-

Retweet

Retweet reposts a tweet.

• Python：account.posts.retweet
• 类型：write，幂等：是
• 状态：🔷 已实现，未真机验收
• 成功判据：RPC 正常返回且未抛出 gRPC 错误。
• 副作用：在本账号时间线公开转发目标推文
• 说明：尚未真机验收。

请求 EngageRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
tweet_id (#2)	string	-	-

响应 EngageResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)

Unlike

Unlike removes a favorite.

• Python：account.posts.unlike
• 类型：write，幂等：是
• 状态：🔷 已实现，未真机验收
• 成功判据：RPC 正常返回且未抛出 gRPC 错误。
• 副作用：撤销本账号对目标推文的点赞
• 说明：尚未真机验收。

请求 EngageRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
tweet_id (#2)	string	-	-

响应 EngageResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)

Unretweet

Unretweet removes a repost (tweet_id = the ORIGINAL/source tweet id).

• Python：account.posts.unretweet
• 类型：write，幂等：是
• 状态：🔷 已实现，未真机验收
• 成功判据：RPC 正常返回且未抛出 gRPC 错误。
• 副作用：撤销本账号对目标推文的转发
• 说明：尚未真机验收。★入参 tweet_id 必须是原始推文 id，不是转发产生的推文 id。

请求 EngageRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
tweet_id (#2)	string	-	-

响应 EngageResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)

TimelineApi

TimelineApi is the Android timeline-read surface.

HomeTimeline

HomeTimeline returns the launch home feed (raw).

• Python：account.timeline.home
• 类型：read，幂等：是
• 状态：🔷 已实现，未真机验收
• 成功判据：响应 raw_json 为可解析的非空 JSON。
• 说明：尚未真机验收。时间线是体量大且易变的 GraphQL 树，以 raw_json 往返，调用方自行解析所需字段。

请求 HomeTimelineRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-

响应 TimelineResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
raw_json (#2)	string	-	untouched GraphQL timeline payload

UserTweets

UserTweets returns a user's own posts timeline (raw).

• Python：account.timeline.user_tweets
• 类型：read，幂等：是
• 状态：🔷 已实现，未真机验收
• 成功判据：响应 raw_json 为可解析的非空 JSON。
• 说明：尚未真机验收。

请求 UserTweetsRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
rest_id (#2)	string	-	-

响应 TimelineResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
raw_json (#2)	string	-	untouched GraphQL timeline payload

UsersApi

UsersApi is the Android profile-read surface.

Me

Me returns the logged-in user's own profile.

• Python：account.users.me
• 类型：read，幂等：是
• 状态：🔷 已实现，未真机验收
• 成功判据：响应 user 非空且 rest_id 与当前会话账号一致。
• 说明：尚未真机验收。返回关键字段 + 原始 raw_json。

请求 MeRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-

响应 UserResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
user (#2)	User（见消息定义）	-	-

ProfileAnalytics

ProfileAnalytics returns raw impressions over [from_time,to_time] (RFC3339 Z).

• Python：account.users.profile_analytics
• 类型：read，幂等：是
• 状态：🔷 已实现，未真机验收
• 成功判据：响应 raw_json 为可解析的非空 JSON。
• 说明：尚未真机验收。时间区间用 RFC3339 Z 格式。

请求 ProfileAnalyticsRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
rest_id (#2)	string	-	-
from_time (#3)	string	-	RFC3339 Z
to_time (#4)	string	-	-

响应 RawResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
raw_json (#2)	string	-	-

ProfileModules

ProfileModules returns the raw profile-page modules.

• Python：account.users.profile_modules
• 类型：read，幂等：是
• 状态：🔷 已实现，未真机验收
• 成功判据：响应 raw_json 为可解析的非空 JSON。
• 说明：尚未真机验收。返回未经处理的 GraphQL 结构，字段随上游变动，调用方需自行做容错解析。

请求 ProfileModulesRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
rest_id (#2)	string	-	-

响应 RawResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
raw_json (#2)	string	-	-

UserByRestID

UserByRestID returns a profile by numeric rest_id.

• Python：account.users.by_rest_id
• 类型：read，幂等：是
• 状态：🔷 已实现，未真机验收
• 成功判据：响应 user 非空。
• 说明：尚未真机验收。入参是数字 rest_id，不是 @screen_name。

请求 UserByRestIDRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
rest_id (#2)	string	-	-

响应 UserResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
user (#2)	User（见消息定义）	-	-

消息定义

Account

proto 全名：twitter.android.v1.Account

字段	类型	约束	说明
username (#1)	string	-	-
password (#2)	string	-	plaintext — server-side only, never logged
totp_seed (#3)	string	-	plaintext 2FA secret; optional

AndroidAccountState

AndroidAccountState is the full round-trip identity for the android namespace. Mirrors identity.AndroidAccountState (OAuth 1.0a session).

proto 全名：twitter.android.v1.AndroidAccountState

字段	类型	约束	说明
account (#1)	Account（见消息定义）	-	-
device (#2)	AndroidDevice（见消息定义）	-	-
app_version (#3)	string	-	-
proxy (#4)	string	-	-
session (#5)	AndroidSession（见消息定义）	-	-

AndroidDevice

proto 全名：twitter.android.v1.AndroidDevice

字段	类型	约束	说明
client_uuid (#1)	string	-	-
device_id (#2)	string	-	-
ad_id (#3)	string	-	-
model (#4)	string	-	-
manufacturer (#5)	string	-	-
brand (#6)	string	-	-
board (#7)	string	-	-
os_version (#8)	string	-	-
build_year (#9)	string	-	-
language (#10)	string	-	-
timezone (#11)	string	-	-
sec_patch (#12)	string	-	-
limit_ad_tracking (#13)	string	-	-
attest_token (#14)	string	-	-

AndroidSession

proto 全名：twitter.android.v1.AndroidSession

字段	类型	约束	说明
oauth_token (#1)	string	-	-
oauth_secret (#2)	string	-	plaintext — server-side only, never logged
cookies (#3)	string	repeated	-
user_id (#4)	string	-	-
screen_name (#5)	string	-	-

CreatePostRequest

proto 全名：twitter.android.v1.CreatePostRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
text (#2)	string	-	-
media_ids (#3)	string	repeated	-

CreatePostResponse

proto 全名：twitter.android.v1.CreatePostResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
tweet (#2)	Tweet（见消息定义）	-	-

DeletePostRequest

proto 全名：twitter.android.v1.DeletePostRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
tweet_id (#2)	string	-	-

DeletePostResponse

proto 全名：twitter.android.v1.DeletePostResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-

EngageRequest

EngageRequest is the shared input for like/unlike/retweet/unretweet. For Unretweet, tweet_id is the ORIGINAL (source) tweet id.

proto 全名：twitter.android.v1.EngageRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
tweet_id (#2)	string	-	-

EngageResponse

proto 全名：twitter.android.v1.EngageResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)

HomeTimelineRequest

proto 全名：twitter.android.v1.HomeTimelineRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-

LoginRequest

proto 全名：twitter.android.v1.LoginRequest

字段	类型	约束	说明
username (#1)	string	-	-
password (#2)	string	-	-
totp (#3)	string	-	totp is the current 2FA code; empty when the account has no 2FA.
version (#4)	string	optional	version selects the client build (default latest); optional.
proxy (#5)	string	optional	proxy dials upstream through this URL (http/https/socks5); optional.
attest_account_id (#6)	string	optional	attest_account_id binds attestation during the guest phase; optional.

LoginResponse

proto 全名：twitter.android.v1.LoginResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-

MeRequest

proto 全名：twitter.android.v1.MeRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-

ProfileAnalyticsRequest

proto 全名：twitter.android.v1.ProfileAnalyticsRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
rest_id (#2)	string	-	-
from_time (#3)	string	-	RFC3339 Z
to_time (#4)	string	-	-

ProfileModulesRequest

proto 全名：twitter.android.v1.ProfileModulesRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
rest_id (#2)	string	-	-

QuoteRequest

proto 全名：twitter.android.v1.QuoteRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
quoted_tweet_id (#2)	string	-	-
text (#3)	string	-	-
media_ids (#4)	string	repeated	-

RawResponse

RawResponse round-trips state + the untouched GraphQL data (raw fallback).

proto 全名：twitter.android.v1.RawResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
raw_json (#2)	string	-	-

ReplyRequest

proto 全名：twitter.android.v1.ReplyRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
in_reply_to_tweet_id (#2)	string	-	-
text (#3)	string	-	-
media_ids (#4)	string	repeated	-

TimelineResponse

proto 全名：twitter.android.v1.TimelineResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
raw_json (#2)	string	-	untouched GraphQL timeline payload

Tweet

Tweet is a posted/read tweet. Structured key fields + raw_json fallback (charter interview #8: 关键字段 + 保留 raw) — on GraphQL schema drift, parse raw_json instead of changing this message. CreatePost fills only tweet_id; reads (B3) fill the rest.

proto 全名：twitter.common.v1.Tweet

字段	类型	约束	说明
tweet_id (#1)	string	-	rest_id
text (#2)	string	-	-
user_id (#3)	string	-	author rest_id
screen_name (#4)	string	-	-
created_at (#5)	int64	-	unix seconds; 0 if unknown
favorite_count (#6)	int64	-	-
retweet_count (#7)	int64	-	-
reply_count (#8)	int64	-	-
quote_count (#9)	int64	-	-
view_count (#10)	int64	-	-
raw_json (#15)	string	-	raw_json is the untouched GraphQL tweet_results payload (drift safety).

UploadMediaRequest

proto 全名：twitter.android.v1.UploadMediaRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
data (#2)	bytes	-	raw image bytes
mime_type (#3)	string	-	default image/jpeg
media_category (#4)	string	-	default tweet_image

UploadMediaResponse

proto 全名：twitter.android.v1.UploadMediaResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
media_id (#2)	string	-	-

User

User is a read profile (B3). Structured key fields + raw_json fallback.

proto 全名：twitter.common.v1.User

字段	类型	约束	说明
user_id (#1)	string	-	rest_id
screen_name (#2)	string	-	-
name (#3)	string	-	-
description (#4)	string	-	-
followers_count (#5)	int64	-	-
following_count (#6)	int64	-	-
tweet_count (#7)	int64	-	-
verified (#8)	bool	-	-
raw_json (#15)	string	-	-

UserByRestIDRequest

proto 全名：twitter.android.v1.UserByRestIDRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
rest_id (#2)	string	-	-

UserResponse

proto 全名：twitter.android.v1.UserResponse

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	refreshed round-trip state (charter §3)
user (#2)	User（见消息定义）	-	-

UserTweetsRequest

proto 全名：twitter.android.v1.UserTweetsRequest

字段	类型	约束	说明
state (#1)	AndroidAccountState（见消息定义）	-	-
rest_id (#2)	string	-	-