---
title: Profile Picture & Avatar CDN Engine
category: Avatar & Media Delivery
order: 8
badge: Media CDN
description: Complete guide to high-speed cookieless avatar delivery, SVG vector initials, dynamic fallbacks, and CDN caching.
---

# Profile Picture & Avatar CDN Engine

Ternis Auth includes a high-performance **Avatar and Media CDN Engine** designed to serve user profile images, crisp SVG vector initials, and graceful fallback silhouettes at ultra-low latency.

Media delivery is decoupled from primary authentication logic and served across dedicated cookieless CDN domains: **`user.t-cdn.de`** and **`avatar.t-cdn.de`**.

---

## 1. Dedicated CDN Domains

| Domain | Role | Optimization |
| :--- | :--- | :--- |
| **`user.t-cdn.de`** | Cookieless Media Edge | High-speed avatar delivery by UUID or handle without cookie overhead. |
| **`avatar.t-cdn.de`** | Avatar Edge Network | Vector SVG and raster avatar edge with automated initials hashing. |
| **`user.t-api.de`** | API Gateway CDN | Backwards-compatible avatar resolution and API discovery. |

---

## 2. Direct Avatar URL Patterns

Client applications can display avatars directly in HTML without making authenticated API calls or parsing JSON:

```
https://user.t-cdn.de/{user_id}.png
https://avatar.t-cdn.de/{username}.png
https://avatar.t-cdn.de/{username}.svg
```

### URL Resolution Matrix

| Resolution Type | Format Example | Content-Type | Description |
| :--- | :--- | :--- | :--- |
| **User UUID (t-CDN)** | `https://user.t-cdn.de/b2f6b897-4001-460d-8386-db93f1d8c1c4.png` | `image/png` | Fast edge delivery using user's immutable UUID. |
| **Username (t-CDN)** | `https://avatar.t-cdn.de/elena.rostova.png` | `image/png` | Direct delivery by user handle / username. |
| **Vector SVG (t-CDN)** | `https://avatar.t-cdn.de/elena.rostova.svg` | `image/svg+xml` | Crisp vector graphic with dynamically generated user initials. |
| **Short URL** | `https://auth.ternis.net/u/elena.rostova` | `image/png` | Convenient short URL for sharing and profiles. |
| **Default Silhouette** | `https://user.t-cdn.de/default.png` | `image/png` | Standard platform silhouette fallback. |

---

## 3. Query Customization Parameters

You can customize size, styling, and fallback behavior via URL query strings:

```http
GET https://avatar.t-cdn.de/elena.rostova.png?size=512&bg=4F46E5&color=FFFFFF
```

| Parameter | Aliases | Type | Range / Options | Default | Description |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `size` | `s` | Integer | `16` to `1024` | `256` | Width and height in pixels. |
| `fallback` | `d` | String | `default`, `silhouette`, `initials`, `404` | `default` | Fallback behavior when custom avatar is unset. |
| `bg` | - | Hex | `000000` to `FFFFFF` (no `#`) | Auto-hash | Custom background color. |
| `color` | `fg` | Hex | `000000` to `FFFFFF` (no `#`) | `FFFFFF` | Foreground text / silhouette color. |

---

## 4. The Graceful Fallback Guarantee (Never Broken Images)

A common issue with web applications is broken image icons (`❌`) when an avatar cannot be found.

Ternis Auth solves this with a strict **HTTP 200 Fallback Contract**:
1. When an unknown user ID or uninitialized avatar is requested, the endpoint returns **HTTP 200 OK** with a clean silhouette or generated initials.
2. The response includes diagnostic headers:
   ```http
   HTTP/1.1 200 OK
   Content-Type: image/png
   X-Ternis-User-Found: 0
   X-Ternis-Fallback: default-avatar
   ```
3. Your frontend `<img>` tags will always render smoothly.

> [!NOTE]
> If your backend needs to programmatically check whether a custom avatar exists, pass `?fallback=404`. The server will return `HTTP 404 Not Found` if no custom avatar has been uploaded.

---

## 5. HTML & Frontend Implementation

### Standard User Profile Image
```html
<img 
  src="https://user.t-cdn.de/b2f6b897-4001-460d-8386-db93f1d8c1c4.png?size=128" 
  alt="User Avatar"
  width="64"
  height="64"
  class="rounded-full border border-slate-200"
  loading="lazy"
/>
```

### High-DPI Vector Initials
```html
<img 
  src="https://avatar.t-cdn.de/elena.rostova.svg" 
  alt="Elena Rostova"
  width="48"
  height="48"
/>
```

---

## 6. Performance, Caching & CDNs

1. **HTTP Caching**:
   Avatar responses include robust cache headers:
   `Cache-Control: public, max-age=86400, stale-while-revalidate=604800, immutable`
2. **Conditional GET**:
   Responses include an `ETag`. Subsequent browser requests containing `If-None-Match` receive an instant `304 Not Modified` without data transfer.
3. **CORS Headers**:
   All avatar endpoints send `Access-Control-Allow-Origin: *`, allowing client applications to load avatars onto HTML5 `<canvas>` elements for client-side cropping or image processing without CORS violations.

---

## 7. Changing & Managing Profile Pictures

Users can manage their profile pictures both via the self-service web interface and programmatically via API.

### Via Web Account Dashboard
Navigate to `/account` in the browser:
- **Upload Image**: Choose any PNG, JPG, JPEG, WebP, SVG, or GIF file up to 5MB. The backend automatically performs centered square-cropping and high-quality compression.
- **External Image URL**: Alternatively, link an external image URL (e.g. your hosted CDN, Gravatar, or GitHub avatar).
- **Reset to Default**: One-click reset cleanly purges the stored image file and reverts back to the platform's auto-generated deterministic initials.

### Programmatic API

#### Upload or Update Avatar
```bash
# File upload
curl -X POST "https://auth.ternis.net/api/v1/user/avatar" \
  -H "Authorization: Bearer <token>" \
  -F "avatar=@/path/to/my-photo.png"

# Or link external URL
curl -X POST "https://auth.ternis.net/api/v1/user/avatar" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"avatar_url": "https://cdn.example.com/avatars/me.jpg"}'
```

#### Reset Avatar to Default
```bash
curl -X DELETE "https://auth.ternis.net/api/v1/user/avatar" \
  -H "Authorization: Bearer <token>"
```