证据边界
一份公共契约参考，而非私有基础设施图
使用它来决定所有权、验证、任务状态、重试、结算、交付、删除和证据应在您自己的集成中位于何处。对于确切的多部分字段和响应，请使用 API 文档 和 OpenAPI 3.1 契约。关于人脸定位、身份迁移、合成、融合和视频一致性中的研究概念，请阅读 AI 换脸的工作原理.
已验证的公共契约
五个异步工作流共享一个控制形态
每个当前的生成工作流都使用 Bearer API 密钥进行身份验证，接受多部分媒体，返回一个 taskId，并通过在同一路由上的 GET 公开所有者作用域的状态。完成使用轮询；目前未发布 Webhook 回调或官方语言软件开发工具包。
| 工作流 | 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、任务ID、账户标识符、工作流、脱敏后的媒体信息、预期信用额度、状态转换、重试次数、错误类别、结算事件和删除时间戳。请勿记录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、准确性分数或质量保证。