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_CONSUMER_KEY="your-consumer-key"
export X_CONSUMER_SECRET="your-consumer-secret"
export X_ACCESS_TOKEN="your-access-token"
export X_ACCESS_TOKEN_SECRET="your-access-token-secret"

X_API_KEY、X_API_SECRET、X_ACCESS_SECRET などの従来のエイリアスは古いセットアップに存在することがあります。新しいフローを文書化またはワイヤリングする際は、X_CONSUMER_* および X_ACCESS_TOKEN_SECRET の名前を優先してください。

import os
from requests_oauthlib import OAuth1Session

oauth = OAuth1Session(
    os.environ["X_CONSUMER_KEY"],
    client_secret=os.environ["X_CONSUMER_SECRET"],
    resource_owner_key=os.environ["X_ACCESS_TOKEN"],
    resource_owner_secret=os.environ["X_ACCESS_TOKEN_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/tweets/search/recent",
    headers=headers,
    params={
        "query": "from:affaanmustafa -is:retweet -is:reply",
        "max_results": 25,
        "tweet.fields": "created_at,public_metrics",
    }
)
voice_samples = resp.json()

ユーザー名でユーザーを取得

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}")

セキュリティ

• トークンをハードコーディングしないでください。 環境変数または .env ファイルを使用してください。
• .env ファイルをコミットしないでください。 .gitignore に追加してください。
• 露出した場合はトークンをローテーションしてください。 developer.x.com で再生成してください。
• 書き込みアクセスが不要な場合は読み取り専用トークンを使用してください。
• OAuth シークレットを安全に保存してください — ソースコードやログには含めないでください。

コンテンツエンジンとの統合

brand-voice と content-engine を使用してプラットフォーム固有のコンテンツを生成し、X API 経由で投稿します:

1. 音声マッチングが重要な場合は、最近のオリジナル投稿を取得
2. VOICE PROFILE を構築または再利用
3. content-engine で X ネイティブ形式のコンテンツを生成
4. 長さとスレッド構造を検証
5. ユーザーが今すぐ投稿することを明確に要求した場合を除き、承認用のドラフトを返す
6. 承認後のみ X API 経由で投稿
7. public_metrics 経由でエンゲージメントを追跡

関連スキル

• brand-voice — 実際の X とサイト/ソース資料から再利用可能な音声プロファイルを構築
• content-engine — X 用のプラットフォーム固有のコンテンツを生成
• crosspost — X、LinkedIn、その他のプラットフォーム間でコンテンツを配信
• connections-optimizer — ネットワーク駆動のアウトリーチ起草前に X グラフを再編成