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

# OpenAI 协议：Chat Completions 请求格式与流式输出

> 用 OpenAI Chat Completions 格式调用老张API文本模型：cURL 与 Python 示例、流式输出读取、请求字段、响应解析和错误排查。

OpenAI 协议即 OpenAI Chat Completions 格式，是老张API最通用的文本调用方式：发送 `messages`，从 `choices[0].message.content` 读取回复。

| 项目 | 内容 |
| - | - |
| 端点 | `POST https://api.laozhang.ai/v1/chat/completions` |
| 认证 | `Authorization: Bearer`，内容类型 `application/json` |
| 适用模型 | [模型与价格总表](/models)中「兼容端点」为「OpenAI 兼容」的文本模型，通过 `model` 字段选择 |
| 本页示例模型 | `gpt-5.4-mini` |

需要 Anthropic Messages 或 Gemini 原生的消息结构时，改用 [Claude 协议](/api-reference/claude)或 [Gemini 协议](/api-reference/gemini)；三种协议的差异对照见[文本生成 API](/api-capabilities/text-generation)。

## 发送请求

```text theme={null}
POST https://api.laozhang.ai/v1/chat/completions
```

请求使用 `Authorization: Bearer` 认证，内容类型为 `application/json`。先在[令牌管理](https://api.laozhang.ai/token)创建 API Key，计费模式选择按量优先（推荐）或按量计费，并确认它所在的令牌分组可以调用所选模型：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
```

使用 Python 示例时，先执行 `python -m pip install openai`。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 120 \
      "https://api.laozhang.ai/v1/chat/completions" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-5.4-mini",
        "messages": [{"role": "user", "content": "请只回复：连接成功"}]
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ["LAOZHANG_API_KEY"],
        base_url="https://api.laozhang.ai/v1",
        timeout=120.0,
        max_retries=0,
    )
    response = client.chat.completions.create(
        model="gpt-5.4-mini",
        messages=[{"role": "user", "content": "请只回复：连接成功"}],
    )
    print(response.choices[0].message.content)
    ```
  </Tab>
</Tabs>

示例关闭了 SDK 自动重试，由应用决定失败后是否重发。更换模型时，从[模型与价格总表](/models)复制完整 ID；不同模型接受的可选参数可能不同。

## 流式输出

在请求中加入 `"stream": true`，服务端会通过 SSE（server-sent events）边生成边返回。

每个数据块是一行以 `data:` 开头的 JSON，新增的文本在 `choices[0].delta.content`；最后一行是 `data: [DONE]`，表示流已经结束。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 120 -N \
      "https://api.laozhang.ai/v1/chat/completions" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-5.4-mini",
        "stream": true,
        "messages": [{"role": "user", "content": "用三句话介绍一下你自己"}]
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ["LAOZHANG_API_KEY"],
        base_url="https://api.laozhang.ai/v1",
        timeout=120.0,
        max_retries=0,
    )
    stream = client.chat.completions.create(
        model="gpt-5.4-mini",
        messages=[{"role": "user", "content": "用三句话介绍一下你自己"}],
        stream=True,
    )
    parts = []
    for chunk in stream:
        if not chunk.choices:
            continue
        choice = chunk.choices[0]
        if choice.delta.content:
            print(choice.delta.content, end="", flush=True)
            parts.append(choice.delta.content)
        if choice.finish_reason:
            print(f"\n结束原因：{choice.finish_reason}")

    full_text = "".join(parts)
    ```
  </Tab>
</Tabs>

cURL 的 `-N` 关闭输出缓冲，数据块一到就显示。输出类似下面这样（省略了 `id`、`model` 等字段）：

```text theme={null}
data: {"choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}]}

data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

逐块读取时注意：

* 把每块的 `delta.content` 按到达顺序拼接，就是完整回复；
* 有的数据块没有 `content`（例如只携带结束原因的最后一块），也可能没有 `choices`，跳过即可；
* `finish_reason` 出现在最后一个有效数据块中，含义与非流式响应相同；
* Python SDK 收到 `data: [DONE]` 后会自动结束 `for` 循环。连接在 `[DONE]` 之前断开时，已收到的文本不完整。

## 请求字段

必需字段只有 `model` 和 `messages`。先完成最小请求，再按模型说明添加可选配置。

| 字段 | 说明 |
| - | - |
| `model` | 必需；完整模型 ID |
| `messages` | 必需；包含当前输入及所需历史的消息数组 |
| `stream` | 设为 `true` 时以 SSE 流式返回，读取方法见上一节 |
| `temperature`、`top_p` | 采样参数；部分模型不接受，通常只调整其中一个 |
| `max_completion_tokens` | 输出预算；部分兼容模型使用 `max_tokens`，以模型说明为准 |
| `response_format` | 输出格式；仅用于支持 JSON 或结构化输出的模型 |
| `tools`、`tool_choice` | 工具定义与选择；需使用支持函数调用的模型 |

模型可能拒绝不适用的参数。遇到参数错误时，回到最小请求，再依据错误正文调整字段和值。

## 消息角色与历史

`user` 表示用户输入，`assistant` 表示模型回复。后续请求需要显式携带必要的历史消息，普通 Chat Completions 请求不会自动续接上一轮对话。

下面是文本对话的消息排列方式：

```json theme={null}
[
  {"role": "user", "content": "给这个项目起一个简短的中文名字。"},
  {"role": "assistant", "content": "星桥"},
  {"role": "user", "content": "用一句话解释这个名字。"}
]
```

系统指令可使用 `system` 角色，部分模型采用 `developer`；具体角色以该模型说明为准。发送图片时，`content` 改为内容块数组，写法见[图片理解 API](/api-capabilities/vision-understanding)。

对于支持工具调用的模型，响应可能包含 `tool_calls`，而 `content` 为空。应用执行所需函数后，按以下方式回传结果：

* 保留模型发出调用的那条 `assistant` 消息；
* 追加 `tool` 角色的消息，并带上对应的 `tool_call_id`。

## 读取响应

非流式响应的关键字段如下，省略了请求标识与使用量等字段：

```json theme={null}
{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "连接成功"
    },
    "finish_reason": "stop"
  }]
}
```

* `choices[].message.content`：普通文本回复。
* `choices[].message.tool_calls`：模型请求的工具调用，适用于支持该能力的模型。
* `choices[].finish_reason`：结束原因；`stop` 通常表示正常结束，`length` 表示达到长度限制。
* `usage`：返回时可用于统计用量，实际费用查看[调用日志](/faq/call-logs)。

文本为空时，先查看工具调用和结束原因。输出因长度限制中断时，调大该模型支持的输出预算，或缩短输入；不要把空文本直接当成网络错误。

## 选择模型

模型 ID、价格和可用分组以[模型与价格总表](/models)为准，能否调用取决于 API Key 所在的令牌分组。常用文本模型支持的协议与价格见[文本生成 API](/api-capabilities/text-generation#常用文本模型)；`o3-pro` 系列只支持 Responses，调用方法见 [OpenAI 模型接入](/api-reference/openai)。

选型时不要照搬固定的“最佳模型”榜单，用自己业务中有代表性的样本比较：

* 任务完成率和事实准确性；
* 指令遵循与结构化输出是否稳定；
* 需要工具调用时，调用参数是否完整；
* 响应延迟和失败率；
* 相同样本下的实际用量与费用（在[调用日志](/faq/call-logs)中查看）。

## 错误处理

| 状态 | 优先检查 |
| - | - |
| 400 | JSON、字段类型、模型参数与上下文长度 |
| 401 | 认证头格式和 API Key 是否有效 |
| 403 | 令牌分组、模型权限与账户限制 |
| 404 | 接口路径和完整模型 ID；SDK 的 Base URL 应为 `https://api.laozhang.ai/v1` |
| 429 | 错误正文中的余额、并发或速率限制信息 |
| 5xx / 超时 | 服务状态、网络和调用日志 |

修正参数或权限问题后再发起请求。对于临时限流和服务错误，可以有限次数地退避重试；超时后先在调用日志中确认请求状态，避免 SDK 与业务层同时重试。

向支持团队反馈时，提供请求时间、模型、接口路径和脱敏后的错误信息，不要附上密钥。

## 相关文档

* [文本生成 API：协议选择与常用模型](/api-capabilities/text-generation)
* [OpenAI 模型接入：端点与 SDK 配置](/api-reference/openai)
* [OpenAI 官方 Chat Completions 参考](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
* [OpenAI 官方流式输出指南](https://developers.openai.com/api/docs/guides/streaming-responses)
* [模型与价格总表](/models)
* [模型可用性与权限](/faq/model-availability)
* [Responses API](/api-manual#responses-api)
* [OpenAI SDK 配置](/api-manual#openai-sdk)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.