Stock Images

The stock image search gives programmatic access to the images at 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.

The endpoint searches existing images only; it never generates one. To make a new image, use the image generation endpoints (paid plans).

Licence and credit

Every image is licensed CC 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

curl "https://api.budgetpixel.com/v1/stock/images?query=misty+pine+forest&orientation=landscape&limit=5" \
  -H "Authorization: Bearer $BUDGETPIXEL_API_KEY"

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"])

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

{
  "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": "<a href=\"https://budgetpixel.com/images/mountain-goat-on-rocky-ledge-33643c7a\">Mountain Goat On Rocky Ledge</a> by <a href=\"https://budgetpixel.com\">BudgetPixel AI</a>, <a href=\"https://creativecommons.org/licenses/by/4.0/\">CC BY 4.0</a>"
      },
      "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 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.
429	`rate_limited`	More than 60 searches a minute on the account, or the general rate limits.
429	`monthly_spend_limit_reached`	The monthly spend limit you set has been reached.

Get Started

MCP

ComfyUI

WordPress

Embeds

Concepts

Stock Images

Pricing

Licence and credit

Search

Parameters

Response

From an AI agent (MCP)

Errors

​Pricing

​Licence and credit

​Search

​Parameters

​Response

​From an AI agent (MCP)

​Errors

Pricing

Licence and credit

Search

Parameters

Response

From an AI agent (MCP)

Errors