Batas bukti
Referensi kontrak publik, bukan diagram infrastruktur pribadi
Gunakan untuk memutuskan di mana kepemilikan, validasi, status tugas, percobaan ulang, penyelesaian, pengiriman, penghapusan, dan bukti harus berada dalam integrasi Anda sendiri. Untuk bidang dan respons multipart yang tepat, gunakan Dokumentasi API dan kontrak OpenAPI 3.1. Untuk konsep riset di dalam lokalisasi wajah, transfer identitas, sintesis, pencampuran, dan konsistensi video, baca cara kerja penukaran wajah AI.
Kontrak publik yang diverifikasi
Lima alur kerja asinkron berbagi satu bentuk kontrol
Setiap alur kerja pembuatan saat ini mengautentikasi dengan kunci API Bearer, menerima media multipart, mengembalikan taskId, dan mengekspos status terbatas pemilik melalui GET pada rute yang sama. Penyelesaian menggunakan polling; panggilan balik webhook dan SDK bahasa resmi saat ini tidak dipublikasikan.
| Alur kerja | POST dan polling GET | Unit biaya | Batas utama |
|---|---|---|---|
| Foto | /api/ai-tasks | 6 kredit per tugas | 30 MB per gambar |
| Foto batch | /api/ai-tasks/batch-face-swap | 6 kredit per keluaran | 20 gambar, 95 MB gabungan |
| Foto grup yang dipetakan | /api/ai-tasks/multi-face-swap | 6 kredit per wajah pengganti | 10 wajah yang dipetakan, 95 MB gabungan |
| Video | /api/ai-tasks/video | Hanya wajah dengan pelestarian latar: 3/dtk, minimal 12 di 1080p | 600 detik, unggahan gabungan 95 MB |
| GIF / klip pendek | /api/ai-tasks/gif | 3 kredit per detik, minimal 12 | 30 detik, target 95 MB |
Ruang kerja langsung dan dokumentasi API tetap menjadi acuan untuk format yang tepat, biaya minimum, dan kolom permintaan. Tugas akun dan API memerlukan email terverifikasi, hanya satu pembuatan yang dapat aktif per akun, dan batas yang habis dapat mengembalikan HTTP 429 dengan informasi coba lagi.
Arsitektur referensi
Berikan setiap keputusan yang tidak dapat diubah satu pemilik
Ingress dan identitas
Akhiri TLS, autentikasi kunci yang dipegang server, tetapkan ID korelasi permintaan, dan ikat setiap tugas ke satu akun.
Kebijakan dan validasi
Periksa status izin, bidang alur kerja, jenis media yang terdeteksi, ukuran byte, jumlah, durasi, pemetaan, kesiapan akun, dan ketersediaan kredit.
Buku besar tugas
Pertahankan taskId, pemilik, alur kerja, biaya yang diharapkan, transisi status, stempel waktu, dan hasil penyelesaian sebelum mengembalikan kendali.
Pemrosesan terbatas
Pisahkan penerimaan permintaan dari pembuatan, batasi pekerjaan aktif, dan bedakan kegagalan transportasi yang dapat dicoba ulang dari masukan yang tidak valid.
Penyelesaian
Gunakan satu otoritas atom untuk keputusan cadangan, penyelesaian, dan pengembalian dana tugas yang gagal sehingga percobaan ulang tidak dapat mengenakan biaya atau mengembalikan dana dua kali.
Pengiriman dan penghapusan
Otorisasi akses hasil oleh pemilik tugas, terapkan hak ekspor gambar, dan hapus media pada jadwal 24 jam yang didokumentasikan.
Urutan permintaan delapan langkah
Hapus dari kontrak permintaan hingga penghapusan yang didukung bukti
- Bekukan kontrak permintaan publik. Pilih alur kerja yang tepat dan catat bidang, batas media, unit biaya, dan status terminal.
- Atur gerbang otorisasi, persetujuan, dan kesiapan akun. Jaga kunci API di sisi server dan minta keputusan izin sebelum menerima media.
- Validasi media dan hitung biaya sebelum mengantrekan. Periksa jenis yang terdeteksi, ukuran, jumlah, durasi, pemetaan, dan kredit yang tersedia sebelum pekerjaan mahal.
- Buat satu catatan tugas yang tahan lama. Pertahankan kepemilikan, alur kerja, biaya yang diharapkan, referensi masukan, status, dan taskId.
- Proses secara asinkron di belakang antrean terbatas. Batasi konkurensi dan klasifikasikan kegagalan sementara versus permanen.
- Selesaikan kredit tepat satu kali. Komit pekerjaan yang selesai dan terapkan jalur pengembalian dana pemrosesan yang gagal yang didokumentasikan tanpa penyelesaian ganda.
- Ekspos status dan akses hasil terbatas pemilik. Polling pada interval yang diukur dan berhenti pada COMPLETED, FAILED, atau CANCELLED.
- Terapkan penghapusan dan pertahankan bukti operasional. Hapus media sesuai jadwal sambil mempertahankan hanya catatan tugas, penagihan, keamanan, dan dukungan minimum yang diizinkan.
Status dan penyelesaian
Jaga status pemrosesan tetap terpisah dari status uang
| Peristiwa | Catatan tugas | Tindakan kredit | Tindakan klien |
|---|---|---|---|
| Permintaan ditolak sebelum pembuatan tugas | Tidak ada tugas yang diterima | Jangan menyimpulkan biaya | Perbaiki permintaan atau status akun |
| Tugas diterima | Pertahankan taskId dan biaya yang diharapkan | Perlakukan penyelesaian sebagai milik server | Mulai polling yang diukur |
| Tugas selesai | Hasil terminal | Pekerjaan yang selesai tetap diselesaikan | Otorisasi pengambilan hasil |
| Pemrosesan gagal | Kegagalan terminal | Kontrak saat ini mengembalikan dana pemrosesan yang gagal secara otomatis | Baca kegagalan sebelum memutuskan untuk mengirim ulang |
| Hasil respons tidak pasti | Rekonsiliasi sebelum POST lain | Jangan pernah menebak dari waktu tunggu | Gunakan taskId yang disimpan atau riwayat akun |
Tidak ada bidang idempotency-key yang didokumentasikan dalam kontrak publik. Layanan pemanggil harus menonaktifkan pengiriman duplikat, pertahankan taskId pertama, dan rekonsiliasi respons jaringan yang tidak pasti sebelum mengeluarkan POST lain.
Kebijakan kegagalan
Coba ulang hanya ketika kelas kegagalan mengizinkannya
| Status | Kelas kegagalan | Respons arsitektur |
|---|---|---|
| 400 | Permintaan atau media tidak valid | Tolak secara permanen hingga kolom atau media berubah. |
| 401 / 403 | Kunci atau kesiapan akun | Putar kunci atau selesaikan verifikasi; jangan melakukan perulangan. |
| 402 | Kredit tidak mencukupi | Tambahkan kredit dan kirimkan tugas baru hanya setelah konfirmasi. |
| 404 | Pemilik, rute, atau taskId salah | Rekonsiliasi identitas dan metadata tugas yang tersimpan. |
| 429 | Batas tarif atau generasi aktif | Hormati Retry-After jika disediakan, tambahkan jitter, dan batasi jumlah percobaan ulang. |
| 500 | Penerimaan sementara atau kegagalan baca | Gunakan exponential backoff terbatas dan rekonsiliasi sebelum pengiriman duplikat. |
Observabilitas dan keamanan
Lacak keputusan kontrol tanpa menyalin media sensitif ke dalam log
Telemetri tugas yang direkomendasikan mencakup ID korelasi, taskId, pengenal akun, alur kerja, fakta media yang telah dibersihkan, jumlah kredit yang diharapkan, transisi status, jumlah percobaan ulang, kelas kesalahan, peristiwa penyelesaian, dan stempel waktu penghapusan. Jangan mencatat kunci API, gambar wajah, nama file unggahan lengkap, URL hasil yang ditandatangani, atau badan multipart. Rekomendasi Konteks Jejak W3C mendefinisikan konteks permintaan yang dapat dioperasikan; ini adalah opsi desain, bukan klaim tentang implementasi pribadi DeepSwapAI.
Untuk pertahanan unggahan, validasi nama file yang didekodekan, konten yang terdeteksi, format yang diizinkan, jumlah, dan ukuran; jangan percaya pada Content-Type yang disediakan browser saja. OWASP File Upload Cheat Sheet adalah referensi keamanan eksternal. Gunakan perencana persetujuan dan pengungkapan untuk gerbang otorisasi manusia dan Pusat Kepercayaan untuk batasan layanan publik saat ini.
Total biaya kepemilikan
Bandingkan yang dikelola, dihosting sendiri, dan hibrida pada beban kerja terukur yang sama
Jangan membandingkan biaya API dengan sewa GPU mentah saja. Tetapkan satu jendela beban kerja terlebih dahulu: campuran alur kerja, durasi dan resolusi media, konkurensi puncak, tingkat percobaan ulang, retensi, volume peninjauan, dan ketersediaan yang diperlukan. Kemudian tetapkan setiap biaya berulang dan terkait kegagalan ke jendela yang sama.
| Dimensi biaya | API yang Dikelola | Dihosting sendiri | Hibrida | Bukti yang harus dikumpulkan |
|---|---|---|---|---|
| Kapasitas pemrosesan | Biaya tugas atau durasi yang dipublikasikan | Sewa atau pembelian GPU, kapasitas menganggur, penskalaan, dan runtime model | Garis dasar internal plus luapan eksternal atau pemrosesan spesialis | Unit selesai, durasi, resolusi, konkurensi, dan pemanfaatan |
| Teknik dan operasi | Integrasi, persistensi tugas, polling, peninjauan, dan penanganan perubahan vendor | Penyajian model, antrian, peningkatan, perencanaan kapasitas, penerapan, dan respons panggilan | Orkestrasi, abstraksi penyedia, dan kepemilikan platform internal | Jam insinyur terukur, irama rilis, dan beban panggilan |
| Keamanan dan tata kelola | Gerbang persetujuan aplikasi, kebijakan akun, peninjauan, dan bukti | Semua moderasi, penyimpanan, penghapusan, kontrol akses, dan kontrol audit | Kontrol bersama dengan pemilik eksplisit untuk setiap keputusan | Menit peninjauan, tingkat eskalasi, ruang lingkup retensi, dan pemilik kontrol |
| Penyimpanan dan pengiriman | Penanganan input, hasil, dan jaringan sisi aplikasi | Input, perantara, hasil, cadangan, egress, dan operasi penghapusan | Catatan internal plus transfer penyedia terbatas | Byte yang disimpan, volume transfer, waktu retensi, dan pekerjaan penghapusan |
| Kegagalan dan keandalan | Percobaan ulang, rekonsiliasi, penanganan pemadaman penyedia, dan biaya peralihan | Redundansi, respons insiden, pekerjaan gagal, pemulihan, dan kapasitas tidak terpakai | Kegagalan ketergantungan dan kegagalan orkestrasi internal | Tingkat kegagalan, waktu pemulihan, pekerjaan duplikat, dan beban dukungan |
Kerangka kerja ini tidak menerbitkan tolok ukur harga yang dihosting sendiri dan tidak mengklaim bahwa yang dikelola, dihosting sendiri, atau hibrida secara universal lebih murah. Keputusan tergantung pada beban kerja dan kontrol yang dapat dibuktikan untuk periode yang sama.
Keputusan pembangunan
Pilih yang dikelola, dihosting sendiri, atau hibrida berdasarkan kontrol yang harus Anda miliki
| Model | Anda memiliki | Ketergantungan eksternal | Paling cocok |
|---|---|---|---|
| API yang Dikelola | Gerbang persetujuan, UX aplikasi, persistensi tugas, polling, peninjauan, dan kebijakan bisnis | API yang dipublikasikan, batasan, harga, dan perilaku pemrosesan | Tim yang memprioritaskan kecepatan integrasi di atas kontrol infrastruktur |
| Dihosting sendiri | Model, kapasitas GPU, antrian, moderasi, penyimpanan, keamanan, penyelesaian, penghapusan, dan respons insiden | Rantai pasokan model dan infrastruktur | Tim dengan persyaratan kontrol atau penerapan yang dibenarkan dan kapasitas operasi |
| Hibrida | Kebijakan internal, orkestrasi, catatan audit, peninjauan, dan abstraksi penyedia | Satu atau lebih layanan generasi terbatas | Tim yang membutuhkan kontrol tingkat aplikasi tanpa mengoperasikan setiap komponen model |
Sumber dan metode
Fakta produk saat ini ditambah standar eksternal utama
Tim Produk DeepSwapAI memeriksa lima rute publik, autentikasi Bearer, permintaan multipart, status tugas, alur polling, respons kesalahan, batas konkurensi, penyelesaian kredit, hak gambar uji coba, dan penghapusan media 24 jam pada 22 Juli 2026. Kontrol yang direkomendasikan didasarkan pada Spesifikasi OpenAPI 3.1.2, panduan unggahan OWASP, NIST AI RMF 1.0, dan Konteks Jejak W3C. Lihat metodologi verifikasi klaim untuk bagaimana pernyataan produk saat ini dipisahkan dari panduan desain umum.
Pertanyaan arsitektur
Ketahui apa yang ditetapkan dan tidak ditetapkan oleh kontrak publik
Apakah ini arsitektur produksi pribadi DeepSwapAI?
Tidak. Ini adalah referensi desain kontrak publik dan tidak mengungkapkan topologi penyedia, teknologi antrian, penempatan model, jumlah pekerja, jaringan internal, atau target tingkat layanan.
Bagaimana klien mengetahui bahwa suatu tugas selesai?
Simpan taskId yang dikembalikan oleh POST dan polling GET pada rute alur kerja yang sama hingga COMPLETED, FAILED, atau CANCELLED. Panggilan balik webhook saat ini tidak dipublikasikan.
Dapatkah kunci API ditempatkan dalam kode klien?
Tidak. Perlakukan sebagai rahasia sisi server dan jangan simpan di bundel browser, biner seluler, repositori, analitik, log, dan pesan dukungan.
Apakah API menerbitkan kunci idempotensi?
Tidak ada bidang kunci idempotensi yang didokumentasikan. Cegah pengiriman duplikat, pertahankan taskId pertama, dan rekonsiliasi respons yang tidak pasti sebelum POST lain.
Apakah desain ini menjamin throughput atau kualitas?
Tidak. Ini bukan tolok ukur, SLA, skor akurasi, atau jaminan kualitas.