API Documentation

Comprehensive guide to our placeholder APIs

Quick Start

Generate your first placeholder image in seconds:

GET https://placehold.cloud/640x320?text=Hello

GET https://placehold.cloud/p/500x300/FF5733/FFFFFF

No API key required • Free forever • 9 image formats • Production-ready

Introduction

Welcome to the placehold.cloud API documentation. Our API allows you to generate custom placeholder images (9 formats), lorem ipsum text, quotes, jokes, weather information, recipes, colors, and holdicons programmatically. This comprehensive guide will help you integrate our services into your applications with ease.

Authentication

No authentication is required to use our API. However, please be mindful of our rate limits and fair usage policy. We recommend including your application name in the User-Agent header for better request tracking and support.

Base URL

All API requests should be made to:

https://placehold.cloud

All endpoints are public and can be accessed directly via GET requests. No authentication required!

Endpoints

1. Placeholder Images

Endpoints: /p/{size}/{background}/{text_color} or /{size}

Method: GET

Parameters:

sizeDimensions (e.g., 500x300 or just 640x320)

formatpng, jpg, jpeg, webp, gif, avif, bmp, ico, svg

textCustom text

bgBackground color (short alias)

fgText color (short alias)

Examples:

/p/500x300/FF5733/FFFFFF?text=Hello+World

/640x320?text=Case+Study&bg=efefef&fg=374151

/500x300?text=Preview&format=webp

2. Lorem Ipsum

Endpoint: GET /l

paragraphsNumber of paragraphs (1-100)

formatjson, html, text

Example:

/l?paragraphs=3&format=json

3. Quotes

Endpoint: GET /q

Returns a random inspirational quote.

/q

4. Jokes

Endpoint: GET /j

Returns a random joke from our database.

/j

5. Weather

Endpoint: GET /w

cityCity name (required)

countryCountry code (required)

/w?city=London&country=GB

6. Recipes

Endpoint: GET /r

Returns random recipes from TheMealDB API.

/r

7. Colors

Endpoint: GET /c

Generate color palettes, hex codes, and named colors.

typepalette, hex, or named (default: palette)

countNumber of results (1-10, default: 5)

/c?type=palette&count=3

8. Holdicons

Endpoint: GET /h

Generate placeholder icons with text, cats, dogs, or robots.

/h?width=128&height=128&text=Hi

Rate Limits

To ensure fair usage, we limit requests to 100 per hour per IP address. If you exceed this limit, you'll receive a 429 Too Many Requests response. The response will include a Retry-After header indicating how long to wait before making another request.

Error Handling

Our API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

2xx range indicate success
4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted)
5xx range indicate an error with our servers

Support

If you have any questions or need assistance with our API, please don't hesitate to contact our support team at support@placehold.cloud. We're here to help you integrate our services seamlessly into your applications.