terminal monitoring api smart_toy

Online

Reference

API Documentation

Comprehensive guide to our placeholder APIs

bolt

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

info 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

Usage & Response Time

The usage dashboard at /stats shows live API call counts per endpoint. Stats are also available as JSON at GET /api-stats. Each endpoint includes avg_response_ms — a rolling average response time in milliseconds.

Webhooks (Video & PDF)

For GET /video and GET /pdf, you can pass callback_url (and optional job_id). We return 202 Accepted and generate the file in the background. When ready, we POST to your callback with job_id, status, url (one-time download), and expires_in. The download URL is single-use; the file is deleted after the first request.

CDN / Cache

Responses include Cache-Control headers per endpoint. Configuration is in config/cache_headers.php. Use these headers for CDN or browser caching.

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
• 5xx range indicate an error with our servers

AI & MCP

Use placehold.cloud from AI assistants (Cursor, Claude Desktop, etc.) via our MCP server. Send GET or POST requests to /mcp with JSON-RPC (initialize, tools/list, tools/call). No install required — add the URL in your MCP client. Full details: AI Documentation.

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.