> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/liao-tian-bu-quan-api.md).

# 聊天補全 API

了解如何使用 ApiSmart 與 OpenAI 相容的聊天補全 API 送出文字生成請求，並啟用串流回應。

使用 Chat Completions API 搭配支援的 ApiSmart 文字模型來生成文字。

ApiSmart 提供一個 **與 OpenAI 相容的 Chat Completions 介面**，讓已經使用熟悉的 `messages` 請求格式的應用程式更容易連接。

### 💬 端點

**方法：** `POST`

**端點：** `/v1/chat/completions`

**完整網址：**

`https://gw.apismart.ai/v1/chat/completions`

### 🔑 驗證

請將你的 ApiSmart API Key 包含在 `Authorization` 標頭中：

```http
Authorization: Bearer <your-api-key>
```

對於 JSON 請求，也請加入：

```http
Content-Type: application/json
```

將 `<your-api-key>` 替換為你的實際 API Key。

### 🚀 基本請求

一個基本請求包含有效的模型 ID 和一個 `messages` 陣列。

```bash
curl https://gw.apismart.ai/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "你好！請介紹你自己。"
      }
    ]
  }'
```

在此範例中：

* `model` 指定處理請求的模型。
* `messages` 包含對話輸入。
* `role` 識別訊息角色。
* `content` 包含傳送給模型的文字。

### 🧩 選擇模型

此 `model` 參數必須使用有效的 ApiSmart 模型 ID。

例如：

```json
{
  "model": "deepseek-v4-flash"
}
```

若要取得最新的模型清單，請使用：

```bash
curl https://gw.apismart.ai/v1/models \
  -H "Authorization: Bearer <your-api-key>"
```

使用回傳的 `data[].id` 值作為你請求中的 `model` 參數。

如需可用的文字模型與模型 ID 規則，請參閱 [**模型與模型 ID**](/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md).

> **模型 ID 必須完全一致。**\
> 句點（`.`）、連字號（`-`）、版本號以及其他字元都必須完全依照文件輸入。

### 📨 訊息

此 `messages` 欄位包含傳送給所選模型的對話輸入。

簡單的請求可以包含一則使用者訊息：

```json
{
  "model": "deepseek-v4-flash",
  "messages": [
    {
      "role": "user",
      "content": "用簡單的方式解釋 API 閘道。"
    }
  ]
}
```

對於較長的對話，請在 `messages` 陣列。

### 🌊 串流

Chat Completions 也支援串流輸出。

若要啟用串流，請加入：

```json
{
  "stream": true
}
```

範例：

```bash
curl https://gw.apismart.ai/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "寫一個短篇故事。"
      }
    ],
    "stream": true
  }'
```

啟用串流後，回應會逐步傳回，而不是等待完整生成完成。

如需標準、串流與非同步 API 行為的概覽，請參閱 [**回應模式**](/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md).

### 🔄 標準與串流

| 模式     | 設定               | 典型用途            |
| ------ | ---------------- | --------------- |
| **標準** | 預設               | 簡短回應與簡單整合       |
| **串流** | `"stream": true` | 互動式應用程式與較長的生成內容 |

當你想等到完整結果再回應時，請使用標準回應。

當你希望生成內容逐步到達時，請使用串流。

### ⚠️ 常見問題

#### 無效的 API Key

如果驗證失敗，API 可能會回傳：

`401 invalid_api_key`

請確認：

* API Key 正確
* 金鑰已啟用
* 此 `Authorization` 標頭使用 `Bearer` 方案
* 沒有遺漏字元或多餘空格

#### 模型不可用

如果所選模型不適用於你的 API Key，API 可能會回傳：

`403 model_not_allowed`

請選擇其他可用模型，或聯絡 [**ApiSmart 支援**](/documentation/zh-tw/shuo-ming-yu-zi-yuan/lian-luo-zhi-yuan.md) 如果你需要存取權限。

#### 意外的 503

如果你收到意外的 `503`，請先驗證模型 ID。

ApiSmart 模型 ID 會精確比對，因此錯誤的句點、連字號或版本號都可能導致請求失敗。

如需完整的錯誤資訊，請參閱 [**HTTP 狀態碼與 API 錯誤**](/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md).

### ✅ 在送出請求之前

在發出 Chat Completions 請求之前，請確認：

* 你的 API Key 有效且已啟用
* 你的帳戶餘額充足
* 端點為 `/v1/chat/completions`
* `Content-Type` 為 `application/json`
* 模型 ID 正確
* 請求包含一個 `messages` 陣列
* `"stream": true` 僅在需要串流時才包含

### ➡️ 下一步

繼續查看：

* [**模型與模型 ID**](/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md) — 找出支援的文字模型 ID
* [**模型定價與計費**](/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-jia-ge-yu-ji-fei.md) — 了解特定模型的計費方式
* [**回應模式**](/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md) — 了解標準、串流與非同步回應
* [**使用紀錄與成本**](/documentation/zh-tw/api-shi-yong-liang/shi-yong-ji-lu-yu-cheng-ben.md) — 檢視請求使用量與成本
* [**HTTP 狀態碼與 API 錯誤**](/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md) — 疑難排解 API 失敗