Vercel AI SDK xAI 5.0.39 更新：实时语音与视频上传落地

Vercel 旗下的 AI SDK 生态中，面向 xAI 的 provider 包 @ai-sdk/xai 发布了 5.0.39 补丁版本。版本号只跳了最后一位，但补丁内容涉及实时语音、转录时间戳和视频生成输出三个方向，对正在用 AI SDK 接入 Grok 系能力的开发者而言，属于需要关注的一次底层能力补齐。

实时语音：从模型封装走向服务端 WebSocket

本次更新中最具结构性的一项，是 XaiRealtimeModel 实现了 getServerWebSocketConfig()。这个方法返回的是上游 voice realtime 的 WebSocket URL，并在 URL 中带上 model 查询参数，同时附上由模型已配置凭据派生出的请求头鉴权信息。

这一改动的意义在于把实时语音的连接配置收敛到 provider 层。过去开发者往往需要自己拼 WebSocket 地址、自己注入鉴权头，一旦上游地址或参数形态变化就得跟着改业务代码。现在这些细节由 model 对象统一承载，调用方拿到的是一份可直接使用的连接配置。对于不支持的 endpoint intent，实现会直接拒绝，而不是发出一个注定失败的请求，这类前置校验能减少线上排障成本。

事件映射层也同步做了调整。事件映射器现在会在 response-done 和 input-transcription-completed 这两类事件上填充归一化的 usage 字段，所用的线格式与 xAI 的 OpenAI 兼容 realtime 结构保持一致。这意味着用量统计可以和其他 OpenAI 兼容 provider 走同一条处理链路，而不必为 xAI 单独写一套解析逻辑。

AI SDK 中的 realtime（实时）模型抽象，目的是把“流式双向语音会话”从普通的一次性请求响应模型中分离出来。传统补全模型的交互是单次请求对应单次响应，而 realtime 会话需要在客户端与服务端之间维持一条长连接，双向持续推送音频帧和事件（如用户开始说话、模型开始响应、响应结束等）。WebSocket 正是承载这种长连接的标准协议。provider 层实现 getServerWebSocketConfig() 的约定，是把“连接到哪里、用什么凭据”这一职责从业务代码上移到模型对象，使不同 provider 的 realtime 接入方式在 SDK 内部保持一致的调用形态。这与 AI SDK 中 provider 抽象层的一贯设计思路一致：模型对象负责协议细节，调用方只面向统一接口。

文中提到的“归一化 usage 字段”，指的是把各 provider 返回的用量信息（token 数、音频时长等）映射为 AI SDK 内部统一的结构。xAI 的 realtime 接口采用了与 OpenAI 兼容的线格式（wire format），因此 SDK 可以直接复用已有的解析路径，而不必为 xAI 单独实现一套。这种“OpenAI 兼容层”在实时语音领域较为常见，多家的 voice API 在事件命名和字段结构上刻意向 OpenAI 靠拢，从而降低生态迁移成本。对开发者而言，归一化后的 usage 可以直接进入计费和可观测性管道，无需按 provider 分支处理。

转录时间戳与视频上传：细节处的可用性提升

转录方面，本次改动把可选的单词级时间戳从 segment 中单独暴露出来，并接受共享的 timestampGranularities 参数。显式设置的 provider timing 配置优先级更高。OpenAI 一侧则改为只在 verbose_json 模式下发送 timestamp_granularities，当请求的时间粒度不可用或被排除时给出警告，而不是静默失败。

视频方向支持了带类型的 output.uploadUrl 投递方式，覆盖视频生成、编辑和扩展三类操作。轮询会返回一个明确的 uploaded 结果，既不会下载文件，也不会把签名后的目标地址暴露出来，在请求错误中也保持这一策略。新选项使用驼峰写法的 output.uploadUrl，替代原先直接透传的 output.upload_url，并且会拒绝 null 值、要求必须是 HTTPS URL。

从工程角度看，这两项都属于「减少意外」的改动：时间戳的可得性有明确提示，上传目标的地址不泄露给调用方，参数命名从透传走向受控。

timestampGranularities 是转录接口中控制时间戳精度的参数，常见取值包括 segment（按句段）和 word（按单词）。不同粒度的输出体积和用途差别很大：句段级时间戳适合做字幕分段和内容索引，词级时间戳则用于精确对齐、卡拉 OK 式高亮或逐词检索。历史上这类参数在 OpenAI 兼容实现中存在差异——部分端点只在 verbose_json 响应模式下才接受该参数，传入不支持的粒度时也可能静默忽略。本次改动把显式配置的 provider 优先级提上来，并在粒度不可用或排除时给出警告，本质上是把“参数是否生效”从隐式行为变成可观测行为，便于排查字幕错位一类的问题。

依赖同步与升级建议

该版本同时更新了多项依赖，其中可以确认的包括 @ai-sdk/provider@4.0.36 与 @ai-sdk/provider-utils@5.0.75。这类联动更新通常意味着 provider 抽象层有小幅演进，升级时应一并检查项目中直接引用这两个包的位置。

如果你的项目已经在用 AI SDK 对接 xAI 的实时语音或视频生成能力，这个补丁版本值得跟进；如果只是使用纯文本补全，升级的实际影响相对有限，但依赖版本对齐仍然推荐。

@ai-sdk/provider 是 AI SDK 定义模型接口契约的核心包，@ai-sdk/provider-utils 则提供各 provider 共用的辅助工具（如请求构造、流解析、schema 校验）。具体 provider 包（如 @ai-sdk/xai）依赖这两者来保证与其他 provider 行为一致。当它们的小版本号发生变动时，通常意味着接口契约或工具行为有微调，可能影响直接引用这些包的自定义 provider 实现。因此升级 provider 包时，建议核对 lockfile 中这两个包的解析版本，避免出现同一项目内多份不兼容副本共存的情况。