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

​
申請流程

要使用 Gemini Videos Generation API，首先到 Ace Data Cloud 控制台 取得您的 API Token，留作備用。 如果你尚未登入或註冊，會自動跳轉到登入頁面邀請你註冊和登入，完成後會自動返回目前頁面。 一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在 控制台 儲值通用餘額。
📘 完整文件：Gemini Videos Generation API →

​
基本使用

首先了解一下基本的使用方式，輸入提示詞 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」按鈕即可進行測試，得到的結果類似如下：
回傳結果一共有多個欄位，介紹如下：
  • 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 程式碼如下：
對應的 Python 程式碼如下：

​
圖片生成影片

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

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

支援直接「輸入一段影片，生成一段新影片」：在 video_urls 中傳入一個參考影片連結（最多 1 個），並同時在 image_urls 中提供至少一張參考圖（上游硬性要求），再用 prompt 描述想要的編輯效果（改風格、換場景、增刪元素等）。 下面是一個完整的真實範例——把一段陽光沙灘的影片改成大雪紛飛的冬日場景，同時保留沙灘、椰樹和小船的配置。影片編輯耗時較長（本例約 6.5 分鐘），因此使用 async: true 非同步提交：
提交後介面立即回傳 task_id：
之後使用該 task_id 作為 id 輪詢 Gemini Tasks API，任務完成後即可取得生成的新影片（這是本範例的真實回傳結果）：
如需更高畫質的結果，可將 resolution 設為 1080p（其餘參數不變）。
提示：範例中的輸入 / 輸出媒體連結皆為真實生成結果。平台生成的影片、圖片連結有保存期限，過期後會失效，請在取得結果後及時下載並儲存到自己的儲存空間。
注意：參考影片最多 1 個；且提供 video_urls 時必須提供至少一張 image_urls，否則會回傳如下參數錯誤：

​
非同步回呼

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

​
查詢任務結果

如果使用了非同步回呼或希望主動查詢任務狀態，可以透過 Gemini Tasks API（POST https://api.acedata.cloud/gemini/tasks）根據 task_id 查詢任務的最新狀態與結果。請求主體中傳入建立影片時回傳的 task_id 作為 id：
任務完成後回傳的結果類似如下，response.data 的結構與同步生成時一致（生成中時 state 為 pending、video_url 為 null）：

​
錯誤處理

當請求出現問題時，API 會回傳對應的錯誤碼與說明，常見的如下：
  • 400：請求參數有誤，例如缺少 prompt 或 aspect_ratio 取值不合法。
  • 401：驗證失敗，token 無效或與 API 不相符。
  • 403：餘額不足，或提示詞觸發內容審核而被拒絕。
  • 500：伺服器內部錯誤或上游生成失敗。