API 接口参考

本文档用于逐接口核对参数和响应。第一次接入或执行多步任务时，请先阅读 模块与任务指南，再回到这里查看字段类型、参数来源和业务成功判定。 内容由 Proto、Python 公共门面和接口语义元数据生成，禁止手工修改。

调用约定

• 共 7 个 Service、19 个 RPC。
• 每个请求字段的“参数来源”说明它应由用户输入、账号/设备配置、运行时生成还是上一步响应提供。
• 除 AuthService/Login 外，每个请求必须携带完整 account_state；SDK 通过 client.account(state) 自动注入并在成功响应后刷新。
• 可选代理是 LoginRequest.proxy / AccountState.proxy 强类型字段；认证信息不得写入日志。
• OK 只表示 gRPC 调用完成，业务成功必须核对各接口列出的实体、字段和副作用。
• 写接口不可盲目重试；超时后先通过读取接口确认是否已经产生副作用。

接口总览

接口	模块	状态	操作	幂等	副作用	Python 方法
账号登录 threads.auth.v1.AuthService/Login	登录与当前账号	experimental	create	否	有	AuthClient.login
读取当前账号 threads.auth.v1.AuthService/GetCurrentUser	登录与当前账号	available	read	是	无	AccountAuthClient.get_current_user
读取推荐用户 threads.feed.v1.FeedService/ListRecommendedUsers	推荐用户	available	read	是	无	FeedClient.list_recommended_users
读取关系状态 threads.friendships.v1.FriendshipsService/GetFriendshipStatus	关系状态	available	read	是	无	FriendshipsClient.get_friendship_status
关注用户 threads.friendships.v1.FriendshipsService/FollowUser	关系状态	available	create	是	有	FriendshipsClient.follow_user
取消关注 threads.friendships.v1.FriendshipsService/UnfollowUser	关系状态	available	delete	是	有	FriendshipsClient.unfollow_user
检查冒犯文本 threads.posts.v1.PostsService/CheckOffensiveText	帖子发布与删除	known-upstream-error	read	是	无	PostsClient.check_offensive_text
创建文本帖 threads.posts.v1.PostsService/CreateTextPost	帖子发布与删除	available	create	否	有	PostsClient.create_text_post
上传图片 threads.posts.v1.PostsService/UploadImage	帖子发布与删除	available	create	否	有	PostsClient.upload_image
创建单图帖 threads.posts.v1.PostsService/CreateImagePost	帖子发布与删除	available	create	否	有	PostsClient.create_image_post
删除帖子 threads.posts.v1.PostsService/DeletePost	帖子发布与删除	available	delete	否	有	PostsClient.delete_post
点赞帖子 threads.posts.v1.PostsService/LikeMedia	帖子发布与删除	available	create	是	有	PostsClient.like_media
取消点赞 threads.posts.v1.PostsService/UnlikeMedia	帖子发布与删除	available	delete	是	有	PostsClient.unlike_media
读取指定用户资料 threads.profile.v1.ProfileService/GetUserInfo	资料与主页帖子	available	read	是	无	ProfileClient.get_user_info
分页读取主页帖子 threads.profile.v1.ProfileService/ListProfileThreads	资料与主页帖子	available	read	是	无	ProfileClient.list_profile_threads
保存当前账号资料 threads.profile.v1.ProfileService/EditProfile	资料与主页帖子	available	update	否	有	ProfileClient.edit_profile
分页读取账号回复 threads.replies.v1.RepliesService/ListProfileReplies	回复采集	available	read	是	无	RepliesClient.list_profile_replies
关键词搜索 threads.search.v1.SearchService/KeywordSearch	搜索与主题校验	available	read	是	无	SearchClient.keyword_search
校验发帖主题 threads.search.v1.SearchService/ValidateTag	搜索与主题校验	available	read	是	无	SearchClient.validate_tag

接口详情

账号登录

• RPC：threads.auth.v1.AuthService/Login
• gRPC 方法：/threads.auth.v1.AuthService/Login
• Python 门面：AuthClient.login
• 所属模块：登录与当前账号（auth）
• 何时调用：没有可用 IGT:2，并且需要通过账密建立新会话时。
• 前置条件：生产容器已固定加载 keybox signer；账号代理可选。
• Metadata：无需账号 metadata；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：create
• 状态：experimental
• 幂等：否
• 副作用：有
• 业务成功：success=true、account_state.session.token 为 IGT:2，且 verified_user.username 与请求账号一致；stable_for_automation 仍必须为 false，直到硬件证明和长期存活观测另行通过。
• 响应用途：保存 account_state，核对 verified_user.username 和 assurance；后续任务用 ThreadsClient.account(state) 恢复，stable_for_automation 不能由即时成功推断。
• 后续接口：threads.posts.v1.PostsService/CreateTextPost
• 所属工作流：login
• 说明：account_state 是后续独立任务的完整输入，SDK 与 Go server 均不负责持久化。Go server 从成套真机模板生成首次登录设备，并使用生产镜像内固定 keybox signer；keybox 不得由 SDK 用户传递或从 Go server 镜像移除，无 signer 时返回 FAILED_PRECONDITION。代理可省略；登录只接受 Python Proxy 强类型对象，Go server 契约同样使用 Proxy 消息。协议支持 HTTP(S)、SOCKS5、SOCKS5H，认证账号密码必须成对提供或同时省略，省略时支持 IP 白名单代理。配置字符串只能通过 Proxy.from_url() 显式转换，不存在 proxy_url 兼容入口。登录成功后必须保存并复用 account_state。

请求 threads.auth.v1.LoginRequest

字段	类型	字段号	规则	参数来源	说明
username	string	1	单值	用户输入：Threads/Instagram 登录账号。	-
password	string	2	单值	受保护账号配置：禁止写入源码和日志。	-
two_factor_seed	string	3	可选	受保护账号配置：启用 TOTP 时提供。	-
proxy	Proxy	7	可选	可选账号出口：由 Proxy 强类型对象提供；认证账号密码必须同时提供或同时省略。	-

响应 threads.auth.v1.LoginResponse

字段	类型	字段号	规则	说明
success	bool	1	单值	success 只有在取到 IGT:2 且用同一代理、设备完成 whoami 身份校验后才为 true。
steps	LoginStep	3	数组	-
verified_user	CurrentUser	5	可选	-
assurance	LoginAssurance	6	单值	-
stable_for_automation	bool	7	单值	当前实现永不把即时登录成功等价为长期稳定；必须由真实硬件证明和存活观测另行确认。
stability_warning	string	8	单值	-
account_state	AccountState	9	可选	登录成功后的完整状态。使用者负责保存，并在发帖等后续独立任务中重新传入。

Python 调用签名

async def login(*, username: str, password: str, two_factor_seed: str | None=None, proxy: Proxy | None=None, timeout: float | None=None) -> LoginResult

读取当前账号

• RPC：threads.auth.v1.AuthService/GetCurrentUser
• gRPC 方法：/threads.auth.v1.AuthService/GetCurrentUser
• Python 门面：AccountAuthClient.get_current_user
• 所属模块：登录与当前账号（auth）
• 何时调用：校验 AccountState 会话、取得当前 uid，或在资料编辑前读取完整原值时。
• 前置条件：已通过 client.account(state) 恢复完整账号状态。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：read
• 状态：available
• 幂等：是
• 副作用：无
• 业务成功：响应 pk 与 AccountState.uid/session 所属账号一致，且 AccountClient.state 已由内部响应信封刷新。
• 响应用途：pk 是发帖 uid 和当前账号 user_id；edit=true 时使用完整资料字段回填 EditProfile。
• 后续接口：threads.profile.v1.ProfileService/EditProfile；threads.posts.v1.PostsService/CreateTextPost；threads.posts.v1.PostsService/CreateImagePost
• 所属工作流：verify_session；login；edit_profile；create_text_post；create_image_post
• 说明：读取当前账号；edit=true 时返回更完整的资料字段。必须从 AccountClient 调用。

请求 threads.auth.v1.GetCurrentUserRequest

字段	类型	字段号	规则	参数来源	说明
edit	bool	1	可选	调用场景：普通身份校验传 false；资料编辑前传 true。	edit=true：编辑资料页的读取场景（字段更全）。
account_state	AccountState	2	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.auth.v1.GetCurrentUserResponse

字段	类型	字段号	规则	说明
user	CurrentUser	1	单值	-
account_state	AccountState	2	单值	-

Python 返回 threads.auth.v1.CurrentUser

字段	类型	字段号	规则	说明
pk	string	1	单值	-
username	string	2	单值	-
full_name	string	3	可选	-
biography	string	4	可选	-
profile_pic_url	string	5	可选	-
email	string	6	可选	-
text_app_biography	string	7	可选	-
external_url	string	8	可选	-
bio_links	BioLink	9	数组	-
text_app_cover_photo_url	string	10	可选	-
is_private	bool	11	可选	-
is_verified	bool	12	可选	-

Python 调用签名

async def get_current_user(edit: bool | None=None, *, timeout: float | None=None) -> auth_pb2.CurrentUser

读取推荐用户

• RPC：threads.feed.v1.FeedService/ListRecommendedUsers
• gRPC 方法：/threads.feed.v1.FeedService/ListRecommendedUsers
• Python 门面：FeedClient.list_recommended_users
• 所属模块：推荐用户（feed）
• 何时调用：需要获取 Threads 推荐账号或继续推荐流分页时。
• 前置条件：AccountClient 已绑定完整 AccountState。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：read
• 状态：available
• 幂等：是
• 副作用：无
• 业务成功：ListPage.items 与请求推荐场景一致，paging 游标来自同一次真实响应。
• 响应用途：直接遍历 items；paging.next_cursor 用于下一页 paging_token；metadata 保留未知顶层字段。
• 后续接口：threads.feed.v1.FeedService/ListRecommendedUsers
• 所属工作流：无
• 说明：返回结构化 items/paging/metadata，不暴露原始 JSON 字符串。

请求 threads.feed.v1.ListRecommendedUsersRequest

字段	类型	字段号	规则	参数来源	说明
paging_token	string	1	可选	上一页响应：使用 ListPage.paging.next_cursor；首次调用省略。	分页游标（对应 paging_token）。
recommendation_type	string	2	可选	产品场景配置：按上游支持的推荐类型填写，未知时省略。	推荐类型（recommended_users / great_accounts / ...，见报告 §5.1）。
account_state	threads.auth.v1.AccountState	3	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.common.v1.ListPageResponse

字段	类型	字段号	规则	说明
page	ListPage	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.common.v1.ListPage

字段	类型	字段号	规则	说明
items	google.protobuf.Struct	1	数组	-
paging	Paging	2	单值	-
metadata	google.protobuf.Struct	3	单值	除列表和分页字段外的上游顶层字段，供兼容未知增量字段。

Python 调用签名

async def list_recommended_users(paging_token: str | None=None, recommendation_type: str | None=None, *, timeout: float | None=None) -> common_pb2.ListPage

读取关系状态

• RPC：threads.friendships.v1.FriendshipsService/GetFriendshipStatus
• gRPC 方法：/threads.friendships.v1.FriendshipsService/GetFriendshipStatus
• Python 门面：FriendshipsClient.get_friendship_status
• 所属模块：关系状态（friendships）
• 何时调用：需要确认当前账号是否关注、被关注、拉黑或静音目标账号时。
• 前置条件：AccountClient 已绑定完整 AccountState。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：read
• 状态：available
• 幂等：是
• 副作用：无
• 业务成功：返回关系状态属于请求 user_id 对应的目标账号。
• 响应用途：直接读取 following、followed_by、blocking、muting 等强类型字段。
• 后续接口：无
• 所属工作流：无
• 说明：读取关注、拉黑、静音等关系状态。

请求 threads.friendships.v1.GetFriendshipStatusRequest

字段	类型	字段号	规则	参数来源	说明
user_id	string	1	单值	目标对象：来自 GetUserInfo.pk、搜索结果或业务数据库。	目标用户数字 id。
is_external_deeplink_profile_view	bool	2	可选	调用场景：普通 API 调用使用 false。	对应请求参数 is_external_deeplink_profile_view（默认 false）。
account_state	threads.auth.v1.AccountState	3	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.friendships.v1.GetFriendshipStatusResponse

字段	类型	字段号	规则	说明
result	FriendshipStatus	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.friendships.v1.FriendshipStatus

字段	类型	字段号	规则	说明
following	bool	1	可选	-
followed_by	bool	2	可选	-
outgoing_request	bool	3	可选	-
incoming_request	bool	4	可选	-
blocking	bool	5	可选	-
is_blocking_reel	bool	6	可选	-
muting	bool	7	可选	-
is_muting_reel	bool	8	可选	-
is_muting_notes	bool	9	可选	-
is_muting_media_notes	bool	10	可选	-
is_muting_media_reposts	bool	11	可选	-
is_private	bool	12	可选	-
is_eligible_to_subscribe	bool	14	可选	-
subscribed	bool	13	可选	以下字段真机响应未出现，仅 JADX 静态可见。 TODO(抓包核对): 置信度=高概率; 来源=JADX parser C31991Ov; 三份真机样本均未返回
is_viewer_unconnected	bool	15	可选	-
should_show_profile_upsell	bool	16	可选	-
is_banner_profile_upsell	bool	17	可选	-
reachability_status	int64	18	可选	int 枚举（apis/friendships/关注关系.md）
is_bestie	bool	20	可选	真机 show 与 create/destroy 均返回，此前模型缺失。
is_restricted	bool	21	可选	-
is_feed_favorite	bool	22	可选	-
text_post_app_pre_following	bool	23	可选	-

Python 调用签名

async def get_friendship_status(user_id: str, is_external_deeplink_profile_view: bool=False, *, timeout: float | None=None) -> 'friendships_pb2.FriendshipStatus'

关注用户

• RPC：threads.friendships.v1.FriendshipsService/FollowUser
• gRPC 方法：/threads.friendships.v1.FriendshipsService/FollowUser
• Python 门面：FriendshipsClient.follow_user
• 所属模块：关系状态（friendships）
• 何时调用：关注目标账号时。
• 前置条件：完整 AccountState、目标 user_id、写操作授权。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：create
• 状态：available
• 幂等：是
• 副作用：有
• 业务成功：result.status.following=true，并用 GetFriendshipStatus 独立回读确认关注生效。
• 响应用途：以 result.status.following 判定结果；previous_following 区分「本次新增关注」与「此前已关注」。
• 后续接口：threads.friendships.v1.FriendshipsService/GetFriendshipStatus
• 所属工作流：无
• 说明：真实关系写操作；previous_following=false 表示本次确实产生变化，true 表示此前已关注。

请求 threads.friendships.v1.FollowUserRequest

字段	类型	字段号	规则	参数来源	说明
user_id	string	1	单值	用户输入或前置响应：目标用户数字 id，可来自 GetUserInfo、推荐流或搜索结果。	目标用户数字 id。
container_module	string	2	可选	固定参数：缺省 ig_text_feed_profile；从帖子详情页操作时传 ig_text_post_permalink。	埋点归因；缺省 container_module=ig_text_feed_profile。
nav_chain	string	3	可选	埋点参数：可留空；需要贴合真机时用进入该用户页那次调用的导航链。	-
attribution_media_id	string	4	可选	前置响应：从某个帖子发起关注时传该帖复合 media_id（{pk}_{author_uid}）；直接按 user_id 操作时留空。	非空表示这次关注来自某个帖子，会同时写入 media_id 与 media_id_attribution； 直接按 user_id 关注时留空。
ranking_info_token	string	5	可选	前置响应：时间线/回复流里该帖的排序归因 token；留空则不发送。	该帖的排序归因 token，留空则不发送。
account_state	threads.auth.v1.AccountState	6	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.friendships.v1.FollowUserResponse

字段	类型	字段号	规则	说明
result	FollowResult	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.friendships.v1.FollowResult

字段	类型	字段号	规则	说明
status	FriendshipStatus	1	单值	操作后的关系状态；判定成功以 status.following 为准。
previous_following	bool	2	可选	操作前是否已关注。create 返回布尔值，destroy 真机返回 null（此处不设值）。
error	string	3	可选	上游业务级错误文案；两份真机样本均为 null。 TODO(抓包核对): 置信度=推测; 非空取值形态未观察到。

Python 调用签名

async def follow_user(user_id: str, container_module: str | None=None, nav_chain: str | None=None, attribution_media_id: str | None=None, ranking_info_token: str | None=None, *, timeout: float | None=None) -> 'friendships_pb2.FollowResult'

取消关注

• RPC：threads.friendships.v1.FriendshipsService/UnfollowUser
• gRPC 方法：/threads.friendships.v1.FriendshipsService/UnfollowUser
• Python 门面：FriendshipsClient.unfollow_user
• 所属模块：关系状态（friendships）
• 何时调用：取消对目标账号的关注时。
• 前置条件：完整 AccountState、目标 user_id、写操作授权。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：delete
• 状态：available
• 幂等：是
• 副作用：有
• 业务成功：result.status.following=false，并用 GetFriendshipStatus 独立回读确认已取关。
• 响应用途：以 result.status.following=false 判定结果；该接口不返回 previous_following。
• 后续接口：threads.friendships.v1.FriendshipsService/GetFriendshipStatus
• 所属工作流：无
• 说明：真实关系写操作；取关不返回 previous_following，不要依赖该字段判断结果。

请求 threads.friendships.v1.UnfollowUserRequest

字段	类型	字段号	规则	参数来源	说明
user_id	string	1	单值	用户输入或前置响应：目标用户数字 id，可来自 GetUserInfo、推荐流或搜索结果。	-
container_module	string	2	可选	固定参数：缺省 ig_text_feed_profile；从帖子详情页操作时传 ig_text_post_permalink。	-
nav_chain	string	3	可选	埋点参数：可留空；需要贴合真机时用进入该用户页那次调用的导航链。	-
attribution_media_id	string	4	可选	前置响应：从某个帖子发起关注时传该帖复合 media_id（{pk}_{author_uid}）；直接按 user_id 操作时留空。	-
ranking_info_token	string	5	可选	前置响应：时间线/回复流里该帖的排序归因 token；留空则不发送。	-
account_state	threads.auth.v1.AccountState	6	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.friendships.v1.UnfollowUserResponse

字段	类型	字段号	规则	说明
result	FollowResult	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.friendships.v1.FollowResult

字段	类型	字段号	规则	说明
status	FriendshipStatus	1	单值	操作后的关系状态；判定成功以 status.following 为准。
previous_following	bool	2	可选	操作前是否已关注。create 返回布尔值，destroy 真机返回 null（此处不设值）。
error	string	3	可选	上游业务级错误文案；两份真机样本均为 null。 TODO(抓包核对): 置信度=推测; 非空取值形态未观察到。

Python 调用签名

async def unfollow_user(user_id: str, container_module: str | None=None, nav_chain: str | None=None, attribution_media_id: str | None=None, ranking_info_token: str | None=None, *, timeout: float | None=None) -> 'friendships_pb2.FollowResult'

检查冒犯文本

• RPC：threads.posts.v1.PostsService/CheckOffensiveText
• gRPC 方法：/threads.posts.v1.PostsService/CheckOffensiveText
• Python 门面：PostsClient.check_offensive_text
• 所属模块：帖子发布与删除（posts）
• 何时调用：发帖前希望执行上游文本风险检查时；当前真实上游返回 404。
• 前置条件：AccountClient 已绑定完整 AccountState。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：read
• 状态：known-upstream-error
• 幂等：是
• 副作用：无
• 业务成功：当前真实上游返回 HTTP 404，测试以真实错误映射为验收结果。
• 响应用途：当前以 gRPC 错误路径处理，不能把未返回结果视为安全。
• 后续接口：无
• 所属工作流：无
• 说明：请求结构与真实 App 抓包一致，但当前线上端点不可用。

请求 threads.posts.v1.CheckOffensiveTextRequest

字段	类型	字段号	规则	参数来源	说明
text_list	string	1	数组	用户内容：待检查的一段或多段文本。	待检测文本（对应 form text_list，JSON 数组）。
media_id	string	2	可选	已有媒体上下文：编辑或关联媒体时提供，否则省略。	可选关联 media_id。
account_state	threads.auth.v1.AccountState	3	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.posts.v1.CheckOffensiveTextResponse

字段	类型	字段号	规则	说明
result	OffensiveCheck	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.posts.v1.OffensiveCheck

字段	类型	字段号	规则	说明
is_offensive	bool	1	单值	-
minimum_next_timestamp	int64	2	可选	-
text_language	string	3	可选	-

Python 调用签名

async def check_offensive_text(text_list: Sequence[str], media_id: str | None=None, *, timeout: float | None=None) -> posts_pb2.OffensiveCheck

创建文本帖

• RPC：threads.posts.v1.PostsService/CreateTextPost
• gRPC 方法：/threads.posts.v1.PostsService/CreateTextPost
• Python 门面：PostsClient.create_text_post
• 所属模块：帖子发布与删除（posts）
• 何时调用：发布不带图片或视频的 Threads 文本帖子时；传 reply_id 时同一接口用于发布回复（评论）。
• 前置条件：完整 AccountState、写操作授权。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：create
• 状态：available
• 幂等：否
• 副作用：有
• 业务成功：返回帖子属于 account_state.uid，caption 与请求一致，并能从账号主页重新读取；AccountClient.state 已刷新。
• 响应用途：保存 id/code/permalink，核对 caption、user 和主页结果；SDK 从内部响应信封刷新状态，调用方将 AccountClient.state 覆盖写回自己的存储。
• 后续接口：threads.profile.v1.ProfileService/ListProfileThreads
• 所属工作流：create_text_post
• 说明：推荐通过 AccountClient 调用并在任务完成后保存 AccountClient.state。真实发帖操作；必须显式授权，调用方不得自动重试。

请求 threads.posts.v1.CreateTextPostRequest

字段	类型	字段号	规则	参数来源	说明
caption	string	1	单值	用户输入：帖子正文。	正文（对应 caption）。
upload_id	string	5	可选	运行时生成：可省略，由 Go SDK 生成；重试时不得随意复用。	幂等批次 id（缺省由 SDK 生成 upload_id、publish_id 固定 "1"）。
reply_control	int32	6	可选	产品设置：回复权限枚举，默认 0。	回复权限：0=everyone（对应 text_post_app_info.reply_control）。
camera_session_id	string	8	可选	运行时生成：模拟发布会话时提供，否则省略。	埋点/会话（必填，缺省由 SDK 生成/留空）。
nav_chain	string	9	可选	运行时上下文：导航链，普通调用可省略。	-
timezone_offset	string	10	可选	运行环境：账号所在地时区偏移。	-
tag_header	string	11	可选	主题功能：先用 ValidateTag 校验后按上游格式提供。	可选功能：主题 / 位置 / 投票（勾选才传）。 主题 display_text
location	Location	12	可选	用户选择：posts_pb2.Location，未选择位置时省略。	-
poll	Poll	13	可选	用户输入：posts_pb2.Poll，未创建投票时省略。	-
account_state	threads.auth.v1.AccountState	14	单值	SDK 自动注入：来自 AccountClient 当前完整状态，包含 uid、设备、Session、可选代理和 App 版本。	登录返回或由使用者存储恢复的完整状态。
reply_id	string	15	可选	可选参数：非空即表示发布回复（评论），取被回复帖的纯数字 pk（Media.pk 或 post.pk，不是 {pk}_{author_uid} 复合 id）；留空为新建独立帖。	非空表示这是对某帖的回复（评论），值为被回复帖的 pk（纯数字，不带 _uid 后缀）。 回复与新建帖是同一端点的两种形态，仅 text_post_app_info 内的入口字段不同。
ranking_info_token	string	16	可选	前置响应：时间线/回复流响应里该帖的排序归因 token；留空则不发送该字段。	时间线/回复流响应里该帖的排序归因 token；回复时真机会带上，置空则不发送。

响应 threads.posts.v1.CreateTextPostResponse

字段	类型	字段号	规则	说明
media	Media	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.posts.v1.Media

字段	类型	字段号	规则	说明
id	string	1	单值	-
pk	int64	2	单值	-
fbid	int64	3	单值	-
taken_at	int64	4	单值	-
media_type	int32	5	单值	19 = text_post
code	string	6	单值	短代码
product_type	string	7	单值	text_post
permalink	string	8	单值	-
integrity_review_decision	string	9	单值	pending 表示异步审核中
caption	Caption	10	单值	-
text_post_app_info	TextPostAppInfo	11	单值	-
has_liked	bool	12	单值	-
like_count	int64	13	单值	-
meta_place	MetaPlace	14	可选	位置回显（带位置发帖时）
image_versions2	ImageVersions2	15	可选	-
original_width	int32	16	单值	-
original_height	int32	17	单值	-
user	MediaUser	18	可选	列表端点的顶层作者

Python 调用签名

async def create_text_post(caption: str, upload_id: str | None=None, reply_control: int=0, camera_session_id: str | None=None, nav_chain: str | None=None, timezone_offset: str | None=None, tag_header: str | None=None, location: posts_pb2.Location | None=None, poll: posts_pb2.Poll | None=None, reply_id: str | None=None, ranking_info_token: str | None=None, *, timeout: float | None=None) -> posts_pb2.Media

上传图片

• RPC：threads.posts.v1.PostsService/UploadImage
• gRPC 方法：/threads.posts.v1.PostsService/UploadImage
• Python 门面：PostsClient.upload_image
• 所属模块：帖子发布与删除（posts）
• 何时调用：创建单图帖前上传 WebP 图片二进制时。
• 前置条件：完整 AccountState、WebP 图片字节、真实宽高、写操作授权。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：create
• 状态：available
• 幂等：否
• 副作用：有
• 业务成功：响应 status=ok 且 upload_id 非空；该 upload_id 可被 CreateImagePost 接受。
• 响应用途：status 必须为 ok；将 upload_id 原样传给 CreateImagePost。
• 后续接口：threads.posts.v1.PostsService/CreateImagePost
• 所属工作流：create_image_post
• 说明：真实图片二进制上传；当前抓包确认 image/webp，视频上传仍缺少抓包来源。

请求 threads.posts.v1.UploadImageRequest

字段	类型	字段号	规则	参数来源	说明
image_data	bytes	1	单值	本地文件或内存：WebP 原始 bytes。	原始图片字节；当前已确认样本为 image/webp。
original_width	int32	2	单值	图片元数据：解码后的真实像素宽度。	-
original_height	int32	3	单值	图片元数据：解码后的真实像素高度。	-
upload_id	string	4	可选	运行时生成：通常省略并由 Go SDK 生成。	缺省由 SDK 生成；后续 CreateImagePost 必须使用响应中的 upload_id。
mime_type	string	5	可选	固定协议值：当前确认 image/webp。	缺省 image/webp；当前仅确认 image/webp。
is_optimistic_upload	bool	6	可选	上传策略：通常省略使用 SDK 默认值。	App 抓包存在乐观预上传与正式上传两种模式；缺省为正式上传。
msssim	double	7	可选	图片质量计算：调用方实际计算时提供，否则省略。	图片压缩质量指标；调用方掌握真实编码结果时再传。
ssim	double	8	可选	图片质量计算：调用方实际计算时提供，否则省略。	-
waterfall_id	string	9	可选	运行时生成：上传链路追踪 ID，通常省略。	缺省由 SDK 生成。
account_state	threads.auth.v1.AccountState	10	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.posts.v1.UploadImageResponse

字段	类型	字段号	规则	说明
result	UploadImageResult	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.posts.v1.UploadImageResult

字段	类型	字段号	规则	说明
upload_id	string	1	单值	-
status	string	2	单值	-

Python 调用签名

async def upload_image(image_data: bytes, original_width: int, original_height: int, upload_id: str | None=None, mime_type: str | None=None, is_optimistic_upload: bool | None=None, msssim: float | None=None, ssim: float | None=None, waterfall_id: str | None=None, *, timeout: float | None=None) -> 'posts_pb2.UploadImageResult'

创建单图帖

• RPC：threads.posts.v1.PostsService/CreateImagePost
• gRPC 方法：/threads.posts.v1.PostsService/CreateImagePost
• Python 门面：PostsClient.create_image_post
• 所属模块：帖子发布与删除（posts）
• 何时调用：UploadImage 成功后，把已上传图片发布为单图帖子时。
• 前置条件：UploadImageResult.status=ok、完整 AccountState、写操作授权。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：create
• 状态：available
• 幂等：否
• 副作用：有
• 业务成功：返回 media_type=1，正文与请求一致，image_versions2 非空，并能从账号主页重新读取。
• 响应用途：核对 media_type=1、image_versions2、caption 和 user，并保存 id/code/permalink。
• 后续接口：threads.profile.v1.ProfileService/ListProfileThreads
• 所属工作流：create_image_post
• 说明：单图帖 configure；调用前必须先用 UploadImage 获取 upload_id，调用方不得自动重试。

请求 threads.posts.v1.CreateImagePostRequest

字段	类型	字段号	规则	参数来源	说明
caption	string	1	单值	用户输入：帖子正文。	图片帖允许空正文。
upload_id	string	5	单值	前置响应：UploadImageResult.upload_id。	必须使用 UploadImage 返回的 upload_id。
reply_control	int32	6	可选	产品设置：回复权限枚举，默认 0。	-
camera_session_id	string	8	可选	运行时生成：模拟发布会话时提供，否则省略。	-
nav_chain	string	9	可选	运行时上下文：导航链，普通调用可省略。	-
timezone_offset	string	10	可选	运行环境：账号所在地时区偏移。	-
tag_header	string	11	可选	主题功能：先用 ValidateTag 校验后按上游格式提供。	-
location	Location	12	可选	用户选择：posts_pb2.Location，未选择位置时省略。	-
poll	Poll	13	可选	用户输入：posts_pb2.Poll，未创建投票时省略。	-
original_width	int32	14	单值	前置请求：与 UploadImage.original_width 保持一致。	-
original_height	int32	15	单值	前置请求：与 UploadImage.original_height 保持一致。	-
custom_accessibility_caption	string	16	可选	用户输入：图片无障碍说明，可省略。	-
account_state	threads.auth.v1.AccountState	17	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.posts.v1.CreateImagePostResponse

字段	类型	字段号	规则	说明
media	Media	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.posts.v1.Media

字段	类型	字段号	规则	说明
id	string	1	单值	-
pk	int64	2	单值	-
fbid	int64	3	单值	-
taken_at	int64	4	单值	-
media_type	int32	5	单值	19 = text_post
code	string	6	单值	短代码
product_type	string	7	单值	text_post
permalink	string	8	单值	-
integrity_review_decision	string	9	单值	pending 表示异步审核中
caption	Caption	10	单值	-
text_post_app_info	TextPostAppInfo	11	单值	-
has_liked	bool	12	单值	-
like_count	int64	13	单值	-
meta_place	MetaPlace	14	可选	位置回显（带位置发帖时）
image_versions2	ImageVersions2	15	可选	-
original_width	int32	16	单值	-
original_height	int32	17	单值	-
user	MediaUser	18	可选	列表端点的顶层作者

Python 调用签名

async def create_image_post(caption: str, upload_id: str, original_width: int, original_height: int, reply_control: int=0, camera_session_id: str | None=None, nav_chain: str | None=None, timezone_offset: str | None=None, tag_header: str | None=None, location: 'posts_pb2.Location | None'=None, poll: 'posts_pb2.Poll | None'=None, custom_accessibility_caption: str | None=None, *, timeout: float | None=None) -> 'posts_pb2.Media'

删除帖子

• RPC：threads.posts.v1.PostsService/DeletePost
• gRPC 方法：/threads.posts.v1.PostsService/DeletePost
• Python 门面：PostsClient.delete_post
• 所属模块：帖子发布与删除（posts）
• 何时调用：删除当前账号已有帖子或清理测试帖子时。
• 前置条件：完整 AccountState、目标 media_id、写操作授权。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：delete
• 状态：available
• 幂等：否
• 副作用：有
• 业务成功：did_delete=true，且重新读取主页确认目标帖子已经消失。
• 响应用途：did_delete 必须为 true，并通过 ListProfileThreads 确认目标帖子消失。
• 后续接口：threads.profile.v1.ProfileService/ListProfileThreads
• 所属工作流：无
• 说明：真实删除操作；必须显式授权，调用方不得自动重试。

请求 threads.posts.v1.DeletePostRequest

字段	类型	字段号	规则	参数来源	说明
media_id	string	1	单值	前置响应：创建接口返回的 Media.id，或主页帖子中的 post.id。	= URL 中的 media_id（pk_uid）
account_state	threads.auth.v1.AccountState	4	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.posts.v1.DeletePostResponse

字段	类型	字段号	规则	说明
result	DeletePostResult	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.posts.v1.DeletePostResult

字段	类型	字段号	规则	说明
did_delete	bool	1	单值	-
cxp_deep_deletion_waterfall_id	string	2	可选	-

Python 调用签名

async def delete_post(media_id: str, *, timeout: float | None=None) -> posts_pb2.DeletePostResult

点赞帖子

• RPC：threads.posts.v1.PostsService/LikeMedia
• gRPC 方法：/threads.posts.v1.PostsService/LikeMedia
• Python 门面：PostsClient.like_media
• 所属模块：帖子发布与删除（posts）
• 何时调用：对指定帖子点赞时。
• 前置条件：完整 AccountState、目标帖子的复合 media_id、写操作授权。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：create
• 状态：available
• 幂等：是
• 副作用：有
• 业务成功：调用成功后重新读取该帖，has_liked 必须为 true。
• 响应用途：无业务返回值；成功判据是重新读取该帖，has_liked 为 true。
• 后续接口：threads.profile.v1.ProfileService/ListProfileThreads
• 所属工作流：无
• 说明：真实互动写操作；media_id 必须是 {pk}_{author_uid} 复合 id。上游成功响应只有 status，方法无返回值。

请求 threads.posts.v1.LikeMediaRequest

字段	类型	字段号	规则	参数来源	说明
media_id	string	1	单值	前置响应：创建接口返回的 Media.id，或主页帖子/时间线中的 post.id（形如 {pk}_{author_uid}）。	URL 与请求体共用的复合 id：{pk}_{author_uid}。
container_module	string	2	可选	固定参数：缺省 ig_text_feed_timeline，从其他入口点赞时按实际来源传入。	埋点归因；缺省 container_module=ig_text_feed_timeline，其余置空则不发送。
nav_chain	string	3	可选	埋点参数：可留空；需要贴合真机时用读取该帖那次调用的导航链。	-
feed_position	int32	4	可选	埋点参数：该帖在列表中的下标，缺省 0。	-
logging_info_token	string	5	可选	前置响应：时间线响应里该帖的 logging token；留空则不发送。	时间线响应里该帖的 logging token。
account_state	threads.auth.v1.AccountState	6	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.posts.v1.LikeMediaResponse

字段	类型	字段号	规则	说明
account_state	threads.auth.v1.AccountState	1	单值	-

Python 调用签名

async def like_media(media_id: str, container_module: str | None=None, nav_chain: str | None=None, feed_position: int | None=None, logging_info_token: str | None=None, *, timeout: float | None=None) -> None

取消点赞

• RPC：threads.posts.v1.PostsService/UnlikeMedia
• gRPC 方法：/threads.posts.v1.PostsService/UnlikeMedia
• Python 门面：PostsClient.unlike_media
• 所属模块：帖子发布与删除（posts）
• 何时调用：撤销此前对某帖的点赞时。
• 前置条件：完整 AccountState、目标帖子的复合 media_id、写操作授权。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：delete
• 状态：available
• 幂等：是
• 副作用：有
• 业务成功：调用成功后重新读取该帖，has_liked 必须回到 false。
• 响应用途：无业务返回值；成功判据是重新读取该帖，has_liked 回到 false。
• 后续接口：threads.profile.v1.ProfileService/ListProfileThreads
• 所属工作流：无
• 说明：TODO(抓包核对): 路径与字段集由 like 对称推导，尚未真机核对；失败时不要自动重试。

请求 threads.posts.v1.UnlikeMediaRequest

字段	类型	字段号	规则	参数来源	说明
media_id	string	1	单值	前置响应：与 LikeMedia 使用同一个复合 media_id。	-
container_module	string	2	可选	固定参数：缺省 ig_text_feed_timeline。	-
nav_chain	string	3	可选	埋点参数：可留空。	-
feed_position	int32	4	可选	埋点参数：缺省 0。	-
logging_info_token	string	5	可选	前置响应：时间线响应里该帖的 logging token；留空则不发送。	-
account_state	threads.auth.v1.AccountState	6	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.posts.v1.UnlikeMediaResponse

字段	类型	字段号	规则	说明
account_state	threads.auth.v1.AccountState	1	单值	-

Python 调用签名

async def unlike_media(media_id: str, container_module: str | None=None, nav_chain: str | None=None, feed_position: int | None=None, logging_info_token: str | None=None, *, timeout: float | None=None) -> None

读取指定用户资料

• RPC：threads.profile.v1.ProfileService/GetUserInfo
• gRPC 方法：/threads.profile.v1.ProfileService/GetUserInfo
• Python 门面：ProfileClient.get_user_info
• 所属模块：资料与主页帖子（profile）
• 何时调用：已知用户 ID，需要读取公开资料和账号统计时。
• 前置条件：AccountClient 已绑定完整 AccountState。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：read
• 状态：available
• 幂等：是
• 副作用：无
• 业务成功：响应 pk 与请求 user_id 一致。
• 响应用途：核对 pk 等于请求 user_id，再使用 username、计数和隐私状态。
• 后续接口：threads.profile.v1.ProfileService/ListProfileThreads；threads.friendships.v1.FriendshipsService/GetFriendshipStatus
• 所属工作流：无
• 说明：读取指定用户资料。

请求 threads.profile.v1.GetUserInfoRequest

字段	类型	字段号	规则	参数来源	说明
user_id	string	1	单值	目标对象：来自搜索结果、帖子作者 pk 或业务数据库。	Threads/IG 用户数字 id（pk）。
account_state	threads.auth.v1.AccountState	2	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.profile.v1.GetUserInfoResponse

字段	类型	字段号	规则	说明
user	User	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.profile.v1.User

字段	类型	字段号	规则	说明
pk	string	1	单值	用户数字 id
username	string	2	单值	-
full_name	string	3	可选	-
biography	string	4	可选	-
profile_pic_url	string	5	可选	-
follower_count	int64	6	可选	-
following_count	int64	7	可选	-
media_count	int64	8	可选	-
is_private	bool	9	可选	-
is_verified	bool	10	可选	-

Python 调用签名

async def get_user_info(user_id: str, *, timeout: float | None=None) -> 'profile_pb2.User'

分页读取主页帖子

• RPC：threads.profile.v1.ProfileService/ListProfileThreads
• gRPC 方法：/threads.profile.v1.ProfileService/ListProfileThreads
• Python 门面：ProfileClient.list_profile_threads
• 所属模块：资料与主页帖子（profile）
• 何时调用：采集指定账号主页帖子、验证发帖或验证删除结果时。
• 前置条件：AccountClient 已绑定完整 AccountState，并已准备目标 user_id。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：read
• 状态：available
• 幂等：是
• 副作用：无
• 业务成功：status=ok，threads[].items[].post 可直接读取，帖子作者与请求 user_id 的业务语义一致。
• 响应用途：优先消费 threads[].items[].post；next_cursor 传给下一页 max_id；raw_json 仅用于兼容排错。
• 后续接口：threads.profile.v1.ProfileService/ListProfileThreads
• 所属工作流：create_text_post；create_image_post；collect_profile_threads
• 说明：主页帖子已强类型化；raw_json 仅为旧客户端线级兼容和未建模字段排错保留。

请求 threads.profile.v1.ListProfileThreadsRequest

字段	类型	字段号	规则	参数来源	说明
user_id	string	1	单值	目标对象：当前账号用 GetCurrentUser.pk，其他账号来自搜索或资料接口。	-
max_id	string	2	可选	上一页响应：使用 ProfileThreadsPage.next_cursor；首次调用省略。	分页
exclude_reposts	bool	3	可选	采集策略：是否排除转发，可省略使用上游默认。	-
account_state	threads.auth.v1.AccountState	4	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.profile.v1.ListProfileThreadsResponse

字段	类型	字段号	规则	说明
page	ProfileThreadsPage	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.profile.v1.ProfileThreadsPage

字段	类型	字段号	规则	说明
raw_json	string	1	单值	-
next_cursor	string	2	可选	-
threads	ProfileThread	3	数组	-
status	string	4	单值	-

Python 调用签名

async def list_profile_threads(user_id: str, max_id: str | None=None, exclude_reposts: bool | None=None, *, timeout: float | None=None) -> 'profile_pb2.ProfileThreadsPage'

保存当前账号资料

• RPC：threads.profile.v1.ProfileService/EditProfile
• gRPC 方法：/threads.profile.v1.ProfileService/EditProfile
• Python 门面：ProfileClient.edit_profile
• 所属模块：资料与主页帖子（profile）
• 何时调用：修改用户名、显示名、简介、隐私状态或外部链接时。
• 前置条件：先调用 GetCurrentUser(edit=true) 读取完整原值。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：update
• 状态：available
• 幂等：否
• 副作用：有
• 业务成功：保存后重新读取当前账号，资料字段与请求值一致。
• 响应用途：核对返回资料，并再次 GetCurrentUser(edit=true) 验证真实保存结果。
• 后续接口：threads.auth.v1.AuthService/GetCurrentUser
• 所属工作流：edit_profile
• 说明：整表回传接口；公开参数支持 username/first_name/biography/is_private/external_url/url_title，设备 UUID 只从 AccountState 内部取得。调用前应读取当前值；头像和封面属于尚未抓包的独立上传端点，location 不是该端点字段。

请求 threads.profile.v1.EditProfileRequest

字段	类型	字段号	规则	参数来源	说明
username	string	1	单值	前置响应或用户修改：未修改时回填 CurrentUser.username。	必填
first_name	string	2	单值	前置响应或用户修改：未修改时回填 CurrentUser.full_name。	必填，显示名（= full_name）
biography	string	3	单值	前置响应或用户修改：未修改时回填 CurrentUser.biography。	必填，个性签名（无签名传空串）
is_private	bool	4	单值	前置响应或用户修改：未修改时回填 CurrentUser.is_private。	必填
external_url	string	6	可选	前置响应或用户修改：未修改时回填 CurrentUser.external_url。	可选，链接 URL；服务端写入 bio_links[]
url_title	string	7	可选	前置响应或用户修改：从 CurrentUser.bio_links 对应链接标题回填。	可选，链接标题，配合 external_url
account_state	threads.auth.v1.AccountState	8	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.profile.v1.EditProfileResponse

字段	类型	字段号	规则	说明
user	threads.auth.v1.CurrentUser	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.auth.v1.CurrentUser

字段	类型	字段号	规则	说明
pk	string	1	单值	-
username	string	2	单值	-
full_name	string	3	可选	-
biography	string	4	可选	-
profile_pic_url	string	5	可选	-
email	string	6	可选	-
text_app_biography	string	7	可选	-
external_url	string	8	可选	-
bio_links	BioLink	9	数组	-
text_app_cover_photo_url	string	10	可选	-
is_private	bool	11	可选	-
is_verified	bool	12	可选	-

Python 调用签名

async def edit_profile(username: str, first_name: str, biography: str, is_private: bool, external_url: str | None=None, url_title: str | None=None, *, timeout: float | None=None) -> auth_pb2.CurrentUser

分页读取账号回复

• RPC：threads.replies.v1.RepliesService/ListProfileReplies
• gRPC 方法：/threads.replies.v1.RepliesService/ListProfileReplies
• Python 门面：RepliesClient.list_profile_replies
• 所属模块：回复采集（replies）
• 何时调用：采集指定账号发布的回复时。
• 前置条件：AccountClient 已绑定完整 AccountState，并已准备目标 user_id。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：read
• 状态：available
• 幂等：是
• 副作用：无
• 业务成功：ListPage.items 属于请求 user_id 的回复列表。
• 响应用途：直接遍历 items；paging.next_cursor 用于下一页 max_id。
• 后续接口：threads.replies.v1.RepliesService/ListProfileReplies
• 所属工作流：无
• 说明：返回结构化 items/paging/metadata，不暴露原始 JSON 字符串。

请求 threads.replies.v1.ListProfileRepliesRequest

字段	类型	字段号	规则	参数来源	说明
user_id	string	1	单值	目标对象：来自当前账号 pk、搜索结果或资料接口。	-
max_id	string	2	可选	上一页响应：使用 ListPage.paging.next_cursor；首次调用省略。	分页
account_state	threads.auth.v1.AccountState	3	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.common.v1.ListPageResponse

字段	类型	字段号	规则	说明
page	ListPage	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.common.v1.ListPage

字段	类型	字段号	规则	说明
items	google.protobuf.Struct	1	数组	-
paging	Paging	2	单值	-
metadata	google.protobuf.Struct	3	单值	除列表和分页字段外的上游顶层字段，供兼容未知增量字段。

Python 调用签名

async def list_profile_replies(user_id: str, max_id: str | None=None, *, timeout: float | None=None) -> common_pb2.ListPage

关键词搜索

• RPC：threads.search.v1.SearchService/KeywordSearch
• gRPC 方法：/threads.search.v1.SearchService/KeywordSearch
• Python 门面：SearchClient.keyword_search
• 所属模块：搜索与主题校验（search）
• 何时调用：按关键词查找 Threads 账号或内容时。
• 前置条件：AccountClient 已绑定完整 AccountState。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：read
• 状态：available
• 幂等：是
• 副作用：无
• 业务成功：ListPage.items 与请求 query 相关。
• 响应用途：直接遍历 items；metadata 保留未知字段；分页参数必须来自同一轮搜索响应和会话。
• 后续接口：threads.search.v1.SearchService/KeywordSearch
• 所属工作流：无
• 说明：返回结构化 items/paging/metadata，不暴露原始 JSON 字符串。

请求 threads.search.v1.KeywordSearchRequest

字段	类型	字段号	规则	参数来源	说明
query	string	1	单值	用户输入：搜索关键词。	-
page_token	string	2	可选	上一页 ListPage.paging.next_cursor；首次调用省略。	-
rank_token	string	3	可选	首次响应或搜索会话上下文：后续页保持同一值。	-
search_session_id	string	4	可选	运行时生成：同一轮搜索分页复用同一个会话 ID。	-
account_state	threads.auth.v1.AccountState	5	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.common.v1.ListPageResponse

字段	类型	字段号	规则	说明
page	ListPage	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.common.v1.ListPage

字段	类型	字段号	规则	说明
items	google.protobuf.Struct	1	数组	-
paging	Paging	2	单值	-
metadata	google.protobuf.Struct	3	单值	除列表和分页字段外的上游顶层字段，供兼容未知增量字段。

Python 调用签名

async def keyword_search(query: str, page_token: str | None=None, rank_token: str | None=None, search_session_id: str | None=None, *, timeout: float | None=None) -> common_pb2.ListPage

校验发帖主题

• RPC：threads.search.v1.SearchService/ValidateTag
• gRPC 方法：/threads.search.v1.SearchService/ValidateTag
• Python 门面：SearchClient.validate_tag
• 所属模块：搜索与主题校验（search）
• 何时调用：发帖前需要确认主题标签是否有效或敏感时。
• 前置条件：AccountClient 已绑定完整 AccountState。
• Metadata：账号认证与可选代理均来自请求内 account_state；可选服务访问密钥由 ThreadsClient(api_key=...) 注入
• 类型：read
• 状态：available
• 幂等：是
• 副作用：无
• 业务成功：返回 is_valid/is_sensitive 对应请求 tag_name。
• 响应用途：is_valid=true 且业务允许时，才构造发帖 tag_header；is_sensitive 需触发产品确认。
• 后续接口：threads.posts.v1.PostsService/CreateTextPost；threads.posts.v1.PostsService/CreateImagePost
• 所属工作流：无
• 说明：发帖主题的前置校验。

请求 threads.search.v1.ValidateTagRequest

字段	类型	字段号	规则	参数来源	说明
tag_name	string	1	单值	用户输入：不含 # 的主题名称。	-
account_state	threads.auth.v1.AccountState	2	单值	SDK 自动注入：来自 AccountClient 当前完整状态。	-

响应 threads.search.v1.ValidateTagResponse

字段	类型	字段号	规则	说明
result	TagValidation	1	单值	-
account_state	threads.auth.v1.AccountState	2	单值	-

Python 返回 threads.search.v1.TagValidation

字段	类型	字段号	规则	说明
is_valid	bool	1	单值	-
is_sensitive	bool	2	单值	-

Python 调用签名

async def validate_tag(tag_name: str, *, timeout: float | None=None) -> search_pb2.TagValidation

通用 gRPC 状态

状态码是调用方的处置依据：重新登录、退避重试、停止重试三类必须可区分。

状态	含义	调用方处置
UNAUTHENTICATED	account_state.session.token 缺失、无效，上游判定会话失效，或未分类 HTTP 401	重新登录后重试
PERMISSION_DENIED	账号已停用/封禁，或未分类 HTTP 403	停止重试，人工申诉或换号
FAILED_PRECONDITION	需完成安全验证（challenge/checkpoint/2FA），或登录缺少要求的硬件 signer	停止重试，先处理前置条件
RESOURCE_EXHAUSTED	上游限流、账号被临时限制，或未分类 HTTP 429	退避后重试
DEADLINE_EXCEEDED	上游超时、未分类 HTTP 408/504，或本次调用超过 deadline	只读幂等接口可有限重试；写接口先查副作用
ABORTED	未分类 HTTP 409 冲突	按接口幂等性重新读取状态后决定是否重试
UNIMPLEMENTED	未分类 HTTP 501	停止重试并检查服务端/上游能力
UNAVAILABLE	上游连接失败，或未分类 HTTP 5xx（501/504 除外）	有限退避重试
INVALID_ARGUMENT	必填字段为空、字段组合冲突或参数格式错误	修正参数，重试无意义
INTERNAL	未分类 HTTP 400/404、其他未映射失败或服务端转换失败	以 details() 为准上报

• details() 只包含结构化摘要（上游 status、失败类型、说明）；上游原始响应正文 可能带 token 和账号信息，只写服务端日志，不回传调用方。
• 上游失败时刷新后的账号状态放在 trailing metadata x-threads-account-state-bin； Python SDK 已自动采纳，使用者应在异常后仍从 account.state 读取并持久化。