生产 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 密钥必须保存在服务端，并避免写入浏览器包、移动端二进制、日志、分析事件或工单。
用一个代表性任务先验证集成
先用获授权的最小媒体样本测试字段、状态、扣费和结果交付，再扩大到批量或长视频。