xAI 的 API 與 OpenAI SDK 相容，因此既有的程式多半只要換 base URL 與模型名稱就能跑。這降低了嘗試成本，卻也帶來一個陷阱：計費結構與 OpenAI 不同，照搬寫法容易在伺服器端工具上付出意料之外的費用。本篇按「先跑起來、再算清楚」的順序處理。
📖 認證與第一個請求
端點：https://api.x.ai/v1
金鑰：在 xAI console 的 API Keys 頁建立，存入環境變數 XAI_API_KEY 或 .env，以 Bearer token 送出。品牌雖已改名 SpaceXSI，這些識別字沒有跟著改。
最小的 curl 請求（Responses 端點）：
curl https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "grok-4.7", "input": "Explain what a race condition is."}'Python，直接用 OpenAI SDK 指向 xAI：
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1",
)
response = client.responses.create(
model="grok-4.7",
input="Explain what a race condition is.",
)
print(response.output_text)三種官方支援的接法：OpenAI SDK 換 base URL、xAI 自己的 xai-sdk、Vercel AI SDK 的 @ai-sdk/xai。官方文件沒有提到 Anthropic SDK 相容。
沒有免費額度。 官方快速開始頁寫明使用前需先為帳戶儲值，該頁也沒有列出速率限制（另有獨立的 rate-limits 頁）。
401 或 403 怎麼辦
依可能性排序：金鑰沒有正確載入（最常見——檢查 echo $XAI_API_KEY 是否真的有值）、帳戶未儲值、base URL 寫錯（漏掉 /v1）、金鑰權限不含該模型。
📖 伺服器端工具
這是 Grok API 相對其他家最值得用的部分：工具在伺服器端執行，你不必自己實作檢索或沙箱。
| 工具 | type | 用途 |
|---|---|---|
| 網路檢索 | web_search | 一般網路檢索 |
| X 檢索 | x_search | 檢索 X 的貼文、使用者與討論串 |
| 程式執行 | — | 沙箱內執行程式 |
| 函式呼叫 | — | 呼叫你自己的函式 |
| 遠端 MCP | — | 接外部 MCP 伺服器 |
| Collections 檢索 | — | 檢索自建文件集 |
啟用方式是在請求裡加 tools：
response = client.responses.create(
model="grok-4.7",
input=[{"role": "user", "content": "What are people saying about SpaceXSI on X?"}],
tools=[{"type": "x_search"}],
)x_search 的完整參數（帳號篩選、日期範圍、圖片與影片理解）見 核心功能。
使用量會回報在 usage.server_side_tool_usage_details。 建議第一天就把這個欄位記錄下來——它是你唯一能看到工具花了多少錢的地方。
📖 計費
官方價目（2026-10-22 查證）。文字模型以每百萬 token 計：
| 模型 | 脈絡 | 輸入 | 快取輸入 | 輸出 |
|---|---|---|---|---|
grok-4.7 | 500k | $2.00 | $0.50 | $6.00 |
grok-4.6 | 500k | $2.00 | $0.50 | $6.00 |
grok-4.5 | 500k | $2.00 | $0.30 | $6.00 |
grok-4.3 | 1M | $1.25 | $0.20 | $2.50 |
grok-4.20-0309-reasoning | 1M | $1.25 | $0.20 | $2.50 |
grok-4.20-0309-non-reasoning | 1M | $1.25 | $0.20 | $2.50 |
grok-4.20-multi-agent-0309 | 1M | $1.25 | $0.20 | $2.50 |
grok-build-0.1 | 256k | $1.00 | $0.20 | $2.00 |
修正項：批次 API 打八折（文字模型；生圖生片不打折）；優先處理為兩倍價；美國區域端點為 1.1 倍（目前僅 grok-4.7 與 grok-4.6）。
三個計費陷阱
一、200k token 的懸崖。 官方寫明：當請求的 prompt 達到 200k token，該請求的全部 token 都按高價階計費，不是只有超出的部分。grok-4.7 由 6 跳成 12，等於整筆翻倍。
這改變了架構決策。 一個 199k 的請求與一個 201k 的請求，價差不是 1%，而是接近 100%。若你的輸入長度會在 200k 附近浮動，應主動截斷或改用 1M 脈絡的
grok-4.3——後者更便宜且懸崖位置相同，但空間大得多。
二、x_search 按抓取量計費，不是按呼叫次數。 每 1,000 則貼文 10。一個寬鬆的查詢可能抓回大量貼文，而你無法事前精確預知數量。務必用 from_date／to_date 與 allowed_x_handles 收窄範圍，這兩個參數同時是品質工具與成本工具。
三、工具呼叫另計 token。 工具的呼叫費之外，檢索回來的內容會進入脈絡，產生輸入 token 費用；推理模型還會產生推理 token。「$5 / 1k 次」只是帳單的一部分。
粗估的方法
先跑 10 次代表性請求，記下 usage 的各欄位，算出單次平均成本再乘以預估流量。這比用紙上公式推估準得多，因為工具用量與推理長度都無法事前計算。
📖 其他值得知道的端點
官方文件另有這些章節，初期用不到但值得知道存在：
Collections — 自建文件集並讓模型檢索，相當於內建的 RAG。檢索費 $2.50 / 1k 次，比自己架向量庫省事。
批次 API — 非即時任務打八折。任何不需要立刻回答的工作都應該走這裡。
脈絡壓縮（context compaction） — 長對話的脈絡管理。
結構化輸出 — 強制 JSON schema，做資料抽取時必用。
deferred chat completions／WebSocket 模式／非同步 — 不同的回應取得方式。
mTLS、區域端點 — 企業合規需求。
🧠 重點整理
端點 https://api.x.ai/v1，金鑰環境變數 XAI_API_KEY——品牌改名後這些都沒變。
與 OpenAI SDK 相容，換 base URL 與模型名即可；另有 xai-sdk 與 Vercel AI SDK。
沒有免費額度，使用前須先儲值。
200k token 是計費懸崖：達到即整筆雙倍計價，不是只算超出部分。
輸入長度會在 200k 附近浮動時，改用 grok-4.3——1M 脈絡且更便宜。
x_search 按抓回的貼文數計費，一定要用日期與帳號參數收窄。
工具費之外還有 token 費，檢索回來的內容會進脈絡。
估成本要跑 10 次實測再乘流量，不要紙上推估。
非即時任務走批次 API，直接省兩成。
✍️ 動手做
建立成本直覺，約 30 分鐘：
- 儲值最小金額，發出上面那個 curl 請求，確認能跑通。
- 改成帶
tools=[{"type": "x_search"}]的請求，問一個關於近期事件的問題。 - 把完整的
usage物件印出來，特別是server_side_tool_usage_details。 - 用同一個問題再跑一次，但這次加上
from_date、to_date與allowed_x_handles收窄範圍。 - 比較兩次的抓取則數與總成本。
第 5 步通常會讓人嚇一跳——收窄前後的差距往往是數倍。在寫任何會自動重複執行的程式之前，先做完這一步。
🔗 資料來源
- xAI 開發者文件 — 快速開始——端點、認證、curl 與 Python 範例、SDK 相容性、需先儲值（一手，2026-10-22）。
- xAI 開發者文件 — 價格——完整價目、200k 計費規則、批次與優先處理修正項（一手）。
- xAI 開發者文件 — X Search——工具用法、參數與抓取量計費（一手）。
- xAI 開發者文件 — 模型（一手）。