REST API

PlacePack API Reference

Generate SVG, PNG, and WebP placeholder images over HTTP — embed in Markdown, CI pipelines, AI agent workflows, and anywhere a URL works.

Base URL: https://placepack.top/api/v1

Rate limits

30 requests / 60 seconds per IP (sliding window). Exceeded requests receive a 429 Too Many Requests response with a Retry-After header. No API key required.

Single image

GET/api/v1/{spec}

Returns image bytes directly. Embeddable in <img>, Markdown, curl, or any HTTP client.

Path format

/api/v1/{alias}:{width}x{height}.{format}
/api/v1/{width}x{height}.{format}

Query parameters

bg	hex	Background color without #. Default: 4F46E5
text	hex	Text color without #. Default: FFFFFF
padding	number	Inner padding in px. Default: 16
stroke	number	Border stroke width in px. Default: 1
template	string	Label template. Tokens: {alias} {w} {h} {ratio}. Default: {alias} {w}x{h}

Examples

# Basic SVG
curl https://placepack.top/api/v1/800x600.svg

# PNG with custom colors
curl https://placepack.top/api/v1/hero:1600x900.png?bg=0F172A&text=F8FAFC -o hero.png

# Markdown embedding
![placeholder](https://placepack.top/api/v1/400x300.svg?bg=E2E8F0&text=334155)

# JavaScript fetch
const res = await fetch('https://placepack.top/api/v1/1200x630.png?bg=4F46E5&text=FFFFFF');
const blob = await res.blob();

Python

import requests

url = "https://placepack.top/api/v1/og:1200x630.png"
params = {"bg": "4F46E5", "text": "FFFFFF", "padding": "16"}
response = requests.get(url, params=params)
with open("og.png", "wb") as f:
    f.write(response.content)

Generate ZIP pack

POST/api/v1/pack

Accepts a JSON body describing multiple images. Returns an application/zip archive.

Request body

sizes*	string	Newline-separated size specs. Same format as the UI input. Example: "hero:1600x900\nbanner:1200x400"
format	svg \| png \| webp	Output format. Default: svg. Note: WebP is browser-generated; the API serves PNG with a .png extension when webp is requested.
bgColor	hex	Background color. Default: 4F46E5
textColor	hex	Text color. Default: FFFFFF
padding	number	Padding in px. Default: 16
strokeWidth	number	Stroke width in px. Default: 1
template	string	Label template. Default: {alias} {w}x{h}

Examples

# curl
curl -X POST https://placepack.top/api/v1/pack \
  -H "Content-Type: application/json" \
  -d '{"sizes":"hero:1600x900\nbanner:1200x400\navatar:200x200","bgColor":"4F46E5","textColor":"FFFFFF","format":"png"}' \
  -o placepack.zip

# JavaScript
const res = await fetch('https://placepack.top/api/v1/pack', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sizes: 'hero:1600x900\nbanner:1200x400',
    bgColor: '0F172A',
    textColor: 'F8FAFC',
    format: 'svg',
  }),
});
const zip = await res.arrayBuffer();

Python

import requests, zipfile, io

payload = {
    "sizes": "hero:1600x900\nbanner:1200x400\navatar:200x200",
    "bgColor": "4F46E5",
    "textColor": "FFFFFF",
    "format": "png",
}
res = requests.post("https://placepack.top/api/v1/pack", json=payload)
with zipfile.ZipFile(io.BytesIO(res.content)) as zf:
    zf.extractall("placeholders/")

List presets

GET/api/v1/presets

Returns all available preset keys and their size definitions as JSON. Cached for 1 hour.

Example

curl https://placepack.top/api/v1/presets

# Response
{
  "presets": [
    { "key": "og", "label": "Open Graph", "sizes": ["og:1200x630", "1200x1200", "800x418"], "format": "svg" },
    { "key": "developers", "label": "Developers", "sizes": ["hero:1600x900", ...], "format": "svg" },
    ...
  ]
}

Size spec syntax

The same syntax works in both URL paths and sizes POST body fields.

Format	Example	Description
WxH		Fixed dimensions in pixels
alias:WxH		Labelled fixed dimensions
WxH@2x		Retina — renders at double the specified size
alias:WxH #BGCOL #TEXTCOL		Per-image color overrides (in sizes POST body)

Embed a badge

Show that your project uses PlacePack placeholders.

Markdown

[![Made with PlacePack](https://placepack.top/badge.svg)](https://placepack.top)

HTML

<a href="https://placepack.top"><img src="https://placepack.top/badge.svg" alt="Made with PlacePack" /></a>

OpenAPI spec

Machine-readable spec for client SDK generation, Swagger UI, and AI tool integrations.

openapi.yaml ↓Swagger UI ↗

Want to build visually first?

Use the generator to preview and customize, then copy the API URL or download the ZIP.

Open generator Automation persona