imges.dev

API Documentation

Generate custom placeholder images with a simple URL-based API

Quick Start

The simplest way to generate an image:

https://imges.dev/800x600

Or use shorthand for square images:

https://imges.dev/300
800x600 placeholder800x600
300x300 square placeholder300

URL Structure

https://imges.dev/[dimensions]/[bg-color]/[fg-color]?[params]

For square images, use shorthand: [size] instead of [dimensions]

[dimensions]

required

Format: WIDTHxHEIGHT or SIZE (for square)

Examples: 800x600, 1920x1080, 300 (creates 300x300)

[bg-color]

optional

Hex color code without # (default: cccccc)

Examples: 3b82f6, ff0000, random

[fg-color]

optional

Text color hex code without # (default: 333333)

Examples: ffffff, 000000, random

Query Parameters

text

Custom text to display on the image. Supports emojis!

/800x600?text=Hello%20World
Example: text

size

Font size in pixels (default: auto-calculated)

/800x600?text=Big%20Text&size=80
Example: size

weight

Font weight: normal, bold, or 100-900

/800x600?text=Bold&weight=bold
Example: weight

style

Font style: normal or italic

/800x600?text=Italic&style=italic
Example: style

align

Vertical alignment: top, center, bottom, or custom

/800x600?text=Top&align=top
Example: align

font

Custom font from Google Fonts library. Choose from 20+ popular fonts including Inter, Roboto, Playfair Display, and more.

/800x600?text=Fancy%20Font&font=playfair-display
Font example
View all supported fonts
Sans-Serif: inter, roboto, open-sans, lato, montserrat, poppins, raleway, nunito
Serif: playfair-display, merriweather, lora, roboto-slab
Monospace: roboto-mono, source-code-pro, fira-code, jetbrains-mono
Display: bebas-neue, lobster, pacifico, dancing-script

border

Border width in pixels

/800x600?border=10&borderColor=ff0000
Example: border

radius

Border radius in pixels for rounded corners

/800x600?text=Rounded&radius=30
Example: radius

noise

Add noise/grain texture effect (0-100). Great for vintage or textured looks.

/800x600?text=Noisy&noise=50
Example: noise

pattern

Add pattern overlay: dots, stripes, checkerboard, or grid (use with patternColor for custom colors)

/800x600?pattern=dots&patternColor=3b82f6
Dots patternStripes patternCheckerboard patternGrid pattern

format

Image format: png, jpeg, or webp (default: webp)

/800x600.png or /800x600?format=png

Advanced Features

Gradients

Use two colors separated by a dash for linear gradients

/800x600/3b82f6-8b5cf6/ffffff?text=Gradient
Gradient example

Retina (@2x)

High-resolution images for retina displays

/800x600@2x

Generates an image at 2x the specified dimensions

Random Colors

Use "random" for background or foreground colors

/800x600/random/ffffff

Each request generates a different random color

Emoji Support

Full color emoji support using Twemoji

/800x600?text=Hello%20👋%20World%20🌍
Emoji example

Font Showcase

Preview of available custom fonts from Google Fonts

Sans-Serif

InterPoppinsMontserrat

Serif

Playfair DisplayMerriweatherLora

Monospace

Fira CodeJetBrains Mono

Display

Bebas NeueDancing Script

Example URLs

/1920x1080/3b82f6-8b5cf6/ffffff?text=Hero%20Image&size=100&weight=boldHero image example
/400x300/random/ffffff?text=Card&border=5&borderColor=000000Card example

Error Handling

The API returns detailed JSON error responses when requests are invalid, helping you quickly identify and fix issues.

Error Response Format

All error responses include these fields:

{
  "error": "Error title",
  "message": "Detailed error message",
  "received": "The value you provided",
  "expected": "What we expected",
  "suggestion": "How to fix it",
  "docs": "https://imges.dev/docs",
  "examples": [
    "https://imges.dev/800x600",
    "https://imges.dev/300"
  ]
}

Common Error Examples

Invalid Dimension Format

GET /invalid

Returns: "Invalid dimension format. Expected: WIDTHxHEIGHT or SIZE (e.g., 800x600 or 300)"

Dimensions Out of Range

GET /5000x5000

Returns: "Dimensions exceed maximum allowed size. Max: 4000x4000"

Invalid Color Format

GET /800x600/invalidcolor

Returns: "Invalid hex color format. Expected: 3 or 6 hexadecimal digits (e.g., 'fff' or '3b82f6')"

Unsupported Format

GET /800x600.gif

Returns: "Unsupported image format. Supported: png, jpeg, webp"

Invalid Query Parameter

GET /800x600?border=abc

Returns: "Invalid border value. Expected: Number between 0 and 100"

Tip: When integrating the API, check the HTTP status code.200 indicates success and returns an image.400 indicates a client error with a JSON error response.500 indicates a server error.

Limits & Best Practices

  • • Maximum dimensions: 4000x4000 pixels
  • • Minimum dimensions: 1x1 pixels
  • • Maximum total pixels (after scale): 8,000,000
  • • Practical square limits: ~2828x2828 at @1x, ~1414x1414 at @2x
  • • Images are cached for optimal performance
  • • WebP format recommended for best compression
  • • URL-encode special characters in text
View ExamplesBack to Home