> 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/api-ji-chu.md).

# API 基礎

ApiSmart 提供一個統一 API，用於存取支援的語言、圖片與影片生成模型。

本指南說明 API 基礎 URL、驗證方式、常用端點、請求格式與基本錯誤處理。

針對特定模型的參數，請務必遵循 **程式碼範例** 中所選模型詳情頁上的說明。

***

### 開始之前

請確認你具備：

* 一個已啟用的 [ApiSmart 帳戶](/documentation/zh-tw/zhang-hu-yu-qian-bao/jian-li-bing-cun-qu-nin-de-zhang-hu.md#create-an-account)
* 充足的 **目前餘額**
* 一個已啟用的 **API 權杖**
* 剩餘的 API 金鑰使用額度
* 一個有效的 [模型 ID](/documentation/zh-tw/mo-xing-yu-ding-jia/mo-xing-yu-mo-xing-id.md#find-the-model-id)

若需協助選擇模型並找到其模型 ID，請參閱 [**選擇模型並找到其模型 ID**](/documentation/zh-tw/mo-xing-yu-ding-jia/mo-xing-yu-mo-xing-id.md).

***

### 🌐 API 基礎 URL

請使用以下 API 基礎 URL：

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

直接傳送 HTTP 請求時，請加上所需的端點路徑。

範例：

```
基礎 URL: https://gw.apismart.ai/v1
路徑:     /chat/completions

完整 URL：
https://gw.apismart.ai/v1/chat/completions
```

> ⚠️ **重要：** 不要 `/v1` 在建立請求 URL 時重複加入兩次。

***

### 常用 API 端點

不同模型類別使用不同的端點與請求格式。

| 目的     | 方法     | 端點                          |
| ------ | ------ | --------------------------- |
| 聊天補全   | `POST` | `/v1/chat/completions`      |
| 圖片生成   | `POST` | `/v1/images/generations`    |
| 建立影片任務 | `POST` | `/v1/video/tasks`           |
| 檢查影片任務 | `GET`  | `/v1/video/tasks/{task_id}` |

一律使用所選模型的 **程式碼範例**.

***

### 🔑 驗證

ApiSmart 使用 Bearer 驗證。

請將你的 **API 權杖** 放在 `Authorization` 標頭中：

```http
Authorization: Bearer YOUR_API_KEY
```

若請求包含 JSON，請同時加入：

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

完整標頭範例：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

> 🔐 請將你的 API 權杖保存在安全的伺服器端環境中。若需詳細安全指引，請參閱 **保護你的 API 權杖**.

***

### 送出基本請求

以下 cURL 範例會將請求送至支援的語言模型：

```
curl https://gw.apismart.ai/v1/chat/completions \\
  -H "Authorization: Bearer $APISMART_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "用一句話解釋 ApiSmart。"
      }
    ]
  }'
```

替換 `YOUR_MODEL_ID` 為所選模型詳情頁上顯示的確切模型 ID **程式碼範例** 或 **快速整合** 區段中的。

***

### 理解請求

基本的 Chat Completions 請求通常包含：

| 欄位         | 說明               |
| ---------- | ---------------- |
| `model`    | 處理此請求之模型的確切模型 ID |
| `messages` | 傳送給語言模型的對話訊息     |

範例：

```
{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "哈囉！"
    }
  ]
}
```

模型 ID 可能區分大小寫。請勿以模型的顯示名稱取代模型 ID，也不要更改其大小寫、底線、連字號或句點。

額外參數會因模型而異。

***

### 請求格式因模型而異

統一 API 並不代表每個模型都使用相同的請求主體。

| 模型類型 | 端點                       | 典型請求結構                                                           |
| ---- | ------------------------ | ---------------------------------------------------------------- |
| 語言   | `/v1/chat/completions`   | `messages`                                                       |
| 圖片   | `/v1/images/generations` | `prompt` 與模型專屬欄位                                                 |
| 影片   | `/v1/video/tasks`        | 模型專屬欄位，例如 `content`, `prompt`, `duration`, `resolution`，或 `size` |

影片生成採用非同步任務工作流程。建立任務後，請使用以下方式檢查其狀態：

```
GET /v1/video/tasks/{task_id}
```

> ⚠️ **重要：** 一律使用所選模型詳情頁上顯示的確切端點、模型 ID、欄位名稱與支援值 **程式碼範例**.

如需完整請求範例，請參閱：

* **Chat Completions API**
* **圖片生成 API**
* **影片生成 API**

***

### 讀取回應

ApiSmart API 回應通常以 JSON 格式傳回。

成功的 Chat Completions 回應可能類似於：

```
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "生成的回應"
      }
    }
  ]
}
```

視模型與請求類型而定，回應也可能包含：

* 模型資訊
* 使用資訊
* 請求識別碼
* 生成的圖片或影片資訊
* 任務狀態

確切的回應結構會因模型而異。

處理回應時：

1. 檢查 HTTP 狀態碼。
2. 剖析 JSON 回應。
3. 確認預期的結果欄位存在。
4. 在讀取生成內容之前先處理錯誤。
5. 儲存 **Request ID** 以便排除問題時使用。

***

### 🛠️ 常見請求問題

| 問題        | 檢查項目                                  |
| --------- | ------------------------------------- |
| **驗證失敗**  | API 權杖狀態、Bearer 標頭，以及完整的權杖值           |
| **找不到模型** | 確切模型 ID、大小寫、標點符號與模型可用性                |
| **無效的請求** | 端點、必要欄位、JSON 語法與模型專屬參數                |
| **餘額不足**  | **錢包 → 目前餘額** 和 **API 權杖 → 已使用 / 剩餘** |
| **請求逾時**  | 用戶端逾時、模型暫時延遲，或非同步任務狀態                 |

參數值也可能因模型而異。例如， `720p` 和 `720P` 可能不能互換。

排除問題時，請檢查 [**使用記錄與費用**](/documentation/zh-tw/api-shi-yong/shi-yong-ji-lu-yu-fei-yong.md) 中的相關請求，並在可用時儲存 **Request ID** 。

> 🔐 請絕不要在應用程式記錄、螢幕截圖、公開儲存庫或支援訊息中提供你的完整 API 權杖。

***

### 🚀 下一步

繼續進行：

* [**Chat Completions API**](/documentation/zh-tw/api-zhi-nan/liao-tian-wan-cheng-api.md)
* [**圖片生成 API**](/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md)
* [**影片生成 API**](/documentation/zh-tw/api-zhi-nan/ying-pian-sheng-cheng-api.md)
* [**串流回應**](/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md)
* [**選擇模型並找到其模型 ID**](/documentation/zh-tw/mo-xing-yu-ding-jia/mo-xing-yu-mo-xing-id.md)
* [**查看 API 使用記錄與費用**](/documentation/zh-tw/api-shi-yong/shi-yong-ji-lu-yu-fei-yong.md)