Use this file to discover all available pages before exploring further.
PixelRAG offers two paths to visual retrieval. The hosted track lets you search a pre-built index of 8.28M Wikipedia pages at api.pixelrag.ai with a single curl command — no installation, no API key. The local track walks you through installing the pipeline, writing a config file, and building a searchable FAISS index from your own PDFs or web pages. Pick the track that fits your goal.
Prefer to follow along in a notebook? Open the interactive demo in Colab — it renders a page, searches the hosted index, and displays the screenshot tiles inline.
The hosted endpoint at api.pixelrag.ai serves a pre-built visual index of all 8.28M English Wikipedia pages. No setup, no API key, and no GPU required — just send a POST request.
1
Send a search query
Submit one or more natural-language queries. The n_docs parameter controls how many results are returned per query.
curl -X POST https://api.pixelrag.ai/search \ -H "Content-Type: application/json" \ -d '{"queries": [{"text": "What is the capital of France?"}], "n_docs": 5}'
2
Read the response
The API returns a list of result sets — one per query — each containing ranked hits with a similarity score and the source Wikipedia URL.
{ "results": [ { "query": "What is the capital of France?", "hits": [ { "score": 0.921, "url": "https://en.wikipedia.org/wiki/Paris", "tile": "https://api.pixelrag.ai/tiles/paris_tile_0.jpg" }, { "score": 0.887, "url": "https://en.wikipedia.org/wiki/France", "tile": "https://api.pixelrag.ai/tiles/france_tile_2.jpg" } ] } ]}
The API also accepts an image as the query for visual search — useful when you have a screenshot or diagram and want to find similar pages. See the API reference for details.
Build and serve a visual index from your own documents. The pixelrag[index] extra installs everything needed: the renderer, the embedding model, and the FAISS index builder.
1
Install the package
pip install 'pixelrag[index]'
This pulls in the core renderer, torch, transformers, faiss-cpu, and the markdown parsing utilities used by the pipeline orchestrator.
2
Create a config file
Create pixelrag.yaml in your working directory. Set source.path to a local directory of files or a single PDF. device: auto picks CUDA on Linux, MPS on macOS, and CPU as a fallback.
source: type: local path: ./my_docsembed: model: Qwen/Qwen3-VL-Embedding-2B device: auto # cuda on Linux, mps on macOS, cpu as fallbackoutput: ./my_index
3
Build the index
The index build command orchestrates all stages — render, chunk, embed, and build-index — end-to-end.
pixelrag index build
Index build time depends on document count and hardware. Expect roughly 3 minutes for a short PDF on Apple M-series and under 1 minute on a GPU.
The pixelrag_render package exposes a simple Python API for rendering URLs and PDFs to screenshot tiles. render_url returns a list of Path objects pointing to the created tile directories.
from pixelrag_render import render_url# Render a single URL to JPEG tiles in ./tiles/tile_dirs = render_url("https://en.wikipedia.org/wiki/Python", "./tiles")# Each element is a Path to a directory of tile images for that pagefor tile_dir in tile_dirs: print(tile_dir)
You can tune the rendering with keyword arguments that match the CLI flags:
from pixelrag_render import render_urltile_dirs = render_url( "https://en.wikipedia.org/wiki/Python", "./tiles", backend="cdp", # "cdp" (default, fastest) or "playwright" tile_height=8192, # maximum tile height in pixels quality=85, # JPEG quality 1–100 viewport_width=875, # browser viewport width in pixels workers=1, # number of parallel browser processes)
To render multiple URLs in one call, use render_urls instead:
