使用 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。提交工作前:
- 在AIHubMix 控制台啟用非同步媒體工作。文件指出,未啟用此功能的帳戶會收到錯誤
403 async_not_enabled。 - 確認 API 金鑰具有存取權限,且帳戶餘額充足。即時檢查回傳
402 insufficient_quota,訊息為Your account has insufficient quota. Add credits and try again. - 在 shell 中匯出
AIHUBMIX_API_KEY。請勿將金鑰放入原始碼檔案或瀏覽器程式碼。 - 取得目前的 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 系列
- 選擇模型前,想先了解價格比較與解析度取捨嗎?Seedance 2.5 Flash 與 2.5、2.0 比較:值得升級嗎?
資料來源
文件與結構描述檢查日期:2026 年 11 月 16 日;驗證回應記錄時間:UTC 08:26。價格為 BytePlus 官方估算,並非實測閘道費用。
- 影片生成 API(AIHubMix 文件)
- 非同步任務 API(AIHubMix 文件)
- Doubao 真人素材指南(AIHubMix 文件)
- ModelArk 定價(BytePlus)
- Seedance 2.5 教學(Volcengine Ark)



