文件整合指南
產品
Frontend Guide
這份指南定義 MidSync 前端應該如何做成產品體驗，而不是單純的 raw API 表單。
多個 API 入口的整合指南權限: 依後端實際 API key scope 設定而定
適合情境
產品、前端與設計團隊。
穩定文件搭配 runtime metadata
友善驗證與價格預覽
把影片與用量分開設計
概覽
這份文件是 MidSync 對外 developer docs 的前端整合總指南。
核心原則是：流程固定、模型規則寫在模型文件、建立任務回應本身就是最終扣點依據。
驗證策略
- 對外 API 使用 Authorization: Bearer <midsync_api_key>。
- 你自己的產品前端應該呼叫 MidSync backend，不要直接從瀏覽器打上游 provider。
- backend 應負責 provider routing、點數扣除、價格 metadata 與 validation error。
產品 UX 原則
- 主流程要固定。
- 只渲染當前模型文件有寫支援的欄位。
- 進階設定用 progressive disclosure。
- 送出前就做 inline validation。
- 建立成功後顯示最終 charged points。
- 用 usage endpoints 做帳務可視化。
前端友善 API 分類
分類
模型規則
建立任務
帳務
完成方式
Video
看模型文件
POST /unified-video/generate
GET /v1/usage/logs 與 GET /v1/usage/summary
以 callback 為主，必要時再追 task
Usage
不需要
不需要
GET /v1/usage/logs 與 GET /v1/usage/summary
不需要
建議前端流程
- Video：先讓客戶選模型，再依模型文件渲染欄位，最後送 POST /unified-video/generate。
- 建立成功後清楚顯示 taskId、providerTaskId 與 pointsCharged。
- Usage：在 dashboard 顯示點數餘額、用量記錄與摘要卡片。
驗證與錯誤 UX
- 模型文件已經寫出的規則，前端要先驗證。
- 設定無效時應停用主要操作按鈕。
- 錯誤訊息要直接講清楚哪裡錯、怎麼修。
- 不要在公開 API 文件暴露 /unified-video/* 內部路徑。
資訊架構
- Generation 聚焦在 Unified Video。
- Billing 顯示點數與最近用量。
- History 顯示任務狀態與生成歷史。
- Docs 保持穩定可讀，供外部開發者直接理解。
想直接開始測試？
先到 Settings 建立 general API key，再回到這裡直接複製請求範例。