生產 API 參考
DeepSwapAI AI 換臉 API
用統一的生產介面接入照片、批次照片、合照對應、影片和 GIF 換臉。先查看關鍵契約、計費單位、任務狀態與邊界；完整欄位和回應請開啟英文 API 參考。
一個契約，五種工作流程
HTTPS、multipart 上傳與 JSON 任務狀態
所有公開生成路由都使用 Bearer API 金鑰，回傳 taskId，並在同一路由透過 GET 查詢任務狀態。
直接回答
一個 API 帳戶涵蓋五種換臉輸入
照片、批次照片、合照多人對應、影片和 GIF 使用同一個生產網域與任務生命週期。請求前檢查格式、大小、時長、目標數量和可用積分；提交後保存 taskId，並在對應的 GET 路由輪詢。
目前公開契約
路由、計費單位和主要邊界
| 工作流程 | POST 路由 | 目前單位 | 主要邊界 |
|---|---|---|---|
| 照片 | POST /api/ai-tasks | 6 積分 / 個輸出 | 一張身份圖和一張目標圖 |
| 批次照片 | POST /api/ai-tasks/batch-face-swap | 6 積分 / 個輸出 | 身份圖與目標圖合計最多 20 張輸入圖片；合計 95 MB |
| 合照對應 | POST /api/ai-tasks/multi-face-swap | 6 積分 / 個選取臉孔 | 最多對應 10 張臉；合計 95 MB |
| 影片 | POST /api/ai-tasks/video | 每向上取整 1 秒 3 積分；最低 12 積分 | MP4、MOV 或 WebM；600 秒；固定最高 1080p 檔 |
| GIF | POST /api/ai-tasks/gif | 每向上取整 1 秒 3 積分；最低 12 積分 | GIF、MP4 或 WebM；30 秒 |
最小整合流程
先驗證請求，再提交生成任務
- 1. 將 API 金鑰保存在服務端，不要放入瀏覽器、行動端套件、日誌或公開儲存庫。
- 2. 按工作流程驗證 multipart 欄位、檔案類型、大小、數量、時長和積分。
- 3. 提交 POST 請求，持久化回傳的 taskId 與預期扣費。
- 4. 輪詢同一路由的 GET 端點，直到 COMPLETED、FAILED 或 CANCELLED。
- 5. 只向任務所屬帳戶交付結果，並依照產品保留規則清理媒體。
公開合約中未記載冪等性金鑰欄位。呼叫服務應禁用重複提交，保留首次 taskId，並在發出另一次 POST 前調解不確定的網路回應。
任務生命週期
保留 taskId 並在終端狀態停止
| 事件 | 任務記錄 | 額度操作 | 客戶端操作 |
|---|---|---|---|
| 任務已接受 | 持久化 taskId 與預期成本 | 將結算視為伺服器擁有 | 開始測量輪詢 |
| 任務已完成 | 終端結果 | 已完成的工作保持結算狀態 | 授權結果檢索 |
| 處理失敗 | 終端失敗 | 目前合約自動退款處理失敗的任務 | 在決定重新提交前閱讀失敗原因 |
| 回應結果不確定 | 在另一次 POST 前進行調解 | 切勿從超時推斷 | 使用儲存的 taskId 或帳戶歷史 |
回應結果不確定 公開合約中未記載冪等性金鑰欄位。呼叫服務應禁用重複提交，保留首次 taskId，並在發出另一次 POST 前調解不確定的網路回應。
計費、隱私與匯出
把可驗證的邊界寫入你的整合
API 僅向已驗證電郵且至少有一筆 PAID 或 COMPLETED 積分訂單的帳戶開放。獎勵與試用積分只能在登入後的網頁流程中使用，不能透過 API 自動呼叫。每個帳戶最多 3 個 API 金鑰；生成介面每個金鑰每分鐘最多 6 次請求。失敗任務按目前規則自動退回積分，媒體在 24 小時內刪除。
開發者問題
上線前確認這些問題
API 支援 webhook 嗎？
目前不支援。提交 POST 後保留 taskId，並在同一工作流程路由使用 GET 輪詢到終態。
API 有官方 SDK 嗎？
目前沒有發布官方語言 SDK。標準 HTTPS、Bearer 驗證、multipart 和 JSON 回應可以透過任意服務端 HTTP 用戶端呼叫。
一個圖片任務需要多少積分？
一張照片、一個批次輸出或一個合照對應臉孔目前都是 12 積分；影片和 GIF 依向上取整的秒數及最低費用計算。
API 金鑰可以放在前端嗎？
不可以。API 金鑰必須保存在服務端，避免寫入瀏覽器套件、行動端二進位檔、日誌、分析事件或工單。
用一個代表性任務先驗證整合
先用獲授權的最小媒體樣本測試欄位、狀態、扣費和結果交付，再擴大到批次或長影片。