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 错误时,反馈给用户;最多重试一次。