> 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/ying-pian-sheng-cheng-api.md).

# 影片生成 API

了解如何使用 ApiSmart 透過 HappyHorse 和 Seedance 生成影片，包括文字、圖片、影片、音訊、多模態輸入、任務輪詢以及解析度設定。

使用影片生成 API，透過支援的 ApiSmart 影片模型建立影片。

依所選模型而定，您可以從以下內容生成影片： **文字、圖片、影片、音訊及多模態參考資料**.

影片生成為非同步作業。建立任務後，請使用傳回的任務 ID 檢查其狀態，直到生成完成。

### 🎬 端點

#### 建立影片任務

**方法：** `POST`

**端點：** `/v1/video/tasks`

**完整 URL：**

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

#### 查詢影片任務

**方法：** `GET`

**端點：** `/v1/video/tasks/{id}`

#### 擷取影片內容

**方法：** `GET`

**端點：** `/v1/videos/{id}/content`

### 🔑 驗證

請在以下位置包含您的 ApiSmart API 金鑰： `Authorization` 標頭：

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

對於 JSON 請求，另請包含：

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

### 🧩 支援的影片模型

ApiSmart 目前支援兩個影片模型系列。

#### HappyHorse

* `happyhorse-1.0`
* `happyhorse-1.1`

#### Seedance

* `doubao-seedance-2.0`
* `doubao-seedance-2-0-fast`
* `doubao-seedance-2-0-mini`
* `doubao-seedance-2-5`

功能、支援的解析度、輸入內容及計費規則會因模型而異。

如需定價資訊，請參閱 [**模型定價與計費**](/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-jia-ge-yu-ji-fei.md).

***

## HappyHorse

HappyHorse 支援數種生成工作流程。API 會根據請求中包含的輸入內容自動判定工作流程。

| 輸入   | 工作流程    |
| ---- | ------- |
| 僅提示詞 | 文字轉影片   |
| 一張圖片 | 圖片轉影片   |
| 多張圖片 | 參考資料轉影片 |
| 影片輸入 | 影片編輯    |

當存在多種輸入類型時，工作流程偵測會遵循以下優先順序：

**影片編輯 → 參考資料轉影片 → 圖片轉影片 → 文字轉影片**

### ✨ 文字轉影片

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0",
    "prompt": "夜晚的微型城市，火車穿梭於街道間，燈光閃耀",
    "duration": 5,
    "size": "720P",
    "metadata": {
      "ratio": "16:9"
    }
  }'
```

### 🖼️ 圖片轉影片

使用以下欄位提供單一圖片 URL： `image`:

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0",
    "prompt": "讓人物自然微笑並緩慢轉向鏡頭",
    "image": "https://example.com/input.png",
    "duration": 5,
    "size": "1080P"
  }'
```

### 🧩 多張參考圖片

使用 `images` 當您的請求需要多張參考圖片時：

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0",
    "prompt": "使用第一張參考圖片中的人物和第二張參考圖片中的風扇",
    "images": [
      "https://example.com/person.png",
      "https://example.com/fan.png"
    ],
    "duration": 5,
    "size": "720P",
    "metadata": {
      "mode": "r2v",
      "ratio": "16:9"
    }
  }'
```

在提示詞中參考多張 HappyHorse 圖片時，請遵循模型使用的參考順序。

### 🎞️ 影片編輯

HappyHorse 也支援影片輸入。

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0",
    "prompt": "將影片轉換為賽博龐克視覺風格，同時保留主體動作",
    "input_reference": "https://example.com/input.mp4",
    "size": "720P"
  }'
```

對於影片編輯，您可以提供 `duration` 以指定生成影片的長度。若省略，服務可使用來源影片的時長。

### ⚠️ HappyHorse 解析度與時長

建立標準 HappyHorse 生成請求時，請務必明確指定解析度和時長。

若省略解析度，HappyHorse 計費預設為：

**1080p**

若省略時長，計費預設為：

**5 秒**

例如，使用 `happyhorse-1.0`:

**預設計費**

`1080p × 5 秒 = $1.35`

明確請求：

```json
{
  "resolution": "720p",
  "duration": 5
}
```

結果為：

`720p × 5 秒 = $0.725`

明確設定這些參數有助於避免非預期的費用。

> HappyHorse 請求格式可能使用 `resolution` 或 `size` 作為與解析度相關的設定。請依照您正在實作的工作流程所示格式。

***

## Seedance

Seedance 使用 `content` 陣列來結合文字與多模態參考資料。

支援的內容類型包括：

* `text`
* `image_url`
* `video_url`
* `audio_url`

### ✨ 文字轉影片

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "一隻貓在日落時沿著海灘奔跑，具有電影感光影與高視覺細節"
      }
    ],
    "ratio": "16:9",
    "duration": 4,
    "resolution": "720p",
    "watermark": false
  }'
```

### 🖼️ 參考圖片

使用 `reference_image` 當圖片應引導生成影片時。

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "讓圖片中的角色進行自然舞蹈"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/input.jpg"
        },
        "role": "reference_image"
      }
    ],
    "duration": 4,
    "resolution": "720p"
  }'
```

### 🎞️ 首尾幀生成

Seedance 可以生成指定首幀與尾幀之間的轉場。

使用：

* `role: "first_frame"`
* `role: "last_frame"`

範例：

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "保持鏡頭固定，並從早晨平滑轉場至日落"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/start.jpg"
        },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/end.jpg"
        },
        "role": "last_frame"
      }
    ],
    "duration": 4,
    "ratio": "16:9",
    "resolution": "720p"
  }'
```

您也可以僅提供一個 `first_frame` 若您希望生成影片以特定圖片開始。

圖片參考資料可使用公開 HTTP/HTTPS URL 或 Base64 資料 URI。

### 🎥 參考影片

使用 `reference_video` 當現有影片應引導生成時：

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "為影片加入電影感光影與氛圍"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/input.mp4"
        },
        "role": "reference_video"
      }
    ],
    "duration": 4,
    "resolution": "720p"
  }'
```

包含影片輸入的請求可能適用不同的 Seedance 定價級別。

請參閱 [**模型定價與計費**](/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-jia-ge-yu-ji-fei.md) 以取得目前定價詳細資訊。

### 🎵 圖片、影片與音訊

Seedance 也支援多模態參考資料組合。

可用角色包括：

| 角色                | 用途      |
| ----------------- | ------- |
| `reference_image` | 參考圖片    |
| `first_frame`     | 生成影片的首幀 |
| `last_frame`      | 生成影片的尾幀 |
| `reference_video` | 參考影片    |
| `reference_audio` | 參考音訊    |

`reference_audio` 無法單獨使用。必須與支援的圖片或影片參考資料搭配使用。

多模態請求可以如下所示：

```json
{
  "model": "doubao-seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "圖片1中的角色在舞台上跳舞，動作參考影片1，並配合音訊1"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/character.jpg"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/dance.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://example.com/music.mp3"
      },
      "role": "reference_audio"
    }
  ],
  "generate_audio": false,
  "ratio": "9:16",
  "duration": 5,
  "resolution": "720p"
}
```

#### 在提示詞中參考多個素材

當包含多個非文字素材時，請使用：

* `圖片1`, `圖片2`, ...
* `影片1`, `影片2`, ...
* `音訊1`, `音訊2`, ...

編號從以下項目開始 `1` 並遵循非文字項目在以下項目中的順序： `content` 陣列。

請勿在中文素材類型與其編號之間加入空格。

### 📦 Seedance 輸入限制

Seedance 最多支援 **共 12 個參考素材**，包括：

* 最多 9 張圖片
* 最多 3 部影片
* 最多 3 個音訊檔案

合計數量不得超過 12。

### 📎 Base64 圖片輸入

除了公開 URL 以外， `image_url.url` 可以包含 Base64 資料 URI：

```json
{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  },
  "role": "reference_image"
}
```

此 `data:image/...;base64,` 前綴為必填。

***

### ⚙️ 請求參數

| 參數                        | 模型         | 類型      | 說明                     |
| ------------------------- | ---------- | ------- | ---------------------- |
| `model`                   | 全部         | 字串      | 影片模型 ID                |
| `prompt`                  | 全部         | 字串      | 文字生成指令                 |
| `duration`                | 全部         | 整數      | 影片時長（秒）                |
| `resolution` / `size`     | 全部         | 字串      | 請求的解析度                 |
| `content`                 | 全部         | 陣列      | 多模態內容陣列                |
| `image` / `images`        | HappyHorse | 字串 / 陣列 | 圖片 URL 或多個圖片 URL       |
| `input_reference`         | HappyHorse | 字串      | 用於影片編輯的來源影片 URL        |
| `metadata`                | HappyHorse | 物件      | 其他 HappyHorse 設定       |
| `ratio`                   | Seedance   | 字串      | 長寬比，例如 `16:9` 或 `9:16` |
| `callback_url`            | Seedance   | 字串      | 選用的回呼 URL              |
| `return_last_frame`       | Seedance   | 布林值     | 傳回生成的最終影格              |
| `generate_audio`          | Seedance   | 布林值     | 生成同步音訊                 |
| `draft`                   | Seedance   | 布林值     | 啟用草稿模式                 |
| `tools`                   | Seedance   | 陣列 / 物件 | 選用的工具設定                |
| `seed`                    | 全部         | 整數      | 隨機種子                   |
| `watermark`               | Seedance   | 布林值     | 啟用或停用浮水印               |
| `execution_expires_after` | Seedance   | 整數      | 任務到期時間（秒）              |

支援的參數會因模型和工作流程而異。

***

### 📐 解析度與時長

解析度和時長會直接影響影片計費。

#### 預設值

| 模型系列       | 省略時的解析度        | 省略時的時長  |
| ---------- | -------------- | ------- |
| HappyHorse | 計費依據 **1080p** | **5 秒** |
| Seedance   | 計費依據 **720p**  | 由模型決定   |

#### 支援的解析度

| 模型 ID                      | 支援的解析度                  |
| -------------------------- | ----------------------- |
| `happyhorse-1.0`           | `720p`, `1080p`         |
| `happyhorse-1.1`           | `720p`, `1080p`         |
| `doubao-seedance-2.0`      | `480p`, `720p`, `1080p` |
| `doubao-seedance-2-0-fast` | `480p`, `720p`, `1080p` |
| `doubao-seedance-2-0-mini` | `480p`, `720p`, `1080p` |
| `doubao-seedance-2-5`      | `480p`, `720p`          |

Seedance 不支援 `4k`.

若請求不支援的解析度，API 可能傳回：

`400 unsupported_resolution`

遭此驗證拒絕的請求不會產生生成費用。

#### Seedance 輸出解析度

對於 Seedance，請求的 `resolution` 決定計費級別，但實際輸出解析度由模型服務決定。

生成完成後，請使用 `resolution` 任務回應中的欄位，以取得實際輸出解析度。

***

### 🔄 查詢任務狀態

建立影片任務後，使用傳回的任務 ID：

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

#### 任務狀態

| 狀態          | 含義      |
| ----------- | ------- |
| `queued`    | 在佇列中等待  |
| `running`   | 生成進行中   |
| `succeeded` | 生成已成功完成 |
| `failed`    | 生成失敗    |
| `cancelled` | 任務已取消   |
| `expired`   | 任務已過期   |

當任務處於以下狀態時，持續輪詢 `queued` 或 `running`.

### 📦 成功的任務回應

成功的回應可能如下所示：

```json
{
  "id": "task_xxxxxx",
  "status": "succeeded",
  "model": "happyhorse-1.0",
  "content": {
    "video_url": "https://cdn.example.com/result.mp4"
  },
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}
```

使用 `content.video_url` 以在傳回時存取生成結果。

### ❌ 任務失敗回應

失敗的任務可能如下所示：

```json
{
  "id": "task_xxxxxx",
  "status": "failed",
  "model": "happyhorse-1.0",
  "error": {
    "code": "InvalidParameter",
    "message": "參數無效。"
  }
}
```

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

***

### 🕘 查看最近生成的影片

使用：

`GET /v1/videos`

以擷取最近成功生成的影片。

範例：

```bash
curl "https://gw.apismart.ai/v1/videos?page=1&page_size=20" \
  -H "Authorization: Bearer <your-api-key>"
```

#### 查詢參數

| 參數          |  預設值 | 說明           |
| ----------- | ---: | ------------ |
| `page`      |  `1` | 頁碼           |
| `page_size` | `20` | 每頁記錄數，最多 100 |

影片歷史記錄可包含：

* 生成 ID
* 任務 ID
* 模型 ID
* 影片 URL
* 時長
* 解析度
* 成本
* 建立時間
* 儲存狀態

只包含成功生成的影片。

目前可查詢最近 **7 天**.

請將重要的生成影片儲存到您自己的儲存空間，而不要只依賴歷史記錄的可用性。

***

### 👤 已驗證真人素材

Seedance 也支援已驗證真人素材工作流程，用於授權的真人影片生成。

此進階工作流程使用：

`POST /seedance-gateway`

典型流程如下：

1. 建立驗證工作階段。
2. 完成行動裝置驗證流程。
3. 取得產生的 `GroupId`.
4. 建立已驗證素材。
5. 等待素材狀態變為 `啟用中`.
6. 使用以下方式參照素材： `asset://asset_id` 於 Seedance 影片請求中。

範例：

```json
{
  "model": "doubao-seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "圖片1中的人物介紹圖片2中的產品，近景鏡頭"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-2026xxxxxx"
      },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/product.jpg"
      },
      "role": "reference_image"
    }
  ],
  "duration": 8,
  "resolution": "720p",
  "generate_audio": true
}
```

已驗證素材是以帳戶為單位的。 `asset://` 參照必須屬於發出影片請求的帳戶。

由於真人素材管理涉及獨立的驗證與素材生命週期，若您大量使用此功能，建議另外記錄完整工作流程。

***

### ⚠️ 常見問題

#### 無效的 API Key

`401 invalid_api_key`

請確認：

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

#### 餘額不足

`402 insufficient_quota`

請先加值後再重試請求。

#### 模型不可用

`403 model_not_allowed`

所選影片模型未為您的帳戶或 API Key 啟用。

#### 不支援的影片模型

`403 model_not_video_capable`

所選模型無法用於影片生成 API。

#### 不支援的解析度

`400 unsupported_resolution`

所要求的解析度不受所選模型支援。

#### 暫時性服務錯誤

`502`, `503`，以及 `504` 可能表示供應商、閘道或相依服務的暫時性問題。

對於暫時性失敗，請使用適當的重試策略。

***

### ✅ 在建立影片任務前

請確認：

* 您的 API Key 有效且已啟用
* 您的帳戶餘額充足
* 模型 ID 正確
* 所選模型支援您的輸入類型
* `resolution` 受該模型支援
* `duration` 在適當時已明確設定
* Seedance 參照素材維持在支援限制內
* `reference_audio` 未單獨使用
* 您的應用程式已準備好輪詢非同步任務狀態
* 您了解所選影片模型的計費方式

### ➡️ 下一步

接著請查看：

* [**模型與模型 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) — 排解失敗的影片請求