文件影片 API

影音

Unified Video API

這是 MidSync 給產品前端與 API key 整合使用的統一影片生成入口。

POST /unified-video/generate權限: 依後端實際 API key scope 設定而定

適合情境

要做客戶端影片生成體驗與 API 整合的團隊。

統一影片生成

送出前先估價

依模型 metadata 與規則組裝 request body

怎麼呼叫

bash

curl --request POST \
  --url https://api.midsync.dev/unified-video/generate \
  --header "Authorization: Bearer <your_api_key>" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedance-1.5-pro",
    "prompt": "黃昏海邊的電影感鏡頭，海浪輕拍岸邊",
    "resolution": "720p",
    "aspectRatio": "16:9",
    "duration": 8,
    "generateAudio": true
  }'

概覽怎麼使用這支 API Endpoints 模型 seedance-1.5-pro 請求欄位規則價格回應整合建議接收結果：callbackUrl 與輪詢

概覽

這頁文件描述的是 MidSync 的統一影片生成流程，適合產品前端與 API key 整合共用。

建議以前端先讀 GET /unified-video/models、送出前呼叫 POST /unified-video/quote，再用 POST /unified-video/generate 建立任務。

怎麼使用這支 API

Step 1

先選擇影片模型，例如 seedance-1.5-pro、kling-2.5-turbo、runway 或 grok-video。

Step 2

先呼叫 GET /unified-video/models，再把同一份 request body 依序送到 POST /unified-video/quote 與 POST /unified-video/generate。

Step 3

保存回傳的 taskId、providerTaskId、model 與 pointsCharged，再用 callback 或後續查詢流程接結果。

Endpoints

GET /unified-video/models 提供前端 metadata，POST /unified-video/quote 提供點數預估，POST /unified-video/generate 建立真正任務。
各模型的參數規則請看下方模型文件。
帳務與用量請搭配 GET /v1/usage/logs 與 GET /v1/usage/summary。

模型能力總覽

模型

適合情境

主要輸入

價格規則

seedance-1.5-pro

文字轉影片、圖片轉影片

prompt、images、aspectRatio、resolution、duration

依 resolution、duration、generateAudio 動態計價

seedance-1.5-pro 請求欄位

必填

model 與 prompt。prompt 長度必須在 3..2500。

媒體輸入

images 最多 2 張圖片 URL。0 張代表文字轉影片，1 到 2 張代表圖片轉影片。

輸出控制

aspectRatio 支援 1:1、4:3、3:4、16:9、9:16、21:9、2:3、3:2。resolution 支援 480p、720p、1080p。duration 支援 4、8、12。

切換項

fixedLens、generateAudio、nsfwChecker 為選填布林值。projectId 為選填內部欄位。

回呼

callbackUrl 為選填 URL。提供後，影片完成時 server 會自動 POST 結果到這個 URL。

驗證規則

seedance-1.5-pro 不應出現 firstFrameUrl、lastFrameUrl、referenceImageUrls、referenceVideoUrls、referenceAudioUrls、returnLastFrame、webSearch。
seedance-1.5-pro 的 images.length 不能超過 2。
seedance-2 與 seedance-2-fast 目前暫時不可用，客戶端先不要露出這兩個模型。

價格說明

seedance-1.5-pro 依 resolution、duration、generateAudio 走動態價格矩陣。
對外 API 文件應以實際建立任務後回傳的 charged points 當成最終扣點依據。

回應格式

json

{
  "success": true,
  "taskId": "generated-task-id",
  "providerTaskId": "provider-task-id",
  "model": "seedance-1.5-pro",
  "providerModel": "bytedance/seedance-1.5-pro",
  "pointsCharged": 25,
  "status": "submitted",
  "estimatedTime": "~2-3 min",
  "estimatedTimeSec": 140
}

建立任務成功後，至少保存 taskId、providerTaskId 與 model。

整合建議

不要把 /unified-video/* 內部產品路徑當成對外 API 文件主入口。
對外文件應固定使用 /unified-video/generate，模型差異則放在各模型規格頁處理。
客戶的花費與歷史紀錄，應從 usage logs 與 summary 呈現。

接收結果：callbackUrl 與輪詢

在 generate 請求中帶上 callbackUrl，影片完成後 server 會自動 POST 結果到這個 URL。正式整合建議用這個方式。

或者你也可以輪詢 GET /unified-video/:taskId/status，直到 status 變成 completed 或 failed。輪詢比較適合 debug 或 webhook 不可行的情境。

想直接開始測試？

先到 Settings 建立 general API key，再回到這裡直接複製請求範例。

打開 API 金鑰