> 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 約定，包括基底 URL、API 金鑰驗證、請求格式、模型 ID、回應模式以及 HTTP 狀態碼。

本指南涵蓋 ApiSmart API 中使用的常見慣例，包括驗證、請求格式、模型選擇、回應模式與錯誤處理。

如需各端點專屬的參數與範例，請參閱對應的 API 指南。

### 🔗 API 基礎 URL

標準的 ApiSmart API 基礎 URL 是：

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

大多數標準 API 端點都位於 `/v1` 路徑下。

例如：

| API              | 完整端點                                           |
| ---------------- | ---------------------------------------------- |
| 模型               | `https://gw.apismart.ai/v1/models`             |
| Chat Completions | `https://gw.apismart.ai/v1/chat/completions`   |
| 圖片生成             | `https://gw.apismart.ai/v1/images/generations` |
| 圖片編輯             | `https://gw.apismart.ai/v1/images/edits`       |
| 影片生成             | `https://gw.apismart.ai/v1/video/tasks`        |

某些專門工作流程可能會使用不同的路徑。請一律使用相關 API 指南中記載的端點。

### 🔑 驗證

ApiSmart 使用 API 金鑰來驗證 API 請求。

請在 `Authorization` 標頭中加入你的 API 金鑰：

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

請將 `<your-api-key>` 替換為你的實際 ApiSmart API 金鑰。

例如：

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

請妥善保管你的 API 金鑰，切勿將其暴露於公開儲存庫、瀏覽器端程式碼、日誌、螢幕截圖或其他可公開存取的位置。

如需金鑰管理與安全建議，請參閱 [**建立與管理 API 金鑰**](https://docs.apismart.ai/documentation/zh-tw/huan-ying-shi-yong-apismart/api-jin-yue/jian-li-bing-guan-li-api-jin-yue.md) 以及 [**保護你的 API 金鑰**](https://docs.apismart.ai/documentation/zh-tw/huan-ying-shi-yong-apismart/api-jin-yue/bao-hu-nin-de-api-jin-yue.md).

### 📦 請求格式

大多數 ApiSmart API 請求使用 JSON。

對於 JSON 請求，請包含：

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

範例：

```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": "Hello!"
      }
    ]
  }'
```

#### 檔案上傳

上傳本機檔案的端點可能會使用 `multipart/form-data` 而非 JSON。

例如，Image Edits API 接受本機圖片檔：

```bash
curl https://gw.apismart.ai/v1/images/edits \\
  -H "Authorization: Bearer <your-api-key>" \\
  -F model="doubao-seedream-5-0" \\
  -F image="@image.png" \\
  -F prompt="Transform this image into a watercolor painting" \\
  -F size="2K" \\
  -F response_format="url"
```

使用 `curl -F`時，curl 會自動建立適當的 multipart 請求。

請一律遵循你所使用端點文件中記載的請求格式。

### 🧩 模型 ID

API 請求使用 `model` 參數來識別應處理該請求的模型。

例如：

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

模型 ID 必須完全一致。

句點（`.`）、連字號（`-`）、版本號以及其他字元都必須完全依文件所示輸入。

例如：

正確：

`gpt-5.6-sol`

錯誤：

`gpt-5-6-sol`

正確：

`doubao-seedance-2-0-fast`

錯誤：

`doubao_seedance_2_0_fast`

格式錯誤的模型 ID 可能會導致 `503` 回應。

如需目前的模型清單與詳細的模型 ID 規則，請參閱 [**模型與模型 ID**](https://docs.apismart.ai/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md).

### 🔍 取得可用模型

你可以使用下列方式取得最新的模型清單：

`GET /v1/models`

範例：

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

範例回應：

```json
{
  "object": "list",
  "data": [
    {
      "id": "doubao-seedream-5-0",
      "object": "model",
      "owned_by": "api-gateway"
    },
    {
      "id": "deepseek-v4-flash",
      "object": "model",
      "owned_by": "api-gateway"
    }
  ]
}
```

請使用 `data[].id` 中的值作為 `model` 受支援 API 請求中的值。

Models API 可以回傳平台支援的模型，但並非每個模型都一定對每個 API 金鑰啟用。

如果某個模型對你的 API 金鑰不可用，API 可能會回傳：

`403 model_not_allowed`

如需更多資訊，請參閱 [**模型與模型 ID**](https://docs.apismart.ai/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md).

### 🌐 HTTP 方法

ApiSmart 端點會依執行的操作使用標準 HTTP 方法。

常見方法包括：

| 方法     | 典型用途           |
| ------ | -------------- |
| `GET`  | 擷取模型、任務狀態或歷史紀錄 |
| `POST` | 建立生成、任務或其他資源   |

例如：

`GET /v1/models`

可擷取可用模型清單，而：

`POST /v1/chat/completions`

會建立一個 Chat Completions 請求。

請務必使用對應 API 指南中指定的 HTTP 方法。

### ↩️ 回應模式

不同的 ApiSmart API 使用不同的回應模式。

| API              | 典型回應模式     |
| ---------------- | ---------- |
| Chat Completions | 標準或串流      |
| 圖片生成             | 同步或 SSE 串流 |
| 影片生成             | 非同步任務      |

#### Chat Completions

當符合以下情況時，Chat Completions 可以回傳標準回應或串流結果：

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

#### 圖片生成

圖片生成預設為同步，表示請求會保持開啟，直到生成完成。

支援的圖片生成工作流程也可使用串流。

#### 影片生成

影片生成為非同步。

建立影片請求會回傳一個任務 ID。請使用該 ID 查詢任務，直到其達到最終狀態。

如需詳細實作指引，請參閱 [**回應模式**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md).

### 🎬 非同步影片任務

使用下列方式建立影片任務：

`POST /v1/video/tasks`

任務建立後，請使用：

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

來檢查其狀態。

常見的任務狀態包括：

* `已排隊`
* `執行中`
* `成功`
* `失敗`
* `已取消`
* `已過期`

成功的任務可在回應中包含生成的影片 URL。

如需完整的請求參數與影片工作流程，請參閱 [**影片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/ying-pian-sheng-cheng-api.md).

### ⚠️ HTTP 狀態碼

ApiSmart 會結合標準 HTTP 狀態碼與 API 專屬錯誤代碼。

常見回應包括：

| HTTP 狀態       | 含義             |
| ------------- | -------------- |
| `400`         | 請求無效或參數不受支援    |
| `401`         | API 金鑰無效       |
| `402`         | 餘額不足           |
| `403`         | 存取或模型權限問題      |
| `404`         | 找不到所請求的任務或資源   |
| `429`         | 超出速率限制         |
| `500`         | 伺服器內部錯誤        |
| `502` / `504` | 上游或閘道錯誤        |
| `503`         | 供應商或相依服務暫時無法使用 |

例如：

`401 invalid_api_key`

表示驗證問題。

`402 insufficient_quota`

表示帳戶可用餘額不足。

`403 model_not_allowed`

表示所選模型目前尚未為該 API 金鑰或帳戶啟用。

如需詳細錯誤代碼與疑難排解指引，請參閱 [**HTTP 狀態碼與 API 錯誤**](https://docs.apismart.ai/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md).

### 🔄 處理暫時性錯誤

某些 `5xx` 回應可能表示上游、供應商、閘道或相依服務的暫時性問題。

應用程式應準備好優雅地處理暫時性失敗。

對於可重試的失敗：

* 避免不間斷地持續重試請求
* 使用合理的重試策略，例如指數退避
* 遵循 `Retry-After` 標頭（若有提供）
* 保留適當的記錄以便疑難排解

在未先修正根本問題之前，切勿因參數無效或驗證錯誤而自動重試失敗的請求。

### 💰 計費與用量

可計費的 API 請求會依所選模型的定價規則收費。

不同模型可能使用不同的計費單位，包括：

* Token
* 生成的圖片
* 影片時長
* 生成的影片 Token
* 依解析度定價

不要假設每個 ApiSmart API 請求都以相同方式計費。

如需模型專屬的計費規則，請參閱 [**模型定價與計費**](https://docs.apismart.ai/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-jia-ge-yu-ji-fei.md).

使用 **使用記錄與成本** 以查看實際請求用量與費用。

### ✅ 送出請求前

在發出 API 請求前，請確認：

* 你的 API 金鑰有效且已啟用
* 此 `Authorization` 標頭格式正確
* 端點與 HTTP 方法正確
* 請求使用所需的內容類型
* 模型 ID 已完全正確複製
* 你的帳戶餘額充足
* 你的應用程式對所呼叫的 API 使用了適當的逾時設定

這些檢查可避免許多常見的 API 整合問題。

### ➡️ 下一步

接著繼續：

* [**模型與模型 ID**](https://docs.apismart.ai/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md) — 找出有效的模型 ID
* [**模型定價與計費**](https://docs.apismart.ai/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-jia-ge-yu-ji-fei.md) — 了解模型專屬計費
* [**Chat Completions API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/liao-tian-bu-quan-api.md) — 使用文字模型進行建置
* [**Image Generation API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md) — 生成與編輯圖片
* [**影片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/ying-pian-sheng-cheng-api.md) — 建立影片工作流程
* [**回應模式**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md) — 了解標準、串流與非同步回應
* [**HTTP 狀態碼與 API 錯誤**](https://docs.apismart.ai/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md) — 排除 API 失敗問題
