Evidence boundary
Isang public-contract reference, hindi isang private infrastructure diagram
Gamitin ito upang magpasya kung saan dapat manirahan ang ownership, validation, task state, retry, settlement, delivery, deletion, at evidence sa iyong sariling integration. Para sa eksaktong multipart fields at responses, gamitin ang API documentation at OpenAPI 3.1 contract. Para sa research concepts sa loob ng face localization, identity transfer, synthesis, blending, at video consistency, basahin ang paano gumagana ang AI face swap.
Verified public contract
Limang asynchronous workflows ang nagbabahagi ng isang control shape
Ang bawat kasalukuyang generation workflow ay nag-authenticate gamit ang isang Bearer API key, tumatanggap ng multipart media, nagbabalik ng taskId, at nag-e-expose ng owner-scoped status sa pamamagitan ng GET sa parehong route. Ang completion ay gumagamit ng polling; webhook callbacks at official language SDKs ay hindi kasalukuyang nai-publish.
| Workflow | POST at polling GET | Cost unit | Primary bound |
|---|---|---|---|
| Larawan | /api/ai-tasks | 6 credits bawat gawain | 30 MB bawat imahe |
| Batch na larawan | /api/ai-tasks/batch-face-swap | 6 credits bawat output | 20 images, 95 MB combined |
| Mapped group photo | /api/ai-tasks/multi-face-swap | 6 credits bawat kapalit na mukha | 10 naka-map na mukha, pinagsamang 95 MB |
| Video | /api/ai-tasks/video | Face-only na may scene preservation: 3/s, min 12 sa 1080p | 600 segundo, 95 MB pinagsamang upload |
| GIF / short clip | /api/ai-tasks/gif | 3 credit per second, min 12 | 30 segundo, 95 MB target |
Ang live workspace at ang API documentation pa rin ang batayan para sa eksaktong format, minimum na singil, at mga field ng request. Ang mga account at API task ay nangangailangan ng na-verify na email, isang generation lang ang puwedeng aktibo bawat account, at ang naubos na limit ay maaaring magbalik ng HTTP 429 na may impormasyon sa muling pagsubok.
Reference architecture
Bigyan ang bawat irreversible decision ng isang owner
Ingress at identity
I-terminate ang TLS, i-authenticate ang server-held key, magtalaga ng request correlation ID, at i-bind ang bawat task sa isang account.
Policy at validation
Suriin ang permission state, workflow fields, detected media type, byte size, count, duration, mapping, account readiness, at credit availability.
Talaan ng gawain
I-persist ang taskId, owner, workflow, expected charge, state transitions, timestamps, at settlement outcome bago ibalik ang control.
Bounded processing
I-decouple ang request acceptance mula sa generation, i-cap ang active work, at i-distinguish ang retryable transport failures mula sa invalid inputs.
Settlement
Gumamit ng isang atomic authority para sa reserve, completion, at failed-task refund decisions upang ang isang retry ay hindi makapag-charge o makapag-refund nang dalawang beses.
Delivery at deletion
I-authorize ang result access ayon sa task owner, ilapat ang image-export entitlement, at i-remove ang media sa dokumentadong 24-hour schedule.
Walong-hakbang na request sequence
I-reMove mula sa request contract hanggang sa evidence-backed deletion
- I-freeze ang public request contract. Piliin ang eksaktong workflow at itala ang fields, media limits, cost unit, at terminal states.
- I-gate ang authorization, consent, at account readiness. Panatilihing server-side ang API key at mangailangan ng permission decision bago tumanggap ng media.
- I-validate ang media at kalkulahin ang cost bago mag-enqueue. Suriin ang detected type, size, count, duration, mapping, at available credits bago ang mamahaling trabaho.
- Lumikha ng isang durable task record. I-persist ang ownership, workflow, expected charge, input references, state, at taskId.
- I-process nang asynchronously sa likod ng isang bounded queue. Limitahan ang concurrency at i-classify ang transient versus permanent failures.
- I-settle ang credits nang eksaktong isang beses. I-commit ang natapos na trabaho at ilapat ang dokumentadong failed-processing refund path nang walang double settlement.
- I-expose ang owner-scoped status at result access. Mag-poll sa isang measured interval at huminto sa COMPLETED, FAILED, o CANCELLED.
- Ipatupad ang deletion at panatilihin ang operational evidence. I-remove ang media sa schedule habang pinapanatili lamang ang minimum na pinapayagang task, billing, security, at support record.
State at settlement
Panatilihing hiwalay ang processing state mula sa money state
| Event | Tala ng gawain | Credit action | Aksyon ng kliyente |
|---|---|---|---|
| Request rejected bago ang task creation | Walang tinanggap na task | Huwag magpahiwatig ng charge | Itama ang request o account state |
| Task accepted | I-persist ang taskId at expected cost | Ituring ang settlement bilang server-owned | Begin measured polling |
| Task completed | Terminal result | Ang natapos na trabaho ay nananatiling naayos | Authorize result retrieval |
| Nabigo ang pagproseso | Terminal failure | Ang kasalukuyang refund ng kontrata ay awtomatikong nabigo sa pagproseso | Basahin ang pagkabigo bago magpasyang muling isumite |
| Response outcome uncertain | Magkasundo bago ang isa pang POST | Huwag manghula batay sa timeout | Gamitin ang naka-imbak na taskId o kasaysayan ng account |
Walang idempotency-key field na naidokumento sa pampublikong kontrata. Dapat i-disable ng tumatawag na serbisyo ang duplicate submission, panatilihin ang unang taskId, at magkasundo sa hindi tiyak na network response bago mag-isyu ng isa pang POST.
Failure policy
Ulitin lamang kapag pinapayagan ng klase ng pagkabigo
| Status | Failure class | Architecture response |
|---|---|---|
| 400 | Invalid request or media | Tanggihan nang permanente hanggang sa magbago ang mga field o media. |
| 401 / 403 | Key or account readiness | Paikutin ang key o kumpletuhin ang verification; huwag umulit. |
| 402 | Insufficient credits | Magdagdag ng credits at magsumite ng bagong task pagkatapos lamang ng kumpirmasyon. |
| 404 | Maling may-ari, ruta, o taskId | Magkasundo sa pagkakakilanlan at naka-imbak na metadata ng task. |
| 429 | Limitasyon sa rate o aktibong pagbuo | Gamitin ang Honor Retry-After kapag ibinigay, magdagdag ng jitter, at limitahan ang mga retry. |
| 500 | Pansamantalang pagtanggap o pagkabigo sa pagbasa | Gumamit ng bounded exponential backoff at ayusin bago ang duplicate na pagsusumite. |
Observability and security
Subaybayan ang mga desisyon ng kontrol nang hindi kinokopya ang sensitibong media sa mga log
Ang inirerekomendang task telemetry ay may kasamang correlation ID, taskId, account identifier, workflow, sanitized media facts, inaasahang halaga ng kredito, state transitions, retry count, error class, settlement event, at deletion timestamp. Huwag i-log ang API keys, face images, complete uploaded filenames, signed result URLs, o multipart bodies. Ang Rekomendasyon ng W3C Trace Context tumutukoy sa interoperable na konteksto ng kahilingan; ito ay isang opsyon sa disenyo, hindi isang pahayag tungkol sa pribadong implementasyon ng DeepSwapAI.
Para sa mga depensa sa pag-upload, i-validate ang mga decoded na filename, natukoy na nilalaman, pinapayagang format, bilang, at laki; huwag magtiwala lamang sa Content-Type na ibinigay ng browser. Ang OWASP File Upload Cheat Sheet ay ang panlabas na sanggunian sa seguridad. Gamitin ang tagaplano ng pahintulot at pagsisiwalat para sa gate ng awtorisasyon ng tao at ang Trust Center para sa kasalukuyang mga hangganan ng pampublikong serbisyo.
Total cost of ownership
Ihambing ang managed, self-hosted, at hybrid sa parehong sinusukat na workload
Huwag ikumpara ang isang API na singil sa raw GPU rental lamang. Ayusin muna ang isang window ng workload: workflow mix, tagal at resolusyon ng media, peak concurrency, retry rate, retention, review volume, at kinakailangang availability. Pagkatapos ay italaga ang bawat paulit-ulit at failure-related na gastos sa parehong window.
| Cost dimension | Managed API | Self-hosted | Hybrid | Evidence to collect |
|---|---|---|---|---|
| Processing capacity | Nai-publish na gawain o tagal na singil | GPU lease o pagbili, idle headroom, scaling, at model runtime | Internal baseline kasama ang external overflow o specialist processing | Nakumpletong units, tagal, resolusyon, concurrency, at utilization |
| Engineering and operations | Integration, task persistence, polling, review, at vendor-change handling | Model serving, queue, upgrades, capacity planning, deployment, at on-call response | Orkestrasyon, provider abstraction, at pagmamay-ari ng internal platform | Nasusukat na oras ng engineer, dalas ng release, at on-call load |
| Safety and governance | Application consent gate, patakaran sa account, pagsusuri, at ebidensya | Lahat ng moderation, storage, deletion, access control, at audit controls | Pinagsamang kontrol na may malinaw na may-ari para sa bawat desisyon | Minuto ng pagsusuri, rate ng escalation, saklaw ng retention, at may-ari ng kontrol |
| Storage and delivery | Pangasiwaan ng input, resulta, at network sa panig ng application | Mga operasyon ng input, intermediate, resulta, backup, egress, at deletion | Panloob na talaan at may hangganang provider transfers | Bytes na napanatili, dami ng transfer, oras ng retention, at gawain ng deletion |
| Failure and reliability | Pagsubok muli, pagkakasundo, paghawak ng pagkawala ng provider, at gastos sa paglipat | Redundancy, pagtugon sa insidente, mga nabigong trabaho, pagbawi, at hindi nagamit na kapasidad | Parehong pagkabigo ng dependency at panloob na pagkabigo ng orkestrasyon | Rate ng pagkabigo, oras ng pagbawi, dobleng trabaho, at suportang karga |
Ang balangkas na ito ay hindi naglalathala ng anumang sariling-host na benchmark ng presyo at hindi nagsasabing ang pinamamahalaan, sariling-host, o hybrid ay pangkalahatang mas mura. Ang desisyon ay nakasalalay sa trabaho at mga kontrol na maaaring mapatunayan para sa parehong panahon.
Build decision
Pumili ng pinamamahalaan, sariling-host, o hybrid batay sa mga kontrol na dapat mong pagmamay-ari
| Model | You own | External dependency | Best fit |
|---|---|---|---|
| Managed API | Gate ng pahintulot, UX ng aplikasyon, pagpapanatili ng gawain, pagboto, pagsusuri, at patakaran ng negosyo | Inilathala ang API, mga limitasyon, pagpepresyo, at pag-uugali sa pagproseso | Mga pangkat na inuuna ang bilis ng pagsasama kaysa sa kontrol ng imprastraktura |
| Self-hosted | Modelo, kapasidad ng GPU, pila, moderasyon, imbakan, seguridad, pag-aayos, pagbura, at pagtugon sa insidente | Modelo at supply chain ng imprastraktura | Mga pangkat na may makatwirang pangangailangan sa kontrol o pag-deploy at kapasidad sa operasyon |
| Hybrid | Panloob na patakaran, orkestrasyon, talaan ng pag-audit, pagsusuri, at abstraksyon ng provider | Isa o higit pang nakatali na serbisyo ng pagbuo | Mga pangkat na nangangailangan ng kontrol sa antas ng aplikasyon nang hindi pinapatakbo ang bawat bahagi ng modelo |
Sources and method
Kasalukuyang mga katotohanan ng produkto kasama ang pangunahing panlabas na pamantayan
Sinuri ng DeepSwapAI Product Team ang limang pampublikong ruta, Bearer authentication, multipart requests, task states, polling flow, error responses, concurrency boundary, credit settlement, trial image entitlement, at 24-hour media deletion noong Hulyo 22, 2026. Ang mga inirerekomendang kontrol ay batay sa OpenAPI Specification 3.1.2, Gabay sa pag-upload ng OWASP, NIST AI RMF 1.0, at W3C Trace Context. Tingnan ang claim verification methodology kung paano pinaghihiwalay ang kasalukuyang mga pahayag ng produkto mula sa pangkalahatang gabay sa disenyo.
Architecture questions
Alamin kung ano ang itinatag at hindi itinatag ng pampublikong kontrata
Ito ba ang pribadong production architecture ng DeepSwapAI?
Hindi. Ito ay isang pampublikong-kontrata na disenyong sanggunian at hindi nito isinasapubliko ang topology ng provider, teknolohiya ng queue, paglalagay ng modelo, bilang ng manggagawa, panloob na network, o mga target sa antas ng serbisyo.
Paano malalaman ng isang kliyente na natapos na ang isang gawain?
Panatilihin ang taskId na ibinalik ng POST at i-poll ang GET sa parehong workflow route hanggang sa COMPLETED, FAILED, o CANCELLED. Ang mga webhook callback ay hindi kasalukuyang nai-publish.
Maaari bang ilagay ang API key sa code ng kliyente?
Hindi. Tratuhin ito bilang isang lihim sa panig ng server at ilayo ito sa mga browser bundle, mobile binaries, repositories, analytics, logs, at support messages.
Nag-publish ba ang API ng isang idempotency key?
Walang dokumentadong idempotency-key field. Pigilan ang duplicate submission, panatilihin ang unang taskId, at i-reconcile ang mga hindi tiyak na tugon bago ang isa pang POST.
Ginagarantiya ba ng disenyong ito ang throughput o kalidad?
Hindi. Ito ay hindi isang benchmark, SLA, accuracy score, o garantiya ng kalidad.