Grok API：在代码中调用 Grok

在代码中调用 Grok 的两种方式

开发者主要可以通过两种途径调用 Grok 模型。第一种是 xAI API，由官方直接运营（现品牌名为 SpaceXSI），可在 console.x.ai 获取密钥。第二种是类似 OpenRouter 的模型聚合平台，只需一个密钥和一份账单即可调用多家厂商的模型。两者均兼容 OpenAI Chat Completions 请求格式，因此只需修改基础接口地址（base URL）和模型名称，即可直接使用官方 OpenAI SDK。

该如何选择

• xAI API：如果你想第一时间体验 Grok 的所有功能，请选此项。支持全系模型、Responses API、服务端联网搜索与 X 搜索工具、基于 Grok Imagine 的图像与视频生成、语音、批处理任务以及提示词缓存折扣。基础 URL 为 https://api.x.ai/v1。
• OpenRouter：如果你希望在 Grok 与其他厂商的模型之间灵活切换且无需单独签约，或者你已拥有 OpenRouter 账户，请选此项。基础 URL 为 https://openrouter.ai/api/v1，模型 ID 需带有 x-ai/ 前缀。配置详情请参阅 OpenRouter 快速上手指南。

无论选择哪种方式，都请务必将密钥保存在服务器端或环境变量中。切勿打包到任何人都能查看的前端网页或移动应用中。

向 xAI API 发送你的首次请求

在控制台生成密钥并保存为环境变量 XAI_API_KEY，然后向 Grok 4.7 发送一条消息：

curl

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "reasoning_effort": "low",
    "messages": [
      {"role": "system", "content": "你是一位简明扼要的助手。"},
      {"role": "user", "content": "请为初次跑马拉松的人提供三条建议。"}
    ]
  }'

Python（搭配 OpenAI 库）

import os
from openai import OpenAI

grok = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

answer = grok.chat.completions.create(
    model="grok-4.3",
    reasoning_effort="medium",
    messages=[{"role": "user", "content": "391 是质数吗？请写出验证过程。"}],
)
print(answer.choices[0].message.content)

reasoning_effort 参数用于控制模型在回复前的思考深度。Grok 4.3 支持 none、low、medium、high 和 xhigh，默认为 low；Grok 4.7 支持 low、medium、high 和 xhigh，默认为 high。针对 Grok 4.20，xAI 提供了不同的模型 ID：grok-4.20-0309-reasoning 与 grok-4.20-0309-non-reasoning。

通过 OpenRouter 调用

在 OpenRouter 上，将密钥存入 OPENROUTER_API_KEY 并使用带 x-ai/ 前缀的模型 ID。OpenRouter 改用 reasoning 对象来控制思考过程。以下 JavaScript 代码适用于 Node.js 18 或更高版本：

const endpoint = "https://openrouter.ai/api/v1/chat/completions";

const reply = await fetch(endpoint, {
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({
    model: "x-ai/grok-4.20",
    reasoning: { enabled: false },
    stream: false,
    messages: [{ role: "user", content: "用更平稳缓和的语气重写这条新闻标题：物价再次暴涨！" }],
  }),
});
const json = await reply.json();
console.log(json.choices[0].message.content);

如需开启思考模式，可传入 reasoning: { effort: "low" }（或 medium、high）。如果希望模型进行思考但在最终回复中不返回思考过程，可添加 exclude: true。将 stream: true 设为流式传输，即可实时接收生成的文字，在聊天界面中的响应体验会大幅提升。

发送图像

Grok 4.20、4.3 和 4.7 均支持图像识别。请求时使用 OpenAI 风格的多模态消息格式即可。xAI 文档指出支持不超过 20 MiB 的 JPEG 和 PNG 格式图片；公开图片链接或 Base64 Data URL 均可使用。

{
  "model": "grok-4.20-0309-non-reasoning",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/receipt.png"}},
      {"type": "text", "text": "列出这张小票上的所有商品及总金额。"}
    ]
  }]
}

Grok 模型 ID 与定价

以下为 OpenRouter 平台收录的 SpaceXAI 文本模型列表，包含上下文窗口大小及每百万 Token 的价格（OpenRouter 官方标价，2026 年 10 月）。对于 20 万 Token 以内的提示词，xAI API 收费基准与此一致。

根据 xAI 模型与定价页面补充说明（xAI 官方标价，2026 年 10 月）：

• 超长提示词费用更高：当提示词达到 20 万 Token 时，整个请求将按更高费率计费：Grok 4.7 为 $4 / $12，Grok 4.3 和 4.20 为 $2.50 / $5。
• 提示词缓存优惠：对于重复使用的前缀，命中缓存的输入 Token 价格更低：Grok 4.7 为 $0.50 / 百万，Grok 4.3 和 4.20 为 $0.20 / 百万。
• 批处理任务：对时效性要求不高的批量任务可享受折扣，OpenRouter 同样提供了 x-ai/grok-4.3:batch，价格为 $1 / $2。
• 不同平台标明的上下文长度可能略有出入：OpenRouter 标注 Grok 4.20 为 2,000,000 Tokens，而 xAI 官方模型页面标注为 1,000,000 Tokens。

思考过程产生的 Token 按输出 Token 计费，因此具备推理能力的模型单次回答的实际花费，可能会高于单纯的单价估算。

实用技巧

• 日常任务优先使用 Grok 4.20 non-reasoning：对于对话、文本改写和信息提取，该模型兼顾速度与性价比。若处理对推理质量要求极高的复杂任务，再升级至 Grok 4.3 或 4.7。
• 留意知识库截止时间：根据 xAI 数据，Grok 4.7 的知识库更新至 2026 年 5 月。如需处理最新信息，请直接在提示词中提供背景事实，或调用 xAI 的服务端网页与 X 搜索工具（按次计费）。
• 善用 System Prompt：设定明确的角色身份、语气及输出格式。如果代码需要解析回答，可要求模型按特定 Schema 输出 JSON。
• 妥善处理频率限制（Rate Limits）：当收到 429 响应时，应设置合理的延迟重试机制。
• 遵守使用规范：调用 API 必须遵循 xAI 的合规政策，并可通过 safety_identifier 字段按终端用户对请求进行标记追踪。

排错指南

• 401 或 403 错误：密钥缺失、已失效或加载到了错误的环境中。可在服务端打印密钥前几位字符以核查是否正确读取。
• Model not found（模型不存在）：检查模型前缀。OpenRouter 要求使用 x-ai/grok-4.7，而 xAI 官方应直接使用 grok-4.7。
• 回复为空或生成极慢：推理模型通常是因为将输出预算耗尽在思考阶段。可尝试调低思考强度（effort）或调大 max_tokens。
• 图片上传失败被拒：请将图片转为 JPEG 或 PNG 格式，并确保文件大小未超过上限。

常见问题

Grok API 兼容 OpenAI SDK 吗？

完全兼容。只需将 SDK 的基础地址指向 https://api.x.ai/v1 并填入 xAI 密钥，或者指向 OpenRouter 并填入 OpenRouter 密钥，同时配置对应的 Grok 模型 ID 即可。

Grok API 有免费额度吗？

官方没有提供永久免费层。xAI 和 OpenRouter 均按 Token 计费，不过小规模测试的花费非常低。

可以通过 Grok API 生成图片吗？

可以，通过 xAI 的 Grok Imagine 模型调用独立的图片生成接口即可。详情请参阅我们的 Grok Imagine 页面。我们的在线聊天界面不支持图片生成。

Grok.Online 目前使用的是哪个 Grok 模型？

我们的在线聊天由 OpenRouter 提供支持，包含关闭思考模式的 Grok 4.20、低思考强度的 Grok 4.3，以及每天最多可发送 10 条消息的 Grok 4.7。