调用方式

这一页解决一个问题：同一个模型，为什么文档里有时写 /xai/...，有时写 /v1/...？我该用哪个？

两种写法

我们的接口分成两类路径，字段名用的是同一套（都按 Grok 官方写），区别只在「要不要经过中间转换」：

	原生透传（`/xai/...`）	OpenAI 兼容（`/v1/...`）
路径前缀	`https://api.wxiai.com/xai/v1/...`	`https://api.wxiai.com/v1/...`
参数怎么处理	原样转发给 Grok 官方	先转换成 Grok 格式再转发
参数校验	不校验，交给 Grok 上游	先在网关本地校验一遍
报错信息	Grok 官方原文	网关统一格式（带 `error.code`）
新参数支持	Grok 一上线就能用	要等网关适配
适合谁	想拿到 Grok 完整能力、方便排查	已有 OpenAI SDK 代码，不想改

怎么选：
优先用原生透传 —— 能力最全、报错最准，Grok 官方文档里的参数都能直接用。
用 OpenAI 兼容 —— 你手上已经有一套跑通的 OpenAI 代码，改地址就能用，不想动逻辑。

先记住：只有一部分能力有「两种写法」

很多人以为所有接口都能加 /xai 前缀——不是的。得分两类看。

只有一种写法：文本相关

能力	端点
文本对话	`POST /v1/chat/completions`
响应生成	`POST /v1/responses`

这两个没有 /xai 版本，加上前缀不是有效地址，请求会失败。

为什么：Grok 的文本接口本身就是 OpenAI 格式。xAI 官方的 /v1/chat/completions 和 OpenAI 的完全一致，所以对我们来说这就是同一条路——不存在"转换"，也就谈不上"原生"和"兼容"之分。

只有图像、视频、音频这些能力，Grok 官方的请求格式和 OpenAI 标准不一样，才需要区分两条路径。

有两种写法：图像、视频、音频

能力	原生透传	OpenAI 兼容
图像生成 / 编辑	`/xai/v1/images/generations`、`/xai/v1/images/edits`	`/v1/images/generations`、`/v1/images/edits`
视频生成 / 编辑 / 扩展	`/xai/v1/videos/generations`、`/edits`、`/extensions`	`/v1/videos/generations`、`/edits`、`/extensions`
视频任务查询	`GET /xai/v1/videos/{request_id}`	`GET /v1/videos/{task_id}`
语音合成 (TTS)	`/xai/v1/tts`	`/v1/audio/speech`
音色列表	`GET /xai/v1/tts/voices`	同左（无兼容写法）
语音识别 (STT)	`/xai/v1/stt`	`/v1/audio/transcriptions`
流式 TTS / STT	`WSS /xai/v1/tts`、`WSS /xai/v1/stt`	同左（无兼容写法）
实时语音	`WSS /xai/v1/realtime`	`WSS /v1/realtime`

请求字段两边是同一套，区别只在前面那张表里的处理方式（是否转换、是否本地校验、报错从哪来）。

兼容层会额外容忍几个 OpenAI 的叫法（例如图像的 size、视频的 seconds），这只是便利，官方文档里没有这些字段。

四种入站协议（按你手上的 SDK 选）

除了上面两种"路径写法"，同一个 API Key 还支持按不同厂商的协议格式发请求。选哪个取决于你用什么工具：

协议	端点	什么时候用
OpenAI Chat Completions	`POST /v1/chat/completions`	最通用。OpenAI 官方 SDK、绝大多数客户端都认这个
OpenAI Responses	`POST /v1/responses`	需要服务端联网搜索等 Responses 专有能力时
Anthropic Messages	`POST /v1/messages`	Claude Code 等只认 Anthropic 协议的工具
Gemini 原生	`POST /v1beta/models/{model}:generateContent`	使用 Google SDK 的项目

Base URL 怎么填（这个经常填错）：

协议	Base URL	注意
OpenAI	`https://api.wxiai.com/v1`	要带 `/v1`
Anthropic	`https://api.wxiai.com`	不要带 `/v1`，否则会拼成 `/v1/v1/messages` 报 404
Gemini	`https://api.wxiai.com`	路径里自带 `/v1beta`

bash

# Anthropic 协议示例（Claude Code 就是走这条）
curl https://api.wxiai.com/v1/messages \
  -H "x-api-key: 你的APIKey" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'

认证头可以混用

/v1/messages 同时接受两种认证方式：

方式	写法
Anthropic 风格	`x-api-key: sk-你的APIKey`
通用方式	`Authorization: Bearer sk-你的APIKey`

哪个方便用哪个，效果一样。Claude Code 用的是前者，所以直接照抄它的配置也能通。

Gemini 协议的认证更宽松，三种任选：

方式	写法
URL 参数	`?key=sk-你的APIKey`
Google 风格请求头	`x-goog-api-key: sk-你的APIKey`
通用方式	`Authorization: Bearer sk-你的APIKey`

一句话总结

文本           →  /v1/chat/completions（只有这一种）
图像 / 视频    →  /xai/v1/... 优先，/v1/... 备选
音频 / 实时    →  /xai/v1/... 优先，/v1/... 备选
Claude 系工具  →  /v1/messages，Base URL 不带 /v1

下一步

对话补全 —— 文本接口完整参数
图像生成 —— 同步接口
视频生成 —— 异步任务与轮询

两种写法 ​

先记住：只有一部分能力有「两种写法」 ​

只有一种写法：文本相关 ​

有两种写法：图像、视频、音频 ​

四种入站协议（按你手上的 SDK 选） ​

一句话总结 ​

下一步 ​