xAI API

什麼是 xAI API？

xAI API 是開發者從應用程式程式碼中使用 xAI 的 Grok 模型的方式。其核心目的是接受提示（某些模型也接受影像），並回傳生成的回應，讓您可以顯示、處理或結構化以供後續使用。

快速入門指南將帶您走完端到端流程：建立 xAI 帳號並新增點數、產生 API 金鑰、安裝 SDK，以及使用支援的端點和範例向 Grok 模型送出第一個請求。

主要功能

• 透過環境變數的 API 金鑰驗證：使用 XAI_API_KEY 設定您的程式碼，xAI SDK 會自動讀取。
• 常見語言的 SDK 支援：安裝 Python 或 JavaScript 的 xAI SDK，即可呼叫 Grok 模型，無需撰寫原始 HTTP 請求。
• 對話式文字生成：傳送系統訊息和使用者訊息，並取樣模型的文字回應輸出。
• 回應端點相容性：使用 API 金鑰直接呼叫 https://api.x.ai/v1/responses 進行模型推論。
• 多模態輸入（文字 + 影像）：對於支援的模型，可在單一請求中附上影像 URL 與文字。
• 結構化輸出（適用於支援的模型）：某些模型可強制輸出結構，以控制生成結果的形狀。

如何使用 xAI API

1. 在 accounts.x.ai 建立 xAI 帳號，然後新增點數以使用 API。
2. 在 xAI 主控台的「API 金鑰」中建立 API 金鑰。
3. 設定 XAI_API_KEY，可於終端機匯出或新增至 .env 檔案：
   • export XAI_API_KEY="your_api_key"
   • XAI_API_KEY=your_api_key
4. 依語言安裝 SDK：
   • Python：pip install xai-sdk
   • JavaScript：npm install ai @ai-sdk/xai zod
5. 向 Grok 模型送出請求（範例顯示 grok-4.20-reasoning 用於文字，以及 grok-4 用於影像+文字）。可使用 SDK 範例或直接的 responses HTTP 請求。

使用情境

• 為 Grok 建立聊天介面：建立應用程式傳送使用者問題與選用系統指示，然後顯示 response.content 或 completion.output_text。
• 使用特定模型端點生成文字：採用 POST https://api.x.ai/v1/responses 流程，將 Grok 整合至偏好直接 HTTP 呼叫的服務。
• 在問答流程中新增影像理解：使用快速入門所示的多模態請求格式，提交影像 URL 與提示如「這張影像有什麼？」。
• 強制輸出格式以供後續處理：使用支援的 Grok 模型時，套用結構化輸出，讓結果遵循您定義的結構描述。
• 跨執行環境快速實驗：在 Python 和 JavaScript 範例間切換，同時維持相同的環境變數設定（XAI_API_KEY）。

常見問題

如何驗證 xAI API 請求？

在 xAI 主控台建立 API 金鑰，並設為 XAI_API_KEY（例如透過 export XAI_API_KEY="..." 或 .env 檔案）。xAI SDK 會自動讀取此環境變數。

第一個請求可以使用哪個 Grok 模型？

快速入門範例使用 grok-4.20-reasoning 進行純文字對話式生成，以及 grok-4 進行影像+文字輸入。

可以不使用 SDK 呼叫 API 嗎？

可以。快速入門包含直接 curl 範例，POST 至 https://api.x.ai/v1/responses，JSON 本體包含 model 和 input。

如何向 Grok 傳送影像？

對於接受影像的模型，可在輸入中附上影像 URL 與文字（範例使用 SDK 的 input_image / input_text 結構，或 responses 呼叫中的類型化內容結構）。

什麼是結構化輸出？

快速入門指出某些模型支援結構化輸出，可強制 LLM 輸出遵循結構描述。頁面參照專屬的「文字生成指南」以深入使用。

替代方案

• 使用其他 LLM 供應商的聊天/助理 API：若您的流程為「輸入提示、輸出生成文字」，可替換為其他供應商的 API，使用類似的金鑰驗證和請求格式。
• 使用不依賴框架的文字生成方式：不使用特定供應商 SDK，直接建構對「completions/responses」風格端點的請求，以跨語言維持整合一致性。
• 使用支援多模態的模型 API：若主要需求為影像+文字理解，請尋找明確支援 API 請求結構描述中影像輸入的供應商，並相應調整請求負載。