Ranh giới bằng chứng
Một tài liệu tham khảo hợp đồng công khai, không phải sơ đồ cơ sở hạ tầng riêng tư
Sử dụng nó để quyết định nơi quyền sở hữu, xác thực, trạng thái tác vụ, thử lại, thanh toán, phân phối, xóa và bằng chứng nên tồn tại trong tích hợp của riêng bạn. Để biết các trường và phản hồi multipart chính xác, hãy sử dụng Tài liệu API và Hợp đồng OpenAPI 3.1. Đối với các khái niệm nghiên cứu bên trong nội địa hóa khuôn mặt, chuyển giao danh tính, tổng hợp, pha trộn và nhất quán video, hãy đọc cách hoán đổi khuôn mặt AI hoạt động.
Hợp đồng công khai đã xác minh
Năm quy trình làm việc bất đồng bộ chia sẻ một hình dạng kiểm soát
Mọi quy trình làm việc tạo hiện tại xác thực bằng khóa Bearer API, chấp nhận phương tiện multipart, trả về một taskId, và hiển thị trạng thái theo phạm vi chủ sở hữu thông qua GET trên cùng một route. Hoàn thành sử dụng polling; callback webhook và SDK ngôn ngữ chính thức hiện chưa được công bố.
| Quy trình | POST và polling GET | Đơn vị chi phí | Ràng buộc chính |
|---|---|---|---|
| Ảnh | /api/ai-tasks | 6 tín dụng mỗi tác vụ | 10MB |
| Ảnh hàng loạt | /api/ai-tasks/batch-face-swap | 6 tín dụng mỗi đầu ra | 20 ảnh, 95 MB tổng cộng |
| Ảnh nhóm đã ánh xạ | /api/ai-tasks/multi-face-swap | 6 tín dụng mỗi khuôn mặt thay thế | 10 khuôn mặt đã ánh xạ, 95 MB tổng cộng |
| Video | /api/ai-tasks/video | Chỉ khuôn mặt với bảo toàn cảnh: 3/giây, tối thiểu 12 tại 1080p | 600 giây, tổng tải lên 95 MB |
| GIF / clip ngắn | /api/ai-tasks/gif | 3 tín dụng mỗi giây, tối thiểu 12 | 30 giây, mục tiêu 95 MB |
Không gian làm việc trực tiếp và tài liệu API vẫn là căn cứ cho định dạng chính xác, mức phí tối thiểu và các trường yêu cầu. Tác vụ tài khoản và API cần email đã xác minh, mỗi tài khoản chỉ có một lượt tạo đang hoạt động, và khi hết giới hạn có thể trả về HTTP 429 kèm thông tin thử lại.
Kiến trúc tham khảo
Giao mỗi quyết định không thể đảo ngược cho một chủ sở hữu
Ingress và danh tính
Kết thúc TLS, xác thực khóa do máy chủ nắm giữ, gán ID tương quan yêu cầu và liên kết mọi tác vụ với một tài khoản.
Chính sách và xác thực
Kiểm tra trạng thái cho phép, trường quy trình làm việc, loại phương tiện được phát hiện, kích thước byte, số lượng, thời lượng, ánh xạ, sẵn sàng tài khoản và khả dụng tín dụng.
Sổ cái tác vụ
Lưu trữ taskId, chủ sở hữu, quy trình làm việc, phí dự kiến, chuyển đổi trạng thái, dấu thời gian và kết quả thanh toán trước khi trả lại quyền kiểm soát.
Xử lý có giới hạn
Tách biệt chấp nhận yêu cầu khỏi tạo, giới hạn công việc đang hoạt động và phân biệt lỗi vận chuyển có thể thử lại với đầu vào không hợp lệ.
Thanh toán
Sử dụng một cơ quan nguyên tử cho các quyết định dự trữ, hoàn thành và hoàn tiền tác vụ thất bại để một lần thử lại không thể tính phí hoặc hoàn tiền hai lần.
Phân phối và xóa
Ủy quyền truy cập kết quả theo chủ sở hữu tác vụ, áp dụng quyền xuất ảnh và xóa phương tiện theo lịch trình 24 giờ được ghi lại.
Trình tự yêu cầu tám bước
Chuyển từ hợp đồng yêu cầu sang xóa dựa trên bằng chứng
- Đóng băng hợp đồng yêu cầu công khai. Chọn quy trình làm việc chính xác và các trường bản ghi, giới hạn phương tiện, đơn vị chi phí và trạng thái đầu cuối.
- Ủy quyền cổng, sự đồng ý và sẵn sàng của tài khoản. Giữ khóa API ở phía máy chủ và yêu cầu quyết định cấp phép trước khi chấp nhận phương tiện.
- Xác thực phương tiện và tính toán chi phí trước khi xếp hàng đợi. Kiểm tra loại, kích thước, số lượng, thời lượng, ánh xạ và tín dụng khả dụng đã phát hiện trước khi thực hiện công việc tốn kém.
- Tạo một bản ghi tác vụ bền vững. Lưu giữ quyền sở hữu, quy trình làm việc, khoản phí dự kiến, tham chiếu đầu vào, trạng thái và taskId.
- Xử lý không đồng bộ phía sau một hàng đợi có giới hạn. Giới hạn đồng thời và phân loại lỗi tạm thời so với lỗi vĩnh viễn.
- Thanh toán tín dụng chính xác một lần. Cam kết công việc đã hoàn thành và áp dụng quy trình hoàn tiền xử lý thất bại đã được ghi lại mà không thanh toán hai lần.
- Hiển thị trạng thái và quyền truy cập kết quả trong phạm vi chủ sở hữu. Thăm dò ở khoảng thời gian đo được và dừng lại ở COMPLETED, FAILED hoặc CANCELLED.
- Thực thi xóa và giữ lại bằng chứng hoạt động. Xóa phương tiện theo lịch trình trong khi chỉ giữ lại bản ghi tác vụ, thanh toán, bảo mật và hỗ trợ tối thiểu được phép.
Trạng thái và thanh toán
Giữ trạng thái xử lý tách biệt khỏi trạng thái tiền tệ
| Sự kiện | Bản ghi tác vụ | Hành động tín dụng | Hành động của khách hàng |
|---|---|---|---|
| Yêu cầu bị từ chối trước khi tạo tác vụ | Không có tác vụ được chấp nhận | Không suy luận một khoản phí | Sửa yêu cầu hoặc trạng thái tài khoản |
| Tác vụ được chấp nhận | Lưu trữ taskId và chi phí dự kiến | Coi việc thanh toán là thuộc sở hữu của máy chủ | Bắt đầu thăm dò đo được |
| Tác vụ hoàn thành | Kết quả đầu cuối | Công việc đã hoàn thành vẫn được thanh toán | Ủy quyền truy xuất kết quả |
| Xử lý thất bại | Lỗi đầu cuối | Hợp đồng hiện tại tự động hoàn tiền xử lý thất bại | Đọc lỗi trước khi quyết định gửi lại |
| Kết quả phản hồi không chắc chắn | Đối chiếu trước khi POST khác | Không bao giờ đoán từ một thời gian chờ | Sử dụng taskId đã lưu trữ hoặc lịch sử tài khoản |
Không có trường khóa idempotency nào được ghi lại trong hợp đồng công khai. Dịch vụ gọi nên vô hiệu hóa việc gửi trùng lặp, lưu trữ taskId đầu tiên và đối chiếu phản hồi mạng không chắc chắn trước khi phát hành POST khác.
Chính sách lỗi
Chỉ thử lại khi lớp lỗi cho phép
| Trạng thái | Lớp lỗi | Phản hồi kiến trúc |
|---|---|---|
| 400 | Yêu cầu hoặc phương tiện không hợp lệ | Từ chối vĩnh viễn cho đến khi các trường hoặc phương tiện thay đổi. |
| 401 / 403 | Khóa hoặc tài khoản sẵn sàng | Xoay khóa hoặc hoàn tất xác minh; không lặp lại. |
| 402 | Không đủ tín dụng | Thêm tín dụng và gửi tác vụ mới chỉ sau khi xác nhận. |
| 404 | Sai chủ sở hữu, tuyến đường hoặc taskId | Đối chiếu danh tính và siêu dữ liệu tác vụ đã lưu trữ. |
| 429 | Giới hạn tốc độ hoặc thế hệ đang hoạt động | Tôn trọng Retry-After khi được cung cấp, thêm jitter và giới hạn số lần thử lại. |
| 500 | Lỗi chấp nhận hoặc đọc tạm thời | Sử dụng backoff theo cấp số nhân có giới hạn và đối chiếu trước khi gửi trùng lặp. |
Khả năng quan sát và bảo mật
Kiểm soát các quyết định theo dõi mà không sao chép phương tiện nhạy cảm vào nhật ký
Phép đo từ xa tác vụ được khuyến nghị bao gồm ID tương quan, taskId, mã định danh tài khoản, quy trình làm việc, dữ kiện phương tiện đã được làm sạch, số tiền tín dụng dự kiến, chuyển đổi trạng thái, số lần thử lại, lớp lỗi, sự kiện thanh toán và dấu thời gian xóa. Không ghi lại khóa API, hình ảnh khuôn mặt, tên tệp đã tải lên hoàn chỉnh, URL kết quả đã ký hoặc nội dung multipart. Khuyến nghị ngữ cảnh theo dõi W3C xác định ngữ cảnh yêu cầu có thể tương tác; đó là một tùy chọn thiết kế, không phải là tuyên bố về triển khai riêng tư của DeepSwapAI.
Đối với biện pháp phòng vệ tải lên, hãy xác thực tên tệp đã giải mã, nội dung đã phát hiện, định dạng được phép, số lượng và kích thước; không chỉ tin tưởng vào Content-Type do trình duyệt cung cấp. OWASP File Upload Cheat Sheet là tài liệu tham khảo bảo mật bên ngoài. Sử dụng công cụ lập kế hoạch đồng ý và tiết lộ cho cổng ủy quyền của con người và Trung tâm tin cậy cho các ranh giới dịch vụ công khai hiện tại.
Tổng chi phí sở hữu
So sánh quản lý, tự lưu trữ và kết hợp trên cùng một khối lượng công việc đo được
Không so sánh phí API với việc thuê GPU thô một mình. Trước tiên hãy cố định một cửa sổ khối lượng công việc: hỗn hợp quy trình làm việc, thời lượng và độ phân giải phương tiện, đồng thời cao điểm, tỷ lệ thử lại, lưu giữ, khối lượng đánh giá và tính khả dụng yêu cầu. Sau đó, chỉ định mọi chi phí định kỳ và liên quan đến lỗi cho cùng một cửa sổ.
| Kích thước chi phí | API được quản lý | Tự lưu trữ | Kết hợp | Bằng chứng cần thu thập |
|---|---|---|---|---|
| Công suất xử lý | Phí tác vụ hoặc thời lượng đã công bố | Cho thuê hoặc mua GPU, khoảng trống nhàn rỗi, mở rộng quy mô và thời gian chạy mô hình | Đường cơ sở nội bộ cộng với xử lý tràn hoặc chuyên gia bên ngoài | Đơn vị đã hoàn thành, thời lượng, độ phân giải, đồng thời và mức sử dụng |
| Kỹ thuật và vận hành | Tích hợp, lưu trữ tác vụ, thăm dò, đánh giá và xử lý thay đổi nhà cung cấp | Phục vụ mô hình, hàng đợi, nâng cấp, lập kế hoạch công suất, triển khai và phản hồi trực | Điều phối, trừu tượng hóa nhà cung cấp và quyền sở hữu nền tảng nội bộ | Giờ kỹ sư đo được, nhịp độ phát hành và tải trực |
| An toàn và quản trị | Cổng đồng ý ứng dụng, chính sách tài khoản, đánh giá và bằng chứng | Tất cả kiểm duyệt, lưu trữ, xóa, kiểm soát truy cập và kiểm soát kiểm toán | Kiểm soát chia sẻ với chủ sở hữu rõ ràng cho mọi quyết định | Phút đánh giá, tỷ lệ leo thang, phạm vi lưu giữ và chủ sở hữu kiểm soát |
| Lưu trữ và phân phối | Xử lý đầu vào, kết quả và mạng phía ứng dụng | Hoạt động đầu vào, trung gian, kết quả, sao lưu, chuyển ra ngoài và xóa | Bản ghi nội bộ cộng với chuyển giao nhà cung cấp có giới hạn | Byte được lưu giữ, khối lượng chuyển giao, thời gian lưu giữ và công việc xóa |
| Lỗi và độ tin cậy | Thử lại, đối chiếu, xử lý sự cố nhà cung cấp và chi phí chuyển đổi | Dự phòng, ứng phó sự cố, công việc thất bại, phục hồi và công suất không sử dụng | Cả lỗi phụ thuộc và lỗi điều phối nội bộ | Tỷ lệ lỗi, thời gian phục hồi, công việc trùng lặp và tải hỗ trợ |
Khuôn khổ này không công bố điểm chuẩn giá tự lưu trữ và không khẳng định rằng quản lý, tự lưu trữ hoặc kết hợp là rẻ hơn về mặt phổ quát. Quyết định phụ thuộc vào khối lượng công việc và các kiểm soát có thể được chứng minh cho cùng một khoảng thời gian.
Quyết định xây dựng
Chọn quản lý, tự lưu trữ hoặc kết hợp dựa trên các kiểm soát bạn phải sở hữu
| Mô hình | Bạn sở hữu | Phụ thuộc bên ngoài | Phù hợp nhất |
|---|---|---|---|
| API được quản lý | Cổng đồng ý, UX ứng dụng, lưu trữ tác vụ, thăm dò, đánh giá và chính sách kinh doanh | API đã công bố, giới hạn, giá cả và hành vi xử lý | Các nhóm ưu tiên tốc độ tích hợp hơn kiểm soát cơ sở hạ tầng |
| Tự lưu trữ | Mô hình, công suất GPU, hàng đợi, kiểm duyệt, lưu trữ, bảo mật, thanh toán, xóa và ứng phó sự cố | Chuỗi cung ứng mô hình và cơ sở hạ tầng | Các nhóm có yêu cầu kiểm soát hoặc triển khai hợp lý và năng lực vận hành |
| Kết hợp | Chính sách nội bộ, điều phối, bản ghi kiểm toán, đánh giá và trừu tượng hóa nhà cung cấp | Một hoặc nhiều dịch vụ tạo có giới hạn | Các nhóm cần kiểm soát cấp ứng dụng mà không vận hành mọi thành phần mô hình |
Nguồn và phương pháp
Sự kiện sản phẩm hiện tại cộng với các tiêu chuẩn bên ngoài chính
Nhóm sản phẩm DeepSwapAI đã kiểm tra năm tuyến đường công khai, xác thực Bearer, yêu cầu multipart, trạng thái tác vụ, luồng thăm dò, phản hồi lỗi, ranh giới đồng thời, thanh toán tín dụng, quyền sử dụng hình ảnh dùng thử và xóa phương tiện trong 24 giờ vào ngày 22 tháng 7 năm 2026. Các kiểm soát được khuyến nghị được thông báo bởi OpenAPI Thông số kỹ thuật 3.1.2, Hướng dẫn tải lên OWASP, NIST AI RMF 1.0, và W3C Trace Context. Xem phương pháp xác minh tuyên bố để biết cách các tuyên bố sản phẩm hiện tại được tách biệt khỏi hướng dẫn thiết kế chung.
Câu hỏi kiến trúc
Biết hợp đồng công khai thiết lập và không thiết lập những gì
Đây có phải là kiến trúc sản xuất riêng tư của DeepSwapAI không?
Không. Đây là tài liệu tham khảo thiết kế hợp đồng công khai và không tiết lộ cấu trúc liên kết nhà cung cấp, công nghệ hàng đợi, vị trí mô hình, số lượng công nhân, mạng nội bộ hoặc mục tiêu cấp dịch vụ.
Làm thế nào để máy khách biết rằng một tác vụ đã hoàn thành?
Giữ taskId được trả về bởi POST và thăm dò GET trên cùng một tuyến đường quy trình làm việc cho đến khi COMPLETED, FAILED hoặc CANCELLED. Hiện tại không có lệnh gọi lại webhook nào được công bố.
Khóa API có thể được đặt trong mã máy khách không?
Không. Coi nó như một bí mật phía máy chủ và giữ nó ra khỏi các gói trình duyệt, tệp nhị phân di động, kho lưu trữ, phân tích, nhật ký và tin nhắn hỗ trợ.
API có công bố khóa idempotency không?
Không có trường khóa idempotency nào được ghi lại. Ngăn chặn gửi trùng lặp, lưu trữ taskId đầu tiên và đối chiếu các phản hồi không chắc chắn trước khi POST khác.
Thiết kế này có đảm bảo thông lượng hoặc chất lượng không?
Không. Đây không phải là điểm chuẩn, SLA, điểm số chính xác hoặc đảm bảo chất lượng.