Görsel Optimizasyonu API Uç Noktası

Çekirdek görsel işleme uç noktası POST /v1/optimize için resmi teknik referans belgesi.

Görselleri optimize etmek, dönüştürmek, küçültmek ve yeniden boyutlandırmak için kullanılan birincil uç nokta:

POST https://api.smallpict.app/v1/optimize
(Takma ad: POST https://api.smallpict.app/v1/convert)

İstek Formatı (JSON Yükü)

HTTP

POST /v1/optimize HTTP/1.1Host: api.smallpict.appX-API-Key: sp_sdk_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0bX-Timestamp: 1716301234X-Signature: 3a9f8b2c4d6e8a0f1b3c5d7e9f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e5f7aContent-Type: application/jsonIdempotency-Key: c9b8a7f6-e5d4-4c3b-2a1f-0e9d8c7b6a5f

İstek Gövdesi Şeması

JSON

{  "filename": "hero-banner.jpg",  "mime_type": "image/jpeg",  "filesize": 1654200,  "options": {    "format": "avif",    "quality": 80,    "max_dimension": 1600,    "max_width": 1920,    "max_height": 1080,    "lossless": false,    "strip_metadata": true  }}

Alan	Tür	Zorunlu	Açıklama
`filename`	string	Evet	Görsel dosyasının orijinal adı (örn. `banner.png`)
`mime_type`	string	Evet	MIME türü (örn. `image/jpeg`, `image/png`, `image/webp`)
`filesize`	integer	Evet	Bayt cinsinden toplam dosya boyutu (> 0 olmalıdır)
`options.format`	string	Hayır	Hedef format: `avif`, `webp`, `original` / `keep`, `jpg`, `png` (Varsayılan: `webp`)
`options.quality`	integer	Hayır	`1` ile `100` arasında sıkıştırma kalitesi (Varsayılan: `80`)
`options.max_dimension`	integer	Hayır	En uzun kenar için piksel cinsinden orantılı sınırlama eşiği (örn. `1600`, `1920`, `2048`, `2560`)
`options.max_width`	integer	Hayır	Maksimum genişlik piksel sınırlaması
`options.max_height`	integer	Hayır	Maksimum yükseklik piksel sınırlaması
`options.lossless`	boolean	Hayır	Piksel düzeyinde kayıpsız sıkıştırmayı etkinleştir (Varsayılan: `false`)
`options.strip_metadata`	boolean	Hayır	Kamera EXIF verilerini ve renk profillerini temizle (Varsayılan: `true`)

Doğrudan Görsel Dönüştürücü Parametreleri

Doğrudan bulut dönüştürme yolları anında yeniden boyutlandırma için sorgu parametrelerini destekler:

GET https://api.smallpict.app/v1/transform?url=...&format=webp&quality=80&max_dimension=1600

?format=avif|webp|original
?quality=1..100
?max_dimension=1600
?max_width=1920
?max_height=1080

Sunucu Yanıtı (200 OK)

Başarılı başlatmanın ardından SmallPict güvenli bir önceden imzalanmış yükleme URL'si ve iş kimliği döndürür:

Response · 200 OK

{  "upload_url": "https://upload.smallpict.app/uploads/a1b2c3d4/hero-banner.jpg?signature=...",  "job_id": "job-a1b2c3d4",  "object_key": "uploads/a1b2c3d4/hero-banner.jpg",  "status": "queued"}

Görsel verisini HTTP PUT isteğiyle upload_url adresine yükleyin, ardından iş durumunu kontrol edin. Güvenli yükleme bağlantısını yanıtta döndüğü şekliyle kullanın: kısa süre sonra geçerliliğini yitirir ve yalnızca bu yükleme için çalışır.

İş Durumunu Sorgulama

Dönüştürme sürecini şu uç nokta üzerinden sorgulayabilirsiniz:

GET https://api.smallpict.app/v1/optimize/status?job_id=job-a1b2c3d4

Tamamlanma Yanıtı (200 OK)

Response · 200 OK

{  "job_id": "job-a1b2c3d4",  "status": "completed",  "url": "https://cdn.smallpict.app/opt/hero-banner.avif",  "format": "avif",  "bytes_saved": 1456200,  "savings_percentage": 88.03,  "created_at": "2026-08-23T08:00:00Z",  "updated_at": "2026-08-23T08:00:01Z"}