證據邊界
公開合約參考，非私有基礎設施圖
使用它來決定所有權、驗證、任務狀態、重試、結算、交付、刪除與證據應在您自己的整合中位於何處。如需確切的多部分欄位與回應，請使用 API 文件 及 OpenAPI 3.1 合約。如需關於人臉定位、身份轉移、合成、融合與影片一致性背後的研究概念，請閱讀 AI 人臉置換運作原理.
已驗證的公開合約
五個非同步工作流程共享同一控制形狀
每個當前的生成工作流程都使用 Bearer API 金鑰進行驗證，接受多部分媒體，返回 taskId，並透過對同一路由執行 GET 來公開所有者範圍的狀態。完成使用輪詢機制；目前尚未發布 Webhook 回呼與官方語言 SDK。
| 工作流程 | POST 與輪詢 GET | 成本單位 | 主要限制 |
|---|---|---|---|
| 照片 | /api/ai-tasks | 每任務 3 點額度 | 每張圖片 30 MB |
| 批次照片 | /api/ai-tasks/batch-face-swap | 每輸出 3 點額度 | 20 張圖片，合計 95 MB |
| 分组合影换脸 | /api/ai-tasks/multi-face-swap | 每張替換臉 3 點額度 | 10 張映射臉，合計 95 MB |
| 影片 | /api/ai-tasks/video | 僅臉部場景保留：1/秒，最少 5 秒於 1080p | 600 秒，合計上傳 95 MB |
| GIF / 短片 | /api/ai-tasks/gif | 每秒 1 點額度，最少 5 秒 | 30 秒，目標 95 MB |
即時工作區與 API 文件對於確切格式、最低費用與請求欄位仍具權威性。需要驗證的帳戶電子郵件，每個帳戶可有一個進行中的生成任務，耗盡限制可能返回帶有重試資訊的 HTTP 429。
參考架構
為每個不可逆的決策指定一個所有者
入口與身份
終止 TLS，驗證伺服器持有的金鑰，分配請求關聯 ID，並將每個任務綁定到一個帳戶。
策略與驗證
檢查權限狀態、工作流程欄位、偵測到的媒體類型、位元組大小、數量、持續時間、映射、帳戶就緒狀態與額度可用性。
任務帳本
在返回控制權前，持久化 taskId、所有者、工作流程、預期費用、狀態轉換、時間戳記與結算結果。
有界處理
將請求接受與生成分離，限制進行中的工作，並區分可重試的傳輸失敗與無效輸入。
結算
使用單一原子權威進行保留、完成與失敗任務退款決策，以避免重試導致重複收費或退款。
交付與刪除
按任務所有者授權結果存取，套用圖片匯出權限，並按記錄在案的 24 小時排程刪除媒體。
八步驟請求順序
從請求合約到證據支援的刪除
- 凍結公開請求合約。 選擇確切的工作流程並記錄欄位、媒體限制、成本單位與終端狀態。
- 把關授權、同意與帳戶就緒狀態。 將 API 金鑰保留在伺服器端，並在接受媒體前要求權限決策。
- 在排入佇列前驗證媒體並計算成本。 在進行昂貴工作前檢查偵測到的類型、大小、數量、持續時間、映射與可用額度。
- 建立一個持久的任務記錄。 持久化所有權、工作流程、預期費用、輸入參考、狀態與 taskId。
- 在有界佇列後方非同步處理。 限制並行度，並將暫時性與永久性失敗分類。
- 精確結算額度一次。 提交已完成的工作，並套用記錄在案的處理失敗退款路徑，避免雙重結算。
- 公開所有者範圍的狀態與結果存取。 以測量間隔輪詢，並在 COMPLETED、FAILED 或 CANCELLED 時停止。
- 強制刪除並保留營運證據。 按排程刪除媒體，同時僅保留允許的最低限度任務、帳單、安全與支援記錄。
狀態與結算
保持處理狀態與金錢狀態分離
| 事件 | 任務記錄 | 額度操作 | 客戶端操作 |
|---|---|---|---|
| 請求在任務建立前被拒絕 | 無接受的任務 | 請勿推斷費用 | 修正請求或帳戶狀態 |
| 任務已接受 | 持久化 taskId 與預期成本 | 將結算視為伺服器擁有 | 開始測量輪詢 |
| 任務已完成 | 終端結果 | 已完成的工作保持結算狀態 | 授權結果檢索 |
| 處理失敗 | 終端失敗 | 目前合約自動退款處理失敗的任務 | 在決定重新提交前閱讀失敗原因 |
| 回應結果不確定 | 在另一次 POST 前進行調解 | 切勿從超時推斷 | 使用儲存的 taskId 或帳戶歷史 |
公開合約中未記載冪等性金鑰欄位。呼叫服務應禁用重複提交，保留首次 taskId，並在發出另一次 POST 前調解不確定的網路回應。
失敗策略
僅在失敗類別允許時重試
| 狀態 | 失敗類別 | 架構回應 |
|---|---|---|
| 400 | 無效請求或媒體 | 永久拒絕，直到欄位或媒體變更。 |
| 401 / 403 | 金鑰或帳戶就緒狀態 | 輪換金鑰或完成驗證；不要循環。 |
| 402 | 額度不足 | 僅在確認後添加額度並提交新任務。 |
| 404 | 錯誤的所有者、路由或 taskId | 調解身份與儲存的任務元數據。 |
| 429 | 速率或進行中生成限制 | 在提供時遵循 Retry-After，添加抖動，並限制重試次數。 |
| 500 | 暫時性接受或讀取失敗 | 使用有界指數退避，並在重複提交前進行協調。 |
可觀測性與安全性
在不將敏感媒體複製到日誌中的情況下追蹤控制決策。
建議的任務遙測資料包含關聯ID、taskId、帳戶識別碼、工作流程、經過處理的媒體資訊、預期信用額度、狀態轉換、重試次數、錯誤類別、結算事件和刪除時間戳記。請勿記錄 API 金鑰、人臉影像、完整的上傳檔案名稱、已簽署的結果URL或多部分主體。 W3C Trace Context 建議 定義了可互操作的請求上下文；它是一個設計選項，而非關於 DeepSwapAI 私有實作的聲明。
針對上傳防禦，請驗證解碼後的檔案名稱、偵測到的內容、允許的格式、計數和大小；請勿僅信任瀏覽器提供的 Content-Type。 OWASP File Upload Cheat Sheet 是外部安全參考。使用 同意與揭露規劃工具 作為人類授權閘道，並使用 信任中心 作為當前公開服務邊界。
總體擁有成本
在相同的工作負載測量下比較託管、自託管和混合方案
請勿僅將 API 費用與原始 GPU 租賃進行比較。首先固定一個工作負載窗口：工作流程組合、媒體持續時間和解析度、峰值並發數、重試率、保留期限、審查量和所需可用性。然後將所有經常性及與故障相關的成本分配至同一窗口。
| 成本維度 | 託管 API | 自託管 | 混合 | 需收集的證據 |
|---|---|---|---|---|
| 處理能力 | 已發布的任務或持續時間費用 | GPU 租賃或購買、閒置空間、擴展和模型運行時 | 內部基準加上外部溢流或專業處理 | 完成的單位、持續時間、解析度、並發數和利用率 |
| 工程與營運 | 整合、任務持久化、輪詢、審查和供應商變更處理 | 模型服務、佇列、升級、容量規劃、部署和待命回應 | 編排、提供者抽象化和內部平台所有權 | 測量的工程師工時、發布節奏和待命負載 |
| 安全性與治理 | 應用程式同意閘道、帳戶政策、審查和證據 | 所有審核、儲存、刪除、存取控制和稽核控制 | 共享控制，每個決策有明確的負責人 | 審查分鐘數、升級率、保留範圍和控制負責人 |
| 儲存與傳遞 | 應用程式端的輸入、結果和網路處理 | 輸入、中間資料、結果、備份、出口和刪除操作 | 內部記錄加上有界限的提供者傳輸 | 保留的位元組數、傳輸量、保留時間和刪除工作量 |
| 故障與可靠性 | 重試、協調、提供者中斷處理和切換成本 | 冗餘、事件回應、失敗任務、復原和未使用容量 | 依賴故障和內部編排故障 | 故障率、復原時間、重複工作和支援負載 |
此框架不發布自託管的價格基準，也不聲明託管、自託管或混合方案普遍更便宜。決策取決於工作負載以及在同一時期內可被證實的控制措施。
建置決策
根據您必須擁有的控制措施選擇託管、自託管或混合方案
| 模型 | 您擁有 | 外部依賴 | 最佳適用情境 |
|---|---|---|---|
| 託管 API | 同意閘道、應用程式使用者體驗、任務持久化、輪詢、審查和業務政策 | 已發布的 API、限制、定價和處理行為 | 優先考慮整合速度而非基礎設施控制的團隊 |
| 自託管 | 模型、GPU 容量、佇列、審核、儲存、安全性、結算、刪除和事件回應 | 模型和基礎設施供應鏈 | 具有正當控制或部署需求以及營運能力的團隊 |
| 混合 | 內部政策、編排、稽核記錄、審查和提供者抽象化 | 一個或多個有界限的生成服務 | 需要在無需操作每個模型元件的情況下獲得應用程式級控制的團隊 |
來源與方法
當前產品事實加上主要外部標準
DeepSwapAI 產品團隊於 2026 年 7 月 22 日檢查了五條公開路由、Bearer 認證、多部分請求、任務狀態、輪詢流程、錯誤回應、並發邊界、信用結算、試用圖片權限和 24 小時媒體刪除。建議的控制措施參考了 OpenAPI 規格 3.1.2, OWASP 上傳指南, NIST AI RMF 1.0, 以及 W3C Trace Context. 請參閱 聲明驗證方法論 了解如何將當前產品陳述與一般設計指南分開。
架構問題
了解公開合約的內容與非內容
這是 DeepSwapAI 的私有生產架構嗎？
不。它是一個公開合約的設計參考，不揭露提供者拓撲、佇列技術、模型放置、工作者數量、內部網路或服務級別目標。
客戶端如何得知任務已完成？
保留 POST 返回的 taskId，並在同一工作流程路由上輪詢 GET，直到 COMPLETED、FAILED 或 CANCELLED。目前未發布 Webhook 回調。
API 金鑰可以放在客戶端程式碼中嗎？
不行。請將其視為伺服器端機密，並遠離瀏覽器套件、行動裝置二進位檔、儲存庫、分析工具、日誌和支援訊息。
API 是否發布冪等金鑰？
沒有記錄任何冪等金鑰欄位。請防止重複提交，持久化第一個 taskId，並在再次 POST 之前協調不確定的回應。
此設計是否保證吞吐量或品質？
不。它不是基準、SLA、準確性分數或品質保證。