Hangganan ng ebidensya
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.
Na-verify na pampublikong kontrata
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 | Yunit ng gastos | Pangunahing limitasyon |
|---|---|---|---|
| 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 larawan, 95 MB sa kabuuan |
| Naka-map na larawan ng grupo | /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 (ang 95 MB ay mga 1–1.5 min ng karaniwang 1080p na video mula sa phone) |
| GIF / maikling 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 na arkitektura
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.
Limitadong pagproseso
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 | Aksyon sa credits | Aksyon ng kliyente |
|---|---|---|---|
| Request rejected bago ang task creation | Walang tinanggap na task | Huwag magpahiwatig ng charge | Itama ang request o account state |
| Tinanggap ang task | I-persist ang taskId at expected cost | Ituring ang settlement bilang server-owned | Simulan ang sinusukat na polling |
| Natapos ang task | Panghuling resulta | Ang natapos na trabaho ay nananatiling naayos | Pahintulutan ang pagkuha ng resulta |
| Nabigo ang pagproseso | Panghuling pagkabigo | Ang kasalukuyang refund ng kontrata ay awtomatikong nabigo sa pagproseso | Basahin ang pagkabigo bago magpasyang muling isumite |
| Hindi tiyak ang resulta ng response | 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.
Patakaran sa pagkabigo
Ulitin lamang kapag pinapayagan ng klase ng pagkabigo
| Status | Uri ng pagkabigo | Tugon ng arkitektura |
|---|---|---|
| 400 | Hindi wastong request o media | Tanggihan nang permanente hanggang sa magbago ang mga field o media. |
| 401 / 403 | Kahandaan ng key o account | Paikutin ang key o kumpletuhin ang verification; huwag umulit. |
| 402 | Kulang ang 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 at seguridad
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 Sentro ng Tiwala para sa kasalukuyang mga hangganan ng pampublikong serbisyo.
Kabuuang gastos ng pagmamay-ari
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.
| Dimensyon ng gastos | Managed API | Self-hosted | Hybrid | Ebidensyang dapat kolektahin |
|---|---|---|---|---|
| Kapasidad ng pagproseso | 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 at operasyon | 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 |
| Kaligtasan at pamamahala | 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 |
| Imbakan at paghahatid | 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 |
| Pagkabigo at pagiging maaasahan | 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.
Desisyon sa pagbuo
Pumili ng pinamamahalaan, sariling-host, o hybrid batay sa mga kontrol na dapat mong pagmamay-ari
| Model | Ikaw ang may hawak | Panlabas na dependency | Pinakaangkop |
|---|---|---|---|
| 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 |
Mga source at paraan
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 metodolohiya ng pagpapatunay ng mga pahayag kung paano pinaghihiwalay ang kasalukuyang mga pahayag ng produkto mula sa pangkalahatang gabay sa disenyo.
Mga tanong sa arkitektura
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.