Seedance 2.5 Flash API 教學:非同步工作、限制與錯誤

推理時代閱讀約 8 分鐘
Seedance 2.5 Flash API 教學:非同步工作、限制與錯誤

使用 doubao-seedance-2-5-flash 搭配 POST /ai/v1/videos,輪詢工作狀態,然後下載結果。目前的 AIHubMix schema 支援 480p/720p 輸出、4–30 秒片段,以及最多 10 個 image、5 個 video 和 5 個 audio 參照。使用舊版 /v1/videos 的用戶端,必須同時更新端點和模型 ID。

本指南已於 2026 年 11 月 16 日檢查。上方的短 ID 和 doubao-seedance-2-5-flash-261115 都回傳了模型 schema,並拒絕 1080p 請求,錯誤為 400 schema_violation。另一次建立 4 秒 480p 影片的嘗試則回傳 402 insufficient_quota;並未生成影片。以下工作流程依據目前的 schema 和文件撰寫,但本次檢查未能端對端驗證生成是否成功、延遲、MOV 輸出和編輯功能。

事前準備與 schema 探索

Seedance 2.5 Flash 模型頁面列出本指南全程使用的短 ID。提交工作前:

  1. 在AIHubMix 控制台啟用非同步媒體工作。文件指出,未啟用此功能的帳戶會收到錯誤 403 async_not_enabled。
  2. 確認 API 金鑰具有存取權限,且帳戶餘額充足。即時檢查回傳 402 insufficient_quota,訊息為 Your account has insufficient quota. Add credits and try again.
  3. 在 shell 中匯出 AIHUBMIX_API_KEY。請勿將金鑰放入原始碼檔案或瀏覽器程式碼。
  4. 取得目前的 schema;探索請求不需要驗證。
curl --fail-with-body -sS \
  'https://aihubmix.com/call/schema/models/doubao-seedance-2-5-flash/endpoints' \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

11 月 16 日的 schema 顯示,Flash 僅列出 /ai/v1/videos。它接受 resolution 值 480p 和 720p(預設值為 720p)、4 到 30 之間的整數 duration,或由模型自行選擇時長的 -1。若需要可預期的預算,請指定明確的時長。

建立、輪詢與下載

AIHubMix 影片生成 API將建立工作、查詢狀態和下載分開處理。建立請求的 HTTP 成功回應代表工作已受理;只有 status: "completed" 才能確認完成。查詢可能回傳 HTTP 200,但工作本身的狀態卻是 status: "failed"。

提交文字轉影片工作

此範例會要求生成一段 10 秒、720p、16:9 且含音訊的產品影片。範例僅使用文字,因此不依賴託管於其他位置的參照圖片。

curl --fail-with-body -sS -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'

請立即儲存回傳的工作 id。每隔 15 秒輪詢一次 GET /ai/v1/videos/{id},直到狀態為 completed、failed 或 cancelled。輪詢進行中的工作時,請使用影片詳細資料路由:它會更新供應商狀態,而統一工作清單無法取代這項檢查。完成後,使用相同的 Bearer 標頭透過 GET /ai/v1/videos/{id}/content 下載。

完整的 Python 用戶端

使用 python3 -m pip install requests 安裝相依套件,將下方內容儲存為 seedance_flash.py,接著在已設定 API 金鑰的 shell 中執行 python3 seedance_flash.py。此範例實作文件所述的流程;前述配額錯誤使我們無法完成生成測試。

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://aihubmix.com"
HEADERS = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}
PAYLOAD = {
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": True,
}

# Submit once. A network timeout does not prove that creation failed.
response = requests.post(
    f"{BASE_URL}/ai/v1/videos", headers=HEADERS, json=PAYLOAD, timeout=60
)
response.raise_for_status()
task = response.json()
task_id = task["id"]
print(f"Task ID: {task_id}", flush=True)

deadline = time.monotonic() + 20 * 60
while task["status"] not in {"completed", "failed", "cancelled"}:
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Still waiting for {task_id}; query it again, do not recreate it.")
    time.sleep(15)
    response = requests.get(
        f"{BASE_URL}/ai/v1/videos/{task_id}", headers=HEADERS, timeout=30
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(f"Task {task_id}: {task.get('error') or task['status']}")

response = requests.get(
    f"{BASE_URL}/ai/v1/videos/{task_id}/content", headers=HEADERS, timeout=120
)
response.raise_for_status()
Path("seedance_flash_10s.mp4").write_bytes(response.content)
print("Saved seedance_flash_10s.mp4")

20 分鐘期限是用戶端的等待上限,不代表伺服器會取消工作,也不是生成時間保證。若輪詢或下載失敗,請保留工作 ID 並重試該操作。發生逾時或供應商狀態不明時,請勿自動再次提交生成請求。

依據BytePlus 官方線上推理費率,Flash 在沒有影片輸入時,每百萬 token 收費 $7.00;在 480p/720p 下有影片輸入時,每百萬 token 收費 $4.30。對於純文字範例,預估用量為 10 × 1280 × 720 × 24 / 1024 = 216,000 token:使用 Flash 為 $1.51,使用旗艦版 2.5 的 720p 則為 $2.31。這些是依據 BytePlus 費率計算的預估值,並非實際測得的 AIHubMix 帳單金額。

參照與 webhook

若要使用媒體引導影片,請新增 input_references 項目,其中包含 type(image_url、video_url 或 audio_url)以及指向可存取媒體的 url。schema 對這些類型的數量上限為 10 / 5 / 5。若要控制首尾影格,請改用 frame_images;每個項目都有 frame_type 和巢狀欄位 image_url.url。請勿同時使用非空的 frame_images 和 input_references。影格工作流程必須設定 aspect_ratio: "adaptive",而且指定最後影格時也必須提供第一個影格。

非同步工作文件說明了透過 webhook_url 傳送 HTTPS 回呼。目前 Flash 的 schema 包含此欄位,但未包含 webhook_events_filter,且設有 additionalProperties: false,因此依照此模型 schema 操作時,請省略篩選欄位。文件指出,預設會傳送 completed、failed 和 cancelled 事件。傳送至少一次,最多重試六次,重試間隔為 1、4、16、64 和 256 秒;請以 event_id 去重。工作層級的回呼沒有獨立的簽署密鑰,因此請查詢工作以確認最終狀態。文件另有說明帳戶層級的訂閱,供需要簽章驗證的應用程式使用。

錯誤:實測結果與文件說明

1080p:實測的 schema 拒絕

兩個 AIHubMix 模型 ID 在收到包含 resolution: "1080p" 的 4 秒請求時,都回傳 HTTP 400。回傳的錯誤欄位如下:

{
  "error": {
    "code": "schema_violation",
    "message": "`resolution` must be one of: 480p, 720p, null.",
    "type": "invalid_request_error"
  }
}

回應中也包含請求追蹤 ID,此處省略。這是實際觀察到的閘道拒絕,不是推測的上游錯誤;它既不能證明生成成功,也不能作為速度測量結果。

以下其他限制來自目前的 Flash schema;本次即時檢查未另外提交這些無效組合。

輸入問題 Schema 要求 修正方式
4K 輸出 480p 或 720p 降低解析度
參照數量過多 10 張圖片 / 5 部影片 / 5 個音訊 減少數量
兩個參照陣列 僅能有一個非空陣列 選擇一種工作流程
只有最後影格 還必須提供第一個影格 提供兩個影格
影格搭配固定比例 自適應比例 使用自適應比例

真實人物參照:使用已驗證的素材

AIHubMix 文件指出,當 Doubao 因真實人物圖片而回傳特定的隱私拒絕時,會出現 doubao_real_person_required。本次檢查並未觸發此錯誤。文件所列訊息如下:

此請求使用了真實人物圖片。請完成真實人物驗證,並使用有效的素材參照。請參閱 https://docs.aihubmix.com/cn/api/doubao-real-person-assets。

請依照Doubao 真實人物素材指南操作:在 /ai/v1/asset-groups 建立群組,在 /ai/v1/asset-groups/{id}/verification-sessions 建立驗證工作階段,請影像中的人物完成網頁驗證,接著在 /ai/v1/asset-groups/{id}/assets 註冊素材,並等候素材啟用。在生成參照中使用 asset://<ASSET_ID>。僅提供原始相片 URL,無法取代同意程序和素材工作流程。

配額、請求大小與下載

實測的 402 insufficient_quota 阻止有效解析度的請求進入生成階段。再次嘗試前請先儲值;修改正確的提示詞或模型 ID 無法解決此回應。403 async_not_enabled 則是另一種文件有載明的事前條件錯誤,必須在控制台啟用功能。

AIHubMix 記載了32 MiB 的請求主體大小上限,以及413 request_too_large。使用公開 URL 可避免 Base64 擴增請求主體大小,但引用的媒體仍須符合模型本身的大小與格式限制。

影片完成後請儘快儲存。AIHubMix 現有的 Seedance 2.5 整合指南提醒,輸出 URL 的有效期限很短,約為 30 分鐘;本次未確認 Flash 的固定保留期限。影片 API 可能回傳 expires_at: null,但這不代表會永久儲存。文件列出的下載錯誤包括 410 artifact_expired 和 429 too_many_downloads。若下載遇到暫時性的服務錯誤,請針對現有工作重試下載,不要重新生成影片。

有效請求仍可能遇到的遷移陷阱

Volcengine Seedance 2.5 指南明確將 Flash 列入此系列,並確認支援 MOV 輸出、編輯和延伸功能;但這些供應商端功能,必須與透過閘道實際驗證的項目區分開來。

  • MOV 和編輯欄位已開放使用,但本次未進行端對端測試。Flash 的 schema 接受 extra.output_format: "mp4" 或 "mov",以及 extra.omni_reference_task_type 值 auto、reference、edit 和 extend。若明確傳送工作類型欄位,schema 要求 input_references 不得為空。edit 另外需要影片參照、自適應比例,以及 duration: -1;extend 則需要影片參照和自適應比例。
  • 指定工作類型不代表模型一定會接受。Ark 文件指出,推斷出的工作類型與參數衝突時,非同步工作會出現 InvalidParameter.TaskTypeConstraint;推斷出的類型與明確指定的類型不符時,則會出現 InvalidParameter.TaskTypeMismatch。本次未實測 AIHubMix 對應的錯誤,因此請檢查回傳工作中的 error,不要假設閘道只會使用某一種錯誤代碼。
  • Flash 不支援 Draft 升級流程。供應商僅為旗艦版 2.5 提供分兩階段、從 480p Draft 升級至最終版本的工作流程。Flash 不支援此功能,而且目前 AIHubMix 的兩個模型 schema 都未包含 draft 和 draft_task。
  • 影片輸入會影響計費。官方計費會計入輸入和輸出影片的時長,並可能設有最低 token 門檻。每百萬 token $4.30 的費率,不保證影片引導工作一定比其他條件相同的純文字工作便宜。請查看實際用量和帳戶帳單,不要只依賴公式估算。
  • 部分說明仍不夠明確。Flash 的閘道結構描述提供了 extra.priority、extra.safety_identifier 和 extra.tools,但其說明仍標示「僅適用於 2.0 系列」。Ark 的建立任務參考文件也將 priority 和 tools 列為 2.5 系列支援的欄位。僅憑結構描述中出現這些欄位,無法確認它們在 AIHubMix 上的效果;在正式環境中依賴特定功能前,請先驗證。

執行前檢查清單

  • 啟用非同步任務,並確認帳戶餘額。
  • 使用簡短的 Flash ID 搭配 /ai/v1/videos,並取得目前的結構描述。
  • 選擇 480p 或 720p,並設定 4–30 秒範圍內的明確片長。
  • 參考素材數量請控制在 10 張圖片、5 部影片和 5 段音訊以內。
  • 將影格參考素材分開提供,並為其使用自適應比例。
  • 若使用真人肖像參考素材,請透過已驗證且處於啟用狀態的素材進行。
  • 儲存任務 ID,確認任務的終止狀態,並儘快下載結果。
  • 若不確定生成狀態,請針對既有任務重試查詢或下載。

常見問題

我可以透過 OpenAI 相容的 /v1/videos 路徑使用 Flash 嗎?
目前的 Flash 結構描述只列出 /ai/v1/videos。本指南中的範例請使用這個原生非同步路徑。

為什麼影格圖片請求使用 aspect_ratio: "16:9" 會失敗?
Flash 的結構描述規定,提供非空的 frame_images 時,必須使用 aspect_ratio: "adaptive"。設定最後影格時也必須提供第一影格,且影格參考素材不得與非空的 input_references 一併使用。

如何修正 doubao_real_person_required?
請完成個人驗證與素材登錄流程,等待素材啟用後,再以素材 URI 引用。這個代碼代表 Doubao 特定的隱私拒絕;本次檢查未能重現此情況。

為什麼短片參考素材的費用可能高於公式預估?
供應商的計費規則可能會在輸入包含影片時套用 token 最低門檻。公式僅供估算;請查閱實際用量與帳戶計費紀錄,以確認扣款金額。

生成失敗或遭內容審核拒絕會收費嗎?
BytePlus 和 Volcengine 的官方計費規則會對成功生成的內容收費,並指出生成失敗與遭內容審核拒絕不會計費。AIHubMix 的錯誤文件建議查閱計費紀錄以確認歷史扣款;本次未測得成功或失敗生成的帳單。

Flash 結果有多久可以下載?
完成後請立即下載。現有的 Seedance 2.5 指南提醒,下載網址的有效時間約為 30 分鐘;但 Flash 的確切保留期限尚未驗證,而到期欄位為 null 也不代表結果會永久保留。

AIHubMix 支援 MOV 輸出以及編輯/延長功能嗎?
目前的 Flash 結構描述在 extra 下提供了對應欄位,供應商也有文件說明這些功能。由於建立測試收到配額不足的回應後便停止,因此尚未驗證這些功能透過 AIHubMix 使用時是否能端對端正常運作。

繼續閱讀:Seedance 2.5 Flash 系列

資料來源

文件與結構描述檢查日期:2026 年 11 月 16 日;驗證回應記錄時間:UTC 08:26。價格為 BytePlus 官方估算,並非實測閘道費用。

一個閘道接入多家 AI 服務商, 為正式環境而生。

前往推理時代官網