如何用 TwexAPI 发布 X Thread

有些内容不适合塞进一条 X 帖子里。产品发布说明、研究总结、事故进展、创始人观点，通常都需要一个稳定顺序：第一条给出主题，后面补背景、证据、限制和下一步。

TwexAPI 的 Create a Tweet Thread 端点可以用一次请求发布这组有序内容。你传入 items 数组、X 账号的 cookie 或 auth_token，响应会按 thread 顺序返回已发布帖子的 tweet ID。

这是写入接口，所以不要把它当成“生成内容”的工具。更稳的做法是先在自己的系统里写草稿、审核每一条，再在确认后调用 API 发布。

端点和请求字段

当你已经有最终版 thread 文案，并希望 TwexAPI 按顺序发布时，使用 POST /v3/twitter/tweets/create-thread。

字段	类型	必填	说明
`items`	string array	是	有序推文文本数组。第一项会成为 thread 的第一条帖子。
`cookie`	string	是	X 认证 cookie 或 `auth_token`。只应保存在服务端密钥中，不要写进前端代码。
`proxy`	string 或 null	否	可选的发布会话代理，例如 `http://username:password@ip:port`。

文档中标注该端点为 $0.0025 每次调用。即使单次调用成本很低，你自己的系统也应该记录每一次发布尝试，因为写入接口如果重试不当，可能造成重复 thread 或部分发布。

基础请求

1curl --request POST \
2  --url https://api.twexapi.io/v3/twitter/tweets/create-thread \
3  --header "Authorization: Bearer $TWEXAPI_BEARER_TOKEN" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "items": [
7      "1/ 我们刚为研究团队上线了更清晰的导出流程。",
8      "2/ 新流程会为每一行保留 query、cursor、fetched_at 时间戳和原始 tweet ID。",
9      "3/ 这样审计更容易：团队可以解释每条结果来自哪里，而不是只相信一张没有来源上下文的表格。"
10    ],
11    "cookie": "auth_token=...; ct0=...; twid=..."
12  }'

成功响应会返回 code、msg 和 data.tweets。每个 item 里包含已发布帖子的 tweet id。

{
  "code": 200,
  "msg": "success",
  "data": {
    "tweets": [
      { "id": "1234567890123456789" },
      { "id": "1234567890123456790" },
      { "id": "1234567890123456791" }
    ]
  }
}

这些 ID 应该立即保存。它们连接了内部草稿、线上 thread、数据分析、评论监控，以及后续删除或修正流程。

带审批开关的 Python 发布脚本

下面这个脚本把凭据放在环境变量里，并且只有在显式设置 PUBLISH_THREAD=true 时才会发布。这个小开关可以避免本地测试或 CI 预览误发真实 thread。

1import os
2from datetime import datetime, timezone
3from typing import Any
4
5import requests
6
7API_URL = "https://api.twexapi.io/v3/twitter/tweets/create-thread"
8BEARER_TOKEN = os.environ["TWEXAPI_BEARER_TOKEN"]
9X_COOKIE = os.environ["TWEXAPI_X_COOKIE"]
10PROXY = os.environ.get("TWEXAPI_PROXY")
11
12def validate_thread_items(items: list[str]) -> list[str]:
13    cleaned = []
14
15    for index, item in enumerate(items, start=1):
16        text = item.strip()
17        if not text:
18            raise ValueError(f"Thread item {index} is empty")
19        cleaned.append(text)
20
21    if not cleaned:
22        raise ValueError("Thread must contain at least one post")
23
24    return cleaned
25
26def create_tweet_thread(items: list[str]) -> dict[str, Any]:
27    payload: dict[str, Any] = {
28        "items": validate_thread_items(items),
29        "cookie": X_COOKIE,
30    }
31
32    if PROXY:
33        payload["proxy"] = PROXY
34
35    response = requests.post(
36        API_URL,
37        headers={
38            "Authorization": f"Bearer {BEARER_TOKEN}",
39            "Content-Type": "application/json",
40            "Accept": "application/json",
41        },
42        json=payload,
43        timeout=60,
44    )
45    response.raise_for_status()
46    data = response.json()
47
48    if data.get("code") != 200:
49        raise RuntimeError(data.get("msg", "TwexAPI returned an error"))
50
51    return data
52
53def normalize_result(draft_id: str, response: dict[str, Any]) -> dict[str, Any]:
54    tweets = response.get("data", {}).get("tweets") or []
55    return {
56        "draft_id": draft_id,
57        "published_at": datetime.now(timezone.utc).isoformat(),
58        "tweet_ids": [tweet.get("id") for tweet in tweets if tweet.get("id")],
59        "api_code": response.get("code"),
60        "api_msg": response.get("msg"),
61        "raw_response": response,
62    }
63
64if __name__ == "__main__":
65    draft_id = "launch-notes-2026-07-14"
66    thread_items = [
67        "1/ 我们刚为研究团队上线了更清晰的导出流程。",
68        "2/ 新流程会为每一行保留 query、cursor、fetched_at 时间戳和原始 tweet ID。",
69        "3/ 这样审计更容易：团队可以解释每条结果来自哪里，而不是只相信一张没有来源上下文的表格。",
70    ]
71
72    reviewed_items = validate_thread_items(thread_items)
73
74    if os.environ.get("PUBLISH_THREAD") != "true":
75        print("Review mode only. Set PUBLISH_THREAD=true after approval.")
76        for number, text in enumerate(reviewed_items, start=1):
77            print(f"{number}: {text}")
78        raise SystemExit(0)
79
80    result = create_tweet_thread(reviewed_items)
81    print(normalize_result(draft_id, result))

在服务端或可信工作站运行：

TWEXAPI_BEARER_TOKEN="your_twexapi_bearer_token" \
TWEXAPI_X_COOKIE="auth_token=...; ct0=...; twid=..." \
PUBLISH_THREAD=true \
python publish_thread.py

如果你的发布环境需要代理，再设置 TWEXAPI_PROXY。

实际发布流程

API 调用应该是内容系统的最后一步。更可靠的流程通常是：

草稿：把 thread 存成多条独立记录，而不是一个大段落。
校验：检查空内容、错误链接、重复编号，以及当前账号的 X 发布限制。
审批：要求编辑、运营或 campaign owner 标记为可发布。
发布：只对审批后的版本调用一次 POST /v3/twitter/tweets/create-thread。
记录：保存有序 tweet_ids、草稿 ID、发布时间和原始 API 响应。
监控：用保存的 ID 做回复监控、互动统计或后续修正。

这对产品发布尤其重要。如果第一条写着“已上线”，但第三条链接错了，你需要知道是哪份草稿被批准、实际发布出了哪些 tweet ID。

保存 Thread 状态

至少建议为整个 thread 保存一条主记录，并为每个 item 保存一条子记录。

字段	作用
`thread_draft_id`	把线上 thread 关联回内部草稿。
`account_id`	标识由哪个 X 账号发布。
`position`	保留发布前后的顺序。
`text`	保存已审批并发送的文本。
`tweet_id`	把每条草稿 item 关联到发布后的 X 帖子。
`status`	支持 `draft`、`approved`、`published`、`failed` 等状态。
`published_at`	方便后续分析和事故复盘。
`raw_response`	保留原始 API 证据，便于排查。

不要在这张表里保存完整 cookie。保存凭据记录 ID 或密钥名称即可。

重试和失败处理

发布 thread 不是读取请求。如果请求超时发生在 API 已经发布了一条或多条帖子之后，盲目重试同一个 payload 可能造成重复发布。

建议用保守流程处理失败：

发布前先保存请求 payload 的 hash。
成功后按顺序保存所有返回的 tweet ID。
如果发生 timeout 或未知失败，先人工检查账号，或用读取端点确认线上状态，再决定是否重试。
如果响应中的 tweet ID 数量少于 items 数量，把 thread 标记为待复核，不要自动重试。
不要在浏览器或不可信客户端调用该端点，因为请求里包含账号凭据。

目标不是把发帖变成完全无人值守，而是让已审批内容的发布可复现、可追踪、可复核。

什么时候适合用这个端点

当多条帖子之间的顺序和关系很重要时，适合使用 thread 端点。例如：

带功能细节的产品发布 thread
包含证据和限制说明的研究总结
需要按顺序更新的事故说明
由 hook、论据和行动号召组成的 campaign 内容
已经由编辑审核过的教学型 thread

如果只是单条帖子，用普通 tweet 发布端点即可。如果是长篇 Markdown 内容，更适合使用 X Article 端点。Thread 的价值在于：每条短帖都能单独阅读，但又属于同一个更大的叙事。

总结

POST /v3/twitter/tweets/create-thread 可以把一个已审批的有序文本数组发布为 X thread，并返回已发布帖子的 tweet ID。最稳的实现并不复杂：校验列表、要求审批、发布一次、保存有序 ID，并把不确定失败交给复核流程。

这样可以保留 thread 自动化的效率，同时避免把写入接口变成不可控的发帖循环。