証拠の境界
公開契約リファレンスであり、プライベートインフラストラクチャ図ではない
所有権、検証、タスク状態、再試行、決済、配信、削除、および証拠が独自の統合のどこに存在すべきかを決定するために使用します。正確なマルチパートフィールドとレスポンスについては、 API ドキュメント および OpenAPI 3.1 契約. 顔の位置特定、アイデンティティ転送、合成、ブレンディング、および動画の一貫性に関する研究概念については、 AI顔交換の仕組み.
を参照してください。
検証済み公開契約
現在のすべての生成ワークフローは、Bearer APIキーで認証し、マルチパートメディアを受け入れ、以下を返します。 taskIdまた、同じルートのGETを通じて所有者スコープのステータスを公開します。完了はポーリングを使用します。Webhookコールバックと公式言語SDKは現在公開されていません。
| を返し、同じルートでのGETを通じて所有者スコープのステータスを公開します。完了はポーリングを使用します。Webhook コールバックと公式言語SDKは現在公開されていません。 | ワークフロー | POST とポーリング GET | コスト単位 |
|---|---|---|---|
| 写真 | /api/ai-tasks | 主要な制限 | タスクあたり3クレジット |
| 画像あたり30 MB | /api/ai-tasks/batch-face-swap | バッチ写真 | 出力あたり3クレジット |
| マッピングされたグループ写真 | /api/ai-tasks/multi-face-swap | 20画像、合計95 MB | 置換顔あたり3クレジット |
| 動画 | /api/ai-tasks/video | シーンの保存を伴う顔のみ：1/秒、最小5、1080p | 600秒、95 MBの合計アップロード |
| GIF / ショートクリップ | /api/ai-tasks/gif | 1秒あたり1クレジット、最小5 | 1秒あたり1クレジット、最小5 |
ライブワークスペースとAPIドキュメントは、正確な形式、最低料金、リクエストフィールドについて信頼できる情報源です。確認済みのアカウントメールが必要で、アカウントごとに1つの生成がアクティブにでき、制限を使い果たすとリトライ情報を含むHTTP 429が返されることがあります。
リファレンスアーキテクチャ
リファレンスアーキテクチャ
各不可逆的な決定に1つの所有者を与える
イングレスとアイデンティティ
TLS を終端し、サーバーが保持するキーを認証し、リクエスト相関IDを割り当て、すべてのタスクを1つのアカウントにバインドします。
ポリシーと検証
許可状態、ワークフローフィールド、検出されたメディアタイプ、バイトサイズ、数、再生時間、マッピング、アカウント準備状況、およびクレジット利用可能性を確認します。
タスク元帳
制御を返す前に、taskId、所有者、ワークフロー、予想請求額、状態遷移、タイムスタンプ、および決済結果を保持します。
境界のある処理
リクエスト受け入れを生成から分離し、アクティブな作業を制限し、再試行可能なトランスポート障害を無効な入力から区別します。
決済
予約、完了、および失敗タスクの返金決定に1つのアトミック権限を使用して、再試行が2回請求または返金できないようにします。
配信と削除
タスク所有者による結果アクセスを認可し、画像エクスポート権限を適用し、文書化された24時間スケジュールでメディアを削除します。
8ステップのリクエストシーケンス
- リクエスト契約から証拠に裏付けられた削除まで 公開リクエスト契約を固定します。
- 正確なワークフローを選択し、フィールド、メディア制限、コスト単位、および終端状態を記録します。 APIキーをサーバーサイドに保持し、メディアを受け入れる前に権限判断を要求します。
- メディアを検証し、キューに入れる前にコストを計算します。 エンキュー前にメディアを検証し、コストを計算します。
- 高価な作業の前に、検出されたタイプ、サイズ、数、再生時間、マッピング、および利用可能なクレジットを検査します。 1つの永続的なタスクレコードを作成します。
- 所有権、ワークフロー、予想請求額、入力参照、状態、および taskId を保持します。 境界のあるキューの背後で非同期に処理します。
- 同時実行性を制限し、一時的な障害と永続的な障害を分類します。 クレジットを正確に1回決済します。
- 完了した作業を確定し、文書化された失敗処理の返金パスを二重決済なしで適用します。 所有者スコープのステータスと結果アクセスを公開します。
- 測定された間隔でポーリングし、COMPLETED、FAILED、または CANCELLED で停止します。 削除を実施し、運用証拠を保持します。
状態と決済
スケジュールに従ってメディアを削除し、許可された最小限のタスク、請求、セキュリティ、およびサポート記録のみを保持します。
| または FAILED / CANCELLED | イベント | タスクレコード | クライアントアクション |
|---|---|---|---|
| タスク作成前にリクエストが拒否されました | 受け入れられたタスクがありません | 課金を推測しないでください | リクエストまたはアカウントの状態を修正してください |
| タスクが受け入れられました | taskIdと予想コストを保持してください | 決済をサーバー所有として扱ってください | 測定されたポーリングを開始してください |
| タスクが完了しました | 最終結果 | 完了した作業は決済されたままです | 結果の取得を許可してください |
| 処理に失敗しました | 最終的な障害 | 現在の契約は、失敗した処理を自動的に返金します | 再送信を決定する前に障害を確認してください |
| 応答結果が不確かです | 別のPOSTの前に調整してください | タイムアウトから推測しないでください | 保存されたtaskIdまたはアカウント履歴を使用してください |
公開契約書にidempotency-keyフィールドは文書化されていません。呼び出しサービスは重複送信を無効にし、最初のtaskIdを保持し、別のPOSTを発行する前に不確かなネットワーク応答を調整する必要があります。
障害ポリシー
障害クラスが許可する場合にのみ再試行してください
| ステータス | 障害クラス | アーキテクチャ応答 |
|---|---|---|
| 400 | 無効なリクエストまたはメディア | フィールドまたはメディアが変更されるまで永久に拒否してください。 |
| 401 / 403 | キーまたはアカウントの準備状態 | キーをローテーションするか、確認を完了してください。ループしないでください。 |
| 402 | クレジット不足 | クレジットを追加し、確認後にのみ新しいタスクを送信してください。 |
| 404 | 間違った所有者、ルート、またはtaskId | IDと保存されたタスクメタデータを調整してください。 |
| 429 | レートまたはアクティブ生成制限 | Retry-Afterが提供されている場合はそれを尊重し、ジッターを追加し、再試行回数を制限してください。 |
| 500 | 一時的な受け入れまたは読み取り障害 | 制限付き指数バックオフを使用し、重複送信の前に調整してください。 |
観測可能性とセキュリティ
トレース制御判断を機密メディアをログにコピーせずに行う
推奨されるタスクテレメトリには、相関ID、タスクID、アカウント識別子、ワークフロー、サニタイズされたメディア情報、予想クレジット額、状態遷移、リトライ回数、エラークラス、決済イベント、削除タイムスタンプが含まれます。APIキー、顔画像、完全なアップロードファイル名、署名済み結果URL、マルチパートボディはログに記録しないでください。 W3C Trace Context勧告 は、相互運用可能なリクエストコンテキストを定義します。これは設計上の選択肢であり、DeepSwapAIのプライベート実装に関する主張ではありません。
アップロード防御では、デコードされたファイル名、検出されたコンテンツ、許可された形式、数、サイズを検証してください。ブラウザが提供するContent-Typeだけを信頼しないでください。 OWASP File Upload Cheat Sheet は外部セキュリティリファレンスです。 同意および開示プランナー を人間による認可ゲートとして使用し、 トラストセンター を現在の公開サービス境界として使用します。
総保有コスト（TCO）
管理型、セルフホスト型、ハイブリッド型を同じ測定ワークロードで比較する
APIの料金と生のGPUレンタル料金だけを比較しないでください。まず、1つのワークロードウィンドウを固定します。ワークフローミックス、メディアの長さと解像度、ピーク同時実行数、リトライ率、保持期間、レビュー量、必要な可用性。次に、すべての定期コストと障害関連コストを同じウィンドウに割り当てます。
| コスト次元 | 管理型API | セルフホスト型 | ハイブリッド型 | 収集する証拠 |
|---|---|---|---|---|
| 処理能力 | 公開されたタスクまたは時間単位の料金 | GPUリースまたは購入、アイドルヘッドルーム、スケーリング、モデルランタイム | 内部ベースラインに外部オーバーフローまたは専門処理を加えたもの | 完了ユニット数、時間、解像度、同時実行数、使用率 |
| エンジニアリングと運用 | 統合、タスク永続化、ポーリング、レビュー、ベンダー変更処理 | モデル提供、キュー、アップグレード、キャパシティプランニング、デプロイ、オンコール対応 | オーケストレーション、プロバイダー抽象化、内部プラットフォーム所有権 | 測定されたエンジニア時間、リリース頻度、オンコール負荷 |
| 安全性とガバナンス | アプリケーション同意ゲート、アカウントポリシー、レビュー、証拠 | すべてのモデレーション、ストレージ、削除、アクセス制御、監査コントロール | すべての決定に明示的な所有者がいる共有コントロール | レビュー時間、エスカレーション率、保持範囲、コントロール所有者 |
| ストレージと配信 | アプリケーション側の入力、結果、ネットワーク処理 | 入力、中間、結果、バックアップ、出力、削除操作 | 内部レコードに制限付きプロバイダー転送を加えたもの | 保持バイト数、転送量、保持時間、削除作業 |
| 障害と信頼性 | リトライ、調整、プロバイダー障害処理、切り替えコスト | 冗長性、インシデント対応、失敗ジョブ、復旧、未使用容量 | 依存関係障害と内部オーケストレーション障害の両方 | 障害率、復旧時間、重複作業、サポート負荷 |
このフレームワークは、セルフホスト型の価格ベンチマークを公開しておらず、管理型、セルフホスト型、ハイブリッド型が普遍的に安価であるとは主張していません。決定は、同じ期間に証拠を示せるワークロードとコントロールに依存します。
構築判断
所有しなければならないコントロールに基づいて、管理型、セルフホスト型、ハイブリッド型を選択する
| モデル | あなたが所有するもの | 外部依存関係 | 最適な適合 |
|---|---|---|---|
| 管理型API | 同意ゲート、アプリケーションUX、タスク永続化、ポーリング、レビュー、ビジネスポリシー | 公開されたAPI、制限、価格、処理動作 | インフラ制御よりも統合スピードを優先するチーム |
| セルフホスト型 | モデル、GPU容量、キュー、モデレーション、ストレージ、セキュリティ、決済、削除、インシデント対応 | モデルとインフラサプライチェーン | 正当な制御または展開要件と運用能力を持つチーム |
| ハイブリッド型 | 内部ポリシー、オーケストレーション、監査記録、レビュー、プロバイダー抽象化 | 1つ以上の制限付き生成サービス | すべてのモデルコンポーネントを運用せずにアプリケーションレベルの制御を必要とするチーム |
ソースと方法
現在の製品情報に主要な外部標準を加えたもの
DeepSwapAI製品チームは、2026年7月22日に、5つの公開ルート、Bearer認証、マルチパートリクエスト、タスク状態、ポーリングフロー、エラーレスポンス、同時実行境界、クレジット決済、トライアル画像権利、24時間メディア削除を確認しました。推奨されるコントロールは、 OpenAPI 仕様 3.1.2, OWASPアップロードガイダンス, NIST AI RMF 1.0,および W3C Trace Contextに基づいています。現在の製品ステートメントが一般的な設計ガイダンスとどのように区別されているかについては、 主張検証方法論 を参照してください。
アーキテクチャに関する質問
公開契約が何を確立し、何を確立しないかを理解する
これは DeepSwapAI のプライベートプロダクションアーキテクチャですか？
いいえ。これは公開契約の設計リファレンスであり、プロバイダートポロジー、キュー技術、モデル配置、ワーカー数、内部ネットワーク、またはサービスレベル目標を開示しません。
クライアントはタスクが完了したことをどのように知るのですか？
POSTで返されたtaskIdを保持し、同じワークフロールートでCOMPLETED、FAILED、またはCANCELLEDになるまでGETをポーリングします。Webhookコールバックは現在公開されていません。
APIキーをクライアントコードに配置できますか？
いいえ。サーバーサイドのシークレットとして扱い、ブラウザバンドル、モバイルバイナリ、リポジトリ、分析、ログ、サポートメッセージから遠ざけてください。
APIは冪等性キーを公開していますか？
冪等性キーフィールドは文書化されていません。重複送信を防ぎ、最初のtaskIdを永続化し、別のPOSTの前に不確かなレスポンスを調整してください。
この設計はスループットや品質を保証しますか？
いいえ。これはベンチマーク、SLA、精度スコア、または品質保証ではありません。