Random Image API
The Random Image API generates random images for all your placeholder and design needs. It supports custom sizes as well as custom image categories.
From 2,721 users
Applications using this API
API Status
API Response Times
Average | P50 | P75 | P90 | P95 |
|---|---|---|---|---|
| 190ms | 203ms | 249ms | 444ms | 1049ms |
Similar APIs
Didn't find what you were looking for? Suggest an improvement
/v1/randomimage GET
https://api.api-ninjas.com/v1/randomimage
Returns a random, base64-encoded image in JPEG format.
Parameters
categoryoptionalpremium onlyImage category. If set, must be one of the following:
nature,city,technology,food,still_life,abstract,wildlife.widthoptionalpremium onlyWidth of the image to generate. Must be between
1and5000. Default value is640.heightoptionalpremium onlyHeight of the image to generate. Must be between
1and5000. Default value is480.
Headers
X-Api-KeyrequiredAPI Key associated with your account.
AcceptrequiredHeader indicating the content type to accept in the result. Must be set to the following:
image/jpg.
Response
Returns a random image in JPG format. The response body is binary image data. Returns an error if the request is unsuccessful.
Sample Request Live Demo!
Try our APIs in the API playground
Sign up for a free API key to get started — no credit card required.
https://api.api-ninjas.com/v1/randomimageHeaders
X-Api-KeyLog in or sign up to get your API KeySample Response
Code Examples
1
2
3
curl -X GET "https://api.api-ninjas.com/v1/randomimage?category=wildlife" \
-H "X-Api-Key: YOUR_API_KEY" \
--output random_image.jpgIf your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.
Frequently Asked Questions
Can I use the Random Image API for commercial purposes?
Yes, but you must have a premium subscription. Commercial use of the Random Image API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.How do I get an API key and start using the Random Image API?
Sign up for a free account to instantly get your API key, then pass it in theX-Api-Keyheader on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.What happens if I exceed my quota for the month?
Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.What happens if a request to the Random Image API fails?
The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.How do I control the size and subject of the image returned?
Use the optionalwidthandheightparameters (each between1and5000, defaulting to640and480) to set dimensions, and thecategoryparameter to pick a subject:nature,city,technology,food,still_life,abstract, orwildlife. All three parameters are premium-only, so you'll need a paid plan from our pricing page to use them.What format does the Random Image API return and how do I request it?
The endpoint returns a random, base64-encoded image in JPEG format, so you must include the requiredAcceptheader set toimage/jpgon your request. The response body is binary image data, or an error if the request is unsuccessful.What are some use cases for the Random Image API?
It's ideal for generating placeholder images during web and app design, populating mockups with category-specific visuals likefoodorwildlife, and seeding test data with realistic graphics. Pair it with our Random User and Random Word APIs to build complete sample datasets, or browse all available APIs.