Skip to main content

​
Overview

The Fluxer Media Proxy is a specialized service for transforming, optimizing, and delivering media content. It handles image resizing, format conversion, video thumbnail generation, and external media proxying.

Endpoints

Browse media proxy endpoints

Image Transformations

Dynamic image resizing and format conversion

Video Processing

Thumbnail extraction and frame generation

External Media

Proxy and cache external images

​
Architecture

The media proxy is built with performance and security in mind:

​
Key Components

In-memory request coalescing prevents duplicate processing of the same media. Multiple simultaneous requests for the same resource are merged into a single operation.
Built on Sharp library for high-performance image transformations:
  • Format conversion (JPEG, PNG, WebP, AVIF)
  • Resizing and cropping
  • Quality optimization
  • Color space management
FFmpeg-based video processing:
  • Thumbnail generation
  • Frame extraction
  • Codec validation
  • Metadata extraction
Machine learning-based NSFW content detection for user-uploaded media.
Optional IP allowlist to ensure all traffic comes through Cloudflare’s edge network.

​
Base URL

The media proxy is typically deployed on a dedicated domain: 
https://media.fluxer.app
For self-hosted instances, configure the media proxy URL in your deployment config.

​
Authentication

The media proxy uses different authentication methods depending on the endpoint:

​
Public Endpoints

Public media endpoints (avatars, icons, attachments, etc.) require no authentication and can be accessed directly: 
GET https://media.fluxer.app/avatars/123456789/avatar.png?size=256

​
Internal Endpoints

Internal endpoints (metadata extraction, thumbnail generation) require authentication via a shared secret key:
​
X-Internal-Secret
string
required
Secret key configured in mediaProxy.secretKey
POST https://media.fluxer.app/_metadata
X-Internal-Secret: your_secret_key

​
External Media Proxy

External media URLs are signed using HMAC to prevent abuse: 
GET /external/{hmac_signature}/{encoded_url}
The signature is generated using the secretKey configuration.

​
Configuration

The media proxy is configured via the following options: 
config: {
  nodeEnv: 'production' | 'development',
  secretKey: string,                    // Secret for internal auth
  requireCloudflareEdge: boolean,       // Require Cloudflare IPs
  staticMode: boolean,                  // Proxy all to static bucket
  s3: {
    endpoint: string,                   // S3 endpoint URL
    region: string,                     // S3 region
    accessKeyId: string,                // S3 access key
    secretAccessKey: string,            // S3 secret key
    bucketCdn: string,                  // CDN assets bucket
    bucketUploads: string,              // User uploads bucket
    bucketStatic: string,               // Static files bucket
  },
  nsfwModelPath?: string,               // Path to NSFW model
}

​
Static Mode

When staticMode is enabled, the media proxy acts as a simple S3 proxy, forwarding all requests to the static bucket: 
staticMode: true  // Proxy all requests to s3.bucketStatic
This is useful for static site hosting where no media transformation is needed.

​
Performance Features

​
Request Coalescing

The media proxy includes intelligent request coalescing: 
// Multiple concurrent requests for the same image
GET /avatars/123/avatar.png?size=256
GET /avatars/123/avatar.png?size=256
GET /avatars/123/avatar.png?size=256

// Only processes once, all requests receive the same result

​
Caching Headers

All media responses include appropriate cache headers: 
Cache-Control: public, max-age=31536000, immutable
ETag: "abc123..."

​
Format Optimization

Images are automatically optimized:
  • JPEG: Progressive encoding, optimized quality
  • PNG: Compression level 9
  • WebP: Modern format with superior compression
  • AVIF: Next-gen format for supported clients

​
Rate Limiting

The media proxy supports rate limiting to prevent abuse: 
rateLimitConfig: {
  enabled: true,
  maxAttempts: 100,           // Max requests per window
  windowMs: 60000,            // 1 minute window
  skipPaths: ['/_health'],    // Skip health checks
}
Public media endpoints typically have higher rate limits than internal endpoints.

​
Health Check

The media proxy includes a health check endpoint: 
GET /_health
Returns: 
OK
Use this endpoint for monitoring and load balancer health checks.

​
Telemetry

The media proxy exposes telemetry information: 
GET /internal/telemetry
Returns: 
{
  "telemetry_enabled": true,
  "service": "fluxer_media_proxy",
  "timestamp": "2026-03-04T12:00:00Z"
}

​
Error Handling

The media proxy returns appropriate HTTP status codes:
  • 200 OK - Media successfully retrieved/processed
  • 400 Bad Request - Invalid parameters or malformed request
  • 403 Forbidden - IP not allowed (Cloudflare protection)
  • 404 Not Found - Media not found in storage
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Processing error

​
Error Response

Bad Request
Error responses are plain text for performance reasons.

​
Security Features

​
Cloudflare Edge Protection

When requireCloudflareEdge is enabled, the media proxy only accepts requests from Cloudflare’s IP ranges: 
requireCloudflareEdge: true
This ensures all traffic passes through Cloudflare’s DDoS protection and edge caching.

​
HMAC Signing

External media URLs are signed using HMAC-SHA256 to prevent URL tampering and ensure only authorized external media can be proxied.

​
Content Validation

All uploaded media is validated:
  • MIME type verification
  • Codec validation for videos
  • File size limits
  • Format restrictions

​
NSFW Detection

The media proxy can detect NSFW content using machine learning models to flag inappropriate content before it’s served.

​
Metrics and Tracing

The media proxy supports comprehensive observability:

​
Metrics

  • Request count and duration
  • S3 operation metrics
  • Image processing metrics
  • FFmpeg operation metrics
  • NSFW detection metrics

​
Tracing

Distributed tracing for request flows:
  • Request ingress
  • S3 operations
  • Image transformations
  • External HTTP requests

​
Next Steps

Endpoints

Explore media proxy endpoints

Image Transformations

Learn about image transformation parameters

API Reference

Return to API overview

Configuration

Configure media proxy for your deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us