Semantic Image Search

Semantic Image Search is an open-source boilerplate from Vercel for building an AI-powered semantic image search app. It combines Next.js 14 with the Vercel AI SDK, OpenAI's GPT-4o, and Vercel's Postgres, Blob, and KV storage to index local images and let users find them by natural-language queries.

What is Semantic Image Search?

Semantic Image Search is a complete application template that turns a folder of JPEG images into a searchable web app. It takes local images as input and produces a chat-style interface where users can type a description and receive matching photos streamed from the server. The template is built on Next.js App Router and is maintained by members of the Vercel and Next.js teams, with contributors including Jared Palmer, Shu Ding, shadcn, Lars Grammel, and Nico Albanese.

Key Features

• Next.js 14 App Router — Uses React Server Components, Suspense, and Server Actions to handle data fetching and streaming UI.
• Vercel AI SDK — Provides multimodal prompting, image metadata generation, embedding, and server-to-client image streaming.
• OpenAI GPT-4o by default — The template ships with OpenAI GPT-4o as the default model; it supports switching to Gemini, Anthropic, Cohere, or custom AI chat models with a few lines of code.
• shadcn/ui and Tailwind CSS — Styled with Tailwind utility classes and built on Radix UI headless component primitives.
• Vercel Postgres + pgvector — Stores vector embeddings for semantic search using Drizzle ORM; setup requires enabling the vector extension.
• Vercel Blob storage — Uploads and serves the image files used in search results.
• Vercel KV query cache — Caches search queries to speed up repeated requests and reduce LLM costs.
• One-click Vercel deployment — Deploy to Vercel directly from the repository with an environment variable for your OpenAI API key.

Who is it for?

• Full-stack developers who want a working reference implementation of semantic search using the Vercel AI SDK and pgvector before building it into their own products.
• Solo makers and hobbyists who want to create a searchable personal photo library or an asset finder for a portfolio.
• Startup teams prototyping an AI search feature on a custom dataset who need a deployable stack with Postgres, Blob, and KV already wired together.

What can you do with Semantic Image Search?

• Search images by concept: type a description such as "a red car on a mountain road" and get relevant photos even if the images were never manually tagged.
• Build an internal media library: upload company photos, generate metadata with an LLM, and let team members query the collection in plain English.
• Learn the Vercel AI SDK and pgvector stack: study the indexing scripts and the app's server/client data flow to understand how to integrate semantic search into other Next.js projects.

How does Semantic Image Search work?

The repository includes a three-stage indexing pipeline. First, place .jpg images in the images-to-index directory and run pnpm run upload to store them in Vercel Blob. Then run pnpm run generate-metadata to have GPT-4o write a title and description for each image. Finally, run pnpm run embed-and-save to convert those descriptions into vector embeddings and store them in Vercel Postgres using pgvector.

After indexing, the app receives a user's natural-language query, embeds it, finds the closest vectors in Postgres, and streams the matching images back to the browser through the Vercel AI SDK.

FAQ

Do I need an OpenAI API key to run this template?

Yes, the default configuration uses OpenAI GPT-4o, so you must add your OpenAI API key to your environment variables. The template also lets you switch to Gemini, Anthropic, Cohere, or other AI SDK providers if you change a few lines of code.

Is the template free to use?

The source code is open source and free to clone, but you will pay for Vercel storage and database services and for API calls to your chosen LLM provider based on their usage pricing.

Which image format must the indexing files be?

The upload script expects images in .jpg format inside the images-to-index folder at the root of the application.

Can I deploy this to Vercel with one click?

Yes, the repository includes a "Deploy with Vercel" button that clones the repo and prompts you to set the required environment variables, including your OpenAI API key and the connection strings for KV, Postgres, and Blob.

Does the template support other vector databases?

The template is specifically wired for Vercel Postgres with pgvector and uses Drizzle ORM for schema management; it does not include adapters for other vector stores.