# GPT 系列 API：模型 ID、Chat Completions 与 Responses 接口、联网搜索与报错

Source: https://ofox.io/zh/docs/develop/models/gpt

OpenAI 的 GPT 文本模型，包括 GPT-6、GPT-5.x、GPT-4.1、GPT-4o 与 Codex 系列。通过 OpenAI 兼容接口调用，支持 **Chat Completions** 与 **Responses** 两种接口，官方 OpenAI SDK 修改 `base_url` 即可使用。

## 常见任务

- [开启推理](https://ofox.io/zh/docs/develop/models/gpt/reasoning) — reasoning_effort 取值、推理 token、推理摘要。
- [联网搜索](#web-search) — Responses 接口的 web_search 工具。
- [提示缓存](#caching) — 自动缓存与命中确认。
- [结构化输出与 PDF](https://ofox.io/zh/docs/develop/models/gpt/structured-output) — json_schema 输出与 PDF 文件输入。
- [报错排查](#errors) — 上下文超限、max_tokens 过大、回答为空、接口不支持。
- [在 Codex 中使用](https://ofox.io/zh/docs/integrations/codex) — 接入配置与常见问题。

## 模型
全部模型支持工具调用与结构化输出；除 GPT-5 nano 外均支持图片输入。完整的模型列表与实时价格请参阅[模型页](https://ofox.io/zh/models?provider=openai)，也可通过 [Models API](https://ofox.io/zh/docs/api/openai/models) 查询。

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

- GPT-6 Sol: `openai/gpt-6-sol`
- GPT-5.4: `openai/gpt-5.4`
- GPT-5.4 mini: `openai/gpt-5.4-mini`
- GPT-4.1 mini: `openai/gpt-4.1-mini` — 不推理，适合简单任务

模型 ID 可省略 `openai/` 前缀，例如 `gpt-5.4`。响应中的 `model` 字段统一为带前缀的写法。

## 接口选择

**要点**:Codex 系列与 GPT-5.4 Pro 仅支持 Responses 接口；其余模型两种接口均可使用。

| | Chat Completions | Responses |
|---|---|---|
| 地址 | `POST https://api.ofox.io/v1/chat/completions` | `POST https://api.ofox.io/v1/responses` |
| 输入 | `messages` | `input`（字符串或消息数组） |
| 输出长度上限 | `max_completion_tokens`（也接受 `max_tokens`） | `max_output_tokens` |
| [推理强度](https://ofox.io/zh/docs/develop/models/gpt/reasoning) | `reasoning_effort` | `reasoning.effort` |
| 推理摘要 | 不返回 | `reasoning.summary`，见[推理摘要](https://ofox.io/zh/docs/develop/models/gpt/reasoning#reasoning-summary) |
| 联网搜索 | 不支持 | `web_search` 工具 |
| 仅支持此接口的模型 | — | `openai/gpt-5.4-pro`、`openai/gpt-5.3-codex`、`openai/gpt-5.2-codex` |

完整的请求参数见 [Chat Completions API](https://ofox.io/zh/docs/api/openai/chat-completions) 与 [Responses API](https://ofox.io/zh/docs/api/openai/responses)。

### 供应商
| 供应商 | 提供的模型 |
|---|---|
| Azure AI Foundry（`azure_foundry`） | 全部模型，默认供应商 |
| OpenAI（`openai`） | GPT-6 Sol、GPT-6 Luna、GPT-6 Astra、GPT-5.6 Sol、GPT-5.6 Terra、GPT-5.6 Luna |

实测两个供应商在推理、缓存与联网搜索上的表现一致。需要指定供应商时，在请求头中加入 `X-OfoxAI-Provider-Type: openai`，其他方式见[供应商路由](https://ofox.io/zh/docs/develop/advanced/provider-routing)。

## 调用示例

**Python（Chat Completions）**

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

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

resp = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=[
        {"role": "system", "content": "你是一名资深后端工程师，回答简洁。"},
        {"role": "user", "content": "用一句话解释什么是幂等性。"},
    ],
)
print(resp.choices[0].message.content)
```

**Python（Responses）**

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

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

resp = client.responses.create(
    model="openai/gpt-5.4",
    instructions="你是一名资深后端工程师，回答简洁。",
    input="用一句话解释什么是幂等性。",
)
print(resp.output_text)
```

**cURL**

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

## 提示缓存

**要点**:GPT 系列自动缓存，无需修改请求；将固定内容放在请求开头即可提高命中率。

请求的前缀与近期请求一致且足够长时，会自动命中缓存，命中部分按缓存读取单价计费。

| 项目 | 说明 |
|---|---|
| 确认命中 | Chat Completions 中 `usage.prompt_tokens_details.cached_tokens` 大于 0；Responses 中为 `usage.input_tokens_details.cached_tokens` |
| 写入 | GPT-6、GPT-5.6 系列首次请求时返回 `prompt_tokens_details.cache_write_tokens`，按缓存写入单价计费 |
| 最小长度 | 前缀过短时不会缓存，最小长度见 [OpenAI 官方文档](https://platform.openai.com/docs/guides/prompt-caching) |
| 稳定性 | 缓存为尽力而为，前缀相同的请求也可能未命中 |

缓存的通用说明见[提示缓存](https://ofox.io/zh/docs/develop/advanced/prompt-caching)。

## 联网搜索
在 Responses 接口的 `tools` 中加入 `web_search`，模型会自行发起搜索并引用来源。Chat Completions 不支持联网搜索。

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

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

resp = client.responses.create(
    model="openai/gpt-5.4",
    tools=[{"type": "web_search"}],
    input="Python 最新的稳定版本是多少？",
)
print(resp.output_text)
print("搜索次数:", sum(1 for item in resp.output if item.type == "web_search_call"))
```

`output` 中的 `web_search_call` 条目为每次搜索，`message` 条目为最终回答。搜索按次计费，单价见[模型页](https://ofox.io/zh/models/openai/gpt-5.4)。

## 常见报错

**要点**:参数错误返回 400 并说明原因；长时间推理偶发 502、504，建议使用流式输出并设置较长的超时。

| HTTP · type | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 400 `invalid_request_error` | `This model's maximum context length is 128000 tokens. However, your messages resulted in 152008 tokens.` | 输入超过模型上下文 | 缩短输入，或改用上下文更长的模型 |
| 400 `invalid_request_error` | `max_tokens is too large: 100000. This model supports at most 16384 completion tokens` | 输出上限超过模型允许的最大值 | 减小 `max_completion_tokens` |
| 400 `invalid_request_error` | `Invalid value: 'bogus'. Supported values are: 'low', 'medium', 'high', and 'xhigh'.` | `reasoning_effort` 取值不受该模型支持 | 改用报错信息中列出的取值 |
| 400 `endpoint_not_supported` | `Model 'openai/gpt-5.4-pro' does not support the /v1/chat/completions endpoint on this platform.` | 该模型仅支持 Responses 接口 | 改用 `/v1/responses` |
| 404 `model_not_found` | `Model 'openai/gpt-9' not found` | 模型 ID 拼写错误或模型已下线 | 从本页复制模型 ID |
| 429 `rate_limit_error` | `Rate limit reached for the requested model. Please retry after a short delay.` | 请求过于频繁 | 稍后重试，见[速率限制](https://ofox.io/zh/docs/develop/guides/rate-limits) |
| 502 `upstream_error` | `The model service is temporarily unavailable. Please retry or switch to another model.` | 上游服务暂时不可用 | 稍后重试，或改用其他模型 |
| 504 `gateway_timeout` | `The upstream service did not respond in time.` | 推理时间过长，上游未在时限内响应 | 使用流式输出，或降低推理强度 |
| 200，`finish_reason: "length"` 且回答为空 | — | 推理用尽了 `max_completion_tokens` | 增大 `max_completion_tokens`，或降低推理强度 |

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

## 官方文档
- [OpenAI · 模型概览](https://platform.openai.com/docs/models)
- [OpenAI · 推理模型](https://platform.openai.com/docs/guides/reasoning)
- [OpenAI · Responses 与 Chat Completions 的区别](https://platform.openai.com/docs/guides/responses-vs-chat-completions)
- [OpenAI · 提示缓存](https://platform.openai.com/docs/guides/prompt-caching)
- [OpenAI · 联网搜索](https://platform.openai.com/docs/guides/tools-web-search)

官方文档描述的是直连 OpenAI 时的行为。在 OfoxAI 上调用时，模型 ID 与接口地址以本页为准。

## 常见问题

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

标准写法为 openai/gpt-5.4，也可以省略 openai/ 前缀写成 gpt-5.4。

**Chat Completions 和 Responses 用哪个？**

两者均可。Codex 系列与 GPT-5.4 Pro 仅支持 Responses；需要推理摘要或联网搜索时也需使用 Responses。已有 Chat Completions 代码的项目可继续使用。

**GPT 怎么开启推理？**

Chat Completions 传 reasoning_effort（如 "high"），Responses 传 reasoning: {"effort": "high"}。部分模型默认不推理，需要时请显式传入。

**GPT 返回的内容为空，finish_reason 是 length？**

推理消耗的 token 计入 max_completion_tokens，推理用尽额度后不会再输出回答。请增大 max_completion_tokens，或降低 reasoning_effort。

**报错 does not support the /v1/chat/completions endpoint？**

该模型仅支持 Responses 接口，例如 gpt-5.4-pro、gpt-5.3-codex、gpt-5.2-codex。请改用 POST /v1/responses。

**GPT 能看到推理过程吗？**

使用 Responses 接口并传入 reasoning: {"effort": "medium", "summary": "auto"}，output 中的 reasoning 条目会包含推理摘要。Chat Completions 不返回推理内容。

**GPT 能联网搜索吗？**

可以，使用 Responses 接口并在 tools 中加入 {"type": "web_search"}。Chat Completions 不支持联网搜索。

**GPT 的提示缓存需要手动开启吗？**

不需要，前缀足够长且与近期请求一致时会自动命中，命中量见 usage 中的 cached_tokens。

**GPT 请求超时或返回 504 怎么办？**

高强度推理可能耗时较长。建议使用流式输出（stream: true），将客户端超时设置为 600 秒以上，或降低 reasoning_effort。