Try it
Run a live image search
One real call against the API — no signup, no key. Change the query, engine or country and see the grid and the raw JSON.
Endpoints & Pricing
One Endpoint, Three Rates, Five Engines
Image search is billed per call, flat. The engine you name never changes the rate, and asking for more images in the same call never costs more.
/api/images
- Eight named fields on every row
numfrom 1 to 100 in one call- Eight filters: size, type, colour …
- 112-country and ISO-639-1 targeting
format=simplefor a four-key row
At volume
- Use separate
GET /api/imagescalls - Pass filters on each request
- Stay within your account limits
- The general batch route is currently unavailable
Free to start
- Image search is free-tier eligible
- Shared with web, news and video
- Same fields as a paid call
- Growth unlocks at one $100 deposit
- Scale unlocks at one $500 deposit
- Enterprise unlocks at one $1,000 deposit
- Enterprise Plus unlocks at one $1,250 deposit
Rates and tier thresholds read from the live billing configuration on 7 September 2026. Each deposit is priced by its size, and your best deposit in a calendar month sets the price for all your deposits that month; credit you already hold keeps the price you bought it at. Refunded or charged-back amounts don't count toward your tier.
Quick Start
Search Images in One Request
One GET, one header. The path, the auth header and the response shape are the same as the rest of the catalog, so an image integration is the same code you already wrote for web search with a different URL.
# Wide, large photographs — the shape a hero image needs curl "https://apiserpent.com/api/images?q=mid+century+living+room&engine=ddg&country=us&num=40&size=large&aspect=wide" \ -H "X-API-Key: YOUR_API_KEY" # Licence-filtered, for images you intend to reuse commercially curl "https://apiserpent.com/api/images?q=solar+panel+installation&engine=yahoo&license=modifycommercial&num=30" \ -H "X-API-Key: YOUR_API_KEY" # Fresh only, localised — what a market started showing this week curl "https://apiserpent.com/api/images?q=running+shoes+2026&engine=brave&country=de&language=de&time=week&num=50" \ -H "X-API-Key: YOUR_API_KEY"
{
"success": true,
"query": "mid century living room",
"type": "images",
"engine": "ddg",
"country": "us",
"results": {
"images": [
{
"position": 1,
"title": "Mid Century Living Room with Walnut Credenza",
"thumbnail": "https://cdn.example-photos.com/thumb/mcm-living.jpg",
"original": "https://cdn.example-photos.com/full/mcm-living.jpg",
"width": 3840,
"height": 2160,
"source": "example-photos.com",
"pageUrl": "https://example-photos.com/gallery/mid-century"
}
],
"totalResults": 40
},
"meta": {
"totalImages": 40,
"elapsed": "4210ms",
"timestamp": "2026-09-07T10:47:33.000Z"
}
}
# You asked for 100 and 58 came back. The top-level `delivery` block says so, # in numbers and in plain English, on the same response. { "success": true, "results": { "images": [ /* 58 rows */ ], "totalResults": 58 }, "meta": { "totalImages": 58, "elapsed": "6180ms" }, "delivery": { "requested": 100, "returned": 58, "reason": "fewer_available", "note": "Delivered the results available for this search." } }
Read delivery.returned before you assume a short list is the whole answer. num is a ceiling, not a promise, and this block is the only thing that tells you which of the two you got. A complete answer carries no delivery block at all, so its presence is the check.
Data Fields
Eight Named Fields on Every Image Row
Named JSON, not markup you have to select against. Every key is always present, so a field the result did not carry arrives as null rather than vanishing.
Image row
- images[].position
- images[].title
- images[].thumbnail
- images[].original
- images[].width
- images[].height
- images[].source
- images[].pageUrl
- totalResults
position is the 1-based place in the grid and never skips a number. source is the host the image is published on; pageUrl is the page it sits on. Those two are what make an image list a ranking record rather than a pile of files.
Request parameters
- q — required
- engine — google, yahoo, bing, ddg, brave
- country — 112 codes, default us
- language — 2-letter ISO 639-1
- num — 1 to 100
- size, type, color, aspect, layout
- people, time, license
- timeout — seconds, lowers only
- format — full or simple
There is no pages parameter here and no freshness: image search is a single call sized with num, and its recency filter is time. timeout can tighten this call to your own SLA but never loosen it past the endpoint budget.
Sizing the response
num takes 1 to 100 and is a ceiling, not a promise — no engine has been measured returning the full 100 in a single call, so build for a short list rather than assuming a full one.
When a call comes up short it carries a top-level delivery block: requested, returned, a machine-readable reason, a plain-English note, The general batch route is currently unavailable.
What a call costs you
One image search is one charge at the flat category rate. num=100 costs exactly what num=10 costs, and so does every filter you add, so there is no reason to under-ask.
Empty responses are refunded automatically when the search could not be completed. A query that genuinely has no images is a delivered answer and is charged — GET /api/billing is the authority on what any call cost.
Filters
Eight Filters, and the Values They Accept
Image search is the one vertical where the filter is half the product: an unfiltered grid of 60 tiles is rarely the list you wanted. Every accepted value is listed here rather than described.
| Parameter | Accepted values | What it is for |
|---|---|---|
| size | small, medium, large, wallpaper |
Screen out thumbnails when you need something print- or hero-sized. |
| type | photo, clipart, lineart, animated, face, gif, transparent |
Separate photography from diagrams, icons and cut-outs. |
| color | color, bw, monochrome, red, orange, yellow, green, teal, blue, purple, pink, brown, black, gray, white |
Match a brand palette, or find the colourway a product is photographed in. |
| aspect | square, wide, tall |
Fit a slot — a 16:9 header, a square card, a vertical story frame. |
| layout | square, tall, wide |
The same intent under the spelling one engine uses for it. |
| people | face, portrait, nonportrait |
Include or exclude people — the single most common cleanup on a stock-style search. |
| time | day, week, month, year |
Recency. This endpoint has no freshness parameter; time is the recency filter. |
| license | any, cc, public, share, sharecommercial, modify, modifycommercial |
Narrow to images whose stated licence allows the reuse you have in mind. |
Values read from the request validator that serves /api/images on 7 September 2026, and cross-checked against the published parameter table in the API reference. A value we do not recognise is ignored, not rejected — the call still returns images, so check the parameter spelling rather than waiting for a 400. Filter support varies by engine and the reference carries the per-engine table; a licence filter in particular is a claim the source page made about itself, so treat it as a strong filter and not as legal clearance.
Why image results
An Image Grid Is a Ranking, and Almost Nobody Measures It
Rank trackers report ten blue links. The image tab is a second ranked surface for the same keyword, with its own winners, and it is usually the one nobody on the team is watching.
A thumbnail is not a source
The tile you see in a browser is a preview. The full-size file, the host it lives on and the page it is published on are three separate facts attached to that tile, and a screenshot carries none of them.
This endpoint returns all four on one row — thumbnail, original, source, pageUrl — plus the pixel width and height, so a result is actionable the moment it lands rather than after a second round of fetching.
The alt text that wins the slot is in the row
title is the caption or alt text the ranking image carries. Pull 50 rows for a keyword and you are reading, in the engine’s own selection, the wording that earns an image slot for that query.
That is a content brief nobody has to guess at: the phrasing, the product naming and the modifiers that already rank, sampled from the results rather than from a keyword tool.
Visual queries are commercial queries
Products, recipes, templates, interiors, apparel, tools, before-and-after — these are searched with the eyes first. For a catalogue or a marketplace, the image grid is often where the click is decided, before any blue link is read.
Measuring who owns those tiles for your top 200 terms is a share-of-voice number most competitors have never calculated, and it moves independently of your text rankings.
Your own images travel without you
source and pageUrl point at whoever is publishing an image, which is exactly what you need to find your product shots, charts and brand assets republished on sites you never licensed.
Run your asset names on a schedule, diff the host list week over week, and new republishers show up as new rows — the same call, read for a different purpose.
Use cases
What Teams Actually Pull Image Results For
Four jobs that account for most image-search traffic, and the parameters each one needs.
Image rank tracking
Log position and source for a keyword list on a schedule and you have an image-grid rank tracker: which domains hold the top tiles, where you sit, and how the order moves.
Use a large num — billing is flat, so 50 rows costs what 10 rows costs, and a deeper list is the difference between “unranked” and “rank 38”.
Brand and product monitoring
Search your product names and asset titles, then diff the source hosts between runs. New hosts are new republishers; disappearing hosts are pages that dropped or delisted.
time=week narrows a run to what surfaced recently, which turns a full sweep into a much cheaper weekly delta.
Catalogue and creative sourcing
Combine size=large, aspect=wide and a license value to shortlist candidates that already fit the slot you are filling, instead of filtering by hand afterwards.
width and height come back on the row, so an unusable file is rejected before you ever download it.
Training and evaluation sets
Run filtered image queries as separate synchronous calls within your account limits; record the source page next to each candidate file. The general batch route is currently unavailable.
Delivery as a single JSONL or CSV file means the output drops straight into a pipeline rather than into 200 separate responses.
# One line per keyword: date, keyword, our best position in the image grid (0 if absent), # and the three domains holding the top tiles. Billing is flat, so num=50 costs what num=10 does. DOMAIN="example.com" while IFS= read -r kw; do json=$(curl -s -G "https://apiserpent.com/api/images" \ --data-urlencode "q=$kw" \ -d "engine=ddg" -d "country=us" -d "num=50" \ -H "X-API-Key: $SERPENT_KEY") pos=$(echo "$json" | jq -r --arg d "$DOMAIN" \ '[.results.images[] | select((.source // "") | contains($d))][0].position // 0') top=$(echo "$json" | jq -r '[.results.images[0:3][].source] | join("|")') echo "$(date -u +%F),$kw,$pos,$top" >> image-positions.csv done < keywords.txt
A row with pos=0 means we were not in the first 50 tiles for that keyword, not that the query failed — check delivery.returned on the response if you need to tell a short list from a genuine absence.
FAQ
Image Search API Questions
position, title, thumbnail, original, width, height, source and pageUrl, alongside a totalResults count. Every key is always present — a value the result did not carry arrives as null rather than as a missing key, so one parser works whichever engine you name.
num takes 1 to 100, and it is a ceiling rather than a promise: no engine has been measured returning the full 100 in a single call. A short answer carries a top-level delivery block with requested, returned, a machine-readable reason and a plain-English note, so you can always tell a short list from a complete one. There is no pages parameter on this endpoint — image search is a single call, sized with num.
size takes small, medium, large or wallpaper. type takes photo, clipart, lineart, animated, face, gif or transparent. color takes red, orange, yellow, green, teal, blue, purple, pink, brown, black, gray or white, plus color, bw and monochrome. aspect takes square, wide or tall, layout takes square, tall or wide, people takes face, portrait or nonportrait, time takes day, week, month or year, and license takes any, cc, public, share, sharecommercial, modify or modifycommercial. A value we do not recognise is ignored rather than rejected, so the call still returns images. Filter support varies by engine — the API reference carries the per-engine table.
position, source and pageUrl are for. position is the 1-based place in the grid and never skips a number, source is the host the image is published on, and pageUrl is the page it appears on, so you can log which domains own the image slots for a keyword and watch the order move week over week. Pixel positions are a Deep Search feature and are not returned on image search.
country accepts 112 codes — us, uk, in, de, fr, jp, br, ca, au and more, with gb accepted as an alias for uk. GET /api/countries returns the full list and needs no API key. language takes a 2-letter ISO 639-1 code such as en, es, de or ja.
GET /api/images calls within your account limits. The general batch job route is currently unavailable. Each delivered call is billed at the published image rate; setting a higher num does not change that rate.
images array and the same key set a full answer carries — the shape never varies. Empty responses are refunded automatically when the search could not be completed; a query that genuinely has no images is a delivered answer and is charged. GET /api/billing is the authority on what any call cost.
Start using the Image Search API
free API calls, shared across web, news, image and video search. No card, no subscription. Image search from $0.18/1K.
Try for Free
