Grok API 实战：从调用到接入（2026 Python 教程，兼容 OpenAI SDK）

weixin_45916276

230人浏览 · 2026-06-15 14:49:54

weixin_45916276 · 2026-06-15 14:49:54 发布

本文带你把 xAI 的 Grok API 从零跑通：拿 Key、装 SDK、发第一个请求，再到流式输出、推理强度、多轮对话、函数调用、结构化输出和常见报错排查。Grok API 同时兼容 OpenAI 和 Anthropic 的 SDK，迁移基本只改一个 URL，已有 OpenAI 项目的同学几乎零成本接入。

环境：Python 3.8+。模型名、价格、限流以 https://docs.x.ai 官方为准（xAI 迭代很快，旧模型串会被重定向）。

一、准备工作

1. 获取 API Key

在 xAI 控制台（x.ai / console.x.ai）注册并创建 API Key。拿到后建议放进环境变量，别硬编码进代码：

# macOS / Linux
export XAI_API_KEY="你的_API_KEY"

# Windows PowerShell
setx XAI_API_KEY "你的_API_KEY"

2. 安装 SDK

因为 Grok 兼容 OpenAI 接口，直接用 OpenAI 官方 SDK 即可：

pip install openai

（也有官方原生 xai-sdk，但用 OpenAI SDK 对大多数人迁移成本最低，本文以它为主。）

二、第一个请求：Hello, Grok

核心只有两点不同于 OpenAI：base_url 指向 https://api.x.ai/v1，model 用 grok-4.3。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",   # 关键：指向 xAI
)

completion = client.chat.completions.create(
    model="grok-4.3",                  # 当前推荐的通用 + 编程旗舰
    messages=[
        {"role": "system", "content": "你是一个简洁专业的助手。"},
        {"role": "user", "content": "用一句话解释什么是 REST API。"},
    ],
)

print(completion.choices[0].message.content)

如果只想快速验证 Key 是否可用，用 curl 最省事：

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

三、流式输出（打字机效果）

做聊天类应用时，逐字返回的体验比"转圈等整段"好得多。加一个 stream=True 即可：

stream = client.chat.completions.create(
    model="grok-4.3",
    messages=[{"role": "user", "content": "写一段关于秋天的短描写。"}],
    stream=True,
)

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

四、控制推理强度：速度与质量的权衡

Grok 4.3 同时支持推理 / 非推理模式，用 reasoning_effort 调档，取值 none / low / medium / high：

completion = client.chat.completions.create(
    model="grok-4.3",
    messages=[{"role": "user", "content": "推导斐波那契数列第 20 项，并说明步骤。"}],
    reasoning_effort="high",   # 复杂推理/代码用 high；简单问答用 low 或 none，更快更省
)
print(completion.choices[0].message.content)

经验：算账、写代码、严谨分析用 high；客服问答、分类、要秒回的场景用 low/none，省 token 也省时间。

五、多轮对话：手动维护上下文

API 是无状态的——它不会"记住"上一轮，你得把历史消息每次都带上：

history = [
    {"role": "system", "content": "你是一个 Python 答疑助手。"},
]

def chat(user_input):
    history.append({"role": "user", "content": user_input})
    resp = client.chat.completions.create(model="grok-4.3", messages=history)
    answer = resp.choices[0].message.content
    history.append({"role": "assistant", "content": answer})  # 把回复也存回历史
    return answer

print(chat("怎么读取一个 txt 文件？"))
print(chat("那写入呢？"))   # 这一轮 Grok 知道你还在问文件操作

注意：历史越长，消耗的 token 越多。生产里要做好截断或摘要，避免上下文无限膨胀。

六、函数调用（Function Calling / Tools）

让模型在需要时"请求调用你的函数"，是做 Agent 的基础。用法与 OpenAI 完全一致：

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询某个城市的当前天气",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string", "description": "城市名"}},
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="grok-4.3",
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
    tools=tools,
)

tool_calls = resp.choices[0].message.tool_calls
if tool_calls:
    print(tool_calls[0].function.name)       # get_weather
    print(tool_calls[0].function.arguments)  # {"city": "北京"}

模型返回的是"想调用哪个函数、参数是什么"，真正的执行由你的代码完成，再把结果作为 role: "tool" 消息回传给模型做下一步。

七、结构化输出（强约束 JSON）

要把模型接进流水线，最怕格式飘忽。用 response_format 强制返回 JSON：

import json

resp = client.chat.completions.create(
    model="grok-4.3",
    messages=[
        {"role": "system", "content": "只输出 JSON，不要多余文字。"},
        {"role": "user", "content": "提取信息：张三，28 岁，软件工程师。"},
    ],
    response_format={"type": "json_object"},
)

data = json.loads(resp.choices[0].message.content)
print(data)   # {'name': '张三', 'age': 28, 'job': '软件工程师'}

需要更严格的字段约束时，可进一步用 json_schema 指定结构（具体格式见官方文档）。

八、常见报错与排查

报错	原因	解决
`401 Unauthorized`	Key 错误或没传	检查环境变量、`Authorization: Bearer` 是否正确
`404 model not found`	模型串拼错或已下线	改用 `grok-4.3`；旧串多已重定向，但别依赖
`429 Too Many Requests`	触发限流或额度用尽	加退避重试、检查账户余额/免费额度
连接超时	网络问题	检查网络环境与代理设置
多智能体模型报错	用错了 API	`grok-4.20-multi-agent` 不支持 Chat Completions，需用 Responses API 或 xai-sdk

退避重试的简单写法：

import time
from openai import RateLimitError

def safe_call(**kwargs):
    for i in range(3):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError:
            time.sleep(2 ** i)   # 1s, 2s, 4s 退避
    raise RuntimeError("重试多次仍失败")

九、模型怎么选 & 价格

模型	适用场景	备注
`grok-4.3`	通用对话 + 编程，默认首选	支持推理/非推理模式
`grok-code-fast-1`	追求速度、低成本的编码任务	长上下文，价格更友好
`grok-4.20-multi-agent`	多智能体深度研究	仅 Responses API / xai-sdk，不走 Chat Completions
`grok-imagine-image-quality`	文生图	走 Images 接口