Media Proxy Endpoints

Public Media Endpoints

These endpoints are publicly accessible and serve transformed media from S3 storage.

Avatar Images

Retrieve and transform user avatar images.

GET /avatars/:id/:filename

string

required

User ID

filename

string

required

Avatar filename (e.g., avatar.png)

size

number

Desired size in pixels (square output). Supported: 16, 32, 64, 128, 256, 512, 1024, 2048

format

string

Output format: jpeg, png, webp, avif. Defaults to original format.

quality

number

JPEG/WebP quality (1-100). Default: 80

Example

GET /avatars/123456789/avatar.png?size=256&format=webp

Returns a 256x256 WebP avatar image.

Guild Icons

Retrieve and transform guild (server) icon images.

GET /icons/:id/:filename

string

required

Guild ID

filename

string

required

Icon filename

Supports the same query parameters as avatars.

Guild Banners

Retrieve and transform guild banner images.

GET /banners/:id/:filename

string

required

Guild ID

filename

string

required

Banner filename

width

number

Desired width in pixels

height

number

Desired height in pixels

Guild Splashes

Retrieve guild splash images (invite backgrounds).

GET /splashes/:id/:filename
GET /embed-splashes/:id/:filename

Custom Emojis

Retrieve custom emoji images.

GET /emojis/:id

string

required

Emoji ID with extension (e.g., 123456789.png)

size

number

Desired size in pixels

Stickers

Retrieve sticker images and animations.

GET /stickers/:id

string

required

Sticker ID with extension (e.g., 123456789.png)

Stickers may be static (PNG) or animated (Lottie JSON).

Guild Member Avatars

Retrieve guild-specific member avatars.

GET /guilds/:guild_id/users/:user_id/avatars/:filename

guild_id

string

required

Guild ID

user_id

string

required

User ID

filename

string

required

Avatar filename

Guild Member Banners

Retrieve guild-specific member banners.

GET /guilds/:guild_id/users/:user_id/banners/:filename

Attachments

Retrieve message attachments with optional transformations.

GET /attachments/:channel_id/:attachment_id/:filename

channel_id

string

required

Channel ID

attachment_id

string

required

Attachment ID

filename

string

required

Original filename

size

number

For images: resize to this size

download

boolean

Force download with Content-Disposition: attachment

Example

GET /attachments/987654321/123456789/screenshot.png?size=512

Themes

Retrieve custom theme CSS files.

GET /themes/:id.css

string

required

Theme ID

Returns CSS content with Content-Type: text/css.

External Media Proxy

Proxy and cache external images with optional transformations.

GET /external/{signature}/{encoded_url}

signature

string

required

HMAC-SHA256 signature of the URL (hex encoded)

encoded_url

string

required

Base64-encoded external URL

size

number

Resize to this size (for images)

format

string

Convert to this format: jpeg, png, webp, avif

External media URLs must be signed using the media proxy’s secretKey to prevent abuse.

Signature Generation

import crypto from 'crypto';

function signExternalUrl(url, secretKey) {
  const encoded = Buffer.from(url).toString('base64url');
  const signature = crypto
    .createHmac('sha256', secretKey)
    .update(encoded)
    .digest('hex');
  return `${signature}/${encoded}`;
}

// Usage
const path = signExternalUrl('https://example.com/image.jpg', secretKey);
const proxyUrl = `https://media.fluxer.app/external/${path}?size=512`;

Internal Endpoints

These endpoints require authentication via the X-Internal-Secret header and are used for server-side media processing.

Metadata Extraction

Extract metadata from uploaded media files.

POST /_metadata
X-Internal-Secret: your_secret_key
Content-Type: application/json

url

string

required

Media URL to process (S3 URL or external URL)

type

string

Media type hint: image, video, audio

Request Example

{
  "url": "https://example.com/video.mp4",
  "type": "video"
}

Response Example

{
  "width": 1920,
  "height": 1080,
  "format": "mp4",
  "duration": 60.5,
  "size": 15728640,
  "mime_type": "video/mp4",
  "has_audio": true,
  "codec": "h264",
  "nsfw_score": 0.05,
  "nsfw_detected": false
}

Thumbnail Generation

Generate video thumbnails.

POST /_thumbnail
X-Internal-Secret: your_secret_key
Content-Type: application/json

video_url

string

required

Video URL (must be in S3 uploads bucket)

timestamp

number

Timestamp in seconds for thumbnail extraction. Default: 0

width

number

Thumbnail width. Default: 320

height

number

Thumbnail height. Default: 180

Request Example

{
  "video_url": "s3://uploads/channel_123/video.mp4",
  "timestamp": 5.0,
  "width": 640,
  "height": 360
}

Response

Returns the thumbnail image directly with Content-Type: image/jpeg.

Frame Extraction

Extract multiple frames from a video for preview/timeline generation.

POST /_frames
X-Internal-Secret: your_secret_key
Content-Type: application/json

video_url

string

required

Video URL (must be in S3 uploads bucket)

count

number

required

Number of frames to extract

width

number

Frame width. Default: 160

height

number

Frame height. Default: 90

Request Example

{
  "video_url": "s3://uploads/channel_123/video.mp4",
  "count": 10,
  "width": 160,
  "height": 90
}

Response Example

{
  "frames": [
    {
      "timestamp": 0.0,
      "data": "base64_encoded_jpeg_data"
    },
    {
      "timestamp": 6.0,
      "data": "base64_encoded_jpeg_data"
    }
    // ... more frames
  ]
}

Health and Status

Health Check

Check if the media proxy is healthy and accepting requests.

GET /_health

Returns:

OK

Status: 200 OK

Telemetry

Get service telemetry information.

GET /internal/telemetry

Returns:

{
  "telemetry_enabled": true,
  "service": "fluxer_media_proxy",
  "timestamp": "2026-03-04T12:00:00Z"
}

Image Transformation Parameters

Most image endpoints support these transformation parameters:

Size Parameters

size

number

Square size (width = height). Common values: 16, 32, 64, 128, 256, 512, 1024, 2048

width

number

Width in pixels (use with height for aspect ratio control)

height

number

Height in pixels

Format Parameters

format

string

Output format: jpeg, png, webp, avif

quality

number

Quality for lossy formats (1-100). Default: 80 for JPEG, 85 for WebP

Advanced Parameters

fit

string

How to fit the image: cover, contain, fill, inside, outside. Default: cover

position

string

Position when cropping: center, top, bottom, left, right, entropy, attention

Response Headers

All media responses include appropriate headers:

Content-Type: image/png
Cache-Control: public, max-age=31536000, immutable
ETag: "abc123..."
Content-Length: 15234
Last-Modified: Wed, 04 Mar 2026 12:00:00 GMT

Error Responses

Error responses are plain text for performance:

400 Bad Request - Invalid parameters
403 Forbidden - IP not allowed (Cloudflare protection)
404 Not Found - Media not found
500 Internal Server Error - Processing error

Next Steps

Media Proxy Overview

Learn about media proxy architecture

API Introduction

Return to API documentation

HTTP API

Media Proxy API

Relay Directory API

​Public Media Endpoints

​Avatar Images

​Example

​Guild Icons

​Guild Banners

​Guild Splashes

​Custom Emojis

​Stickers

​Guild Member Avatars

​Guild Member Banners

​Attachments

​Example

​Themes

​External Media Proxy

​Signature Generation

​Internal Endpoints

​Metadata Extraction

​Request Example

​Response Example

​Thumbnail Generation

​Request Example

​Response

​Frame Extraction

​Request Example

​Response Example

​Health and Status

​Health Check

​Telemetry

​Image Transformation Parameters

​Size Parameters

​Format Parameters

​Advanced Parameters

​Response Headers

​Error Responses

​Next Steps

Media Proxy Overview

API Introduction

Build docs developers (and LLMs) love

Public Media Endpoints

Avatar Images

Example

Guild Icons

Guild Banners

Guild Splashes

Custom Emojis

Stickers

Guild Member Avatars

Guild Member Banners

Attachments

Example

Themes

External Media Proxy

Signature Generation

Internal Endpoints

Metadata Extraction

Request Example

Response Example

Thumbnail Generation

Request Example

Response

Frame Extraction

Request Example

Response Example

Health and Status

Health Check

Telemetry

Image Transformation Parameters

Size Parameters

Format Parameters

Advanced Parameters

Response Headers

Error Responses

Next Steps