Ketika MFA diaktifkan untuk seorang pengguna, `POST /api/auth/login` mengembalikan `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` alih-alih token sesi. Kirim `mfaToken` tersebut ditambah kode TOTP atau kode pemulihan ke `/api/auth/mfa/complete`.
### Izin {#permissions}
| Izin | Admin | Pengguna |
|-----------|:-----:|:----:|
| Gunakan tool | ✓ | ✓ |
| File/pipeline/kunci API milik sendiri | ✓ | ✓ |
| Lihat file/pipeline/kunci semua pengguna | ✓ | - |
| Tulis pengaturan | ✓ | - |
| Kelola pengguna & tim | ✓ | - |
| Kelola branding | ✓ | - |
## Pemeriksaan Kesehatan {#health-check}
| Method | Path | Akses | Deskripsi |
|--------|------|--------|-------------|
| `GET` | `/api/v1/health` | Publik | Pemeriksaan kesehatan dasar. Mengembalikan `{"status":"healthy","version":"..."}` dengan 200, atau `{"status":"unhealthy"}` dengan 503 jika basis data tidak dapat dijangkau. |
| `GET` | `/api/v1/readyz` | Publik | Probe kesiapan. Memeriksa PostgreSQL, Redis, ruang disk, dan S3 ketika dikonfigurasi. Mengembalikan 503 ketika instans tidak seharusnya menerima lalu lintas. |
| `GET` | `/api/v1/admin/health` | Admin (`system:health`) | Diagnostik terperinci termasuk waktu aktif, mode penyimpanan, status basis data, keadaan antrean, dan ketersediaan GPU. |
## Menggunakan Tool {#using-tools}
Setiap tool mengikuti pola yang sama:
```bash
# Single file
curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId> \
-H "Authorization: Bearer <token>"\
-F "file=@input.jpg"\
-F 'settings={"width":800,"height":600}'
# Batch (returns ZIP)
curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId>/batch \
-H "Authorization: Bearer <token>"\
-F "files=@a.jpg"\
-F "files=@b.jpg"\
-F 'settings={...}'
```
`<section>` adalah salah satu dari `image`, `video`, `audio`, `pdf`, atau `files`.
- Unggahan bersifat `multipart/form-data`.
-`settings` adalah string JSON dengan opsi spesifik tool.
-`clientJobId` adalah field formulir opsional untuk korelasi progres yang disediakan pemanggil.
-`fileId` adalah field formulir opsional yang mereferensikan item pustaka file yang sudah ada. Ketika hadir, keluaran yang diproses disimpan sebagai versi baru dan response menyertakan `savedFileId`.
- **Tool cepat** biasanya mengembalikan JSON 200: `{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}`. Ambil file yang diproses dari `downloadUrl`.
- **Setiap tool yang diantrekan** dapat mengembalikan JSON 202 jika berjalan lama atau melampaui jendela tunggu sinkron: `{"jobId":"...","async":true}`. Sambungkan ke SSE untuk progres, lalu unduh setelah selesai (lihat [Pelacakan Progres](#progress-tracking)).
- **Batch** mengembalikan arsip ZIP yang dialirkan secara langsung (dengan header `X-Job-Id`) untuk tool yang terdaftar di registri batch generik.
## Referensi Tool {#tools-reference}
### Preset Konversi {#conversion-presets}
Katalog bersama menyertakan 83 endpoint preset konversi khusus seperti `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg`, dan `excel-to-csv`. Preset adalah rute tool kelas satu:
`POST /api/v1/tools/<section>/<presetId>`
Setiap preset mengunci format keluaran dan mendelegasikan ke tool dasar seperti `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster`, atau `convert-spreadsheet`. Lihat [Preset Konversi](/id/tools/conversion-presets) untuk tabel rute lengkap dan pengaturan opsional.
### Esensial {#essentials}
| ID Tool | Nama | Pengaturan utama |
|---------|------|-------------|
| `resize` | Resize | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement`, plus 23 preset media sosial |
Semua tool AI berjalan di perangkat keras Anda: CPU secara default, atau NVIDIA CUDA ketika GPU NVIDIA yang didukung tersedia. Akselerasi iGPU Intel/AMD melalui VA-API, Quick Sync, atau OpenCL saat ini tidak didukung untuk inferensi AI. Tidak memerlukan internet.
| `extract-zip` | Extract ZIP | - (terlindungi dari bomb) |
### HTML to Image {#html-to-image}
Tangkap halaman web sebagai gambar. Tidak seperti tool lain, endpoint ini menerima `application/json` alih-alih data formulir multipart (tidak perlu unggah file).
Beberapa tool mengekspos endpoint tambahan di luar `POST /api/v1/tools/<section>/<toolId>` standar:
| Method | Path | Deskripsi |
|--------|------|-------------|
| `GET` | `/api/v1/tools/popular` | Mengembalikan ID tool populer, kembali ke daftar default terkurasi ketika data penggunaan minim |
| `POST` | `/api/v1/tools/image/remove-background/effects` | Terapkan efek latar belakang (color/gradient/blur/shadow) tanpa menjalankan ulang AI. Menggunakan mask yang di-cache dari penghapusan awal. |
| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | Baca metadata EXIF/IPTC/XMP yang ada dari sebuah gambar |
| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | Periksa field metadata sebelum penghapusan |
| `POST` | `/api/v1/tools/image/passport-photo/analyze` | Fase 1: Deteksi wajah AI + penghapusan latar belakang. Mengembalikan landmark wajah dan data yang di-cache. |
| `POST` | `/api/v1/tools/image/passport-photo/generate` | Fase 2: Crop, resize, dan tile menggunakan analisis yang di-cache. Tanpa menjalankan ulang AI. |
| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | Konversi batch beberapa SVG ke raster |
| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | Analisis kualitas gambar dan kembalikan rekomendasi peningkatan |
| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | Pratinjau ringan untuk penyetelan parameter secara langsung. Mengembalikan gambar yang dioptimalkan dengan header ukuran. |
Terapkan tool generik yang mendukung batch ke beberapa file sekaligus. Mengembalikan arsip ZIP. Rute multi-file atau multi-langkah kustom, seperti penandatanganan PDF dan rute preset PDF-ke-gambar, menggunakan kontrak endpoint sendiri alih-alih rute `/batch` generik.
Tool `ocr-pdf` mendukung rute `/batch` generik ini.
curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
-H "Authorization: Bearer <token>"\
-F "files=@a.jpg"\
-F "files=@b.jpg"\
-F "files=@c.jpg"\
-F 'settings={"quality":80}'
```
Konkurensi dikendalikan oleh `CONCURRENT_JOBS` (default: dideteksi otomatis dari inti CPU). `MAX_BATCH_SIZE` membatasi jumlah file per batch (default: 100; setel 0 untuk tanpa batas).
## Pipeline {#pipelines}
### Menjalankan pipeline {#execute-a-pipeline}
```bash
# Single file
curl -X POST http://localhost:1349/api/v1/pipeline/execute \
Keluaran setiap langkah adalah masukan langkah berikutnya. Pipeline mengizinkan 20 langkah secara default, dapat dikonfigurasi melalui `MAX_PIPELINE_STEPS`. Setel `MAX_PIPELINE_STEPS=0` untuk menghapus batas.
### Menyimpan dan mengelola pipeline {#save-and-manage-pipelines}
| `GET` | `/api/v1/pipeline/list` | Daftar pipeline tersimpan (admin melihat semua; pengguna melihat milik sendiri) |
| `DELETE` | `/api/v1/pipeline/:id` | Hapus (pemilik atau admin) |
| `GET` | `/api/v1/pipeline/tools` | Daftar ID tool yang valid untuk langkah pipeline |
## Pelacakan Progres {#progress-tracking}
Job yang berjalan lama, tool yang diantrekan, job batch, dan pipeline memancarkan progres real-time melalui Server-Sent Events. Aliran progres bersifat publik dan dikunci berdasarkan ID job, jadi klien tidak perlu mengirim header Authorization untuk membacanya.
```bash
# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
Anda dapat meminta pembatalan untuk job yang diantrekan atau sedang berjalan dengan `POST /api/v1/jobs/:jobId/cancel`. Response-nya adalah `{"canceled":true|false}`.
## Pustaka File {#file-library}
Penyimpanan file persisten dengan riwayat versi.
| Method | Path | Deskripsi |
|--------|------|-------------|
| `POST` | `/api/v1/upload` | Unggah file ke ruang kerja (pemrosesan sementara) |
| `POST` | `/api/v1/fetch-urls` | Ambil URL jarak jauh ke dalam ruang kerja untuk impor berbasis URL |
| `POST` | `/api/v1/preview` | Hasilkan pratinjau WebP yang kompatibel dengan peramban (untuk format HEIC/HEIF/RAW) |
| `GET` | `/api/v1/files/:id/preview` | Alirkan pratinjau yang di-cache atau dihasilkan yang kompatibel dengan peramban untuk file PDF, dokumen office, video, atau audio tersimpan |
| `POST` | `/api/v1/preview/generate` | Hasilkan pratinjau MP4 atau MP3 sesuai permintaan untuk file media yang diunggah tanpa menyimpannya terlebih dahulu |
| `GET` | `/api/v1/download/:jobId/:filename` | Unduh file yang diproses dari ruang kerja |
Untuk menyimpan otomatis hasil tool ke pustaka, sertakan `fileId` sebagai field formulir multipart yang mereferensikan file pustaka yang sudah ada. Hasil yang diproses akan disimpan sebagai versi baru.
## Manajemen Kunci API {#api-key-management}
| Method | Path | Akses | Deskripsi |
|--------|------|--------|-------------|
| `POST` | `/api/v1/api-keys` | Auth | Hasilkan kunci baru - ditampilkan sekali |
| `GET` | `/api/v1/api-keys` | Auth | Daftar kunci (name, id, lastUsedAt - bukan kunci mentah) |
| `GET` | `/api/v1/teams` | Admin (`teams:manage`) | Daftar tim |
| `POST` | `/api/v1/teams` | Admin (`teams:manage`) | Buat tim |
| `PUT` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Ganti nama tim |
| `DELETE` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Hapus tim (tidak dapat menghapus tim default atau tim dengan anggota) |
## Pengaturan {#settings}
Konfigurasi kunci-nilai runtime (dibaca oleh pengguna terautentikasi mana pun, ditulis hanya oleh admin).
| Method | Path | Deskripsi |
|--------|------|-------------|
| `GET` | `/api/v1/settings` | Dapatkan semua pengaturan |
| `PUT` | `/api/v1/settings` | Perbarui pengaturan secara massal (body JSON dengan pasangan kunci-nilai) |
| `GET` | `/api/v1/settings/:key` | Dapatkan pengaturan tertentu berdasarkan kunci |
Kunci yang diketahui: `disabledTools` (array JSON dari ID tool), `enableExperimentalTools` (string bool), `loginAttemptLimit` (number).
## Preferensi {#preferences}
Preferensi per pengguna terpisah dari pengaturan instans. Setiap pengguna terautentikasi dapat membaca dan memperbarui peta preferensi mereka sendiri.
| Method | Path | Deskripsi |
|--------|------|-------------|
| `GET` | `/api/v1/preferences` | Dapatkan preferensi pengguna saat ini sebagai `{ "preferences": { ... } }` |
| `PUT` | `/api/v1/preferences` | Upsert satu atau lebih kunci preferensi untuk pengguna saat ini |
## Peran {#roles}
Manajemen peran kustom dengan izin terperinci.
| Method | Path | Akses | Deskripsi |
|--------|------|--------|-------------|
| `GET` | `/api/v1/roles` | Admin (`audit:read`) | Daftar semua peran dengan jumlah pengguna |
| `POST` | `/api/v1/roles` | Admin (`security:manage`) | Buat peran kustom (`name`, `description`, `permissions`) |
| `PUT` | `/api/v1/roles/:id` | Admin (`security:manage`) | Perbarui peran kustom (tidak dapat mengubah peran bawaan) |
| `DELETE` | `/api/v1/roles/:id` | Admin (`security:manage`) | Hapus peran kustom (tidak dapat menghapus peran bawaan; pengguna terdampak kembali ke peran `user`) |
| `action` | Filter berdasarkan tipe tindakan (mis. `ROLE_CREATED`, `ROLE_DELETED`) |
| `ip` | Filter berdasarkan alamat IP sumber |
| `from` | Filter entri setelah tanggal ISO 8601 ini |
| `to` | Filter entri sebelum tanggal ISO 8601 ini |
## Analitik {#analytics}
| Method | Path | Akses | Deskripsi |
|--------|------|--------|-------------|
| `GET` | `/api/v1/config/analytics` | Publik | Dapatkan konfigurasi analitik efektif (kunci PostHog, DSN Sentry, sample rate). Kunci, DSN, dan ID instans kosong ketika analitik nonaktif, baik dari bake waktu kompilasi maupun pengaturan instans `analyticsEnabled`. |
| `POST` | `/api/v1/feedback` | Auth | Kirim umpan balik pengguna eksplisit ke proyek PostHog yang dikonfigurasi sebagai `feedback_submitted`. Rute ini menghormati gerbang analitik, membatasi laju pengiriman, menghapus field kontak kecuali `contactOk` bernilai true, dan tidak pernah menerima konten file, nama file, jalur unggahan, atau teks kesalahan pribadi mentah. Ketika analitik dinonaktifkan, rute mengembalikan `{ "ok": true, "accepted": false }`. |
| `PUT` | `/api/v1/settings` | Admin (`settings:write`) | Setel opt-out untuk seluruh instans. Kirim body JSON `{ "analyticsEnabled": "false" }` untuk menonaktifkan analitik bagi semua orang, atau `"true"` untuk mengaktifkannya kembali. |
## Fitur / AI Bundle {#features-ai-bundles}
Kelola bundle fitur AI (pasang/hapus paket model AI di lingkungan Docker). Utamakan endpoint pemasangan tingkat tool ketika mengaktifkan sebuah tool dari otomasi kustom: beberapa tool AI memerlukan lebih dari satu bundle bersama, dan endpoint ini melewati bundle yang sudah terpasang sambil hanya mengantrekan yang belum ada.
OCR adalah peningkatan opsional dan bukan ketergantungan yang sulit. Tingkat `fast` Tesseract berfungsi tanpa paket; `POST /api/v1/admin/features/ocr/install` menginstal paket RapidOCR yang ditandatangani untuk `balanced` dan `best` di Linux amd64 atau arm64. Waktu proses OCR yang akurat menggunakan CPU hanya pada CPU dan host NVIDIA serta memerlukan setidaknya 4 GiB memori efektif (batas kontainer yang dikonfigurasi cgroup, jika tidak, memori host). SnapOtter melaporkan `requiredMemoryBytes`, `effectiveMemoryBytes`, dan alasan kompatibilitas `insufficient-memory`, dan menolak pemasangan yang tidak kompatibel sebelum mengunduh. Persyaratan memori ini tidak berlaku untuk `fast`. Paketnya sekitar 208-234 MiB untuk diunduh dan 409-488 MiB diinstal, tergantung pada targetnya; indeks yang ditandatangani mengikat ukuran persis yang diterapkan selama instalasi.
| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin (`features:manage`) | Pasang setiap bundle yang dibutuhkan sebuah tool; mengembalikan status queued/skipped per bundle |
| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin (`features:manage`) | Hapus bundle fitur dan bersihkan file model |
| `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Dapatkan total penggunaan disk oleh model AI |
| `POST` | `/api/v1/admin/features/import` | Admin (`features:manage`) | Impor paket AI lama (`file`) atau rilis offline OCR (`index` plus `archive`) |
Impor OCR dengan celah udara harus menyertakan `ocr-runtime-index.json` rilis yang ditandatangani dan arsip platform yang cocok. SnapOtter menerapkan tanda tangan Ed25519, hash artefak, kompatibilitas, ekstraksi, dan pemeriksaan uji asap yang sama dengan yang digunakan oleh instalasi online:
```bash
curl -X POST http://localhost:1349/api/v1/admin/features/import \
-H "Authorization: Bearer <admin-token>"\
-F "index=@ocr-runtime-index.json"\
-F "archive=@ocr-linux-amd64-cpu-py312.tar.gz"
```
Gunakan arsip `linux-arm64-cpu-py311` di arm64. Artefak yang ditandatangani untuk target lain ditolak, bukan dipasang.
