Evidence boundary
A public-contract reference, not a private infrastructure diagram
Use it to decide where ownership, validation, task state, retry, settlement, delivery, deletion, and evidence should live in your own integration. For exact multipart fields and responses, use the API documentation and OpenAPI 3.1 contract.
Verified public contract
Five asynchronous workflows share one control shape
Every current generation workflow authenticates with a Bearer API key, accepts multipart media, returns a taskId, and exposes owner-scoped status through GET on the same route. Completion uses polling; webhook callbacks and official language SDKs are not currently published.
| Workflow | POST and polling GET | Cost unit | Primary bound |
|---|---|---|---|
| Photo | /api/ai-tasks | 2 credits per task | 30 MB per image |
| Batch photo | /api/ai-tasks/batch-face-swap | 2 credits per output | 20 images, 200 MB combined |
| Mapped group photo | /api/ai-tasks/multi-face-swap | 2 credits per replacement face | 10 mapped faces, 120 MB combined |
| Video | /api/ai-tasks/video | 2/s at 720p or 5/s at 1080p | 300 seconds, 200 MB target |
| GIF / short clip | /api/ai-tasks/gif | 3 credits per second | 30 seconds, 100 MB target |
The live workspace and API documentation remain authoritative for exact formats, minimum charges, and request fields. A verified account email is required, one generation can be active per account, and exhausted limits can return HTTP 429 with retry information.
Reference architecture
Give each irreversible decision one owner
Ingress and identity
Terminate TLS, authenticate the server-held key, assign a request correlation ID, and bind every task to one account.
Policy and validation
Check permission state, workflow fields, detected media type, byte size, count, duration, mapping, account readiness, and credit availability.
Task ledger
Persist the taskId, owner, workflow, expected charge, state transitions, timestamps, and settlement outcome before returning control.
Bounded processing
Decouple request acceptance from generation, cap active work, and distinguish retryable transport failures from invalid inputs.
Settlement
Use one atomic authority for reserve, completion, and failed-task refund decisions so a retry cannot charge or refund twice.
Delivery and deletion
Authorize result access by task owner, apply the image-export entitlement, and remove media on the documented 24-hour schedule.
Eight-step request sequence
Move from request contract to evidence-backed deletion
- Freeze the public request contract. Choose the exact workflow and record fields, media limits, cost unit, and terminal states.
- Gate authorization, consent, and account readiness. Keep the API key server-side and require a permission decision before accepting media.
- Validate media and calculate cost before enqueueing. Inspect detected type, size, count, duration, mapping, and available credits before expensive work.
- Create one durable task record. Persist ownership, workflow, expected charge, input references, state, and taskId.
- Process asynchronously behind a bounded queue. Limit concurrency and classify transient versus permanent failures.
- Settle credits exactly once. Commit completed work and apply the documented failed-processing refund path without double settlement.
- Expose owner-scoped status and result access. Poll at a measured interval and stop at COMPLETED, FAILED, or CANCELLED.
- Enforce deletion and retain operational evidence. Remove media on schedule while retaining only the minimum allowed task, billing, security, and support record.
State and settlement
Keep processing state separate from money state
| Event | Task record | Credit action | Client action |
|---|---|---|---|
| Request rejected before task creation | No accepted task | Do not infer a charge | Correct the request or account state |
| Task accepted | Persist taskId and expected cost | Treat settlement as server-owned | Begin measured polling |
| Task completed | Terminal result | Completed work remains settled | Authorize result retrieval |
| Processing failed | Terminal failure | Current contract refunds failed processing automatically | Read the failure before deciding to resubmit |
| Response outcome uncertain | Reconcile before another POST | Never guess from a timeout | Use the stored taskId or account history |
No idempotency-key field is documented in the public contract. The calling service should disable duplicate submission, persist the first taskId, and reconcile an uncertain network response before issuing another POST.
Failure policy
Retry only when the failure class permits it
| Status | Failure class | Architecture response |
|---|---|---|
| 400 | Invalid request or media | Reject permanently until fields or media change. |
| 401 / 403 | Key or account readiness | Rotate the key or complete verification; do not loop. |
| 402 | Insufficient credits | Add credits and submit a new task only after confirmation. |
| 404 | Wrong owner, route, or taskId | Reconcile identity and stored task metadata. |
| 429 | Rate or active-generation limit | Honor Retry-After when supplied, add jitter, and cap retries. |
| 500 | Temporary acceptance or read failure | Use bounded exponential backoff and reconcile before duplicate submission. |
Observability and security
Trace control decisions without copying sensitive media into logs
Recommended task telemetry includes a correlation ID, taskId, account identifier, workflow, sanitized media facts, expected credit amount, state transitions, retry count, error class, settlement event, and deletion timestamp. Do not log API keys, face images, complete uploaded filenames, signed result URLs, or multipart bodies. The W3C Trace Context recommendation defines interoperable request context; it is a design option, not a claim about DeepSwapAI's private implementation.
For upload defenses, validate decoded filenames, detected content, allowed formats, counts, and sizes; do not trust the browser-supplied Content-Type alone. The OWASP File Upload Cheat Sheet is the external security reference. Use the consent and disclosure planner for the human authorization gate and the Trust Center for current public service boundaries.
Build decision
Choose managed, self-hosted, or hybrid by the controls you must own
| Model | You own | External dependency | Best fit |
|---|---|---|---|
| Managed API | Consent gate, application UX, task persistence, polling, review, and business policy | Published API, limits, pricing, and processing behavior | Teams prioritizing integration speed over infrastructure control |
| Self-hosted | Model, GPU capacity, queue, moderation, storage, security, settlement, deletion, and incident response | Model and infrastructure supply chain | Teams with a justified control or deployment requirement and operations capacity |
| Hybrid | Internal policy, orchestration, audit record, review, and provider abstraction | One or more bounded generation services | Teams that need application-level control without operating every model component |
Sources and method
Current product facts plus primary external standards
The DeepSwapAI Product Team checked the five public routes, Bearer authentication, multipart requests, task states, polling flow, error responses, concurrency boundary, credit settlement, trial image entitlement, and 24-hour media deletion on July 22, 2026. The recommended controls are informed by the OpenAPI Specification 3.1.2, OWASP upload guidance, NIST AI RMF 1.0, and W3C Trace Context. See the claim verification methodology for how current product statements are separated from general design guidance.
Architecture questions
Know what the public contract does and does not establish
Is this DeepSwapAI's private production architecture?
No. It is a public-contract design reference and does not disclose provider topology, queue technology, model placement, worker count, internal network, or service-level targets.
How does a client learn that a task finished?
Keep the taskId returned by POST and poll GET on the same workflow route until COMPLETED, FAILED, or CANCELLED. Webhook callbacks are not currently published.
Can the API key be placed in client code?
No. Treat it as a server-side secret and keep it out of browser bundles, mobile binaries, repositories, analytics, logs, and support messages.
Does the API publish an idempotency key?
No idempotency-key field is documented. Prevent duplicate submission, persist the first taskId, and reconcile uncertain responses before another POST.
Does this design guarantee throughput or quality?
No. It is not a benchmark, SLA, accuracy score, or quality guarantee.