# Twitter API：以 Markdown 讀取公開 X 貼文

讀取公開 X 內容的 Twitter API，並非 X 官方服務。傳入貼文連結，即可取得 Markdown 或 JSON 格式的串文。免費提供 50 點點數，用完後按貼文計費。

Page: https://twitterviewer.app/zh-hant/twitter-api

以簡潔的 Markdown 或 JSON 讀取公開 X 貼文、完整串文與個人檔案。這是讀取公開內容的獨立 API，無須 X 開發者帳號，也無每月最低消費。

TwitterViewer 是獨立服務，並非 X 官方 API，也與 X Corp. 無關。僅能讀取公開貼文，無法發文、按讚、追蹤、傳送訊息或讀取私人帳號。

## Endpoints

| Method | Path | What it does |
| --- | --- | --- |
| POST | /api/v1/convert | 將單篇貼文、完整串文或帳號近期貼文轉為 Markdown、Obsidian、純文字、JSON 或 PDF |
| GET | /api/v1/search | 使用 X 搜尋運算子搜尋公開貼文（Pro 與 Business） |
| GET | /api/v1/replies | 取得貼文下的公開回覆 |
| GET | /api/v1/trends | 查看特定地區的熱門趨勢 |
| GET | /{handle}/status/{id} | 替換 URL：沿用 X 連結的路徑，附上金鑰即可取得 Markdown |
| GET | /api/v1/credits | 依來源查看餘額：方案點數與加購點數 |
| MCP | /mcp | 提供 Claude、Cursor 與 Codex 使用的 convert_x_url、search_x_posts、get_x_replies、get_x_trends、get_credits |

## Example

```bash
curl https://twitterviewer.app/api/v1/convert \
  -H "Authorization: Bearer $TWITTERVIEWER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://x.com/username/status/1234567890123456789",
    "scope": "thread",
    "format": "markdown"
  }'

# or just swap the domain
curl -H "Authorization: Bearer $TWITTERVIEWER_API_KEY" \
  https://twitterviewer.app/username/status/1234567890123456789
```

```json
{
  "kind": "thread",
  "title": "How we shipped the new release:",
  "sourceUrl": "https://x.com/username/status/1234567890123456789",
  "author": { "handle": "username", "name": "Example", "followers": 1204 },
  "postsReturned": 31,
  "wordCount": 2214,
  "markdown": "# How we shipped the new release…\n\nThread by @username…",
  "text": "How we shipped the new release…",
  "posts": [ { "id": "1234567890123456789", "text": "…" }, … ],
  "replies": [],
  "credits": { "charged": 31, "remaining": 2969 }
}
```

## Pricing

註冊即送 50 點免費點數 · 用完後每篇貼文 $0.002 起.

- Requests per minute: Free 10, Plus 30, Pro 60, Business 300. API keys per account: Free 1, Plus 2, Pro 5, Business 20. Monthly credits: Plus 3,000, Pro 8,000, Business 25,000 (yearly plans get 12 months of credits at once); every account also gets 50 credits once at sign-up. PDF output (format=pdf) is part of Pro and Business.
- Credit packs: 1,000 credits for $5, 6,000 credits for $20, 20,000 credits for $50, one-time, never expire.

本頁介紹的 Twitter API 讓你透過程式讀取 X 公開內容，並按貼文數量付費。只要將貼文、討論串或個人檔案連結傳送至同一個端點，就能取得整理好的 Markdown、Obsidian 筆記、純文字、JSON 或 PDF。它專為 AI 代理程式、研究腳本，以及需要將討論串文字交給模型或筆記應用程式使用的開發者而設計，不必先申請 X 開發者帳號。

這是一項獨立服務，並非 X 官方 API，TwitterViewer 也與 X Corp. 沒有關聯。它只能讀取公開貼文，無法發文、按讚、追蹤、傳送訊息或存取私人帳號。本指南將說明 Twitter API 的功能、與官方 X API 的差異、第一次呼叫的方式、點數計費規則、使用限制，以及 MCP 伺服器、命令列工具和代理程式技能各自的用途。

## 本頁介紹的 Twitter API 是什麼？

這裡的 Twitter API 是唯讀 HTTP API，用來讀取 X（前身為 Twitter）上的公開貼文。建立 API 金鑰後，將它作為 Bearer 權杖傳送，即可呼叫 `https://twitterviewer.app/api/v1` 下的端點。Twitter API 的核心端點是 `convert`：提供一個 X 連結，就能取得該則貼文、同一作者的完整討論串，或該個人檔案的近期貼文。

回傳內容的格式方便後續使用。Markdown 版本包含標題、作者、每則貼文的日期、內文、圖片連結，以及作者分享的連結。JSON 版本則將相同內容整理成結構化資料：每則貼文各有一個物件，包含識別碼、內文、日期、媒體、統計數據和引用貼文。兩種版本會在同一次回應中提供，讓腳本保留資料結構，也讓代理程式直接閱讀文字。

每次呼叫 Twitter API 都以點數計費，每回傳一則貼文扣除 1 點。作者資料免費，呼叫失敗也不收費。免費帳號可一次獲得 50 點；付費方案每月提供 3,000、8,000 或 25,000 點，另購的點數包則永久有效。完整參數清單請見 [API 文件](https://twitterviewer.app/docs/api)。

## 與官方 X API 有什麼不同？

官方 X API 是由 X 經營的另一項產品，需要開發者帳號、應用程式和方案，除了讀取內容，也涵蓋發文、帳號與權限操作。如果你需要發布貼文或代表使用者執行操作，官方 API 才是合適的工具，本頁介紹的服務無法取代這些功能。

這項 Twitter API 專注於一件事：讀取任何人都能在 X 上看到的內容，並整理成文件回傳。你不需要開發者帳號，不必經過應用程式審查，也沒有每月最低消費，因為費用只按點數計算。使用核心端點時，不必提供 X 密碼、Cookie 或權杖。搜尋是例外，因為 X 只向已登入的使用者提供搜尋功能；此端點僅適用於 Pro 和 Business，並使用你自行連接的 X 帳號。

你可以把 Twitter API 想成讀取內容的一層介面。當你的目標是「把這個討論串存進筆記」、「把這些貼文交給模型」或「查看大家的回覆」時，你需要的是內容。[X 轉 Markdown](https://twitterviewer.app/zh-hant/x-to-markdown) 頁面讓你在瀏覽器中手動完成這件事；Twitter API 則讓你透過程式完成。

## Twitter API 可以讀取哪些內容？

共有六個端點提供讀取功能，而且全部都是唯讀：

- **轉換**：將貼文、討論串或個人檔案轉為 Markdown、Obsidian、純文字、JSON 或 PDF。使用 `scope` 選擇單則貼文、作者的討論串，或討論串加上第一頁回覆。
- **搜尋**：執行 `from:`、`since:`、`min_faves:` 等 X 搜尋運算子，並回傳公開貼文。搜尋功能適用於 Pro 和 Business，且需要連接 X 帳號。運算子與[推特進階搜尋](https://twitterviewer.app/zh-hant/twitter-advanced-search)相同，詳細說明請見 [X 搜尋運算子](https://twitterviewer.app/zh-hant/blog/x-advanced-search-operators)指南。
- **回覆**：回傳貼文下方的公開回覆，也就是[推特回覆檢視器](https://twitterviewer.app/zh-hant/twitter-reply-viewer)在瀏覽器中顯示的內容。
- **趨勢**：列出指定地區的熱門趨勢，可選擇全球、美國、英國、日本、沙烏地阿拉伯、印度、巴西或德國等地區。
- **點數**：依來源列出點數餘額，查詢免費。
- **替換網址**：將貼文網址中的 `x.com` 換成 `twitterviewer.app`，並在請求中附上金鑰，即可取得 Markdown。

Twitter API 無法讀取的內容也很明確。私人帳號、受保護貼文、私人訊息、已刪除貼文，以及遭停權帳號都不屬於公開內容，因此無法取得。其他人的按讚紀錄與書籤也無法取得。

## 快速開始：三步驟完成第一次 Twitter API 呼叫

1. 建立免費帳號，開啟 API 頁面並建立金鑰。金鑰以 `tv_live_` 開頭，而且只會顯示一次，請將它存入環境變數，例如 `TWITTERVIEWER_API_KEY`。
2. 將連結傳送至 `convert`。以下範例會要求以 Markdown 格式回傳討論串：

```bash
curl -X POST https://twitterviewer.app/api/v1/convert \
  -H "Authorization: Bearer $TWITTERVIEWER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://x.com/username/status/1234567890123456789", "scope": "thread", "format": "markdown" }'
```

3. 查看回應標頭。`x-credits-charged` 表示這次呼叫扣除的點數，`x-credits-remaining` 是剩餘點數，`x-ratelimit-remaining` 則是本分鐘內還能呼叫的次數。

如果只需要文件，請加上 `Accept: text/markdown` 標頭，回應主體就會直接是 Markdown，可直接存成檔案。回傳的貼文數量會放在 `x-posts-returned` 標頭中。

> **Tip: 替換網域**
> 將貼文網址中的 `x.com` 換成 `twitterviewer.app`，並將金鑰作為 Bearer 權杖傳送，該 URL 就會回傳 Markdown。在瀏覽器中開啟時，仍會顯示一般檢視頁面，因此同一個連結可供人閱讀，也可供代理程式使用。

## Twitter API 的 convert 端點實際用法

`convert` 有四類重要選項。`scope` 決定取得的內容範圍：`post` 只回傳連結指向的貼文，`thread` 依序回傳作者串接的貼文，`conversation` 則加上第一頁回覆。`format` 決定輸出格式：預設為 `json`，會回傳完整內容；`markdown` 和 `obsidian` 會產生對應格式的文件，`text` 會移除格式，`pdf` 則回傳檔案。

`stats` 控制按讚、轉發與回覆數的顯示方式：`all` 會在每則貼文中顯示，`root` 只在第一則顯示，`off` 則全部省略，讓交給模型的文字更精簡。對個人檔案連結而言，`max` 可設定回傳的近期貼文數量，範圍為 1 至 200；`replies` 和 `reposts` 則決定是否包含回覆與轉發。

JSON 回應每次都使用固定欄位名稱：`kind`、`title`、`sourceUrl`、`author`、`markdown`、`text`、`posts`、`replies`、`postsReturned`、`wordCount`，以及包含本次扣點與剩餘點數的 `credits` 物件。標題取自第一則貼文的開頭，並在完整詞語的邊界截斷，方便直接用作檔名或筆記標題。

有幾個細節需要留意。引用貼文會額外計為一則貼文。同一把金鑰在 10 分鐘內，以相同參數再次請求同一個連結，不會重複扣點。資料也會短暫快取：貼文約為兩分鐘，個人檔案約為十分鐘，因此在內容剛編輯完時呼叫，可能仍會看到編輯前的文字。

## 適合 AI 代理程式與研究使用的 Twitter 爬蟲 API

需要將貼文當作資料使用的人，常會搜尋 Twitter 爬蟲。自行執行爬蟲時，必須處理速率限制與版面變動，而且 X 一旦修改頁面，爬蟲就可能失效。這項 Twitter API 將這些工作交由服務處理：只需呼叫一個端點，就能取得格式穩定的公開貼文。

最常見的用途很簡單：

- **將討論串交給模型。** 把連結轉為 Markdown，再貼入 ChatGPT、Claude 或 Gemini 的上下文。Markdown 能保留標題與連結，使用的 token 比 HTML 少，讀起來也接近原文。
- **建立筆記資料庫。** `obsidian` 格式會加入包含作者、日期與來源的 YAML 前置資料，讓討論串成為 Obsidian 或 Notion 中的一篇筆記。
- **追蹤主題。** 使用運算子搜尋，轉換最相關的結果，再儲存 Markdown。你可以搭配自己的工具設定排程。
- **研究回覆。** 擷取貼文下方的回覆，找出反覆出現的問題或反對意見。
- **將討論串存成 PDF。** Pro 和 Business 可使用 `format=pdf` 取得 A4 或 Letter 尺寸的 PDF，包含圖片與貼文連結，結果與瀏覽器中的 [Twitter 討論串轉 PDF](https://twitterviewer.app/zh-hant/twitter-thread-to-pdf)相同。

Twitter API 以公開範圍為界，只回傳訪客能看到的內容。只有搜尋與額外頁面的回覆會使用已登入的 X 帳號，而且使用的是你自行連接的帳號。若要手動閱讀長討論串，可使用瀏覽器版的 [Twitter 討論串閱讀器](https://twitterviewer.app/zh-hant/twitter-thread-reader)。

## Twitter API 點數與定價

費用只按點數計算。不論使用哪個端點，每回傳一則貼文扣除 1 點。包含 31 則貼文的討論串需 31 點，單則貼文需 1 點，一頁 20 則回覆需 20 點，而一次趨勢查詢需 1 點。作者資料免費，呼叫失敗或未回傳內容時也不扣點。

| 來源 | 數量 | 備註 |
| --- | --- | --- |
| 註冊 | 一次獲得 50 點 | 永久有效 |
| Plus | 每月 3,000 點 | 每月重設 |
| Pro | 每月 8,000 點 | 每月重設，包含 PDF 與搜尋功能 |
| Business | 每月 25,000 點 | 每月重設，包含 PDF 與搜尋功能 |
| 點數包 | $5 購買 1,000 點、$20 購買 6,000 點、$50 購買 20,000 點 | 單次購買，永久有效 |

系統會優先使用最早到期的點數，因此每月方案點數會先於另購點數扣除。最低單價約為 Business 方案的每則貼文 $0.002，最小點數包則為每則貼文 $0.005。方案與價格請見[定價](https://twitterviewer.app/zh-hant/pricing)頁面。

如果呼叫所需的點數超過餘額，餘額為零時會以 `402` 拒絕請求；若仍有點數但不足以取得全部結果，則只回傳餘額可支付的貼文數量。餘額端點會顯示剩餘點數，以及每月方案點數的重設時間。

## Twitter API 速率限制、錯誤與快取

Twitter API 依帳號限制每分鐘請求次數：免費帳號為 10 次、Plus 為 30 次、Pro 為 60 次、Business 為 300 次。超過限制時，API 會回傳 `429`，並附上 `retryAfterSec` 值與 Retry-After 標頭。免費帳號可持有 1 把金鑰，Plus 為 2 把、Pro 為 5 把、Business 為 20 把。

所有錯誤都採用相同格式：一個 `error` 物件，包含 `code`、`message`，有時也包含 `details`。未提供金鑰或金鑰錯誤時，會回傳 `401`，且不會擷取內容。點數餘額不足時，會回傳 `402`，註明原因 `INSUFFICIENT_CREDITS` 與所需點數。受保護帳號會回傳 `403`、已刪除貼文回傳 `404`、遭停權帳號回傳 `410`；資料來源發生錯誤時則回傳 `502`，不扣點，可重試。完整清單請見 [API 文件](https://twitterviewer.app/docs/api)。

回應內容取決於你的金鑰，因此不會存入共用快取。服務本身會短暫快取 X 資料，讓重複讀取更快速，也讓結果保持一致。

## MCP 伺服器、CLI 與代理程式技能

Twitter API 是四種存取方式之一，全部共用同一份點數餘額。

- **MCP 伺服器。** 位於 `https://twitterviewer.app/mcp` 的遠端伺服器，讓 Claude、Cursor 和 Codex 直接讀取 X。它提供五項唯讀工具，設定方式請見 [Twitter MCP 伺服器](https://twitterviewer.app/zh-hant/twitter-mcp-server)頁面。
- **命令列工具。** `npx twitterviewer <link>` 可從終端機轉換連結，並將結果儲存為檔案。`twitterviewer login` 會透過瀏覽器登入，`twitterviewer credits` 則會印出點數餘額。
- **代理程式技能。** 位於 `/.well-known/agent-skills/twitterviewer/SKILL.md` 的技能檔，會告訴代理程式遇到 X 連結時該如何處理。
- **替換網域。** 最簡單的方式：變更連結的網域，並在請求中附上金鑰。

對代理程式來說，通常優先選擇替換網域或 MCP 工具，因為這兩種方式都不必寫程式。若要整合進自動化流程，則直接使用 Twitter API。

## 作為 Twitter API 替代方案：適合哪些情況？

如果你的工作是讀取公開內容，又不想管理開發者帳號，可以考慮將這項服務作為 Twitter API 的替代方案。它適合筆記工具、研究、整理討論串摘要、將內容交給語言模型，以及封存貼文。若需要發文、代表使用者執行操作、讀取私人內容，或即時串流取得每則新貼文，就比較不適合。這些工作需要官方 API 與你自己的授權。

使用前，也應將幾項 Twitter API 限制納入規劃。資料僅限公開內容，且有短暫快取。搜尋需要 Pro 或 Business 方案，以及已連接的 X 帳號，因為 X 只向已登入的使用者顯示搜尋結果。部分 X 功能尚未支援轉換，例如 X 文章、投票與連結卡片；遇到文章時，會回傳分享該文章的貼文。TwitterViewer 是獨立服務，X 與 Twitter 的商標均屬其各自擁有者所有。

如果想先試用 Twitter API，請建立免費帳號，用 50 點轉換幾個討論串，看看輸出結果。若只是偶爾需要轉換，[X 轉 Markdown](https://twitterviewer.app/zh-hant/x-to-markdown) 頁面不必寫程式；[推特個人檔案檢視器](https://twitterviewer.app/zh-hant/twitter-profile-viewer)則能讓你在轉換前先查看帳號內容。

## Twitter API 常見問題

### TwitterViewer 的 Twitter API 是什麼？

這是一項獨立的唯讀 API，用來讀取 X 公開內容。傳送貼文、討論串或個人檔案連結後，即可取得 Markdown、Obsidian、純文字、JSON 或 PDF。它以點數計費，每回傳一則貼文扣除 1 點，並非 X 官方 API。

### 這是官方 X API 嗎？

不是。官方 X API 是 X 提供的另一項產品，需要開發者帳號與方案。這項 API 只能讀取公開貼文，與 X Corp. 沒有關聯，無法發文、按讚、追蹤或傳送訊息。

### 我需要 X 開發者帳號嗎？

不需要。你只需要 TwitterViewer 帳號與 API 金鑰。核心端點不會要求你的 X 登入資料。搜尋是唯一的例外：X 只向已登入的使用者提供搜尋功能，因此這項功能適用於 Pro 和 Business，並使用你自行連接的 X 帳號。

### Twitter API 的費用是多少？

每 1 點可取得一則貼文。免費帳號可一次獲得 50 點，Plus 每月包含 3,000 點、Pro 為 8,000 點、Business 為 25,000 點。點數包價格為 $5 購買 1,000 點、$20 購買 6,000 點、$50 購買 20,000 點，且永久有效。最低單價約為每則貼文 $0.002。

### Twitter API 會回傳哪些格式？

預設為 `json`，也支援 `markdown`、`obsidian`、`text` 和 `pdf`。JSON 回應一定會同時包含產生的 Markdown 與結構化貼文資料。PDF 輸出適用於 Pro 和 Business，可選擇 A4 或 Letter 尺寸。

### 它可以當作 Twitter 爬蟲 API 使用嗎？

可以，適用於公開貼文。它以穩定的格式回傳任何人都能看到的貼文，讓你不必自行執行爬蟲。它不會回傳私人帳號、受保護貼文、私人訊息，或任何 X 不向未登入訪客公開的內容。

### 如何轉換完整討論串？

將討論串中任一則貼文的連結傳送至 `convert`，並將 `scope` 設為 `thread`，即可依序取得作者串接的貼文。使用 `scope=conversation` 可加上第一頁回覆，使用 `scope=post` 則只取得單則貼文。

### 點數用完會怎樣？

餘額為零時，呼叫會以 `402` 拒絕，且不會從 X 擷取任何內容。如果仍有點數，但不足以取得全部結果，則只回傳餘額可支付的貼文數量。你可以購買點數包，或等候每月方案點數重設。

### 有速率限制嗎？

有，依帳號計算每分鐘上限：免費帳號為 10 次、Plus 為 30 次、Pro 為 60 次、Business 為 300 次。每次回應都會在 `x-ratelimit-remaining` 標頭中顯示剩餘可呼叫次數。

### 可以搭配 Claude、Cursor 或 Codex 使用嗎？

可以。位於 `https://twitterviewer.app/mcp` 的遠端 MCP 伺服器支援 Claude、Claude Code、Cursor 和 Codex，點數計費方式相同。[Twitter MCP 伺服器](https://twitterviewer.app/zh-hant/twitter-mcp-server)頁面提供各用戶端的設定方式。