> 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/cheng-shi-ma-fan-li-yu-qian-yi/curl.md).

# cURL

了解如何使用 cURL 呼叫 ApiSmart API，包括模型探索、文字生成、圖片生成、本地圖片上傳、串流以及非同步影片任務。

cURL 是一個用來發送 HTTP 請求的命令列工具，也是測試 ApiSmart API 的最快方式之一。

本指南示範如何驗證請求、取得可用模型，以及直接從你的終端機呼叫文字、圖片和影片 API。

### 🚀 開始之前

請確認你已具備：

* ApiSmart 帳戶
* 有效的 API 金鑰
* 足夠的錢包餘額以供付費請求使用
* 系統已安裝 cURL

你可以用以下指令確認 cURL 是否可用：

```bash
curl --version
```

### 🔑 設定你的 API 金鑰

ApiSmart 使用 Bearer 驗證。

你可以直接在請求中放入 API 金鑰：

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

在本機測試時，你也可以將金鑰儲存在環境變數中，而不必在每個指令中重複輸入。

#### macOS 與 Linux

```bash
export APISMART_API_KEY="your-api-key"
```

接著使用：

```bash
-H "Authorization: Bearer $APISMART_API_KEY"
```

#### Windows PowerShell

```powershell
$env:APISMART_API_KEY="your-api-key"
```

接著使用：

```powershell
-H "Authorization: Bearer $env:APISMART_API_KEY"
```

請妥善保管你的 API 金鑰，不要將其放入公開儲存庫、螢幕截圖或共享的命令歷史中。

### 🔗 API 基礎網址

標準的 ApiSmart API 基礎網址是：

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

本指南中的大多數範例都使用完整的端點網址，方便直接複製並測試。

### 🧩 取得可用模型

在送出生成請求之前，你可以使用以下方式取得最新的模型 ID：

```bash
curl https://gw.apismart.ai/v1/models \
  -H "Authorization: Bearer $APISMART_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` 值作為 `模型` 支援的請求中的參數。

> **模型 ID 必須完全一致。**\
> 句點（`.`）、連字號（`-`）、以及版本號都必須依照回傳內容或文件所述完整複製。

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

### 💬 聊天完成

使用：

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

範例：

```bash
curl https://gw.apismart.ai/v1/chat/completions \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "Hello! Please introduce yourself."
      }
    ]
  }'
```

如需完整的請求行為，請參閱 [**Chat Completions API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/liao-tian-bu-quan-api.md).

### 🌊 串流文字回應

加入：

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

到請求本文：

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

如需串流行為概覽，請參閱 [**回應模式**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md).

### 🖼️ 產生圖片

使用：

```
POST /v1/images/generations
```

範例：

```bash
curl https://gw.apismart.ai/v1/images/generations \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 120 \
  -d '{
    "model": "doubao-seedream-5-0",
    "prompt": "日出時分的山村，水彩風格",
    "size": "2K",
    "watermark": false
  }'
```

圖片生成預設為同步，所需時間可能比一般文字請求更長。

請將你的用戶端逾時時間設為至少 **90 秒**。上方範例使用 `--max-time 120` 來為生成預留額外時間。

如需圖片參數與支援的工作流程，請參閱 [**Image Generation API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md).

### 🔄 依參考圖片生成

使用以下方式傳入公開圖片網址： `image`:

```bash
curl https://gw.apismart.ai/v1/images/generations \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 120 \
  -d '{
    "model": "doubao-seedream-5-0",
    "prompt": "將這張圖片轉換成水彩畫",
    "image": "https://example.com/input.jpg",
    "size": "2048x2048"
  }'
```

在支援的情況下，也可以使用陣列提供多個圖片網址。

### 📤 上傳本機圖片

若要上傳本機圖片檔案，請使用：

```
POST /v1/images/edits
```

此端點使用 multipart form data，而不是 JSON 請求本文。

```bash
curl https://gw.apismart.ai/v1/images/edits \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -F model="doubao-seedream-5-0" \
  -F image="@character.png" \
  -F prompt="Place the character in a cyberpunk environment" \
  -F size="2K" \
  -F response_format="url"
```

搭配 `-F`，cURL 會自動建立 multipart 請求。

每個上傳的圖片檔案都必須符合文件中記載的限制： [**Image Generation API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md).

### 🌊 串流圖片生成

支援的圖片工作流程可以使用 SSE 串流。

使用 cURL 時，請加入 `-N` 以防止輸出緩衝：

```bash
curl https://gw.apismart.ai/v1/images/generations \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  --max-time 120 \
  -d '{
    "model": "doubao-seedream-5-0",
    "prompt": "建立一組極簡風格的產品設計序列",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 4
    },
    "stream": true
  }'
```

如需支援的串流工作流程，請參閱 [**Image Generation API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md) 以及 [**回應模式**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md).

### 🎬 建立影片任務

影片生成是非同步的。

請建立任務，使用：

```
POST /v1/video/tasks
```

範例：

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0",
    "prompt": "夜晚的微縮城市，火車穿梭於街道之間",
    "duration": 5,
    "size": "720p"
  }'
```

回應會傳回一個任務 ID，你可以用它來檢查生成狀態。

> 對於影片模型，如果 `解析度` 以及 `時長` 會影響計費，請明確指定，而不要依賴預設值。

### 🔄 檢查影片任務狀態

建立任務後，使用以下方式查詢：

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

範例：

```bash
curl https://gw.apismart.ai/v1/video/tasks/<task_id> \
  -H "Authorization: Bearer $APISMART_API_KEY"
```

常見的任務狀態包括：

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

只要任務仍處於 `排隊中` 或 `執行中`.

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

### 🕘 取得最近生成的媒體

你也可以使用 cURL 來取得最近生成的媒體。

#### 圖片

```bash
curl "https://gw.apismart.ai/v1/images?page=1&page_size=20" \
  -H "Authorization: Bearer $APISMART_API_KEY"
```

#### 影片

```bash
curl "https://gw.apismart.ai/v1/videos?page=1&page_size=20" \
  -H "Authorization: Bearer $APISMART_API_KEY"
```

如需欄位定義與歷史記錄限制，請參閱 [**生成媒體歷史記錄**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/sheng-cheng-mei-ti-li-shi.md).

### 🛠️ 常用 cURL 選項

| 選項           | 用途                           |
| ------------ | ---------------------------- |
| `-H`         | 新增 HTTP 請求標頭                 |
| `-d`         | 傳送請求本文                       |
| `-F`         | 傳送 multipart form data 或上傳檔案 |
| `-N`         | 停用串流的輸出緩衝                    |
| `--max-time` | 設定請求的最長持續時間                  |
| `-X`         | 在需要時明確指定 HTTP 方法             |

對於大多數 JSON `POST` 請求，使用 `-d`，cURL 會自動送出 POST 請求，因此 `-X POST` 通常是可選的。

### ⚠️ 常見錯誤

#### `401 invalid_api_key`

請確認 API 金鑰有效，且請求中包含：

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

#### `402 insufficient_quota`

你的帳戶沒有足夠的可用餘額。

#### `403 model_not_allowed`

所選模型目前對你的 API 金鑰或帳戶不可用。

#### `400 unsupported_resolution`

所請求的解析度不受所選影片模型支援。

#### `503`

一個 `503` 可能表示暫時的服務問題。

如果在選擇模型後發生，也請確認模型 ID 是否完全依照文件所示撰寫。

如需完整的錯誤處理指引，請參閱 [**HTTP 狀態碼與 API 錯誤**](https://docs.apismart.ai/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md).

### ✅ cURL 快速檢查清單

送出請求前，請確認：

* 你的 API 金鑰已啟用
* 該 `Authorization` 標頭使用 `Bearer`
* 端點正確
* JSON 請求包含 `Content-Type: application/json`
* 模型 ID 已完全正確複製
* 檔案上傳使用 `-F` 而不是 JSON 本文
* 圖片請求使用適當的逾時時間
* 影片工作流程會輪詢回傳的任務 ID
* 你的錢包有足夠的餘額

### ➡️ 下一步

接著進行：

* [**API 基礎**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/api-ji-chu.md) — 學習常見的 API 慣例
* [**模型與模型 ID**](https://docs.apismart.ai/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md) — 找出有效的模型 ID
* [**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) — 生成與編輯圖片
* [**Video Generation 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) — 了解標準、串流與非同步行為
* [**生成媒體歷史記錄**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/sheng-cheng-mei-ti-li-shi.md) — 取得最近生成的圖片與影片
