Skip to main content
Flux Videos API 使用 POST /flux/videos 完成影片生成、關鍵影格圖生影片、影片續接和草稿增強。action=generate（預設），mode 選擇生成模式；查詢結果統一使用已有的 POST /flux/tasks。
目前為 Beta。文生影片、圖生影片、影片續接和草稿增強已開放。HTTP 200 和任務 ID 只表示任務受理，須繼續查詢最終結果。

​
1. 取得 API Token

  1. 在 Ace Data Cloud 控制台 註冊或登入，建立應用程式並取得 API Token。一個通用 API Token 可呼叫平台服務；請確認應用程式具有 Flux 服務的呼叫權限和可用餘額。
  2. 在 Flux 服務頁面 查看方案及各操作價格。餘額不足時，在 控制台餘額頁面 儲值。
  3. 請求使用 Authorization: Bearer <你的 Token>。Token 應儲存在伺服器端環境變數中，不要寫入前端頁面、公開儲存庫、螢幕截圖或回呼 URL。
控制台申請 API Token 本文程式碼統一讀取環境變數：
完整欄位與線上偵錯見 Flux Videos API，任務查詢見 Flux Tasks API。

​
2. 選擇操作和輸入

生成模型為 flux-3，action 為 generate（預設）。透過 mode 選擇文生影片、圖生影片、影片續接或草稿增強。

​
通用生成參數

素材 URL 必須能夠被服務讀取。若用暫時簽名 URL，應為下載與處理預留足夠的有效期。不要將網頁位址當作圖片或影片檔案位址。

​
3. 文生影片：完整實測請求與結果

以下請求於 2026-10-02 調價前在生產介面執行成功。省略 action 驗證了預設生成行為；async=true 避免長時間等待 HTTP 連線。
受理回應（真實任務 ID）：
儲存自己回應中的 task_id，繼續查詢；不要使用文件範例的任務 ID 查詢其他帳戶的結果。
任務查詢回傳的 response 欄位包含最終業務結果。以下為本次實測成功的 response，省略了外層任務中繼資料。文件中的影片 URL 已替換為長期範例 CDN 的同檔案副本（SHA-256 一致），實際呼叫會回傳本次任務自己的結果 URL：
查看本次實測影片。媒體檢查確認輸出為 1280×704、24 fps、5.041667 秒的 MP4，檔案大小 2,607,276 位元組。 這是調價前的歷史實測：list_amount=2.9871876975 Credits，帳戶當時享有 10% 消費優惠，實際 amount=2.68846892775 Credits。2026-10-02 新價格已下調約 6.33%；相同 5.041667 秒草稿按目前價格為 2.798125185 Credits（消費優惠前），如仍享有 10% 消費優惠則為 2.5183126665 Credits。歷史任務帳單不重新計算。其他帳戶的方案與優惠可能不同；這不是所有使用者固定的美元價格。

​
4. 圖生影片：普通與帶時間關鍵影格

以下為參數範例，需要替換素材 URL，不是該範例已經執行成功的聲明。生成完成後按上面的流程查詢，結果結構相同。 單張或兩張圖片使用普通陣列：
指定關鍵影格時刻時，使用 [秒數, 圖片 URL] 對：
允許 1–10 張關鍵影格。帶時間陣列須按時間遞增，時間為 0–20 秒，不可混用普通 URL 和帶時間項目。三張或更多普通關鍵影格必須明確指定 duration，不能用 auto。

​
圖生影片實測輸出

本次實測的匹配輸入如下（僅以說明文字替代完整 base64，其餘欄位為真實請求）：
本次圖生影片的參考關鍵影格 下載該 PNG 關鍵影格 後，可用 Python 的 base64.b64encode(image_bytes).decode("ascii") 得到原始字串，放入 keyframes 陣列。不要將文件中的說明文字作為圖片輸入。 以下是 2026-10-01 生產任務的真實最終 response（非模擬回應）；僅影片 URL 換為雜湊相同的長期範例副本。實測輸入使用 1280×720 PNG 的原始 base64 字串作為單張關鍵影格；上面的 URL 輸入為獨立參數範例。
查看實測影片。

​
5. 影片續接

start_video 傳入已有影片檔案位址，mode=v2v，時長最多 15 秒。

​
影片續接實測輸出

本次完整實測輸入如下；重現草稿增強時須替換為自己的草稿 ID。素材 URL 使用相同檔案的長期範例副本：
以下是 2026-10-01 生產任務的真實最終 response（非模擬回應）；僅影片 URL 換為雜湊相同的長期範例副本。
查看實測影片。 實測輸入 start_video 為 已完成的草稿影片，其餘參數為 duration=5、resolution=hd、generate_audio=false。

​
6. 先草稿、再增強

  1. 用 draft=true、resolution=hd 生成草稿並等待成功。
  2. 從最終 data[0].draft_task_id 取出平台草稿 ID。
  3. 用同一歸屬的應用程式憑據提交增強請求：
草稿增強不能傳入 prompt、duration、aspect_ratio、version、generate_audio、draft、keyframes、start_video 來覆蓋原始內容。草稿快取是暫時資源，請及時增強；不承諾永久保存或固定保留天數。非本人/非目前應用程式草稿、未完成草稿和已失效快取不能重複使用。草稿與增強是兩次任務，成功後分別計費。

​
草稿增強實測輸出

本次完整實測輸入如下；重現草稿增強時須替換為自己的草稿 ID。素材 URL 使用相同檔案的長期範例副本：
以下是 2026-10-01 生產任務的真實最終 response（非模擬回應）；僅影片 URL 換為雜湊相同的長期範例副本。
查看實測影片。 實測輸入為自己的 draft_task_id=b41293be-94c0-4dc7-9f39-ce04f0a8798d、resolution=hd；最終 usage.mode=t2v 表示原始草稿模式。此任務與原草稿分別收費。

​
7. Python 端到端呼叫

安裝 requests，設定自己的 Token，執行下面指令碼即可完成「提交一次 → 輪詢 → 輸出影片 URL」。查詢與網路重試都應使用原 task_id，避免重複提交付費任務。
網路逾時後，不要將未知狀態視為失敗並立即重新提交。若已取得 task_id，繼續查詢該任務；記錄 task_id 與 trace_id 以利排查。輪詢介面本身不收取生成費用。

​
8. 使用回呼

提交時新增 callback_url，任務完成後會向該位址 POST 最終 JSON 結果，成功結構與前述 response 一致，失敗則包含 error。
回呼位址應可從公網存取。收到通知後依 task_id 冪等處理，盡快回傳 2xx；業務處理可入佇列。本文不聲明回呼具有簽名驗證：在發放業務權益等敏感操作前，使用自己的 Token 查詢同一任務以核對結果。未收到回呼時也可繼續輪詢，不要重新生成。

​
9. 目前計費和價目表

2026-10-02 更新：本次影片介面各級單價下調約 6.33%，計量方式、方案與消費優惠規則維持不變。前文歷史實測 response 中的 cost 是任務完成時的帳單，不代表目前報價。 影片生成依實際輸出秒數計費。以下是目前未套用帳戶消費優惠的 Credits 單價，與 Flux 價格頁 的規則一致。 換算美元：實際費用（USD）= cost.amount（Credits）× 方案 price / 方案 amount。儲值級距和消費優惠會影響實際價格，Credits 不能直接視為 USD。失敗任務不收取生成費用；最終金額以完成結果和控制台呼叫紀錄為準。

​
10. 常見問題與排查

回饋時提供 task_id、trace_id、請求時間和去識別化參數，不要傳送 API Token。更多方式見 Flux MCP 整合指南。