---
title: Chat Completions 对话接口
description: POST /v1/chat/completions 的最小请求、常用字段、响应读取和多轮对话写法。
---

<aside className="docs-publication" data-pagefind-ignore>文档由 <a href="https://1zheai.com/editorial/#publisher">1折AI</a> 维护。<a href="https://1zheai.com/editorial/">来源、商业关系与纠错说明</a>。发现错误，请向 <a href="mailto:support@1zheai.com">support@1zheai.com</a> 提供页面地址与可核查依据，不要发送密钥或账号资料。</aside>

使用 OpenAI 兼容客户端，或已有 `chat.completions.create` 代码时，从这个接口开始。完整地址是 `https://1zheai.com/v1/chat/completions`；SDK 的 Base URL 只填到 `/v1`。

## 最小请求

先在终端设置 `ONEZHE_API_KEY` 为本站密钥。下面的模型必须存在于[你的可用模型列表](/docs/api-models/)中。

```bash
curl --fail-with-body --connect-timeout 10 --max-time 120 \
  https://1zheai.com/v1/chat/completions \
  -H "Authorization: Bearer $ONEZHE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [{"role": "user", "content": "请用一句中文解释 DNS 的作用。"}]
  }'
```

`--fail-with-body` 让 HTTP 错误返回非零退出码，同时保留错误正文；需要 curl 7.76 或更新版本。旧版可先用 `-i` 查看状态码。

## 常用字段

| 字段 | 类型 | 使用方式 |
| --- | --- | --- |
| `model` | string | 必填，复制本站模型 ID，不添加其他平台的供应商前缀 |
| `messages` | array | 必填，按顺序发送本轮问题和需要保留的历史消息 |
| `messages[].role` | string | 普通对话使用 `user` / `assistant`；系统指令的角色支持依模型而定 |
| `messages[].content` | string 或内容块数组 | 纯文本先用字符串；图片输入需模型支持对应内容块 |
| `stream` | boolean | 设为 `true` 时读取 SSE，不再把整份响应当作一个 JSON |
| `temperature` | number | 可选，部分推理模型不支持修改；先省略再逐项验证 |
| `tools` / `tool_choice` | array / string 或 object | 可选，模型与上游都需支持；工具实际执行由你的程序完成 |

输出上限参数随模型而异。不要把 Claude 的 `max_tokens`、Responses 的 `max_output_tokens` 和 Chat Completions 的参数机械互换；参考所选模型要求，遇到 400 先看错误正文。

## 怎么读取响应

普通文本结果位于 `choices[0].message.content`。结束原因在 `choices[0].finish_reason`；返回工具调用时，文本可能为空，需要读取 `message.tool_calls`。响应的 `id`、`model` 和 `usage` 可用于核对这次调用。

下面只展示需要关注的结构，省略字段与数字不代表真实请求结果：

```json
{
  "id": "example-completion",
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "DNS 将域名解析为网络地址。"},
    "finish_reason": "stop"
  }]
}
```

## 多轮对话

接口不会因为你重复使用同一密钥就自动记住前一轮。将需要保留的历史一起发送：

```json
{
  "model": "gpt-5.6-sol",
  "messages": [
    {"role": "user", "content": "我正在学习 DNS。"},
    {"role": "assistant", "content": "我们可以从域名解析开始。"},
    {"role": "user", "content": "它和 HTTP 有什么区别？"}
  ]
}
```

历史越长，请求越大。应用应按上下文限制裁剪或摘要，并保留完整的工具调用与结果配对。

## 流式与下一步

加上 `"stream": true` 后，文本增量来自 `choices[].delta.content`。有些事件没有文本或 `choices` 为空，读取时要判断；详见[流式输出](/docs/streaming/)。

直接运行 [Python / Node.js 完整示例](/docs/code-examples/)，或改用 [Responses](/docs/api-responses/)；Claude 原生参数见 [Messages](/docs/api-messages/)。