AI SDK xAI Grok 提供者ai-sdk/xai能力全景从 Chat、Responses 到批量、文件、音视频与 Realtime【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/aiai-sdk/xai是 AI SDKTypeScript 版 AI 工具包中面向 xAI Grok 模型的官方提供者本文基于 packages/xai/CHANGELOG.md 的完整变更记录结合 packages/xai 包内源码系统梳理该提供者当前4.x具备的全部能力Responses API 默认化、推理控制reasoning、服务端工具、批量Batch与文件Files接口、图像/视频生成、语音合成与流式转写、Realtime 语音对话等。读完本文你可以掌握xai()各入口的选型、关键 provider options 的参数语义与取值以及这些功能在 SDK 内部如何落到真实 HTTP/WebSocket 调用上。一、包与入口一个提供者七类模型接口安装与版本前提在 README.md 中提供了最小安装方式npm i ai-sdk/xai根据 package.jsonai-sdk/xai当前版本为4.0.57属于 ESM-only 包type: module最低要求 Node.js 22支持 22、24、26zod为 peerDependency^3.25.76 || ^4.1.8。运行时依赖只有ai-sdk/provider与ai-sdk/provider-utils——CHANGELOG 4.0.31 记录曾将共享的ai-sdk/openai-compatible依赖彻底移除表明该提供者已完全自研实现不再依托 openai-compatible 基础。Provider 入口与默认出口从 src/xai-provider.ts 可以看到createXai()默认以https://api.x.ai/v1为 baseURL从XAI_API_KEY环境变量读取 API Key并在 User-Agent 中附带ai-sdk/xai/${VERSION}后缀。导出的默认实例import { xai } from ai-sdk/xai; const text await generateText({ model: xai(grok-4.6), prompt: Write a vegetarian lasagna recipe for 4 people., });CHANGELOG 4.0.0f62681f明确记录了make responses api the defaultxai(modelId)、xai.languageModel(modelId)、xai.responses(modelId)三者现在都走 Responses APIxai.chat(modelId)保留为 Chat Completions API 的显式入口。此外 src/xai-provider.ts 还暴露了如下模型工厂入口返回对应能力xai(modelId)/xai.responses()LanguageModelV4Responses API 文本生成默认xai.chat(modelId)LanguageModelV4Chat Completions 文本生成xai.image(modelId)ImageModelV4图像生成/编辑xai.video(modelId)Experimental_VideoModelV4视频生成grok-imagine 系列xai.speech()SpeechModelV4文本转语音TTSxai.transcription()TranscriptionModelV4语音转文本STT含 WebSocket 流式xai.files()FilesV4文件上传/元数据/下载/删除xai.experimental_batch()BatchV4批量推理xai.experimental_realtime(modelId)Realtime 工厂语音到语音对话并提供.getToken()生成服务端临时令牌所有类型入口XaiProvider、XaiProviderSettings定义在 src/xai-provider.ts并在 src/index.ts 中统一导出XaiProviderSettings支持自定义baseURL、apiKey、headers、fetch拦截/测试以及webSocket为不支持自定义 header 的运行时提供 WebSocket 构造器。二、模型 ID 与推理控制reasoning当前模型 ID 集合CHANGELOG 4.0.080e1702对XaiChatModelId/XaiResponsesModelId自动补全列表做了裁剪src/xai-chat-language-model-options.ts 与 src/responses/xai-responses-language-model-options.ts 当前一致的集合为grok-4.20-non-reasoninggrok-4.20-reasoninggrok-4.3grok-4.54.0.10d25a084加入grok-4.64.0.37a4d386d加入grok-latest注意模型 ID 类型为开放联合(string {})即只要 xAI API 接受的 ID 都可以传入上述列表仅影响 IDE 自动补全CHANGELOG 中明确说明这不是运行时变更。历史版本中还记录过 grok-3、grok-4-fast、grok-code-fast-1 等 ID 的增删以及 4.0.0aa5a583移除已下线 Grok 2 模型。reasoningEffort 与顶层 reasoning推理控制是 4.x 迭代的核心之一reasoningEffortChat 与 Responses 的 provider option 均为none | low | medium | high | xhigh可选。其中none完全禁用推理grok-4.3 及更新推理模型支持不产生 thinking tokensxhigh是 4.0.37 随 grok-4.6 新增的最高档。4.0.080e1702给出示例import { xai } from ai-sdk/xai; import { generateText } from ai; await generateText({ model: xai(grok-4.3), prompt: Hi, providerOptions: { xai: { reasoningEffort: none }, }, });顶层reasoning参数映射4.0.88e006de修复了reasoning: none时向 API 发送reasoning_effort: none的行为并对拒绝该参数的模型如grok-4.20-reasoning、grok-4.20-non-reasoning及日期变体省略参数并发出 unsupported 警告。4.0.080e1702还修复了 chat 模型将顶层reasoning: medium错误强转为low的问题。reasoningSummary仅 Responses见 src/responses/xai-responses-language-model-options.tsauto | concise | detailed4.0.00f11f10引入。加密推理ZDR4.0.08d87577支持 encrypted reasoning round-trip3.0.x 系列则记录了reasoning-start/reasoning-end顺序修复3.0.137ac2437、3.0.3958800f3、新 reasoning chunk part 处理3.0.498b3e72d、多 summary-part 场景下reasoning-start去重4.0.02dc2a52以及从内容中提取推理文本的修复4.0.012115e9。这些修复保证了流式输出中推理内容与正文的顺序、去重与提取都符合 AI SDK 的 message 规范。三、Chat 与 Responses两套请求管线的 provider optionssrc/xai-chat-language-model-options.tsChat与 src/responses/xai-responses-language-model-options.tsResponses分别定义了 provider options除reasoningEffort外还包括Provider optionChatResponses说明reasoningEffort✅✅见上文reasoningSummary—✅auto/concise/detailedlogprobs/topLogprobs✅✅topLogprobs为 0–8 整数3.0.612e00e03引入serviceTier✅✅default \| priority4.0.38484293f引入parallel_function_calling✅—默认 true控制工具并行调用3.0.0b9e5b77searchParametersLive Search✅—已废弃见下store—✅是否存储输入/输出ZDR 团队必须设false默认 truepreviousResponseId—✅关联上一条响应 IDinclude—✅目前仅[file_search_call.results]用于内联返回文件搜索结果3.0.4005f3f36几个值得注意的行为Live Search 已废弃4.0.023f9d72将searchParametersxai live search标记为 deprecated改用web_search/x_searchAgent Tools4.0.09cded0d还修复了sources格式。请求携带该选项现在会收到 Live search is deprecated 错误。源码中保留了完整的 schemamode、returnCitations、fromDate/toDate、maxSearchResults1–50、sourcesweb/x/news/rss 四种 discriminated union供迁移时对照。serviceTier: priority4.0.38 为 Chat 与 Responses 同时加入优先级服务档位用于对延迟敏感的生产场景。usage 与 providerMetadata4.0.45dfa7305保证 Chat Completions 的完整 usage 对象在生成与流式结果中原样保留4.0.4641e7760同样覆盖 Responses usagecostInUsdTicks通过 providerMetadata 暴露4.0.0a0b0a0c、d20829e。流式协议健壮性历史版本针对 Responses 流做了大量修复——处理response.incomplete/response.failed事件4.0.0813851f、处理流中错误 chunk4.0.0e5bdc8d、避免 text delta 重复3.0.119a53f59、支持response.function_call_arguments.delta/done3.0.54902e93b、usage: null兼容3.0.34648c8f3、200 状态但返回错误体3.0.12e7bdbc7、流式与一次性 providerMetadata 结构一致3.0.16f446e23、transcript-final/reasoning-end的发送顺序等。四、服务端工具Server-side Tools与 Responses 文件输入8 个开箱即用的 Agent Toolssrc/tool/index.ts 将 8 个服务端工具聚合成xaiTools通过xai.tools.*或具名导出使用配合xai.responses(modelId)工具能力变更来源webSearchResponses API Web Search支持enableImageSearch映射enable_image_search3.0.01dbecd7xSearch站内搜索工具3.0.05ad1bbe服务端工具调用落地codeExecution沙箱代码执行3.0.0b39ec2c修复 schemafileSearch向量库检索vectorStoreIdsmaxNumResultsinclude: [file_search_call.results]3.0.4005f3f36imageGeneration图像生成服务端工具Responses API4.0.34fa2c2bbmcpServer远程 MCP 服务器调用3.0.3227d0c05viewImage/viewXVideo查看图像 / X 视频—相关实现细节分散在 src/tool 目录下如 web-search.ts、file-search.ts。CHANGELOG 还记录了工具相关修复toolChoice强制指定服务端工具不被 xAI API 支持时改为发警告3.0.40、严格模式3.0.65d5801fe、自定义工具custom_tool_callx_search、view_x_video流式 input chunk3.0.9/3.0.10、工具调用 finish reason 修正4.0.09f20868、流式工具调用结果按 provider-executed 发出4.0.75520b8a、工具结果中保留图片4.0.1654e5498、web_search action 的 query/sources/open_page 完整保留4.0.486843788以及 4.0.085735d8移除工具 schema 中多余的 additionalProperties 标志。非图片文件input_file file_url4.0.078b6433为 Responses API 补齐非图片文件PDF、text、CSV支持data:URL 且 mediaType 非image/时SDK 输出{ type: input_file, file_url }并把application/pdf、text/*加入supportedUrls以免提前下载为字节内联 base64 非图片输入仍会报错因为 xAI Responses API 要求非图片文档必须使用公开 URL 或已上传的file_id。相关转换逻辑在 src/responses/convert-to-xai-responses-input.ts 与 src/xai-file-part-options.ts。4.0.09bd6512同时将文件 part 的 data 属性改为带类型标记并移除了独立的 image part 类型。五、Files 接口上传、TTL、下载与删除CHANGELOG 4.0.52f1513f0为 xAI Files 接口补齐了完整生命周期能力实现在 src/files 目录getFileMetadata/downloadFile流式/deleteFile全部落地上传 TTLexpiresAfter整数秒范围 36001 小时 259200030 天见 src/files/xai-files-options.ts按 xAI 要求 TTL 字段必须先于 file part 发送流式上传支持{ type: stream }data上传结果暴露byteSize/createdAt/expiresAt所有文件操作均支持abortSignal与headers透传空字符串与点段dot-segment文件 ID 会被拒绝/编码防止路径重定向攻击。Files 接口与 Batch 紧密配合批量输入文件即通过/v1/files上传4.0.54048ce06进一步把上传的输入文件信息inputFileId/inputFileExpiresAt暴露到 batch start 结果的providerMetadata.xai。六、Batch API文本与图像批量推理能力矩阵Batch 支持从 4.0.453f8fa93引入并在后续版本持续增强当前实现位于 src/xai-batch.ts能力变更基础 batch 启动/状态/结果4.0.453f8fa93工具调用支持4.0.51e07b577按请求指定模型per-request models4.0.55a4ba394批量取消与列表4.0.574b8c4fa输入文件 TTLinputFileExpiresAfter3600–2592000 秒与 inputFileId 元数据4.0.54048ce06底层实现要点从 src/xai-batch.ts 源码可以看到完整调用链启动校验仅支持text/image两类请求其他类型抛UnsupportedFunctionalityError逐条请求调用XaiResponsesLanguageModel.prepareRequest文本或直接构造图像请求体将每条请求序列化为 JSONLcustom_idmethod: POSTurlbody以application/jsonlBlob 通过POST /v1/filesmultipartexpires_after先于 file 字段上传再POST /v1/batches提交name: ai-sdk-text-batch、input_file_id返回batchId、状态与providerMetadata.xai.inputFileId/inputFileExpiresAt。注意xAI Batch 不支持 per-batch webhook URL传入webhookUrl会产生 unsupported 警告。状态GET /v1/batches/{id}归一化为pending/completed/failed含取消与过期判定cancel_by_xai_message、expire_time均参与判断并带出requestCountstotal/pending/completed/failed。结果GET /v1/batches/{id}/results?limit1000pagination_token...分页拉取文本结果按 chat completion 格式解析chat_get_completion映射 finish reason、usagecost_in_usd_ticks、引用citations → source part、工具调用含 provider-executed 标记图像结果image_generation支持b64_json与 URL 两种形式URL 走getFromApi并启用validateUrltrustedOrigin校验respect_moderation: false判为内容策略违规失败每个 item 的失败会转为带code的BatchV4Error。取消/列表POST /v1/batches/{id}:cancel与GET /v1/batches?limitpagination_token4.0.57。图像批量请求还支持 provider optionsoutput_format、sync_mode、aspect_ratio、resolution、quality、user见 src/xai-image-model-options.tssize/seed/mask不被支持时会发出 unsupported 警告。七、图像与视频生成图像模型图像模型src/xai-image-model.ts能力从 1.1.18 的 image model support 一路演进4.0.025f1837b64_json响应格式、usage 成本追踪costInUsdTicks、quality与user参数4.0.0f5181ad图像编辑支持多张输入图3.0.52c781168独立XaiImageModel支持 JSON-based 图像编辑3.0.598641667resolutionprovider option1k | 2kgrok-imagine 模型可输出更高分辨率3.0.586af6c5c模型 ID 补全加入grok-imagine-image-pro、grok-2-image-12124.0.972eee24image file part 支持imageDetailprovider option 控制图像处理分辨率4.0.42ef05760与 4.0.39646c86e图像/视频 moderation blocks 报为内容策略错误、缺失 URL 报为错误状态而非抛异常。视频模型视频能力从 3.0.5756dfdf6add video support开始当前模型 ID 见 src/xai-video-settings.tsgrok-imagine-video、grok-imagine-video-1.54.0.368edc775加入。关键演进异步 start/status 流程4.0.2679e133c为实验性视频模型接口VideoModelV4加入doStart/doStatus/handleWebhookOptionexperimental_generateVideo接受poll/webhook编排完成轮询支持自定义 delay 实现以兼容 durable workflow引用输入R2V4.0.0f51c95e加入 reference-to-videoR2V支持4.0.30274f34加入一等公民frameImages与inputReferences调用选项4.0.100f93c57允许视频不只图片作为引用输入参考音频4.0.363d05053加入referenceVoiceIds最多 3 个 xAI 预设 voice id如[eve]在 prompt 中用AUDIO_0–AUDIO_2引用请求时发送reference_audios: [{ voice_id }]到POST /v1/videos/generationsGrok Imagine Video 1.54.0.36 支持原生1080ptext-to-video / image-to-video标准resolution: 1920x1080现在映射到1080preference-to-video 仍封顶 720p请求 1080p 会自动降级并警告同时修复引用路由——此前任意非空inputReferences数组都会选中 reference-to-video导致只有非图片引用时发送空reference_images: []健壮性4.0.222b872b0修复轮询状态时挂起、4.0.161e2ae1f处理空 HTTP 202 响应4.0.0d20829e加入 moderation error 与costInUsdTicks4.0.1591a3d6e支持 end-user 标识视频生成与编辑。八、语音TTS、STT 与 Realtime文本转语音TTS4.0.07486744加入 text-to-speech4.0.401ffa1d2大幅增强provider options 定义在 src/xai-speech-model-options.tssampleRate8000/16000/22050/24000/44100/48000 HzbitRateMP3 比特率 32k/64k/96k/128k/192k bps仅outputFormat: mp3时生效optimizeStreamingLatency0/1/2降低首包延迟牺牲部分音质textNormalization合成前将书面文本规范为口语形式withTimestamps解码 JSON 信封、照常返回音频同时通过providerMetadata.xai暴露时长、content type 与字符级对齐character-level alignmentreplace发音替换映射值可以是拼写改写如{ Acme Mobile: Acme Mobull }或 IPA 音标如{ nginx: /ˈɛndʒɪn ˈɛks/ }每次语音响应都会在providerMetadata.xai.traceId返回x-trace-id响应头错误解析读取{error:...}形状使APICallError携带 xAI 真实错误信息而非 HTTP 原因短语。语音转文本STT与 WebSocket 流式转写4.0.07486744加入 speech-to-text4.0.65c5c0f5加入实验性流式转写WebSocket STT4.0.11e193290引入共享的connectToWebSocket层。provider options 见 src/xai-transcription-model-options.ts非流式audioFormatpcm/mulaw/alaw、sampleRate、language、formatinverse text normalization需language、multichannel、channels2–8、diarize、keyterm单个或数组、fillerWords流式streaming子对象interimResults中间结果、endpointing静默阈值毫秒0–5000、smartTurn0–1设置后启用 Smart Turn 结束检测、smartTurnTimeout1–5000 毫秒强制 speech_final。4.0.11 详细记录了流式转写的协议级修复transcript-final只在speech_final: true时发出xAI 会先用speech_final: false重发已定稿文本也会定稿最终会被合并的片段定稿片段以transcript-partial暴露transcript.done事件 text 为空导致NoTranscriptGeneratedError的问题通过用累积的最终话语回填 finish.text解决。工程层面WebSocket 构造失败转为流错误而非同步抛错、已 abort 的 signal 不再建连、发送失败会取消调用方的音频流、bufferedAmount反压、undefined header 值在构造前剔除。Realtime 语音对话4.0.0ce769dd为 OpenAI、Google、xAI 三个提供者加入实验性 Realtime语音到语音支持xAI 实现位于 src/realtimexai.experimental_realtime(modelId)在服务端与浏览器均可用.getToken()静态方法服务端生成临时令牌见 src/xai-provider.ts 中doCreateClientSecret调用返回{ token, url, expiresAt }experimental_getRealtimeToolDefinitions生成会话工具定义ai-sdk/react的experimental_useRealtimehook 返回与useChat对齐的UIMessage[]支持onToolCall/addToolOutput做客户端驱动工具执行inputAudioTranscription会话配置可在提供者支持时展示转写后的用户音频消息。九、横切能力安全、元数据、工作流与兼容性URL 安全校验4.0.124be62c1在getFromApi增加validateUrl标志xAI 在图像/视频/音频下载与轮询等URL 来自提供者响应体的调用点启用配合credentialedOrigin仅同源才发送 API Key与trustedOrigin开发者配置端点同源豁免被阻止的 URL 抛DownloadError。相关指导见 contributing/secure-url-handling.md。工作流序列化4.0.0b3976a2为所有 provider 模型加入WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZEheaders变为可选便于模型跨 workflow 步骤边界序列化。ESM-only4.0.0ef992f8移除所有 CommonJS 导出require()用户需迁移到 ESMimport。usage 准确性3.0.51e1d5111修正推理模型 token 计算、3.0.677012ef避免负数text_output_tokens、3.0.567ccb902处理缓存 token 报告不一致、2.0.0cf8280e流式返回真实 usage 而非 NaN。错误信息4.0.01293885在APICallError.message中呈现完整 xAI 错误详情而非 HTTP 状态文本XaiErrorData类型从 src/xai-error.ts 导出。兼容性提示4.0.312b1068f说明该提供者已从 openai-compatible 基线重写为自研实现自有 tool preparation、finish-reason 映射与 response metadata helpers4.0.21dc2f851会在 Responses 模型忽略不支持的采样设置时发出警告3.0.65d5801fe确保工具 strict mode。十、快速参考最小接入示例import { xai } from ai-sdk/xai; import { generateText, streamText, generateImage, generateSpeech } from ai; // 1) 文本生成默认 Responses API const { text } await generateText({ model: xai(grok-4.6), prompt: Explain the Grok model family in one paragraph., providerOptions: { xai: { reasoningEffort: medium, serviceTier: priority }, }, }); // 2) 服务端工具Responses API web_search const result await generateText({ model: xai.responses(grok-4.6), tools: { search: xai.tools.webSearch({ maxNumResults: 5 }), }, prompt: What is the latest xAI announcement?, }); // 3) 图片生成 const { images } await generateImage({ model: xai.image(grok-imagine-2), prompt: A neon city skyline at dusk, providerOptions: { xai: { quality: high } }, }); // 4) 语音合成 const { audio } await generateSpeech({ model: xai.speech(), text: Hello from Grok., providerOptions: { xai: { withTimestamps: true, replace: { Grok: Grok, like the martian. } }, }, });十一、迭代脉络小结从 CHANGELOG 的版本序列可以清楚看到ai-sdk/xai的三条主线一是API 对齐——4.0.0 把 Responses API 设为默认、移除对 openai-compatible 基线的依赖、全面切换 v4 类型二是能力横向扩展——从纯文本逐步覆盖图像生成/编辑、视频含 R2V、参考音频、异步轮询、语音TTS/STT/Realtime、Files、Batch三是工程健壮性打磨——流式协议事件、usage 统计、错误解析、URL 安全、ZDR 加密推理、工作流序列化等细节持续修复。这套实现与测试、快照、fixtures 全部位于 packages/xai/src如 xai-batch.test.ts、xai-chat-language-model.test.ts、xai-video-model.test.ts 等可作为深入阅读与二次开发的入口。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考