快速开始¶

本页使用已有 IGT:2 token 完成第一次真实 API 调用。你会启动服务、连接一个账号并读取当前用户。

1. 启动 Go gRPC 服务¶

go run ./cmd/server

默认监听 127.0.0.1:50051。生产容器已经把仓库固定 keybox.xml 放到 /run/secrets/threads-keybox.xml 并自动配置 signer，Python SDK 用户不传 keybox。不要把 token、 cookie、密码、2FA seed 或代理凭据写入仓库和日志。

跨主机部署时，为 Go server 挂载 TLS 证书与私钥并同时配置：

THREADS_GRPC_ADDR='0.0.0.0:50051' \
THREADS_GRPC_TLS_CERT_FILE='/run/tls/server.crt' \
THREADS_GRPC_TLS_KEY_FILE='/run/tls/server.key' \
go run ./cmd/server

证书或私钥只配置一项时 server 会拒绝启动。本机默认模式可以两项都省略。

生产容器跨机器提供服务时，使用仓库提供的 TLS Compose 叠加文件：

THREADS_IMAGE=ghcr.io/open-luban/go-threads-api \
IMAGE_TAG=0.1.0 \
THREADS_GRPC_API_KEY='<至少 32 字符的随机值>' \
THREADS_GRPC_BIND_HOST=0.0.0.0 \
THREADS_GRPC_TLS_CERT_HOST_PATH=/absolute/path/server.crt \
THREADS_GRPC_TLS_KEY_HOST_PATH=/absolute/path/server.key \
THREADS_GRPC_TLS_SERVER_NAME=threads-api.example.com \
docker compose \
  -f docker-compose-pro.yml \
  -f docker-compose-pro-tls.yml \
  up -d

证书 SAN 必须覆盖客户端连接使用的主机名。叠加文件会把同一证书交给容器内标准 gRPC healthcheck 校验，私钥只读挂载。

2. 安装 Python 客户端¶

每个 Go server Tag 都会同时发布相同 X.Y.Z 版本的 Python SDK。从当前文档版本的 Python SDK 下载页下载 wheel 后安装：

uv add ./threads_sdk-X.Y.Z-py3-none-any.whl

如果不安装包，也可以下载 threads_sdk-X.Y.Z-copy.zip，解压后把完整 threads_sdk/ 目录复制进项目。其中已经包含生成的 protobuf/gRPC stub；运行环境只需 grpcio 和 protobuf，不需要生成 stub。

仓库贡献者开发时才使用 uv sync --project python。

3. 读取当前账号¶

先从自己的存储恢复登录返回的完整 AccountState。SDK 不负责选择数据库或文件格式；下面只用本地文件演示。 dump_account_state() 的结果包含 token、设备身份和可能存在的代理凭据，生产环境必须在存储层加密，不能照搬示例明文落盘。

运行以下 Python：

import asyncio
import os
from pathlib import Path

from threads_sdk import ThreadsClient, dump_account_state, load_account_state


async def main() -> None:
    state_path = Path("account-state.bin")
    state = load_account_state(state_path.read_bytes())
    async with ThreadsClient(
        target=os.getenv("THREADS_GRPC_TARGET", "127.0.0.1:50051"),
        tls=os.getenv("THREADS_GRPC_TLS") == "1",
        root_certificates=(
            Path(os.environ["THREADS_GRPC_CA_FILE"]).read_bytes()
            if os.getenv("THREADS_GRPC_CA_FILE")
            else None
        ),
        api_key=os.getenv("THREADS_GRPC_API_KEY"),
        default_timeout=60,
    ) as client:
        account = client.account(state)
        current = await account.auth.get_current_user(
            edit=False,
            timeout=15,
        )
        print(current.pk, current.username)
        state_path.write_bytes(dump_account_state(account.state))


asyncio.run(main())

target 是启动客户端时唯一必需的服务连接配置；默认连接 127.0.0.1:50051，部署到其他受保护地址时通过 THREADS_GRPC_TARGET 设置。跨主机时必须启用 TLS；Go server 同时配置 THREADS_GRPC_TLS_CERT_FILE / THREADS_GRPC_TLS_KEY_FILE，SDK 设置 tls=True。私有 CA 通过 root_certificates 提供；公开 CA 可省略。非 loopback 监听必须设置至少 32 字符的 THREADS_GRPC_API_KEY，客户端通过 api_key 传递；TLS 和 API key 都不能省略。

default_timeout 默认就是 60 秒，控制所有 RPC 的默认 deadline；每个公开异步方法都支持单独的 timeout=。逐调用值优先。ARQ 的任务级超时、取消、重试和幂等仍由使用者负责。

输出的 pk 必须属于 AccountState 对应账号。业务调用完成后把 account.state 写回使用者自己的存储，下一次独立任务直接恢复，不重新生成设备。

公开 AccountState 是隐藏 protobuf 的安全值对象，repr() / str() 不输出 Session、设备标识或代理凭据；持久化只使用 dump_account_state()，不要依赖 threads_sdk._generated。

代理可省略；登录时通过强类型 Proxy 传递协议、主机、端口和成对可选的账号密码，成功后随 AccountState 保存。支持 HTTP、HTTPS、SOCKS5、SOCKS5H；省略账号密码时适用于 IP 白名单代理。环境变量中的字符串先用 Proxy.from_url() 转换。无效协议、主机、端口、半截认证信息或附带 path/query/fragment，都会在请求发出前被拒绝。

如果没有可用 token，请阅读账密登录工作流。调用方只提供账号、密码、可选 TOTP seed 和可选账号代理；Go server 自动生成成套设备，并在成功响应的 AccountState 中返回。后续任务必须保存和复用该状态，不能重新生成设备。

下一步¶

Python SDK 下载页：下载与 Go server 同版本的 wheel、sdist 或可复制目录包。
模块与任务指南：发布文本帖、发布单图帖、编辑资料和分页采集。
接口与参数参考：查看每个字段的类型、是否可选以及动态参数来源。

交给 AI 对接¶

把公开的 https://threads-api.es007.com/llms.txt 直接交给具备网页读取能力的 AI；测试版本使用 https://threads-api.es007.com/test/latest/llms.txt。完整说明见 AI 直接接入。Python 代码生成应继续读取 python/llms-full.txt，其中包含任务工作流、动态参数来源和步骤间字段映射。