description:"Eksiksiz REST API başvurusu. Araç uç noktaları, toplu işleme, işlem hatları, dosya kitaplığı, kimlik doğrulama, ekipler ve yönetici işlemleri."
| `POST` | `/api/auth/saml/callback` | Herkese açık | SAML doğrulama tüketici hizmeti |
Bir kullanıcı için MFA etkinleştirildiğinde, `POST /api/auth/login` bir oturum belirteci yerine `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` döndürür. Bu `mfaToken` değerini bir TOTP veya kurtarma kodu ile birlikte `/api/auth/mfa/complete` adresine gönderin.
### İzinler {#permissions}
| İzin | Yönetici | Kullanıcı |
|-----------|:-----:|:----:|
| Araçları kullan | ✓ | ✓ |
| Kendi dosyaları/işlem hatları/API anahtarları | ✓ | ✓ |
| Tüm kullanıcıların dosyalarını/işlem hatlarını/anahtarlarını gör | ✓ | - |
| Ayarları yaz | ✓ | - |
| Kullanıcıları ve ekipleri yönet | ✓ | - |
| Markalamayı yönet | ✓ | - |
## Sağlık Kontrolü {#health-check}
| Yöntem | Yol | Erişim | Açıklama |
|--------|------|--------|-------------|
| `GET` | `/api/v1/health` | Herkese açık | Temel sağlık kontrolü. 200 ile `{"status":"healthy","version":"..."}` döndürür veya veritabanına erişilemiyorsa 503 ile `{"status":"unhealthy"}` döndürür. |
| `GET` | `/api/v1/readyz` | Herkese açık | Hazır olma yoklaması. Yapılandırıldığında PostgreSQL, Redis, disk alanı ve S3'ü kontrol eder. Örnek trafik almaması gerektiğinde 503 döndürür. |
| `GET` | `/api/v1/admin/health` | Yönetici (`system:health`) | Çalışma süresi, depolama modu, veritabanı durumu, kuyruk durumu ve GPU kullanılabilirliği dahil ayrıntılı tanılama. |
## Araçları Kullanma {#using-tools}
Her araç aynı deseni izler:
```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>` şunlardan biridir: `image`, `video`, `audio`, `pdf` veya `files`.
- Yükleme `multipart/form-data` şeklindedir.
-`settings`, araca özgü seçeneklere sahip bir JSON dizesidir.
-`clientJobId`, çağırana özgü ilerleme ilişkilendirmesi için isteğe bağlı bir form alanıdır.
-`fileId`, mevcut bir dosya kitaplığı öğesine başvuran isteğe bağlı bir form alanıdır. Bulunduğunda, işlenen çıktı yeni bir sürüm olarak kaydedilir ve yanıt `savedFileId` içerir.
- **Kuyruğa alınan herhangi bir araç**, uzun süre çalışıyorsa veya eşzamanlı bekleme penceresini aşarsa 202 JSON döndürebilir: `{"jobId":"...","async":true}`. İlerleme için SSE'ye bağlanın, ardından tamamlandığında indirin ([İlerleme İzleme](#progress-tracking) bölümüne bakın).
- **Toplu** yollar, genel toplu kayıt defterinde kayıtlı araçlar için doğrudan akışa alınan (`X-Job-Id` başlığıyla) bir ZIP arşivi döndürür.
## Araçlar Başvurusu {#tools-reference}
### Dönüştürme Ön Ayarları {#conversion-presets}
Paylaşılan katalog, `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg` ve `excel-to-csv` gibi 83 özel dönüştürme ön ayarı uç noktası içerir. Ön ayarlar birinci sınıf araç yollarıdır:
`POST /api/v1/tools/<section>/<presetId>`
Her ön ayar çıktı biçimini kilitler ve `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster` veya `convert-spreadsheet` gibi bir temel araca yetki devreder. Eksiksiz yol tablosu ve isteğe bağlı ayarlar için [Dönüştürme Ön Ayarları](/tr/tools/conversion-presets) bölümüne bakın.
### Temel Öğeler {#essentials}
| Araç Kimliği | Ad | Anahtar ayarlar |
|---------|------|-------------|
| `resize` | Yeniden Boyutlandır | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement` ve 23 sosyal medya ön ayarı |
Tüm yapay zeka araçları kendi donanımınızda çalışır: varsayılan olarak CPU'da veya desteklenen bir NVIDIA GPU mevcut olduğunda NVIDIA CUDA'da. VA-API, Quick Sync veya OpenCL aracılığıyla Intel/AMD iGPU hızlandırması yapay zeka çıkarımı için bugün desteklenmemektedir. İnternet gerekmez.
| Araç Kimliği | Ad | Yapay Zeka Modeli | Anahtar ayarlar |
| `red-eye-removal` | Kırmızı Göz Giderme | Yüz işaret noktası + renk analizi | `sensitivity`, `strength` |
| `restore-photo` | Fotoğraf Onarımı | Çok adımlı işlem hattı | `mode` (auto/light/heavy), `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
| `passport-photo` | Vesikalık Fotoğraf | MediaPipe işaret noktaları | İki aşamalı akış. Çözümleme, multipart `file` kullanır; oluşturma, `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), işaret noktaları, görüntü boyutları içeren JSON kullanır |
| `extract-zip` | ZIP Ayıkla | - (bomba korumalı) |
### HTML'den Görüntüye {#html-to-image}
Bir web sayfasını görüntü olarak yakalayın. Diğer araçların aksine bu uç nokta, multipart form verisi yerine `application/json` kabul eder (dosya yükleme gerekmez).
Bazı araçlar standart `POST /api/v1/tools/<section>/<toolId>` dışında ek uç noktalar sunar:
| Yöntem | Yol | Açıklama |
|--------|------|-------------|
| `GET` | `/api/v1/tools/popular` | Popüler araç kimliklerini döndürür, kullanım verileri az olduğunda özenle seçilmiş bir varsayılan listeye geri döner |
| `POST` | `/api/v1/tools/image/remove-background/effects` | Yapay zekayı yeniden çalıştırmadan arka plan efektleri (renk/gradyan/bulanıklaştırma/gölge) uygula. İlk kaldırmadan önbelleğe alınan maskeyi kullanır. |
| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | Bir görüntüden mevcut EXIF/IPTC/XMP meta verilerini oku |
| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | Kaldırmadan önce meta veri alanlarını incele |
| `POST` | `/api/v1/tools/image/passport-photo/analyze` | 1. Aşama: Yapay zeka yüz algılama + arka plan kaldırma. Yüz işaret noktalarını ve önbelleğe alınan verileri döndürür. |
| `POST` | `/api/v1/tools/image/passport-photo/generate` | 2. Aşama: Önbelleğe alınan analizi kullanarak kırp, yeniden boyutlandır ve döşe. Yapay zeka yeniden çalıştırılmaz. |
| `POST` | `/api/v1/tools/image/gif-tools/info` | GIF meta verilerini al (kare sayısı, boyutlar, süre) |
| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | PDF meta verilerini al (sayfa sayısı, boyutlar) |
| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | Belirli bir PDF sayfasının önizlemesini oluştur |
| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/info` | Özel JPG ön ayarı için PDF meta verilerini al |
| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | JPG ön ayarı PDF sayfa önizlemesi oluştur |
| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | Özel PNG ön ayarı için PDF meta verilerini al |
| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | PNG ön ayarı PDF sayfa önizlemesi oluştur |
| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | Özel TIFF ön ayarı için PDF meta verilerini al |
| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | TIFF ön ayarı PDF sayfa önizlemesi oluştur |
| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | Birden çok SVG'yi toplu olarak rastere dönüştür |
| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | Görüntü kalitesini analiz et ve iyileştirme önerileri döndür |
| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | Canlı parametre ayarı için hafif önizleme. Boyut başlıklarıyla iyileştirilmiş görüntü döndürür. |
Toplu işlem etkin genel bir aracı bir kerede birden çok dosyaya uygulayın. Bir ZIP arşivi döndürür. PDF imzalama ve PDF'den görüntüye ön ayar yolları gibi özel çok dosyalı veya çok adımlı yollar, genel `/batch` yolu yerine kendi uç nokta sözleşmelerini kullanır.
`ocr-pdf` aracı bu genel `/batch` yolunu destekler.
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}'
```
Eşzamanlılık `CONCURRENT_JOBS` tarafından kontrol edilir (varsayılan: CPU çekirdeklerinden otomatik algılanır). `MAX_BATCH_SIZE`, toplu işlem başına dosya sayısını sınırlar (varsayılan: 100; sınırsız için 0 ayarlayın).
## İşlem Hatları {#pipelines}
### Bir işlem hattı çalıştır {#execute-a-pipeline}
```bash
# Single file
curl -X POST http://localhost:1349/api/v1/pipeline/execute \
Her adımın çıktısı bir sonraki adımın girdisidir. İşlem hatları varsayılan olarak 20 adıma izin verir; `MAX_PIPELINE_STEPS` ile yapılandırılabilir. Sınırı kaldırmak için `MAX_PIPELINE_STEPS=0` ayarlayın.
### İşlem hatlarını kaydet ve yönet {#save-and-manage-pipelines}
| Yöntem | Yol | Açıklama |
|--------|------|-------------|
| `POST` | `/api/v1/pipeline/save` | Adlandırılmış bir işlem hattı kaydet (`name`, `description`, `steps[]`) |
| `GET` | `/api/v1/pipeline/list` | Kayıtlı işlem hatlarını listele (yöneticiler tümünü görür; kullanıcılar kendilerininkini görür) |
| `DELETE` | `/api/v1/pipeline/:id` | Sil (sahibi veya yöneticisi) |
| `GET` | `/api/v1/pipeline/tools` | İşlem hattı adımları için geçerli araç kimliklerini listele |
## İlerleme İzleme {#progress-tracking}
Uzun süre çalışan işler, kuyruğa alınan araçlar, toplu işler ve işlem hatları, Server-Sent Events aracılığıyla gerçek zamanlı ilerleme yayar. İlerleme akışı herkese açıktır ve iş kimliğiyle anahtarlanır, bu nedenle istemcilerin okumak için bir Authorization başlığı göndermesi gerekmez.
```bash
# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
| `GET` | `/api/v1/files/:id/preview` | Kayıtlı bir PDF, office belgesi, video veya ses dosyası için önbelleğe alınmış ya da oluşturulmuş tarayıcı uyumlu önizlemeyi akışa al |
| `POST` | `/api/v1/preview/generate` | Yüklenen bir medya dosyası için önce kaydetmeden isteğe bağlı bir MP4 veya MP3 önizlemesi oluştur |
| `GET` | `/api/v1/download/:jobId/:filename` | Bir çalışma alanından işlenmiş bir dosya indir |
Bir araç sonucunu kitaplığa otomatik kaydetmek için, mevcut bir kitaplık dosyasına başvuran bir multipart form alanı olarak `fileId` ekleyin. İşlenen sonuç yeni bir sürüm olarak kaydedilir.
## API Anahtarı Yönetimi {#api-key-management}
| Yöntem | Yol | Erişim | Açıklama |
|--------|------|--------|-------------|
| `POST` | `/api/v1/api-keys` | Kimlik doğrulamalı | Yeni anahtar oluştur - bir kez gösterilir |
| `GET` | `/api/v1/api-keys` | Kimlik doğrulamalı | Anahtarları listele (ad, kimlik, lastUsedAt - ham anahtar değil) |
Çalışma zamanı yapılandırması, tanınan anahtarlardan oluşan kapalı bir küme kullanır. Okuma `settings:read`, yazma ise `settings:write` gerektirir; güvenlik ve uyumluluk anahtarları ayrıca `security:manage` veya `compliance:manage` gerektirir. Gizli ayarlar tam yönetici yetkisi gerektirirken özel uç noktaların yönettiği kimlik bilgileri ve durum burada salt okunurdur. Toplu güncellemeler herhangi bir değer yazılmadan önce doğrulanır.
Kullanıcı başına tercihler, örnek ayarlarından ayrıdır. Kimliği doğrulanmış herhangi bir kullanıcı kendi tercih haritasını okuyabilir ve güncelleyebilir.
| Yöntem | Yol | Açıklama |
|--------|------|-------------|
| `GET` | `/api/v1/preferences` | Geçerli kullanıcının tercihlerini `{ "preferences": { ... } }` olarak al |
| `PUT` | `/api/v1/preferences` | Geçerli kullanıcı için bir veya daha fazla tercih anahtarını ekle/güncelle |
## Roller {#roles}
Ayrıntılı izinlerle özel rol yönetimi.
| Yöntem | Yol | Erişim | Açıklama |
|--------|------|--------|-------------|
| `GET` | `/api/v1/roles` | Yönetici (`audit:read`) | Kullanıcı sayılarıyla birlikte tüm rolleri listele |
| `POST` | `/api/v1/roles` | Yönetici (`security:manage`) | Özel bir rol oluştur (`name`, `description`, `permissions`) |
| `PUT` | `/api/v1/roles/:id` | Yönetici (`security:manage`) | Özel bir rolü güncelle (yerleşik roller değiştirilemez) |
| `DELETE` | `/api/v1/roles/:id` | Yönetici (`security:manage`) | Özel bir rolü sil (yerleşik roller silinemez; etkilenen kullanıcılar `user` rolüne geri döner) |
| `from` | Bu ISO 8601 tarihinden sonraki girdileri filtrele |
| `to` | Bu ISO 8601 tarihinden önceki girdileri filtrele |
## Analitik {#analytics}
| Yöntem | Yol | Erişim | Açıklama |
|--------|------|--------|-------------|
| `GET` | `/api/v1/config/analytics` | Herkese açık | Etkin analitik yapılandırmasını al (PostHog anahtarı, Sentry DSN, örnekleme oranı). Analitik kapalı olduğunda, ister derleme zamanı bakisinden ister örnek `analyticsEnabled` ayarından, anahtarlar, DSN ve örnek kimliği boş olur. |
| `POST` | `/api/v1/feedback` | Kimlik doğrulamalı | Yapılandırılmış PostHog projesine `feedback_submitted` olarak açık kullanıcı geri bildirimi gönder. Yol, analitik kapısına uyar, gönderimleri hız sınırlar, `contactOk` doğru olmadıkça iletişim alanlarını çıkarır ve dosya içeriklerini, dosya adlarını, yükleme yollarını veya ham özel hata metnini asla kabul etmez. Analitik devre dışıyken `{ "ok": true, "accepted": false }` döndürür. |
| `PUT` | `/api/v1/settings` | Yönetici (`settings:write`) | Örnek genelinde devre dışı bırakmayı ayarla. Analitiği herkes için kapatmak üzere `{ "analyticsEnabled": "false" }`, tekrar açmak üzere `"true"` JSON gövdesi gönderin. |
## Özellikler / Yapay Zeka Paketleri {#features-ai-bundles}
Yapay zeka özellik paketlerini yönetin (Docker ortamında yapay zeka modeli paketlerini kurun/kaldırın). Özel otomasyondan bir aracı etkinleştirirken araç düzeyindeki kurulum uç noktasını tercih edin: bazı yapay zeka araçları birden fazla paylaşılan pakete ihtiyaç duyar ve bu uç nokta zaten kurulu paketleri atlarken yalnızca eksik olanları kuyruğa alır.
OCR, katı bir bağımlılık yerine isteğe bağlı bir geliştirmedir. `fast` Tesseract katmanı paket olmadan çalışır; `POST /api/v1/admin/features/ocr/install`, `balanced` ve `best` için imzalı RapidOCR paketini Linux amd64 veya arm64 üzerine yükler. Doğru OCR çalışma zamanı, yalnızca CPU ve NVIDIA ana bilgisayarlarında CPU kullanır ve en az 4 GiB etkin bellek gerektirir (yapılandırılmış kapsayıcı cgroup sınırı, aksi takdirde ana bilgisayar belleği). SnapOtter, `requiredMemoryBytes`, `effectiveMemoryBytes` ve `insufficient-memory` uyumluluk nedenini bildirir ve indirmeden önce uyumsuz bir yüklemeyi reddeder. Bu bellek gereksinimi `fast` için geçerli değildir. Paket, hedefe bağlı olarak yaklaşık 208-234 MiB indirilebilir ve 409-488 MiB kuruludur; imzalı dizin, yükleme sırasında uygulanan tam boyutları bağlar.
| `GET` | `/api/v1/features` | Kimlik doğrulamalı | Tüm özellik paketlerini ve kurulum durumlarını listele |
| `POST` | `/api/v1/admin/features/:bundleId/install` | Yönetici (`features:manage`) | Bir özellik paketi kur (eşzamansız, ilerleme izleme için `jobId` döndürür) |
| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Yönetici (`features:manage`) | Bir aracın gerektirdiği her paketi kur; paket başına kuyruğa alınan/atlanan durumu döndürür |
| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Yönetici (`features:manage`) | Bir özellik paketini kaldır ve model dosyalarını temizle |
| `GET` | `/api/v1/admin/features/disk-usage` | Yönetici (`features:manage`) | Yapay zeka modellerinin toplam disk kullanımını al |
| `POST` | `/api/v1/admin/features/import` | Yönetici (`features:manage`) | Eski bir AI paketini (`file`) veya imzalı bir çevrimdışı OCR sürümünü (`index` artı`archive`) içe aktarın |
Hava boşluklu bir OCR içe aktarımı, sürümün imzalı`ocr-runtime-index.json`'sini ve eşleşen platform arşivini içermelidir. SnapOtter, çevrimiçi kurulumda kullanılan aynı Ed25519 imzasını, yapay karma değerini, uyumluluğu, çıkarma ve duman testi kontrollerini uygular:
```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"
```
arm64'de `linux-arm64-cpu-py311` arşivini kullanın. Başka bir hedef için imzalanmış bir yapıt yüklenmek yerine reddedilir.
**Tam yetkili yerleşik yönetici**, kimliği doğrulanmış aktörün `admin` rolüne ve etkin yönetici izinlerinin tamamına sahip olduğu anlamına gelir. Herhangi bir yönetici iznini içermeyen API anahtarı kapsamı bu koşulu sağlamaz.
| `GET` | `/api/v1/enterprise/config/export` | Tam yetkili yerleşik yönetici | Redakte edilmiş örnek yapılandırmasını, özel rolleri ve ekipleri dışa aktar |
| `POST` | `/api/v1/enterprise/config/import` | Tam yetkili yerleşik yönetici | Yapılandırmayı içe aktar, isteğe bağlı deneme çalışmasıyla |
