Grok 有官方 SDK 了，TypeScript 开发者的 REST 封装可以扔了

调 Grok 一直有个别扭的地方：xAI 官方只给 REST 文档，想要类型提示、流式解析、工具调用，全靠社区封装或者自己手搓 fetch。9 月中旬这事有了转机，@xai-official/sdk 上了 npm，到 10 月初已经更到 v0.2.1。装一行命令就能用，虽然 README 里明晃晃写着 experimental，但它把 Responses API、X 搜索、代码执行、图像视频生成、语音这些能力全部装进了一个零依赖的 TypeScript 包。

五分钟能跑起来

SDK 要求 Node 22.13 以上、ESM 项目，密钥从环境变量 XAI_API_KEY 读：

import { SpaceXAI } from "@xai-official/sdk";

const client = new SpaceXAI();

const response = await client.responses.create({
  model: "grok-4.7",
  input: "Explain why the sky is blue in one sentence.",
});

console.log(response.toText());

整个包没有任何运行时依赖，类型跟着源码走，不用再对着 REST 文档猜字段。流式的写法是事件监听：on("text") 收正文、on("reasoning") 收思考过程、on("server_tool_call") 能看到每一次服务端工具调用的名字和参数，最后 await stream.done() 拿到完整响应。

服务端工具是真正的主角

函数工具各家 SDK 都有，xAI 把差异化放在了服务端工具上：网页搜索、X 搜索、代码执行、Collections 搜索、远程 MCP，全部由 xAI 的服务端代跑，你只管在 tools 里声明。

最实用的是 X 搜索，可以限定账号和时间窗：

import { xSearch } from "@xai-official/sdk/tools";

const response = await client.responses.create({
  model: "grok-4.7",
  input: "What has xAI announced on X this month?",
  tools: [xSearch({ allowed_x_handles: ["xai"], from_date: "2026-09-01" })],
});

allowed_x_handles 和 excluded_x_handles 各收最多 20 个账号，打开 enable_image_understanding 之后模型还能看推文里的图片和视频。对做舆情监控、竞品追踪的应用来说，这一项就够把自建爬虫下掉了。

其余几个服务端工具各有分工：网页搜索带引用回传，流式时每条引用会走 "citation" 事件；代码执行让模型在沙箱里跑代码验证答案；远程 MCP 则是把外部 MCP 服务器的工具直接挂进对话，不用自己写协议层。这些调用走 server_tool_call 事件回传明细，调试时能完整看到模型每一步用了什么工具、传了什么参数。

细节里能看出产品判断

几个设计点值得单独说。

浏览器和 Worker 默认禁用。 SDK 检测到非 Node 环境直接抛错，理由写在文档里：API 密钥进了客户端代码，等于交到用户手里。想强开要自己显式传参，这个默认值站得稳。

Reasoning 模型的等待要自己管理。 默认推理强度下，长回答可能几分钟才吐第一个 token。做流式 UI 有两条路：把 reasoning.effort 调低换响应速度，或者把 "reasoning" 事件也渲染出来让用户看着模型思考。

视频生成是后台任务。 videos.generate() 拿到 request_id，videos.wait() 每 5 秒轮询、最长等 10 分钟。任务开始后没法取消，跑完照常计费，生成的 URL 是临时的，要自己及时下载落盘。

其余能力清单还包括：图像输入、图像生成与编辑、Files、Batch、语音合成与转写、tokenization、长对话自动压缩。响应里带 usage、HTTP 元数据和未识别字段的透传，再配一组类型守卫函数方便遍历输出项，工程完成度不像一个 0.2 版本。

一句话结论

这不是又一个 API wrapper，而是 xAI 生态补上的关键一环：X 数据、代码执行、多媒体生成这些别家没有的能力，第一次有了一等公民的编程接口。experimental 的标签意味着 1.0 之前接口还会变，官方文档也建议锁定精确版本再升级。如果你本来就在用 Grok API，现在值得把封装换成它；如果还在观望，至少 X 搜索这一项值得认真看一眼。

仓库地址：xai-org/xai-sdk-ts，npm 包名 @xai-official/sdk。