Brand Image API

Brand Image API

The Statsly Brand Image API provides access to official brand logos and images for various Minecraft server software. These images can be used in documentation, websites, or any other application that needs to display server software branding.

Overview

The Brand Image API serves official brand images for supported server software types. Images are automatically resized on-demand and cached for optimal performance.

• Official brand logos
• Multiple variants (light/dark, with/without text)
• Automatic resizing
• Redis caching for performance
• Multiple formats (PNG, WebP, SVG)
• Download-ready images

Endpoints

Get Brand Image

Retrieve a brand image for a specific server software.

Endpoint: GET /api/image/brand/:brand

Authentication: Not required (public endpoint)

URL Parameters

• brand (required) - Brand name (case-insensitive)
  • Available brands: papermc, velocity, folia, canvasmc, leafmc, purpurmc

Query Parameters

Parameter	Type	Default	Description
variant	string	default	Image variant (see brand-specific variants below)
size	number	original	Target size in pixels (1-2048). Maintains aspect ratio.
format	string	original	Output format (png, webp, jpg, gif)
download	string	false	Set to true or 1 to download instead of display

Example Requests

examples.sh

# PaperMC with light text, 256px
curl "https://api.statsly.org/api/image/brand/papermc?variant=light&size=256"

# Velocity blue with text, 512px
curl "https://api.statsly.org/api/image/brand/velocity?variant=blue&size=512"

# Folia standard, 128px
curl "https://api.statsly.org/api/image/brand/folia?size=128"

# PaperMC dark variant, download
curl "https://api.statsly.org/api/image/brand/papermc?variant=dark&download=true"

Response

Returns an image file with appropriate Content-Type header:

• image/png for PNG files
• image/webp for WebP files
• image/svg+xml for SVG files

Get Available Brands

List all available brands and their variants.

Endpoint: GET /api/image/brand

Authentication: Not required (public endpoint)

Example Request

list.sh

curl "https://api.statsly.org/api/image/brand"

Example Response

response.json

{
  "brands": {
    "papermc": ["light", "dark", "none", "default"],
    "velocity": ["white", "blue", "blue-no-text", "white-no-text", "default"],
    "folia": ["default"],
    "canvasmc": ["default"],
    "leafmc": ["default"],
    "purpurmc": ["default"]
  }
}

Supported Brands

PaperMC

Official PaperMC brand images.

Variants:

• light - Light text variant (papermc_Text_light.webp)
• dark - Dark text variant (papermc_text_dark.webp)
• none - No text variant (papermc.webp)
• default - Default variant (same as none)

Example:

/api/image/brand/papermc?variant=light&size=256

Velocity

Official Velocity proxy brand images.

Variants:

• white - White text variant (velocity_text_white.webp)
• blue - Blue text variant (velocity_text_blue.webp)
• blue-no-text - Blue without text (velocity_blue.webp)
• white-no-text - White without text (velocity_white.webp)
• default - Default variant (same as white)

Example:

/api/image/brand/velocity?variant=blue&size=512

Folia

Official Folia brand image.

Variants:

• default - Only variant available (folia_text.png)

Example:

/api/image/brand/folia?size=128

CanvasMC

Official CanvasMC brand image.

Variants:

• default - Only variant available (canvas.png)

Example:

/api/image/brand/canvasmc?size=256

LeafMC

Official LeafMC brand image.

Variants:

• default - Only variant available (leafmc.svg)

Note: SVG format - resizing may not be fully supported.

Example:

/api/image/brand/leafmc

PurpurMC

Official PurpurMC brand image.

Variants:

• default - Only variant available (purpur.png)

Example:

/api/image/brand/purpurmc?size=256

Usage Examples

HTML Embed

Embed brand images directly in HTML:

embed.html

<img
  src="https://api.statsly.org/api/image/brand/papermc?variant=light&size=256"
  alt="PaperMC"
  width="256"
  height="256"
/>

Markdown/README

Use brand images in Markdown files:

readme.md

![PaperMC](https://api.statsly.org/api/image/brand/papermc?variant=light&size=128)
![Velocity](https://api.statsly.org/api/image/brand/velocity?variant=blue&size=128)

Download Images

Download images for offline use:

download.sh

# Download PaperMC light variant
curl -O -J "https://api.statsly.org/api/image/brand/papermc?variant=light&download=true"

# Download Velocity blue variant, 512px
curl -O -J "https://api.statsly.org/api/image/brand/velocity?variant=blue&size=512&download=true"

Image Resizing

The API automatically resizes images while maintaining aspect ratio:

• Supported formats: PNG, WebP, JPG, GIF
• SVG resizing: Limited support (may return original size)
• Size range: 1-2048 pixels
• Aspect ratio: Always maintained

Resizing Examples

resize.sh

# Small icon (64px)
curl "https://api.statsly.org/api/image/brand/papermc?size=64"

# Medium logo (256px)
curl "https://api.statsly.org/api/image/brand/papermc?size=256"

# Large banner (1024px)
curl "https://api.statsly.org/api/image/brand/papermc?size=1024"

Caching

Brand images are cached using Redis for optimal performance:

• Resized images: Cached for 1 hour
• Original images: Cached for 24 hours
• Cache key format: brand-image:{brand}:{variant}:{size}

Tip

Images are automatically cached after first request. Subsequent requests for the same image and size will be served from cache, significantly improving response times.

Performance

Best Practices

• Use appropriate sizes - larger images take longer to process
• Leverage caching - same requests are served from cache
• Consider CDN caching for frequently accessed images
• Use WebP format when possible for better compression

Response Times

• Cached requests: < 10ms
• Uncached original: < 50ms
• Uncached resized: < 200ms (depends on size)

Tip

For best performance, use sizes between 128-512 pixels. These sizes are most commonly cached and provide good quality for most use cases.

Error Handling

HTTP Status Codes

• 200 - Success (image returned)
• 400 - Bad Request (invalid size parameter)
• 404 - Not Found (brand or variant doesn’t exist)
• 500 - Internal Server Error

Error Response Format

error.json

{
  "error": "Brand not found",
  "availableBrands": ["papermc", "velocity", "folia", "canvasmc", "leafmc", "purpurmc"]
}

Example Error Handling

error-handling.js

async function getBrandImage(brand, variant, size) {
  try {
    const url = `https://api.statsly.org/api/image/brand/${brand}?variant=${variant}&size=${size}`;
    const response = await fetch(url);

    if (!response.ok) {
      if (response.status === 404) {
        const error = await response.json();
        console.error('Brand or variant not found:', error);
        return null;
      }
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const blob = await response.blob();
    return blob;
  } catch (error) {
    console.error('Failed to load brand image:', error);
    return null;
  }
}

Parameter Validation

All parameters are validated:

• brand: Must be a valid brand name (case-insensitive)
• variant: Must be a valid variant for the specified brand
• size: Must be a number between 1 and 2048
• format: Must be png, webp, jpg, or gif
• download: Must be true, 1, false, or omitted

Invalid parameters will return a 400 Bad Request or 404 Not Found response with an error message.

Rate Limiting

Brand image endpoints are public and subject to standard rate limiting:

• 100 requests per 15 minutes per IP address
• Cached responses don’t count towards rate limits
• 429 Too Many Requests if exceeded

Caution

Implement caching on your end to avoid hitting rate limits. Most use cases won’t exceed the limit, but high-traffic applications should cache images locally.

Support

For questions or issues with the Brand Image API:

• Open a support ticket
• Join our Discord community
• Check available brands: /api/image/brand