CDN URLs

CDN URLs follow a consistent pattern that combines the space handle, file path, and optional transformation parameters.

URL Format

https://cdn.tzzl.io/{space_handle}/{file_name}

The space_handle is the 6-character identifier assigned when the space is created. The file_name is the generated name from the upload response (e.g., image-01HQ...).

Building URLs

From Upload Response

After uploading a file, use the storage_path field:

const response = await uploadFile(file)
const cdnUrl = `https://cdn.tzzl.io/${response.storage_path}`
// https://cdn.tzzl.io/a1b2c3/image-01HQ...

With Transformations

Append query parameters for on-the-fly processing:

https://cdn.tzzl.io/a1b2c3/image-01HQ...?w=400&h=300&f=webp&q=80

Batch URL Generation

Generate URLs for multiple files at once using the API:

curl -X POST https://api.tzzl.io/api/v1/files/urls \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_ids": ["01HQ...", "01HR...", "01HS..."]
  }'

Path Security

The CDN blocks path traversal attempts. URLs containing .., null bytes (\0), or double slashes (//) are rejected with a 400 status.

Custom Domains

Spaces can be configured with a custom domain for branded URLs:

https://media.yoursite.com/image-01HQ...?w=400

Configure this through the space's custom_domain setting.

URL Examples

# Original file
https://cdn.tzzl.io/a1b2c3/image-01HQ...

# Resized thumbnail
https://cdn.tzzl.io/a1b2c3/image-01HQ...?w=200&h=200&r=thumb

# WebP with quality
https://cdn.tzzl.io/a1b2c3/image-01HQ...?f=webp&q=80

# Face-cropped avatar
https://cdn.tzzl.io/a1b2c3/image-01HQ...?w=150&h=150&r=thumb&g=face&f=webp

# Full transformation
https://cdn.tzzl.io/a1b2c3/image-01HQ...?w=800&h=600&r=fill&g=center&f=avif&q=75