切换日光/暗黑模式

使用指南API 文档示例更新日志更多
curl https://api.wxiai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WXIAI_API_KEY" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手。"},
      {"role": "user", "content": "用一句话说明什么是 HTTP。"}
    ],
    "stream": false
  }'
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.wxiai.com/v1",
)

resp = client.chat.completions.create(
    model="grok-4.6",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手。"},
        {"role": "user", "content": "用一句话说明什么是 HTTP。"},
    ],
)

print(resp.choices[0].message.content)
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.wxiai.com/v1",
)

stream = client.chat.completions.create(
    model="grok-4.6",
    messages=[{"role": "user", "content": "写一首关于雨的短诗"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    # 思考型模型会先输出思维链，再输出正文
    if getattr(delta, "reasoning_content", None):
        print(delta.reasoning_content, end="", flush=True)
    if delta.content:
        print(delta.content, end="", flush=True)
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1735689600,
  "model": "grok-4.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "HTTP 是一种用于在网络上传输超文本的应用层协议。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 24,
    "total_tokens": 52
  }
}
data: {"id":"chatcmpl-abc123","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","choices":[{"index":0,"delta":{"content":"HTTP"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","choices":[{"index":0,"delta":{"content":" 是一种"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
{
  "error": {
    "code": "model_not_found",
    "message": "The model 'grok-99' does not exist",
    "type": "wxi_api_error",
    "param": "model"
  }
}
Grok API 调用

对话补全

和 Grok 模型对话。支持多轮上下文、流式输出、工具调用和思考模式。这是最常用的接口，OpenAI 官方 SDK 可以直接用。

POST/v1/chat/completions

这个接口只有一个地址 ​

http
POST /v1/chat/completions

没有 /xai 版本。 加前缀写成 /xai/v1/chat/completions 不是有效地址。

本页按 OpenAI 的标准字段写——你手上的 OpenAI SDK / 客户端怎么写，这里就怎么用。

Grok 的实现和 OpenAI 可能有差异

Grok 兼容 OpenAI 的请求/响应形状，但不保证逐字段一致：部分参数在 Grok 上有额外限制（例如推理模型不支持 stop、frequency_penalty、presence_penalty），也有一些 OpenAI 没有的专有参数和响应字段。

遇到对不上的地方，以 xAI 官方文档为准：

图像、视频、音频才有两种写法，区别见 调用方式。

新项目建议直接用 Responses

xAI 官方把 Chat Completions 标为 Deprecated（旧版端点，仅做有限更新），新集成推荐 响应生成。

它仍在正常工作，已有代码不必紧急迁移，但不要指望它跟进新能力。

Authorizations ​

Authorizationstringheader default: Bearer YOUR_API_KEY必填
使用 Bearer Token 进行身份验证。

Body ​

application/json

除 model 和 messages 外，其余参数都有合理默认值，第一次接入建议先只传这两个。

modelstring必填
要调用的模型 ID。可用值以 GET /v1/models 的返回为准，不要凭记忆写。
示例grok-4.6
messagesarray<object>必填
对话消息数组，按时间顺序传入。模型看到的就是这个数组的全部内容——它不会记住上一次请求。
最小长度1
streamboolean default: false可选
是否流式返回。开启后走 SSE，逐块推送增量内容，以 data: [DONE] 结束。做打字机效果、避免长回答超时都用它。
temperaturenumber default: 1可选
随机性。0 附近更确定、适合抽取和代码；1 以上更发散、适合创意写作。通常不要和 top_p 同时调。
top_pnumber可选
核采样范围。和 temperature 二选一调节即可，同时改会很难定位效果变化的原因。
max_completion_tokensinteger default: 128000可选
输出 token 上限，**只统计可见正文**，不含推理和工具调用消耗的 token。不设时默认 128000。
max_tokensinteger可选
【已废弃】请改用 max_completion_tokens。旧代码里仍能生效，新代码不要再用。
reasoning_effortstring可选
思考深度档位，仅部分模型支持。none 完全关闭思考；档位越高推理越充分，也越慢越贵。各模型接受的取值和默认值不同，以模型页说明为准。
可选值nonelowmediumhighxhigh
toolsarray<object>可选
声明可调用的函数。传了之后模型可能返回 tool_calls 而不是直接回答，由你的代码执行函数后再把结果回传。
tool_choicestring | object可选
控制是否强制调用工具。auto 由模型决定，none 禁止调用，也可指定某个函数名强制调用。默认值：**没传 tools 时是 none，传了 tools 时是 auto**。
可选值autononerequired
logprobsboolean可选
是否在返回里给出输出 token 的对数概率。部分模型不支持，传了会被忽略。
top_logprobsinteger可选
每个位置返回几个最可能的 token，取值 0–8。必须先开 logprobs。

其他常用参数 ​

stopstring | array可选
遇到这些字符串就停止生成。传字符串或字符串数组，最多 4 个。**推理模型不支持**，传了会直接报错。
ninteger default: 1可选
生成几个候选回答。取结果时遍历 choices 数组。注意按输出 token 计费，n 越大越贵。
frequency_penaltynumber default: 0可选
按词频惩罚，降低重复用词。范围 -2 到 2，正值减少重复。**推理模型不支持**，传了会直接报错。
presence_penaltynumber default: 0可选
按是否出现过惩罚，鼓励引入新话题。范围 -2 到 2。**`grok-3` 和推理模型不支持**，传了会直接报错。
seedinteger可选
随机种子。固定它有助于复现同一结果——但**不保证完全相同**，模型推理仍有随机性。
response_formatobject可选
要求结构化输出。三种取值：text（默认，纯文本）、json_object（兼容用，官方建议改用 json_schema）、json_schema（推荐，用 schema 约束输出，模型保证符合）。
示例{"type": "json_schema", "json_schema": {"name": "person", "schema": {...}}}
parallel_tool_callsboolean可选
是否允许模型一次返回多个工具调用。设为 false 则每次只调一个，便于串行处理。
stream_optionsobject可选
流式模式下的附加选项。最有用的是 include_usage —— 见下方说明。
示例{"include_usage": true}
userstring可选
标识终端用户的字符串，便于你自己在日志里区分调用来源。

流式模式下怎么拿到 token 用量 ​

默认情况下，开了 stream: true 就收不到 usage 字段——流式响应是一块块推的，最后一包里没有汇总信息。

做成本统计时会很麻烦。加一个参数就能拿到：

python
stream = client.chat.completions.create(
    model="grok-4.6",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
    stream_options={"include_usage": True},   # 关键
)

for chunk in stream:
    if chunk.usage:                            # 最后一包会带 usage
        print("本次用量：", chunk.usage)
    elif chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

⚠️ 注意最后一包的 choices 是空数组，直接取 chunk.choices[0] 会报错——所以要先判断 chunk.usage。

响应对象 ​

idstring服务端
本次对话的唯一标识。
objectstring服务端
固定为 chat.completion（流式分片是 chat.completion.chunk）。
createdinteger服务端
响应生成的 Unix 时间戳（秒）。
modelstring服务端
实际使用的模型。
choicesarray<object>服务端
结果数组。不传 n 时长度为 1，取 choices[0] 即可。
choices[].message.contentstring服务端
模型的正文回答。
choices[].message.reasoning_contentstring服务端
思考型模型的思维链内容，可能为空。展示时可折叠，不要把两段直接拼给用户看。
choices[].finish_reasonstring服务端
结束原因。stop 正常结束；length 表示撞到输出上限被截断；end_turn 表示模型主动结束这一轮；流式模式下非最后一包可能是 null。
usageobject服务端
token 用量统计，用于核对计费。含 prompt_tokens / completion_tokens / total_tokens；Grok 还会给 prompt_tokens_details、completion_tokens_details（推理 token 数）和 cost_in_usd_ticks。

多轮对话怎么做 ​

这个接口是无状态的——模型不会记得上一轮说了什么。要实现多轮，需要你自己把历史消息带上：

python
messages = [{"role": "system", "content": "你是一个助手。"}]

def chat(user_input):
    messages.append({"role": "user", "content": user_input})
    resp = client.chat.completions.create(model="grok-4.6", messages=messages)
    reply = resp.choices[0].message.content
    messages.append({"role": "assistant", "content": reply})
    return reply

chat("你好")
chat("我刚才说了什么？")   # 因为 messages 里有历史，它能答上来

⚠️ 上下文越长越贵也越慢。长会话要么截断旧消息，要么自己做个摘要。usage.prompt_tokens 可以帮你算出当前上下文多大。

接入建议 ​

  • 先跑非流式，确认模型名和鉴权都对，再加 stream: true。同时排查多个变量最容易卡住。
  • 别把 system 消息用得过于啰嗦：它会占用每一轮的输入 token，等于每次都付一遍钱。
  • reasoning_content 不要丢给终端用户看：思维链是中间过程，展示出来既干扰阅读也泄露提示词设计。
  • 工具调用是个循环不是一次请求：模型返回 tool_calls → 你的代码执行 → 把结果作为 tool 消息再请求一次，直到 finish_reason 变成 stop。

相关页 ​

基于 Apache-2.0 许可发布

Copyright © 2026 WXIAI. All rights reserved.