文件整合指南
產品
Frontend Guide
這份指南定義 MidSync 前端應該如何做成產品體驗，而不是單純的 raw API 表單。
多個 API 入口的整合指南權限: api.generate
適合情境
產品、前端與設計團隊。
穩定文件搭配 runtime metadata
友善驗證與價格預覽
把影片與用量分開設計
概覽
這份文件是 MidSync 的前端整合總指南。
核心原則是：docs 保持清楚穩定、runtime metadata 驅動 UI、quote 驅動價格、generate 回傳最終扣點。
驗證策略
- 對外 API 使用 Authorization: Bearer <midsync_api_key>。
- 你自己的產品前端應該呼叫 MidSync backend，不要直接從瀏覽器打上游 provider。
- backend 應負責 provider routing、點數扣除、價格 metadata 與 validation error。
產品 UX 原則
- 先載入 runtime metadata。
- 只渲染當前 model 支援的欄位。
- 進階設定用 progressive disclosure。
- 送出前就做 inline validation。
- 價格敏感欄位變化時重新估價。
- 建立成功後顯示最終 charged points。
前端友善 API 分類
分類
Runtime metadata
Quote
Generate
Status
Video
GET /unified-video/models
POST /unified-video/quote
POST /unified-video/generate
以 callback 為主，GET /unified-video/:taskId/status 為 fallback
Usage
不需要
不需要
GET /v1/usage/logs 與 GET /v1/usage/summary
不需要
建議前端流程
- Video：先讀 /models，再依模型渲染欄位，價格敏感欄位變動時呼叫 /quote，最後送 /generate，並以 callback 當成主要完成通知。
- Usage：在 dashboard 顯示點數餘額、用量記錄與摘要卡片。
驗證與錯誤 UX
- metadata 已經提供的規則要先在前端驗證。
- 影片價格以 /quote 為權威答案。
- 設定無效時應停用主要操作按鈕。
- 錯誤訊息要直接講清楚哪裡錯、怎麼修。
資訊架構
- Generation 目前聚焦在 Video。
- Billing 顯示點數、估價與最近用量。
- History 顯示任務狀態與生成歷史。
- Docs 保持穩定可讀，runtime metadata 負責動態渲染。
想直接開始測試？
先到 Settings 建立 general API key，再回到這裡直接複製請求範例。