> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 影片生成介面

>  AiHubMix 提供統一的影片生成 API，相容 OpenAI Sora 介面格式，後端支援多家廠商模型

## 快速開始

影片生成是非同步操作，整個流程分為三步：

```text theme={null}
1. 提交任務 → 取得 video_id
2. 輪詢狀態 → 等待 status 變為 completed
3. 下載影片 → 取得 MP4 檔案
```

**最簡範例**

```shellscript theme={null}
# 第一步：提交影片生成任務
curl -X POST https://aihubmix.com/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A cat playing jazz on a piano, warm lighting, cinematic shot",
    "seconds": "5",
    "size": "1280x720"
  }'

# 回應範例：
# {
#   "id": "eyJtb2RlbCI6IndhbjI...",
#   "object": "video",
#   "status": "in_progress",
#   "model": "wan2.6-t2v",
#   "duration": 5,
#   "width": 1280,
#   "height": 720,
#   ...
# }

# 第二步：輪詢查詢狀態（每 15 秒查詢一次，直到 status 為 completed）
curl https://aihubmix.com/v1/videos/{video_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 第三步：下載影片
curl https://aihubmix.com/v1/videos/{video_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output video.mp4
```

## 介面總覽

| 介面   | 方法     | 路徑                              | 說明           |
| :--- | :----- | :------------------------------ | :----------- |
| 建立影片 | POST   | `/v1/videos`                    | 提交影片生成任務     |
| 查詢狀態 | GET    | `/v1/videos/{video_id}`         | 查詢任務狀態與進度    |
| 下載影片 | GET    | `/v1/videos/{video_id}/content` | 下載生成的 MP4 影片 |
| 刪除任務 | DELETE | `/v1/videos/{video_id}`         | 刪除影片任務       |

Base URL：`https://aihubmix.com`

認證方式：Bearer Token

```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
```

## 支援的模型

### 文生影片（Text-to-Video）

| 廠商     | 模型名稱                                                    | 特點                               |
| ------ | ------------------------------------------------------- | -------------------------------- |
| OpenAI | `sora-2`                                                | 標準影片生成，支援音畫同步                    |
| OpenAI | `sora-2-pro`                                            | 高品質版本，更精緻穩定的畫面                   |
| Google | `veo-3.1-generate-preview`                              | 最新 Veo 3.1，原生音訊，支援 4K            |
| Google | `veo-3.1-fast-generate-preview`                         | Veo 3.1 快速版，生成速度更快               |
| Google | `veo-3.0-generate-preview`                              | Veo 3.0，高保真影片                    |
| Google | `veo-2.0-generate-001`                                  | Veo 2.0，穩定版                      |
| 阿里     | `wan2.6-t2v`                                            | 通義萬相最新版，音畫同步                     |
| 阿里     | `wan2.5-t2v-preview`                                    | 通義萬相 2.5，中文最佳化                   |
| 阿里     | `wan2.2-t2v-plus`                                       | 通義萬相 2.2                         |
| 字節     | `jimeng-3.0-pro`                                        | 即夢 3.0 Pro，1080P 高清              |
| 字節     | `jimeng-3.0-1080p`                                      | 即夢 3.0 1080P                     |
| 字節     | `doubao-seedance-2-0-260128`                            | 專業級多模態創作影片模型 Seedance 2.0        |
| 字節     | `doubao-seedance-2-0-fast-260128`                       | Seedance 2.0 快速版                 |
| 快手     | `kling-v3`、`kling-v2-6`、`kling-v2-5-turbo`、`kling-v2-1` | 可靈 Kling 文生/圖生，新版支援 3\~15 秒      |
| 快手     | `kling-v3-omni`、`kling-video-o1`                        | 可靈 OmniVideo 多模態，支援參考影片、原生音訊、多鏡頭 |

### 圖生影片（Image-to-Video）

| 廠商 | 模型名稱                              | 特點                       |
| -- | --------------------------------- | ------------------------ |
| 阿里 | `wan2.6-i2v`                      | 通義萬相最新版圖生影片              |
| 阿里 | `wan2.5-i2v-preview`              | 通義萬相 2.5 圖生影片            |
| 阿里 | `wan2.2-i2v-plus`                 | 通義萬相 2.2 圖生影片            |
| 字節 | `doubao-seedance-2-0-260128`      | 多模態參考輸入，支援圖片/影片/音訊       |
| 字節 | `doubao-seedance-2-0-fast-260128` | Seedance 2.0 快速版         |
| 快手 | `kling-v1-6` 等                    | 可靈圖生影片，支援尾幀、多圖參考（最多 4 張） |

<Note>
  圖生影片需透過 `input_reference` 參數傳入參考圖片（阿里通義萬相）；豆包 Seedance 透過 `extra_body.content` 陣列傳入，支援圖片、影片、音訊多種參考類型；可靈 Kling 使用 `image` / `image_tail` / `image_list` 傳圖，詳見下方[可靈 Kling](#可靈-kling) 小節。
</Note>

## API 詳細說明

### 請求標頭

```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
Content-Type: application/json
```

### 建立影片生成任務

```shellscript theme={null}
POST /v1/videos
```

#### **請求主體**

| 參數                | 類型            | 必填 | 說明                                     |
| :---------------- | :------------ | :- | :------------------------------------- |
| `model`           | string        | 是  | 模型名稱，如 `wan2.6-t2v`、`sora-2`           |
| `prompt`          | string        | 是  | 影片描述文字                                 |
| `seconds`         | string        | 否  | 影片時長（秒），統一使用字串類型，如 `"5"`、`"8"`（見各模型詳解） |
| `size`            | string        | 否  | 解析度，格式 `寬x高`，如 `1920x1080`（各模型支援值不同）   |
| `input_reference` | string/object | 否  | 參考圖片（圖生影片），支援 URL 或 base64             |

> 不同模型的回應格式略有差異，但都包含 `id`（video\_id）和 `status` 欄位。以 `status` 判斷任務進度即可。

#### 回應範例（**通義萬相/Veo/即夢AI**）

```json theme={null}
{
  "id": "eyJtb2RlbCI6IndhbjI...",
  "object": "video",
  "created": 1772460274,
  "model": "wan2.6-t2v",
  "status": "in_progress",
  "prompt": "A cat watching the rain on a windowsill",
  "duration": 5,
  "width": 1920,
  "height": 1080,
  "url": null,
  "error": null
}
```

**回應範例（Sora）**

```json theme={null}
{
  "id": "eyJtb2RlbCI6InNvcmEtMi...",
  "object": "video",
  "created_at": 1772451930,
  "status": "queued",
  "model": "sora-2",
  "progress": 0,
  "prompt": "A cinematic drone shot over mountains",
  "seconds": "8",
  "size": "1280x720"
}
```

#### 通用狀態值說明

| 狀態            | 說明           |
| :------------ | :----------- |
| `queued`      | 排隊中（Sora 特有） |
| `in_progress` | 生成中          |
| `completed`   | 生成完成，可以下載    |
| `failed`      | 生成失敗         |

### 查詢影片狀態

```shellscript theme={null}
GET /v1/videos/{video_id}
```

輪詢此介面檢查任務是否完成。建議每 **15 秒** 查詢一次。

#### **回應範例（生成完成 - 通義萬相）**

```json theme={null}
{
  "id": "eyJtb2RlbCI6IndhbjI...",
  "object": "video",
  "status": "completed",
  "model": "wan2.5-t2v-preview",
  "duration": 5,
  "width": 1920,
  "height": 1080,
  "url": "https://aihubmix.com/v1/videos/eyJtb2RlbCI6IndhbjI.../content",
  "error": null
}
```

#### **回應範例（生成完成 - Sora）**

```json theme={null}
{
  "id": "eyJtb2RlbCI6InNvcmEtMi...",
  "object": "video",
  "created_at": 1772451930,
  "status": "completed",
  "completed_at": 1772452114,
  "expires_at": 1772538330,
  "model": "sora-2",
  "progress": 100,
  "prompt": "A cinematic drone shot over mountains",
  "seconds": "8",
  "size": "1280x720"
}
```

> 所有模型均透過 `status == "completed"` 判斷完成狀態，然後呼叫 `/content` 介面下載。

### 下載影片內容

```shellscript theme={null}
GET /v1/videos/{video_id}/content
```

當狀態為 `completed` 後，呼叫此介面下載 MP4 影片檔案。

**回應**: 直接回傳影片二進位串流（`Content-Type: video/mp4`）。

```shellscript theme={null}
curl https://aihubmix.com/v1/videos/{video_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output my_video.mp4
```

> **注意**：影片下載連結通常有 24 小時有效期，請及時下載儲存。

### 刪除影片任務

此介面用於刪除已建立的影片任務。

```shellscript theme={null}
DELETE /v1/videos/{video_id}
```

## 各模型參數詳解

### **OpenAI Sora**

| 參數           | 支援值                                               |
| ------------ | ------------------------------------------------- |
| 模型           | `sora-2`、`sora-2-pro`                             |
| 時長 (seconds) | `"4"`（預設）、`"8"`、`"12"`                            |
| 解析度 (size)   | `720x1280`（預設）、`1280x720`、`1024x1792`、`1792x1024` |
| 圖生影片         | 支援，透過 `input_reference` 傳入圖片                      |

> 提示：所有模型的 `seconds` 參數統一使用字串類型傳入（如 `"8"`）。

**範例**

<CodeGroup>
  ```shellscript Sora theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sora-2",
      "prompt": "A cinematic drone shot soaring over a misty mountain range at sunrise, golden light filtering through the clouds",
      "seconds": "8",
      "size": "1280x720"
    }'
  ```

  ```shellscript Sora Pro 直版影片 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sora-2-pro",
      "prompt": "A person walking through a neon-lit city street at night, rain reflecting on the pavement, cinematic lighting",
      "seconds": "12",
      "size": "720x1280"
    }'
  ```
</CodeGroup>

### Google Veo

| 參數            | 支援值                                                                                                                                                                                                                                 |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 模型            | `veo-3.1-generate-preview`（推薦）、`veo-3.1-fast-generate-preview`（快速）、`veo-3.0-generate-preview`、`veo-2.0-generate-001`                                                                                                                |
| 時長 (seconds)  | Veo 3/3.1：`"4"`、`"6"`、`"8"`；Veo 2：`"5"`\~`"8"`（預設 `"8"`）                                                                                                                                                                            |
| 解析度 (size)    | `720p`（預設）、`1080p`、`4k`（4K 僅 Veo 3+），或像素格式如 `1280x720`、`1920x1080`                                                                                                                                                                  |
| 寬高比           | 16:9（預設）、9:16                                                                                                                                                                                                                       |
| 圖生影片（Veo 3.1） | **首幀**：`first_frame`（或相容欄位 `input_reference`）；**尾幀**：`last_frame`；**參考圖**：`reference_images`（陣列，最多 3 張）。圖片支援公網 URL、base64 dataURL、`{"mime_type": "...", "data": "..."}` 物件。**時長**：首幀/首尾幀支援 `"4"`/`"6"`/`"8"`；使用參考圖時 Google 固定輸出 8 秒 |

**範例**

<CodeGroup>
  ```shellscript Veo 3.1 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-generate-preview",
      "prompt": "A tranquil Japanese garden, cherry blossom petals slowly drifting down, koi swimming in the pond, with the melodious sound of wind chimes in the background",
      "seconds": "8",
      "size": "1280x720"
    }'
  ```

  ```shellscript Veo 3.1 Fast theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-fast-generate-preview",
      "prompt": "Ocean waves crashing on rocky cliffs at sunset, seagulls flying overhead",
      "seconds": "8",
      "size": "1280x720"
    }'
  ```

  ```shellscript 首尾幀（圖生影片） theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-generate-preview",
      "prompt": "The camera slowly pushes in from a valley at dawn, transitioning naturally into sunset",
      "seconds": "8",
      "size": "1280x720",
      "first_frame": "https://example.com/first.jpg",
      "last_frame": "https://example.com/last.jpg"
    }'
  ```

  ```shellscript 參考圖（圖生影片，最多 3 張） theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-generate-preview",
      "prompt": "The character from the reference images walks through a forest, cinematic shot",
      "seconds": "8",
      "size": "1280x720",
      "reference_images": [
        "https://example.com/ref1.jpg",
        "https://example.com/ref2.jpg"
      ]
    }'
  ```
</CodeGroup>

<Note>
  **圖片欄位說明**：

  * 首幀優先級：`first_frame` > `input_reference`（OpenAI 相容單幀）。
  * `first_frame` / `last_frame` / `reference_images` 每個元素均支援：公網 URL、base64 dataURL（`data:image/png;base64,...`）、或 `{"mime_type":"image/png","data":"<base64>"}` 物件。
  * 也相容 OpenRouter 風格的 `frame_images`（元素帶 `frame_type: first_frame | last_frame`）與 `input_references` 別名。
  * 參考圖最多 3 張，超出返回 400。
</Note>

> 提示：Veo 支援原生音訊生成，可在 prompt 中描述音效，如「背景傳來鳥鳴聲」、「鋼琴旋律」。

### 通義萬相

| 參數           | 支援值                                                     |
| ------------ | ------------------------------------------------------- |
| 文生影片模型       | `wan2.6-t2v`（推薦）、`wan2.5-t2v-preview`、`wan2.2-t2v-plus` |
| 圖生影片模型       | `wan2.6-i2v`（推薦）、`wan2.5-i2v-preview`、`wan2.2-i2v-plus` |
| 時長 (seconds) | 因模型而異（見下方說明），預設 `"5"`                                   |
| 解析度 (size)   | 見下方表格，`x` 和 `*` 分隔符均可（如 `1920x1080` 或 `1920*1080`）      |
| 圖生影片         | 透過 `input_reference` 傳入圖片 URL 或 base64                  |

**各模型支援的時長**

| 模型                                          | seconds 可選值          | 預設值   |
| :------------------------------------------ | :------------------- | :---- |
| `wan2.6-t2v` / `wan2.6-i2v`                 | `"2"`\~`"15"`（任意整數值） | `"5"` |
| `wan2.5-t2v-preview` / `wan2.5-i2v-preview` | `"5"` 或 `"10"`       | `"5"` |
| `wan2.2-t2v-plus` / `wan2.2-i2v-plus`       | `"5"`（固定）            | `"5"` |

**支援的解析度（寬\*高）**

| 清晰度   | 可選解析度                                                                 |
| :---- | :-------------------------------------------------------------------- |
| 480P  | `832x480`、`480x832`、`624x624`                                         |
| 720P  | `1280x720`（預設）、`720x1280`、`960x960`、`1088x832`（4:3）、`832x1088`（3:4）   |
| 1080P | `1920x1080`、`1080x1920`、`1440x1440`、`1632x1248`（4:3）、`1248x1632`（3:4） |

> **注意**：wan2.6 僅支援 720P 和 1080P；wan2.5 支援 480P、720P、1080P；wan2.2 僅支援 480P 和 1080P。

**範例**

<CodeGroup>
  ```shellscript 文生影片 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "wan2.6-t2v",
      "prompt": "A winding stream flows through an autumn forest, golden fallen leaves drifting on the water surface, sunlight casting dappled light and shadow through the leaves",
      "seconds": "5",
      "size": "1920x1080"
    }'
  ```

  ```shellscript 圖生影片 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "wan2.6-i2v",
      "prompt": "The character in the frame slowly turns their head and smiles, the camera slowly pushes in",
      "seconds": "5",
      "size": "1280x720",
      "input_reference": "https://example.com/my-image.jpg"
    }'
  ```
</CodeGroup>

> 提示：wan2.5 及以上版本預設生成有聲影片（自動配音），中文 prompt 效果更佳。

### 即夢 AI

| 參數           | 支援值                                       |
| ------------ | ----------------------------------------- |
| 模型           | `jimeng-3.0-pro`（推薦）、`jimeng-3.0-1080p`   |
| 時長 (seconds) | `"5"` 或 `"10"`（預設 `"5"`）                  |
| 解析度 (size)   | 支援寬高比格式或像素格式                              |
| 圖生影片         | 支援，透過 `input_reference` 傳入圖片 URL 或 base64 |

**支援的寬高比與對應解析度**

| 寬高比 (size)           | 實際解析度     |
| :------------------- | :-------- |
| `16:9` 或 `1920x1080` | 1920×1088 |
| `9:16` 或 `1080x1920` | 1088×1920 |
| `4:3` 或 `1664x1248`  | 1664×1248 |
| `3:4` 或 `1248x1664`  | 1248×1664 |
| `1:1` 或 `1440x1440`  | 1440×1440 |
| `21:9` 或 `2176x928`  | 2176×928  |

**範例**

<CodeGroup>
  ```shellscript 即夢 AI theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "jimeng-3.0-pro",
      "prompt": "A young woman in Hanfu dances gracefully amid a bamboo forest, her long dress flowing in the wind, with a faint morning mist in the background",
      "seconds": "5",
      "size": "16:9"
    }'
  ```

  ```即夢 AI 直屏版 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "jimeng-3.0-1080p",
      "prompt": "A sunset over the ocean, waves gently rolling, warm golden light",
      "seconds": "5",
      "size": "9:16"
    }'
  ```
</CodeGroup>

### 豆包 Seedance

| 參數                     | 支援值                                                                      |
| ---------------------- | ------------------------------------------------------------------------ |
| 模型                     | `doubao-seedance-2-0-260128`、`doubao-seedance-2-0-fast-260128`           |
| 解析度 (resolution)       | `"480p"`、`"720p"`（預設）                                                    |
| 時長 (duration)          | 整數，範圍 `4`\~`15`，或 `-1`（模型自動決定）                                           |
| 寬高比 (ratio)            | `"adaptive"`（預設，自動適配）、`"16:9"`、`"9:16"`、`"1:1"`、`"4:3"`、`"3:4"`、`"21:9"` |
| 有聲影片 (generate\_audio) | 預設 `true`；設為 `false` 生成無聲影片                                              |
| 浮水印 (watermark)        | 預設 `false`                                                               |
| 多模態參考                  | 支援圖片、影片、音訊                                                               |

**`extra_body.content` 支援的引用類型**

| 類型   | `type` 值    | `role` 值          | 說明        |
| ---- | ----------- | ----------------- | --------- |
| 參考圖片 | `image_url` | `reference_image` | 畫面/風格參考圖片 |
| 參考影片 | `video_url` | `reference_video` | 運鏡/構圖參考影片 |
| 參考音訊 | `audio_url` | `reference_audio` | 背景音樂音訊檔案  |

**範例**

```shellscript Seedance 2.0 / 2.0 Fast theme={null}
curl -X POST "https://aihubmix.com/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "Use the first-person POV framing from Video 1 throughout, and use Audio 1 as the background music for the entire clip. Create a first-person fruit tea commercial featuring the Seedance brand limited-edition apple fruit tea, "Ping Ping An An." 

Opening frame: Image 1. From a first-person perspective, your hand picks a dew-covered Aksu red apple, accompanied by a crisp, satisfying bite-like tapping sound.

Seconds 2–4: Fast-paced cuts. Your hand drops freshly cut apple chunks into a shaker, adds ice and tea base, then shakes vigorously. The sound of ice clinking and shaking syncs with upbeat percussion. Background voiceover: "Freshly cut, freshly shaken."

Seconds 4–6: First-person close-up of the finished drink. The layered fruit tea is poured into a clear cup. Your hand gently squeezes a creamy topping across the surface. A pink label is placed on the cup. The camera pushes in to highlight the rich texture and layering.

Seconds 6–8: First-person hand holding the drink. You raise the fruit tea from Image 2 toward the camera, as if offering it directly to the viewer. The label is clearly visible. Background voiceover: "Take a refreshing sip."

Final frame: Freeze on Image 2. 

All background voiceovers should be in a female voice.",
    "extra_body": {
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
          },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
          },
          "role": "reference_image"
        },
        {
          "type": "video_url",
          "video_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
          },
          "role": "reference_video"
        },
        {
          "type": "audio_url",
          "audio_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
          },
          "role": "reference_audio"
        }
      ],
      "ratio": "16:9",
      "duration": 11,
      "watermark": false
    }
  }'
```

### 可靈 Kling

可靈（Kling）支援 **文生影片、圖生影片、多圖參考生影片、OmniVideo 多模態** 四類能力，統一透過 `/v1/videos` 介面呼叫，閘道按「模型名 + 輸入形態」自動路由到可靈對應端點，無需呼叫方區分。

| 能力            | 模型                                                                                           |
| ------------- | -------------------------------------------------------------------------------------------- |
| 文生 / 圖生       | `kling-v1`、`kling-v1-5`、`kling-v1-6`、`kling-v2-1`、`kling-v2-5-turbo`、`kling-v2-6`、`kling-v3` |
| 多圖參考          | `kling-v1-6`                                                                                 |
| OmniVideo 多模態 | `kling-video-o1`、`kling-v3-omni`                                                             |

**參數**

| 參數                     | 類型     | 說明                                                                                                             |
| ---------------------- | ------ | -------------------------------------------------------------------------------------------------------------- |
| `model`                | string | **必填**，`kling-*`，決定能力與版本                                                                                       |
| `prompt`               | string | 文字提示詞                                                                                                          |
| `negative_prompt`      | string | 負向提示詞                                                                                                          |
| `mode`                 | string | 生成模式：`std`（720P）/ `pro`（1080P）/ `4k`，預設 `std`                                                                  |
| `duration` / `seconds` | string | 時長（秒），舊模型 `5`/`10`，新模型 `3`\~`15`，預設 `5`                                                                        |
| `aspect_ratio`         | string | 畫幅：`16:9` / `9:16` / `1:1`（omni 純文生、影片參考時必填，缺省自動補 `16:9`）                                                      |
| `cfg_scale`            | float  | 提示詞相關性 `[0, 1]`，預設 `0.5`（`kling-v2.x` 不支援）                                                                     |
| `image`                | string | **圖生**：單圖，圖片 URL 或 Base64（Base64 不帶 `data:image/...;base64,` 前綴）                                               |
| `image_tail`           | string | **圖生**：尾幀圖（可選）                                                                                                 |
| `image_list`           | array  | **多圖參考**：圖片 URL 陣列，最多 4 張                                                                                      |
| `sound`                | string | **omni**：`on`/`off`，是否生成原生音訊，預設 `off`                                                                          |
| `video_list`           | array  | **omni**：參考影片 `[{ "video_url": "...", "refer_type": "feature" }]`，`refer_type` 取 `feature`（影片參考）/ `base`（影片編輯） |

<Note>
  不支援或未對應的關鍵參數會明確報錯，不會靜默丟棄。其餘可靈原生參數可放進 `extra_body` 透傳到上游。
</Note>

**範例**

<CodeGroup>
  ```shellscript 文生影片 theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v1-6",
      "prompt": "An orange cat running on a sunlit grassy meadow",
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript 圖生影片 theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v1-6",
      "image": "https://example.com/first.png",
      "prompt": "The camera pulls back, the character smiles",
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript 多圖參考 theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v1-6",
      "image_list": ["https://example.com/a.png", "https://example.com/b.png"],
      "prompt": "Two characters meet on the street",
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript OmniVideo 參考影片 theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v3-omni",
      "prompt": "Generate the next shot based on the reference video",
      "video_list": [{ "video_url": "https://example.com/in.mp4", "refer_type": "feature" }],
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript OmniVideo 原生音訊 theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v3-omni",
      "prompt": "A man smiles and says hello",
      "sound": "on",
      "aspect_ratio": "16:9",
      "duration": "5"
    }'
  ```
</CodeGroup>

**說明**

* **非同步三步**：提交取得 `video_id` → 輪詢 `GET /v1/videos/{video_id}` 至 `status` 為 `completed` → `GET /v1/videos/{video_id}/content` 下載 MP4。狀態值：`in_progress` / `completed` / `failed`。
* 出片通常 1\~3 分鐘；結果影片 URL **30 天後清理**，請及時轉存。
* **刪除任務**：可靈無刪除介面，`DELETE /v1/videos/{video_id}` 回傳 `501 not_supported`。
* **計費**：按 模型 × `mode` × 時長 × 能力（有無參考影片 / 有聲）扣費；**生成失敗不扣費**，查詢與下載不計費。

## **完整呼叫範例**

<CodeGroup>
  ```python 通義萬相 theme={null}
  import requests
  import time

  API_KEY = "AIHUBMIX_API_KEY"
  BASE_URL = "https://aihubmix.com"
  HEADERS = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  # 第一步：建立影片生成任務
  response = requests.post(
      f"{BASE_URL}/v1/videos",
      headers=HEADERS,
      json={
          "model": "wan2.6-t2v",
          "prompt": "A desert under a starry sky, a meteor streaking across the night sky, the glow of a distant campfire flickering in the breeze",
          "seconds": "5",
          "size": "1920x1080"
      }
  )
  result = response.json()
  video_id = result["id"]
  print(f"任務已建立，video_id: {video_id}")

  # 第二步：輪詢查詢狀態
  while True:
      status_response = requests.get(
          f"{BASE_URL}/v1/videos/{video_id}",
          headers=HEADERS
      )
      status_data = status_response.json()
      current_status = status_data["status"]
      print(f"目前狀態: {current_status}")

      if current_status == "completed":
          print("影片生成完成！")
          break
      elif current_status == "failed":
          error_msg = status_data.get("error", {})
          if isinstance(error_msg, dict):
              error_msg = error_msg.get("message", "未知錯誤")
          print(f"生成失敗: {error_msg}")
          break

      time.sleep(15)  # 每 15 秒查詢一次

  # 第三步：下載影片
  video_response = requests.get(
      f"{BASE_URL}/v1/videos/{video_id}/content",
      headers=HEADERS
  )
  with open("output.mp4", "wb") as f:
      f.write(video_response.content)
  print(f"影片已儲存為 output.mp4（{len(video_response.content) / 1024 / 1024:.1f} MB）")
  ```

  ```python Sora theme={null}
  import requests
  import time

  API_KEY = "AIHUBMIX_API_KEY"
  BASE_URL = "https://aihubmix.com"
  HEADERS = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  # 建立影片生成任務
  response = requests.post(
      f"{BASE_URL}/v1/videos",
      headers=HEADERS,
      json={
          "model": "sora-2",
          "prompt": "A cinematic shot of a futuristic city at sunset, flying cars in the background",
          "seconds": "8",       # 可選 "4"/"8"/"12"
          "size": "1280x720"    # 支援 1280x720, 720x1280, 1024x1792, 1792x1024
      }
  )
  result = response.json()
  video_id = result["id"]
  print(f"任務已建立，video_id: {video_id}")

  # Sora 狀態輪詢（可能出現 queued -> in_progress -> completed）
  while True:
      status_response = requests.get(
          f"{BASE_URL}/v1/videos/{video_id}",
          headers=HEADERS
      )
      status_data = status_response.json()
      current_status = status_data["status"]
      progress = status_data.get("progress", "")
      print(f"狀態: {current_status}, 進度: {progress}%")

      if current_status == "completed":
          print("影片生成完成！")
          break
      elif current_status == "failed":
          print(f"生成失敗: {status_data.get('error')}")
          break

      time.sleep(15)

  # 下載影片
  video_response = requests.get(
      f"{BASE_URL}/v1/videos/{video_id}/content",
      headers=HEADERS
  )
  with open("sora_output.mp4", "wb") as f:
      f.write(video_response.content)
  print("影片已儲存為 sora_output.mp4")
  ```

  ```javascript Node.js theme={null}
  const API_KEY = "your_aihubmix_api_key";
  const BASE_URL = "https://aihubmix.com";

  async function generateVideo() {
    // 第一步：建立任務（以 Veo 3.1 為例）
    const createResponse = await fetch(`${BASE_URL}/v1/videos`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        model: "veo-3.1-generate-preview",
        prompt: "A desert under a starry sky, with a meteor streaking across the night.",
        seconds: "8",
        size: "1280x720"
      })
    });
    const { id: videoId } = await createResponse.json();
    console.log(`任務已建立: ${videoId}`);

    // 第二步：輪詢狀態
    let status = "in_progress";
    while (status !== "completed" && status !== "failed") {
      await new Promise(resolve => setTimeout(resolve, 15000));
      const statusResponse = await fetch(`${BASE_URL}/v1/videos/${videoId}`, {
        headers: { "Authorization": `Bearer ${API_KEY}` }
      });
      const result = await statusResponse.json();
      status = result.status;
      console.log(`目前狀態: ${status}`);
    }

    if (status === "completed") {
      // 第三步：下載影片
      const videoResponse = await fetch(`${BASE_URL}/v1/videos/${videoId}/content`, {
        headers: { "Authorization": `Bearer ${API_KEY}` }
      });
      const fs = require("fs");
      const buffer = Buffer.from(await videoResponse.arrayBuffer());
      fs.writeFileSync("output.mp4", buffer);
      console.log("影片已儲存為 output.mp4");
    }
  }

  generateVideo();
  ```
</CodeGroup>

## **FAQ**

### **影片生成需要多長時間？**

影片生成通常需要 1-5 分鐘，具體時間取決於模型、解析度和時長。建議設定 15 秒的輪詢間隔。

### `input_reference` **參數怎麼用？**

`input_reference` 用於圖生影片場景，支援三種傳入方式：

```json theme={null}
// 方式一：直接傳入圖片 URL
"input_reference": "https://example.com/image.jpg"

// 方式二：傳入 base64 編碼的圖片（物件格式）
"input_reference": {
  "mime_type": "image/jpeg",
  "data": "<BASE64_ENCODED_IMAGE>"
}

// 方式三：傳入 data URL
"input_reference": "data:image/jpeg;base64,<BASE64_ENCODED_IMAGE>"
```

### **影片下載連結有效期是多久？**

生成的影片下載連結通常有 **24 小時** 有效期，請及時下載儲存。

### **各模型**`seconds` **參數有什麼區別？**

| 模型                                                     | 可選值                         | 預設值   |
| ------------------------------------------------------ | --------------------------- | ----- |
| Sora (`sora-2` / `sora-2-pro`)                         | `"4"`, `"8"`, `"12"`        | `"4"` |
| Veo 3/3.1 (`veo-3.1-generate-preview` 等)               | `"4"`, `"6"`, `"8"`         | `"8"` |
| Veo 2 (`veo-2.0-generate-001`)                         | `"5"`\~`"8"`                | `"8"` |
| 通義萬相 `wan2.6`                                          | `"2"`\~`"15"`               | `"5"` |
| 通義萬相 `wan2.5`                                          | `"5"`, `"10"`               | `"5"` |
| 通義萬相 `wan2.2`                                          | `"5"`（固定）                   | `"5"` |
| 即夢AI (`jimeng-3.0-pro` 等)                              | `"5"`, `"10"`               | `"5"` |
| 豆包 Seedance (`doubao-seedance-2-0-*`)                  | 整數 `duration4`\~`15` 或 `-1` | `5`   |
| 可靈 Kling 新版 (`kling-v2-x` / `kling-v3` 等)              | `"3"`\~`"15"`               | `"5"` |
| 可靈 Kling 舊版 (`kling-v1` / `kling-v1-5` / `kling-v1-6`) | `"5"`, `"10"`               | `"5"` |

\> **提示**：所有模型的 `seconds` 參數統一使用字串類型傳入（如 `"8"`），API 會自動處理。

### 不同模型`size` 參數格式有什麼區別？

| 模型          | 支援的 size 值                                                                             |
| ----------- | -------------------------------------------------------------------------------------- |
| Sora        | `1280x720720x12801024x17921792x1024`                                                   |
| Veo         | 像素格式`1280x720` 等）或解析度標籤`720p1080p4k`）                                                  |
| 通義萬相        | 像素格式`x` 和 `*` 均可（如 `1920x1080` 或 `1920*1080`）                                          |
| 即夢 AI       | 寬高比格式`16:99:16` 等）或像素格式                                                                |
| 豆包 Seedance | 寬高比格式（`"adaptive"`、`"16:9"`、`"9:16"` 等）                                                |
| 可靈 Kling    | 不使用 `size`，改用 `mode`（`std`/`pro`/`4k` 控制清晰度）+ `aspect_ratio`（`16:9`/`9:16`/`1:1` 控制畫幅） |

**###** `seconds` **和** `duration` **有什麼區別？**

兩者含義相同，均表示影片時長。API 同時支援這兩個參數名（Sora 除外，Sora 只接受 `seconds`）。推薦統一使用 `seconds`。

### 如何撰寫更好的 prompt？

* **描述具體場景**：包含主體、動作、環境、光線、氛圍
* **指定鏡頭語言**：如「特寫」、「航拍」、「推鏡頭」、「慢動作」
* **描述風格**：如「電影感」、「紀錄片風格」、「動畫風格」
* **中文模型用中文 prompt 效果更好**：通義萬相針對中文最佳化
* **Veo 支援音訊描述**：可在 prompt 中描述聲音，如「鳥鳴聲」、「鋼琴旋律」

### 任務失敗怎麼處理？

當 `status` 為 `failed` 時，回應中的 `error` 欄位會包含錯誤資訊：

```json theme={null}
{
  "status": "failed",
  "error": {
    "message": "Video generation failed due to content policy violation",
    "type": "video_generation_error"
  }
}
```

## 常見失敗原因包括：內容違規、prompt 過長、圖片格式不支援等。請根據錯誤資訊調整後重試。

更新時間：2026-06-01