Placeholder Image API

API version 1.0.0 · OpenAPI 3.0.3

Free URL-based placeholder images for wireframes, prototypes, and CMS layouts. No account or API key is required. GET an image URL directly or use it as an HTML img src. Responses contain image bytes, not JSON or a hosted-image URL. PNG is the default; an extension selects JPEG, WebP, or SVG. These are geometric placeholders with text and colors, not prompt-generated photographs or illustrations. Prefer query parameters for captions and colors to avoid ambiguous path segments. URL-encode query values; encode # as %23 or omit it.

Download the OpenAPI specification

Quick start

Use a URL directly in your markup. This creates a 1200 × 630 gradient placeholder with a caption:

<img src="https://fpoimg.com/1200x630?gradient=ocean&amp;text=Blog+Cover&amp;dims=false"
     width="1200" height="630" alt="Blog cover placeholder">

Omit the extension for PNG. For other formats use URLs such as /400x300.webp?text=Card or /400x300.svg?gradient=sunset.

GET `/{square}`

Generate a square PNG

Use the same pixel size for width and height.

Example: https://fpoimg.com/300

curl 'https://fpoimg.com/300' --output placeholder

Parameters for /{square}
Parameter	Location	Type / default	Description
`square` Required	path	integer	Both dimensions in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`text`	query	string Default: `""`	Caption; supports literal \n or encoded newline characters. Raster captions wrap automatically; SVG captions do not. Ignored when a path caption is present.
`bg_color`	query	string Default: `"#C7C7C7"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence. A valid gradient replaces the background color.
`text_color`	query	string Default: `"#8F8F8F"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence.
`gradient`	query	string Default: `""`	Preset name (case-insensitive): sunset, ocean, forest, lavender, midnight, fire, sky, peach, mint, berry, coral, steel, candy, arctic, ember, twilight, spring, neon, rose, shadow. Alternatively, two CSS names or hex colors separated by a comma. Invalid or empty values use a solid background.
`gradient_angle`	query	integer	CSS-style degrees: 0=up, 90=right, 180=down, 270=left. Omit to use the preset angle, or 180 for custom gradients. Invalid integers use that same default. Ignored without a valid gradient.
`dims`	query	boolean Default: `true`	Show dimension text. Only false (case-insensitive) hides it; other values show it. Captions still render when dimensions are hidden.

Responses

200 — Generated image bytes. Embed the request URL directly in an img src.
image/png
404 — The URL does not match a route (for example, negative dimensions).
application/json
500 — Image generation failed.
text/html

GET `/{square}.{ext}`

Generate a square in a selected format

Select PNG, JPEG, WebP, or SVG with a file extension.

Example: https://fpoimg.com/300.webp?text=Avatar

curl 'https://fpoimg.com/300.webp?text=Avatar' --output placeholder

Parameters for /{square}.{ext}
Parameter	Location	Type / default	Description
`ext` Required	path	string	Output extension: png, jpg, jpeg, webp, svg. Case-insensitive. Unrecognized extensions fall back to PNG.
`square` Required	path	integer	Both dimensions in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`text`	query	string Default: `""`	Caption; supports literal \n or encoded newline characters. Raster captions wrap automatically; SVG captions do not. Ignored when a path caption is present.
`bg_color`	query	string Default: `"#C7C7C7"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence. A valid gradient replaces the background color.
`text_color`	query	string Default: `"#8F8F8F"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence.
`gradient`	query	string Default: `""`	Preset name (case-insensitive): sunset, ocean, forest, lavender, midnight, fire, sky, peach, mint, berry, coral, steel, candy, arctic, ember, twilight, spring, neon, rose, shadow. Alternatively, two CSS names or hex colors separated by a comma. Invalid or empty values use a solid background.
`gradient_angle`	query	integer	CSS-style degrees: 0=up, 90=right, 180=down, 270=left. Omit to use the preset angle, or 180 for custom gradients. Invalid integers use that same default. Ignored without a valid gradient.
`dims`	query	boolean Default: `true`	Show dimension text. Only false (case-insensitive) hides it; other values show it. Captions still render when dimensions are hidden.

Responses

200 — Generated image bytes. Embed the request URL directly in an img src.
image/png, image/jpeg, image/webp, image/svg+xml
404 — The URL does not match a route (for example, negative dimensions).
application/json
500 — Image generation failed.
text/html

GET `/{square}/{first}`

Generate a square with a path color or caption

Color-like path values select a background; other values set a caption.

Example: https://fpoimg.com/300/steelblue?text=Avatar&text_color=white

curl 'https://fpoimg.com/300/steelblue?text=Avatar&text_color=white' --output placeholder

Parameters for /{square}/{first}
Parameter	Location	Type / default	Description
`first` Required	path	string	A CSS named color or 3/6-digit hex without # sets the background. Anything else is a caption. Use ?text=red for a caption that looks like a color. A path color overrides bg_color; a path caption overrides text.
`square` Required	path	integer	Both dimensions in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`text`	query	string Default: `""`	Caption; supports literal \n or encoded newline characters. Raster captions wrap automatically; SVG captions do not. Ignored when a path caption is present.
`bg_color`	query	string Default: `"#C7C7C7"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence. A valid gradient replaces the background color.
`text_color`	query	string Default: `"#8F8F8F"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence.
`gradient`	query	string Default: `""`	Preset name (case-insensitive): sunset, ocean, forest, lavender, midnight, fire, sky, peach, mint, berry, coral, steel, candy, arctic, ember, twilight, spring, neon, rose, shadow. Alternatively, two CSS names or hex colors separated by a comma. Invalid or empty values use a solid background.
`gradient_angle`	query	integer	CSS-style degrees: 0=up, 90=right, 180=down, 270=left. Omit to use the preset angle, or 180 for custom gradients. Invalid integers use that same default. Ignored without a valid gradient.
`dims`	query	boolean Default: `true`	Show dimension text. Only false (case-insensitive) hides it; other values show it. Captions still render when dimensions are hidden.

Responses

200 — Generated image bytes. Embed the request URL directly in an img src.
image/png
404 — The URL does not match a route (for example, negative dimensions).
application/json
500 — Image generation failed.
text/html

GET `/{square}/{bg}/{text_c}`

Generate a square with path colors

Set background and text colors in the URL path. Add a caption with the text query parameter.

Example: https://fpoimg.com/300/tomato/white?text=Avatar

curl 'https://fpoimg.com/300/tomato/white?text=Avatar' --output placeholder

Parameters for /{square}/{bg}/{text_c}
Parameter	Location	Type / default	Description
`bg` Required	path	string	Background color: CSS name or 3/6-digit hex. Overrides the corresponding query color. Invalid colors use the default.
`square` Required	path	integer	Both dimensions in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`text_c` Required	path	string	Text color: CSS name or 3/6-digit hex. Overrides the corresponding query color. Invalid colors use the default.
`text`	query	string Default: `""`	Caption; supports literal \n or encoded newline characters. Raster captions wrap automatically; SVG captions do not. Ignored when a path caption is present.
`bg_color`	query	string Default: `"#C7C7C7"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence. A valid gradient replaces the background color.
`text_color`	query	string Default: `"#8F8F8F"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence.
`gradient`	query	string Default: `""`	Preset name (case-insensitive): sunset, ocean, forest, lavender, midnight, fire, sky, peach, mint, berry, coral, steel, candy, arctic, ember, twilight, spring, neon, rose, shadow. Alternatively, two CSS names or hex colors separated by a comma. Invalid or empty values use a solid background.
`gradient_angle`	query	integer	CSS-style degrees: 0=up, 90=right, 180=down, 270=left. Omit to use the preset angle, or 180 for custom gradients. Invalid integers use that same default. Ignored without a valid gradient.
`dims`	query	boolean Default: `true`	Show dimension text. Only false (case-insensitive) hides it; other values show it. Captions still render when dimensions are hidden.

Responses

200 — Generated image bytes. Embed the request URL directly in an img src.
image/png
404 — The URL does not match a route (for example, negative dimensions).
application/json
500 — Image generation failed.
text/html

GET `/{width}x{height}`

Generate a rectangular PNG

Recommended default endpoint. Customize the image using query parameters.

Example: https://fpoimg.com/800x600?gradient=ocean&text=Blog+Cover&dims=false

curl 'https://fpoimg.com/800x600?gradient=ocean&text=Blog+Cover&dims=false' --output placeholder

Parameters for /{width}x{height}
Parameter	Location	Type / default	Description
`height` Required	path	integer	Height in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`width` Required	path	integer	Width in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`text`	query	string Default: `""`	Caption; supports literal \n or encoded newline characters. Raster captions wrap automatically; SVG captions do not. Ignored when a path caption is present.
`bg_color`	query	string Default: `"#C7C7C7"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence. A valid gradient replaces the background color.
`text_color`	query	string Default: `"#8F8F8F"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence.
`gradient`	query	string Default: `""`	Preset name (case-insensitive): sunset, ocean, forest, lavender, midnight, fire, sky, peach, mint, berry, coral, steel, candy, arctic, ember, twilight, spring, neon, rose, shadow. Alternatively, two CSS names or hex colors separated by a comma. Invalid or empty values use a solid background.
`gradient_angle`	query	integer	CSS-style degrees: 0=up, 90=right, 180=down, 270=left. Omit to use the preset angle, or 180 for custom gradients. Invalid integers use that same default. Ignored without a valid gradient.
`dims`	query	boolean Default: `true`	Show dimension text. Only false (case-insensitive) hides it; other values show it. Captions still render when dimensions are hidden.

Responses

200 — Generated image bytes. Embed the request URL directly in an img src.
image/png
404 — The URL does not match a route (for example, negative dimensions).
application/json
500 — Image generation failed.
text/html

GET `/{width}x{height}.{ext}`

Generate a rectangle in a selected format

Select PNG, JPEG, WebP, or SVG with a file extension.

Example: https://fpoimg.com/800x600.svg?gradient=sunset&text=Hero&dims=false

curl 'https://fpoimg.com/800x600.svg?gradient=sunset&text=Hero&dims=false' --output placeholder

Parameters for /{width}x{height}.{ext}
Parameter	Location	Type / default	Description
`ext` Required	path	string	Output extension: png, jpg, jpeg, webp, svg. Case-insensitive. Unrecognized extensions fall back to PNG.
`height` Required	path	integer	Height in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`width` Required	path	integer	Width in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`text`	query	string Default: `""`	Caption; supports literal \n or encoded newline characters. Raster captions wrap automatically; SVG captions do not. Ignored when a path caption is present.
`bg_color`	query	string Default: `"#C7C7C7"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence. A valid gradient replaces the background color.
`text_color`	query	string Default: `"#8F8F8F"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence.
`gradient`	query	string Default: `""`	Preset name (case-insensitive): sunset, ocean, forest, lavender, midnight, fire, sky, peach, mint, berry, coral, steel, candy, arctic, ember, twilight, spring, neon, rose, shadow. Alternatively, two CSS names or hex colors separated by a comma. Invalid or empty values use a solid background.
`gradient_angle`	query	integer	CSS-style degrees: 0=up, 90=right, 180=down, 270=left. Omit to use the preset angle, or 180 for custom gradients. Invalid integers use that same default. Ignored without a valid gradient.
`dims`	query	boolean Default: `true`	Show dimension text. Only false (case-insensitive) hides it; other values show it. Captions still render when dimensions are hidden.

Responses

200 — Generated image bytes. Embed the request URL directly in an img src.
image/png, image/jpeg, image/webp, image/svg+xml
404 — The URL does not match a route (for example, negative dimensions).
application/json
500 — Image generation failed.
text/html

GET `/{width}x{height}/{first}`

Generate a rectangle with a path color or caption

Color-like path values select a background; other values set a caption. For unambiguous captions prefer the text query parameter.

Example: https://fpoimg.com/400x300/Hello%20World

curl 'https://fpoimg.com/400x300/Hello%20World' --output placeholder

Parameters for /{width}x{height}/{first}
Parameter	Location	Type / default	Description
`first` Required	path	string	A CSS named color or 3/6-digit hex without # sets the background. Anything else is a caption. Use ?text=red for a caption that looks like a color. A path color overrides bg_color; a path caption overrides text.
`height` Required	path	integer	Height in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`width` Required	path	integer	Width in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`text`	query	string Default: `""`	Caption; supports literal \n or encoded newline characters. Raster captions wrap automatically; SVG captions do not. Ignored when a path caption is present.
`bg_color`	query	string Default: `"#C7C7C7"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence. A valid gradient replaces the background color.
`text_color`	query	string Default: `"#8F8F8F"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence.
`gradient`	query	string Default: `""`	Preset name (case-insensitive): sunset, ocean, forest, lavender, midnight, fire, sky, peach, mint, berry, coral, steel, candy, arctic, ember, twilight, spring, neon, rose, shadow. Alternatively, two CSS names or hex colors separated by a comma. Invalid or empty values use a solid background.
`gradient_angle`	query	integer	CSS-style degrees: 0=up, 90=right, 180=down, 270=left. Omit to use the preset angle, or 180 for custom gradients. Invalid integers use that same default. Ignored without a valid gradient.
`dims`	query	boolean Default: `true`	Show dimension text. Only false (case-insensitive) hides it; other values show it. Captions still render when dimensions are hidden.

Responses

200 — Generated image bytes. Embed the request URL directly in an img src.
image/png
404 — The URL does not match a route (for example, negative dimensions).
application/json
500 — Image generation failed.
text/html

GET `/{width}x{height}.{ext}/{caption}`

Generate an image with a format and path caption

This caption is always treated as text, even when it matches a color name. It overrides the text query parameter.

Example: https://fpoimg.com/400x300.jpg/red?bg_color=navy&text_color=white

curl 'https://fpoimg.com/400x300.jpg/red?bg_color=navy&text_color=white' --output placeholder

Parameters for /{width}x{height}.{ext}/{caption}
Parameter	Location	Type / default	Description
`caption` Required	path	string	URL-encoded caption. Overrides the text query parameter. Supports literal \n or encoded newline characters. Raster captions wrap; SVG captions do not.
`ext` Required	path	string	Output extension: png, jpg, jpeg, webp, svg. Case-insensitive. Unrecognized extensions fall back to PNG.
`height` Required	path	integer	Height in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`width` Required	path	integer	Width in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`text`	query	string Default: `""`	Caption; supports literal \n or encoded newline characters. Raster captions wrap automatically; SVG captions do not. Ignored when a path caption is present.
`bg_color`	query	string Default: `"#C7C7C7"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence. A valid gradient replaces the background color.
`text_color`	query	string Default: `"#8F8F8F"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence.
`gradient`	query	string Default: `""`	Preset name (case-insensitive): sunset, ocean, forest, lavender, midnight, fire, sky, peach, mint, berry, coral, steel, candy, arctic, ember, twilight, spring, neon, rose, shadow. Alternatively, two CSS names or hex colors separated by a comma. Invalid or empty values use a solid background.
`gradient_angle`	query	integer	CSS-style degrees: 0=up, 90=right, 180=down, 270=left. Omit to use the preset angle, or 180 for custom gradients. Invalid integers use that same default. Ignored without a valid gradient.
`dims`	query	boolean Default: `true`	Show dimension text. Only false (case-insensitive) hides it; other values show it. Captions still render when dimensions are hidden.

Responses

200 — Generated image bytes. Embed the request URL directly in an img src.
image/png, image/jpeg, image/webp, image/svg+xml
404 — The URL does not match a route (for example, negative dimensions).
application/json
500 — Image generation failed.
text/html

GET `/{width}x{height}/{bg}/{text_c}`

Generate a rectangle with path colors

Set background and text colors in the URL path. A valid gradient replaces the background.

Example: https://fpoimg.com/400x300/tomato/white?text=Card

curl 'https://fpoimg.com/400x300/tomato/white?text=Card' --output placeholder

Parameters for /{width}x{height}/{bg}/{text_c}
Parameter	Location	Type / default	Description
`bg` Required	path	string	Background color: CSS name or 3/6-digit hex. Overrides the corresponding query color. Invalid colors use the default.
`height` Required	path	integer	Height in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`text_c` Required	path	string	Text color: CSS name or 3/6-digit hex. Overrides the corresponding query color. Invalid colors use the default.
`width` Required	path	integer	Width in pixels. Nonnegative integers are accepted and clamped to 10–5000; out-of-range values are not rejected. Negative numbers do not match the route.
`text`	query	string Default: `""`	Caption; supports literal \n or encoded newline characters. Raster captions wrap automatically; SVG captions do not. Ignored when a path caption is present.
`bg_color`	query	string Default: `"#C7C7C7"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence. A valid gradient replaces the background color.
`text_color`	query	string Default: `"#8F8F8F"`	CSS named color or 3/6-digit hex, optionally prefixed with # (encode # as %23). Invalid values fall back to the default. A corresponding path color takes precedence.
`gradient`	query	string Default: `""`	Preset name (case-insensitive): sunset, ocean, forest, lavender, midnight, fire, sky, peach, mint, berry, coral, steel, candy, arctic, ember, twilight, spring, neon, rose, shadow. Alternatively, two CSS names or hex colors separated by a comma. Invalid or empty values use a solid background.
`gradient_angle`	query	integer	CSS-style degrees: 0=up, 90=right, 180=down, 270=left. Omit to use the preset angle, or 180 for custom gradients. Invalid integers use that same default. Ignored without a valid gradient.
`dims`	query	boolean Default: `true`	Show dimension text. Only false (case-insensitive) hides it; other values show it. Captions still render when dimensions are hidden.

Responses

200 — Generated image bytes. Embed the request URL directly in an img src.
image/png
404 — The URL does not match a route (for example, negative dimensions).
application/json
500 — Image generation failed.
text/html

Placeholder Image API

Quick start

GET /{square}

Generate a square PNG

Responses

GET /{square}.{ext}

Generate a square in a selected format

Responses

GET /{square}/{first}

Generate a square with a path color or caption

Responses

GET /{square}/{bg}/{text_c}

Generate a square with path colors

Responses

GET /{width}x{height}

Generate a rectangular PNG

Responses

GET /{width}x{height}.{ext}

Generate a rectangle in a selected format

Responses

GET /{width}x{height}/{first}

Generate a rectangle with a path color or caption

Responses

GET /{width}x{height}.{ext}/{caption}

Generate an image with a format and path caption

Responses

GET /{width}x{height}/{bg}/{text_c}

Generate a rectangle with path colors

Responses

GET `/{square}`

GET `/{square}.{ext}`

GET `/{square}/{first}`

GET `/{square}/{bg}/{text_c}`

GET `/{width}x{height}`

GET `/{width}x{height}.{ext}`

GET `/{width}x{height}/{first}`

GET `/{width}x{height}.{ext}/{caption}`

GET `/{width}x{height}/{bg}/{text_c}`