# OpenAI API

> 来源：
> - OpenAPI 规范（权威）：https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml
> - https://developers.openai.com/api/reference/resources/responses/methods/create
> - https://developers.openai.com/api/docs/guides/function-calling.md
> - https://developers.openai.com/api/docs/guides/structured-outputs.md
> - https://developers.openai.com/api/docs/guides/reasoning.md
> - https://developers.openai.com/api/docs/guides/migrate-to-responses.md
>
> 采集于 2026-08-12。注意：`platform.openai.com/docs/api-reference/*` 对爬虫返回 403，文档主站已迁移到 `developers.openai.com`；页面 URL 后加 `.md` 可直接取 Markdown 版本。

OpenAI 目前有**两套并存**的文本生成接口，中转站通常两套都要支持：

- `POST /v1/chat/completions` — 老接口，生态最广，几乎所有第三方"OpenAI 兼容"服务都实现它。
- `POST /v1/responses` — 新接口，OpenAI 主推，reasoning 模型的完整能力只在这里。

---

## 1. Chat Completions

### 1.1 请求参数

必填：`model`、`messages`。

`messages[]` 的 role 取值：`system`、`developer`、`user`、`assistant`、`tool`、`function`(deprecated)。

来自 `CreateChatCompletionRequest`：

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `messages` | array | — | 必填，minItems 1 |
| `model` | string | — | 必填 |
| `max_completion_tokens` | int\|null | — | 输出上限，**含 reasoning tokens** |
| `max_tokens` | int\|null | — | **已 deprecated**，且与 o 系列/reasoning 模型不兼容 |
| `modalities` | array | — | 如 `["text"]` / `["text","audio"]` |
| `verbosity` | enum | — | 输出详略控制 |
| `reasoning_effort` | enum | — | 见 §3 |
| `frequency_penalty` | number | 0 | -2 ~ 2 |
| `presence_penalty` | number | 0 | -2 ~ 2 |
| `response_format` | object | `{type:"text"}` | `text` / `json_object` / `json_schema` |
| `stream` | bool | false | SSE |
| `stream_options` | object | — | `{include_usage: true}` |
| `stop` | string\|array | — | 停止序列 |
| `logit_bias` | map<int,int> | null | -100 ~ 100 |
| `logprobs` | bool | false | |
| `top_logprobs` | int | — | 0 ~ 20，需 `logprobs=true` |
| `n` | int | 1 | 1 ~ 128 |
| `seed` | int | — | **已 deprecated**，Beta，不保证确定性 |
| `store` | bool | false | 是否存储用于 distillation/evals；>8MB 图片会被丢弃 |
| `moderation` | object | — | 请求/输出审核配置 |
| `prediction` | object | — | Predicted Outputs |
| `audio` | object | — | `modalities:["audio"]` 时必填，含 `voice`、`format` |
| `web_search_options` | object | — | 内置 web 搜索 |
| `tools` | array | — | function tools 或 custom tools |
| `tool_choice` | string\|object | — | `none`/`auto`/`required`/指定函数/`allowed_tools` |
| `parallel_tool_calls` | bool | true | |
| `function_call` | — | — | **deprecated**，用 `tool_choice` |
| `functions` | array | — | **deprecated**，用 `tools`；1~128 项 |

继承自 `ModelResponseProperties`（Chat 与 Responses **共享**）：

| 参数 | 类型 | 范围/默认 | 说明 |
| --- | --- | --- | --- |
| `temperature` | number | 0 ~ 2，默认 1 | |
| `top_p` | number | 0 ~ 1，默认 1 | 建议与 temperature 二选一 |
| `metadata` | map | — | |
| `user` | string | — | **deprecated**，被 `safety_identifier` + `prompt_cache_key` 取代 |
| `safety_identifier` | string | ≤64 字符 | 建议传用户名/邮箱的 hash |
| `prompt_cache_key` | string | — | 提升缓存命中率，取代 `user` |
| `service_tier` | enum | — | |
| `prompt_cache_retention` | enum | `in_memory` / `24h` | **deprecated**，改用 `prompt_cache_options.ttl`；`gpt-5.5` 及以后只支持 `24h` |
| `prompt_cache_options` | object | — | 含 `ttl` |
| `top_logprobs` | int | 0 ~ 20 | |

### 1.2 响应

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1741570283,
  "model": "gpt-4o-2024-08-06",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "...", "refusal": null, "annotations": []},
    "logprobs": null,
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 1117,
    "completion_tokens": 46,
    "total_tokens": 1163,
    "prompt_tokens_details": {"cached_tokens": 0, "audio_tokens": 0},
    "completion_tokens_details": {
      "reasoning_tokens": 0, "audio_tokens": 0,
      "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_..."
}
```

`finish_reason` 枚举：`stop` | `length` | `tool_calls` | `content_filter` | `function_call`(deprecated)。

`system_fingerprint` 已标记 **deprecated**。

`choices[].logprobs` 是 nullable 且在 schema 中被列为 **required**——即必须存在该 key，值可为 `null`。中转站生成响应时不要省略这个字段，严格的客户端会校验。

### 1.3 流式

`stream: true` 时返回 `object: "chat.completion.chunk"` 的 SSE，每个 chunk 的 `id` 相同，内容在 `choices[].delta`。

关键点：
- 设置 `stream_options: {"include_usage": true}` 时，**最后一个 chunk 的 `choices` 为空数组**，只带 `usage`。这是很多客户端解析崩溃的来源。
- 流以 `data: [DONE]` 结束（非 JSON）。
- 工具调用的 `arguments` 以字符串分片下发，需按 `tool_calls[].index` 累加。

---

## 2. Responses API

`POST /v1/responses`。

### 2.1 与 Chat Completions 的字段映射

| Chat Completions | Responses |
| --- | --- |
| `messages` | `input`（可为 string，也可为 Item 数组） |
| system / developer 消息 | `instructions`（顶层参数） |
| `max_completion_tokens` | `max_output_tokens` |
| `response_format` | `text.format` |
| `choices[0].message.content` | `output_text`（SDK 便捷字段）/ `output[]` 里的 message item |
| `tool_calls[]`（含 `id`） | `function_call` item（含 **`call_id`**） |
| `tools[].function.{name,...}` | `tools[].{name,...}`（少一层嵌套） |

### 2.2 专有请求参数

| 参数 | 说明 |
| --- | --- |
| `background` | 后台执行 |
| `conversation` | 会话 ID 或 `{id}` 对象，自动把历史 item 拼到 input 前 |
| `previous_response_id` | 由 OpenAI 托管上下文；**注意仍需重发 `instructions`** |
| `store` | Responses **默认存储**（Chat Completions 对新账户默认存储） |
| `include` | 请求额外输出，如 `web_search_call.action.sources`、`file_search_call.results` |
| `context_management` | `{type, compact_threshold}` 自动压缩上下文 |
| `reasoning` | `{effort, summary}` |

### 2.3 输出 item 类型

`output[]` 是异构数组，已知类型：

- `message` — `{id, role:"assistant", content:[text|refusal], status, phase?}`，`phase` 可为 `commentary` / `final_answer`
- `function_call` — `{arguments, call_id, name, status}`
- `file_search_call` — `{id, queries, status, results}`
- `web_search_call` — `{id, action, status}`
- `computer_call` — `{id, call_id, pending_safety_checks, action/actions, status}`
- `reasoning` — `{id, summary, content, encrypted_content, status}`
- `compaction` — `{id, encrypted_content}`

`status` 取值：`in_progress` | `completed` | `incomplete`。

### 2.4 流式

事件是命名事件（如 `response.function_call_arguments.delta` / `.done`），与 Chat Completions 的匿名 chunk 完全不同结构。
未取到完整事件清单（`/api/reference/responses/streaming` 返回 404），实现前需补齐。

---

## 3. Reasoning 模型的怪癖

这是 OpenAI 侧最容易踩的一类坑：

1. **`max_tokens` 不可用**。Chat Completions 必须用 `max_completion_tokens`，Responses 必须用 `max_output_tokens`。老代码直接透传 `max_tokens` 会报错。
2. **`temperature`、`top_p`、`presence_penalty` 不支持**（reasoning 模型上）。中转站若把这些参数无条件透传，请求会失败。
3. **`max_output_tokens` 包含 reasoning tokens**。官方建议实验时至少留 **25,000** tokens。给一个小的上限很可能只烧掉推理、输出为空。
4. **reasoning tokens 按 output token 计费**，占用上下文窗口，统计在 `output_tokens_details.reasoning_tokens`（Chat 侧为 `completion_tokens_details.reasoning_tokens`）。
5. **`reasoning.effort` 取值随模型而变**：`none` | `minimal` | `low` | `medium` | `high` | `xhigh` | `max`。`gpt-5.5` 默认 `medium`。不要假设所有模型接受全部取值。
6. **reasoning summary 需显式开启**：`reasoning.summary`，设 `"auto"` 取最详细的可用摘要。默认不返回。
7. **无状态模式下必须回传 `encrypted_content`**。当 `store: false` 或组织启用 ZDR 时，reasoning item 携带 `encrypted_content`，多轮要把它传回去才能保留推理链。
8. **函数调用多轮时必须带回 reasoning item**：把最后一次 function call 返回的 reasoning items 与 function output 一起回传；连续多次函数调用时，需保留自上一条 user 消息以来的**所有** reasoning / function_call / function_call_output item。

---

## 4. Function calling 的怪癖

- **`strict: true` 的硬性要求**：`additionalProperties` 必须为 `false`；**所有** `properties` 都必须出现在 `required` 里。可选字段只能用 `"type": ["string", "null"]` 表达。
- **`strict` 在两套 API 下行为不同**：Responses API 中 `strict` 默认尝试严格模式，**失败时自动回退到非严格**；Chat Completions 无此回退。
- **`tool_choice` 取值**：`"auto"`（默认）| `"required"` | `"none"` | `{"type":"function","name":"x"}` | `allowed_tools`（限定子集）。
- **`parallel_tool_calls: false`** 保证一轮最多一次工具调用。
- **ID 字段名不一致**：Chat Completions 是 `tool_calls[].id`，Responses 是 `function_call.call_id`。跨 API 转换时这是最常见的 bug 点。
- **流式 arguments 是分片字符串**，Responses 侧要累加 `response.function_call_arguments.delta` 直到 `.done`。

---

## 5. Structured Outputs 的怪癖

`strict: true` 下 JSON Schema 只支持一个子集：

**支持**：string、number、boolean、integer、object、array、enum、anyOf。

**不支持的关键字**：`allOf`、`not`、`dependentRequired`、`dependentSchemas`、`if`/`then`/`else`。
微调模型还额外不支持：字符串的 `minLength`/`maxLength`/`pattern`/`format`，数字的范围约束，数组的 `minItems`/`maxItems`。

**结构上限**：
- 最多 5000 个对象属性
- 最多 10 层嵌套
- 所有属性名 + 定义名 + 枚举值的总字符数 ≤ 120,000
- 枚举最多 1000 个值；超过 250 个时，单个属性的枚举值总长 ≤ 15,000 字符
- **根对象必须是 object，不能是 `anyOf`**
- 所有字段必须在 `required` 中；`additionalProperties` 必须为 `false`

**`refusal` 字段**：安全拒绝时，响应带一个**不遵守 schema** 的 `refusal` 字段。解析方必须先判断 `refusal` 再解析 JSON。

**与 `json_object` 的区别**：`json_object` 只保证是合法 JSON，**不保证符合 schema**。

---

## 6. 其他杂项怪癖

- `n > 1` 时按所有 choices 的生成 token 总量计费。多数第三方"OpenAI 兼容"实现只支持 `n=1`。
- `seed` 已 deprecated 且从来不保证确定性。
- `store: true` 时超过 8MB 的图片输入会被静默丢弃。
- `prompt_cache_retention` 与 `prompt_cache_options.ttl` 是**两个独立且不交互**的字段：前者表达最大保留策略，后者表达最小缓存寿命。