Citing the exact page and figure in File Search answers with visual-citation metadata

Rendering logic that resolves page + figure per sentence

This is the heart of the article. We split the answer by the grounding_supports spans and attach a page number and image reference to each. The defenses against missing metadata are baked in from the start so you can use it as is.

from google import genai
from google.genai import types
 
client = genai.Client(api_key="YOUR_GEMINI_API_KEY")
 
def build_cited_answer(response):
    """Split the answer into supported spans and attach verifiable sources."""
    cand = response.candidates[0]
    meta = getattr(cand, "grounding_metadata", None)
    answer_text = cand.content.parts[0].text
 
    # No metadata = an ungrounded answer. Return it without sources.
    if meta is None or not getattr(meta, "grounding_supports", None):
        return [{"text": answer_text, "citations": []}]
 
    chunks = meta.grounding_chunks or []
    segments = []
 
    for sup in meta.grounding_supports:
        seg = sup.segment
        citations = []
        for idx in sup.grounding_chunk_indices:
            if idx >= len(chunks):
                continue  # guard against index drift
            ctx = chunks[idx].retrieved_context
            citations.append({
                "title": ctx.title,
                "pages": getattr(ctx, "page_numbers", None),   # e.g. [12]
                "media_id": getattr(ctx, "media_id", None),    # e.g. "media/abc123"
            })
        segments.append({
            "text": answer_text[seg.start_index:seg.end_index],
            "citations": _dedupe_citations(citations),
        })
    return segments
 
 
def _dedupe_citations(citations):
    """Collapse citations that point to the same file and page."""
    seen, out = set(), []
    for c in citations:
        key = (c["title"], tuple(c["pages"] or []), c["media_id"])
        if key in seen:
            continue
        seen.add(key)
        out.append(c)
    return out

Run an answer through this and it comes out structured like so.

# Example output of build_cited_answer
[
  {
    "text": "Tokens expire after 3600 seconds.",
    "citations": [{"title": "design-spec.pdf", "pages": [12], "media_id": None}]
  },
  {
    "text": "The post-login flow is shown in the following figure.",
    "citations": [{"title": "onboarding-flow.png", "pages": None, "media_id": "media/abc123"}]
  }
]

Each sentence is now tied to "page 12 of design-spec.pdf" or "the figure in onboarding-flow.png." All that's left is rendering it.

Pulling the actual figure from a media_id

A media_id is a string identifier, not the image itself. To show a thumbnail, you need one extra step to fetch that media from the File Search store. Whether you can actually show the figure makes or breaks how convincing the citation feels.

def resolve_media_thumbnail(client, media_id):
    """Fetch displayable image bytes from a media_id. Returns None on failure."""
    if not media_id:
        return None
    try:
        # Retrieve the stored media (the retrieval API depends on store config)
        media = client.files.get(name=media_id)
        return media  # a file reference; convert to an <img> src in the UI
    except Exception as e:
        # Expired or deleted media is not a rare case
        print(f"media resolve failed for {media_id}: {e}")
        return None

Why wrap it in try/except matters in production. When you update reference data, old media_id values expire. Even a few seconds of lag between generation and rendering can produce a "media not found." If you don't swallow that exception and fall back to a text citation here, the whole citation UI crashes. I underestimated this at first and shipped a bug where figures went blank for a moment right after a store rebuild.

Turn PDF page numbers into a reader path

page_numbers is useful just displayed, but wiring it to a PDF viewer's page anchor makes it genuinely practical. Most viewers open a page via the URL fragment #page=12.

def page_anchor_url(base_pdf_url, page_numbers):
    """Turn page_numbers into a URL that opens the right PDF page."""
    if not page_numbers:
        return base_pdf_url
    # Jump to the first page; show a range separately if needed
    return f"{base_pdf_url}#page={page_numbers[0]}"
 
# Usage
url = page_anchor_url("https://example.com/docs/design-spec.pdf", [12])
# -> "https://example.com/docs/design-spec.pdf#page=12"

With that in place, a link like "design-spec.pdf p.12 ↗" sits beside each sentence, and the reader jumps to the supporting paragraph in one click. Moving from "showing" a source to "letting the reader verify" it is what these two fields really unlock.

Pitfalls you will hit in production

The implementation is less of a time sink than the operations around it. Here are the holes I fell into running File Search help references, with fixes.

That first row is the core of trustworthiness. Honestly showing in the UI that not every sentence has a source actually earns the reader's trust. Force a citation onto every line and you end up stamping "Source: foo.pdf" onto general claims that live outside the reference data — which is exactly where verification falls apart.

How well it fits your own reference data

This shines for documents with page structure (PDFs, slides) and for data where you want a figure to be the evidence. Conversely, a store of nothing but short text snippets won't carry page_numbers or media_id, and you're back to plain chunk citations. Take a quick inventory of which media your store is built from before adopting this, and you'll save the wasted effort.

Designing a multimodal store that mixes images in the first place is covered in unifying text and screenshots into one File Search. If you want the whole verification pipeline for sourced answers, citation generation and verification for sourced RAG is the foundation. And the basics of answering from your own data with File Search alone, no RAG, are in building data-grounded responses with the Gemini File Search API.

Start by dropping one PDF into File Search and running it through build_cited_answer to see whether page_numbers comes back. If the pages it returns line up with the text, your reference data is already ready to produce verifiable citations.