xAI API (Grok)
當環境中存在 XAI_API_KEY 時,此應用程式便擁有真正的 xAI API 存取權——請將其用於 AI 功能,而不要模擬回應或使用其他提供者。同一個變數在部署應用程式時也會被注入,因此基於此變數建構的程式碼在預覽和正式環境中都能以相同方式運作。
此金鑰是應用程式擁有者的個人金鑰:每次呼叫都會耗用他們的配額和點數。 在使用上請審慎考量——在將 AI 呼叫接入任何會自動執行或對訪客開放的流程之前,請參閱謹慎使用額度。
此金鑰解鎖了完整的 API 功能,不僅限於聊天:
- 聊天 / LLM — 最新模型:
grok-4.5;除非使用者特別要求,否則預設使用此模型。 - Imagine (圖片與影片) — 在應用程式執行時生成及編輯圖片、生成影片。
- 語音 — 文字轉語音,提供富有表現力的語音選項 (以及語音轉文字功能)。
- 官方文件:docs.x.ai — 端點、模型、參數、串流、工具使用。不要猜測 API 的結構;請查閱文件。
- 此 API 與 OpenAI 相容 (
https://api.x.ai/v1),因此任何 OpenAI 風格的客戶端只需切換基本 URL 和金鑰即可使用。
環境變數 — 請勿建立 .env 檔案
| 變數 | 位置 | 用途 |
|---|---|---|
XAI_API_KEY | 伺服器 | 由平台注入 (預覽和部署)。切勿自行編寫、寫死或向使用者索取此金鑰。 |
此金鑰僅供伺服器端使用:在 createServerFn 處理器 / 伺服器程式碼中使用 process.env.XAI_API_KEY 讀取,切勿在客戶端元件中使用,也絕不能透過 VITE_ 前綴的變數或 API 回應將其暴露出去。
此金鑰可能是不存在的 (逐步開放)。請妥善降級處理——檢查金鑰是否存在,若不存在則顯示友善的「AI 功能目前不可用」狀態,而非讓應用程式崩潰:
const apiKey = process.env.XAI_API_KEY;
if (!apiKey) throw new Error("AI is not available in this environment");
呼叫 API (僅限伺服器端)
無需 SDK——從伺服器函式中使用原生的 fetch:
import { createServerFn } from "@tanstack/react-start";
export const askGrok = createServerFn({ method: "POST" })
.validator((input: { prompt: string }) => input)
.handler(async ({ data }) => {
const apiKey = process.env.XAI_API_KEY;
if (!apiKey) return { ok: false as const, error: "AI is not available" };
const res = await fetch("https://api.x.ai/v1/chat/completions", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${apiKey}`,
},
body: JSON.stringify({
model: "grok-4.5",
messages: [{ role: "user", content: data.prompt }],
}),
});
if (!res.ok) {
return { ok: false as const, error: `xAI API error ${res.status}` };
}
const body = (await res.json()) as {
choices: { message: { content: string } }[];
};
return { ok: true as const, text: body.choices[0]?.message.content ?? "" };
});
關於串流、結構化輸出、視覺辨識或完整模型列表,請參閱 docs.x.ai — 其結構與 OpenAI 相容。
Imagine — 圖片與影片生成 (僅限伺服器端)
相同的金鑰可用於驅動應用程式中的執行時圖片/影片功能 (使用者頭像、場景美術、生成的內容)。這與您的建置時 imagine_text_to_image / imagine_image_to_image / imagine_image_to_video 工具 (imagine-grok-build 技能) 不同:當正在運行的應用程式需要生成媒體時請使用API,而當您在建置過程中為靜態素材進行創作時則使用那些工具。
// POST https://api.x.ai/v1/images/generations — 使用與聊天相同的授權標頭
body: JSON.stringify({
model: "grok-imagine-image-quality", // 或 "grok-imagine-image" (較便宜)
prompt: data.prompt,
// n (≤10), resolution ("1k"|"2k"), response_format ("url"|"b64_json")
})
// → body.data[0].url
- 圖片編輯:
POST /v1/images/edits— 自然語言編輯,最多可使用 3 張參考圖片。 - 影片:
grok-imagine-video需透過非同步影片端點 (啟動,然後輪詢傳回的請求 ID;片段最長約 15 秒)。 - 完整參數與範例:docs.x.ai → Imagine API。
語音 — 文字轉語音 (僅限伺服器端)
POST https://api.x.ai/v1/tts 可將文字轉換為語音音訊——適用於旁白、無障礙功能、角色語音:
// 相同的 Authorization 標頭;傳回音訊位元組 (例如 MP3)
body: JSON.stringify({ text: data.text, voice_id: "eve" }) // eve = 預設語音
透過 GET /v1/tts/voices 列出可用的語音 (也支援自訂語音);語音轉文字功能同樣可用。詳情請參閱 docs.x.ai → Voice API。從您的伺服器函式中將音訊提供給客戶端——切勿從瀏覽器端呼叫此 API (這會暴露金鑰)。
謹慎使用額度
此金鑰屬於應用程式擁有者 (您正在為其建構的使用者):每一次呼叫——包括由已部署應用程式的匿名訪客觸發的呼叫——都會耗用他們個人的配額和點數。將配額浪費在無謂的呼叫上會降低或中斷其金鑰的所有其他用途。請謹慎使用:
- 設定輸出上限 (
max_tokens) 並保持提示詞簡潔,特別是針對訪客面向的功能。圖片生成,尤其是影片生成,每次呼叫的成本遠高於聊天。 - 絕不要在任何迴圈中、每次按鍵時或頁面載入時呼叫 API——請確保呼叫是由使用者發起的 (如按鈕點擊、表單提交) 並進行去抖處理。
- 快取或持久化結果 (請參閱
neon技能),而不是為每個訪客或每次渲染重新生成相同內容。 - 對昂貴的流程加上限制——特別是媒體生成。在已具備登入功能的應用程式中,可將其置於
authMiddleware之後 (請參閱auth技能)。登入功能預設為關閉,若未經授權直接使用中介軟體會導致已部署的應用程式崩潰 (AGENTS.md §0.5)——因此,對於沒有帳號系統的應用程式,請改用使用限制的方式:由使用者發起呼叫、設定小額限制、快取結果。 - 請勿設定過多的重試機制:當 API 發生錯誤時,向使用者顯示錯誤訊息;最多重試一次。