Dokümanlar

Başlarken

1. Hesap aç, panelde API anahtarları bölümünden bir anahtar oluştur. Anahtar tcdn_ ile başlar ve yalnızca bir kez gösterilir.
2. Ölçüler bölümünde sitende kullandığın boyutları tanımla, örneğin kart adıyla 400×400.
3. Görseli yükle, sonra adresini ölçü adıyla kullan.

curl -X PUT \
  -H "Authorization: Bearer tcdn_..." \
  --data-binary @kapak.jpg \
  https://api.turkcdn.com/v1/images/urun/kapak.jpg

# pip install requests
import requests

TOKEN = "tcdn_..."  # Panel → API anahtarları
API = "https://api.turkcdn.com/v1"
headers = {"Authorization": f"Bearer {TOKEN}"}

with open("kapak.jpg", "rb") as f:
    r = requests.put(f"{API}/images/urun/kapak.jpg", headers=headers, data=f)
r.raise_for_status()
print(r.json()["url"])

<img src="https://cdn.turkcdn.com/magazam/urun/kapak_kart.webp"
     width="400" height="400" alt="Ürün">

Görsel adresleri

Her görselin adresi https://cdn.turkcdn.com/{hesap}/{yol} biçimindedir. {hesap} panelde görünen hesap adın, {yol} yüklerken verdiğin yoldur. Ölçü ve format dosya adından okunur; sorgu parametresi ya da SDK gerekmez.

Dosya adının sonundaki her _ bir komut başlatır ve komutların sırası önemli değildir. Adında alt çizgi olan dosyalar da çalışır: önce tam ad aranır, bulunamazsa sondaki parçalar komut olarak okunur. Bir adreste en fazla bir tasarım adı ve bir ebat olur. Dosya adında _th_ kullanılamaz, çünkü eski biçimin ayıracıdır.

Kaynaktan çekme (web proxy)

Görsellerin zaten bir sitede duruyorsa hiçbirini yüklemen gerekmez. Alana kaynak olarak siteni ver, sonra sayfalarındaki görsel adreslerinde yalnız alan adını değiştir. Alanda olmayan bir görsel ilk istendiğinde kaynaktan alınır, alanına kaydedilir ve istenen ölçü üretilir. Sonraki istekler doğrudan CDN'den gelir.

Kurulum

1. Panelde Alanlar sayfasında alanının yanındaki Kaynak: Ekle'ye tıkla.
2. Sitenin adresini yaz: https://mysite.com. Görseller bir klasördeyse klasörü de verebilirsin: https://mysite.com/uploads.
3. Sayfalarındaki görsel adreslerinde https://mysite.com yerine https://cdn.turkcdn.com/{alan} yaz, istediğin ölçüyü dosya adına ekle.

<!-- Önce -->
<img src="https://mysite.com/urun/ayakkabi.jpg">

<!-- Sonra: kart tasarımında, WebP olarak -->
<img src="https://cdn.turkcdn.com/magazam/urun/ayakkabi_kart.webp">

Hangi dosya alınır?

Komutlar ve uzantı adresten çıkarılır, kalan yol kaynağın sonuna eklenir:

Boşluk ve Türkçe karakterler adreste kendiliğinden kodlanır. Kaynak https://mysite.com/uploads ise aynı adresler https://mysite.com/uploads/urun/… olarak aranır. Kendi alan adını bağladıysan aynısı orada da çalışır: https://img.mysite.com/urun/ayakkabi_kart.webp.

Bilmen gerekenler

• İlk istek biraz yavaş: görsel kaynaktan indirilip işlenir. Sonra CDN'den gelir.
• Görsel güncellemek: TurkCDN kaynağı tekrar kontrol etmez. Kaynakta bir görseli değiştirdiysen panelden ya da API'den (DELETE /images/{yol}) sil; bir sonraki istekte yenisi alınır.
• Olmayan dosya: kaynakta bulunamayan dosya 404 döner ve 10 dakika tekrar sorulmaz. Kaynak adresini değiştirince bu bekleme sıfırlanır.
• Kaynağın erişilebilir olması lazım: istekler TurkCDN/1 (+https://turkcdn.com) kimliğiyle gelir, 10 saniyede cevap gelmezse vazgeçilir. Yönlendirmeler (301, 302) izlenmez; adres doğrudan görseli vermeli. Sitende hotlink ya da bot koruması varsa bu kimliğe izin ver.
• Sınırlar: yüklemedeki kurallar geçerli: en fazla 20 MB, JPG, PNG, WebP ya da GIF. Çekilen görseller paketindeki görsel sayısına ve depolamaya sayılır.
• Güvenlik: yalnız internete açık adreslere bağlanılır; iç ağ ve yerel adresler engellidir.

Ebatlar ve tasarımlar

Panelde Ölçüler sekmesinde iki ayrı liste vardır:

• İzin verilen ebatlar: İsimsiz genişlik × yükseklik listesi. Adreste boyutuyla çağrılır (_300x250, _w400, _h400) ve tasarımların ölçüsünü ezmek için kullanılır. Ortadan kırpılır.
• Tasarımlar: İsim zorunludur. Varsayılan ölçü, mod, kırpma yönü, kalite, tasarım komutları ve görüntüleyici bir arada saklanır; adreste adıyla çağrılır (_akart).

API'de ikisi de /presets ucundadır: name verilirse tasarım, verilmezse ebattır. Ebatta effects ve viewer kullanılamaz.

Bir ölçüyü değiştirdiğinde ondan üretilmiş kopyalar silinir ve sonraki istekte yeni ayarla yeniden üretilir.

Tasarım komutları

Köşe, çerçeve ve benzeri ayarları ölçüye kaydedebilir ya da adrese doğrudan ekleyebilirsin. Ölçüsüz de kullanılır; o zaman görselin kendi boyutunda uygulanır.

Seviyeler görselin boyutuna göre ölçeklenir; 200 ve 2000 piksellik görselde aynı görünür. Piksel vermek istersen sayı yaz: _rounded-16 (1-500), _border-2 ve _border-2-eeeeee (1-50), _blur-8 (1-50). Türkçesi de aynı: _yuvarlak-16, _cerceve-2-eeeeee, _bulanik-8.

İngilizce ve Türkçe komutlar birbirinin takma adıdır, aynı kopyayı üretir. Aynı komut iki dilde birden yazılamaz: _gri_grayscale geçersizdir.

Komutlar sırasız yazılır ve birleştirilir: urun/kapak_kart_rounded-lg_border.webp, ekip/ayse_circle.png, banner_grayscale_blur-low.jpg. Bir adreste en fazla 6 komut olur, her komut bir kez yazılır. Renkler 3 ya da 6 haneli, küçük harf onaltılıktır.

Sık kullandığın birleşimi kendi adınla kullanmak istersen bir ölçüye kaydet: örneğin kapak adlı ölçü rounded-lg_shadow olsun, adreste _kapak yaz. Ölçüde ve adreste aynı komut varsa adrestekiyle üretilir. Saydam köşeler için .webp, .avif ya da .png iste; JPG saydamlık taşımaz, köşeler beyaz ya da _bg rengiyle dolar.

Büyütme ve büyüteç

Sitene bir kez şu satırı ekle:

<script src="https://cdn.turkcdn.com/turkcdn.js" defer></script>

Sonra görselin adresine komutu ekle. Görsel aynı kalır; davranışı script ekler.

Komutu her adrese yazmak istemezsen panelde tasarımın Görüntüleyici ayarını seç; o tasarımı kullanan her adres (resim_akart.jpg) kendiliğinden büyütülebilir olur. Özel alan adı kullanıyorsan script etiketine alan adını ekle: data-domains="cdn.mysite.com".

İkisi birlikte de olur: urun/kapak_kart_o-on_z-on.webp. Script büyük hâller için aynı adresin iki sürümünü ister; istersen sen de kullanabilirsin:

• _full: ölçü yok sayılır, görselin tamamı orijinal boyutunda gelir.
• _hd: aynı ölçü ve kırpım, 3 kat çözünürlükte; orijinalden büyük olmaz.

Görüntüleyici ayarları

Panelde Ölçüler sekmesinin altındaki Görüntüleyici bölümünden alan başına ayarlanır. Overlay ya da zoom'u kapatırsan adreslere dokunmadan anında durur.

API: GET / PUT /zones/{alan}/viewer. Script ayarları ve görüntüleyicili tasarımları alanın turkcdn.json dosyasından okur: https://cdn.turkcdn.com/{alan}/turkcdn.json.

Script yaklaşık 4 KB'tır, bağımlılığı yoktur. Eklemezsen komutlu görseller normal görsel gibi davranır.

Formatlar ve sınırlar

Format adresteki uzantıyla seçilir. .jpeg uzantısı .jpg olarak okunur.

Önbellek ve temizlik

• Kopyalar ilk istekte üretilir, sonra CDN'den sunulur. Yanıtlar Cache-Control: public, max-age=86400 ve ETag taşır.
• Her alan adından kullanılabilir (Access-Control-Allow-Origin: *).
• Aynı yola yeniden yükleme yaparsan eski kopyalar ve CDN önbelleği temizlenir. Adres değişmez.
• 30 gün boyunca istenmeyen kopyalar kendiliğinden silinir; tekrar istenirse yeniden üretilir. Orijinal dosya silinmez.

Video

Yüklenen video arka planda H.264 MP4'e dönüştürülür. Dönüşüm bitene kadar adresler 404 döner, sonra hazır olur. Range istekleri desteklenir.

Video ölçüleri görsel ölçülerinden ayrıdır. Genişlik ve yükseklik 32 ile 3840 arasında çift sayı olmalı. mode varsayılanı contain, kalite crf ile verilir (18-35, varsayılan 23, küçük sayı daha yüksek kalite). Yeni ölçü eklediğinde hesabındaki videolar o ölçüde yeniden hazırlanır.

API

Temel adres https://api.turkcdn.com/v1. Her istekte API anahtarını Authorization başlığında gönder:

Authorization: Bearer tcdn_...

Anahtarını sunucu tarafında sakla, tarayıcıya ya da mobil uygulamaya koyma. Sızdığını düşünürsen panelden sil ve yenisini oluştur.

Her anahtar bir alana bağlıdır; yüklediğin görseller ve videolar o alanın adresinde yayınlanır.

Görseller

Yükleme ve listeleme her görsel için şu alanları döner:

{
  "id": 128,
  "path": "urun/kapak.jpg",
  "size": 1258291,
  "width": 2400,
  "height": 2400,
  "created_at": 1792540800,
  "url": "https://cdn.turkcdn.com/magazam/urun/kapak.jpg"
}

Ölçüler

Gövde JSON'dur; alanlar Ölçüler bölümündeki tabloda.

curl -X POST \
  -H "Authorization: Bearer tcdn_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "kart", "width": 400, "height": 400, "mode": "cover", "anchor": "t"}' \
  https://api.turkcdn.com/v1/presets

import requests

r = requests.post(
    "https://api.turkcdn.com/v1/presets",
    headers={"Authorization": "Bearer tcdn_..."},
    json={"name": "kart", "width": 400, "height": 400, "mode": "cover", "anchor": "t"},
)
r.raise_for_status()

Filigran

Videolar

Video durumu status alanındadır: queued, processing, ready ya da failed. Yanıtta oynatma adresi url, kapak karesi poster_url alanında gelir.

Anahtarlar

Alanlar

Bir hesabın birden fazla alanı olabilir; her alanın kendi adresi (https://cdn.turkcdn.com/{alan}/), görselleri, videoları, ölçüleri, alan adları ve anahtarları vardır. Görsel, video, depolama ve trafik limitleri tüm alanların toplamına uygulanır. Alan sayısı: Webmaster ve Başla 1, Geliştir 3, Büyüt 10. Ücretsiz Webmaster paketinde ayrıca günlük sınır var: günde 50 MB trafik ve 1.000 istek. Biri dolunca görseller ertesi gün 03:00'e kadar sunulmaz.

Kaynak adresin nasıl çalıştığı Kaynaktan çekme bölümünde.

Alan eklemek ve silmek yalnız panelden yapılır. Silinen alanın görselleri, videoları, ölçüleri, alan adları ve anahtarları kalıcı olarak silinir, adresleri CDN önbelleğinden de temizlenir.

İstatistik

GET/stats görsel, kopya ve ölçü sayılarını ve kapladıkları alanı bayt olarak döner: images, image_bytes, variants, variant_bytes, presets.

Hatalar

Hatalı isteklerde gövde {"error": "açıklama"} biçimindedir; açıklama Türkçedir.