切换日光/暗黑模式
Grok API 调用
响应生成
OpenAI Responses API 格式。相比对话补全，它的主要价值是服务端工具——联网搜索、X 搜索、代码执行，模型可以直接调用，你不需要自己实现。
POST
/v1/responses什么时候用它，什么时候不用
| 你要做的事 | 用哪个 |
|---|---|
| 要让模型联网搜索 / 搜 X / 跑代码 | 用这个 |
需要服务端保存上下文、用 previous_response_id 续接 | 用这个 |
| 普通对话、做聊天界面 | 对话补全，更简单 |
| 已有的 Chat Completions 代码跑得好好的，也不需要上面的能力 | 不用换 |
xAI 官方把 Chat Completions 定位为上一代接口，新项目建议直接用 Responses。我们两个都支持。
这个接口只有一个地址
http
POST /v1/responses没有 /xai 版本——文本类接口本身就是 OpenAI 格式，不存在「原生」和「兼容」两层。加 /xai 前缀不是有效地址。
图像、视频、音频才有两种写法，区别见 调用方式。
开始前必须知道的三个字段差异
xAI 官方是支持 instructions 的（"An alternate way to specify the system prompt"），但在这个网关上它不会生效——为了兼容现有的 Responses 请求形态，网关会在转发前丢弃 instructions 和 metadata。
所以照官方文档写、却在我们这里跑不通时，先看这张表：
| 你传的 | 在官方 API | 在这个网关 | 怎么办 |
|---|---|---|---|
instructions | ✅ 系统提示词入口（不能与 previous_response_id 同用） | ❌ 会被丢弃，不生效 | 把系统提示词写进 input 的第一条 system / developer 消息 |
metadata | 仅为兼容保留，不生效 | ❌ 会被丢弃 | 自己在上层记录业务标识 |
web_search_preview | OpenAI 的旧工具名 | 按 web_search 处理 | 直接写 web_search 更直观 |
最容易踩的坑是 instructions
它在官方那边是合法的「系统提示词」，网上大量 Responses 示例都这么写，很容易照抄。在这个网关上它会被静默丢弃——模型不会报错，只是完全没按你说的做。
改用 input 携带系统指令。
instructions与previous_response_id在官方那边也互斥：带了previous_response_id时，会沿用上一轮的系统提示词。
Authorizations
Authorizationstringheader default: Bearer YOUR_API_KEY必填使用 Bearer Token 进行身份验证。
Body
application/json最简单的情况只需要 model 和 input 两个字段。
modelstring必填要调用的模型 ID。以 GET /v1/models 的返回为准。
示例
grok-4.6inputstring | array必填输入内容。直接传字符串最简单；需要多轮上下文或结构化输入时传消息数组。系统提示词也写在这里（第一条 system / developer 消息）。
previous_response_idstring可选上一轮响应的 id。带上它，服务端会把上一轮的上下文接上，你不用自己拼历史消息。需要配合 store 使用。
storeboolean可选是否保存本次输入与输出，供后续 previous_response_id 检索。做多轮对话时需要打开。
max_output_tokensinteger default: 128000可选输出 token 上限。**同时包含正文和推理 token**——思考型模型会先用掉一部分，设太紧正文会被截断。
temperaturenumber可选随机性，0–2。含义与对话补全一致。
top_pnumber可选核采样。和 temperature 二选一调节即可。
reasoningobject可选思考模式配置，例如 reasoning.effort 控制思考深度。部分模型支持。
reasoning_effortstring可选reasoning 的简写形式。两者同时出现时只认 reasoning。
可选值
nonelowmediumhighxhighstreamboolean default: false可选是否流式返回。开启后按语义化事件推送，而不是逐 token。
toolsarray<object>可选要启用的工具。服务端工具（web_search / x_search / code_interpreter）跑在 Grok 侧；function 类型由你的代码执行。**最多 350 个**。
tools[].typeenum<string>可选工具类型。function 由你的代码执行，其余由服务端执行。Grok 支持的服务端工具不止列出的这些，完整清单见 xAI 官方文档。
可选值
functionweb_searchtool_choicestring | object default: auto可选控制是否强制调用工具。
可选值
autononerequiredparallel_tool_callsboolean可选是否允许模型一次发起多个工具调用。设为 false 则每次只调一个，便于串行处理。
userstring可选标识终端用户的字符串，便于你自己在日志里区分调用来源。
Grok 的实现和 OpenAI 可能有差异
本页按 OpenAI Responses 的标准字段写。Grok 兼容其形状，但不保证逐字段一致：有些 OpenAI 字段在 Grok 上不生效或不存在，Grok 也有自己的专有参数（联网搜索的细粒度配置、缓存键等）。
遇到对不上的地方，以 xAI 官方文档为准：
三个服务端工具
| 工具 | type | 用途 | 计费 |
|---|---|---|---|
| 联网搜索 | web_search | 让模型检索互联网获取最新信息，回答里带来源引用 | 按调用次数 |
| X 搜索 | x_search | 搜索 X（推特）上的实时讨论与舆情 | 按调用次数 |
| 代码执行 | code_interpreter | 模型写并运行代码来算数、处理数据 | 按调用次数 |
工具的细粒度参数（限域名、限 X 账号、时间范围等）由 xAI 定义，见：
- 联网搜索 https://docs.x.ai/developers/tools/web-search
- X 搜索 https://docs.x.ai/developers/tools/x-search
- 代码执行 https://docs.x.ai/developers/tools/code-execution
json
{
"model": "grok-4.6",
"input": "xAI 最近有什么动态？",
"tools": [
{"type": "web_search", "filters": {"allowed_domains": ["x.ai"]}},
{"type": "x_search", "allowed_x_handles": ["elonmusk"]}
]
}工具调用次数从响应的 usage.server_side_tool_usage_details 里读，可以据此核对费用：
json
"usage": {
"num_server_side_tools_used": 3,
"server_side_tool_usage_details": {
"web_search_calls": 2,
"x_search_calls": 1
}
}多轮对话
两种做法，按需选：
做法一：previous_response_id（推荐，不用自己拼历史）
python
r1 = client.responses.create(model="grok-4.6", input="你好", store=True)
r2 = client.responses.create(
model="grok-4.6",
input="我刚才说了什么？",
previous_response_id=r1.id,
)
print(r2.output_text)做法二：自己维护 input 数组（和对话补全一样，上下文完全在你手里）
注意：
instructions不能和previous_response_id一起用——官方说明这种情况下会沿用上一轮的系统提示词。
响应对象
idstring服务端响应对象唯一标识。做多轮时把它存下来。
statusenum<string>服务端completed 正常结束；in_progress 进行中；incomplete 未完成（看 incomplete_details）。
outputarray<object>服务端输出数组，可能同时包含推理过程、工具调用、正文消息等多种类型。取正文用 SDK 的 output_text 更方便。
output[].content[].annotationsarray<object>服务端联网搜索时的来源引用，含 url_citation。做事实核查类产品时应该把它展示给用户。
incomplete_detailsobject服务端status 为 incomplete 时说明原因，常见是撞到了 max_output_tokens。
usage.num_server_side_tools_usedinteger服务端本次请求用到的服务端工具总次数。
usage.server_side_tool_usage_detailsobject服务端服务端工具调用次数明细，用于核对工具产生的费用：web_search_calls、x_search_calls、code_interpreter_calls、file_search_calls、mcp_calls、document_search_calls、image_generation_calls。
接入建议
- 联网结果一定要标来源：
annotations里有url_citation，展示出来既专业也避免用户误以为是模型自己知道的。 x_search是 Grok 的特色：需要舆情、热点、实时讨论类场景时，比通用联网搜索更对路。instructions不要用，写进input。- 别为了「新」而迁移：已经有稳定的 Chat Completions 流程，且不需要服务端工具，就没必要换。
- 工具循环要设上限：模型可能陷入「调用工具 → 再调用」的空转，客户端要有自己的轮数或超时上限。