Generating Placeholder Images via REST API

Published March 10, 2026

A placeholder image API removes the manual step of opening a browser tool, configuring sizes, and downloading files. When your CI pipeline, documentation site, or AI agent needs an image, it should be a single HTTP request away. The PlacePack REST API exposes image generation as a stateless endpoint — describe what you want in the URL path and parameters, and get back raw image bytes with the correct Content-Type header.

API overview and base URL

The PlacePack API is a public REST endpoint hosted at `https://placepack.top/api/v1/`. It requires no API key and supports two primary operations:

- **Single image**: `GET /api/v1/{spec}.{format}` — returns one SVG or PNG - **Pack ZIP**: `POST /api/v1/pack` — returns a ZIP of multiple images - **Presets**: `GET /api/v1/presets` — returns the list of named presets

The API is rate-limited to 30 requests per 60 seconds per IP address. For batch generation, use the `/pack` endpoint rather than making individual requests in a loop.

Constructing the spec string

The `{spec}` path segment encodes the image dimensions and optional alias in a compact format:

- `800x600` — plain dimensions - `hero:1600x900` — alias + dimensions - `16:9@720w` — aspect ratio at a specific width - `thumb:400x400@2x` — alias + dimensions + retina multiplier

Append `.svg` or `.png` to select the output format. Query parameters control colors and text:

- `bg` — background hex color without the `#` (e.g., `bg=4F46E5`) - `text` — text hex color (e.g., `text=FFFFFF`) - `label` — custom label text (URL-encoded) - `padding` — inner padding in pixels

# Plain 800×600 PNG
GET /api/v1/800x600.png

# Named hero image with custom colors
GET /api/v1/hero:1600x900.png?bg=4F46E5&text=FFFFFF

# Aspect ratio at width
GET /api/v1/16:9@1280w.svg

# High-DPI thumbnail
GET /api/v1/thumb:400x400@2x.png

Embedding images in Markdown and HTML

Because the API returns raw image bytes, you can reference a PlacePack URL directly in an `<img>` tag or Markdown image syntax. This is useful for README files, documentation sites, and CMS previews that need placeholder images without a file upload step.

In GitHub README files, images render inline. In documentation generators like Docusaurus or VitePress, the same URL syntax works in MDX. Note that for production content you should eventually replace these with real assets — the API is rate-limited and the URL expresses your design intent, not a permanent CDN.

![Hero placeholder](https://placepack.top/api/v1/hero:1200x630.png?bg=4F46E5&text=FFFFFF)

<!-- HTML -->
<img src="https://placepack.top/api/v1/card:400x225.png" alt="Card placeholder" />

Generating packs in CI pipelines

The `/pack` endpoint accepts a JSON body and returns a ZIP file. This makes it suitable for CI pipeline steps that need to provision fixture images without manual downloads.

A typical use case: before running visual regression tests, a pipeline step calls `/pack` to generate or verify the fixture set. If the response matches the committed hash, no update is needed. If it differs, the pipeline fails and prompts a fixture refresh.

The endpoint accepts `sizes` (array of spec strings), `bgColor`, `textColor`, and `format` (`svg` or `png`). The response is a `application/zip` body with one file per spec.

curl -X POST https://placepack.top/api/v1/pack \
  -H "Content-Type: application/json" \
  -d '{
    "sizes": ["hero:1600x900", "card:400x225", "thumb:200x200"],
    "bgColor": "#4F46E5",
    "textColor": "#FFFFFF",
    "format": "png"
  }' \
  --output fixtures.zip

Using the API from AI agent workflows

AI agents that generate UI mockups or seed databases need a reliable source for placeholder images. The PlacePack API is a good fit because it is stateless, requires no authentication, and returns a predictable response for any given input.

An agent can construct the spec URL from the layout metadata it produces (component name, width, height) and embed the URL directly in the generated HTML or pass it to an image download step. Because the response is deterministic, the agent can also cache responses by URL and skip redundant network calls.

For agents that generate ZIP packs, the `/pack` endpoint is cleaner than making one request per image. A single POST with the full size list returns all images in one response.

Rate limits and best practices

The API enforces a sliding-window rate limit of 30 requests per 60 seconds per IP. To stay within this limit:

- Use the `/pack` endpoint for batch operations instead of looping over single-image requests - Cache responses locally — the same spec always returns the same image - For high-volume pipelines, generate fixtures once and commit them rather than regenerating on every run

No API key is required, so there is nothing to rotate or protect. The rate limit is sufficient for development and CI use cases.

FAQ — Frequently asked questions

Do I need an account or API key?

No. The API is public and requires no authentication. It is rate-limited to 30 requests per 60 seconds per IP address.

What image formats does the API support?

SVG, PNG, and WebP. Append .svg, .png, or .webp to the spec in the URL path. The Content-Type header in the response matches the requested format.

Can I use the API to generate a ZIP of multiple images?

Yes. POST to /api/v1/pack with a JSON body containing sizes, bgColor, textColor, and format. The response is a ZIP file containing one image per size.

Related guides

• Deterministic Test Fixtures for CI/CD Pipelines →