Google Images via SERP API: Field Quirks and 2-Credit Discipline

The images endpoint is the one that burns credits fastest — 2 credits per successful request, double the search endpoint — and it's also the one whose response shape will surprise you if you assume it mirrors web search. Two things to know before you write a line of code: the real endpoint path, and which fields you can actually rely on.

I hit both on a product-monitoring script last month. The endpoint path isn't what you'd guess, and title turned out to be missing on half my results. Here's the shape of it.

The endpoint path

It's POST /google/image/search — singular "image", not "images". The docs list six endpoints under /google/ and the images one is the odd one out, so if you're copy-pasting from a route list, check it. Same base URL, same X-API-Key header, same JSON body.

What you can rely on

Per the docs, every image result is guaranteed to have rank and link — "Primary link returned by the parser" — plus image_url, the full image URL. Everything else is explicitly optional:

Field	Status	What the docs say
rank	required	"1-based ranking position in this response."
link	required	"Primary link returned by the parser."
image_url	required	"Full image URL."
title	optional	"When image title or alt text is parsed."
position	optional	"Alias for rank when available."
url	optional	"Present for normalized result links."
source_url	optional	"Only when Google redirect/source URL is observed."
display_url	optional	"When Google display text or a domain can be derived."
thumbnail_url / thumbnail	optional	"When Google exposes a thumbnail."
source / domain	optional	"When source text is parsed."

The docs also warn that "some Google Images payload shapes expose rank/link but not every normalized alias" — so write your parser defensively: read the three required fields, and treat everything else as a bonus. Field definitions live in SerpBase's endpoint documentation.

The script

import requests

API = "https://api.serpbase.dev/google/image/search"
KEY = "your_api_key"   # your key here

def image_search(q: str, page: int = 1) -> list:
    resp = requests.post(API,
        headers={"X-API-Key": KEY, "Content-Type": "application/json"},
        json={"q": q, "hl": "zh-CN", "gl": "cn", "page": page},
        timeout=30)
    data = resp.json()
    if data.get("status") != 0:
        raise RuntimeError(f"{data.get('status')}: {data.get('error')}")
    return data.get("images", [])

for item in image_search("机械键盘 产品图"):
    # only trust the required fields; optional ones get .get() fallbacks
    print(item["rank"], item["image_url"][:60])
    print("  title:", item.get("title", "(none)"))
    print("  source:", item.get("source", "(none)"), item.get("domain", ""))

Three habits that keep the cost down:

1. Check status before touching images. The array is optional — "When image results are parsed" — so a zero-result query can come back with status: 0 and no images key at all. data.get("images", []) handles it; data["images"] will KeyError.
2. Budget before you loop. Each successful request is 2 credits. A 20-keyword monitoring pass is 40 credits; the 100-search free trial covers about two and a half of those. Failed requests come back with credits_charged: 0, so retries are free — but a loop that retries 20 times is still 20 round trips.
3. Don't re-fetch the same query. Unlike the search endpoint, image results for the same query are stable enough that caching by (q, hl, gl, page) pays off quickly at 2 credits a hit.

FAQ

Why does my title come back empty? It's optional — "When image title or alt text is parsed." Alt text is missing on plenty of real pages, so the parser can't always fill it. Design your display logic to work without it.

Can I use link or image_url in an <img> tag? image_url is the full image URL — that's the one for <img src>. link is the parser's primary result link, which may be a source page rather than the image file itself. And hotlinking third-party images has its own etiquette and legal considerations — check the source site's terms before embedding.

Is there a device parameter? No. device is documented only for the search endpoint. Images takes q, hl, gl, page.

Does the free trial cover images? The 100 free searches are trial credits; images requests cost 2 each, so plan roughly 50 image requests from the trial budget.

Point the script at a product keyword, print the required fields only, and see how much of the optional data your niche actually returns.