---
title: "Chat Completions API（相容 OpenAI）"
description: "OpenAI-compatible /v1/chat/completions，包含參數、stream、tools、usage 和 cache 欄位。"
source: https://lazu.ai/docs/zh-TW/endpoints/chat
updated: 2026-10-02
---

# Chat completions

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

透過 Lazu 發送 OpenAI-compatible chat 請求。Base URL、認證、必要 body 欄位、stream、tools、response usage 和排障入口都在這一頁。

## 請求範例

```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 }
}
```

## 基本設定

- **Base URL** — 使用 `https://api.lazu.ai/v1` 搭配 OpenAI SDK，或直接呼叫完整
  path `https://api.lazu.ai/v1/chat/completions`。
- **模型發現** — 執行時讀取 `GET /api/models/catalog`，並篩選
  `supported_endpoint_types` 包含 `chat` 的模型。

## 請求 Body

- `model` `string` (必填) — 模型 ID、route alias 或未來的 route policy 名稱。建議從
  `GET /api/models/catalog` 讀取。
- `messages` `object[]` (必填) — 有序對話訊息。角色遵循 OpenAI shape。

  - `role` `string` — system、user、assistant 或 tool。
  - `content` `string | content_part[]` — 純文字，或多模態 content parts。
  - `tool_call_id` `string` — tool message 用於關聯先前的 tool call。
- `stream` `boolean` (可選) — 為 `true` 時返回 Server-Sent Events stream，最後以
  `data: [DONE]` 結束。
- `tools` `object[]` (可選) — Function/tool 定義。送出前先檢查模型 catalog 中的 
  `parameters.tools`。

  - `type` `"function"` — 目前支援 function tools。
  - `function.name` `string` — 模型可呼叫的工具名稱。
  - `function.parameters` `object` — 描述參數的 JSON Schema。
- `tool_choice` `string | object` (可選) — OpenAI-compatible tool choice 控制，例如 `auto`、
  `none`
  或指定工具物件。
- `response_format` `object` (可選) — Structured output 控制，例如 `{"type":"json_object"}`。
- `temperature` `number` (可選) — 取樣溫度，多數模型接受 `0` 到 `2`。
- `max_tokens` `integer` (可選) — 產生 token 上限，仍受模型 context 和 output limit 限制。

## Vision input

圖片輸入使用 OpenAI-compatible content parts。可以傳 HTTPS 圖片 URL 或 data URL：

**Image 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-TW/endpoints/files) 上傳，並使用
[Responses](https://lazu.ai/docs/zh-TW/endpoints/responses)。Chat completions 不會自動解引用

`file_id`。

## Response

- `id` `string` — Lazu 或 provider response ID。
- `choices` `object[]` — Assistant output choices。Streaming response 會送出增量 `delta`。
- `usage.prompt_tokens` `integer` — 輸入 token 數。
- `usage.completion_tokens` `integer` — 輸出 token 數。
- `usage.prompt_tokens_details.cached_tokens` `integer` (可選) — 上游回報時的 cache read token。

完整對帳請使用 [請求詳情](https://lazu.ai/docs/zh-TW/endpoints/usage-requests)。

## 相關頁面

- [模型目錄](https://lazu.ai/docs/zh-TW/models/catalog)
- [Responses API](https://lazu.ai/docs/zh-TW/endpoints/responses)
- [錯誤碼](https://lazu.ai/docs/zh-TW/errors)