# Grok API 调用教程：OpenAI Python SDK、Responses 与流式

> 使用 Passion8 API Key 和 /v1 地址调用 Grok，提供 OpenAI Python SDK、Chat Completions、Responses 与流式示例，说明推理和搜索工具边界。

URL: https://docs.passion8.cc/docs/grok/api
Language: zh-CN
Publisher: Passion8
Last updated: 2026-10-11

如果你在开发自己的应用，可以直接用 OpenAI SDK 调用本站 Grok。准备 Passion8 Key 和控制台开放的模型即可。本文从最小 Chat Completions 请求开始，再区分 Responses 与官方托管工具。

## 配置地址、Key 与模型

| 项目 | 值 |
| --- | --- |
| Base URL | `https://passion8.cc/v1` |
| API Key | Passion8 控制台创建的 Key |
| 示例模型 | `grok-4.7`，使用前确认账号已开放 |

macOS / Linux：

```bash
export PASSION8_API_KEY="replace-with-your-Passion8-key"
export PASSION8_GROK_MODEL="grok-4.7"
```

Windows PowerShell：

```powershell
$env:PASSION8_API_KEY="replace-with-your-Passion8-key"
$env:PASSION8_GROK_MODEL="grok-4.7"
```

如果控制台提供其他型号，将变量替换为实际 ID。下列代码从环境读取 Key，不读取 Grok Build 或 Codex 配置。

## 第一次请求：Chat Completions

在项目虚拟环境中安装：

```bash
python -m pip install --upgrade openai
```

保存为 `grok_smoke.py`：

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PASSION8_API_KEY"],
    base_url="https://passion8.cc/v1",
)
response = client.chat.completions.create(
    model=os.environ["PASSION8_GROK_MODEL"],
    messages=[{"role": "user", "content": "Reply only OK."}],
)
print(response.choices[0].message.content)
```

运行 `python grok_smoke.py` 后，到 [控制台](https://passion8.cc) 核对模型与请求时间。不要通过问“你是什么模型”判断路由。

## 流式输出

在上述初始化代码后改为：

```python
stream = client.chat.completions.create(
    model=os.environ["PASSION8_GROK_MODEL"],
    messages=[{"role": "user", "content": "Explain the purpose of unit tests."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
print()
```

流式返回的是增量片段，应用应持续读取，不要按普通 JSON 一次解析整个响应。费用仍然核对控制台记录。

## Responses：按客户端需求选择

xAI 官方目前推荐 Responses 用于新集成，并将 Chat Completions 标记为 legacy。兼容现有编程插件时，仍要按客户端实际请求协议配置。

如果你的账号渠道支持本站 Grok Responses，可把请求部分替换为：

```python
response = client.responses.create(
    model=os.environ["PASSION8_GROK_MODEL"],
    input="Reply only OK.",
)
print(response.output_text)
```

Responses 使用 `input` 和 `output_text`；Chat Completions 使用 `messages` 和 `choices`。不要只换接口名字却沿用另一种响应解析。官方 `previous_response_id`、后台运行等能力需确认本站是否支持，不能从一个文本响应推断。

## 推理、工具调用与窗口

Grok 4.7 官方上下文是 **500,000 tokens**，支持 `low`、`medium`、`high`、`xhigh`，默认 `high`。具体如何传推理参数取决于协议，建议最小请求成功后再按该协议文档添加，不要传旧的 `none`。

函数调用让模型返回工具请求，由你的应用执行并回传结果；官方 Web Search、X Search、Code Execution 则是托管工具。本站渠道未确认开放时，不要直接复制包含这些托管工具的完整官方示例。上下文窗口也不是最大输出 token 数。

## 故障定位

| 错误 | 优先检查 |
| --- | --- |
| 401 / 403 | 本站 Key、令牌状态、模型权限与余额 |
| 404 | `/v1` 地址、具体请求协议与模型 ID |
| 400 参数错误 | 请求体是否混用了 Chat / Responses 字段，是否带未支持工具 |
| 429 | 错误正文、请求并发与限流提示 |
| 长会话超限 | 客户端上下文预算和实际渠道限制；不要反复重发相同超限请求 |

编辑器接入见 [VS Code 使用 Grok](https://docs.passion8.cc/docs/grok/vscode)，官方客户端见 [Grok Build](https://docs.passion8.cc/docs/grok)。

## API 接入问答

### Cline 和 Codex 调用 Grok 时用的是同一个接口吗？

Base URL 都可以是 `https://passion8.cc/v1`，但 Cline 的 OpenAI Compatible 使用 Chat Completions，本文的 Codex 配置使用 Responses。地址相同不代表请求体相同，也不证明账号渠道同时开放两种协议。编辑器步骤分别见 [Cline 多模型配置](https://docs.passion8.cc/docs/cline) 和 [Grok 的 Codex 配置](https://docs.passion8.cc/docs/grok)。

### Grok API 能回答问题，就说明可以搜索 X 或网页吗？

不能。普通文本生成、函数调用和 xAI 托管的 X Search / Web Search 是不同能力。只有当前渠道明确支持对应托管工具时才能使用；不要把文本回答或 Cline 本地工具执行成功当成搜索功能已开放。

## 核对来源

核对日期：2026-10-11。

- [Grok 官方文本生成](https://docs.x.ai/developers/model-capabilities/text/generate-text)
- [Chat Completions legacy](https://docs.x.ai/developers/model-capabilities/legacy/chat-completions)
- [Grok 4.7 能力与推理档位](https://docs.x.ai/developers/models/grok-4.7)

本站模型与渠道支持以控制台和实际错误响应为准。