API 模块与任务指南¶
这份文档先回答“为了完成任务应该调用什么”，再链接到逐字段接口参考。
所有调用均通过 ThreadsClient 的异步子客户端完成。
参数来源约定¶
- 用户输入：正文、搜索词、主题、位置、投票等业务输入。
- 受保护账号配置：token、密码、2FA seed；不得出现在源码或日志。
- 持久设备身份：
device_id、uuid、LoginDevice；同一账号长期复用。 - 前置响应：必须从上一步真实响应提取，例如图片上传返回的
upload_id。 - 运行时生成：会话 ID、上传 ID、追踪 ID；按接口说明生成或交给 SDK。
- 分页响应：上一页
next_cursor只能用于同一接口、同一查询的下一页。
任务入口¶
| 任务 | 模块 | 状态 | 第一调用 |
|---|---|---|---|
校验现有 IGT:2 会话 (verify_session) |
登录与当前账号 | available |
AuthClient.get_current_user |
账密登录并取得 IGT:2 (login) |
登录与当前账号 | experimental |
AuthClient.login |
安全编辑当前账号资料 (edit_profile) |
资料与主页帖子 | available |
AuthClient.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
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
账号登录AuthClient.login |
没有可用 IGT:2，并且需要通过账密建立新会话时。 | experimental |
读取当前账号AuthClient.get_current_user |
校验 token 身份、取得当前 uid，或在资料编辑前读取完整原值时。 | available |
本模块任务¶
校验现有 IGT:2 会话 verify_session¶
- 状态：
available - 目标：确认 token 对应的真实账号，并取得后续调用使用的 uid 和资料字段。
- 前置条件：ThreadsClient 已注入 IGT:2 token。；每个账号使用独立 proxy_url；不要让多账号共享出口。
| 步骤 | 调用接口 | 目的 | 输入与参数来源 | 响应与下一步 |
|---|---|---|---|---|
| 1 | AuthClient.get_current_userthreads.auth.v1.AuthService/GetCurrentUser |
调用 get_current_user(edit=False) 校验会话。 | edit=False；token 和代理由 ThreadsClient metadata 自动注入。 | 核对 pk、username；将 pk 作为发帖 uid 或目标 user_id。 |
账密登录并取得 IGT:2 login¶
- 状态：
experimental - 目标：通过 CAA/Bloks 登录生成会话并即时核对账号身份。
- 前置条件：准备持久化设备参数 LoginDevice。；生产使用必须在 Go server 通过 THREADS_KEYBOX_FILE 加载硬件 attestation signer；Docker 镜像从仓库根目录版本化 keybox.xml 构建。；无硬件证明登录属于高风险操作，必须得到明确授权。
| 步骤 | 调用接口 | 目的 | 输入与参数来源 | 响应与下一步 |
|---|---|---|---|---|
| 1 | AuthClient.loginthreads.auth.v1.AuthService/Login |
提交账号、密码、设备和可选 2FA seed。 | 默认 allow_unattested_login=False；不要把密码或 2FA seed 写入日志。 | 核对 success、session.token、verified_user.username 和 assurance。 |
| 2 | AuthClient.get_current_userthreads.auth.v1.AuthService/GetCurrentUser |
用新 token 创建 ThreadsClient 后再次读取当前账号。 | 将 LoginResponse.session.token 注入 ThreadsClient.token。 | 确认 pk、username 与登录账号一致；即时成功不代表长期稳定。 |
步骤间参数传递¶
LoginResponse.session.token→ThreadsClient.token：登录返回的 IGT:2 用于后续全部业务 RPC。
当前缺失能力¶
- 软件环境尚不能证明 session 可长期稳定；stable_for_automation 必须保持 false，直到硬件证明和存活观测通过。
资料与主页帖子¶
读取用户资料、保存当前账号资料并分页采集主页帖子。
Python 入口：client.profile
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
读取指定用户资料ProfileClient.get_user_info |
已知用户 ID，需要读取公开资料和账号统计时。 | available |
分页读取主页帖子ProfileClient.list_profile_threads |
采集指定账号主页帖子、验证发帖或验证删除结果时。 | available |
保存当前账号资料ProfileClient.edit_profile |
修改用户名、显示名、简介、隐私状态或外部链接时。 | available |
本模块任务¶
安全编辑当前账号资料 edit_profile¶
- 状态：
available - 目标：修改指定资料字段，同时避免整表回传接口清空未携带的原值。
- 前置条件：已有有效 IGT:2 token。；已持久化当前账号 uuid。
| 步骤 | 调用接口 | 目的 | 输入与参数来源 | 响应与下一步 |
|---|---|---|---|---|
| 1 | AuthClient.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 必须完整回传；uuid 来自持久设备身份。 | 核对返回资料，再调用 get_current_user(edit=True) 验证保存结果。 |
步骤间参数传递¶
CurrentUser.username/full_name/biography/is_private/external_url→EditProfileRequest 对应字段：未修改字段必须回填原值，不能省略。
当前缺失能力¶
- 头像和封面需要独立上传端点，当前契约未实现。
- location 不是 EditProfile 端点字段。
分页采集主页帖子 collect_profile_threads¶
- 状态：
available - 目标：读取指定账号主页帖子，并使用游标持续翻页。
- 前置条件：已有有效 IGT:2 token。；准备目标 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 入口：client.posts
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
检查冒犯文本PostsClient.check_offensive_text |
发帖前希望执行上游文本风险检查时；当前真实上游返回 404。 | known-upstream-error |
创建文本帖PostsClient.create_text_post |
发布不带图片或视频的 Threads 文本帖子时。 | available |
上传图片PostsClient.upload_image |
创建单图帖前上传 WebP 图片二进制时。 | available |
创建单图帖PostsClient.create_image_post |
UploadImage 成功后，把已上传图片发布为单图帖子时。 | available |
删除帖子PostsClient.delete_post |
删除当前账号已有帖子或清理测试帖子时。 | available |
本模块任务¶
发布文本帖 create_text_post¶
- 状态：
available - 目标：使用当前账号和持久设备身份创建纯文本帖子。
- 前置条件：已有有效 IGT:2 token。；已通过 get_current_user 取得 uid。；已持久化 device_id 和 uuid。；写操作已获得明确授权。
| 步骤 | 调用接口 | 目的 | 输入与参数来源 | 响应与下一步 |
|---|---|---|---|---|
| 1 | PostsClient.create_text_postthreads.posts.v1.PostsService/CreateTextPost |
提交 caption、uid、device_id、uuid 和可选发帖功能字段。 | 纯文本帖不需要先上传媒体；upload_id 可省略或由调用方生成。 | 核对返回 Media 的作者、caption、code 和 permalink。 |
| 2 | ProfileClient.list_profile_threadsthreads.profile.v1.ProfileService/ListProfileThreads |
重新读取账号主页确认帖子真实出现。 | user_id 使用发帖 uid。 | 在 threads[].items[].post 中找到新帖子。 |
步骤间参数传递¶
CurrentUser.pk→CreateTextPostRequest.uid：发帖 uid 来自当前账号身份校验。
发布单图帖 create_image_post¶
- 状态：
available - 目标：先上传 WebP 图片，再用上传结果创建单图帖子。
- 前置条件：已有有效 IGT:2 token。；已通过 get_current_user 取得 uid。；已持久化 device_id 和 uuid。；准备 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 入口：client.replies
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
分页读取账号回复RepliesClient.list_profile_replies |
采集指定账号发布的回复时。 | available |
| ## 搜索与主题校验 |
关键词搜索以及发帖主题标签校验。
Python 入口：client.search
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
关键词搜索SearchClient.keyword_search |
按关键词查找 Threads 账号或内容时。 | available |
校验发帖主题SearchClient.validate_tag |
发帖前需要确认主题标签是否有效或敏感时。 | available |
| ## 推荐用户 |
分页读取 Threads 推荐账号。
Python 入口：client.feed
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
读取推荐用户FeedClient.list_recommended_users |
需要获取 Threads 推荐账号或继续推荐流分页时。 | available |
| ## 关系状态 |
读取与目标账号之间的关注、拉黑和静音状态。
Python 入口：client.friendships
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
读取关系状态FriendshipsClient.get_friendship_status |
需要确认当前账号是否关注、被关注、拉黑或静音目标账号时。 | available |
| ## 账号洞察 |
读取账号洞察；当前缺少真实 GraphQL doc_id，尚不可用。
Python 入口：client.insights
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
读取账号洞察InsightsClient.get_account_insights |
需要账号洞察数据时；当前接口尚不可用。 | unimplemented |
| ## 提及建议 |
获取 @ 提及建议；当前缺少真实 GraphQL doc_id，尚不可用。
Python 入口：client.mentions
本模块接口¶
| 接口 | 什么时候调用 | 状态 |
|---|---|---|
获取提及建议MentionsClient.get_mention_suggestions |
输入 @ 用户名时需要候选建议；当前接口尚不可用。 | unimplemented |