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

# Chat Completions 接口

> 理解对话请求、返回正文、结束原因与用量。

向 `POST https://api.apione.ai/v1/chat/completions` 发送消息，即可使用 OpenAI 兼容的对话接口。先用最小请求确认连接，再添加目标模型支持的参数。

## 发送请求

先按[快速开始](https://apione.ai/docs/quickstart.md)设置 `APIONE_API_KEY` 和 `APIONE_MODEL`。模型 ID 从[可用模型列表](https://apione.ai/docs/models/catalog.md)复制，需与当前 Key 的权限及分组匹配。

```bash theme={null}
: "${APIONE_API_KEY:?请先设置 APIONE_API_KEY}"
: "${APIONE_MODEL:?请先设置 APIONE_MODEL}"

curl -sS https://api.apione.ai/v1/chat/completions \
  -H "Authorization: Bearer $APIONE_API_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"model\":\"$APIONE_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"给文档网站列出三个导航分组。\"}]}"
```

多轮对话时，由应用在 `messages` 中发送必要的历史消息。不要假设下一次请求会自动带上上次的上下文。需要 SDK 示例时，见 [Python 与 Node.js 接入](https://apione.ai/docs/guides/sdks.md)。

## 常用请求字段

| 字段 | 类型 | 用法 |
| - | - | - |
| `model` | string | 必填，当前 Key 可调用的模型 ID |
| `messages` | object\[] | 必填，包含 `role` 和 `content` 的消息历史 |
| `stream` | boolean | 开启 SSE 流式返回，默认 `false` |
| `max_tokens` | integer | 输出上限；是否支持及取值范围以模型参数为准 |
| `temperature` | number | 采样控制，支持范围以模型为准 |
| `top_p` | number | 另一种采样控制，通常不与 `temperature` 同时调整 |
| `tools` / `tool_choice` | object\[] / string 或 object | 工具定义与选择方式，要求模型支持 |
| `response_format` | object | JSON 或 JSON Schema 输出，要求模型支持 |

切换模型时重新核对参数。出现不支持的参数错误，先移除可选字段，确认最小请求可用后逐个恢复。

## 读取响应

普通文本响应结构如下，字段值仅作示意：

```json theme={null}
{
  "model": "YOUR_MODEL_ID",
  "choices": [
    {
      "message": {"role": "assistant", "content": "开始使用、接口参考、集成指南。"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 20, "completion_tokens": 10, "total_tokens": 30}
}
```

| 字段 | 读取方式 |
| - | - |
| `choices[].message.content` | 回复正文；工具调用时可能为空 |
| `choices[].message.tool_calls` | 模型请求应用执行的工具调用 |
| `choices[].finish_reason` | 例如 `stop`、`length`、`tool_calls` 或 `content_filter` |
| `usage` | 输入、输出与总 Token 用量；缓存等扩展字段随模型变化 |
| `model` | 响应中的模型信息 |

`finish_reason` 为 `length` 时，检查输出上限和内容是否完整；截断的 JSON 不能直接用于后续业务。工具调用和 JSON 校验见[结构化输出与工具调用](https://apione.ai/docs/models/advanced.md)，连续接收增量见[流式输出](https://apione.ai/docs/models/streaming.md)。

完整字段见 [APIONE Chat 接口参考](https://apione.ai/zh/api-docs/reference/ref-chat)；调用失败时见[错误码与排查](https://apione.ai/docs/support/errors.md)。


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