> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budgetpixel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Stock Images
> Search BudgetPixel's free stock image library from your code or AI agent — reviewed, AI-generated photos and illustrations under CC BY 4.0. Available on every plan, including Free.
The stock image search gives programmatic access to the images at
[budgetpixel.com/images](https://budgetpixel.com/images): AI-generated photos,
illustrations, backgrounds, wallpapers and textures. Every image is reviewed before it
is listed and keeps out real people, logos and text. Each result comes with download
links in several sizes and a ready-made credit line.
```
GET https://api.budgetpixel.com/v1/stock/images
```
Available on **every plan, including Free**. It is the one endpoint a Free plan's API key
can call. Everything else in the API, and generation through the MCP connector, needs a
paid plan.
## Pricing
* **10 credits per search**, from your plan's credits.
* A search is charged when it succeeds, **including one that matches nothing**. Make
queries specific rather than issuing many vague ones.
* Invalid parameters are refused with a `400` and cost nothing.
* Searches count toward the monthly spend limit you can set under
[Billing](https://budgetpixel.com/developers?tab=billing).
The endpoint searches existing images only; it never generates one. To make a new image,
use the [image generation endpoints](/concepts/models) (paid plans).
## Licence and credit
Every image is licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): you can
use it commercially, edit it, and use it in client work, provided you credit it wherever
it is used. Each result includes the credit line, so you don't have to compose one:
* `attribution.text`, for captions, video descriptions, credits pages and README files.
* `attribution.html`, for web pages. It links the image, BudgetPixel and the licence.
Download the files and serve them yourself. Don't hotlink the returned URLs from a
production app.
## Search
```bash curl theme={null}
curl "https://api.budgetpixel.com/v1/stock/images?query=misty+pine+forest&orientation=landscape&limit=5" \
-H "Authorization: Bearer $BUDGETPIXEL_API_KEY"
```
```python Python theme={null}
import os, requests
r = requests.get(
"https://api.budgetpixel.com/v1/stock/images",
headers={"Authorization": f"Bearer {os.environ['BUDGETPIXEL_API_KEY']}"},
params={"query": "misty pine forest", "orientation": "landscape", "limit": 5},
timeout=30,
)
r.raise_for_status()
for image in r.json()["data"]:
print(image["title"], image["urls"]["large"])
print(" credit:", image["attribution"]["text"])
```
```javascript Node.js theme={null}
const params = new URLSearchParams({ query: "misty pine forest", orientation: "landscape", limit: "5" });
const res = await fetch(`https://api.budgetpixel.com/v1/stock/images?${params}`, {
headers: { Authorization: `Bearer ${process.env.BUDGETPIXEL_API_KEY}` },
});
const { data } = await res.json();
for (const image of data) console.log(image.title, image.urls.large, image.attribution.text);
```
### Parameters
All parameters are optional. Send a `query`, a `category`, or both.
| Parameter | Values | What it does |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `query` | Up to 200 characters | What the image should show, in plain words. |
| `category` | `nature`, `backgrounds`, `wallpapers`, `textures`, `animals`, `food`, `travel`, `transportation`, `architecture`, `business`, `industry`, `technology`, `people`, `education`, `music`, `art`, `abstract`, `holidays`, `science`, `health`, `sports` | Limit results to one category. |
| `orientation` | `landscape`, `portrait`, `square` | Limit results to one shape. |
| `color` | `red`, `orange`, `yellow`, `green`, `turquoise`, `blue`, `purple`, `pink`, `white`, `gray`, `black`, `brown` | Limit results to one dominant colour. |
| `type` | `photo`, `illustration` | Photographs only, or illustrations (including 3D and painted art) only. |
| `sort` | `popular` (default), `newest`, `top` | With a query, `popular` puts the best matches first. `top` is highest rated. |
| `limit` | 1–20, default 20 | Results per page. The price is the same for any limit. |
| `offset` | 0–5000, default 0 | Results to skip. Fetch the next page with `offset + limit`; each page is a new search. |
Words match each image's title, tags, alt text, prompt and search keywords. When a text
query has few word matches, images found by meaning are added on the first page.
### Response
```json theme={null}
{
"object": "list",
"data": [
{
"id": "33643c7a-…",
"title": "Mountain Goat On Rocky Ledge",
"description": "A mountain goat stands on a rocky alpine ledge…",
"alt_text": "Mountain goat with curved horns standing on a rocky ledge",
"tags": ["mountain goat", "ibex", "wildlife", "rocky ledge", "alpine"],
"category": "animals",
"style": "photo",
"colors": ["gray", "brown"],
"width": 1536,
"height": 1024,
"orientation": "landscape",
"page_url": "https://budgetpixel.com/images/mountain-goat-on-rocky-ledge-33643c7a",
"urls": {
"original": "https://cdn.budgetpixel.com/image-library/mountain-goat-on-rocky-ledge-33643c7a.jpg",
"large": "https://cdn.budgetpixel.com/image-library/mountain-goat-on-rocky-ledge-33643c7a-1280.jpg",
"small": "https://cdn.budgetpixel.com/image-library/mountain-goat-on-rocky-ledge-33643c7a-640.jpg",
"large_webp": "https://cdn.budgetpixel.com/image-library/mountain-goat-on-rocky-ledge-33643c7a-1280.webp",
"small_webp": "https://cdn.budgetpixel.com/image-library/mountain-goat-on-rocky-ledge-33643c7a-640.webp"
},
"license": { "code": "CC-BY-4.0", "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" },
"attribution": {
"required": true,
"text": "“Mountain Goat On Rocky Ledge” by BudgetPixel AI (https://budgetpixel.com/images/mountain-goat-on-rocky-ledge-33643c7a) — CC BY 4.0",
"html": "Mountain Goat On Rocky Ledge by BudgetPixel AI, CC BY 4.0"
},
"ai_generated": true,
"model": "z-image-turbo",
"prompt": "mountain goat standing on a rock ledge",
"downloads": 1,
"quality_score": 8,
"created_at": "2026-09-23T22:31:04Z"
}
],
"total": 1,
"limit": 5,
"offset": 0,
"has_more": false,
"credits_charged": 10
}
```
The `urls` are the original JPG plus 1280 px and 640 px versions (the long edge), in JPG
and WebP. The files also carry the licence and credit in their embedded metadata (IPTC/XMP).
## From an AI agent (MCP)
The [MCP connector](/mcp-server) has the same search as the `search_stock_images` tool. Sign
in once, with no API key, and ask in plain words:
* *"Find a free stock photo of a misty forest for my blog header, and give me the credit line"*
* *"I need a portrait-shaped pastel background for an Instagram story"*
The tool costs the same 10 credits per search and works on every plan, including Free.
## Errors
| Status | `code` | Meaning |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| 400 | `invalid_parameter` | A parameter is out of range or not an allowed value. The message lists the allowed values. Not charged. |
| 401 | `missing_api_key` / `invalid_api_key` | No key, or an unknown or revoked key. |
| 402 | `insufficient_credits` | Your balance is under 10 credits. [Get more credits](https://budgetpixel.com/pricing). |
| 429 | `rate_limited` | More than 60 searches a minute on the account, or the general [rate limits](/concepts/rate-limits). |
| 429 | `monthly_spend_limit_reached` | The monthly spend limit you set has been reached. |