xAI Grok API 集成指南：模型、定价与接入实战（2026）

xAI 的 Grok API 让你通过 OpenAI 兼容协议访问当前最强的推理模型之一——从 Grok 4.3 的百万 token 上下文到 Grok 3 Mini 每百万输入 token 仅 $0.30。如果你已经在用 OpenAI SDK，接入 xAI 只需改两行代码：base_url 换成 xAI 的端点，model 换成 Grok 的模型名。

我们在生产环境通过 xAI 端点路由了真实流量，测试了他们全系模型。这份指南涵盖完整的模型家族、截至 2026 年 6 月的定价、可用代码示例、我们踩过的常见错误，以及如何将 xAI 接入多供应商路由架构。

快速开始：3 分钟接入 xAI API

第一步——获取 API 密钥。 在 console.x.ai 注册。xAI 曾通过数据共享计划为开发者提供每月最高 $150 的免费额度（请在控制台确认当前是否可用）。在 Settings → API Keys 中生成密钥。

第二步——安装 OpenAI SDK（如果还没有的话）：

pip install openai

第三步——发起第一次调用：

from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="your-xai-api-key",
)

response = client.chat.completions.create(
    model="grok-4.3",
    messages=[{"role": "user", "content": "用一段话解释量子计算。"}],
)
print(response.choices[0].message.content)

就这些。xAI 的 API 完全兼容 OpenAI——工具调用、结构化输出、流式传输和视觉能力全部通过同一个 SDK 可用。不需要 xAI 专用的客户端库。

Grok 模型家族

xAI 截至 2026 年 6 月的 API 模型阵容跨越五个定价层级：

价格来源：docs.x.ai/developers/models，2026 年 6 月获取。

关键定价洞察： Grok 4.3 的输入价格比原版 Grok 4 低 58%，输出价格低 83%。缓存输入价格（$0.20/M）享受 84% 折扣——对于系统提示词在多次请求中保持不变的智能体循环来说非常有价值。

Grok 4.3——默认首选

Grok 4.3 是 xAI 当前的旗舰模型，于 2026 年 4 月 30 日发布。它默认开启链式推理（无需手动切换），支持原生视频输入（mp4/mov/webm，最长 5 分钟，1080p），以及原生文档生成（PDF、PowerPoint、电子表格）。xAI 官方文档推荐将其用于所有聊天和编码场景。

一个重要的别名细节：在 xAI 侧，grok-4、grok-4-latest、grok-4-0709、grok-3、grok-3-mini 等别名目前全部解析为 Grok 4.3。如果需要原始 Grok 4 的行为，必须使用固定的 grok-4-0709 快照标识。

Grok 4.20 变体——需要细粒度控制时

三个 Grok 4.20 变体让你显式选择推理行为：

• grok-4.20-0309-reasoning — 开启链式思维，适合数学和多步逻辑
• grok-4.20-0309-non-reasoning — 标准补全，更低延迟
• grok-4.20-multi-agent-0309 — 2M 上下文，面向多智能体编排

三者定价相同（$1.25/$2.50/M）。根据延迟预算选择推理或非推理版本。

Grok 4.1 Fast——性价比之王

每百万 token $0.20/$0.50，2M 上下文窗口——Grok 4.1 Fast 以约 Grok 4 的 1/15 价格提供了接近旗舰的品质。对于大多数聊天机器人、RAG 和编码智能体工作负载，这才是正确的默认选择。缓存输入价格 $0.05/M 在规模化使用下几乎等于免费。

遗留模型（Grok 4、Grok 3、Grok 3 Mini）

Grok 4 和 Grok 3 定价 $3.00/$15.00/M——比新模型贵得多但没有质量优势。Grok 4.1 Fast 在大多数基准上已超越 Grok 3，而价格仅为一小部分。

例外是 Grok 3 Mini（$0.30/$0.50/M）——对于尚未迁移的现有集成，它仍然可用于低成本推理任务。

⚠️ Grok 4、Grok 3、Grok 3 Mini 和 Grok 4.1 Fast 可能不会出现在 xAI 当前的公开定价页面上。它们可能是遗留或企业专属模型。在基于这些模型构建前，请在 xAI 控制台 确认可用性。

按场景的代码示例

聊天补全

from openai import OpenAI

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key="your-xai-api-key",
)

# Grok 4.3 — 当前旗舰
response = client.chat.completions.create(
    model="grok-4.3",
    messages=[
        {"role": "system", "content": "你是一位资深后端工程师。"},
        {"role": "user", "content": "设计一个分布式 API 网关的限流器。"},
    ],
)
print(response.choices[0].message.content)

视觉（图像 + 文本）

response = client.chat.completions.create(
    model="grok-4.3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://example.com/architecture.png"}},
            {"type": "text", "text": "描述该架构并识别潜在瓶颈。"},
        ],
    }],
)

图像约束： 单图最大 20 MiB，仅支持 jpg/jpeg 或 png。每请求无图像数量限制。文本和图像输入顺序任意。

函数调用（工具使用）

response = client.chat.completions.create(
    model="grok-4.3",
    messages=[{"role": "user", "content": "东京今天天气怎么样？"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定位置的当前天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "城市名"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
        },
    }],
    tool_choice="auto",
)

结构化输出（JSON 模式）

import json

response = client.chat.completions.create(
    model="grok-4.3",
    messages=[{"role": "user", "content": "列出 3 种编程语言及其创建年份。"}],
    response_format={"type": "json_object"},
)
data = json.loads(response.choices[0].message.content)

流式传输

stream = client.chat.completions.create(
    model="grok-4.3",
    messages=[{"role": "user", "content": "写一首关于 API 的俳句。"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

如何选择合适的 Grok 模型

速率限制

所有 xAI API 模型共享相同的速率限制：

• 每分钟 1,800 次请求
• 每分钟 10,000,000 token

对大多数工作负载来说足够宽裕。如需更高限制，请联系 xAI 企业团队。

常见错误与解决方法

1. 迁移后报 "Model not found"

问题： 之前用 grok-4 突然返回 Grok 4.3 而非原始模型。

原因： xAI 已合并遗留别名。grok-4、grok-4-latest、grok-3、grok-3-mini 等在 xAI 侧自 2026 年 5 月起均解析为 Grok 4.3。

解决： 使用固定快照 grok-4-0709 保证 Grok 4 行为稳定，或明确使用 grok-4.3 获取当前旗舰。

2. 图像上传失败

问题： 发送图像时返回 400 错误。

原因： xAI 仅接受 jpg/jpeg 和 png 格式。单图最大 20 MiB。

解决： 在上传前将其他格式（webp、gif、bmp）转换为 png。压缩超过 20 MiB 的图像。

3. logprobs 返回 null

问题： 设置了 logprobs 和 top_logprobs 但没有返回逐 token 概率。

原因： Grok 4.20 及更新模型（包括 4.3）静默忽略 logprobs 和 top_logprobs。API 接受参数但不报错，也不返回数据。

解决： 如果需要 logprobs，请使用其他供应商的模型。

4. 缺少实时信息

问题： Grok 不知道最近的事件。

原因： Grok 3 和 Grok 4 的知识截止日期为 2024 年 11 月。Grok 4.3 的截止日期未公开披露，但同样没有内置实时知识。

解决： 按请求启用 xAI 的服务端 web 搜索或 X（Twitter）搜索工具。注意： 这些是 xAI 原生工具，不会通过代理或路由服务转发——如需实时信息请直接调用 xAI API。

5. 别名解析异常

问题： 代码使用 grok-3-mini 但得到 Grok 4.3 品质的响应（以及 Grok 4.3 的定价）。

原因： 别名合并。你使用的标识解析到了与预期不同的模型。

解决： 审计你的模型标识。查看 xAI 模型文档 了解当前别名映射。使用日期固定标识（如 grok-4-0709）以获得可重现的行为。

生产环境检查清单

部署 xAI 前请确认：

• 固定模型标识。 使用日期固定标识（grok-4-0709）或明确版本标识（grok-4.3），而非浮动别名（grok-4、grok-latest）
• 设置超时。 Grok 4.3 默认开启推理，首 token 延迟较高（社区基准实测约 11.6 秒）。请据此设置客户端超时
• 处理速率限制。 对 429 响应实现指数退避。限制：每分钟 1,800 请求、每分钟 10M token
• 积极缓存。 缓存输入价格（$0.20/M vs $1.25/M）享受 84% 折扣。将稳定的系统提示词作为缓存上下文发送
• 按模型监控成本。 Grok 4.3 的 $1.25/$2.50/M 价格合理；遗留 Grok 4 的 $3.00/$15.00/M 就不便宜了。确保路由逻辑选择正确的模型
• 校验图像输入。 在发送到 API 前强制检查 jpg/png 格式和 20 MiB 限制
• 不要依赖 logprobs。 Grok 4.20+ 模型会静默忽略
• 单独测试流式传输。 推理和非推理变体的流式行为可能不同
• 规划别名漂移。 xAI 历史上会在不通知的情况下合并别名。构建监控机制以检测意外的模型行为变化

通过 TheRouter 路由 xAI

如果你管理多个 AI 供应商，通过 TheRouter 路由 xAI 可以获得统一的 OpenAI 兼容端点、自动故障转移、用量追踪和成本控制。

通过 TheRouter 路由到 xAI，使用供应商前缀模型标识：

from openai import OpenAI

client = OpenAI(
    base_url="https://api.therouter.ai/v1",
    api_key="your-therouter-api-key",
)

# 通过 TheRouter 路由到 xAI Grok 4.3
response = client.chat.completions.create(
    model="xai/grok-4.3",
    messages=[{"role": "user", "content": "用具体例子解释 CAP 定理。"}],
)

# 切换到不同供应商——同样的 SDK，同样的代码
response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4",
    messages=[{"role": "user", "content": "用具体例子解释 CAP 定理。"}],
)

TheRouter 的 xAI 供应商页面 列出了所有可用的模型标识及其当前路由目标。TheRouter 上的每个模型映射到特定的 xAI API 标识——例如，xai/grok-4 固定到 grok-4-0709 快照以保证稳定性，而 xai/grok-4.3 跟踪 xAI 的当前世代。

TheRouter 为 xAI 用户带来的价值：

• 统一计费 — 跨 xAI 和其他供应商的同一张账单
• 自动故障转移 — xAI 宕机时路由到其他供应商的等价模型
• 团队治理 — 每个团队成员的 API 密钥、配额和审计日志
• 供应商前缀模型 ID — 代码不会硬编码单一供应商端点

聊天之外：语音、图像和视频 API

xAI 还提供聊天补全之外的专用 API：

这些专用 API 与 chat/completions 路径分离，不通过 TheRouter 的标准路由暴露。图像、视频和语音工作负载请直接使用 xAI API。

常见问题

问：xAI 的 API 真的兼容 OpenAI 吗？

是的——/v1/chat/completions 端点、工具调用、结构化输出、流式传输和视觉能力全部遵循 OpenAI API 规范。已知差异：logprobs 和 top_logprobs 在 Grok 4.20 及更新模型上被静默忽略。

问：Grok 4.3 和 Grok 4.20 有什么区别？

Grok 4.3（2026 年 4 月）是当前旗舰，默认推理、原生视频输入和文档生成。Grok 4.20（2026 年 2 月）提供三个变体（推理、非推理、多智能体），可显式控制推理行为。两者定价相同（$1.25/$2.50/M）。新项目从 Grok 4.3 开始，除非你需要非推理变体的低延迟或多智能体变体的 2M 上下文。

问：能在 Grok 4.3 中关闭推理吗？

不能。链式推理在 Grok 4.3 中始终开启，无法通过 API 禁用。如果需要非推理行为，请改用 grok-4.20-non-reasoning。权衡是：Grok 4.3 的首 token 延迟约 11.6 秒（社区基准实测），而非推理模型更低。

问：xAI 提供免费 API 额度吗？

xAI 曾通过数据共享计划提供每月最高 $150 的免费额度。请在 xAI 控制台 确认当前可用性——该计划经历过变动。

问：xAI 和 OpenAI、Anthropic 相比如何？

xAI 的 Grok 4.3 定价 $1.25/$2.50/M——在输出 token 上显著低于 OpenAI 的 GPT-5.5 或 Anthropic 的 Claude Opus 4.7。在 Artificial Analysis 智能指数上，Grok 4.3 得分 53（GPT-5.5 为 60，Gemini 3.1 Pro Preview 为 57）。xAI 的亮点在智能体工具调用和长周期多步任务，社区评测发现其与价格高 9 倍的模型具有竞争力。

问：xAI 服务哪些区域？

xAI API 可用区域为 us-east-1、eu-west-1 和 us-west-2。如果需要从亚洲低延迟访问，可考虑通过 TheRouter 路由来优化区域路由。

---

来源：xAI 模型文档（2026 年 6 月获取）、xAI Grok 4.3 模型文档、xAI 发布说明。定价经 xAI 公开文档验证，并与 mem0.ai 定价分析（2026 年 5 月）交叉核对。基准数据来自 Artificial Analysis 和社区评测。