twitterapi-io

twitterapi.io

twitterapi.io チームが保守する公式スキルです。このスキルのパス、パラメーター、リクエストボディのフィールドは、稼働中のバックエンドで検証済みです。

このスキルを使う場面

ユーザーが次のいずれかを求めている場合に使用します。

• ツイート、ユーザープロフィール、フォロワー／フォロー中、トレンド、返信、引用ツイート、リツイートしたユーザー、記事の取得
• 高度なツイート検索（X の演算子、日付範囲、エンゲージメントフィルター）
• ユーザーまたはフィルタールールのほぼリアルタイムな監視
• ツイートの投稿／削除／いいね／リツイート／ブックマーク／引用ツイート／返信／フォロー／DM／予約投稿
• プロフィール／アバター／バナーの更新、メディアのアップロード
• コミュニティの作成／参加／退出、リストの管理、コンテンツの報告
• twitterapi.io、api.twitterapi.io、x-api-key、login_cookies、または OAuth を使わない X API に関するあらゆる操作

基本情報

ベース URL	https://api.twitterapi.io
プレフィックス	ほとんどのエンドポイントは /twitter/...、リアルタイム監視／Webhook は /oapi/x_user_stream/... および /oapi/tweet_filter/...、残高は /oapi/my/info
認証ヘッダー	x-api-key: YOUR_KEY
ダッシュボード	https://twitterapi.io/dashboard
ドキュメント	https://docs.twitterapi.io
レート制限	クライアントあたり約 200 req/s
料金	ツイート 1,000 件あたり約 $0.15、プロフィール 1,000 件あたり約 $0.18、最低 $0.00015

⚠️ 注意が必要な 2 つのルール

ルール 1 — パラメーター名はエンドポイントごとに異なります

すべてに適用できる snake_case または camelCase のルールはありません。例（すべて正しい形式です）。

• /twitter/user/followers?userName=（camel）
• /twitter/user/verifiedFollowers?user_id=（snake）
• /twitter/user/articles?username=（すべて小文字）
• /twitter/tweets?tweet_ids=（snake）、ただし /twitter/tweet/replies?tweetId=（camel）
• /twitter/list/tweets_timeline?listId=（camel）、ただし /twitter/list/members?list_id=（snake）

references/endpoints.md に記載されたパラメーター名を正確にコピーしてください。形式を統一しないでください。

ルール 2 — 書き込みには、2 つではなく 3 つの項目がリクエストボディに必要です

書き込みエンドポイントには、次の項目がすべて必要です。

1. login_cookies（login_cookie ではなく複数形）— /twitter/user_login_v2 から取得した、JSON の base64 エンコード値
2. proxy（HTTP/SOCKS プロキシ URL。ダッシュボードで設定してください）
3. 操作固有のフィールド。ほとんどの場合、snake_case（tweet_id、user_id）です

フィールド名で間違いやすい点も確認してください。

• create_tweet_v2 のテキストフィールドは tweet_text（text ではありません）。返信フィールドは reply_to_tweet_id（in_reply_to_tweet_id ではありません）
• update_profile_v2 では description（bio ではありません）を使用します
• bookmarks_v2 では count（pageSize ではありません）を使用します
• send_dm_to_user では user_id と text を使用します。media_id（単数形）は任意です
• 監視対象の追加には x_user_name、削除には id_for_user を使用します（エンドポイントごとにフィールドが異なります）

リクエストボディの完全な形式については、references/write-operations.md を参照してください。

ルール 3 — レスポンスの形式はエンドポイントごとに異なります

• data でラップされる形式：user/info、user_about、last_tweets、tweet_timeline、trends、check_follow_relationship → r["data"]["..."]
• エンベロープ付きのフラット形式：followers、followings、replies、mentions、community/tweets → r["followers"]、r["tweets"] など
• エンベロープなしのフラット形式：advanced_search、thread_context、user/search、get_tweets_from_all_community → {tweets[], has_next_page, next_cursor} のみ
• 名前付きのトップレベルフィールド：community/info → r["community_info"]、batch_info_by_ids → r["users"]
• oapi/my/info → {recharge_credits, total_bonus_credits}（status のラッパーなし）

安全性を高めるには、次のように防御的なアクセスを使用してください。r.get("tweets", r.get("data", {}).get("tweets", []))。

セキュリティ

API キーをハードコードしないでください。環境変数 TWITTERAPI_IO_KEY から読み取ります。設定されていない場合は、ユーザーに確認してください。

最小限の動作例

curl -s "https://api.twitterapi.io/twitter/user/info?userName=elonmusk" \
  -H "x-api-key: $TWITTERAPI_IO_KEY"

import os, requests

BASE = "https://api.twitterapi.io"
HEADERS = {"x-api-key": os.environ["TWITTERAPI_IO_KEY"]}

r = requests.get(f"{BASE}/twitter/user/info",
                 headers=HEADERS,
                 params={"userName": "elonmusk"},
                 timeout=30)
r.raise_for_status()
d = r.json()["data"]
print(f"{d['userName']} — {d['followers']:,} followers")

エンドポイントのクイックリファレンス

読み取り（API キーのみ）。パラメーター名は正確に、表示どおりにコピーしてください。

機能	メソッド	パスと主要なパラメーター
スクリーンネームでユーザーを取得	GET	/twitter/user/info?userName=
プロフィール詳細	GET	/twitter/user_about?userName=
IDを指定して複数のユーザーを取得	GET	/twitter/user/batch_info_by_ids?userIds=
ユーザーを検索	GET	/twitter/user/search?query= (keywordではありません)
最近のツイート	GET	/twitter/user/last_tweets?userName=（またはuserId=）
IDでタイムラインを取得	GET	/twitter/user/tweet_timeline?userId=
ユーザーの記事	GET	/twitter/user/articles?username= (すべて小文字)
ユーザーへのメンション	GET	/twitter/user/mentions?userName=
フォロワー	GET	/twitter/user/followers?userName=&pageSize=200
認証済みフォロワー	GET	/twitter/user/verifiedFollowers?user_id= (スネークケース)
フォロー中のユーザー	GET	/twitter/user/followings?userName=
フォロー関係を確認	GET	/twitter/user/check_follow_relationship?source_user_name=&target_user_name=
IDでツイートを取得	GET	/twitter/tweets?tweet_ids= (スネークケース)
ツイートへの返信	GET	/twitter/tweet/replies?tweetId=
返信（並べ替え可能）	GET	/twitter/tweet/replies/v2?tweetId=&queryType=Latest
引用ツイート	GET	/twitter/tweet/quotes?tweetId=
リツイートしたユーザー	GET	/twitter/tweet/retweeters?tweetId=
スレッドのコンテキスト	GET	/twitter/tweet/thread_context?tweetId=
記事の内容	GET	/twitter/article?tweet_id= (スネークケース)
高度な検索	GET	/twitter/tweet/advanced_search?query=
高度な一括検索	POST	/twitter/tweet/bulk_advanced_search 本文 {queries:[{query,queryType?,cursor?}]}
トレンド	GET	/twitter/trends?woeid=1&count=30
スペースの詳細	GET	/twitter/spaces/detail?space_id= (スネークケース)
リストのツイート（フィルター付き）	GET	/twitter/list/tweets?listId=
リストのtweets_timeline	GET	/twitter/list/tweets_timeline?listId=
リストのメンバー／フォロワー	GET	/twitter/list/{members,followers}?list_id= (スネークケース)
コミュニティ情報	GET	/twitter/community/info?community_id=
コミュニティのツイート／メンバー／モデレーター	GET	/twitter/community/{tweets,members,moderators}?community_id=
全コミュニティのファイアホース	GET	/twitter/community/get_tweets_from_all_community?query=（必須！）
アカウント残高	GET	/oapi/my/info

リアルタイム監視（/oapi/x_user_stream/*）。エンドポイントによってフィールド名が異なります！

機能	メソッド	パスと本文
監視対象を追加	POST	/oapi/x_user_stream/add_user_to_monitor_tweet 本文 {x_user_name} ← user_idではありません
監視対象を一覧表示	GET	/oapi/x_user_stream/get_user_to_monitor_tweet（およびquery_type 0/1/2）
監視対象を削除	POST	/oapi/x_user_stream/remove_user_to_monitor_tweet 本文 {id_for_user} ← 追加時とはフィールドが異なります

Webhookのフィルタールール（/oapi/tweet_filter/*）：

機能	メソッド	パスと本文
ルールを追加	POST	/oapi/tweet_filter/add_rule 本文 {tag, value, interval_seconds?=60}（範囲：0.05～86400）
ルールを一覧表示	GET	/oapi/tweet_filter/get_rules
ルールを更新	POST	/oapi/tweet_filter/update_rule 本文 {rule_id, tag, value, interval_seconds?, is_effect?}
ルールを削除	DELETE	/oapi/tweet_filter/delete_rule 本文 {rule_id} (クエリではなくJSON本文)

書き込み操作 — 本文にlogin_cookiesとproxyが必要です。login_cookiesは/twitter/user_login_v2から取得するbase64(json(cookie_dict))です。

機能	メソッド	パス	主な本文フィールド（login_cookies と proxy 以外）
ログイン → Cookie	POST	/twitter/user_login_v2	{user_name, email, password, totp_secret?, proxy}
ツイートを作成	POST	/twitter/create_tweet_v2	tweet_text（必須）；任意で reply_to_tweet_id、quote_tweet_id、community_id、media_ids[]、schedule_for
削除	POST	/twitter/delete_tweet_v2	tweet_id
いいね／いいねを取り消す	POST	/twitter/{like,unlike}_tweet_v2	tweet_id
リツイート	POST	/twitter/retweet_tweet_v2	tweet_id
ブックマーク／ブックマークを解除	POST	/twitter/{bookmark,unbookmark}_tweet_v2	tweet_id
ブックマーク一覧	POST	/twitter/bookmarks_v2	任意の count（デフォルトは20、pageSize ではありません）、cursor
フォロー／フォロー解除	POST	/twitter/{follow,unfollow}_user_v2	user_id
DM を送信	POST	/twitter/send_dm_to_user	user_id、text、任意の media_id（単数形）、reply_to_message_id
報告	POST	/twitter/report_v2	（tweet_id または user_id）、reason（列挙型。endpoints.md を参照）
メディアをアップロード	POST	/twitter/upload_media_v2	multipart：file、任意の media_category、is_long_video
プロフィールを更新	PATCH	/twitter/update_profile_v2	JSON：name、description（bio ではありません！）、location、url のいずれか1つ以上
アバター／バナーを更新	PATCH	/twitter/update_{avatar,banner}_v2	multipart：file
コミュニティを作成	POST	/twitter/create_community_v2	name、description（両方必須）
コミュニティに参加／退出	POST	/twitter/{join,leave}_community_v2	community_id
コミュニティを削除	POST	/twitter/delete_community_v2	community_id、community_name（両方必須）
リストメンバーを追加	POST	/twitter/list/add_member_v2	list_id、user_id

正確なパラメーター一覧、レスポンス形式、エッジケースについては、references/endpoints.md を参照してください。

繰り返し使われるパターン

カーソルによるページネーション — has_next_page を使う

def iter_followers(user_name):
    cursor = ""
    while True:
        r = requests.get(f"{BASE}/twitter/user/followers",
                         headers=HEADERS,
                         params={"userName": user_name, "cursor": cursor, "pageSize": 200},
                         timeout=30).json()
        yield from r.get("followers", [])
        if not r.get("has_next_page"):
            break
        cursor = r.get("next_cursor") or ""

エラー処理

# FastAPI-style 4xx/5xx
{ "detail": "tweet_id is required" }
{ "detail": [{"type":"missing","loc":["body","file"]}] }  # 422 on multipart

# Semantic 200 errors
{ "status": "error", "msg": "No active monitoring subscription" }

• 401 → x-api-key が無効、または login_cookies の有効期限切れ
• 402 → ダッシュボードで残高をチャージ
• 429 → レート制限に達しています。指数バックオフを行う
• 400/422 → detail を確認してください。不足または誤っているフィールドが示されています
• 500 → 一時的なエラーです。ジッターを加えて再試行してください。繰り返し発生する場合は、パラメーター名が誤っています

コストへの配慮

長時間のページネーションが発生する可能性のあるループ（大規模アカウントのフォロワー取得、数年分の高度な検索など）の前に、事前にコストを見積もり、数ドルを超える可能性がある場合はユーザーに確認してください。1億人のフォロワーを取得すると、1,000件あたり0.15ドルの場合、15,000ドル以上かかります。

アンチパターン

• パラメーターの大文字・小文字のルールが共通だと思い込まないでください — endpoints.md を確認してください
• login_cookie（単数形）を使わないでください — login_cookies（複数形）です
• 書き込みリクエストの本文に proxy を忘れずに指定してください — すべての書き込みで必須です
• create_tweet_v2 に text を送信しないでください — tweet_text を使ってください
• update_profile_v2 で bio を使わないでください — description を使ってください
• create_tweet_v2 で in_reply_to_tweet_id を使わないでください — reply_to_tweet_id です
• upload_media_v2／update_avatar_v2／update_banner_v2 に JSON を送信しないでください — multipart/form-data を使います
• bookmarks_v2 で pageSize を使わないでください — count です
• モニタリングの追加には user_id を送信しないでください — x_user_name を使います。削除では id_for_user を使います
• API キー、login_cookies、プロキシ、totp_secret をログに記録したり、コミットしたりしないでください
• developer.twitter.com／公式 X OAuth を使わないでください — この API がそれらに置き換わります
• 「リアルタイム」取得のために /user/last_tweets をポーリングしないでください — /oapi/tweet_filter/add_rule と Webhook を使ってください