Docs

Getting started

The dashboard is currently in Turkish.

1. Create an account, then create a key in the API keys (API anahtarları) section of the dashboard. Keys start with tcdn_ and are shown only once.
2. In the Sizes (Ölçüler) section, define the sizes your site uses, for example 400×400 named kart. The name is up to you; kart is Turkish for "card".
3. Upload the image, then use its URL with the size name.

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_..."  # Dashboard → API keys
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="Product">

Image URLs

Every image URL has the form https://cdn.turkcdn.com/{account}/{path}. {account} is the account name shown in the dashboard, and {path} is the path you gave when uploading. Size and format are read from the file name; no query parameters or SDK needed.

Each _ at the end of the file name starts a command, and command order doesn't matter. File names that contain underscores work too: the full name is looked up first, and if it isn't found, the trailing parts are read as commands. A URL can contain at most one template name and one size. You can't use _th_ in a file name, because it is the legacy format's separator.

Origin pull (web proxy)

If your images already live on a website, you don't need to upload any of them. Set your site as the zone's origin, then change only the domain in the image URLs on your pages. The first time an image that isn't in the zone is requested, it is fetched from the origin, saved to your zone, and the requested size is generated. Later requests are served straight from the CDN.

Setup

1. In the dashboard, on the Zones (Alanlar) page, click Origin: Add (Kaynak: Ekle) next to your zone.
2. Enter your site's URL: https://mysite.com. If your images are in a folder, you can include the folder too: https://mysite.com/uploads.
3. In the image URLs on your pages, replace https://mysite.com with https://cdn.turkcdn.com/{zone} and add the size you want to the file name.

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

<!-- After: kart template, as WebP -->
<img src="https://cdn.turkcdn.com/magazam/urun/ayakkabi_kart.webp">

Which file is fetched?

Commands and the extension are removed from the URL, and the remaining path is appended to the origin:

Spaces and non-ASCII characters (such as Turkish letters) are encoded in the URL automatically. If the origin is https://mysite.com/uploads, the same URLs are looked up as https://mysite.com/uploads/urun/…. If you've connected your own domain, the same works there too: https://img.mysite.com/urun/ayakkabi_kart.webp.

Things to know

• The first request is a bit slower: the image is downloaded from the origin and processed. After that it comes from the CDN.
• Updating images: TurkCDN doesn't check the origin again. If you change an image at the origin, delete it in the dashboard or through the API (DELETE /images/{path}); the new version is fetched on the next request.
• Missing files: a file that isn't found at the origin returns 404 and isn't requested again for 10 minutes. Changing the origin URL resets this wait.
• The origin must be reachable: requests use the user agent TurkCDN/1 (+https://turkcdn.com) and give up if there is no response within 10 seconds. Redirects (301, 302) are not followed; the URL must serve the image directly. If your site has hotlink or bot protection, allow this user agent.
• Limits: the upload rules apply: up to 20 MB, JPG, PNG, WebP or GIF. Fetched images count toward your plan's image count and storage.
• Security: only publicly reachable addresses are contacted; internal network and local addresses are blocked.

Sizes and templates

The Sizes tab in the dashboard has two separate lists:

• Allowed sizes: An unnamed list of width × height values. You request them in the URL by dimensions (_300x250, _w400, _h400), and you can use them to override a template's size. They are cropped from the center.
• Templates: A name is required. A template stores the default size, mode, crop anchor, quality, styling commands and viewer together; you request it in the URL by name (_akart).

In the API both use the /presets endpoint: with name it's a template, without it it's a size. Sizes can't use effects or viewer.

When you change a preset, the copies generated from it are deleted and regenerated with the new settings on the next request.

Styling commands

You can save corners, borders and similar settings in a preset, or add them directly to the URL. They also work without a size; in that case they are applied at the image's own size.

Levels scale with the image size, so they look the same on a 200 px and a 2000 px image. To set pixels, use a number: _rounded-16 (1-500), _border-2 and _border-2-eeeeee (1-50), _blur-8 (1-50). The Turkish aliases work the same way: _yuvarlak-16, _cerceve-2-eeeeee, _bulanik-8.

English and Turkish commands are aliases of each other and produce the same copy. You can't write the same command in both languages: _gri_grayscale is invalid.

Commands can be written in any order and combined: urun/kapak_kart_rounded-lg_border.webp, ekip/ayse_circle.png, banner_grayscale_blur-low.jpg. A URL can have at most 6 commands, and each command can appear only once. Colors are 3- or 6-digit lowercase hex.

To use a combination you need often under your own name, save it to a preset: for example, make a preset named kapak ("cover") with rounded-lg_shadow, then write _kapak in the URL. If the same command is in both the preset and the URL, the URL's value is used. For transparent corners, request .webp, .avif or .png; JPG has no transparency, so the corners are filled with white or the _bg color.

Lightbox and zoom

Add this line to your site once:

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

Then add the command to the image URL. The image itself stays the same; the script adds the behavior.

If you don't want to add the command to every URL, choose a Viewer (Görüntüleyici) setting for the template in the dashboard; every URL that uses that template (resim_akart.jpg) becomes zoomable automatically. If you use a custom domain, add it to the script tag: data-domains="cdn.mysite.com".

You can use both together: urun/kapak_kart_o-on_z-on.webp. For the large views, the script requests two variants of the same URL, and you can use them too:

• _full: the size is ignored and the whole image is returned at its original size.
• _hd: the same size and crop at 3× resolution, never larger than the original.

Viewer settings

These are set per zone in the Viewer section under the Sizes tab in the dashboard. If you turn off the overlay or zoom, it stops immediately, without touching your URLs.

API: GET / PUT /zones/{zone}/viewer. The script reads the settings and the templates that have a viewer from the zone's turkcdn.json file: https://cdn.turkcdn.com/{zone}/turkcdn.json.

The script is about 4 KB and has no dependencies. If you don't add it, images with these commands behave like regular images.

Formats and limits

The format is chosen by the extension in the URL. The .jpeg extension is read as .jpg.

Caching and cleanup

• Copies are generated on the first request and then served from the CDN. Responses include Cache-Control: public, max-age=86400 and an ETag.
• Images can be used from any domain (Access-Control-Allow-Origin: *).
• If you upload again to the same path, the old copies and the CDN cache are purged. The URL stays the same.
• Copies that aren't requested for 30 days are deleted automatically and regenerated if requested again. The original file is never deleted.

Video

Uploaded videos are converted to H.264 MP4 in the background. Their URLs return 404 until the conversion finishes, then become available. Range requests are supported.

Video presets are separate from image presets. Width and height must be even numbers between 32 and 3840. mode defaults to contain, and quality is set with crf (18-35, default 23; a lower number means higher quality). When you add a new preset, the videos in your account are reprocessed at that size.

API

The base URL is https://api.turkcdn.com/v1. Send your API key in the Authorization header with every request:

Authorization: Bearer tcdn_...

Keep your key on the server side; don't put it in a browser or a mobile app. If you think it has leaked, delete it in the dashboard and create a new one.

Each key belongs to a zone; the images and videos you upload are published at that zone's URL.

Images

Upload and list return these fields for each image:

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

Presets

The body is JSON; the fields are listed in the table in the Sizes and templates section.

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()

Watermark

Videos

The video status is in the status field: queued, processing, ready or failed. The response includes the playback URL in url and the poster frame in poster_url.

Keys

Zones

An account can have multiple zones; each zone has its own URL (https://cdn.turkcdn.com/{zone}/), images, videos, presets, domains and keys. Image, video, storage and traffic limits apply to the total across all zones. Number of zones: Webmaster and Başla 1, Geliştir 3, Büyüt 10. The free Webmaster plan also has daily limits: 50 MB of traffic and 1,000 requests per day. When either limit is reached, images aren't served until 03:00 the next day.

How the origin URL works is described in Origin pull.

Zones can be added and deleted only in the dashboard. Deleting a zone permanently deletes its images, videos, presets, domains and keys, and also purges its URLs from the CDN cache.

Stats

GET/stats returns the number of images, copies and presets, and the space they take up in bytes: images, image_bytes, variants, variant_bytes, presets.

Errors

For failed requests, the body has the form {"error": "description"}. API error messages are currently returned in Turkish.