API dokümantasyonu

Kendi uygulamandan görsel yükle, listele ve yönet. Tek bir POST isteğiyle fotoğrafını gönderip paylaşılabilir bağlantısını alabilirsin.

Başlangıç

API, Pro ve Business planlarında kullanılabilir. Anahtarını panelindeki API bölümünden oluşturabilirsin.

Tüm istekler https://hizlifoto.net/api/v1/public altındadır ve HTTPS zorunludur. Yanıtlar her zaman JSON döner.

Kimlik doğrulama

Anahtarını Authorization başlığında bearer token olarak gönder. Alternatif olarak X-API-Key başlığını da kullanabilirsin.

Authorization

Authorization: Bearer hf_live_9fdbfbbf1c2d...

Anahtarı URL'ye koyma. Sorgu parametresiyle anahtar kabul etmiyoruz; adresler sunucu kayıtlarına, tarayıcı geçmişine ve Referer başlıklarına düşer, bir kimlik bilgisinin düşmemesi gerekir.

Anahtarın yalnızca oluşturulduğu anda bir kez gösterilir. Veritabanında yalnızca SHA-256 özeti saklanır, bu yüzden sonradan tekrar gösteremeyiz. Kaybedersen iptal edip yenisini oluştur.

Yetkiler

Her anahtara yalnızca ihtiyaç duyduğu yetkileri ver. Yetkisi olmayan bir uç nokta çağrıldığında 403 ve insufficient_scope döner.

images:read	Görselleri listele ve oku
images:write	Görsel yükle ve düzenle
images:delete	Görsel sil
albums:read	Albümleri listele ve oku
albums:write	Albüm oluştur ve düzenle
albums:delete	Albüm sil

Hız sınırı

Sınır planına bağlıdır: Pro için dakikada 120, Business için dakikada 600 istek. Her yanıtta kalan hakkını görebilirsin:

Yanıt başlıkları

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118

Sınırı aşarsan 429 ve ne kadar beklemen gerektiğini söyleyen bir Retry-After başlığı alırsın.

Görsel yükleme

multipart/form-data ile tek dosya gönderilir. Dosyanın gerçek türü içeriğinden belirlenir; uzantı veya bildirilen MIME türü dikkate alınmaz.

POST/uploadimages:write

Bir görsel yükler ve bağlantılarını döner.

Alan	Tür	Durum	Açıklama
file	dosya	Zorunlu	JPG, PNG, WebP, GIF, AVIF veya BMP.
title	metin	İsteğe bağlı	Görsel başlığı, en fazla 160 karakter.
visibility	metin	İsteğe bağlı	public, unlisted (varsayılan) veya private.
strip_metadata	boolean	İsteğe bağlı	Varsayılan true. EXIF ve konum bilgisini dosyadan siler.
expires_in	sayı	İsteğe bağlı	Saniye cinsinden ömür. 300 ile 31536000 arası.

curl

curl -X POST https://hizlifoto.net/api/v1/public/upload \
  -H "Authorization: Bearer $HIZLIFOTO_KEY" \
  -F "file=@fotograf.jpg" \
  -F "visibility=unlisted" \
  -F "expires_in=604800"

201 Created

{
  "image": {
    "id": "a8K92xQw",
    "status": "processing",
    "filename": "fotograf.jpg",
    "width": 2400,
    "height": 1600,
    "size_bytes": 289765,
    "visibility": "unlisted",
    "urls": {
      "page": "https://hizlifoto.net/i/a8K92xQw",
      "direct": "https://hizlifoto.net/f/0c069d3d.../original.jpg",
      "download": "https://hizlifoto.net/d/a8K92xQw",
      "thumb": null
    }
  }
}

Yanıttaki status alanı ilk anda processing olur: WebP ve AVIF sürümleri arka planda hazırlanır ve bu yüzden thumb gibi alanlar başlangıçta null döner. Orijinal dosya ve direct bağlantısı ilk andan itibaren çalışır. Küçük boyutlara ihtiyacın varsa görseli birkaç saniye sonra tekrar sorgula.

Görseller

GET/imagesimages:read

Hesabındaki görselleri sayfalı olarak listeler. page, per_page (en fazla 100) ve visibility parametrelerini destekler.

GET/images/{id}images:read

Tek bir görselin ayrıntılarını döner.

DELETE/images/{id}images:delete

Görseli çöp kutusuna taşır. 30 gün içinde panelden geri alınabilir.

curl

curl https://hizlifoto.net/api/v1/public/images?per_page=50 \
  -H "Authorization: Bearer $HIZLIFOTO_KEY"

Albümler

GET/albumsalbums:read

Albümlerini listeler.

POST/albumsalbums:write

Yeni albüm oluşturur. title zorunlu; description ve visibility isteğe bağlı.

DELETE/albums/{id}albums:delete

Albümü siler. İçindeki görseller kitaplığında kalır.

Hesap

GET/account

Kullanılan depolama, sınırlar ve mevcut plan bilgisi. Yetki gerektirmez.

Hatalar

Hatalar her zaman bir message ve makine tarafından okunabilir bir code içerir. message alanı doğrudan kullanıcıya gösterilebilecek şekilde yazılır.

HTTP	code	Anlamı
401	missing_api_key	Authorization başlığı gönderilmedi.
401	invalid_api_key	Anahtar geçersiz, süresi dolmuş veya iptal edilmiş.
403	insufficient_scope	Anahtarın bu işlem için yetkisi yok.
403	api_not_available	Planın API erişimi içermiyor.
413	storage_full	Depolama alanın yetersiz.
422	unsupported_type	Dosya desteklenen bir görsel değil.
422	file_too_large	Dosya, plan sınırını aşıyor.
422	truncated_image	Dosya eksik ulaştı.
429	rate_limited	Dakikalık istek sınırı aşıldı.

422 Unprocessable Content

{
  "message": "Bu dosya 30 MB boyutunda ve 25 MB sınırını aşıyor.",
  "code": "file_too_large"
}

Sürümleme

Yol /api/v1/ ile sürümlenir. Uyumluluğu bozan bir değişiklik gerekirse /api/v2/ olarak yayınlanır; v1 çalışmaya devam eder. Yanıtlara yeni alan eklenmesi bozucu değişiklik sayılmaz, bu yüzden bilmediğin alanları yok sayacak şekilde ayrıştır.