AI SDK xAI Grok Provider 接入指南从安装到 Responses API 服务端工具【免费下载链接】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 SDKVercel 出品的 TypeScript AI 工具包中的xAI Grok Providerai-sdk/xai包展开系统讲解如何在项目中安装接入 xAI 语言模型、创建与定制 Provider 实例、通过generateText与streamText完成文本生成并深入覆盖基于 xAI Responses API 的服务端 Agentic 工具网页搜索、X 搜索、代码执行、图像生成、MCP 等以及语音、图像、视频等扩展能力。读完本文你将掌握在 AI SDK 应用中完整接入并充分调用 xAI Grok 全系能力的实战方案。一、xAI Grok Provider 概览ai-sdk/xai是 AI SDK 官方提供的 xAI Grok 模型接入包为 xAI 的 Chat Completions API 与 Responses API 提供完整的语言模型支持。它不仅是文本生成入口还是一个覆盖多模态能力的 Provider 工厂语言模型chat/responses、图像生成image、视频生成video、语音合成speech、语音转写transcription、实时语音experimental_realtime、文件管理files与批处理experimental_batch均可在同一个 Provider 实例下创建。从源码看Provider 接口定义在 packages/xai/src/xai-provider.tsXaiProvider接口实现ProviderV4包的默认导出与全部类型定义集中在 packages/xai/src/index.ts包括createXai、xai以及全部服务端工具的工厂函数。二、安装与前置准备xAI Grok Provider 以ai-sdk/xai模块发布使用 npm 安装即可npm i ai-sdk/xai从 packages/xai/package.json 可以看到该包的运行时依赖只有ai-sdk/provider与ai-sdk/provider-utils两个工作区包zod为 peer 依赖要求^3.25.76 || ^4.1.8因此安装体积很小且sideEffects: false便于摇树优化。为编码 Agent 添加 AI SDK 技能如果你使用 Claude Code、Cursor 等编码 Agent 开发本项目建议将 AI SDK 官方技能加入仓库让 Agent 获得最新、最准确的 AI SDK 使用规范npx skills add vercel/aiAPI Key 配置Provider 默认从XAI_API_KEY环境变量读取 API Key。源码中通过loadApiKey加载优先使用createXai({ apiKey })传入的显式 Key否则读取XAI_API_KEY环境变量见 xai-provider.ts。默认的 API Base URL 为https://api.x.ai/v1。三、Provider 实例默认导入与自定义创建默认实例ai-sdk/xai导出了一个开箱即用的默认 Provider 实例xaiimport { xai } from ai-sdk/xai;自定义实例当需要定制 API Key、代理地址、自定义请求头或自定义fetch实现时使用createXai创建import { createXai } from ai-sdk/xai; const xai createXai({ apiKey: your-api-key, });支持的设置项XaiProviderSettings定义于 xai-provider.ts支持以下可选配置配置项类型说明baseURLstringAPI 调用地址前缀可用于指向代理服务器。默认https://api.x.ai/v1apiKeystring通过Authorization请求头发送的 API Key默认取XAI_API_KEY环境变量headersRecordstring, string附加到每个请求的自定义请求头fetchFetchFunction自定义 fetch 实现可作中间件拦截请求或用于测试环境注入 mockwebSocketWebSocketConstructor自定义 WebSocket 实现。当运行时的原生 WebSocket 构造器不支持携带请求头xAI 流式语音转写需要时必填底层实现中xai-provider.ts所有模型工厂共享同一套baseURL、getHeaders与fetch并会为请求附加ai-sdk/xai/VERSION的 User-Agent 后缀。四、语言模型最小示例与两种 API最小示例xAI 语言模型可直接在 AI SDK 的generateText中使用import { xai } from ai-sdk/xai; import { generateText } from ai; const { text } await generateText({ model: xai(grok-4.6), prompt: Write a vegetarian lasagna recipe for 4 people., });Responses API 与 Chat Completions API自 AI SDK 7 起xai(modelId)默认走xAI Responses API如需使用较旧的 Chat Completions API请显式调用xai.chat(modelId)。两种入口在 Provider 上均有对应工厂方法源码见 xai-provider.tsconst modelA xai(grok-4.6); // 默认Responses API const modelB xai.responses(grok-4.6); // 显式Responses API const modelC xai.chat(grok-4.6); // 显式Chat Completions API模型 ID 联合类型定义在 xai-chat-language-model-options.ts 与 xai-responses-language-model-options.ts当前包括grok-4.20-non-reasoning、grok-4.20-reasoning、grok-4.3、grok-4.5、grok-4.6、grok-latest也支持以字符串形式传入任意可用模型 ID。流式输出与结构化输出语言模型同样可用于streamText实现流式输出并可通过 AI SDK Core 的Output进行结构化数据生成见 content/docs/03-ai-sdk-core。五、Provider 选项推理强度、优先级处理与更多控制xAI 特有的配置通过providerOptions.xai传入并在请求组装阶段由 zod schema 校验Chat 路径见 xai-chat-language-model-options.tsResponses 路径见 xai-responses-language-model-options.ts。Reasoning Effort推理强度对于支持可配置推理的模型通过reasoningEffort控制模型思考的深度两种 API 均适用import { xai } from ai-sdk/xai; import { generateText } from ai; const { text } await generateText({ model: xai(grok-4.3), prompt: Explain quantum entanglement., providerOptions: { xai: { reasoningEffort: medium }, }, });可选值与适用场景none— 完全禁用推理不消耗思考 token适合追求近即时响应的简单场景low默认— 使用少量推理 token速度快适合通用 Agent 与工具调用medium— 更多思考适合对延迟不敏感的复杂数据分析、长上下文推理high— 更深思考适合复杂数学、多步逻辑与竞赛级任务xhigh— 最多推理 token仅grok-4.6支持。各模型支持的值与默认值不同grok-4.3支持none/low/medium/highgrok-4.5仅支持low/medium/high且默认high无法禁用推理grok-4.6支持low/medium/high/xhigh且默认highgrok-4.20-reasoning与grok-4.20-non-reasoning不接受该选项grok-4.20-multi-agent下low/medium/high控制的是 Agent 数量而非推理深度。具体请以 xAI 官方文档为准。Priority Processing优先级处理serviceTier: priority可请求更高调度优先级通常降低首 token 延迟并提升 token 间速度const { providerMetadata } await generateText({ model: xai(grok-4.6), prompt: Explain quantum entanglement., providerOptions: { xai: { serviceTier: priority }, }, }); // 实际生效的档位priority 或 default优先级容量不足时 console.log(providerMetadata?.xai?.serviceTier);优先级请求按 token 收取溢价且只有响应确认命中优先级档位时才会按该费率计费。因此务必从providerMetadata.xai.serviceTier读回实际生效档位而非假设请求即结果。省略该选项等价于default。其他选项Chat Completions APIlogprobs返回输出 token 的对数概率、topLogprobs每 token 位置返回最可能的 0–8 个 token、parallel_function_calling并行函数调用默认 truesearchParametersLive Search已被 xAI 废弃改用web_search/x_search工具。Responses APIlogprobs、topLogprobs、store是否存储输入与响应以便检索默认true启用 Zero Data Retention 的团队必须设为false、previousResponseId续接上一次响应的会话、include如[file_search_call.results]携带文件搜索结果、reasoningSummaryauto/concise/detailed。六、Responses API 服务端 Agentic 工具xAI Responses API 的核心价值在于模型可以在 xAI 服务器侧自主编排工具调用并完成研究无需客户端逐轮驱动。全部服务端工具由xai.tools暴露实现集中在 packages/xai/src/tool 目录入口见 tool/index.ts。注意Responses API 只支持服务端工具同一请求中不能混用服务端工具与客户端函数工具。1. Web Search网页搜索支持域名过滤与图片理解const { text, sources } await generateText({ model: xai.responses(grok-4.6), prompt: What are the latest developments in AI?, tools: { web_search: xai.tools.webSearch({ allowedDomains: [arxiv.org, openai.com], enableImageUnderstanding: true, }), }, }); console.log(text); console.log(Citations:, sources);参数说明allowedDomainsstring[]最多 5 个— 仅在这些域名内搜索不能与excludedDomains同用excludedDomainsstring[]最多 5 个— 排除指定域名不能与allowedDomains同用enableImageSearchboolean— 允许模型在图片对答案有帮助时以独立图像搜索模式检索响应可包含 Markdown 图片嵌入enableImageUnderstandingboolean— 允许模型查看并分析搜索到的图片会增加 token 消耗。2. X SearchX/Twitter 搜索按账号与日期范围检索 X 帖子const { text, sources } await generateText({ model: xai.responses(grok-4.6), prompt: What are people saying about AI on X this week?, tools: { x_search: xai.tools.xSearch({ allowedXHandles: [elonmusk, xai], fromDate: 2025-10-23, toDate: 2025-10-30, enableImageUnderstanding: true, enableVideoUnderstanding: true, }), }, });参数说明allowedXHandles最多 10 个— 仅检索这些账号的帖子不能与excludedXHandles同用excludedXHandles最多 10 个— 排除指定账号的帖子fromDate/toDateISO8601YYYY-MM-DD— 帖子日期范围enableImageUnderstanding/enableVideoUnderstandingboolean— 是否分析帖子中的图片与视频。3. Code Execution代码执行让模型编写并执行 Python 代码完成计算与数据分析const { text } await generateText({ model: xai.responses(grok-4.6), prompt: Calculate the compound interest for $10,000 at 5% annually for 10 years, tools: { code_execution: xai.tools.codeExecution(), }, });4. View Image / View X Video图片与 X 视频分析// 分析图片 const { text } await generateText({ model: xai.responses(grok-4.6), prompt: Describe what you see in the image, tools: { view_image: xai.tools.viewImage() }, }); // 分析 X 帖子中的视频 const { text } await generateText({ model: xai.responses(grok-4.6), prompt: Summarize the content of this X video, tools: { view_x_video: xai.tools.viewXVideo() }, });5. Image Generation对话内图像生成模型自行决定何时调用、撰写图像提示词并在文本回复的同时返回成品图基于 Grok Imagineconst result await generateText({ model: xai.responses(grok-4.6), prompt: Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print, tools: { image_generation: xai.tools.imageGeneration(), }, }); for (const toolResult of result.staticToolResults) { if (toolResult.toolName image_generation) { const base64Image toolResult.output.result; } }action参数默认auto可限制能力generate仅文生图、edit仅编辑对话内已有图片含模型先前生成的图片、auto两者皆可。工具结果中还包含模型为图像模型撰写的提示词便于理解与调试。6. MCP Server远程 MCP 连接连接远程 Model Context Protocol 服务器并使用其工具const { text } await generateText({ model: xai.responses(grok-4.6), prompt: Use the weather tool to check conditions in San Francisco, tools: { weather_server: xai.tools.mcpServer({ serverUrl: https://example.com/mcp, serverLabel: weather-service, serverDescription: Weather data provider, allowedTools: [get_weather, get_forecast], }), }, });参数说明serverUrl必填为远程 MCP 地址serverLabel/serverDescription用于标识与描述服务器allowedTools限制模型可用的工具名列表不传则全部可用headers与authorization用于携带自定义请求头与鉴权信息如Bearer token123。7. File Search向量库文档检索在 xAI 向量库collections中检索文档import { xai, type XaiLanguageModelResponsesOptions } from ai-sdk/xai; import { streamText } from ai; const result streamText({ model: xai.responses(grok-4.6), prompt: What documents do you have access to?, tools: { file_search: xai.tools.fileSearch({ vectorStoreIds: [collection_your-collection-id], maxNumResults: 10, }), }, providerOptions: { xai: { include: [file_search_call.results], } satisfies XaiLanguageModelResponsesOptions, }, });vectorStoreIds必填指定要检索的向量库 IDmaxNumResults限制返回条数。通过providerOptions.xai.include [file_search_call.results]可让响应携带带分数与内容的实际检索结果。该工具要求 grok-4 家族模型含 grok-4.20与 Responses API。8. 多工具组合与流式消费多个服务端工具可组合完成综合研究配合streamText流式消费文本与引用来源import { xai } from ai-sdk/xai; import { streamText } from ai; const { stream } streamText({ model: xai.responses(grok-4.6), prompt: Research AI safety developments and calculate risk metrics, tools: { web_search: xai.tools.webSearch(), x_search: xai.tools.xSearch(), code_execution: xai.tools.codeExecution(), file_search: xai.tools.fileSearch({ vectorStoreIds: [collection_your-documents], }), data_service: xai.tools.mcpServer({ serverUrl: https://data.example.com/mcp, serverLabel: data-service, }), }, }); for await (const part of stream) { if (part.type text-delta) { process.stdout.write(part.text); } else if (part.type source part.sourceType url) { console.log(\nSource:, part.url); } }七、视觉能力图像输入与分辨率控制Responses API 支持向视觉模型输入图片import { xai } from ai-sdk/xai; import { generateText } from ai; const { text } await generateText({ model: xai.responses(grok-4.6), messages: [ { role: user, content: [ { type: text, text: What do you see in this image? }, { type: file, mediaType: image, data: fs.readFileSync(./image.png), }, ], }, ], });可在图片 part 上通过providerOptions.xai.imageDetail控制解析分辨率low降分辨率处理、消耗更少输入 token、high全分辨率、auto由 xAI API 决定不设置时按全分辨率处理。八、语音能力语音合成与语音转写Speech文本转语音xAI 的 TTS 端点不要求模型 ID直接xai.speech()创建模型import { xai } from ai-sdk/xai; import { generateSpeech } from ai; const result await generateSpeech({ model: xai.speech(), text: Hello from the AI SDK!, voice: ara, language: en, outputFormat: mp3, speed: 1.1, });支持的参数text必填— 可内嵌 xAI 语音标签如[pause]、[laugh]、whisper.../whispervoice— 默认eve内置eve/ara/rex/sal/leo也接受自定义 voice IDlanguage— BCP-47 语言码或auto自动检测默认autospeed— 语速倍率范围0.7–1.5outputFormat—mp3/wav/pcm/mulaw/alaw默认mp3。Provider 选项providerOptions.xai类型XaiSpeechModelOptions包括sampleRate8000–48000 Hz、bitRate32000–192000仅 mp3、optimizeStreamingLatency0/1/2、textNormalization、withTimestamps返回字符级时间轴、replace发音替换映射支持重拼或 IPA 音标。结果元数据在providerMetadata.xai中traceId、duration、contentType与audioTimestamps逐字符对齐数据。Transcription语音转文本批量转写端点同样不需要模型 IDimport { xai } from ai-sdk/xai; import { transcribe } from ai; import { readFile } from fs/promises; const result await transcribe({ model: xai.transcription(), audio: await readFile(meeting.mp3), providerOptions: { xai: { language: en, format: true, keyterm: [AI SDK, Grok], diarize: true, } satisfies XaiTranscriptionModelOptions, }, });Provider 选项包括audioFormatpcm/mulaw/alaw、sampleRate、language配合format做反向文本归一化、multichannel与channels2–8 声道交错音频、diarize说话人分离、keyterm术语偏置、fillerWords是否包含uh/um等填充词以及streaming子选项供experimental_streamTranscribe走 WebSocket 流式识别interimResults中途结果、endpointing0–5000ms 静音判定、smartTurn0.0–1.0 结束检测阈值、smartTurnTimeout1–5000ms 强制结束静音上限。逐词时间戳、说话人标签与分段仅在请求/响应路径transcribe返回。九、图像生成模型通过xai.image()工厂创建图像模型配合generateImage使用import { xai } from ai-sdk/xai; import { generateImage } from ai; const { image } await generateImage({ model: xai.image(grok-imagine-image), prompt: A futuristic cityscape at sunset, });要点xAI 图像模型不支持size参数改用aspectRatio支持1:1、16:9、9:16、4:3、3:4、3:2、2:3、2:1、1:2、19.5:9、9:19.5、20:9、9:20与auto编辑能力通过prompt.images传入输入图支持Buffer/ArrayBuffer/Uint8Array/base64 字符串用文本描述变换目标不支持蒙版编辑完全由提示词驱动Provider 选项XaiImageModelOptionsresolution1k约 1024×1024 /2k约 2048×20482k仅grok-imagine-image-pro、qualitylow/medium/high。十、视频生成模型xai.video()工厂支持文生视频、图生视频、视频编辑、视频续写与参考图转视频R2V五种操作配合experimental_generateVideo使用注意视频生成是异步任务可能耗时数分钟建议将pollTimeoutMs设为至少 600000ms且生成的视频 URL 是临时的应及时下载。文生视频import { xai, type XaiVideoModelOptions } from ai-sdk/xai; import { experimental_generateVideo as generateVideo } from ai; const { video } await generateVideo({ model: xai.video(grok-imagine-video), prompt: A chicken flying into the sunset in the style of 90s anime., aspectRatio: 16:9, duration: 5, providerOptions: { xai: { user: user-123, pollTimeoutMs: 600000, // 10 minutes } satisfies XaiVideoModelOptions, }, });视频编辑与链式并发编辑mode: edit-videovideoUrl编辑现有视频输入上限 8.7 秒输出继承输入属性并被限制在 720p。xAI 托管的输出 URL 位于providerMetadata.xai.videoUrl可据此串联多次编辑或用Promise.all并发分支编辑。视频续写mode: extend-videovideoUrl从源视频最后一帧续写duration只控制续写片段的长度宽高比与分辨率继承自源视频。参考图转视频R2Vmode: reference-to-videoreferenceImageUrls1–7 张HTTPS URL 或 base64 data URI提示词中用IMAGE_1、IMAGE_2引用图片也可用 Provider 无关的顶层inputReferences选项自动进入 R2V 模式接受文件数据或{ type: url, url }。referenceVoiceIds最多传 3 个 xAI 预设语音 ID不能用自有音频用AUDIO_0/AUDIO_1/AUDIO_2在提示词中引用——该能力目前仅限美国地区可信合作伙伴。视频 Provider 选项与分辨率pollIntervalMs默认 5000/pollTimeoutMs默认 600000— 任务轮询间隔与最长等待resolution—480p/720p/1080pSDK 标准参数1920x1080/1280x720/854x480会自动映射到对应档位1080p原生支持需grok-imagine-video-1.5R2V 最高720p1080p请求会被降级并告警mode—edit-video/extend-video/reference-to-video互斥省略时走标准生成user— 终端用户标识xAI 用于滥用监控建议使用不透明稳定标识。十一、批处理、实时语音与更多工厂方法Batch实验性xai.experimental_batch()提供异步文本生成批处理能力配合 AI SDK 的 Batch API 使用同一批次内可使用不同的文本模型。注意 xAI Batch API 不支持按批次 webhook传入webhookUrl时会收到 unsupported 告警并照常启动批次。Realtime实验性xai.experimental_realtime(grok-voice-latest)创建实时语音模型。会话运行在浏览器端需先在服务端通过xai.experimental_realtime.getToken({ model: grok-voice-latest })获取短期令牌完整接入模式见 content/docs/03-ai-sdk-core 的 Realtime 章节。Filesxai.files()提供文件上传接口实现见 packages/xai/src/files。嵌入模型embeddingModel/textEmbeddingModel会抛出NoSuchModelError即当前 xAI Provider 不提供嵌入能力见 xai-provider.ts。十二、模型能力速查语言模型模型图像输入对象生成工具调用工具流式推理grok-4.6✅✅✅✅✅grok-4.5✅✅✅✅✅grok-4.20-reasoning✅✅✅✅✅grok-4.20-non-reasoning✅✅✅✅❌grok-3❌✅✅✅❌grok-3-mini❌✅✅✅✅更多模型请查阅 xAI 官方文档也可将任意可用模型 ID 以字符串传入。图像模型模型分辨率宽高比图像编辑grok-imagine-image-pro1k、2k全套 13 种 auto✅grok-imagine-image1k全套 13 种 auto✅视频模型模型时长分辨率图生视频编辑续写R2Vgrok-imagine-video1–15s480p、720p✅✅✅✅grok-imagine-video-1.51–15s480p、720p、1080p*✅✅✅✅*原生1080p适用于文生视频与图生视频R2V 上限720p。十三、进一步探索Provider 完整实现packages/xai/src/xai-provider.ts公开导出与类型packages/xai/src/index.tsChat 语言模型实现与选项校验xai-chat-language-model.ts、xai-chat-language-model-options.tsResponses 语言模型实现与选项校验packages/xai/src/responses/xai-responses-language-model.ts、xai-responses-language-model-options.ts服务端工具集合packages/xai/src/tool官方配套文档content/providers/01-ai-sdk-providers/01-xai.mdx完整测试用例含流式输出、工具调用、错误处理等快照xai-chat-language-model.test.ts、xai-responses-language-model.test.ts结合 AI SDK 的核心 APIgenerateText、streamText、generateSpeech、transcribe、generateImage、experimental_generateVideoai-sdk/xai让你能以统一接口调用 xAI 的文本、搜索、代码执行、图像、视频与语音全栈能力是构建多模态 AI 应用与自主 Agent 的实用选择。【免费下载链接】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），仅供参考