自定义集成

这一页给自己写代码接进来的场景——自研后端、内部工作流、或者要做一个我们没列出的工具适配层。

如果你只是想在项目里调接口，OpenAI SDK 那一页更直接。

先决定用哪种协议

我们支持四种入站协议，选哪个取决于你手上已有什么：

协议	端点	什么时候选
OpenAI Chat Completions	`POST /v1/chat/completions`	默认选这个。生态最全，几乎所有语言的 SDK 都支持
OpenAI Responses	`POST /v1/responses`	需要服务端联网搜索（`web_search` / `x_search`）时
Anthropic Messages	`POST /v1/messages`	你已有的代码本来就是 Anthropic 格式
Gemini 原生	`POST /v1beta/models/{model}:generateContent`	你已有的代码本来就是 Google SDK

Base URL 因协议而异，别搞混：

协议	Base URL
OpenAI	`https://api.wxiai.com/v1`
Anthropic	`https://api.wxiai.com`（不带 `/v1`）
Gemini	`https://api.wxiai.com`

详见调用方式。

图像 / 视频 / 音频还多一个选择

文本只有一种写法，但图像、视频、音频有两条路：

	路径	差异
兼容写法	`/v1/images/generations` 等	系统做参数转换 + 本地校验
原生写法	`/xai/v1/images/generations` 等	原样转发，报错是 Grok 官方原文

新写的集成建议用原生写法——Grok 加了新参数你能立刻用上，排查问题时也拿得到最原始的错误。

集成时最容易漏的四件事

1. 区分「同步」和「异步」接口

这是接进来最容易写错的地方：

类型	接口	怎么处理
同步	文本、图像、语音	发请求 → 等结果
异步	视频	提交拿 `task_id` → 轮询 → 下载

异步的任务失败或超时会自动退还额度，不需要你处理退款。

视频轮询参数见视频生成。

2. 超时按接口类型分设

不要全局一个超时值：

接口	建议超时
文本对话	60 秒
图像生成	120 秒以上
语音	120 秒
视频提交	30 秒（结果靠轮询）

3. 用 `error.code` 做判断，不要匹配文案

python

RETRYABLE = {
    "rate_limit", "too_many_requests", "overloaded",
    "upstream_error", "upstream_timeout_no_response",
}

code = ((resp.get("error") or {}).get("code"))
if code in RETRYABLE:
    ...  # 退避重试
else:
    ...  # 直接报错给用户，重试没有意义

文案会调整，code 是稳定的。 完整列表见错误码。

4. 记录 `request_id`

每个响应都带请求标识。出问题时只有带上它才能定位到具体那一次调用，比描述"昨天下午有个请求失败了"有用得多。

上线前检查清单

□ Key 从环境变量 / 配置中心读，不在代码里
□ 上游地址可通过配置切换，不硬编码在业务逻辑里
□ 区分了同步和异步接口，异步有轮询上限
□ 超时按接口类型分设
□ 只对可重试错误做退避重试，有最大次数
□ 日志里记录了 request_id
□ 长上下文场景做了截断或摘要
□ 用量有监控（在 api.wxiai.com 看消费记录）

关于 Embeddings

我们不提供 embedding 模型（Grok 官方没有）。

如果你的业务需要向量检索或 RAG，向量部分必须另找一家。你的集成设计里要把"生成"和"向量"当成两个独立的上游来配。

先决定用哪种协议 ​

图像 / 视频 / 音频还多一个选择 ​

集成时最容易漏的四件事 ​

1. 区分「同步」和「异步」接口 ​

2. 超时按接口类型分设 ​

3. 用 error.code 做判断，不要匹配文案 ​

4. 记录 request_id ​

上线前检查清单 ​

关于 Embeddings ​

相关页 ​