twitter

Twitter / X（腳本模式）

唯讀存取 twitterapi.io 端點。13 個函式涵蓋推文、使用者、追蹤者、回覆、討論串、引用、文章和趨勢。

所有請求透過 sc-proxy 經由 core.http_client.proxied_get 發送。TWITTER_API_KEY 環境變數由伺服器端自動注入，代理機器上無需本機金鑰。

腳本使用方式

標準呼叫模式：

python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/twitter")
from exports import twitter_user_info, twitter_user_tweets

profile = twitter_user_info(username="vitalikbuterin")
print(json.dumps(profile, indent=2))

recent = twitter_user_tweets(username="vitalikbuterin")
print(f"取得 {len(recent.get('tweets', []))} 則推文")
EOF

從網址提取推文 ID：任何 x.com/{user}/status/{id} 或 twitter.com/{user}/status/{id} 網址的最後一段路徑即為推文 ID。請以字串形式傳入（Python int 在長 ID 上會失去精度）。

函式參考（簽章）

所有 13 個函式位於 exports.py。回傳值為直接來自 twitterapi.io 的字典 — 鍵值因端點而異，請先檢查一次再編寫腳本。

推文端點

函式	說明
twitter_search_tweets(query, cursor=None)	進階搜尋。運算子：from:user、to:user、#tag、$cashtag、lang:en、has:media、has:links、is:reply、min_faves:N、since:YYYY-MM-DD、until:YYYY-MM-DD。
twitter_get_tweets(tweet_ids)	依 ID 擷取一則或多則推文。tweet_ids = 字串列表（也接受逗號分隔字串）。
twitter_tweet_replies(tweet_id, cursor=None)	推文的回覆。
twitter_tweet_retweeters(tweet_id, cursor=None)	轉推的使用者。
twitter_tweet_thread_context(tweet_id)	完整討論串上下文（父推文 + 直接回覆）。
twitter_tweet_quote(tweet_id, cursor=None)	引用推文。
twitter_get_article(tweet_id)	長篇 X 文章內容。
twitter_get_trends(woeid=None, country=None, category=None, limit=None)	熱門話題；所有篩選條件皆為選填。

使用者端點

函式	說明
twitter_user_info(username)	個人資料：簡介、追蹤者/追蹤中數量、推文數、已驗證。
twitter_user_tweets(username, cursor=None)	使用者的近期推文。
twitter_user_followers(username, cursor=None)	追蹤者列表。
twitter_user_followings(username, cursor=None)	追蹤中的帳號。
twitter_search_users(query, cursor=None)	依名稱/關鍵字搜尋使用者。

username 為不含 @ 的使用者代稱（例如 "elonmusk"，而非 "@elonmusk"）。
分頁：當回應包含 next_cursor 時，在下一次呼叫中將其作為 cursor 傳入。

何時使用此技能

• 任何 x.com/... 或 twitter.com/... 網址 → 從這裡開始，不要用 web_fetch（Twitter 封鎖爬蟲）。
• 單則推文詳細資訊 → twitter_get_tweets([tweet_id])。
• "@user 最近發了什麼？" → twitter_user_tweets。
• KOL 發現 / 代碼提及 → twitter_search_tweets("$SOL min_faves:50")。
• 熱門話題 → twitter_get_trends。

計費與成本控制（大量/排程使用前請閱讀）

twitterapi.io 按實際回傳的項目數量計費，而非按請求次數，也非按您要求的任何 "max_results"。sc-proxy 費用 = 回傳項目數 × 單位（推文 45 / 個人資料 54 / 追蹤者 45 點；10 萬點 = 1 美元；上游 3 倍）。每次請求至少 1 個項目。

last_tweets / user_tweets 陷阱： 上游 /twitter/user/last_tweets 端點沒有頁面大小參數 — 它總是回傳最多 每頁 20 則推文。沒有 max_results / pageSize 控制桿，且 twitter_user_tweets() 不接受此參數。因此「我只需要 5 則」仍會擷取並計費約 20 則。在客戶端對結果進行切片並不會省錢 — 費用已在代理端根據上游回應計算。

⭐ 輪詢「帳號 X 的新推文」→ 使用搜尋，而非 last_tweets

這是最常見且最大的浪費。twitter_user_tweets()（上游 last_tweets）沒有頁面大小參數，每次呼叫總是計費一整頁約 20 則推文，即使沒有新貼文。官方 twitterapi.io 指南建議改用 advanced_search 端點，我們的技能已將其公開為 twitter_search_tweets()：

# 便宜的輪詢模式 — 僅對時間範圍內實際存在的推文計費。
# 當沒有新推文時，該呼叫計費為 1 個項目（而非 20 個）。
import time
since = int(last_check_unix)
until = int(time.time())
q = f"from:{handle} include:nativeretweets since_time:{since} until_time:{until}"
res = twitter_search_tweets(q)   # queryType 預設為 Latest

官方定價（上游；我們的代理計費 3 倍）：

• 找到推文 → 每則回傳推文 $0.00015
• 未找到推文 → 整次呼叫 $0.00015（相較於 last_tweets 約 20 倍）

在我們的計費中，每次呼叫的成本差異明顯：

• last_tweets → 每次呼叫約 $0.009（每次 20 則推文）
• advanced_search 空時間範圍 → 每次呼叫約 $0.00045（1 個項目）— 便宜約 20 倍

頻率 vs 每月成本（單一帳號，上游）：每小時 $0.11 · 每 30 分鐘 $0.22 · 每 15 分鐘 $0.43 · 每 5 分鐘 $1.30 · 每 1 分鐘 $6.48。

其他成本控制手段

• 使用 get_tweets([ids]) 當已知 ID 時 — 僅為這些確切推文付費，而非 20 項的頁面。
• 追蹤者/追蹤中 按回傳的個人資料計費（預設頁面 200 → 計費 200）。僅在必要時才進行分頁。若僅需 ID 的圖形工作，請使用大量追蹤者 ID 端點（輕量）。
• 縮小搜尋查詢範圍（min_faves、since_time/until_time、lang），以減少所需頁數。

注意：twitterapi.io 也提供受管串流/webhook 產品。我們未訂閱此服務 — 請勿使用 /oapi/x_user_stream/* 或 /oapi/tweet_filter/* 端點。對於任何帳號監控需求，上述 advanced_search 輪詢模式是此處唯一且正確的方法。

錯誤處理

• 402 Credits is not enough → 上游代理點數耗盡；告知使用者補充點數。請勿重試。
• 429 → 達到速率限制；告知使用者，請勿自動重試。
• 404 user not found → 建議檢查使用者代稱拼寫。

版本政策（嚴格規則）

此技能為腳本模式（delivery: script）。它不會註冊執行時期工具 — 代理必須 read_file SKILL.md 並透過 bash + python3 呼叫函式。舊版 tools.py / __init__.py 檔案保留以向後相容，但不再是建議的進入點。

版本號規則：

• 任何簽章變更、環境變數變更或 sc-proxy 合約變更 → MAJOR
• 新增函式、回應結構說明更清楚 → MINOR
• 錯誤修正或僅文件變更 → PATCH