REST API · v1
StarkCDN API dokümantasyonu
Görsel, video, ses, ofis dokümanı, tasarım, 3D, font ve arşiv dosyalarını kendi uygulamanızdan yükleyin, listeleyin ve yönetin; görselleri URL parametreleriyle anında boyutlandırın. Basit bir REST API ve AI asistanları için hazır bir MCP sunucusu.
- Protokol:
- HTTPS
- Format:
- JSON
- Kimlik:
- API anahtarı / JWT
- Dosya başına:
- 100 MB
- AI:
- MCP
Hızlı başlangıç#
Üç adımda ilk dosyanızı CDN’e yükleyip kullanın.
-
API anahtarınızı alın
Panele giriş yapın ve Kontrol paneli → API hızlı başlangıç kartından anahtarınızı kopyalayın. Aynı yerden bir proje oluşturun; dosyalar her zaman bir projeye yüklenir. Proje kimliğini (
project_id) projeler uç noktasından öğrenebilirsiniz.curl "https://cdn.starkbilisim.com/api/api.php?action=projects" \ -H "X-API-Key: API_ANAHTARINIZ" -
Dosyanızı yükleyin
Dosyayı
filealanıylamultipart/form-dataolarak gönderin. Yanıttakiimage.urldosyanın kalıcı, herkese açık adresidir.curl -X POST "https://cdn.starkbilisim.com/api/api.php?action=upload" \ -H "X-API-Key: API_ANAHTARINIZ" \ -F "project_id=7" \ -F "file=@kapak.jpg" -
URL’yi kullanın
Dönen adres kimlik doğrulama gerektirmez; doğrudan sitenizde, uygulamanızda veya e-postalarınızda kullanabilirsiniz. Dosyalar 1 gün önbelleğe alınabilecek şekilde sunulur (silinen bir dosya CDN ve tarayıcı önbelleklerinden en geç 1 gün içinde kalkar).
<img src="https://cdn.starkbilisim.com/uploads/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg" alt="Kapak görseli" width="1200" height="630" loading="lazy">
Temel URL ve uç noktalar#
Dosya API’sinin tüm işlemleri tek bir adres üzerinden, action sorgu parametresiyle seçilir. Yanıtlar her zaman JSON’dur (dosyanın kendisini döndüren serve hariç).
https://cdn.starkbilisim.com/api/api.php
| Metot | İşlem | Açıklama |
|---|---|---|
| POST | ?action=upload | Dosya yükle (multipart) |
| POST | ?action=upload_init | Parçalı yüklemeyi başlat |
| POST | ?action=upload_chunk | Bir parça gönder |
| POST | ?action=upload_complete | Parçalı yüklemeyi tamamla |
| POST | ?action=upload_abort | Parçalı yüklemeyi iptal et (DELETE de olur) |
| POST | ?action=url_upload | Uzak bir URL’den dosya yükle |
| GET | ?action=list | Bir projenin dosyalarını listele |
| DELETE | ?action=delete | Dosya sil |
| GET | ?action=serve | Dosyayı sun / görseli boyutlandır |
| GET | ?action=limits | Yükleme limitleri ve izinli türler |
| GET | ?action=projects | Projeleri listele |
| GET | ?action=stats | Hesap istatistikleri |
Hata durumunda uygun HTTP durum kodu ve {"error": "mesaj"} gövdesi döner. Ayrıntılar: Hata kodları.
Diğer adresler
| Adres | Kimlik | Açıklama |
|---|---|---|
| /img/{dosya_yolu}?w=&format= | — | Herkese açık anlık görsel dönüştürme |
| /mcp | API anahtarı | AI istemcileri için MCP sunucusu |
| /api/health.php | — | Sağlık kontrolü (izleme servisleri için) |
| /api/auth.php, projects.php, images.php | JWT | Web panelinin kullandığı uç noktalar |
Kimlik doğrulama#
Dosya API’si iki yöntemi kabul eder. Uygulamalar ve sunucular için API anahtarını kullanın.
API anahtarı önerilen
64 karakterlik onaltılık anahtar. Panelden alınır ve yenilenebilir. Üç şekilde gönderilebilir:
- Header
X-API-Key: API_ANAHTARINIZ - Sorgu
?api_key=API_ANAHTARINIZ - Form
api_key(multipart/form POST alanı)
JWT oturum belirteci
Web panelinin kullandığı, 24 saat geçerli belirteç. auth.php ile giriş yapılarak alınır.
- Header
Authorization: Bearer eyJhbGciOi…
Dosya API’si önce JWT’yi, sonra API anahtarını dener. projects.php, images.php ve auth.php yalnızca JWT kabul eder.
cdn.starkbilisim.com kökenine izin verdiği için başka sitelerin tarayıcı kodundan yapılan istekler zaten engellenir; istekleri kendi sunucunuzdan yapın. Anahtar sızarsa panelden yenileyin; eski anahtar hemen geçersiz olur.curl "https://cdn.starkbilisim.com/api/api.php?action=stats" \
-H "X-API-Key: API_ANAHTARINIZ"
// Node.js 18+ (sunucu tarafı)
const res = await fetch('https://cdn.starkbilisim.com/api/api.php?action=stats', {
headers: { 'X-API-Key': process.env.STARKCDN_API_KEY },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
<?php
$ch = curl_init('https://cdn.starkbilisim.com/api/api.php?action=stats');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('STARKCDN_API_KEY')],
]);
$data = json_decode(curl_exec($ch), true);
import os
import requests
r = requests.get(
'https://cdn.starkbilisim.com/api/api.php',
params={'action': 'stats'},
headers={'X-API-Key': os.environ['STARKCDN_API_KEY']},
timeout=30,
)
r.raise_for_status()
print(r.json())
Hız limitleri#
Limit aşıldığında 429 Too Many Requests döner; bir süre bekleyip tekrar deneyin.
| Kapsam | Limit | Not |
|---|---|---|
Giriş (auth.php login) | 10 deneme / 5 dakika | IP adresi başına |
Google ile giriş (auth.php google) | 10 deneme / 5 dakika | IP adresi başına |
| MCP sunucusu | 120 istek / dakika | Kullanıcı başına |
| MCP hatalı kimlik | 30 deneme / 5 dakika | IP adresi başına |
| Açık parçalı yükleme | Aynı anda 10 | Kullanıcı başına; tamamlayın veya iptal edin |
Sağlık kontrolü (health.php) | 60 istek / dakika | IP adresi başına |
Görsel dönüştürme (/img/) | İstek limiti yok | Sunucuda aynı anda en fazla 2 görsel işlenir; yoğunlukta orijinal dosyaya yönlendirilir |
Dosya API’si (api.php) | İstek limiti yok* | Adil kullanım |
* Sunucu kaynaklarını korumak için adil kullanım politikaları uygulanabilir.
AI asistanı için prompt#
ChatGPT, Claude veya Copilot gibi bir asistana StarkCDN entegrasyonu yazdıracaksanız aşağıdaki özeti kopyalayıp sohbetin başına yapıştırın. Claude kullanıyorsanız MCP sunucusu daha da pratiktir.
StarkCDN; görsel, video, ses, doküman/ofis, tasarım, 3D, ham fotoğraf, font ve arşiv dosyalarını barındıran bir CDN ve dosya yönetim platformudur. Görseller /img/ adresleriyle anında boyutlandırılabilir. Aşağıdaki bilgilere göre StarkCDN API'sini kullanan kod yaz.
TEMEL URL: https://cdn.starkbilisim.com/api/api.php (işlem ?action=... ile seçilir)
YANIT: JSON. Hata olursa HTTP 4xx/5xx ve {"error": "mesaj"}.
KİMLİK DOĞRULAMA (API anahtarı panelden alınır, 64 karakter hex):
- Header: X-API-Key: <API_ANAHTARI> (önerilen)
- veya sorgu parametresi ?api_key=<API_ANAHTARI> (multipart POST'ta api_key alanı da olur)
- Web paneli JWT'si de geçerlidir: Authorization: Bearer <JWT>
- Herkese açık kayıt yoktur; hesaplar yönetici tarafından oluşturulur.
- CORS yalnızca cdn.starkbilisim.com'a açıktır: API'yi sunucu tarafında çağır, anahtarı tarayıcı koduna koyma.
PROJELER: Her dosya bir projeye aittir. project_id için GET ?action=projects kullan. Proje oluşturma web panelinden (veya MCP create_project aracıyla) yapılır.
UÇ NOKTALAR:
- GET ?action=projects → {"projects":[{id,name,description,image_count,created_at}]}
- POST ?action=upload (multipart/form-data): project_id*, file* (eski ad: image), width, height, fit=cover|contain, dedupe=1 → 201 {"success":true,"image":{id,project_id,original_name,url,file_size,mime_type,category,width,height,created_at}}
- POST ?action=url_upload (JSON): url*, project_id*, width, height, fit, dedupe → 201, aynı "image" nesnesi + source_url
- Parçalı yükleme (büyük dosyalar):
1) POST ?action=upload_init (JSON: project_id*, filename*, size* (bayt), width, height, fit, dedupe) → 201 {success,upload_id,chunk_size,total_chunks,max_bytes,expires_at}
2) POST ?action=upload_chunk&upload_id=...&index=N (N 0'dan başlar). Gövde: ham baytlar (Content-Type: application/octet-stream) veya multipart "chunk" alanı. Son parça hariç her parça tam chunk_size bayt olmalı. → {success,upload_id,index,received,total_chunks}
3) POST ?action=upload_complete&upload_id=... → 201, upload ile aynı "image" nesnesi (eksik parça varsa 409)
İptal: POST veya DELETE ?action=upload_abort&upload_id=... Kullanıcı başına en fazla 10 açık parçalı yükleme (aşılırsa 429); tamamlanmayanlar 24 saat sonra silinir.
- TEKRAR ÖNLEME: upload, url_upload ve upload_init'e dedupe=1 eklenirse ve aynı projede birebir aynı dosya (aynı kaynak + aynı width/height/fit) varsa kopya saklanmaz; mevcut dosya "duplicate": true alanıyla döner (durum kodu yine 201). Verilmezse her yükleme yeni dosyadır.
- GET ?action=list&project_id=X&page=1&limit=50 (en fazla 100)&sort=newest|oldest|name_asc|name_desc → {images:[{id,original_name,url,file_size,mime_type,category,width,height,created_at}],total,page,totalPages}
- DELETE ?action=delete&id=X → {"success":true,"message":"Image deleted"} ve çöp kutusu etkinse ek olarak "trashed":true,"restore_until":"YYYY-MM-DD HH:MM:SS" (UTC). URL hemen 404 olur; dosya 30 gün boyunca yalnızca web panelinden (Çöp kutusu) geri yüklenebilir, sonra kalıcı silinir. API ile geri yükleme yoktur.
- GET ?action=serve&id=X&w=&h=&fit= → dosyanın kendisi. Kimlik ister; herkese açık sayfalarda "url" alanını veya /img/ dönüştürme adresini kullan.
- GET ?action=stats → {projects,images,storage_bytes,storage_formatted,recent_images[...],monthly_uploads[{month,count}],categories{kategori:{count,bytes}}}
- GET ?action=limits → {max_upload_bytes,max_upload_formatted,chunk_size,single_request_max_bytes,max_files_per_upload,max_image_pixels,allowed_types[{mime,extension,category}],allowed_extensions[],extension_aliases{jpeg:"jpg",...}}
GÖRSEL DÖNÜŞTÜRME (herkese açık, kimlik gerekmez): dosya url'sindeki /uploads/ kısmını /img/ yap ve parametre ekle:
https://cdn.starkbilisim.com/img/user_1/project_7/<ad>.jpg?w=800&format=webp
- w, h: 1–10000; bir sonraki standart boyuta yukarı yuvarlanır (16 … 800, 960, 1024, 1200, 1280, 1440, 1600, 1920, 2048, 2560; en fazla 2560). Asla büyütülmez. İkisi birlikte verilirse istenen en-boy oranı korunur.
- fit: cover (varsayılan, ortadan kırpar) | contain (kutuya sığdırır, şeffaf/JPEG'de beyaz doldurur) | inside (kutuya sığdırır, doldurmaz)
- format: auto | webp | avif | jpg | png. Verilmezse orijinal format (GIF → PNG, ilk kare). auto: tarayıcının Accept başlığına göre AVIF/WebP'ye 302 yönlendirir; açık format daha verimlidir. AVIF yoksa WebP verilir.
- q: 1–100 (40/60/75/85/95'e yuvarlanır; varsayılan JPEG 85, WebP 75, AVIF 60; PNG'de yok sayılır)
- Yalnızca jpg/png/gif/webp/avif kaynaklar dönüştürülür; svg/ico ve işlenemeyen görseller orijinale yönlendirilir; başka uzantılı yollar 400. Parametresiz /img/ adresi /uploads/ adresine 301 yönlendirir. Dosya yok/silinmiş → 404, hatalı parametre → 400.
- Yanıtlar 1 gün önbelleklenir. Kaynak başına en fazla 12 varyant; sınır veya sunucu yoğunluğunda orijinal dosyaya yönlendirilir: istemci yönlendirmeleri izlemeli ve dönen boyuta güvenmemeli; gösterim boyutunu CSS/width-height ile ver. Duyarlı görseller için srcset'te 480w/800w/1600w gibi listedeki standart genişlikleri kullan.
DOSYA TÜRLERİ (dosya başına en fazla 100 MB; tam liste GET ?action=limits):
- image: jpg, png, gif, webp, avif, svg, ico, tif, bmp, heic, heif
- video: mp4, webm, mov, avi, mkv, mpg, wmv
- audio: mp3, wav, ogg, m4a, flac, aac, aiff, mid, wma
- document: pdf, txt, csv, json, md, xml, rtf, doc, docx, xls, xlsx, ppt, pptx, odt, ods, odp, pages, numbers, key, epub
- font: woff, woff2, ttf, otf, eot
- archive: zip, rar, 7z, tar, gz, tgz, bz2, xz
- design: ai, eps, psd, indd, xd, sketch, fig, cdr, afdesign, afphoto
- 3d: glb, gltf, obj, stl, fbx, usdz
- raw: dng, cr2, cr3, nef, arw, raf, orf, rw2
Tür dosya içeriğinden tespit edilir; kayıt uzantısı tespit edilen türden gelir (ör. .jpeg → .jpg). Uzantısı değiştirilmiş veya içeriği tutmayan dosyalar reddedilir. HTML, JavaScript, PHP ve çalıştırılabilir dosyalar hiçbir uzantıyla kabul edilmez. SVG'ler temizlenir (script vb. kaldırılır). Görsel/video/ses/font ve PDF tarayıcıda açılır; diğer her şey indirme (Content-Disposition: attachment) olarak sunulur.
Yüklemede boyutlandırma (width/height/fit) yalnızca JPG/PNG/GIF/WebP için uygulanır (en fazla 4000 px, orijinalin yerine kaydedilir); diğer türlerde yok sayılır. Raster görseller en fazla 64 megapiksel (8000×8000) olabilir.
Tek upload isteğiyle en fazla single_request_max_bytes (şu an 100 MB) gönderilebilir; bundan büyük dosyalarda ve kesintili bağlantılarda parçalı yüklemeyi kullan.
URL'DEN YÜKLEME: yalnızca http/https; özel/iç ağ adresleri reddedilir; en fazla 5 yönlendirme; TLS sertifikası doğrulanır; 120 sn zaman aşımı; 100 MB sınırı.
SAĞLIK KONTROLÜ: GET https://cdn.starkbilisim.com/api/health.php (kimlik gerekmez, IP başına 60 istek/dk) → 200 {"status":"ok"|"degraded","checks":{database,uploads,disk,php},"version","environment","time"}; veritabanına ulaşılamazsa 503 {"status":"down",...}.
MCP (AI istemcileri için): https://cdn.starkbilisim.com/mcp (Streamable HTTP, durumsuz JSON-RPC, yalnızca POST). Kimlik: Authorization: Bearer <API_ANAHTARI>, X-API-Key veya ?key=. Araçlar: list_projects, create_project, list_files, get_file, upload_from_url, upload_file (base64, en fazla 20 MB), delete_file (trashed/restore_until döner), get_stats, get_upload_limits. Yükleme araçlarında dedupe varsayılan olarak açıktır (dedupe: false ile kapatılır).
HATA KODLARI: 400 geçersiz parametre/tür/boyut veya /img/ parametresi, 401 anahtar eksik/geçersiz, 403 yetkisiz/hesap engelli/kayıt kapalı, 404 proje/dosya bulunamadı (silinen dosyalar dahil), 405 yanlış HTTP metodu, 409 parçalı yükleme eksik/çakışma, 413 gövde çok büyük (parçalı yüklemeyi kullan), 429 çok fazla istek veya açık yükleme, 500/503 sunucu hatası.
POSTDosya yükle#
/api/api.php?action=upload
API anahtarı veya JWT
Tek bir dosyayı multipart/form-data olarak yükler. Tür, dosya adına değil içeriğine bakılarak tespit edilir. Tek istekte taşınamayacak kadar büyük dosyalar için parçalı yüklemeyi kullanın.
| Parametre | Tür | Açıklama |
|---|---|---|
project_idzorunlu |
int |
Dosyanın yükleneceği proje. |
filezorunlu |
file |
Yüklenecek dosya. Eski istemciler için image alan adı da kabul edilir (ikisi birden gönderilirse image kullanılır). |
widthisteğe bağlı |
int |
Hedef genişlik (px, en fazla 4000). Yalnızca JPG/PNG/GIF/WebP için uygulanır; diğer türlerde yok sayılır. |
heightisteğe bağlı |
int |
Hedef yükseklik (px, en fazla 4000). Yalnızca biri verilirse diğeri en-boy oranına göre hesaplanır. |
fitisteğe bağlı |
string |
cover (varsayılan): kırparak doldurur · contain: kutuya sığdırır, boş alanı siyahla doldurur. |
dedupeisteğe bağlı |
bool |
1 verilirse ve aynı projede birebir aynı dosya zaten varsa yeni kopya saklanmaz; mevcut dosya "duplicate": true alanıyla döner. Form alanı veya sorgu parametresi olarak gönderilebilir. Ayrıntılar |
curl -X POST "https://cdn.starkbilisim.com/api/api.php?action=upload" \
-H "X-API-Key: API_ANAHTARINIZ" \
-F "project_id=7" \
-F "file=@kapak.jpg" \
-F "width=1200"
// Node.js 18+
import { readFile } from 'node:fs/promises';
const form = new FormData();
form.append('project_id', '7');
form.append('file', new Blob([await readFile('kapak.jpg')]), 'kapak.jpg');
form.append('width', '1200'); // isteğe bağlı, yalnızca JPG/PNG/GIF/WebP
const res = await fetch('https://cdn.starkbilisim.com/api/api.php?action=upload', {
method: 'POST',
headers: { 'X-API-Key': 'API_ANAHTARINIZ' },
body: form,
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.error}`);
console.log(data.image.url);
<?php
$ch = curl_init('https://cdn.starkbilisim.com/api/api.php?action=upload');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: API_ANAHTARINIZ'],
CURLOPT_POSTFIELDS => [
'project_id' => 7,
'file' => new CURLFile(__DIR__ . '/kapak.jpg'),
'width' => 1200,
],
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status !== 201) {
throw new RuntimeException($data['error'] ?? 'Yükleme başarısız');
}
echo $data['image']['url'];
import requests
with open('kapak.jpg', 'rb') as f:
r = requests.post(
'https://cdn.starkbilisim.com/api/api.php',
params={'action': 'upload'},
headers={'X-API-Key': 'API_ANAHTARINIZ'},
data={'project_id': 7, 'width': 1200},
files={'file': f},
timeout=300,
)
data = r.json()
if r.status_code != 201:
raise RuntimeError(data.get('error'))
print(data['image']['url'])
{
"success": true,
"image": {
"id": 42,
"project_id": 7,
"original_name": "kapak.jpg",
"url": "https://cdn.starkbilisim.com/uploads/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg",
"file_size": 245760,
"mime_type": "image/jpeg",
"category": "image",
"width": 1200,
"height": 675,
"created_at": "2026-11-02 12:30:00"
}
}
Tekrar önleme (dedupe=1) Yeni
upload, url_upload ve upload_init isteklerine dedupe=1 eklerseniz, aynı projede birebir aynı dosya varsa yeni kopya saklanmaz ve mevcut dosya döner. Yanıt yine 201 ve aynı image nesnesidir; yalnızca "duplicate": true alanı eklenir (yeni dosyada bu alan hiç yoktur). Parametre verilmezse davranış değişmez: her yükleme yeni bir dosyadır.
- Eşleşme, saklanan son içeriğin SHA-256 özetine göre yapılır. Görseller yeniden kodlandığı için aynı kaynak dosya aynı
width/height/fitile yüklenirse eşleşir; farklı boyutlandırma yeni dosya oluşturur. - Yalnızca aynı projedeki, silinmemiş dosyalarla karşılaştırılır; çöp kutusundaki dosyalar eşleşmez.
- Sunucuda özet kolonu henüz yoksa (bekleyen veritabanı güncellemesi)
dedupesessizce yok sayılır ve dosya normal şekilde kaydedilir.
curl -X POST "https://cdn.starkbilisim.com/api/api.php?action=upload" \
-H "X-API-Key: API_ANAHTARINIZ" \
-F "project_id=7" \
-F "dedupe=1" \
-F "file=@kapak.jpg"
{
"success": true,
"image": {
"id": 42,
"project_id": 7,
"original_name": "kapak.jpg",
"url": "https://cdn.starkbilisim.com/uploads/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg",
"file_size": 245760,
"mime_type": "image/jpeg",
"category": "image",
"width": 1200,
"height": 675,
"created_at": "2026-11-02 12:30:00",
"duplicate": true
}
}
| Durum | Örnek mesaj | Neden |
|---|---|---|
400 | project_id is required | Proje belirtilmemiş |
400 | No valid image file provided. Use "image" field name. | file / image alanı yok veya bozuk |
400 | Invalid file type. Allowed: image (JPG, PNG, GIF, WEBP, ...), video (...), … - full list: GET api.php?action=limits | Desteklenmeyen tür veya içeriği uzantısıyla uyuşmayan dosya. Mesaj kategori özetidir; tam liste için limits |
400 | Bu dosya türü için yönetici panelinden bekleyen migration'ı çalıştırın (file type not enabled yet: database migration pending). | DOCX/XLSX/PPTX: sunucuda veritabanı güncellemesi henüz yapılmamış |
400 | File exceeds 100MB limit | Dosya 100 MB’tan büyük |
400 | Image dimensions too large (max 8000x8000) | 64 megapikseli aşan raster görsel |
404 | Project not found | Proje yok veya size ait değil |
413 | Request body exceeds the server limit. Use chunked upload … | Gövde tek istek için çok büyük → parçalı yükleme |
Parçalı yüklemeYeni#
Büyük dosyaları sabit boyutlu parçalar hâlinde gönderin. Kopan bir parça yeniden gönderilebilir; tüm parçalar gelince sunucu dosyayı birleştirir ve normal yüklemeyle aynı doğrulamalardan geçirir. Tek upload isteğinin taşıyabileceği boyut single_request_max_bytes ile sınırlıdır (şu an 100 MB); bu değerden büyük dosyalarda zorunludur, yavaş veya kesintili bağlantılarda büyük dosyalar için de önerilir.
-
Adım 1
upload_init
Dosya adı ve boyutunu bildirin; upload_id ve chunk_size alın.
-
Adım 2
upload_chunk
0’dan başlayan index ile her parçayı gönderin.
-
Adım 3
upload_complete
Parçaları birleştirin; dosya kaydedilir.
-
İsteğe bağlı
upload_abort
Vazgeçerseniz geçici parçaları silin.
1. Yüklemeyi başlat
/api/api.php?action=upload_init
API anahtarı veya JWT
Gövde JSON’dur. Dosya adının uzantısı izinli türlerden biri ya da bir takma adı olmalıdır (ör. .jpeg, .jfif → jpg; .m4v → mp4; .tiff → tif; tam liste extension_aliases). Asıl tür tespiti tamamlama adımında içerikten yapılır.
| Parametre | Tür | Açıklama |
|---|---|---|
project_idzorunlu |
int |
Hedef proje. |
filenamezorunlu |
string |
Orijinal dosya adı, uzantısıyla birlikte (ör. tanitim.mp4). |
sizezorunlu |
int |
Dosyanın toplam boyutu (bayt). En fazla 104857600 (100 MB). |
width / height / fitisteğe bağlı |
int / int / string |
Tamamlandığında uygulanacak boyutlandırma; upload ile aynı kurallar. |
dedupeisteğe bağlı |
bool |
true / 1: tamamlandığında aynı projede birebir aynı dosya varsa kopya saklanmaz; upload_complete mevcut dosyayı "duplicate": true ile döndürür. Ayrıntılar |
{
"success": true,
"upload_id": "9f2c4e0a7b1d4c3e8a6f5b2d1c0e9f8a",
"chunk_size": 8388608,
"total_chunks": 9,
"max_bytes": 104857600,
"expires_at": "2026-11-03 12:30:00"
}
chunk_size değerini kullanın (genellikle 8 MB; sunucu ayarlarına göre daha küçük olabilir, en az 1 MB). expires_at zamanına kadar tamamlanmayan yüklemeler silinir (24 saat). Aynı anda en fazla 10 açık yükleme olabilir; fazlası 429 döner.2. Parçaları gönder
/api/api.php?action=upload_chunk&upload_id={id}&index={n}
API anahtarı veya JWT
Parçayı iki şekilde gönderebilirsiniz: ham gövde (Content-Type: application/octet-stream, önerilen) veya multipart/form-data içinde chunk dosya alanı. Ham gövdede API anahtarını header ya da sorgu parametresiyle gönderin.
| Parametre | Tür | Açıklama |
|---|---|---|
upload_idzorunlu |
string |
upload_init yanıtındaki kimlik (sorgu veya form alanı). |
indexzorunlu |
int |
Parça sırası, 0 ile total_chunks - 1 arası (sorgu veya form alanı). |
chunkisteğe bağlı |
file |
Yalnızca multipart gönderimde: parça verisi. Ham gövdede gerekmez. |
chunk_size bayt olmalıdır; son parça kalan baytlardır. Farklı boyuttaki parça 400 (Chunk 3 must be exactly 8388608 bytes …) ile reddedilir. Aynı index’i yeniden göndermek öncekinin üzerine yazar; ağ hatasında parçayı güvenle tekrar deneyebilirsiniz.{
"success": true,
"upload_id": "9f2c4e0a7b1d4c3e8a6f5b2d1c0e9f8a",
"index": 0,
"received": 1,
"total_chunks": 9
}
3. Yüklemeyi tamamla
/api/api.php?action=upload_complete&upload_id={id}
API anahtarı veya JWT
upload_id sorgu parametresiyle ya da JSON gövdede ({"upload_id": "…"}) gönderilir. Başarılı yanıt upload ile aynı image nesnesidir. Eksik parça varsa 409 (Upload incomplete: missing chunks 3,4) döner; eksikleri gönderip tekrar çağırın. Tür doğrulaması başarısız olursa geçici dosyalar silinir.
{
"success": true,
"image": {
"id": 131,
"project_id": 7,
"original_name": "tanitim.mp4",
"url": "https://cdn.starkbilisim.com/uploads/user_1/project_7/b81e0c5a9d2f4e7c8a1b3c5d7e9f0a12.mp4",
"file_size": 73400320,
"mime_type": "video/mp4",
"category": "video",
"width": null,
"height": null,
"created_at": "2026-11-02 12:34:10"
}
}
İptal et
/api/api.php?action=upload_abort&upload_id={id}
POST da kabul edilir
Açık bir yüklemeyi ve geçici parçalarını siler. upload_id sorguda ya da JSON gövdede gönderilebilir. Yanıt: {"success": true, "message": "Upload aborted"}.
Tam örnek
#!/usr/bin/env bash
# Gerekli: curl, jq, GNU coreutils (split, stat)
set -euo pipefail
KEY="API_ANAHTARINIZ"
API="https://cdn.starkbilisim.com/api/api.php"
FILE="tanitim.mp4"
SIZE=$(stat -c%s "$FILE") # macOS: stat -f%z "$FILE"
# 1) Başlat
INIT=$(curl -sf -X POST "$API?action=upload_init" \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d "{\"project_id\":7,\"filename\":\"$FILE\",\"size\":$SIZE}")
UPLOAD_ID=$(echo "$INIT" | jq -r .upload_id)
CHUNK=$(echo "$INIT" | jq -r .chunk_size)
# 2) chunk_size'lık parçalara böl ve sırayla gönder
split -b "$CHUNK" -d -a 4 "$FILE" part_
i=0
for p in part_*; do
curl -sf -X POST "$API?action=upload_chunk&upload_id=$UPLOAD_ID&index=$i" \
-H "X-API-Key: $KEY" -H "Content-Type: application/octet-stream" \
--data-binary "@$p" > /dev/null
i=$((i + 1))
done
rm -f part_*
# 3) Tamamla
curl -s -X POST "$API?action=upload_complete&upload_id=$UPLOAD_ID" \
-H "X-API-Key: $KEY" | jq -r .image.url
// Node.js 18+
import { open, stat } from 'node:fs/promises';
import { basename } from 'node:path';
const API = 'https://cdn.starkbilisim.com/api/api.php';
const KEY = 'API_ANAHTARINIZ';
async function call(action, { query = {}, headers = {}, ...init } = {}) {
const qs = new URLSearchParams({ action, ...query });
const res = await fetch(`${API}?${qs}`, {
method: 'POST',
...init,
headers: { 'X-API-Key': KEY, ...headers },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.error}`);
return data;
}
async function uploadLarge(path, projectId) {
const { size } = await stat(path);
// 1) Başlat
const init = await call('upload_init', {
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ project_id: projectId, filename: basename(path), size }),
});
// 2) Parçaları sırayla gönder
const fh = await open(path, 'r');
try {
for (let index = 0; index < init.total_chunks; index++) {
const offset = index * init.chunk_size;
const length = Math.min(init.chunk_size, size - offset);
const buf = Buffer.alloc(length);
await fh.read(buf, 0, length, offset);
await call('upload_chunk', {
query: { upload_id: init.upload_id, index },
headers: { 'Content-Type': 'application/octet-stream' },
body: buf,
});
}
} catch (err) {
await call('upload_abort', { query: { upload_id: init.upload_id } }).catch(() => {});
throw err;
} finally {
await fh.close();
}
// 3) Tamamla
const done = await call('upload_complete', { query: { upload_id: init.upload_id } });
return done.image;
}
const image = await uploadLarge('./tanitim.mp4', 7);
console.log(image.url);
<?php
const API = 'https://cdn.starkbilisim.com/api/api.php';
const KEY = 'API_ANAHTARINIZ';
function cdn(string $action, array $query = [], string $body = '', string $type = 'application/json'): array
{
$ch = curl_init(API . '?' . http_build_query(['action' => $action] + $query));
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . KEY, 'Content-Type: ' . $type],
CURLOPT_POSTFIELDS => $body,
]);
$data = json_decode((string) curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400 || !is_array($data)) {
throw new RuntimeException($data['error'] ?? 'İstek başarısız');
}
return $data;
}
$path = __DIR__ . '/tanitim.mp4';
// 1) Başlat
$init = cdn('upload_init', [], json_encode([
'project_id' => 7,
'filename' => basename($path),
'size' => filesize($path),
]));
// 2) Parçaları sırayla gönder
$fp = fopen($path, 'rb');
try {
for ($i = 0; $i < $init['total_chunks']; $i++) {
$chunk = stream_get_contents($fp, $init['chunk_size']);
cdn('upload_chunk', ['upload_id' => $init['upload_id'], 'index' => $i], $chunk, 'application/octet-stream');
}
} catch (Throwable $e) {
cdn('upload_abort', ['upload_id' => $init['upload_id']]);
throw $e;
} finally {
fclose($fp);
}
// 3) Tamamla
$done = cdn('upload_complete', ['upload_id' => $init['upload_id']]);
echo $done['image']['url'];
import os
import requests
API = 'https://cdn.starkbilisim.com/api/api.php'
KEY = 'API_ANAHTARINIZ'
def call(action, params=None, headers=None, **kwargs):
r = requests.post(
API,
params={'action': action, **(params or {})},
headers={'X-API-Key': KEY, **(headers or {})},
timeout=300,
**kwargs,
)
data = r.json()
if r.status_code >= 400:
raise RuntimeError(f"{r.status_code}: {data.get('error')}")
return data
path = 'tanitim.mp4'
# 1) Başlat
init = call('upload_init', json={
'project_id': 7,
'filename': os.path.basename(path),
'size': os.path.getsize(path),
})
# 2) Parçaları sırayla gönder
try:
with open(path, 'rb') as f:
for index in range(init['total_chunks']):
call('upload_chunk',
params={'upload_id': init['upload_id'], 'index': index},
headers={'Content-Type': 'application/octet-stream'},
data=f.read(init['chunk_size']))
except Exception:
call('upload_abort', params={'upload_id': init['upload_id']})
raise
# 3) Tamamla
done = call('upload_complete', params={'upload_id': init['upload_id']})
print(done['image']['url'])
POSTURL’den yükle#
/api/api.php?action=url_upload
API anahtarı veya JWT
Herkese açık bir http(s) adresindeki dosyayı sunucu indirir ve projenize kaydeder. Gövde JSON’dur; bu yüzden API anahtarını header veya sorgu parametresiyle gönderin. Dosya adı URL yolundan alınır; uzantısı yoksa tespit edilen türün uzantısı eklenir.
| Parametre | Tür | Açıklama |
|---|---|---|
urlzorunlu |
string |
İndirilecek dosyanın adresi. Yalnızca http/https, en fazla 2048 karakter. |
project_idzorunlu |
int |
Hedef proje. |
width / heightisteğe bağlı |
int |
Yalnızca JPG/PNG/GIF/WebP için boyutlandırma (en fazla 4000 px). |
fitisteğe bağlı |
string |
cover (varsayılan) veya contain. |
dedupeisteğe bağlı |
bool |
true / 1: aynı projede birebir aynı dosya varsa kopya saklanmaz; mevcut dosya "duplicate": true ile döner. Ayrıntılar |
Güvenlik ve sınırlar
- Özel, iç ağ ve rezerve adresler (localhost, 10.x, 192.168.x, 169.254.x…) reddedilir; kontrol her yönlendirmede tekrarlanır.
- En fazla 5 yönlendirme izlenir.
- TLS sertifikası doğrulanır; geçersiz sertifikalı adresler indirilemez.
- En fazla 100 MB; toplam süre 120 saniye.
curl -X POST "https://cdn.starkbilisim.com/api/api.php?action=url_upload" \
-H "X-API-Key: API_ANAHTARINIZ" \
-H "Content-Type: application/json" \
-d '{"url":"https://ornek.com/foto.jpg","project_id":7,"width":800,"fit":"cover","dedupe":true}'
const res = await fetch('https://cdn.starkbilisim.com/api/api.php?action=url_upload', {
method: 'POST',
headers: {
'X-API-Key': 'API_ANAHTARINIZ',
'Content-Type': 'application/json',
},
body: JSON.stringify({
url: 'https://ornek.com/foto.jpg',
project_id: 7,
width: 800,
fit: 'cover',
dedupe: true, // aynı dosya varsa kopya saklama
}),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.image.url);
<?php
$ch = curl_init('https://cdn.starkbilisim.com/api/api.php?action=url_upload');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: API_ANAHTARINIZ', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://ornek.com/foto.jpg',
'project_id' => 7,
'width' => 800,
]),
]);
$data = json_decode(curl_exec($ch), true);
echo $data['image']['url'] ?? $data['error'];
import requests
r = requests.post(
'https://cdn.starkbilisim.com/api/api.php',
params={'action': 'url_upload'},
headers={'X-API-Key': 'API_ANAHTARINIZ'},
json={'url': 'https://ornek.com/foto.jpg', 'project_id': 7, 'width': 800, 'dedupe': True},
timeout=180,
)
r.raise_for_status()
print(r.json()['image']['url'])
{
"success": true,
"image": {
"id": 43,
"project_id": 7,
"original_name": "foto.jpg",
"url": "https://cdn.starkbilisim.com/uploads/user_1/project_7/c04d7e2f9a1b4c8d9e0f1a2b3c4d5e6f.jpg",
"source_url": "https://ornek.com/foto.jpg",
"file_size": 153600,
"mime_type": "image/jpeg",
"category": "image",
"width": 800,
"height": 533,
"created_at": "2026-11-02 12:31:00"
}
}
Olası hatalar (400): URL points to a private or reserved address, Too many redirects, Download timed out, Remote file exceeds 100MB limit, Failed to download file from URL….
GETDosyaları listele#
/api/api.php?action=list&project_id={id}
API anahtarı veya JWT
Bir projenin dosyalarını sayfalı döndürür; çöp kutusundaki dosyalar listelenmez. Her öğede dosyanın türünü gösteren category alanı bulunur: image, video, audio, document, font, archive, design, 3d, raw veya other.
| Parametre | Tür | Açıklama |
|---|---|---|
project_idzorunlu |
int |
Proje kimliği. |
pageisteğe bağlı |
int |
Sayfa numarası (varsayılan 1). |
limitisteğe bağlı |
int |
Sayfa başına öğe (varsayılan 50, en fazla 100). |
sortisteğe bağlı |
string |
newest (varsayılan) · oldest · name_asc · name_desc |
curl "https://cdn.starkbilisim.com/api/api.php?action=list&project_id=7&page=1&limit=20&sort=newest" \
-H "X-API-Key: API_ANAHTARINIZ"
const qs = new URLSearchParams({ action: 'list', project_id: 7, page: 1, limit: 20, sort: 'newest' });
const res = await fetch(`https://cdn.starkbilisim.com/api/api.php?${qs}`, {
headers: { 'X-API-Key': 'API_ANAHTARINIZ' },
});
const { images, total, page, totalPages } = await res.json();
const videos = images.filter((f) => f.category === 'video');
<?php
$query = http_build_query(['action' => 'list', 'project_id' => 7, 'page' => 1, 'limit' => 20]);
$ch = curl_init('https://cdn.starkbilisim.com/api/api.php?' . $query);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: API_ANAHTARINIZ'],
]);
$data = json_decode(curl_exec($ch), true);
foreach ($data['images'] as $file) {
echo $file['category'], ' ', $file['url'], PHP_EOL;
}
import requests
r = requests.get(
'https://cdn.starkbilisim.com/api/api.php',
params={'action': 'list', 'project_id': 7, 'page': 1, 'limit': 20, 'sort': 'newest'},
headers={'X-API-Key': 'API_ANAHTARINIZ'},
timeout=30,
)
for f in r.json()['images']:
print(f['category'], f['url'])
{
"images": [
{
"id": 131,
"original_name": "tanitim.mp4",
"url": "https://cdn.starkbilisim.com/uploads/user_1/project_7/b81e0c5a9d2f4e7c8a1b3c5d7e9f0a12.mp4",
"file_size": 73400320,
"mime_type": "video/mp4",
"category": "video",
"width": null,
"height": null,
"created_at": "2026-11-02 12:34:10"
},
{
"id": 42,
"original_name": "kapak.jpg",
"url": "https://cdn.starkbilisim.com/uploads/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg",
"file_size": 245760,
"mime_type": "image/jpeg",
"category": "image",
"width": 1200,
"height": 675,
"created_at": "2026-11-02 12:30:00"
}
],
"total": 2,
"page": 1,
"totalPages": 1
}
DELETEDosya sil#
/api/api.php?action=delete&id={id}
API anahtarı veya JWT
Dosyayı hemen yayından kaldırır: /uploads/… adresi ve tüm /img/… varyantları anında 404 döner, dosya listelerde ve istatistiklerde görünmez. Dosya yoksa, size ait değilse veya zaten silinmişse 404 (Image not found) döner.
| Parametre | Tür | Açıklama |
|---|---|---|
idzorunlu |
int |
Silinecek dosyanın kimliği. |
"trashed": true ile "restore_until" (UTC, YYYY-MM-DD HH:MM:SS) eklenir. Dosya bu tarihe kadar (30 gün) panelin Çöp kutusu sayfasından aynı URL ile geri yüklenebilir; süre dolunca kalıcı olarak silinir. Geri yükleme yalnızca panelden yapılır, dosya API’sinde karşılığı yoktur. Çöp kutusu etkin değilse (alanlar yanıtta yoksa) silme kalıcıdır.curl -X DELETE "https://cdn.starkbilisim.com/api/api.php?action=delete&id=42" \
-H "X-API-Key: API_ANAHTARINIZ"
const res = await fetch('https://cdn.starkbilisim.com/api/api.php?action=delete&id=42', {
method: 'DELETE',
headers: { 'X-API-Key': 'API_ANAHTARINIZ' },
});
const data = await res.json(); // { success: true, message: 'Image deleted', trashed: true, restore_until: '…' }
if (data.trashed) console.log(`Çöp kutusunda, ${data.restore_until} (UTC) tarihine kadar geri yüklenebilir`);
<?php
$ch = curl_init('https://cdn.starkbilisim.com/api/api.php?action=delete&id=42');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: API_ANAHTARINIZ'],
]);
$data = json_decode(curl_exec($ch), true);
import requests
r = requests.delete(
'https://cdn.starkbilisim.com/api/api.php',
params={'action': 'delete', 'id': 42},
headers={'X-API-Key': 'API_ANAHTARINIZ'},
timeout=30,
)
print(r.json())
{
"success": true,
"message": "Image deleted",
"trashed": true,
"restore_until": "2026-12-02 12:45:00"
}
GETDosya sunumu ve boyutlandırma#
/api/api.php?action=serve&id={id}&w=&h=&fit=
API anahtarı veya JWT
Dosyanın kendisini (JSON değil) döndürür. JPG/PNG/GIF/WebP görseller istenen boyuta küçültülür ve sonuç diskte önbelleğe alınır. Diğer tüm türler her zaman olduğu gibi, doğru Content-Type ile döner; SVG’ler sandbox CSP başlığıyla sunulur. Görsel, video, ses, font ve PDF dışındaki her şey (metin, ofis, tasarım, 3D, RAW, arşiv…) indirme (Content-Disposition: attachment) olarak gelir.
| Parametre | Tür | Açıklama |
|---|---|---|
idzorunlu |
int |
Dosya kimliği. |
wisteğe bağlı |
int |
Genişlik (px, en fazla 4000). |
histeğe bağlı |
int |
Yükseklik (px, en fazla 4000). Yalnızca biri verilirse diğeri orana göre hesaplanır. |
fitisteğe bağlı |
string |
cover (varsayılan) veya contain. |
wvehverilmezse orijinal dosya döner.- Orijinalden büyük boyut istenirse orijinal döner (büyütme yapılmaz).
- Boyutlandırılmış kopyalar diskte önbelleğe alınır; yanıtlar 24 saat önbelleğe alınabilir.
serve kimlik doğrulama ister. API anahtarını <img src="…&api_key=…"> gibi herkese açık HTML’e koymayın. Sitelerde her zaman yükleme yanıtındaki herkese açık url alanını kullanın; farklı bir boyut gerekiyorsa kimlik gerektirmeyen görsel dönüştürme adresini (/img/…?w=) kullanın.curl "https://cdn.starkbilisim.com/api/api.php?action=serve&id=42&w=300&h=300&fit=cover" \
-H "X-API-Key: API_ANAHTARINIZ" \
-o kucuk-resim.jpg
import { writeFile } from 'node:fs/promises';
const res = await fetch('https://cdn.starkbilisim.com/api/api.php?action=serve&id=42&w=300', {
headers: { 'X-API-Key': 'API_ANAHTARINIZ' },
});
if (!res.ok) throw new Error((await res.json()).error);
await writeFile('kucuk-resim.jpg', Buffer.from(await res.arrayBuffer()));
<?php
$ch = curl_init('https://cdn.starkbilisim.com/api/api.php?action=serve&id=42&w=300');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: API_ANAHTARINIZ'],
]);
file_put_contents(__DIR__ . '/kucuk-resim.jpg', curl_exec($ch));
import requests
r = requests.get(
'https://cdn.starkbilisim.com/api/api.php',
params={'action': 'serve', 'id': 42, 'w': 300, 'fit': 'cover'},
headers={'X-API-Key': 'API_ANAHTARINIZ'},
timeout=60,
)
r.raise_for_status()
with open('kucuk-resim.jpg', 'wb') as f:
f.write(r.content)
GETGörsel dönüştürmeYeni#
/img/{dosya_yolu}?w=&h=&fit=&format=&q=
Kimlik gerekmez
Yüklediğiniz raster görselleri (JPG, PNG, GIF, WebP; sunucu destekliyorsa AVIF) URL parametreleriyle anında boyutlandırıp başka bir formatta alın. Dosya URL’sindeki /uploads/ kısmını /img/ ile değiştirmeniz yeterli; yolun geri kalanı aynıdır. Kimlik doğrulama gerekmez, adresi doğrudan <img src> içinde kullanabilirsiniz. Orijinal dosya değişmez.
Orijinalhttps://cdn.starkbilisim.com/uploads/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg
Dönüşümhttps://cdn.starkbilisim.com/img/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg?w=800&format=webp
| Parametre | Tür | Açıklama |
|---|---|---|
w, histeğe bağlı |
int |
Genişlik / yükseklik, 1–10000. Bir sonraki standart boyuta yukarı yuvarlanır: 16, 32, 48, 64, 96, 128, 160, 192, 256, 320, 384, 480, 512, 640, 768, 800, 960, 1024, 1200, 1280, 1440, 1600, 1920, 2048, 2560 (en fazla 2560). Görsel asla orijinalinden büyütülmez. Yalnızca biri verilirse diğeri en-boy oranına göre hesaplanır; ikisi birlikte verilirse w yuvarlanır ve istenen oran korunur. |
fitisteğe bağlı |
string |
Yalnızca w ve h birlikte verildiğinde etkilidir. cover (varsayılan): kutuyu doldurur, ortadan kırpar · contain: kutuya sığdırır, boş kenarları şeffaf (JPEG’de beyaz) doldurur · inside: kutuya sığdırır, doldurma yapmaz (çıktı kutudan küçük olabilir). |
formatisteğe bağlı |
string |
auto · webp · avif · jpg (jpeg) · png. Verilmezse orijinal format korunur (GIF → PNG, yalnızca ilk kare). auto: tarayıcının Accept başlığına göre AVIF, sonra WebP, desteklenmiyorsa orijinal format. Sunucuda AVIF kodlayıcı yoksa avif isteğine WebP döner. |
qisteğe bağlı |
int |
Kalite, 1–100; en yakın 40 / 60 / 75 / 85 / 95 değerine yuvarlanır. Varsayılan: JPEG 85, WebP 75, AVIF 60. PNG’de yok sayılır. |
| Sorgu | Sonuç |
|---|---|
| ?w=480 | 480 px genişlik, orijinal format, oran korunur (?w=400 da 480’e yuvarlanır) |
| ?w=1200&format=webp&q=85 | 1200 px WebP, yüksek kalite |
| ?w=640&h=640&fit=cover&format=avif | 640 × 640 kare, ortadan kırpılmış AVIF |
| ?w=320&h=320&fit=contain&format=png | 320 × 320 şeffaf kenarlı PNG (logo, ürün görseli) |
| ?format=webp | Boyut aynı, yalnızca format dönüşümü |
Davranış
- Önbellek: dönüştürülen görsel bir kez üretilir, sunucuda saklanır ve
Cache-Control: public, max-age=86400(1 gün),ETagveLast-Modifiedbaşlıklarıyla sunulur.X-Transform-Cache: HIT|MISSbaşlığı sunucu önbelleğini gösterir. İlk istek görselin büyüklüğüne göre biraz daha yavaştır. format=auto: açık formatlı adrese302ile yönlendirir (ör.?w=800&format=auto→?w=800&format=avif). Bu her istekte küçük bir ek gidiş-dönüş demektir; formatı biliyorsanızformat=webpgibi açık değer verin.- Yönlendirmeler: parametresiz
/img/…adresi301ile/uploads/…adresine gider. SVG ve ICO dosyaları, 64 megapikselden büyük veya sunucunun işleyemediği görseller ve hiçbir değişiklik gerektirmeyen istekler (ör. orijinalden büyükw, aynı format)302ile orijinal dosyaya yönlendirilir. - Sınırlar: her kaynak görsel için en fazla 12 farklı varyant saklanır; sınır dolduğunda yeni varyant için son 7 günde kullanılmamış en eski varyant silinir, yoksa orijinal dosyaya yönlendirilir. Sunucu yoğunken veya önbellek doluyken de orijinal döner. Bu yüzden istemciniz yönlendirmeleri izlemeli ve dönen görselin boyutuna ya da formatına güvenmemelidir;
Content-Typebaşlığına bakın. - İşleme: JPEG’lerin EXIF yönü uygulanır, EXIF/GPS gibi meta veriler silinir, PNG/WebP/AVIF çıktılarda şeffaflık korunur. Animasyonlu GIF’lerde yalnızca ilk kare kullanılır.
- Erişim: yanıtlar
Access-Control-Allow-Origin: *ile döner; görseller başka sitelerde<canvas>vefetchile de kullanılabilir. Bilinmeyen sorgu parametreleri yok sayılır. - Silinen dosyalar: dosya silindiğinde (çöp kutusuna taşındığında da) tüm varyantları kaldırılır ve
/img/adresi404döner.
w=700 → 768 px). Ekrandaki boyutu her zaman CSS veya width/height öznitelikleriyle belirleyin.# 800 px genişlikte WebP indir (-L: yönlendirmeleri izle)
curl -L -o kapak-800.webp \
"https://cdn.starkbilisim.com/img/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg?w=800&format=webp"
# 320×320 kare küçük resim (ortadan kırpılmış JPEG)
curl -L -o kare.jpg \
"https://cdn.starkbilisim.com/img/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg?w=320&h=320&fit=cover&format=jpg"
# Yalnızca yanıt başlıkları (Content-Type, Cache-Control, X-Transform-Cache)
curl -sI "https://cdn.starkbilisim.com/img/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg?w=480&format=avif"
// Yükleme yanıtındaki url'den dönüştürme adresi üretir
function cdnImg(url, params = {}) {
const u = new URL(url.replace('/uploads/', '/img/'));
for (const [key, value] of Object.entries(params)) u.searchParams.set(key, value);
return u.toString();
}
const url = 'https://cdn.starkbilisim.com/uploads/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg';
const img = document.createElement('img');
img.src = cdnImg(url, { w: 800, format: 'webp' });
img.srcset = [480, 800, 1600]
.map((w) => `${cdnImg(url, { w, format: 'webp' })} ${w}w`)
.join(', ');
img.sizes = '(max-width: 800px) 100vw, 800px';
img.alt = 'Kapak görseli';
<?php
/** /uploads/ adresinden /img/ dönüştürme adresi üretir. */
function cdn_img(string $url, array $params = []): string
{
$url = preg_replace('#/uploads/#', '/img/', $url, 1);
return $params ? $url . '?' . http_build_query($params) : $url;
}
$url = $image['url']; // yükleme veya list yanıtından
echo cdn_img($url, ['w' => 640, 'h' => 640, 'fit' => 'cover', 'format' => 'avif']);
// https://cdn.starkbilisim.com/img/user_1/project_7/3f9c….jpg?w=640&h=640&fit=cover&format=avif
$srcset = implode(', ', array_map(
fn (int $w) => cdn_img($url, ['w' => $w, 'format' => 'webp']) . " {$w}w",
[480, 800, 1600]
));
import requests
src = 'https://cdn.starkbilisim.com/uploads/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg'
url = src.replace('/uploads/', '/img/', 1)
# requests yönlendirmeleri kendiliğinden izler
r = requests.get(url, params={'w': 480, 'format': 'webp'}, timeout=60)
r.raise_for_status()
# Sınır/yoğunluk durumunda orijinal dosya dönebilir: türü başlıktan alın
print(r.headers['Content-Type'], r.headers.get('X-Transform-Cache'))
with open('kucuk.webp' if r.headers['Content-Type'] == 'image/webp' else 'kucuk.jpg', 'wb') as f:
f.write(r.content)
İpucu: duyarlı görseller
Tek bir orijinal yükleyip srcset ile birden fazla genişlik sunun; tarayıcı ekran genişliğine ve piksel yoğunluğuna uygun olanı seçer. Standart boyut listesindeki genişlikleri (ör. 320, 480, 640, 800, 1200, 1600) kullanın: listede olmayan bir değer (ör. 400) bir üst boyuta (480) yuvarlanır ve srcset’teki genişlik tanımı gerçeği yansıtmaz. Az sayıda sabit genişlik, varyant sınırına takılmamanızı da sağlar.
<img src="https://cdn.starkbilisim.com/img/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg?w=800&format=webp"
srcset="https://cdn.starkbilisim.com/img/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg?w=480&format=webp 480w,
https://cdn.starkbilisim.com/img/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg?w=800&format=webp 800w,
https://cdn.starkbilisim.com/img/user_1/project_7/3f9c2a1be0d84c55a1e7f04b9d6c2e18.jpg?w=1600&format=webp 1600w"
sizes="(max-width: 800px) 100vw, 800px"
width="800" height="450" loading="lazy" decoding="async" alt="Kapak görseli">
AVIF’i destekleyen tarayıcılara AVIF, diğerlerine WebP sunmak için <picture> içinde iki <source type="image/avif"> / type="image/webp" satırı kullanın; bu yöntemde format=auto’daki ek yönlendirme olmaz.
| Durum | Örnek mesaj | Neden |
|---|---|---|
400 | Invalid image path | Yol bir StarkCDN dosya yolu değil veya uzantısı jpg/jpeg/png/gif/webp/avif/svg/ico değil (video, PDF vb. dönüştürülemez) |
400 | Invalid w: must be an integer between 1 and 10000 | w, h veya q (1–100) aralık dışında ya da sayı değil |
400 | Invalid fit: use cover, contain or inside | Geçersiz fit |
400 | Invalid format: use auto, webp, avif, jpg or png | Geçersiz format |
404 | Image not found | Dosya yok veya silinmiş (çöp kutusundakiler dahil) |
GETLimitleri sorgulaYeni#
/api/api.php?action=limits
API anahtarı veya JWT
Sunucunun güncel yükleme limitlerini ve izinli türleri döndürür. İstemcinizde tür/boyut kontrolünü sabit kodlamak yerine bu uç noktayı kullanın. single_request_max_bytes tek bir upload isteğiyle gönderilebilecek en büyük dosyadır (sunucunun PHP ayarlarından hesaplanır); daha büyükleri parçalı yükleyin. extension_aliases, kabul edilen ve başka bir uzantıyla saklanan yazımları listeler (ör. jpeg → jpg, tiff → tif).
curl "https://cdn.starkbilisim.com/api/api.php?action=limits" \
-H "X-API-Key: API_ANAHTARINIZ"
const limits = await fetch('https://cdn.starkbilisim.com/api/api.php?action=limits', {
headers: { 'X-API-Key': 'API_ANAHTARINIZ' },
}).then((r) => r.json());
const useChunked = file.size > limits.single_request_max_bytes;
<?php
$ch = curl_init('https://cdn.starkbilisim.com/api/api.php?action=limits');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: API_ANAHTARINIZ'],
]);
$limits = json_decode(curl_exec($ch), true);
$izinli = in_array('webp', $limits['allowed_extensions'], true);
import requests
limits = requests.get(
'https://cdn.starkbilisim.com/api/api.php',
params={'action': 'limits'},
headers={'X-API-Key': 'API_ANAHTARINIZ'},
timeout=30,
).json()
print(limits['max_upload_formatted'], limits['allowed_extensions'])
{
"max_upload_bytes": 104857600,
"max_upload_formatted": "100.0 MB",
"chunk_size": 8388608,
"single_request_max_bytes": 104857600,
"max_files_per_upload": 20,
"max_image_pixels": 64000000,
"allowed_types": [
{ "mime": "image/jpeg", "extension": "jpg", "category": "image" },
{ "mime": "image/png", "extension": "png", "category": "image" },
{ "mime": "video/mp4", "extension": "mp4", "category": "video" },
{ "mime": "application/zip", "extension": "zip", "category": "archive" },
{ "mime": "image/vnd.adobe.photoshop", "extension": "psd", "category": "design" },
{ "mime": "model/gltf-binary", "extension": "glb", "category": "3d" },
{ "mime": "image/x-canon-cr3", "extension": "cr3", "category": "raw" }
],
"allowed_extensions": ["jpg", "png", "gif", "webp", "avif", "svg", "ico", "mp4", "webm", "mov", "mp3", "wav", "ogg", "m4a", "pdf", "txt", "csv", "json", "woff", "woff2", "ttf", "otf", "zip", "tif", "bmp", "heic", "heif", "dng", "cr2", "cr3", "nef", "arw", "raf", "orf", "rw2", "ai", "eps", "psd", "indd", "xd", "sketch", "fig", "cdr", "afdesign", "afphoto", "glb", "gltf", "obj", "stl", "fbx", "usdz", "avi", "mkv", "mpg", "wmv", "flac", "aac", "aiff", "mid", "wma", "doc", "xls", "ppt", "docx", "xlsx", "pptx", "odt", "ods", "odp", "pages", "numbers", "key", "epub", "rtf", "md", "xml", "eot", "rar", "7z", "tar", "gz", "tgz", "bz2", "xz"],
"extension_aliases": {
"jpeg": "jpg", "jpe": "jpg", "jfif": "jpg", "m4v": "mp4", "oga": "ogg", "opus": "ogg",
"tiff": "tif", "mpeg": "mpg", "midi": "mid", "aif": "aiff", "aifc": "aiff"
}
}
GETProjeleri listele#
/api/api.php?action=projects
API anahtarı veya JWT
Tüm projelerinizi en yeniden eskiye döndürür; parametre almaz. Proje oluşturma, düzenleme ve silme panelden, projects.php (JWT) ile ya da MCP create_project aracıyla yapılır.
curl "https://cdn.starkbilisim.com/api/api.php?action=projects" \
-H "X-API-Key: API_ANAHTARINIZ"
const res = await fetch('https://cdn.starkbilisim.com/api/api.php?action=projects', {
headers: { 'X-API-Key': 'API_ANAHTARINIZ' },
});
const { projects } = await res.json();
<?php
$ch = curl_init('https://cdn.starkbilisim.com/api/api.php?action=projects');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: API_ANAHTARINIZ'],
]);
$projects = json_decode(curl_exec($ch), true)['projects'];
import requests
projects = requests.get(
'https://cdn.starkbilisim.com/api/api.php',
params={'action': 'projects'},
headers={'X-API-Key': 'API_ANAHTARINIZ'},
timeout=30,
).json()['projects']
{
"projects": [
{
"id": 7,
"name": "Web sitesi",
"description": "Kurumsal site görselleri ve tanıtım videoları",
"image_count": 42,
"created_at": "2026-10-15 10:00:00"
}
]
}
GETİstatistikler#
/api/api.php?action=stats
API anahtarı veya JWT
Hesap özetini döndürür: proje ve dosya sayısı, toplam depolama, son 5 yükleme, son 12 ayın aylık yükleme sayıları ve kategori bazında dağılım (categories). Son yüklemelerde project_id, mime_type ve category alanları da bulunur.
curl "https://cdn.starkbilisim.com/api/api.php?action=stats" \
-H "X-API-Key: API_ANAHTARINIZ"
const stats = await fetch('https://cdn.starkbilisim.com/api/api.php?action=stats', {
headers: { 'X-API-Key': 'API_ANAHTARINIZ' },
}).then((r) => r.json());
console.log(stats.storage_formatted, stats.categories.video?.count ?? 0);
<?php
$ch = curl_init('https://cdn.starkbilisim.com/api/api.php?action=stats');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: API_ANAHTARINIZ'],
]);
$stats = json_decode(curl_exec($ch), true);
echo $stats['storage_formatted'];
import requests
stats = requests.get(
'https://cdn.starkbilisim.com/api/api.php',
params={'action': 'stats'},
headers={'X-API-Key': 'API_ANAHTARINIZ'},
timeout=30,
).json()
for name, c in stats['categories'].items():
print(name, c['count'], c['bytes'])
{
"projects": 5,
"images": 127,
"storage_bytes": 52428800,
"storage_formatted": "50.0 MB",
"recent_images": [
{
"id": 131,
"original_name": "tanitim.mp4",
"url": "https://cdn.starkbilisim.com/uploads/user_1/project_7/b81e0c5a9d2f4e7c8a1b3c5d7e9f0a12.mp4",
"file_size": 73400320,
"width": null,
"height": null,
"project_name": "Web sitesi",
"created_at": "2026-11-02 12:34:10",
"project_id": 7,
"mime_type": "video/mp4",
"category": "video"
}
],
"monthly_uploads": [
{ "month": "2026-10", "count": 45 },
{ "month": "2026-11", "count": 82 }
],
"categories": {
"image": { "count": 118, "bytes": 31457280 },
"video": { "count": 3, "bytes": 20447232 },
"document": { "count": 6, "bytes": 524288 }
}
}
MCP / Claude entegrasyonuYeni#
StarkCDN bir MCP (Model Context Protocol) sunucusu sunar. Claude Code, claude.ai veya MCP destekleyen başka bir istemciye bağladığınızda asistanınız projelerinizi listeleyebilir, URL’den ya da doğrudan dosya yükleyebilir, dosyaları bulup silebilir ve istatistiklerinizi okuyabilir.
https://cdn.starkbilisim.com/mcp
- Taşıma:
- Streamable HTTP, durumsuz (oturum ve SSE yok)
- Metot:
- Yalnızca
POSTJSON-RPC 2.0 (GET/DELETE → 405) - Protokol:
- 2025-06-18, 2025-03-26, 2024-11-05
- Alternatif adres:
- /api/mcp.php
Kimlik doğrulama
Paneldeki API anahtarınızı kullanın (panel JWT’si de kabul edilir). Sunucu sırasıyla şunlara bakar:
Authorization: Bearer API_ANAHTARINIZ— önerilenX-API-Key: API_ANAHTARINIZ?key=API_ANAHTARINIZveya?api_key=…— header gönderemeyen istemciler için
Anahtar yoksa veya geçersizse 401 (WWW-Authenticate: Bearer başlığıyla), hesap engelliyse 403 döner. Kullanıcı başına dakikada 120 istek; IP başına 5 dakikada 30 hatalı deneme sınırı vardır. İstek gövdesi en fazla yaklaşık 28 MB olabilir.
Kurulum
Claude Code
Terminalde tek komutla ekleyin; anahtar bir header olarak gönderilir.
claude mcp add --transport http starkcdn https://cdn.starkbilisim.com/mcp --header "Authorization: Bearer API_ANAHTARINIZ"
Bağlantıyı claude mcp list ile ya da Claude Code içinde /mcp komutuyla doğrulayın. Ekip olarak paylaşılan bir projede anahtarı depoya koymamak için .mcp.json dosyasında ortam değişkeni kullanabilirsiniz:
{
"mcpServers": {
"starkcdn": {
"type": "http",
"url": "https://cdn.starkbilisim.com/mcp",
"headers": { "Authorization": "Bearer ${STARKCDN_API_KEY}" }
}
}
}
claude.ai (özel bağlayıcı)
- Ayarlar → Bağlayıcılar (Settings → Connectors) bölümünde Özel bağlayıcı ekle’yi seçin.
- Ad olarak
StarkCDNyazın, URL alanına anahtarlı adresi yapıştırın:
https://cdn.starkbilisim.com/mcp?key=API_ANAHTARINIZ
Araçlar
Her araç okunabilir bir metin ve şemaya uygun yapılandırılmış veri (structuredContent) döndürür. Geçersiz argüman, bulunamayan kayıt veya reddedilen yükleme gibi araç hataları isError: true sonucu olarak gelir. Tüm işlemler yalnızca kendi verilerinizi kapsar.
| Araç | Parametreler | Ne yapar? |
|---|---|---|
list_projectssalt okunur |
search?, page? (1), limit? (20, en fazla 100) | Projeleri en yeniden listeler; dosya sayısı ve toplam boyutla. |
create_project |
name (1–200), description? (en fazla 1000) | Yeni proje oluşturur, kimliğini döndürür. |
list_filessalt okunur |
project_id, search?, category?, page?, limit? (50, en fazla 100), sort? (newest · oldest · name · size) | Bir projenin dosyalarını herkese açık URL’leriyle listeler. category: image · video · audio · document · font · archive · design · 3d · raw · other. |
get_filesalt okunur |
id | Tek dosyanın bilgilerini, URL’sini ve yüklemede boyutlandırılabilir olup olmadığını (resizable) döndürür. |
upload_from_url |
project_id, url, filename?, width?, height? (1–4000), fit? (cover · contain), dedupe? (true) | Herkese açık bir http(s) adresini indirip projeye kaydeder (100 MB’a kadar, SSRF korumalı). Web’de duran her şey için tercih edilen yol. dedupe varsayılan olarak açıktır: aynı projede birebir aynı dosya varsa kopya saklanmaz, mevcut dosya duplicate: true ile döner (dedupe: false ile kapatılır). |
upload_file |
project_id, filename, content_base64, width?, height?, fit?, dedupe? (true) | Base64 içeriği yükler (data: URI ve base64url kabul edilir). Çözülmüş hâli en fazla 20 MB; daha büyükler için upload_from_url. dedupe, upload_from_url ile aynıdır. |
delete_fileyıkıcı |
id | Dosyayı yayından kaldırır; URL hemen çalışmaz. Çöp kutusu etkinse yanıtta trashed: true ve restore_until bulunur, dosya 30 gün boyunca panelden geri yüklenebilir; değilse kalıcı olarak silinir. |
get_statssalt okunur |
— | Proje/dosya sayısı, depolama, kategori dağılımı ve son 5 dosya. |
get_upload_limitssalt okunur |
— | En büyük dosya boyutları ve izinli türler. |
“?” ile biten parametreler isteğe bağlıdır; parantez içindekiler varsayılan değer ve sınırlardır.
url’deki /uploads/ kısmı /img/ yapılıp ?w=…&format=webp eklenerek yeniden yükleme yapmadan alınabilir (bkz. görsel dönüştürme). Asistanınızdan bu adresi üretmesini isteyebilirsiniz. Boyutlandırılmış kalıcı bir kopya gerekiyorsa width/height ile yükleme yine mümkündür.Örnek istekler
- “StarkCDN’de Blog adında bir proje oluştur ve şu görseli 1200 px genişlikte yükle: https://…”
- “Web sitesi projesindeki videoları listele, en büyük üçünün URL’sini ver.”
- “Bu klasördeki logo.svg dosyasını StarkCDN’e yükle ve HTML img etiketini yaz.”
- “Kapak görselimin 480, 800 ve 1600 px WebP sürümleriyle srcset’li bir img etiketi hazırla.”
- “Depolama kullanımımı kategori bazında özetle.”
- “Blog projesindeki eski-banner.png dosyasını sil; geri yükleme süresini söyle.”
Elle test etmek (JSON-RPC)
Sunucu durumsuz olduğu için her mesaj bağımsız bir POST isteğidir. Araçları listelemek veya çağırmak için:
# Araç listesi
curl -s https://cdn.starkbilisim.com/mcp \
-H "Authorization: Bearer API_ANAHTARINIZ" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# Araç çağrısı
curl -s https://cdn.starkbilisim.com/mcp \
-H "Authorization: Bearer API_ANAHTARINIZ" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_projects","arguments":{"limit":5}}}'
const res = await fetch('https://cdn.starkbilisim.com/mcp', {
method: 'POST',
headers: {
Authorization: 'Bearer API_ANAHTARINIZ',
'Content-Type': 'application/json',
Accept: 'application/json, text/event-stream',
},
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: { name: 'get_upload_limits', arguments: {} },
}),
});
const { result } = await res.json();
console.log(result.structuredContent);
Oturum ve API anahtarı#
/api/auth.php
login hariç JWT
Web panelinin kullandığı uç nokta. İşlem sorgu parametresiyle değil, JSON gövdedeki action alanıyla seçilir.
{"action": "register"} isteği 403 ve Kayıt kapalı. Hesaplar yönetici tarafından oluşturulur. mesajıyla reddedilir. Hesap için yöneticiyle iletişime geçin.| action | Gövde | Kimlik | Yanıt |
|---|---|---|---|
login | email, password | — | {token, user:{id,name,email,role}} |
google | credential (Google ID token) | — | {token, user} (yalnızca mevcut hesaplar; hesap yoksa 403) |
me | — | JWT | {user:{id,name,email,role,status,is_owner}} |
get_api_key | — | JWT | {api_key} (yoksa oluşturur) |
regenerate_api_key | — | JWT | {api_key} (eskisi hemen geçersiz) |
# Giriş: JWT al (24 saat geçerli)
curl -X POST "https://cdn.starkbilisim.com/api/auth.php" \
-H "Content-Type: application/json" \
-d '{"action":"login","email":"ad@ornek.com","password":"parolaniz"}'
# Oturumdaki kullanıcı
curl -X POST "https://cdn.starkbilisim.com/api/auth.php" \
-H "Authorization: Bearer JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"action":"me"}'
const auth = (body, token) =>
fetch('https://cdn.starkbilisim.com/api/auth.php', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
...(token ? { Authorization: `Bearer ${token}` } : {}),
},
body: JSON.stringify(body),
}).then((r) => r.json());
const { token } = await auth({ action: 'login', email: 'ad@ornek.com', password: 'parolaniz' });
const { api_key } = await auth({ action: 'get_api_key' }, token);
<?php
function auth(array $body, ?string $token = null): array
{
$headers = ['Content-Type: application/json'];
if ($token) {
$headers[] = 'Authorization: Bearer ' . $token;
}
$ch = curl_init('https://cdn.starkbilisim.com/api/auth.php');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_POSTFIELDS => json_encode($body),
]);
return json_decode(curl_exec($ch), true);
}
$token = auth(['action' => 'login', 'email' => 'ad@ornek.com', 'password' => 'parolaniz'])['token'];
$me = auth(['action' => 'me'], $token)['user'];
import requests
URL = 'https://cdn.starkbilisim.com/api/auth.php'
token = requests.post(URL, json={'action': 'login', 'email': 'ad@ornek.com', 'password': 'parolaniz'},
timeout=30).json()['token']
me = requests.post(URL, json={'action': 'me'},
headers={'Authorization': f'Bearer {token}'}, timeout=30).json()['user']
{
"user": {
"id": 1,
"name": "Ayşe Yılmaz",
"email": "ad@ornek.com",
"role": "user",
"status": "active",
"is_owner": false
}
}
Parola ve Google ile giriş, IP başına 5 dakikada 10 denemeyle sınırlıdır; Google ile giriş hiçbir zaman yeni hesap oluşturmaz. Hatalı bilgiler 401 (Invalid credentials), engellenmiş hesap 403 döner.
Proje yönetimi#
Projeleri oluşturmak, düzenlemek ve silmek için /api/projects.php kullanılır. Bu uç nokta yalnızca JWT kabul eder (Authorization: Bearer JWT_TOKEN); API anahtarı geçerli değildir.
/api/projects.php?page=&limit=&search=&sort=
JWT
/api/projects.php?id={id}
JWT
/api/projects.php
JWT
/api/projects.php?id={id}
JWT
/api/projects.php?id={id}
JWT
| Parametre | Tür | Açıklama |
|---|---|---|
page / limitisteğe bağlı |
int |
Listeleme: sayfa (varsayılan 1) ve sayfa başına proje (varsayılan 12, en fazla 50). |
searchisteğe bağlı |
string |
Listeleme: proje adında arar. |
sortisteğe bağlı |
string |
newest · oldest · name_asc · name_desc |
namezorunlu |
string |
POST ve PUT gövdesi (JSON): 1–200 karakter. |
descriptionisteğe bağlı |
string |
POST ve PUT gövdesi: en fazla 1000 karakter. PUT’ta gönderilmezse açıklama temizlenir. |
PUT ?id= ile proje adı ve açıklaması düzenlenebilir; listeleme ve tekil yanıtlarda projedeki dosyaların toplam boyutu total_size (bayt) olarak gelir. Silme, projedeki tüm dosyaları (çöp kutusundakiler dahil) kalıcı olarak siler; proje silindiğinde dosyalar çöp kutusuna gitmez. Ad ve açıklama HTML kaçışlı (& vb.) saklanır.# Proje oluştur
curl -X POST "https://cdn.starkbilisim.com/api/projects.php" \
-H "Authorization: Bearer JWT_TOKEN" -H "Content-Type: application/json" \
-d '{"name":"Web sitesi","description":"Kurumsal site görselleri"}'
# Adını / açıklamasını değiştir
curl -X PUT "https://cdn.starkbilisim.com/api/projects.php?id=7" \
-H "Authorization: Bearer JWT_TOKEN" -H "Content-Type: application/json" \
-d '{"name":"Web sitesi 2026","description":"Yeni tasarım"}'
const res = await fetch('https://cdn.starkbilisim.com/api/projects.php?id=7', {
method: 'PUT',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'Web sitesi 2026', description: 'Yeni tasarım' }),
});
const { project } = await res.json();
<?php
$ch = curl_init('https://cdn.starkbilisim.com/api/projects.php?id=7');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['name' => 'Web sitesi 2026', 'description' => 'Yeni tasarım']),
]);
$project = json_decode(curl_exec($ch), true)['project'];
import requests
r = requests.put(
'https://cdn.starkbilisim.com/api/projects.php',
params={'id': 7},
headers={'Authorization': f'Bearer {token}'},
json={'name': 'Web sitesi 2026', 'description': 'Yeni tasarım'},
timeout=30,
)
project = r.json()['project']
{
"project": {
"id": 7,
"user_id": 1,
"name": "Web sitesi 2026",
"description": "Yeni tasarım",
"created_at": "2026-10-15 10:00:00",
"updated_at": "2026-11-02 12:40:00",
"image_count": 42,
"total_size": 98566144
}
}
Listeleme yanıtı: {"projects": [...], "total", "page", "totalPages"} · Oluşturma: 201 ve {"project": {...}} · Silme: {"message": "Project deleted"}.
Panel dosya işlemleri#
/api/images.php web panelinin dosya ekranını besler ve yalnızca JWT kabul eder. Entegrasyonlar için dosya API’sini tercih edin.
| İstek | Açıklama |
|---|---|
GET ?project_id=&page=&limit=&search=&sort= | Proje dosyaları (varsayılan 24, en fazla 100 / sayfa; dosya adında arama). Öğelerde category bulunur, url göreli yoldur (/uploads/…). Yanıt: {project, images, total, page, totalPages} |
| POST multipart | project_id + images[]: istek başına en fazla 20 dosya; isteğe bağlı dedupe=1 (eşleşen öğelerde duplicate: true). Hepsi başarılıysa 201, bir kısmı reddedildiyse 207: {uploaded, errors:[{file, error}], count} |
| POST JSON | {"action": "bulk_delete", "image_ids": [1, 2, 3]} → {"deleted": 3}; çöp kutusu etkinse ayrıca "trashed": true, "restore_until": "…" |
DELETE ?id={id} | Tek dosya siler → {"message": "Image deleted"}; çöp kutusu etkinse trashed ve restore_until da gelir |
Çöp kutusu Yeni
Panelin Çöp kutusu sayfası da images.php üzerinden çalışır (yalnızca JWT). Silinen dosyalar 30 gün boyunca burada listelenir ve geri yüklenebilir; süresi dolanlar otomatik olarak kalıcı silinir. Sunucuda çöp kutusu henüz etkin değilse liste "enabled": false döner, geri yükleme ve kalıcı silme işlemleri 409 verir.
| İstek | Açıklama |
|---|---|
GET ?trash=1&project_id=&page=&limit= | Çöpteki dosyalar, tüm projeler (varsayılan 50, en fazla 100 / sayfa; project_id isteğe bağlı filtre). Yanıt: {enabled, days, images:[{id, project_id, project_name, original_name, file_size, mime_type, category, width, height, created_at, deleted_at, restore_until, days_left}], total, total_size, page, totalPages} |
| POST JSON | {"action": "restore", "image_ids": [5, 6]} → {restored, images:[{id, project_id, url}], errors:[{id, error}]}. Dosya aynı URL’ye geri döner. Hiçbiri geri yüklenemezse 409. |
| POST JSON | {"action": "purge", "image_ids": [5]} → {"purged": 1} (çöpteki dosyayı kalıcı siler) |
| POST JSON | {"action": "empty_trash"} → {purged, remaining}; tek istekte işlenemeyenler remaining’de kalır, tekrar çağırın |
restore ve purge istek başına en fazla 500 kimlik kabul eder.
Limitler ve dosya türleri#
100 MB
dosya başına
8 MB
parça boyutu*
64 MP
raster görsel
2560 px
anlık dönüştürme
upload isteğiyle en fazla single_request_max_bytes kadar dosya gönderilebilir; bu değer sunucunun PHP ayarlarından hesaplanır ve şu an dosya sınırıyla aynıdır (100 MB). Güncel değeri limits uç noktasından okuyun. Daha büyük dosyalar için ve yavaş/kesintili bağlantılarda büyük dosyalarda parçalı yüklemeyi kullanın. Site artık Cloudflare proxy’si arkasında değildir (yalnızca DNS); eski “100 MB’a yakın gövdelere Cloudflare 413” kısıtı geçerli değildir. Gövde sunucu sınırını aşarsa yine 413 döner.| Özellik | Değer |
|---|---|
| Dosya başına en büyük boyut | 100 MB (104 857 600 bayt) — tüm yükleme yollarında |
Tek istekte (upload, ShareX) | single_request_max_bytes — şu an 100 MB; daha büyükleri parçalı yükleme |
| Parçalı yükleme parça boyutu | 8 MB* (sunucu ayarına göre daha küçük olabilir, en az 1 MB; upload_init yanıtındaki değeri kullanın) |
| Açık parçalı yükleme | Kullanıcı başına aynı anda 10; tamamlanmayanlar 24 saat sonra silinir |
| Raster görsel çözünürlüğü | En fazla 64 megapiksel (ör. 8000 × 8000), kenar başına en fazla 65 535 px |
| Yüklemede boyutlandırma | En fazla 4000 × 4000 px; yalnızca JPG, PNG, GIF, WebP |
Anlık dönüştürme (/img/) | Çıktı en fazla 2560 px; kaynak görsel başına en fazla 12 varyant |
| SVG | En fazla 10 MB; kaydedilmeden önce temizlenir |
| URL’den yükleme | 100 MB, 120 sn, en fazla 5 yönlendirme |
MCP upload_file | Çözülmüş içerik en fazla 20 MB (daha büyükleri upload_from_url) |
| Panelden tek seferde | 20 dosya |
| Çöp kutusu | Silinen dosyalar 30 gün panelden geri yüklenebilir, sonra kalıcı silinir |
| Önbellek | /uploads/ dosyaları ve /img/ dönüşümleri 1 gün (silinen dosyalar önbelleklerden en geç 1 günde kalkar); serve yanıtları 24 saat |
Desteklenen dosya türleri
Dokuz kategoride 80’den fazla uzantı desteklenir. satır içi türler tarayıcıda doğrudan açılır (<img>, <video>, <audio>, @font-face, PDF görüntüleyici); indirme türleri her zaman Content-Disposition: attachment ile, dosya olarak iner. Tüm /uploads/ dosyaları Access-Control-Allow-Origin: * ile sunulur. Tam ve güncel liste: GET ?action=limits.
| Kategori | Uzantılar | Sunum | Notlar |
|---|---|---|---|
image Görsel | jpg, png, gif, webp, avif, svg, ico tif, bmp, heic, heif | satır içi | JPG/PNG/GIF/WebP yüklemede boyutlandırılabilir ve yeniden kodlanır; /img/ ile anında dönüştürülebilir. AVIF, ICO, TIFF, BMP ve HEIC/HEIF olduğu gibi saklanır (tarayıcı desteği değişir). SVG’lerden script, olay öznitelikleri, javascript: bağlantıları ve foreignObject temizlenir; sandbox CSP ile sunulur. |
video Video | mp4, webm, mov avi, mkv, mpg, wmv | satır içi | Olduğu gibi saklanır. Tüm tarayıcılarda oynatma için MP4 (H.264) veya WebM tercih edin. |
audio Ses | mp3, wav, ogg, m4a flac, aac, aiff, mid, wma | satır içi | Olduğu gibi saklanır. |
document Doküman ve ofis | pdf, txt, csv, json, md, xml, rtf doc, docx, xls, xlsx, ppt, pptx odt, ods, odp, pages, numbers, key, epub | PDF satır içi diğerleri indirme | PDF tarayıcıda açılır; geri kalan her şey indirme olarak sunulur. DOCX/XLSX/PPTX, sunucuda veritabanı güncellemesi yapılana kadar reddedilebilir. |
font Font | woff, woff2, ttf, otf, eot | satır içi | Başka sitelerde @font-face ile kullanılabilir. |
archive Arşiv | zip, rar, 7z, tar gz, tgz, bz2, xz | indirme | İçerik açılmaz veya taranmaz; olduğu gibi saklanır. |
design Tasarım | ai, eps, psd, indd, xd sketch, fig, cdr, afdesign, afphoto | indirme | Illustrator, Photoshop, InDesign, Adobe XD, Sketch, Figma, CorelDRAW ve Affinity dosyaları. |
3d 3D model | glb, gltf, obj, stl, fbx, usdz | indirme | Olduğu gibi saklanır. |
raw Ham fotoğraf | dng, cr2, cr3, nef arw, raf, orf, rw2 | indirme | Adobe DNG, Canon, Nikon, Sony, Fujifilm, Olympus ve Panasonic RAW dosyaları. Önizleme veya dönüştürme yapılmaz. |
Kabul edilen uzantı yazımları (extension_aliases): jpeg, jpe, jfif → jpg · m4v → mp4 · oga, opus → ogg · tiff → tif · mpeg → mpg · midi → mid · aif, aifc → aiff.
foto.jpeg .jpg olarak, aslında PNG olan resim.jpg ise .png olarak kaydedilir. İçeriği iddia ettiği türle uyuşmayan, uzantısı değiştirilmiş dosyalar 400 ile reddedilir. original_name alanı gönderdiğiniz adı korur..phtml, .phar vb. dahil), kabuk betikleri ve çalıştırılabilir dosyalar (EXE, DLL, ELF, Mach-O) hiçbir uzantıyla kabul edilmez; adında .php veya .htaccess geçen dosyalar da reddedilir.GETSağlık kontrolüYeni#
/api/health.php
Kimlik gerekmez
Servisin çalışıp çalışmadığını bildirir; UptimeRobot, Better Stack gibi izleme servisleri ve kendi durum sayfalarınız için uygundur. Kimlik doğrulama gerekmez, yanıt önbelleğe alınmaz (Cache-Control: no-store) ve IP başına dakikada 60 istekle sınırlıdır. HEAD de desteklenir; diğer metotlar 405 döner.
status | HTTP | Anlamı |
|---|---|---|
ok | 200 | Tüm kontroller geçti. |
degraded | 200 | Servis çalışıyor ama bir sorun var: yükleme dizini yazılamıyor veya boş disk alanı 1 GB’ın altında. Yeni yüklemeler başarısız olabilir. |
down | 503 | Veritabanına ulaşılamıyor; API istekleri başarısız olur. |
| Alan | Tür | Açıklama |
|---|---|---|
checks.database |
object |
ok ve latency_ms (tek SELECT 1 sorgusunun süresi). Bağlantı yoksa yalnızca {"ok": false}. |
checks.uploads |
object |
ok: yükleme dizini var ve yazılabilir. |
checks.disk |
object |
ok: boş alan eşiğin üstünde mi. Sunucu boş alanı ölçemiyorsa {"ok": null}. |
checks.php |
object |
ok: PHP çalışıyor. |
version |
string | null |
Yayındaki sürümün commit SHA’sı; bilinmiyorsa null. |
environment |
string |
production veya staging. |
time |
string |
Sunucu saati, ISO 8601 (UTC). |
curl -s "https://cdn.starkbilisim.com/api/health.php"
# Yalnızca durum kodu (izleme betikleri için)
curl -s -o /dev/null -w "%{http_code}\n" "https://cdn.starkbilisim.com/api/health.php"
const res = await fetch('https://cdn.starkbilisim.com/api/health.php');
const health = await res.json();
if (res.status === 503 || health.status === 'down') alert('StarkCDN çalışmıyor');
else if (health.status === 'degraded') console.warn('StarkCDN kısmen çalışıyor', health.checks);
<?php
$ch = curl_init('https://cdn.starkbilisim.com/api/health.php');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10]);
$health = json_decode((string) curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$ok = $status === 200 && ($health['status'] ?? '') === 'ok';
import requests
r = requests.get('https://cdn.starkbilisim.com/api/health.php', timeout=10)
health = r.json()
print(r.status_code, health['status'], health['checks']['database'].get('latency_ms'))
{
"status": "ok",
"checks": {
"database": { "ok": true, "latency_ms": 3 },
"uploads": { "ok": true },
"disk": { "ok": true },
"php": { "ok": true }
},
"version": "df91df7c3a1e5b9f0d2c4e6a8b0c2d4e6f8a0b1c",
"environment": "production",
"time": "2026-11-02T14:49:38+00:00"
}
degraded durumunu kaçırır; mümkünse yanıt gövdesinde "status":"ok" anahtar kelimesini de arayın. Kontrol aralığını dakikada bir veya daha seyrek tutun.Hata kodları#
Tüm hatalar JSON olarak döner: {"error": "Hata mesajı"}. Mesajlar çoğunlukla İngilizcedir (birkaç panel ve veritabanı güncellemesi mesajı Türkçedir) ve istemci tarafında koşul olarak kullanılmamalıdır; HTTP durum koduna göre karar verin. (MCP sunucusu hataları JSON-RPC error nesnesiyle bildirir.)
| Kod | Anlamı | Ne zaman? |
|---|---|---|
200 / 201 | Başarılı | 201: yeni dosya veya proje oluşturuldu. images.php kısmi başarıda 207 döner. |
400 | Bad Request | Eksik/geçersiz parametre, desteklenmeyen veya içeriği uyuşmayan tür, boyut aşımı, hatalı parça boyutu, URL indirilemedi, geçersiz JSON; /img/ adresinde geçersiz yol veya w/h/fit/format/q; veritabanı güncellemesi bekleyen tür (DOCX/XLSX/PPTX) |
401 | Unauthorized | API anahtarı / JWT eksik, hatalı biçimde veya geçersiz; JWT süresi dolmuş |
403 | Forbidden | Hesap engellenmiş, kayıt kapalı, MCP’de izin verilmeyen Origin |
404 | Not Found | Proje, dosya veya parçalı yükleme bulunamadı (ya da size ait değil); silinmiş/çöp kutusundaki dosya; süresi dolmuş upload_id; /img/ kaynağı yok |
405 | Method Not Allowed | Yanlış HTTP metodu (ör. upload için GET) |
409 | Conflict | Eksik parçalarla upload_complete veya aynı yükleme zaten tamamlanıyor; panelde çöp kutusu henüz etkin değil ya da geri yükleme başarısız |
413 | Payload Too Large | İstek gövdesi sunucunun tek istek sınırını aştı → parçalı yükleme kullanın |
429 | Too Many Requests | Hız limiti aşıldı veya 10 açık parçalı yükleme dolu |
500 / 503 | Sunucu hatası | Beklenmeyen hata. 503: sunucuda URL indirme özelliği kullanılamıyor veya sağlık kontrolü down (veritabanına ulaşılamıyor) |
Sık görülen mesajlar
| Durum | Mesaj | Nerede / neden |
|---|---|---|
400 | Invalid file type. Allowed: image (JPG, PNG, GIF, WEBP, ...), video (MP4, WEBM, MOV, AVI, ...), … - full list: GET api.php?action=limits | Yükleme yolları. Kategori özetidir; tam liste limits yanıtında |
400 | Bu dosya türü için yönetici panelinden bekleyen migration'ı çalıştırın (file type not enabled yet: database migration pending). | DOCX/XLSX/PPTX: MIME türü eski veritabanı kolonuna sığmıyor; yönetici güncellemeyi çalıştırana kadar reddedilir |
400 | Invalid image path · Invalid w: must be an integer between 1 and 10000 · Invalid fit: … · Invalid format: … | /img/ adresi |
404 | Image not found | Dosya yok, size ait değil, silinmiş veya çöp kutusunda (delete, serve, /img/) |
409 | Upload incomplete: missing chunks 3,4 | upload_complete eksik parçalarla çağrıldı |
409 | Çöp kutusu henüz etkin değil (migration bekleniyor) | Panel (images.php): restore / purge / empty_trash |
{
"error": "Upload incomplete: missing chunks 3,4"
}
Sonuç bulunamadı
“” için eşleşen bölüm yok. Farklı bir kelime deneyin.