跳转至

X API

以编程方式与 X（Twitter）交互，用于发布、读取、搜索和分析。

适用场景

  • 用户想以编程方式发布推文或线程
  • 读取 X 的时间线、提及或用户数据
  • 在 X 上搜索内容、趋势或对话
  • 构建 X 集成或机器人
  • 分析和互动追踪
  • 用户提到“发布到 X”、“发推”、“X API”或“Twitter API”

认证

OAuth 2.0 Bearer Token（仅应用）

最佳用途：读取密集型操作、搜索、公开数据。

# Environment setup
export X_BEARER_TOKEN="your-bearer-token"

import os
import requests

bearer = os.environ["X_BEARER_TOKEN"]
headers = {"Authorization": f"Bearer {bearer}"}

# Search recent tweets
resp = requests.get(
    "https://api.x.com/2/tweets/search/recent",
    headers=headers,
    params={"query": "claude code", "max_results": 10}
)
tweets = resp.json()

OAuth 1.0a（用户上下文）

以下场景需要：发布推文、账户管理、DM。

# Environment setup — source before use
export X_API_KEY="your-api-key"
export X_API_SECRET="your-api-secret"
export X_ACCESS_TOKEN="your-access-token"
export X_ACCESS_SECRET="your-access-secret"

import os
from requests_oauthlib import OAuth1Session

oauth = OAuth1Session(
    os.environ["X_API_KEY"],
    client_secret=os.environ["X_API_SECRET"],
    resource_owner_key=os.environ["X_ACCESS_TOKEN"],
    resource_owner_secret=os.environ["X_ACCESS_SECRET"],
)

核心操作

发布一条推文

resp = oauth.post(
    "https://api.x.com/2/tweets",
    json={"text": "Hello from Claude Code"}
)
resp.raise_for_status()
tweet_id = resp.json()["data"]["id"]

发布线程

def post_thread(oauth, tweets: list[str]) -> list[str]:
    ids = []
    reply_to = None
    for text in tweets:
        payload = {"text": text}
        if reply_to:
            payload["reply"] = {"in_reply_to_tweet_id": reply_to}
        resp = oauth.post("https://api.x.com/2/tweets", json=payload)
        tweet_id = resp.json()["data"]["id"]
        ids.append(tweet_id)
        reply_to = tweet_id
    return ids

读取用户时间线

resp = requests.get(
    f"https://api.x.com/2/users/{user_id}/tweets",
    headers=headers,
    params={
        "max_results": 10,
        "tweet.fields": "created_at,public_metrics",
    }
)

搜索推文

resp = requests.get(
    "https://api.x.com/2/tweets/search/recent",
    headers=headers,
    params={
        "query": "from:affaanmustafa -is:retweet",
        "max_results": 10,
        "tweet.fields": "public_metrics,created_at",
    }
)

按用户名获取用户

resp = requests.get(
    "https://api.x.com/2/users/by/username/affaanmustafa",
    headers=headers,
    params={"user.fields": "public_metrics,description,created_at"}
)

上传媒体并发布

# Media upload uses v1.1 endpoint

# Step 1: Upload media
media_resp = oauth.post(
    "https://upload.twitter.com/1.1/media/upload.json",
    files={"media": open("image.png", "rb")}
)
media_id = media_resp.json()["media_id_string"]

# Step 2: Post with media
resp = oauth.post(
    "https://api.x.com/2/tweets",
    json={"text": "Check this out", "media": {"media_ids": [media_id]}}
)

速率限制

X API 的速率限制因端点、认证方法和账户层级而异，并会随时间变化。始终：

  • 在做出硬编码假设之前，查阅当前 X 开发者文档
  • 在运行时读取 x-rate-limit-remaining 和 x-rate-limit-reset 标头
  • 不要依赖代码中的静态表，而是自动退避
import time

remaining = int(resp.headers.get("x-rate-limit-remaining", 0))
if remaining < 5:
    reset = int(resp.headers.get("x-rate-limit-reset", 0))
    wait = max(0, reset - int(time.time()))
    print(f"Rate limit approaching. Resets in {wait}s")

错误处理

resp = oauth.post("https://api.x.com/2/tweets", json={"text": content})
if resp.status_code == 201:
    return resp.json()["data"]["id"]
elif resp.status_code == 429:
    reset = int(resp.headers["x-rate-limit-reset"])
    raise Exception(f"Rate limited. Resets at {reset}")
elif resp.status_code == 403:
    raise Exception(f"Forbidden: {resp.json().get('detail', 'check permissions')}")
else:
    raise Exception(f"X API error {resp.status_code}: {resp.text}")

安全

  • 不要硬编码 Token。 使用环境变量或 .env 文件。
  • 不要提交 .env 文件。 将其添加到 .gitignore。
  • 如果 Token 泄露，请轮换它。 在 developer.x.com 上重新生成。
  • 如果不需要写入权限，请使用只读 Token。
  • 安全保管 OAuth 密钥 — 不要保存在源代码或日志中。

与内容引擎集成

使用 content-engine 技能生成平台原生内容，并通过 X API 发布：

  1. 使用内容引擎生成内容（X 平台格式）
  2. 验证长度（每条推文 280 个字符）
  3. 使用上述模式通过 X API 发布
  4. 使用 public_metrics 追踪互动
  • content-engine — 为 X 生成平台原生内容
  • crosspost — 在 X、LinkedIn 和其他平台上分发内容

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC