> 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

使用影片生成 API，搭配支援的 ApiSmart 影片模型來建立影片。

影片生成是非同步的：請先建立任務，然後使用回傳的 **任務 ID** 來檢查其狀態，直到生成成功或失敗。

關於 API 基礎 URL、驗證與一般請求規則，請參閱 [**API 基礎**](/documentation/zh-tw/api-zhi-nan/api-ji-chu.md).

***

### API 端點

#### 建立影片任務

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

#### 檢查任務狀態

```
GET https://gw.apismart.ai/v1/video/tasks/{task_id}
```

必要標頭：

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

> ⚠️ **重要：** 影片模型可能會使用不同的請求欄位與支援值。請務必始終遵循所選模型的 **程式碼範例**.

***

### 影片生成的運作方式

典型流程如下：

```
建立影片任務
       ↓
接收任務 ID
       ↓
檢查任務狀態
       ↓
取得生成的影片
```

初始請求通常是建立任務，而不是立即回傳已完成的影片。

***

### 建立影片任務

請求結構因模型而異。

某些模型可能會使用一個 `content` 陣列：

```json
{
  "model": "YOUR_MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "一隻貓在日落時分的海灘上奔跑"
    }
  ],
  "duration": 4,
  "resolution": "720p"
}
```

其他模型可能會使用如下欄位，例如 `prompt`, `duration`，與 `size`:

```json
{
  "model": "YOUR_MODEL_ID",
  "prompt": "夜晚的微縮城市",
  "duration": 5,
  "size": "720P"
}
```

不要假設像 `content` 與 `prompt`，或 `resolution` 與 `size`這類欄位是可互換的。

***

### 常見請求欄位

可用參數取決於所選模型。

| 欄位                    | 說明                |
| --------------------- | ----------------- |
| `model`               | 要使用的精確模型 ID       |
| `prompt`              | 某些影片模型使用的文字提示     |
| `content`             | 某些模型使用的結構化文字或媒體輸入 |
| `duration`            | 請求的影片時長           |
| `resolution` / `size` | 輸出解析度或尺寸          |
| `比例`                  | 長寬比，若支援           |
| `浮水印`                 | 浮水印設定，若支援         |

模型也可能支援圖片、影片、音訊或其他參考輸入。

僅使用模型中顯示的欄位與值 **程式碼範例**.

***

### 檢查任務狀態

建立任務後，請保存回傳的任務 ID：

```python
task_id = result["id"]
```

接著檢查其狀態：

```python
import requests

response = requests.get(
    f"https://gw.apismart.ai/v1/video/tasks/{task_id}",
    headers={
        "Authorization": f"Bearer {api_key}"
    },
    timeout=60,
)

response.raise_for_status()
result = response.json()

print(result.get("status"))
```

任務可能會回傳如下狀態：

```
處理中
成功
失敗
```

請以合理的間隔持續檢查，直到任務達到最終狀態。

成功的回應可能會在模型特定的回應欄位中包含生成的影片 URL。

***

### 了解影片計費

影片定價可能取決於：

* 生成時長
* 解析度
* 輸入類型
* 模型版本
* 其他模型特定設定

例如：

```
720P： $0.145/秒
1080P：$0.24/秒
```

在建立大量工作負載之前，請務必檢視所選模型的 **價格設定** 。

詳情請參閱 **了解模型定價與計費**.

***

### 🛠️ 常見問題

| 問題          | 檢查項目                       |
| ----------- | -------------------------- |
| **驗證失敗**    | API 權杖狀態與 Bearer 標頭        |
| **找不到模型**   | 精確的模型 ID 與大小寫              |
| **無效的請求**   | 必要欄位和模型特定參數名稱              |
| **不支援的值**   | 時長、解析度、比例或其他支援的選項          |
| **任務仍在處理中** | 請等待並以合理間隔持續檢查              |
| **任務失敗**    | 錯誤訊息、請求欄位、餘額與 API Token 配額 |

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

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

> 🔐 絕不要向支援提供你的完整 API Token。

***

### 🚀 下一步

繼續進行：

* [**選擇模型並尋找其模型 ID**](/documentation/zh-tw/mo-xing-yu-ding-jia/mo-xing-yu-mo-xing-id.md)
* [**了解模型定價與計費**](/documentation/zh-tw/mo-xing-yu-ding-jia/mo-xing-ding-jia-yu-ji-fei.md)
* [**圖片生成 API**](/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md)
* [**使用紀錄與成本**](/documentation/zh-tw/api-shi-yong/shi-yong-ji-lu-yu-fei-yong.md)