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

# Gemini Videos Generation API 串接說明

> Gemini AI 整合指南 - Ace Data Cloud

本文將介紹 Gemini Videos Generation API 的串接說明，它可以透過輸入文字提示詞（以及可選的參考圖片）來生成 Google Gemini（omni-flash）影片。

## 申請流程

要使用 Gemini Videos Generation API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 取得您的 API Token，留作備用。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

如果你尚未登入或註冊，會自動跳轉到登入頁面邀請你註冊和登入，完成後會自動返回目前頁面。

**一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 儲值通用餘額。

> 📘 完整文件：[Gemini Videos Generation API →](https://platform.acedata.cloud/documents/gemini-videos)

## 基本使用

首先了解一下基本的使用方式，輸入提示詞 `prompt`、模型 `model` 以及長寬比 `aspect_ratio`，便可生成對應的影片。

可以看到這裡我們設定了 Request Headers，包括：

* `accept`：想要接收何種格式的回應結果，這裡填寫為 `application/json`，即 JSON 格式。
* `authorization`：呼叫 API 的金鑰，申請之後可以直接下拉選擇。

另外設定了 Request Body，包括：

* `prompt`：描述想要生成影片內容的文字提示詞，**必填**。
* `model`：生成影片的模型，目前僅支援 `omni-flash`，預設即為 `omni-flash`。
* `aspect_ratio`：生成影片的長寬比，可選 `16:9`（橫向）或 `9:16`（直向），預設 `16:9`。
* `resolution`：可選的輸出解析度，可選 `720p` 或 `1080p`，預設 `720p`。
* `image_urls`：可選的參考圖片連結陣列，用於引導影片生成，留空項目會被忽略。當使用 `video_urls` 進行影片編輯時，本參數必填（至少一張）。
* `video_urls`：可選的參考影片連結陣列（最多 1 個），用於**影片編輯 / 影片參考**；提供時必須同時提供至少一張 `image_urls`。
* `callback_url`：非同步回呼位址，設定後 API 會立即回傳 `task_id`，任務完成時將結果 POST 到該位址。
* `async`：可選，設為 `true` 時介面立即回傳 `task_id`，無需提供 `callback_url`，隨後透過對應的任務查詢介面輪詢取得結果。

點擊「Try」按鈕即可進行測試，得到的結果類似如下：

```json theme={null}
{
  "success": true,
  "task_id": "9258c45f-bed9-4dde-81c2-a70a710a6904",
  "trace_id": "862d6aae-cec0-407f-9524-bc1be2291bcb",
  "data": [
    {
      "id": "dc4b7292-070c-49a8-8183-919bdf8ad59e",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/9258c45f-bed9-4dde-81c2-a70a710a6904-418c13e0605f.mp4",
      "state": "succeeded",
      "aspect_ratio": "16:9",
      "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden"
    }
  ],
  "started_at": 1784112953.856,
  "finished_at": 1784113021.328,
  "elapsed": 67.472,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}
```

回傳結果一共有多個欄位，介紹如下：

* `success`：本次影片生成請求是否成功。
* `task_id`：本次影片生成任務的 ID。
* `trace_id`：本次請求的追蹤 ID，用於排查問題。
* `data`：生成的影片結果清單。
  * `id`：生成影片的唯一識別碼。
  * `video_url`：生成影片的連結位址（`state` 為 `pending` 時為 `null`）。
  * `state`：影片生成任務的狀態，可選 `pending` / `succeeded` / `failed`。
  * `aspect_ratio`：該影片的長寬比，與請求參數一致。
  * `prompt`：生成該影片所使用的提示詞。

同步回傳時，頂層還會附帶 `started_at`、`finished_at`、`elapsed`（耗時，秒）以及 `cost`（本次扣費，單位 Credit）等欄位。

我們只需要根據結果中 `data` 的 `video_url` 連結位址取得生成的影片即可。

對應的 CURL 程式碼如下：

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/gemini/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9"
}'
```

對應的 Python 程式碼如下：

```python theme={null}
import requests

url = "https://api.acedata.cloud/gemini/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "omni-flash",
    "aspect_ratio": "16:9"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## 圖片生成影片

如果想基於參考圖片生成影片，可以在 `image_urls` 中傳入一個或多個圖片連結，用於引導影片生成：

```json theme={null}
{
  "prompt": "The woman slowly turns around and smiles at the camera, gentle breeze",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://cdn.acedata.cloud/assets/examples/nanobanana/e44bfceb-1458-4b4b-9d10-21024678f1a3-5ccb6e83b402.png"
  ]
}
```

## 影片編輯 / 參考影片（輸入影片，生成影片）

支援直接「輸入一段影片，生成一段新影片」：在 `video_urls` 中傳入一個參考影片連結（最多 1 個），並**同時**在 `image_urls` 中提供至少一張參考圖（上游硬性要求），再用 `prompt` 描述想要的編輯效果（改風格、換場景、增刪元素等）。

下面是一個完整的真實範例——把一段陽光沙灘的影片改成大雪紛飛的冬日場景，同時保留沙灘、椰樹和小船的配置。影片編輯耗時較長（本例約 6.5 分鐘），因此使用 `async: true` 非同步提交：

```json theme={null}
{
  "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout.",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "image_urls": [
    "https://cdn.acedata.cloud/99289603bd.png"
  ],
  "video_urls": [
    "https://cdn.acedata.cloud/assets/examples/seedance/dd3dc063-3383-4f29-bedc-e771a096758c-044e05281a2a.mp4"
  ],
  "async": true
}
```

提交後介面立即回傳 `task_id`：

```json theme={null}
{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}
```

之後使用該 `task_id` 作為 `id` 輪詢 [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks)，任務完成後即可取得生成的新影片（這是本範例的真實回傳結果）：

```json theme={null}
{
  "success": true,
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284",
  "trace_id": "5b22104b-5a6d-4a4f-8063-69acae1dc1c6",
  "data": [
    {
      "id": "e125d316-3d26-4c65-9413-55baf6be46b8",
      "video_url": "https://cdn.acedata.cloud/assets/examples/sora/cd68b4ee-de70-4c94-ac69-997a3fed0284-c5603ef983da.mp4",
      "state": "succeeded",
      "aspect_ratio": "9:16",
      "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout."
    }
  ],
  "started_at": 1784084482.914,
  "finished_at": 1784084877.09,
  "elapsed": 394.176,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}
```

如需更高畫質的結果，可將 `resolution` 設為 `1080p`（其餘參數不變）。

> 提示：範例中的輸入 / 輸出媒體連結皆為真實生成結果。**平台生成的影片、圖片連結有保存期限，過期後會失效**，請在取得結果後及時下載並儲存到自己的儲存空間。

> 注意：參考影片最多 1 個；且提供 `video_urls` 時必須提供至少一張 `image_urls`，否則會回傳如下參數錯誤：

```json theme={null}
{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "image_urls (at least one reference image) is required when video_urls is provided."
  }
}
```

## 非同步回呼

影片生成需要一定的處理時間。如果不希望保持長連線等待，可以傳入 `callback_url`，此時 API 會立即回傳 `task_id`，任務完成後會將最終結果 POST 到該位址：

```json theme={null}
{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9",
  "callback_url": "https://your-domain.com/callback/gemini"
}
```

立即回傳的結果如下：

```json theme={null}
{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

## 查詢任務結果

如果使用了非同步回呼或希望主動查詢任務狀態，可以透過 [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks)（`POST https://api.acedata.cloud/gemini/tasks`）根據 `task_id` 查詢任務的最新狀態與結果。請求主體中傳入建立影片時回傳的 `task_id` 作為 `id`：

```json theme={null}
{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

任務完成後回傳的結果類似如下，`response.data` 的結構與同步生成時一致（生成中時 `state` 為 `pending`、`video_url` 為 `null`）：

```json theme={null}
{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
  "type": "videos",
  "request": {
    "model": "omni-flash",
    "prompt": "A time-lapse of clouds over snow mountains at sunrise",
    "aspect_ratio": "16:9",
    "async": true
  },
  "response": {
    "success": true,
    "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
    "data": [
      {
        "id": "486ebd5a-6a4b-406c-84ae-33835de4fe19",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "state": "succeeded",
        "aspect_ratio": "16:9",
        "prompt": "A time-lapse of clouds over snow mountains at sunrise"
      }
    ],
    "elapsed": 96.716,
    "cost": {
      "amount": 1.932,
      "currency": "credit",
      "list_amount": 2.1
    }
  }
}
```

## 錯誤處理

當請求出現問題時，API 會回傳對應的錯誤碼與說明，常見的如下：

* `400`：請求參數有誤，例如缺少 `prompt` 或 `aspect_ratio` 取值不合法。
* `401`：驗證失敗，token 無效或與 API 不相符。
* `403`：餘額不足，或提示詞觸發內容審核而被拒絕。
* `500`：伺服器內部錯誤或上游生成失敗。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.