第一次调用：构建一个可验证的解释器

先选择接口，而不是先装 SDK

xAI 当前推荐 POST https://api.x.ai/v1/responses。它接收 input，返回一组 typed output items，适合工具、流和多轮响应。/v1/chat/completions 仍可用，但属于 legacy 接口，使用 messages / choices，新能力通常先进入 Responses。

本站示例只依赖 Node.js 内置 fetch，避免把协议细节藏在 SDK 后面。完整文件位于 examples/basic.ts，运行：

cp .env.example .env
export XAI_API_KEY="xai-..."
pnpm example:basic "为什么 KV Cache 能降低解码计算？"

最小请求

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "input": [
      {"role": "system", "content": "你是严谨的技术导师。"},
      {"role": "user", "content": "用三句话解释 KV Cache。"}
    ]
  }'

model 是部署 ID，不是永恒常量；截至本站快照，grok-4.5 是文档示例中的当前模型。上线前用 GET /v1/models 查询账户可用项，需要复现时优先固定 dated version 而不是可移动的 -latest alias。

TypeScript：解析 typed output

// 真实可运行示例，见 examples/basic.ts
const response = await fetch('https://api.x.ai/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: process.env.XAI_MODEL ?? 'grok-4.5',
    input: [
      { role: 'system', content: 'Explain precisely. Mark uncertainty.' },
      { role: 'user', content: question },
    ],
  }),
});

if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const data = await response.json();
const text = data.output
  .filter((item: any) => item.type === 'message')
  .flatMap((item: any) => item.content)
  .filter((item: any) => item.type === 'output_text')
  .map((item: any) => item.text)
  .join('');

不要假设 output[0].content[0] 永远是文字。工具调用、推理信息和其他 item 可能混在 output 中；按 type 分派可以让代码随着能力扩展保持清晰。

消息角色与上下文

常用角色是 system、user、assistant。system 提供稳定行为约束，user 提供本轮任务，assistant 历史用于延续对话。多模态输入的 content 可变为 input_text / input_image 等 typed blocks。

Responses 默认可存储响应，并能用 previous_response_id 继续；若业务不希望服务端保存，应按当前文档设置 store: false 并自行重传必要上下文。数据保留要求应在上线前按账户条款复核。

把“小应用”做成可验证流程

示例应用不是普通聊天框，而是“技术概念解释器”：要求模型返回直觉、机制、限制与核验点。调用后由程序检查结果非空、保存 model/version/usage，并把来源要求展示给用户。

推荐请求模板：

解释 {concept}：
1. 它解决什么问题
2. 一个不误导的直觉类比
3. 技术机制
4. 在 Grok-1 公开源码中的对应（没有就说没有）
5. 优势、代价与不可确认部分

这不是为了“提示词工程花活”，而是把教材的事实边界转成稳定输出契约。

错误处理最少要覆盖

情况	应用行为
401/403	不重试；检查 key 与权限，日志不得记录完整 key
429	读取响应头，指数退避并设最大次数
5xx / 网络失败	有上限地重试；为写操作使用幂等设计
超时	`AbortController` 中断，向用户显示可恢复状态
内容为空/结构变化	保留原始 request ID，按 type 安全解析

本章检查点

一个可用 API 集成至少要做到：密钥只在服务端、请求可超时、错误可分类、输出按 type 解析、模型版本可追踪。能“打印一句回答”只是连接成功，不是工程完成。