xAI API 免费额度：数据共享每月最高 175 美元

xAI API 兼容 OpenAI 的接口形态，把 base_url 换成 https://api.x.ai/v1，就能复用官方 SDK 或任意 OpenAI 兼容客户端。

准备密钥与环境变量

先在终端里把密钥放进环境变量，避免写死在代码里：

export XAI_API_KEY="粘贴控制台创建的 API Key"

用 curl 发起一次对话补全

模型名以控制台模型列表为准，下面示例使用 grok-4.7：

curl https://api.x.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4.7",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手"},
      {"role": "user", "content": "用一句话解释什么是向量检索"}
    ],
    "temperature": 0.7,
    "max_tokens": 512,
    "stream": false
  }'

用 Python SDK 调用

复用 OpenAI 官方 SDK，只改 base_url 与密钥来源：

import os
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="grok-4.7",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手"},
        {"role": "user", "content": "用一句话解释什么是向量检索"},
    ],
    temperature=0.7,
    max_tokens=512,
)

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

关键参数说明

• model：模型标识，例如 grok-4.7，可用的完整列表在控制台模型页查看。
• messages：消息数组，按顺序传入，每条包含 role 与 content；role 常用 system（设定人设与规则）、user（用户输入）、assistant（多轮对话中的历史回复）。
• temperature：随机性，取值 0 到 2，数值越低输出越稳定，做结构化抽取时建议调低。
• max_tokens：单次回复的最大 token 数，设得过大不会额外扣费，但会增加等待时间。
• stream：设为 true 时以流式返回，适合做打字机效果的对话界面。

额度耗尽与限流的典型表现与排查顺序

1. 401 未授权：密钥错误、请求头漏写 Bearer 前缀，或复制时带了空格与换行，重新生成密钥再试。
2. 403 或余额不足提示：账单上限仍为 0、未充值、数据共享额度未生效或已关闭，先回控制台核对额度与开关。
3. 429 请求过多：可能是超出 Tier 0 的 150 RPS / 5000 万 TPM，也可能是免费额度已用尽。先看响应头里的重试提示，再按指数退避降低并发。
4. 400 参数错误：常见原因是模型名拼错、messages 结构不合法、max_tokens 超出上限，对照报错字段逐项修改。
5. 5xx 或超时：多为服务端波动，用指数退避重试并记录请求 ID，持续失败再查控制台状态页。