如何配置 API 金鑰、選擇模型端點並使用 xAI Grok API 實現函式呼叫

軟體開發者將 xAI 的 Grok 模型整合至自身應用程式的過程非常直覺且高效，因為 xAI 平台不僅提供原生 SDK 與現代化 REST 端點，亦完全相容 OpenAI SDK 規範。Grok API 統一運行於 https://api.x.ai/v1 基礎位址，開發者只需配置標準的 Bearer Token 授權，即可自由調用旗艦級推理模型（如 grok-4.7）或低延遲程式碼模型（如 grok-build-0.1），並透過多輪函式呼叫（Function Calling）將 Grok 與企業資料庫、內部微服務以及外部第三方 API 深度串接。

本文為開發者提供從金鑰配置、模型與端點選型，到完整函式呼叫實作的完整指南。

一、配置 API 金鑰與基礎授權

存取 Grok API 所需的所有憑證皆透過 xAI 控制台（https://console.x.ai）進行集中管理。

1. 產生 API 金鑰

1. 前往並登入 xAI Console。
2. 於 Billing（帳單與儲值）頁面完成點數購買，確保帳戶擁有足夠的 API 額度。
3. 進入 API Keys 管理頁面（https://console.x.ai/team/default/api-keys），點擊 Create API Key。
4. 立即複製產生的金鑰字串並安全存放；關閉對話視窗後控制台將不再顯示完整金鑰。

2. 配置環境變數

建議透過環境變數傳入金鑰，變數名稱通常設定為 XAI_API_KEY：

export XAI_API_KEY="xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

在 Node.js 或 Python 專案中，可儲存在專案根目錄的 .env 檔案內：

XAI_API_KEY=xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. 初始化客戶端 SDK

由於 xAI 嚴格遵循標準 REST 協定並支援 OpenAI Schema 相容性，開發者可選擇官方 xai-sdk、社群廣泛採用的 openai 套件，或前端生態系的 Vercel AI SDK。

Python（使用 openai 官方套件）：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

Python（使用原生 xai-sdk）：

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))

Node.js / TypeScript（使用 openai 套件）：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

二、模型端點與架構選型

在設計系統架構時，開發者需釐清 HTTP 端點通訊協定與各模型代號間的對應關係。

端點協定：/v1/responses 與 /v1/chat/completions

• https://api.x.ai/v1/responses（官方推薦現代化端點）： 專為智慧代理（Agentic）工作流程打造，原生支援複合輸入陣列、利用 previous_response_id 進行多輪狀態追蹤、結構化輸出，以及與伺服器端搜尋工具的聯動。
• https://api.x.ai/v1/chat/completions（OpenAI 隨插即用相容端點）： 與業界主流 Chat Completions 規範完全一致，既有專案只需更新 baseURL 與 apiKey 即可無縫接軌。

文字與推理模型比較

補充說明：除了語言模型，xAI 亦提供專屬多模態端點，包括即時雙向語音 grok-voice-think-fast-2.0（Voice API）與影像/影片生成模型 grok-imagine-image-2.0（Imagine API）。

三、實現函式呼叫（Function Calling / Tool Calling）

函式呼叫賦予 Grok 自主使用外部工具的能力。模型不再僅依賴靜態訓練資料，而是能動態產生結構化參數來呼叫外部 API、讀寫資料庫或執行內部指令。

核心運作流程

1. 宣告工具： 開發者於請求中傳入具備 JSON Schema 格式的工具陣列（包含 name、description 與 parameters）。
2. 模型評估： Grok 分析使用者輸入，判斷是否需要呼叫外部函式以取得資訊。
3. 發出呼叫請求： 模型回傳包含函式名稱及 JSON 參數的 tool_calls 物件，並暫停產出文字。
4. 本機執行： 應用程式解析參數，並於本機或後端伺服器執行對應業務邏輯。
5. 回傳結果並總結： 將函式執行結果包裝後回傳給 Grok，模型結合結果生成最終的使用者回覆。

完整範例程式碼（Python + OpenAI 客戶端）

以下範例示範如何在 responses 端點中定義客戶資料查詢工具，解析呼叫請求、執行本機函式並將結果回傳：

import os
import json
from openai import OpenAI

# 1. 初始化客戶端
client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

# 2. 定義工具 Schema（必須遵循 JSON Schema 規範）
tools = [
    {
        "type": "function",
        "name": "fetch_user_account",
        "description": "根據使用者帳號 ID 查詢帳戶資料、訂閱方案等級與目前帳號狀態。",
        "parameters": {
            "type": "object",
            "properties": {
                "account_id": {
                    "type": "string",
                    "description": "使用者專屬帳號識別碼，例如 'usr_10294'"
                },
                "include_usage_stats": {
                    "type": "boolean",
                    "description": "是否同步回傳當前計費週期的 Token 使用量數據",
                    "default": False
                }
            },
            "required": ["account_id"]
        }
    }
]

# 本機商業邏輯模擬
def execute_fetch_user_account(account_id: str, include_usage_stats: bool = False):
    return {
        "account_id": account_id,
        "name": "Alex Mercer",
        "tier": "Enterprise",
        "status": "Active",
        "usage_tokens": 1420500 if include_usage_stats else None
    }

# 3. 發送包含工具定義的使用者問題
user_query = "請幫我查詢 usr_10294 使用者的帳號資料，並確認他們是否處於有效 Enterprise 方案？"

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": user_query}],
    tools=tools,
)

# 4. 處理模型回傳的函式呼叫
for item in response.output:
    if item.type == "function_call":
        func_name = item.name
        func_args = json.loads(item.arguments)
        call_id = item.call_id
        
        print(f"模型請求執行工具: {func_name}，參數為: {func_args}")
        
        if func_name == "fetch_user_account":
            tool_result = execute_fetch_user_account(**func_args)
            
            # 5. 將執行結果回傳給 Grok 繼續推論
            followup = client.responses.create(
                model="grok-4.7",
                input=[{
                    "type": "function_call_output",
                    "call_id": call_id,
                    "output": json.dumps(tool_result)
                }],
                tools=tools,
                previous_response_id=response.id,
            )
            
            # 輸出最終整合後的回覆文字
            for followup_item in followup.output:
                if followup_item.type == "message":
                    print("\n模型最終回覆:\n", followup_item.content[0].text)

四、工程架構重要規範與進階功能

在建置生產等級的 Grok 工具呼叫架構時，需留意下列規格特點：

• 根節點物件規範： 在工具的 parameters 定義中，根結構必須嚴格為 "type": "object"（或分支皆為 object 的 oneOf/anyOf）。若根結構直接定義為純純量或陣列，API 將拒絕請求並回傳 HTTP 400 驗證錯誤。
• 並行函式呼叫（Parallel Function Calling）： Grok 預設啟用並行呼叫。當複雜問題牽涉多個獨立資料源時，模型能在單一回合中同時輸出多筆工具呼叫請求。若需強制依序序列執行，可在請求中加入 parallel_tool_calls: false。
• 工具呼叫決策控制（tool_choice）：
  • "auto"（預設）：模型自主評估是回答文字還是觸發工具。
  • "required"：強制模型該回合必須至少呼叫一項工具。
  • "none"：暫時關閉工具呼叫功能。
  • {"type": "function", "function": {"name": "fetch_user_account"}}：強制指定模型呼叫特定函式。
• 混合編排自訂工具與內建工具： Grok 支援強大的混合編排能力。開發者可在同一次請求中，同時傳入本機自訂函式以及 xAI 官方託管的伺服器端工具（如 {"type": "web_search"} 網頁搜尋、{"type": "x_search"} X 社群檢索）。伺服器端工具由 xAI 雲端全自動執行，而自訂函式則保留給開發者本機接管。
• 單區塊串流傳輸： 在啟用串流模式（Streaming）時，Grok 的函式呼叫中繼資料會在單一完整區塊中送達，而非分散於微小的字符片段中，極大地簡化了前端或服務端反序列化的處理難度。

參考資料

• Grok API Quickstart: Get Your API Key | SpaceXAI Docs
• Grok Models & Pricing | SpaceXAI Docs
• API Pricing | SpaceXAI Docs
• Function Calling | SpaceXAI Docs
• API Reference - REST API Reference | SpaceXAI Docs