# Veo 影片生成

來源: https://docs.aicentos.com/zh-TW/veo-video

Language: zh-TW

> 透過 aicentos 調用 Google Veo 影片生成模型 —— 文生影片、圖生影片、首尾影格、參考圖

本文面向開發者，說明如何透過 aicentos 調用 Google Veo 影片生成模型。介面為 OpenAI 影片 API 相容格式（OpenAI Videos API），下游接入時通道類型使用 `openai` 即可。

## 模型能力說明

按影片生成時長（秒）計費。具體單價以 aicentos 控制台為準，最終扣費以系統實際扣費記錄為準。

### 官方能力與 aicentos 開放口徑

| 模型                              | 支援秒數  | 支援解析度         | 畫面比例      | 音訊    | 說明                                        |
| ------------------------------- | ----- | ------------- | --------- | ----- | ----------------------------------------- |
| `veo-3.1-generate-preview`      | 4、6、8 | 720p、1080p、4k | 16:9、9:16 | 原生含音訊 | 1080p 和 4k 僅支援 8 秒；用參考圖、首尾影格等圖片能力時建議 8 秒。 |
| `veo-3.1-fast-generate-preview` | 4、6、8 | 720p、1080p、4k | 16:9、9:16 | 原生含音訊 | 1080p 和 4k 僅支援 8 秒；用參考圖、首尾影格等圖片能力時建議 8 秒。 |

參考文件：

* [Google Gemini API Veo 影片生成](https://ai.google.dev/gemini-api/video)
* [Veo 參考圖說明](https://ai.google.dev/gemini-api/video#reference_images)
* [Veo 首尾影格說明](https://ai.google.dev/gemini-api/video#first_and_last_frame)
* [Veo 畫面比例說明](https://ai.google.dev/gemini-api/video#aspect_ratio)

### 畫面比例

| 模型                              | 16:9 橫式 | 9:16 直式 | 預設比例 | 建議                   |
| ------------------------------- | ------- | ------- | ---- | -------------------- |
| `veo-3.1-generate-preview`      | 支援      | 支援      | 16:9 | 4K 必須用 8 秒；影片擴展暫不開放。 |
| `veo-3.1-fast-generate-preview` | 支援      | 支援      | 16:9 | 4K 必須用 8 秒；影片擴展暫不開放。 |

請求中可以透過 `metadata.aspectRatio` 或表單欄位 `aspectRatio` 指定比例：

```bash
{
  "metadata": {
    "aspectRatio": "9:16"
  }
}
```

如果沒有顯式傳 `aspectRatio`，系統會優先根據 `size` 推導比例，例如 `1280x720` 推導為 16:9、`720x1280` 推導為 9:16。如果 `size` 也未傳，上游預設使用 16:9。

### 音訊說明

| 模型                              | 官方音訊能力 | 支援 generateAudio | 建議                                    |
| ------------------------------- | ------ | ---------------- | ------------------------------------- |
| `veo-3.1-generate-preview`      | 原生含音訊  | 不支援              | 不要傳 `generateAudio`，需要聲音效果請寫進 prompt。 |
| `veo-3.1-fast-generate-preview` | 原生含音訊  | 不支援              | 不要傳 `generateAudio`，需要聲音效果請寫進 prompt。 |

Veo 3.1 系列是原生含音訊的影片模型，但目前 Gemini API 的 Veo 參數表沒有開放 `generateAudio` 作為可控參數。傳入該欄位可能會被上游回傳 `INVALID_ARGUMENT`。

如果希望控制音訊內容，可以在 prompt 中描述對白、環境音、音效或音樂風格，例如：

```bash
黃昏海邊的燈塔，海浪輕拍礁石，遠處有低沉的風聲和海鳥聲，電影級光影，穩定運鏡
```

## 圖片輸入能力

| 能力           | Google 官方 Veo 能力                   | aicentos 介面支援 | 說明                                                                                                |
| ------------ | ---------------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
| 單張初始圖生成影片    | 支援                                 | 支援            | 使用 `input_reference` 上傳 1 張圖片，作為影片起始畫面。                                                           |
| 首尾影格生成 / 插影格 | Veo 3.1 系列支援 image + lastFrame     | 支援            | 首影格用 `input_reference`，尾影格用 `last_frame` 或 `lastFrame`。建議 Veo 3.1 系列、8 秒。                         |
| 多張參考圖        | Veo 3.1 系列支援最多 3 張 referenceImages | 支援            | 用 `reference_image`、`reference_images` 或 `referenceImages` 上傳，`referenceType` 僅支援 `asset`。建議 8 秒。 |
| 影片擴展         | Veo 3.1 / Fast 支援擴展已有 Veo 影片       | 暫不支援          | 目前 aicentos 介面沒有開放官方 video 輸入。                                                                    |

* 圖片 MIME 類型支援 `image/jpeg`、`image/png`、`image/webp`。建議傳檔案或 Base64，不建議直接傳遠端圖片 URL。
* 參考圖模式注意：目前上游在參考圖場景不支援 `negativePrompt`，傳入後可能回傳 `Negative prompt is not supported in your use case`。參考圖請求請不要傳 `negativePrompt`。
* 實現說明：Gemini API 的 Veo `predictLongRunning` 圖片入參使用 `bytesBase64Encoded` + `mimeType`，不是普通 `generateContent` 的 `inlineData`。aicentos 會把 multipart 上傳的圖片轉換成上游需要的格式。

## 計費規則

* 按影片生成時長計費，單位為秒。請使用上表中模型支援的秒數，不建議傳任意秒數。
* 如果請求未指定影片時長，系統預設按 8 秒計費。
* 秒數辨識優先順序：`metadata.durationSeconds` > `duration` > `seconds` > 預設 8 秒。
* 解析度辨識優先順序：`metadata.resolution` > `size` > 預設 720p。
* 720p / 1080p / 4K 按相同規則計費，不因解析度另外加價。
* `aspectRatio` 只控制橫式或直式，不另外加價。
* 4K 只支援 8 秒。
* 具體單價以 aicentos 控制台為準。

## 介面說明

目前建議使用這 3 個介面：

| 用途   | 方法   | 路徑                             |
| ---- | ---- | ------------------------------ |
| 建立任務 | POST | `/v1/videos`                   |
| 查詢狀態 | GET  | `/v1/videos/{task_id}`         |
| 下載結果 | GET  | `/v1/videos/{task_id}/content` |

如果希望查詢時直接拿到結果位址，也可以使用：

| 用途        | 方法  | 路徑                                |
| --------- | --- | --------------------------------- |
| 查詢狀態和結果位址 | GET | `/v1/video/generations/{task_id}` |

### 驗證

```bash
export BASE_URL="https://aicentos.com"
export AICENTOS_API_KEY="sk-xxxxxx"
```

所有請求都帶：

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

### 建立文生影片任務

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "黃昏海邊的燈塔，鏡頭緩慢推進，海浪輕拍礁石，電影級光影，穩定運鏡",
    "seconds": "8",
    "size": "1280x720",
    "metadata": {
      "negativePrompt": "blurry, watermark, distorted, low quality",
      "resolution": "720p",
      "aspectRatio": "16:9",
      "seed": 20260401
    }
  }'
```

典型回應：

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1775025000
}
```

### 建立首影格圖生影片任務

目前圖生影片建議使用 `multipart/form-data`，首影格圖片欄位名必須是 `input_reference`。

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=讓畫面中的女孩回頭看向鏡頭，微風吹動頭髮，背景城市燈光輕微虛化，鏡頭平穩推進" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, deformed hands" \
  -F "seed=20260401"
```

### 建立首尾影格任務

首尾影格需要同時提供首影格和尾影格。首影格用 `input_reference`，尾影格用 `last_frame` 或 `lastFrame`。

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=從第一張女孩畫面自然過渡到最後一張男孩畫面，鏡頭平穩推進，城市燈光虛化，髮絲和衣服有輕微風動，過渡自然真實" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "last_frame=@./last-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, distorted face, deformed hands" \
  -F "seed=20260402"
```

### 建立參考圖任務

參考圖任務只支援 Veo 3.1 系列，最多 3 張，且 `referenceType` 僅支援 `asset`。欄位名可用 `reference_image`、`reference_images` 或 `referenceImages`。參考圖任務不要傳 `negativePrompt`。

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=參考兩張圖片中的人物外觀和城市夜景氛圍，生成一段電影感雙人街頭鏡頭，鏡頭平穩推進，背景燈光輕微虛化，人物自然看向鏡頭" \
  -F "reference_image=@./ref-1.png;type=image/png" \
  -F "reference_image=@./ref-2.png;type=image/png" \
  -F "reference_type=asset" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "seed=20260403"
```

JSON / Base64 也支援：

```bash
{
  "model": "veo-3.1-generate-preview",
  "prompt": "使用參考圖中的產品外觀生成廣告鏡頭",
  "duration": 8,
  "metadata": {
    "resolution": "720p",
    "aspectRatio": "16:9",
    "referenceImages": [
      {
        "image": {
          "bytesBase64Encoded": "BASE64_IMAGE",
          "mimeType": "image/png"
        },
        "referenceType": "asset"
      }
    ]
  }
}
```

### 查詢任務狀態

先把建立介面回傳的 `id` 或 `task_id` 儲存下來：

```bash
export TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

然後查詢狀態：

```bash
curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

處理中時，典型回應：

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1775025000
}
```

完成後，典型回應：

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1775025000,
  "completed_at": 1775025068
}
```

### 查詢任務狀態和結果位址

如果想在查詢時直接拿到可下載位址，可以調用：

```bash
curl -X GET "$BASE_URL/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

典型回應：

```bash
{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "url": "https://aicentos.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
  }
}
```

### 下載影片結果

任務完成後，直接下載：

```bash
curl -L "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -o veo-result.mp4
```

## 狀態說明

`GET /v1/videos/{task_id}` 回傳的狀態主要有：

| 狀態            | 說明  |
| ------------- | --- |
| `queued`      | 已排隊 |
| `in_progress` | 生成中 |
| `completed`   | 已完成 |
| `failed`      | 失敗  |

`GET /v1/video/generations/{task_id}` 回傳的狀態主要有：

| 狀態           | 說明  |
| ------------ | --- |
| `queued`     | 已排隊 |
| `processing` | 生成中 |
| `succeeded`  | 已成功 |
| `failed`     | 失敗  |

## 接入注意事項

* `prompt` 必填。
* 圖生影片時，圖片欄位名必須是 `input_reference`。
* 首尾影格任務必須同時提供首影格和尾影格，首影格用 `input_reference`，尾影格用 `last_frame` 或 `lastFrame`。
* 參考圖任務只支援 Veo 3.1 系列，最多 3 張，且必須 8 秒。
* 參考圖任務不要傳 `negativePrompt`。
* 目前 Gemini 圖生影片不建議直接傳遠端圖片 URL，建議傳檔案或 Base64。
* 建議輪詢 `GET /v1/videos/{task_id}`，等 `status=completed` 後再下載。
* Veo 3.1 系列可以傳 4、6、8 秒；當使用 1080p 或 4k 時必須傳 8 秒。- 橫式使用 `aspectRatio=16:9`，直式使用 `aspectRatio=9:16`；如果不傳，預設按 16:9 處理。
* 不要傳 `generateAudio` 參數。Veo 3.1 系列是原生含音訊的影片模型，但目前 Gemini API 不支援透過 `generateAudio` 參數開關音訊；傳入該欄位可能會被上游回傳 `INVALID_ARGUMENT`。
* 如需控制音訊內容，請在 prompt 中描述對白、環境音、音效或音樂風格。
* 官方 Veo 3.1 支援影片擴展，但目前 aicentos 介面暫未開放官方 video 輸入。