---
title: "Chat Completions API（OpenAI 兼容）"
description: "OpenAI 兼容的 /v1/chat/completions，同页包含参数、示例、流式、工具调用和 cache usage 字段。"
source: https://lazu.ai/docs/zh/endpoints/chat
updated: 2026-10-02
---

# Chat completions

**POST** `/v1/chat/completions`

通过 Lazu 发送 OpenAI 兼容的对话请求。本页直接包含 base URL、鉴权、请求字段、响应 usage、流式输出、工具调用和请求详情查询，不需要跳到单独的 OpenAPI Explorer 页面。

## 请求示例

```bash
curl https://api.lazu.ai/v1/chat/completions \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "messages": [
      {"role": "user", "content": "Say hello from Lazu"}
    ]
  }'
```

## 响应示例

```json
{
  "id": "chatcmpl-9aZx",
  "model": "gpt-6-luna",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 11, "completion_tokens": 3 }
}
```

## 基础配置

- **SDK base\_url** — OpenAI SDK 使用 `https://api.lazu.ai/v1`。
- **模型发现** — 生产代码应先读取 `GET /api/models/catalog`，筛选
  `supported_endpoint_types` 包含 `chat` 的模型。

## 请求 Body

- `model` `string` (必填) — 模型 ID，来自 `GET /api/models/catalog`。后续也可以承载
  `auto` 或 route policy 名称。
- `messages` `object[]` (必填) — 对话消息数组。role 使用 OpenAI 兼容格式：
  `system`、`user`、`assistant`、
  `tool`。
- `stream` `boolean` (可选) — 设置为 `true` 时返回 SSE 流式响应，结尾为
  `data: [DONE]`。
- `tools` `object[]` (可选) — 工具/函数定义。发送前建议检查模型目录里的
  `parameters.tools`。
- `response_format` `object` (可选) — 结构化输出控制，例如 `{"type":"json_object"}`。
- `temperature` `number` (可选) — 采样温度。不同 provider 的有效范围可能不同。
- `max_tokens` `integer` (可选) — 最大输出 token，仍受模型上下文和输出限制约束。

## 消息格式

- `role` `string` (必填) — 消息角色。 取值: `system`, `user`, `assistant`, `tool`
- `content` `string | content_part[]` (必填) — 文本消息可直接传字符串；多模态请求可传 content parts。
- `tool_calls` `object[]` (可选) — assistant 消息里的工具调用。
- `tool_call_id` `string` (可选) — `tool` 消息需要带这个字段，用来对应上一轮 tool call。

## 图片输入

**Vision input**

```json
{
"model": "gpt-6-luna",
"messages": [
  {
    "role": "user",
    "content": [
      {"type": "text", "text": "What's in this image?"},
      {
        "type": "image_url",
        "image_url": {"url": "data:image/png;base64,..."}
      }
    ]
  }
]
}
```

PDF 和大文件应该使用 [Files](https://lazu.ai/docs/zh/endpoints/files) +
[Responses](https://lazu.ai/docs/zh/endpoints/responses)。Chat completions 不会自动读取

`file_id`。

## 响应 usage 和 cache 字段

- `usage.prompt_tokens` `integer` — 输入 token。
- `usage.completion_tokens` `integer` — 输出 token。
- `usage.prompt_tokens_details.cached_tokens` `integer` (可选) — cache read tokens。
- `usage.prompt_tokens_details.cache_write_tokens` `integer` (可选) — provider 上报时返回的 cache write tokens。
- `usage.prompt_tokens_details.cache_miss_tokens` `integer` (可选) — provider 明确上报 cache miss 时返回，例如 DeepSeek 兼容字段。

完整对账信息使用请求详情 API：

**Request detail**

```bash
curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \
-H "Authorization: Bearer $LAZU_API_KEY"
```

## 相关页面

- [模型目录](https://lazu.ai/docs/zh/models/catalog)
- [Responses API](https://lazu.ai/docs/zh/endpoints/responses)
- [计费规则](https://lazu.ai/docs/zh/billing)
- [请求详情](https://lazu.ai/docs/zh/endpoints/usage-requests)