# Grok API：模型 ID、推理强度、2M 上下文与报错

Source: https://ofox.ai/zh/docs/develop/models/grok

xAI 的 Grok 模型，包括推理模型 Grok 4.7、4.6、4.5、4.3，与非推理模型 Grok 4.1 Fast、4.20。通过 OpenAI 兼容接口调用。

## 常见任务

- [降低推理耗时](#reasoning) — reasoning_effort 的作用与实测效果。
- [接口支持](#endpoints) — Chat Completions、Responses、Anthropic 接口。
- [报错排查](#errors) — 不支持推理参数、协议不支持、请求超时。

## 模型
完整的模型列表与实时价格请参阅[模型页](https://ofox.ai/zh/models?provider=x-ai)。模型 ID 的前缀为 `x-ai/`，可省略。

**常用模型 ID（调用时原样复制）**

- Grok 4.7: `x-ai/grok-4.7` — 推理模型，500K 上下文
- Grok 4.1 Fast: `x-ai/grok-4.1-fast` — 非推理，2M 上下文，支持图片

| 类型 | 模型 | 说明 |
|---|---|---|
| 推理模型 | Grok 4.7、4.6、4.5 | 始终推理，耗时较长；500K 上下文，仅支持文本 |
| 推理模型 | Grok 4.3 | 1M 上下文，支持图片输入 |
| 非推理模型 | Grok 4.1 Fast、4.20 | 响应快；2M 上下文，支持图片输入 |

## 接口支持
| 接口 | 支持的模型 |
|---|---|
| Chat Completions `/v1/chat/completions` | 全部 |
| Responses `/v1/responses` | Grok 4.3、4.20、4.1 Fast |
| Anthropic 原生接口 | 仅 Grok 4.3；其余返回 `protocol_not_supported` |

Grok 模型由 xAI 官方（`grok`）提供，部分模型另有 Azure AI Foundry 供应商。

## 调用示例

**Python**

```python filename="grok_basic.py"
import os
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="x-ai/grok-4.7",
    reasoning_effort="low",
    messages=[{"role": "user", "content": "用一句话解释什么是幂等性。"}],
)
print(resp.choices[0].message.content)
print("推理 token:", resp.usage.completion_tokens_details.reasoning_tokens)
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.ai/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x-ai/grok-4.7",
    "reasoning_effort": "low",
    "messages": [{"role": "user", "content": "用一句话解释什么是幂等性。"}]
  }'
```

## 推理

**要点**:Grok 4.7、4.6、4.5 始终推理，复杂问题可能耗时数分钟。请用 reasoning_effort: low 降低推理量，或改用非推理的 Grok 4.1 Fast。

| 模型 | 推理 | `reasoning_effort` |
|---|---|---|
| Grok 4.7、4.6、4.5 | 始终推理 | `low` 可显著降低推理量 |
| Grok 4.3 | 始终推理，不返回推理内容 | 可传入 |
| Grok 4.1 Fast、4.20 | 不推理 | Grok 4.1 Fast 传入返回 400 |

实测同一道数学题：Grok 4.7 默认推理约 1.5 万 token、耗时约 4 分钟；`reasoning_effort: "low"` 时约 4200 token、约 1 分钟。推理 token 按输出单价计费，数量见 `usage.completion_tokens_details.reasoning_tokens`；推理内容在流式响应的 `delta.reasoning_content` 中。

## 其他功能
- **图片输入**：Grok 4.3、4.20、4.1 Fast 支持，使用标准的 `image_url` 内容块，写法见[视觉理解](https://ofox.ai/zh/docs/develop/guides/vision)。
- **结构化输出与工具调用**：`response_format` 支持 `json_schema`；工具调用使用标准的 `tools` 参数。
- **缓存**：自动缓存重复的请求前缀，命中量见 `usage.prompt_tokens_details.cached_tokens`。

## 常见报错
| HTTP · type | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 400 `invalid_request_error` | 包含 `This model does not support` 与 `reasoning` | 向非推理模型 Grok 4.1 Fast 传入了 `reasoning_effort` | 删除该参数 |
| 400 `protocol_not_supported` | `Model 'x-ai/grok-4.7' does not support the 'anthropic' protocol on this platform.` | 该模型不支持 Anthropic 接口 | 改用 OpenAI 兼容接口 |
| 400 `endpoint_not_supported` | `Model 'x-ai/grok-4.7' does not support the /v1/responses endpoint on this platform.` | 该模型不支持 Responses 接口 | 改用 `/v1/chat/completions` |
| 404 `model_not_found` | `Model 'xai/grok-4.7' not found` | 前缀写成了 `xai/` | 前缀为 `x-ai/` |
| 请求超时 | — | 推理时间过长 | 传 `reasoning_effort: "low"`、使用流式输出，或将客户端超时设置为 600 秒以上 |

其他通用错误见[错误处理](https://ofox.ai/zh/docs/develop/guides/error-handling)。

## 官方文档
- [xAI · 文档](https://docs.x.ai/)

## 常见问题

**Grok 的模型 ID 怎么写？**

标准写法为 x-ai/grok-4.7，也可以省略前缀写成 grok-4.7。写成 xai/grok-4.7 会返回 404。

**Grok 4.7 为什么这么慢？**

Grok 4.7、4.6、4.5 始终推理，复杂问题可能推理上万 token、耗时数分钟。传 reasoning_effort: "low" 可显著缩短，或改用不推理的 Grok 4.1 Fast。

**Grok 能关闭推理吗？**

Grok 4.7、4.6、4.5、4.3 无法关闭推理，只能用 reasoning_effort 降低推理量。需要快速响应时请使用 Grok 4.1 Fast。

**Claude Code 能用 Grok 吗？**

仅 Grok 4.3 支持 Anthropic 接口，其余 Grok 模型调用会返回 protocol_not_supported。

**Grok 支持多长的上下文？**

Grok 4.1 Fast 与 4.20 为 2M token，Grok 4.3 为 1M，Grok 4.7、4.6、4.5 为 500K。