API 模块与任务指南¶
这份文档先回答“为了完成任务应该调用什么”，再链接到逐字段接口参考。
所有调用均通过 ThreadsClient 的异步子客户端完成。
参数来源约定¶
- 用户输入：正文、搜索词、主题、位置、投票等业务输入。
- 受保护账号配置：token、密码、2FA seed；不得出现在源码或日志。
- 持久设备身份：
device_id、uuid、LoginDevice；同一账号长期复用。 - 前置响应：必须从上一步真实响应提取，例如图片上传返回的
upload_id。 - 运行时生成：会话 ID、上传 ID、追踪 ID；按接口说明生成或交给 SDK。
- 分页响应：上一页
next_cursor只能用于同一接口、同一查询的下一页。
任务入口¶
| 任务 | 模块 | 状态 | 第一调用 |
|---|---|---|---|
校验已保存的完整账号状态 (verify_session) |
登录与当前账号 | available |
AccountAuthClient.get_current_user |
账密登录并取得 IGT:2 (login) |
登录与当前账号 | experimental |
AuthClient.login |
安全编辑当前账号资料 (edit_profile) |
资料与主页帖子 | available |
AccountAuthClient.get_current_user |
发布文本帖 (create_text_post) |
帖子发布与删除 | available |
PostsClient.create_text_post |
发布单图帖 (create_image_post) |
帖子发布与删除 | available |
PostsClient.upload_image |
发布视频帖 (create_video_post) |
帖子发布与删除 | unavailable |
无可用接口 |
分页采集主页帖子 (collect_profile_threads) |
资料与主页帖子 | available |
ProfileClient.list_profile_threads |
以下内容按业务模块展开。每个模块先列接口，再列需要多个接口协作的任务。
登录与当前账号¶
登录、校验会话并读取当前账号身份。
Python 入口：client.auth（仅登录）/ account.auth（登录后）
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
账号登录AuthClient.login |
没有可用 IGT:2，并且需要通过账密建立新会话时。 | experimental |
读取当前账号AccountAuthClient.get_current_user |
校验 AccountState 会话、取得当前 uid，或在资料编辑前读取完整原值时。 | available |
本模块任务¶
校验已保存的完整账号状态 verify_session¶
- 状态：
available - 目标：确认 AccountState 对应的真实账号，并取得后续调用使用的资料字段。
- 前置条件：已从使用者存储恢复完整 AccountState。；每个账号状态携带自己的可选 Proxy；不要让多账号共享可变状态对象。
| 步骤 | 调用接口 | 目的 | 输入与参数来源 | 响应与下一步 |
|---|---|---|---|---|
| 1 | AccountAuthClient.get_current_userthreads.auth.v1.AuthService/GetCurrentUser |
调用 get_current_user(edit=False) 校验会话。 | 先通过 client.account(state) 创建账号客户端，再传 edit=False。 | 核对 pk、username；任务结束后保存 account.state。 |
账密登录并取得 IGT:2 login¶
- 状态：
experimental - 目标：通过 CAA/Bloks 登录生成会话并即时核对账号身份。
- 前置条件：准备账号、密码和可选 TOTP seed；Proxy 可省略。；生产容器已经固定加载仓库版本化 keybox.xml；SDK 用户不传 keybox。；登录成功后由使用者持久化返回的 AccountState。
| 步骤 | 调用接口 | 目的 | 输入与参数来源 | 响应与下一步 |
|---|---|---|---|---|
| 1 | AuthClient.loginthreads.auth.v1.AuthService/Login |
提交账号、密码、可选 2FA seed 和可选账号代理；Go server 生成首次登录设备。 | 代理可省略；传递 Proxy(host, port, protocol, username, password)。username/password 成对可选，省略时用于 IP 白名单代理；协议支持 HTTP、HTTPS、SOCKS5、SOCKS5H。配置字符串只能先通过 Proxy.from_url() 转成强类型对象。不要把密码、2FA seed 或代理凭据写入日志。 | 核对 success、account_state、verified_user.username 和 assurance；把 account_state 保存到使用者自己的存储。 |
步骤间参数传递¶
LoginResponse.account_state→ThreadsClient.account(state)：后续独立任务从使用者存储加载完整状态；SDK 不负责持久化。
当前缺失能力¶
- 软件环境尚不能证明 session 可长期稳定；stable_for_automation 必须保持 false，直到硬件证明和存活观测通过。
资料与主页帖子¶
读取用户资料、保存当前账号资料并分页采集主页帖子。
Python 入口：account.profile
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
读取指定用户资料ProfileClient.get_user_info |
已知用户 ID，需要读取公开资料和账号统计时。 | available |
分页读取主页帖子ProfileClient.list_profile_threads |
采集指定账号主页帖子、验证发帖或验证删除结果时。 | available |
保存当前账号资料ProfileClient.edit_profile |
修改用户名、显示名、简介、隐私状态或外部链接时。 | available |
本模块任务¶
安全编辑当前账号资料 edit_profile¶
- 状态：
available - 目标：修改指定资料字段，同时避免整表回传接口清空未携带的原值。
- 前置条件：已从使用者存储恢复完整 AccountState。
| 步骤 | 调用接口 | 目的 | 输入与参数来源 | 响应与下一步 |
|---|---|---|---|---|
| 1 | AccountAuthClient.get_current_userthreads.auth.v1.AuthService/GetCurrentUser |
先调用 get_current_user(edit=True) 读取完整当前资料。 | edit=True。 | 保存 username、full_name、biography、is_private、external_url 和 bio_links。 |
| 2 | ProfileClient.edit_profilethreads.profile.v1.ProfileService/EditProfile |
只替换目标字段，其余字段使用上一步原值并整表提交。 | username/first_name/biography/is_private 必须完整回传；设备身份由 AccountState 内部提供。 | 核对返回资料，再调用 get_current_user(edit=True) 验证保存结果。 |
步骤间参数传递¶
CurrentUser.username/full_name/biography/is_private/external_url→EditProfileRequest 对应字段：未修改字段必须回填原值，不能省略。
当前缺失能力¶
- 头像和封面需要独立上传端点，当前契约未实现。
- location 不是 EditProfile 端点字段。
分页采集主页帖子 collect_profile_threads¶
- 状态：
available - 目标：读取指定账号主页帖子，并使用游标持续翻页。
- 前置条件：已从使用者存储恢复完整 AccountState。；准备目标 user_id。
| 步骤 | 调用接口 | 目的 | 输入与参数来源 | 响应与下一步 |
|---|---|---|---|---|
| 1 | ProfileClient.list_profile_threadsthreads.profile.v1.ProfileService/ListProfileThreads |
首次调用不传 max_id，读取 threads 强类型结果。 | user_id 为目标账号；exclude_reposts 按采集需求设置。 | 消费 threads[].items[].post，并读取 next_cursor。 |
| 2 | ProfileClient.list_profile_threadsthreads.profile.v1.ProfileService/ListProfileThreads |
next_cursor 非空时继续请求下一页。 | 将上一页 next_cursor 传入下一次 max_id。 | next_cursor 为空时结束；raw_json 只用于未建模字段排错。 |
步骤间参数传递¶
ProfileThreadsPage.next_cursor→ListProfileThreadsRequest.max_id：分页游标来自上一次真实响应。
帖子发布与删除¶
检查文本、发布文本帖、上传图片、发布单图帖和删除帖子。
Python 入口：account.posts
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
检查冒犯文本PostsClient.check_offensive_text |
发帖前希望执行上游文本风险检查时；当前真实上游返回 404。 | known-upstream-error |
创建文本帖PostsClient.create_text_post |
发布不带图片或视频的 Threads 文本帖子时；传 reply_id 时同一接口用于发布回复（评论）。 | available |
上传图片PostsClient.upload_image |
创建单图帖前上传 WebP 图片二进制时。 | available |
创建单图帖PostsClient.create_image_post |
UploadImage 成功后，把已上传图片发布为单图帖子时。 | available |
删除帖子PostsClient.delete_post |
删除当前账号已有帖子或清理测试帖子时。 | available |
点赞帖子PostsClient.like_media |
对指定帖子点赞时。 | available |
取消点赞PostsClient.unlike_media |
撤销此前对某帖的点赞时。 | available |
本模块任务¶
发布文本帖 create_text_post¶
- 状态：
available - 目标：使用当前账号和持久设备身份创建纯文本帖子。
- 前置条件：已从登录响应或使用者存储取得完整 AccountState。；写操作已获得明确授权。
| 步骤 | 调用接口 | 目的 | 输入与参数来源 | 响应与下一步 |
|---|---|---|---|---|
| 1 | PostsClient.create_text_postthreads.posts.v1.PostsService/CreateTextPost |
用 ThreadsClient.account(state).posts 提交 caption 和可选发帖功能字段。 | AccountState 自动提供 uid、完整设备、Session、代理与 App 版本；纯文本帖不需要先上传媒体。 | 核对 Media 的作者、caption、code 和 permalink，并把 account.state 的刷新结果写回使用者存储。 |
| 2 | ProfileClient.list_profile_threadsthreads.profile.v1.ProfileService/ListProfileThreads |
重新读取账号主页确认帖子真实出现。 | user_id 使用 AccountState.uid。 | 在 threads[].items[].post 中找到新帖子。 |
步骤间参数传递¶
LoginResponse.account_state 或使用者存储→CreateTextPostRequest.account_state：每个独立任务显式传入完整状态；响应状态覆盖保存后供下一任务使用。
发布单图帖 create_image_post¶
- 状态：
available - 目标：先上传 WebP 图片，再用上传结果创建单图帖子。
- 前置条件：已从登录响应或使用者存储取得完整 AccountState。；准备 WebP 图片字节及真实宽高。；写操作已获得明确授权。
| 步骤 | 调用接口 | 目的 | 输入与参数来源 | 响应与下一步 |
|---|---|---|---|---|
| 1 | PostsClient.upload_imagethreads.posts.v1.PostsService/UploadImage |
上传图片二进制及真实宽高。 | image_data 为 WebP bytes；original_width/original_height 来自图片元数据。 | 要求 status=ok，并保存响应 upload_id。 |
| 2 | PostsClient.create_image_postthreads.posts.v1.PostsService/CreateImagePost |
使用上传响应创建单图帖。 | upload_id 必须使用 UploadImageResult.upload_id；宽高与上传步骤保持一致。 | 核对 media_type=1、caption、image_versions2 和帖子作者。 |
| 3 | ProfileClient.list_profile_threadsthreads.profile.v1.ProfileService/ListProfileThreads |
重新读取账号主页确认图片帖真实出现。 | user_id 使用发帖 uid。 | 在 threads[].items[].post 中找到新帖子和图片字段。 |
步骤间参数传递¶
UploadImageResult.upload_id→CreateImagePostRequest.upload_id：图片上传返回值必须原样传给创建接口。UploadImageRequest.original_width/original_height→CreateImagePostRequest.original_width/original_height：创建接口使用与上传图片一致的真实尺寸。
发布视频帖 create_video_post¶
- 状态：
unavailable - 目标：上传视频并创建视频帖子。
- 前置条件：无
当前没有可执行调用步骤。
当前缺失能力¶
- 当前 Proto、Go SDK 和 Python 门面均没有视频上传 RPC。
- 当前没有视频 configure RPC、视频转码状态查询或封面上传工作流。
- 在完成真实抓包、契约和黑盒测试前，禁止复用 UploadImage/CreateImagePost 伪装视频发布。
回复采集¶
分页读取指定账号的回复列表。
Python 入口：account.replies
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
分页读取账号回复RepliesClient.list_profile_replies |
采集指定账号发布的回复时。 | available |
| ## 搜索与主题校验 |
关键词搜索以及发帖主题标签校验。
Python 入口：account.search
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
关键词搜索SearchClient.keyword_search |
按关键词查找 Threads 账号或内容时。 | available |
校验发帖主题SearchClient.validate_tag |
发帖前需要确认主题标签是否有效或敏感时。 | available |
| ## 推荐用户 |
分页读取 Threads 推荐账号。
Python 入口：account.feed
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
读取推荐用户FeedClient.list_recommended_users |
需要获取 Threads 推荐账号或继续推荐流分页时。 | available |
| ## 关系状态 |
读取与目标账号之间的关注、拉黑和静音状态。
Python 入口：account.friendships
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
读取关系状态FriendshipsClient.get_friendship_status |
需要确认当前账号是否关注、被关注、拉黑或静音目标账号时。 | available |
关注用户FriendshipsClient.follow_user |
关注目标账号时。 | available |
取消关注FriendshipsClient.unfollow_user |
取消对目标账号的关注时。 | available |