> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions

> POST /v1/chat/completions —— 与 OpenAI 完全兼容的对话接口

创建一次模型响应,基于对话上下文(messages 数组)。
所有支持对话能力的模型(OpenAI / Claude / Gemini / DeepSeek / Qwen 等)都可通过此接口调用。

## 请求

### 鉴权

```
Authorization: Bearer sk-XXXXXXXXXXXXXXXX
```

### 主要参数

| 字段                      | 类型               |  必填 | 说明                                                                |
| ----------------------- | ---------------- | :-: | ----------------------------------------------------------------- |
| `model`                 | string           |  ✅  | 模型 ID,如 `gpt-5.5`                                                 |
| `messages`              | array            |  ✅  | 对话历史,每条 `{ role, content }`                                       |
| `temperature`           | number           |     | 0-2,默认 1。越低越确定                                                    |
| `top_p`                 | number           |     | 0-1,核采样,与 temperature 二选一                                         |
| `n`                     | integer          |     | 生成几个候选(默认 1)                                                      |
| `stream`                | boolean          |     | true 启用 SSE 流式                                                    |
| `stream_options`        | object           |     | `{ include_usage: true }` 在流末追加 usage                             |
| `max_tokens`            | integer          |     | 最大输出 token 数(旧字段,部分模型已被 `max_completion_tokens` 替代)               |
| `max_completion_tokens` | integer          |     | 新字段,适用于 o3 / GPT-5                                                |
| `stop`                  | string \| array  |     | 停止序列                                                              |
| `presence_penalty`      | number           |     | -2\~2                                                             |
| `frequency_penalty`     | number           |     | -2\~2                                                             |
| `logit_bias`            | map              |     | token 偏置                                                          |
| `seed`                  | integer          |     | 复现性种子                                                             |
| `response_format`       | object           |     | `{ type: "json_object" }` 或 JSON Schema                           |
| `tools`                 | array            |     | 函数调用工具列表                                                          |
| `tool_choice`           | string \| object |     | `auto` / `required` / `{ type:"function", function:{name:"..."}}` |
| `parallel_tool_calls`   | boolean          |     | 是否允许并行调用工具                                                        |
| `reasoning_effort`      | string           |     | o3 / GPT-5 的推理强度:`low` / `medium` / `high`                        |
| `modalities`            | array            |     | 多模态输出,如 `["text","audio"]`                                        |
| `audio`                 | object           |     | 音频输出选项                                                            |
| `user`                  | string           |     | 终端用户标识(用于审计)                                                      |

### messages 结构

```json theme={null}
[
  {"role": "system",    "content": "你是中文助手"},
  {"role": "user",      "content": "讲个笑话"},
  {"role": "assistant", "content": "为什么程序员喜欢黑夜?因为没有 bug。"},
  {"role": "user",      "content": [
    {"type": "text", "text": "看图说话"},
    {"type": "image_url", "image_url": {"url": "https://..."}}
  ]}
]
```

支持的 role:`system` / `user` / `assistant` / `tool`(函数返回)。

## 响应

```json theme={null}
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1715750400,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "回答内容..."
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 19,
    "total_tokens": 46,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  },
  "system_fingerprint": "fp_..."
}
```

`finish_reason` 可能值:`stop` / `length` / `tool_calls` / `content_filter`。

## 流式响应

`stream: true` 时,服务端按 SSE 格式推送 chunk:

```
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"你"},"index":0}]}

data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"好"},"index":0}]}

data: {"id":"chatcmpl-...","choices":[{"delta":{},"index":0,"finish_reason":"stop"}]}

data: [DONE]
```

把 `stream_options.include_usage: true` 后,会在最后多发一条带 usage 的 chunk:

```
data: {"id":"chatcmpl-...","choices":[],"usage":{"prompt_tokens":...,"completion_tokens":...}}
```

## 函数调用

```json theme={null}
{
  "model": "gpt-5.5",
  "messages": [{"role": "user", "content": "上海天气"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get weather",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}
```

响应中:

```json theme={null}
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"city\":\"上海\"}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}
```

执行工具后把结果追加到 messages:

```json theme={null}
{"role": "tool", "tool_call_id": "call_abc", "content": "上海今天 26°C,晴"}
```

再次调用 chat completions 即可让模型基于工具结果继续回答。

## 推理模型

对 o3 / GPT-5 系列,使用 `reasoning_effort`:

```json theme={null}
{
  "model": "o3-mini-high",
  "messages": [{"role": "user", "content": "证明 √2 是无理数"}],
  "reasoning_effort": "high",
  "max_completion_tokens": 4096
}
```

也可使用带后缀的模型 ID(`o3-mini-low` / `-medium` / `-high`),效果等价。

## 错误

常见错误见 [错误码](/api-reference/errors)。