三个固定值

写代码前先记住这三个，其余都是变量：

Base URL:      https://api.wxiai.com/v1
Authorization: Bearer 你的APIKey
Content-Type:  application/json

模型名不固定——用 GET /v1/models 查出来的才准，见 模型列表。

端点总表

能力	方法与路径	返回方式	文档
查询可用模型	GET /v1/models	同步	模型列表 API
文本对话	POST /v1/chat/completions	同步 / SSE 流式	对话补全
响应生成	POST /v1/responses	同步 / 流式	响应生成
图像生成	POST /v1/images/generations	同步	兼容层 · 原生
图像编辑 / 图生图	POST /v1/images/edits	同步	兼容层 · 原生
视频生成	POST /v1/videos/generations	异步	兼容层 · 原生
视频编辑	POST /v1/videos/edits	异步	兼容层 · 原生
视频扩展	POST /v1/videos/extensions	异步	兼容层 · 原生
查询视频任务	GET /v1/videos/{task_id}	同步	兼容层 · 原生
下载视频内容	GET /v1/videos/{task_id}/content	文件流	兼容层 · 原生
语音合成 (TTS)	POST /v1/audio/speech	同步，返回音频	兼容层 · 原生
语音识别 (STT)	POST /v1/audio/transcriptions	同步	兼容层 · 原生
音色列表	GET /v1/tts/voices	同步	音频处理总览
流式 TTS	WSS /xai/v1/tts	长连接	音频处理总览
流式 STT	WSS /xai/v1/stt	长连接	音频处理总览
实时语音	WSS /v1/realtime	长连接	兼容层 · 原生
Anthropic 协议	POST /v1/messages	同步 / 流式	调用方式

同步 vs 异步是这里最重要的区别：文本、图像、语音发完就等结果；视频要先拿任务 ID 再轮询（原生层叫 request_id，兼容层叫 task_id）。选错了会写出永远拿不到结果的代码。

两种路径写法

上表列的是 OpenAI 兼容路径。图像、视频、音频还额外支持 Grok 原生透传路径（把 /v1/... 换成 /xai/v1/...），请求字段是同一套，但报错信息和参数支持更贴近 Grok 官方。

注意：文本类接口（/v1/chat/completions、/v1/responses）没有 /xai 版本——Grok 的文本接口本身就是 OpenAI 格式。

完整对照和选择建议见 → 调用方式

通用约定

认证：每个请求都要带 Authorization: Bearer <key>。格式细节见 认证方式。

指定模型：所有请求都用 model 字段声明调哪个模型。

流式输出：文本类接口（对话补全、响应生成）支持 stream: true，走 SSE（text/event-stream）。语音的流式走 WebSocket——WSS /xai/v1/tts 和 WSS /xai/v1/stt，不是 SSE。视频这类异步任务不支持流式。

错误格式：统一是 {"error": {"code": "...", "message": "..."}}。用 code 判断，不要用 message。完整列表见 错误码。

超时建议：

能力	建议客户端超时
文本对话	60 秒
图像生成	120 秒以上
TTS / STT	120 秒以上（长音频、大段文本会更久）
视频任务	提交 30 秒；轮询逻辑自己设总上限

推荐阅读顺序

1. 调用方式 —— 先搞清 /v1 和 /xai 的区别，少走弯路
2. 对话补全 —— 最常用，先把文本跑通
3. 按需要看 图像 / 视频 / 音频 / 实时会话
4. 出问题查 错误码