Grok API 接入教程：Base URL、模型名与第一次调用（2026）

Grok API 的接入难点通常不在写请求，而在三件事：Key 与地址是否配套、端点该用哪个、模型名从哪里复制。把这三件事做对，第一次调用几分钟就能跑通；做错，最常见的表现就是 401、404 或 model not found。

本文以 xAI 官方文档为准，按账号与 Key、Base URL、模型名、curl、Python、流式与函数调用、错误排查、迁移清单的顺序走一遍。价格与可用模型会调整，接入前请核对 xAI 官方 Models 页面和站内模型价格。

说明：xAI、Grok 是其权利人的商标，OpenAI 是其权利人的商标，本文仅作技术接入说明。

一、先选路径：官方控制台还是兼容网关

Grok API 的 Key 有两个常见来源：xAI 官方控制台，以及提供 OpenAI 兼容入口的国内网关。两条路径的请求格式接近，但账号、付款和 Base URL 不同，Key 不能混用。

对比项	xAI 官方	中商起航 AI 网关
控制台	console.x.ai	ai.zhongshangqihang.com
Base URL	`https://api.x.ai/v1`	`https://ai.zhongshangqihang.com/v1`
付款	按官方支持的方式	人民币充值，具体以站内为准
适合	有稳定访问与海外付款方式	国内访问、统一账单、多模型切换

先选路径，再创建 Key。把官方 Key 填到网关地址，或反过来，通常会得到 401。网关的注册入口在这里，是否需要网关取决于你的网络、付款和发票要求。

二、创建 Key 的六个步骤

注册并登录控制台。官方路径是 console.x.ai；网关路径从注册页进入。
完成账单设置或充值。没有可用额度时，Key 可能创建成功但调用失败。
进入 API Keys 页面，新建 Key，名称写清项目和运行环境，例如 prod-qa-2026-10。
立即复制完整 Key，存入服务端环境变量或密钥管理服务。多数控制台只在创建时显示一次。
按最小权限设置额度、IP 或团队权限；控制台没有的选项不必强求。
用一条最小请求验证 Key、Base URL 和模型名三项是否匹配。

不要把 Key 写进前端代码、Git 仓库或聊天记录。测试和生产分开建 Key，轮换时才不会影响全部业务。

三、Base URL 与端点：只写到 /v1

官方 Base URL 是 https://api.x.ai/v1。注意两点：Base URL 只写到 /v1，不要自己拼 /chat/completions；具体端点由 SDK 或请求路径决定。

目前官方推荐 POST /v1/responses（Responses API），OpenAI 兼容的 POST /v1/chat/completions 仍可用，但官方已将其标注为 legacy，新功能优先进入 Responses API。新项目建议直接用 Responses API；已有 OpenAI Chat Completions 代码可以继续跑，但要接受它不再是主路线。

最小 curl 请求如下，鉴权统一使用 Authorization: Bearer：

export XAI_API_KEY="你的密钥"

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "用三句话解释什么是 API 网关。",
    "store": false
  }'

store 控制是否在服务端保存请求与响应。官方文档说明 Responses 默认保存 30 天；处理敏感内容时，建议明确设置 store: false，并确认关闭后无法使用 previous_response_id 续接对话。

四、模型名怎么填：复制 ID，不要猜

模型名是 API 的标识符，不是产品页上的宣传名。官方 Models 页面会列出当前可用的 ID、上下文长度和计费档位。以下是 2026 年 10 月文档中的几个例子，仅作格式说明：

模型 ID	上下文	常见用途
`grok-4.7`	500k	通用问答、编码、Agent
`grok-4.3`	1M	长文档、长对话
`grok-4.20-0309-reasoning`	1M	需要显式推理的任务
`grok-build-0.1`	256k	编码与构建类工作流

模型会上下架，名称也会带日期后缀。上线前从官方 Models 页面或站内模型价格复制，不要凭记忆手写。带 -reasoning 的模型通常输出推理过程，延迟和费用结构与普通模型不同，先用小流量验证。

五、Python 第一次调用

官方提供 xAI SDK，也支持 OpenAI SDK。已有 OpenAI 代码的团队，改 base_url 和 api_key 即可先跑通：

import os
from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.7",
    input="用三句话解释什么是 API 网关。",
    store=False,
)

print(response.output_text)

output_text 是 SDK 提供的便捷属性，适合纯文本结果。需要读取推理、工具调用或引用时，遍历 response.output 并按 type 判断，不要假设文本永远在固定下标。

六、流式输出与函数调用

流式输出使用 SSE：请求里设置 "stream": true，客户端逐块读取增量。官方文档提醒，推理模型的生成时间可能较长，使用流式时要把客户端超时调大，避免连接被提前关闭。下面是 OpenAI SDK 调用兼容端点的写法：

stream = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": "用三句话解释 SSE。"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

函数调用分五步：定义工具的名称、描述和 JSON Schema；把工具放进请求；模型返回 function_call；你在本地执行函数；把结果交回模型继续生成。Responses API 的工具定义是扁平结构，核心字段为 type: "function"、name、description 和 parameters。

两个容易忽略的细节：流式模式下，函数调用参数可能整块返回，而不是逐字流式；搜索类服务端工具可能按调用量单独计费，具体以官方价格页为准。工具越多、描述越模糊，模型误选工具的概率越高，先把工具数量和参数收紧。

七、常见错误：先看状态码

状态码	常见原因	处理
401	没带 Key、Key 错误，或 Key 与 Base URL 不匹配	检查 `Authorization` 头和地址是否配套
403	账号或 Key 无权限，或受地区与条款限制	查控制台权限与账号状态
404	路径写错、模型名不存在	核对 `/v1/responses` 与模型 ID
400 / 422	请求体字段格式错误	对照 API Reference 检查字段
429	请求频率或并发超过限制	指数退避重试，降低并发
超时	推理模型生成时间长、网络链路慢	调大超时，改用流式，记录耗时

余额不足有时不会以 429 表现，具体错误码和提示以控制台与官方文档为准。排查顺序建议是：先看状态码，再看错误消息，最后才改提示词。提示词改得再好，也修不好一个错误的 Base URL。

八、上线前的迁移清单

把 Key 放进服务端环境变量，确认不会进入前端包和日志。
固定 Base URL，禁止在业务代码里手拼端点。
建立模型名映射表，记录旧模型、新模型、上下文和计费档位。
新项目用 /v1/responses；旧项目若继续用 Chat Completions，标注为 legacy 并排期迁移。
统一流式与非流式的超时、重试和取消逻辑。
为 429 和 5xx 设置指数退避，不要无上限重试。
记录请求 ID、模型、Token 用量和延迟，方便对账与排障。
先灰度一个非核心功能，观察一周再放量。

常见问题

Grok API 的 Base URL 到底填什么？

官方是 https://api.x.ai/v1，网关以其控制台给出的地址为准。只写到 /v1，不要带具体端点。

为什么 OpenAI SDK 能调用 Grok？

xAI 提供 OpenAI 兼容的请求结构，尤其是 Chat Completions；Responses API 也可通过 OpenAI SDK 的 responses.create 调用。把 base_url 指向 xAI 即可，但模型名和部分参数仍要按 xAI 文档来。

Grok API 和 OpenAI API 是一回事吗？

不是。两者是不同公司的服务，只是接口形状兼容。Key、计费、模型和数据处理政策都不同，不能混用。

一定要用 Responses API 吗？

新项目建议用。官方已把 Chat Completions 标为 legacy，新能力优先进入 Responses API；已有系统可以按迁移成本排期，不必一夜切换。

国内团队怎么接入更稳？

先确认是网络、付款还是合规问题。若只是访问和结算，可评估 OpenAI 兼容网关；若数据不能出内网，则要考虑私有化或其他部署方式。是否适合，以你的实际约束为准。

小结

Grok API 接入可以压缩成一句话：选对 Key 来源，Base URL 只写到 /v1，模型名从官方页面复制，新项目优先 Responses API。剩下的流式、函数调用和错误处理，都是在这条主链上补细节。

需要统一管理多模型和账单，可以从注册页开始；具体模型与计费以站内模型价格为准。