ドキュメントガイド
製品
Frontend Guide
MidSync のフロントエンドを raw API フォームではなく、製品体験として作るための統合ガイドです。
複数 API の統合ガイド権限: 実際の backend API key scope 設定に依存します
向いている用途
プロダクト、フロントエンド、デザインチーム。
安定した docs と runtime metadata の分離
やさしいバリデーションと価格プレビュー
動画、画像、利用状況を分けた設計
概要
これは MidSync の外部 developer docs 向け統合ガイドです。
基本方針は、主フローを固定し、モデル別ルールをモデルドキュメントに寄せ、タスク作成レスポンスを最終課金点数の基準にすることです。
認証戦略
- 顧客向け API は Authorization: Bearer <midsync_api_key> を使います。
- 自社プロダクトのフロントエンドは MidSync backend を呼び、ブラウザから provider API を直接呼ばないでください。
- backend が 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: ダッシュボードでポイント残高、利用履歴、集計カードを表示します。
バリデーションとエラー UX
- モデルドキュメントにある規則は前端で先に検証する。
- 無効な構成では主要アクションを無効化する。
- エラーは何が悪く、どう直すかを明確に書く。
- 公開 API ドキュメントで /unified-video/* を見せない。
情報設計
- Generation は Unified Video に集中する。
- Billing はポイントと最近の利用を見せる。
- History はタスク状態と生成履歴を見せる。
- Docs は外部開発者向けに安定して読みやすく保つ。
すぐに試したいですか？
Settings で general API key を作成してから、ここに戻ってリクエスト例をコピーしてください。