> ## 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.

# Flux Videos API 整合指南

> Flux 整合指南 - Ace Data Cloud

Flux Videos API 使用 `POST /flux/videos` 完成影片生成、關鍵影格圖生影片、影片續接和草稿增強。`action=generate`（預設），`mode` 選擇生成模式；查詢結果統一使用已有的 `POST /flux/tasks`。

> 目前為 Beta。文生影片、圖生影片、影片續接和草稿增強已開放。HTTP 200 和任務 ID 只表示任務受理，須繼續查詢最終結果。

## 1. 取得 API Token

1. 在 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 註冊或登入，建立應用程式並取得 API Token。一個通用 API Token 可呼叫平台服務；請確認應用程式具有 Flux 服務的呼叫權限和可用餘額。
2. 在 [Flux 服務頁面](https://platform.acedata.cloud/services/flux?tab=pricing) 查看方案及各操作價格。餘額不足時，在 [控制台餘額頁面](https://platform.acedata.cloud/console/coin) 儲值。
3. 請求使用 `Authorization: Bearer <你的 Token>`。Token 應儲存在伺服器端環境變數中，不要寫入前端頁面、公開儲存庫、螢幕截圖或回呼 URL。

![控制台申請 API Token](https://cdn.acedata.cloud/dvc3cg.jpg)

本文程式碼統一讀取環境變數：

```bash theme={null}
export ACEDATACLOUD_API_TOKEN='替換為你自己的 API Token'
```

| 項目 | 值 |
| - | - |
| API 根網址 | `https://api.acedata.cloud` |
| 提交影片任務 | `POST /flux/videos` |
| 查詢已有任務 | `POST /flux/tasks` |
| 驗證 | `Authorization: Bearer $ACEDATACLOUD_API_TOKEN` |
| 請求格式 | `Content-Type: application/json` |

完整欄位與線上偵錯見 [Flux Videos API](https://platform.acedata.cloud/documents/flux-videos)，任務查詢見 [Flux Tasks API](https://platform.acedata.cloud/documents/flux-tasks)。

## 2. 選擇操作和輸入

| action | mode | 輸入 | 結果 |
| - | - | - | - |
| `generate`（省略 action 時的預設值） | `t2v` | `prompt` | 從文字生成影片 |
| `generate` | `i2v` | `prompt`、`keyframes` | 從一張或多張關鍵影格生成影片 |
| `generate` | `v2v` | `prompt`、`start_video` | 基於輸入影片續接 |
| `generate` | `draft_enhance` | 自己已完成草稿的 `draft_task_id` | 增強該草稿 |

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

### 通用生成參數

| 參數 | 說明 |
| - | - |
| `mode` | 必填；`t2v`、`i2v`、`v2v` 或 `draft_enhance` |
| `prompt` | 一般生成必填；草稿增強不允許覆寫原始提示詞 |
| `duration` | t2v/i2v 為 5–20 秒整數，v2v 為 5–15 秒整數，或 `auto`；最終輸出時長可能與請求值有小幅差異 |
| `resolution` | `hd`、`fhd`、`qhd`、`uhd`；一般生成預設 `hd`，草稿增強預設 `fhd` |
| `aspect_ratio` | `auto`、`21:9`、`2:1`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`9:21` |
| `draft` | 是否先生成草稿；草稿僅支援 `hd` |
| `generate_audio` | 是否生成同步音訊；`false` 是有效值，請保留明確布林值 |
| `safety_tolerance` | 可選；0–4 的整數 |
| `async` | 建議設為 `true`，立即回傳平台任務 ID，再輪詢結果 |
| `callback_url` | 可選；接收最終 JSON 結果的 HTTP(S) 位址；設定後也會非同步受理 |

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

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

以下請求於 2026-10-02 調價前在生產介面執行成功。省略 `action` 驗證了預設生成行為；`async=true` 避免長時間等待 HTTP 連線。

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/flux/videos' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "flux-3",
    "mode": "t2v",
    "prompt": "A small toy sailboat floating on calm blue water in warm morning light, steady camera, no text.",
    "duration": 5,
    "resolution": "hd",
    "draft": true,
    "async": true
  }'
```

受理回應（真實任務 ID）：

```json theme={null}
{
  "task_id": "4341eb66-3845-4972-bb86-712a6cfae845",
  "trace_id": "b0f851bd-0925-43ca-acc3-6f634c70d607"
}
```

儲存自己回應中的 `task_id`，繼續查詢；不要使用文件範例的任務 ID 查詢其他帳戶的結果。

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/flux/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"action":"retrieve","id":"替換為本次回傳的 task_id"}'
```

任務查詢回傳的 `response` 欄位包含最終業務結果。以下為本次實測成功的 `response`，省略了外層任務中繼資料。文件中的影片 URL 已替換為長期範例 CDN 的同檔案副本（SHA-256 一致），實際呼叫會回傳本次任務自己的結果 URL：

```json theme={null}
{
  "success": true,
  "task_id": "4341eb66-3845-4972-bb86-712a6cfae845",
  "trace_id": "b0f851bd-0925-43ca-acc3-6f634c70d607",
  "data": [
    {
      "id": "4341eb66-3845-4972-bb86-712a6cfae845",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/4341eb66-3845-4972-bb86-712a6cfae845-5f4391e1942c.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24,
      "draft_task_id": "4341eb66-3845-4972-bb86-712a6cfae845"
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "t2v",
    "resolution": "hd",
    "draft": true
  },
  "cost": {
    "amount": 2.6884689277500002,
    "currency": "credit",
    "list_amount": 2.9871876975000005
  }
}
```

[查看本次實測影片](https://cdn.acedata.cloud/assets/examples/flux/4341eb66-3845-4972-bb86-712a6cfae845-5f4391e1942c.mp4)。媒體檢查確認輸出為 1280×704、24 fps、5.041667 秒的 MP4，檔案大小 2,607,276 位元組。

| 回應欄位 | 用途 |
| - | - |
| `success` | 最終任務是否成功；受理階段回傳 task\_id 不等於 success=true |
| `task_id` | 平台任務 ID，用於輪詢和業務冪等處理 |
| `trace_id` | 問題排查時提供給支援人員 |
| `data[].video_url` | 可讀取的影片結果位址 |
| `data[].seconds/width/height/fps` | 服務端測量的實際輸出時長、尺寸、影格率 |
| `data[].draft_task_id` | 草稿增強的輸入 ID；只在回傳可重複使用草稿時出現 |
| `usage` | 最終計費使用量；不要用請求 duration 覆蓋實際 seconds |
| `cost.amount` | 此次最終扣取的 Credits；`currency=credit` 不是美元 |
| `cost.list_amount` | 應用使用者消費優惠前的 Credits；適用時回傳 |

這是調價前的歷史實測：`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，不是該範例已經執行成功的聲明。生成完成後按上面的流程查詢，結果結構相同。

單張或兩張圖片使用普通陣列：

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "i2v",
  "prompt": "The camera slowly moves around the product in soft studio light.",
  "keyframes": ["https://example.com/first-frame.jpg"],
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "async": true
}
```

指定關鍵影格時刻時，使用 `[秒數, 圖片 URL]` 對：

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "i2v",
  "prompt": "A smooth transition from morning light to a warm sunset.",
  "keyframes": [[0, "https://example.com/start.jpg"], [5, "https://example.com/end.jpg"]],
  "duration": 5,
  "resolution": "hd",
  "async": true
}
```

允許 1–10 張關鍵影格。帶時間陣列須按時間遞增，時間為 0–20 秒，不可混用普通 URL 和帶時間項目。三張或更多普通關鍵影格必須明確指定 duration，不能用 auto。

### 圖生影片實測輸出

本次實測的匹配輸入如下（僅以說明文字替代完整 base64，其餘欄位為真實請求）：

```json theme={null}
{
  "async": true,
  "action": "generate",
  "model": "flux-3",
  "prompt": "The toy sailboat drifts slowly across calm water. A steady camera, gentle daylight, no people or text.",
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "draft": false,
  "mode": "i2v",
  "keyframes": [
    "<下图 PNG 文件的原始 base64 字符串>"
  ]
}
```

![本次圖生影片的參考關鍵影格](https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-input-b0525db595d2.png)

[下載該 PNG 關鍵影格](https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-input-b0525db595d2.png) 後，可用 Python 的 `base64.b64encode(image_bytes).decode("ascii")` 得到原始字串，放入 keyframes 陣列。不要將文件中的說明文字作為圖片輸入。

以下是 2026-10-01 生產任務的真實最終 response（非模擬回應）；僅影片 URL 換為雜湊相同的長期範例副本。實測輸入使用 1280×720 PNG 的原始 base64 字串作為單張關鍵影格；上面的 URL 輸入為獨立參數範例。

```json theme={null}
{
  "success": true,
  "task_id": "b1106de8-d586-4e23-b489-381e2f86a10f",
  "trace_id": "f62d5c56-cfb2-4f8f-b339-ef019d4c0d10",
  "data": [
    {
      "id": "b1106de8-d586-4e23-b489-381e2f86a10f",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-bef14458cc9d.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "i2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 7.617328628625,
    "currency": "credit",
    "list_amount": 8.46369847625
  }
}
```

[查看實測影片](https://cdn.acedata.cloud/assets/examples/flux/b1106de8-d586-4e23-b489-381e2f86a10f-bef14458cc9d.mp4)。

## 5. 影片續接

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

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "v2v",
  "prompt": "Continue the sailboat drifting forward with the same steady camera.",
  "start_video": "https://example.com/source.mp4",
  "duration": 5,
  "resolution": "hd",
  "async": true
}
```

### 影片續接實測輸出

本次完整實測輸入如下；重現草稿增強時須替換為自己的草稿 ID。素材 URL 使用相同檔案的長期範例副本：

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "v2v",
  "start_video": "https://cdn.acedata.cloud/assets/examples/flux/b41293be-94c0-4dc7-9f39-ce04f0a8798d-c055a3079059.mp4",
  "prompt": "Continue the same sailboat drifting gently across calm water in the same continuous steady shot.",
  "duration": 5,
  "resolution": "hd",
  "generate_audio": false,
  "async": true
}
```

以下是 2026-10-01 生產任務的真實最終 response（非模擬回應）；僅影片 URL 換為雜湊相同的長期範例副本。

```json theme={null}
{
  "success": true,
  "task_id": "8af9aa42-7e4d-47a4-bd61-144d97440c91",
  "trace_id": "4fb49afc-abca-4039-bbaa-adb66e293544",
  "data": [
    {
      "id": "8af9aa42-7e4d-47a4-bd61-144d97440c91",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/8af9aa42-7e4d-47a4-bd61-144d97440c91-a512d6574811.mp4",
      "seconds": 5,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5,
    "output_mp_seconds": 4.296875,
    "mode": "v2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 18.219375,
    "currency": "credit",
    "list_amount": 20.24375
  }
}
```

[查看實測影片](https://cdn.acedata.cloud/assets/examples/flux/8af9aa42-7e4d-47a4-bd61-144d97440c91-a512d6574811.mp4)。

實測輸入 `start_video` 為 [已完成的草稿影片](https://cdn.acedata.cloud/assets/examples/flux/b41293be-94c0-4dc7-9f39-ce04f0a8798d-c055a3079059.mp4)，其餘參數為 duration=5、resolution=hd、generate\_audio=false。

## 6. 先草稿、再增強

1. 用 `draft=true`、`resolution=hd` 生成草稿並等待成功。
2. 從最終 `data[0].draft_task_id` 取出平台草稿 ID。
3. 用同一歸屬的應用程式憑據提交增強請求：

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "draft_enhance",
  "draft_task_id": "替換為自己的已完成草稿 ID",
  "resolution": "fhd",
  "async": true
}
```

草稿增強不能傳入 `prompt`、`duration`、`aspect_ratio`、`version`、`generate_audio`、`draft`、`keyframes`、`start_video` 來覆蓋原始內容。草稿快取是暫時資源，請及時增強；不承諾永久保存或固定保留天數。非本人/非目前應用程式草稿、未完成草稿和已失效快取不能重複使用。草稿與增強是兩次任務，成功後分別計費。

### 草稿增強實測輸出

本次完整實測輸入如下；重現草稿增強時須替換為自己的草稿 ID。素材 URL 使用相同檔案的長期範例副本：

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "draft_enhance",
  "draft_task_id": "b41293be-94c0-4dc7-9f39-ce04f0a8798d",
  "resolution": "hd",
  "async": true
}
```

以下是 2026-10-01 生產任務的真實最終 response（非模擬回應）；僅影片 URL 換為雜湊相同的長期範例副本。

```json theme={null}
{
  "success": true,
  "task_id": "1db6243b-4a05-4484-828c-25bb17de7108",
  "trace_id": "64f93fa1-8d18-4c8b-a6d2-888009eb7cfa",
  "data": [
    {
      "id": "1db6243b-4a05-4484-828c-25bb17de7108",
      "model": "flux-3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/flux/1db6243b-4a05-4484-828c-25bb17de7108-058d92166607.mp4",
      "seconds": 5.041667,
      "width": 1280,
      "height": 704,
      "fps": 24
    }
  ],
  "usage": {
    "action": "generate",
    "seconds": 5.041667,
    "output_mp_seconds": 4.3326825781250005,
    "mode": "t2v",
    "resolution": "hd",
    "draft": false
  },
  "cost": {
    "amount": 7.617328628625,
    "currency": "credit",
    "list_amount": 8.46369847625
  }
}
```

[查看實測影片](https://cdn.acedata.cloud/assets/examples/flux/1db6243b-4a05-4484-828c-25bb17de7108-058d92166607.mp4)。

實測輸入為自己的 draft\_task\_id=b41293be-94c0-4dc7-9f39-ce04f0a8798d、resolution=hd；最終 usage.mode=t2v 表示原始草稿模式。此任務與原草稿分別收費。

## 7. Python 端到端呼叫

安裝 `requests`，設定自己的 Token，執行下面指令碼即可完成「提交一次 → 輪詢 → 輸出影片 URL」。查詢與網路重試都應使用原 task\_id，避免重複提交付費任務。

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

base_url = "https://api.acedata.cloud"
headers = {
    "Authorization": "Bearer " + os.environ["ACEDATACLOUD_API_TOKEN"],
    "Accept": "application/json",
}
payload = {
    "action": "generate",
    "model": "flux-3",
    "mode": "t2v",
    "prompt": "A small toy sailboat floating on calm blue water in warm morning light.",
    "duration": 5,
    "resolution": "hd",
    "draft": True,
    "async": True,
}
submitted = requests.post(base_url + "/flux/videos", json=payload, headers=headers, timeout=120)
submitted.raise_for_status()
accepted = submitted.json()
if accepted.get("error"):
    raise RuntimeError(accepted["error"])
task_id = accepted["task_id"]
print("Task ID:", task_id)  # 持久化保存，用于恢复輪詢

# 30 分鐘是本範例的用戶端等待上限，不是服務的完成時限承諾。
deadline = time.monotonic() + 30 * 60
while time.monotonic() < deadline:
    polled = requests.post(
        base_url + "/flux/tasks",
        json={"action": "retrieve", "id": task_id},
        headers=headers,
        timeout=30,
    )
    polled.raise_for_status()
    task = polled.json()
    if task.get("error"):
        raise RuntimeError(task["error"])
    result = task.get("response") or task.get("result")
    if isinstance(result, dict) and result.get("success") is True:
        print("Video:", result["data"][0]["video_url"])
        print("Usage:", result.get("usage"))
        print("Cost:", result.get("cost"))
        break
    if isinstance(result, dict) and result.get("error"):
        raise RuntimeError(result["error"])
    time.sleep(10)
else:
    raise TimeoutError("Still processing; resume polling with task_id=" + task_id)
```

網路逾時後，不要將未知狀態視為失敗並立即重新提交。若已取得 task\_id，繼續查詢該任務；記錄 task\_id 與 trace\_id 以利排查。輪詢介面本身不收取生成費用。

## 8. 使用回呼

提交時新增 `callback_url`，任務完成後會向該位址 POST 最終 JSON 結果，成功結構與前述 response 一致，失敗則包含 error。

```json theme={null}
{
  "action": "generate",
  "model": "flux-3",
  "mode": "t2v",
  "prompt": "A small sailboat on calm water.",
  "duration": 5,
  "resolution": "hd",
  "draft": true,
  "callback_url": "https://your-server.example/flux-callback"
}
```

回呼位址應可從公網存取。收到通知後依 task\_id 冪等處理，盡快回傳 2xx；業務處理可入佇列。本文不聲明回呼具有簽名驗證：在發放業務權益等敏感操作前，使用自己的 Token 查詢同一任務以核對結果。未收到回呼時也可繼續輪詢，不要重新生成。

## 9. 目前計費和價目表

2026-10-02 更新：本次影片介面各級單價下調約 6.33%，計量方式、方案與消費優惠規則維持不變。前文歷史實測 response 中的 cost 是任務完成時的帳單，不代表目前報價。

影片生成依**實際輸出秒數**計費。以下是目前未套用帳戶消費優惠的 Credits 單價，與 [Flux 價格頁](https://platform.acedata.cloud/services/flux?tab=pricing) 的規則一致。

| 操作/模式 | 解析度 | Credits 單價 |
| - | - | -: |
| t2v / i2v 草稿 | hd | 0.555 / 秒 |
| v2v 草稿 | hd | 1.11 / 秒 |
| t2v / i2v / 對應草稿增強 | hd | 1.5725 / 秒 |
| 同上 | fhd | 2.6825 / 秒 |
| 同上 | qhd | 3.7 / 秒 |
| 同上 | uhd | 7.4 / 秒 |
| v2v / 對應草稿增強 | hd | 3.7925 / 秒 |
| 同上 | fhd | 4.9025 / 秒 |
| 同上 | qhd | 6.0125 / 秒 |
| 同上 | uhd | 8.7875 / 秒 |

換算美元：`實際費用（USD）= cost.amount（Credits）× 方案 price / 方案 amount`。儲值級距和消費優惠會影響實際價格，Credits 不能直接視為 USD。失敗任務不收取生成費用；最終金額以完成結果和控制台呼叫紀錄為準。

## 10. 常見問題與排查

| 情況 | 建議 |
| - | - |
| 參數錯誤（400） | 檢查 action=generate、mode、duration、關鍵影格格式；不要混用不同生成模式的欄位 |
| 驗證錯誤（401） | 檢查 Bearer Token、應用程式權限及憑證是否有效 |
| 內容審核拒絕（403） | 調整素材與提示詞，不要原樣重複提交 |
| 限流（429） | 降低並行數，退避重試 |
| service\_unavailable（503） | 目前操作不可用；已受理的非同步任務可能在最終 response 中回報該錯誤 |
| task\_id 已回傳但還沒有影片 | 繼續查詢 response，不將 HTTP 200 視為生成完成 |
| 草稿無法重複使用 | 確認本人/目前應用程式、任務已完成、原請求 draft=true，並檢查暫存快取是否仍有效 |

回饋時提供 task\_id、trace\_id、請求時間和去識別化參數，不要傳送 API Token。更多方式見 [Flux MCP 整合指南](https://platform.acedata.cloud/documents/flux-mcp)。


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