Show, don't tell: a media reference library for AI generation

What a reference buys you that a prompt can't

Prompts describe; references demonstrate. "Warm diner at dusk, sodium street light through the blinds" is a paragraph of guessing. A single reference photo of exactly that light transfers the palette, the grain, the falloff — details no sentence reliably reaches.

The compounding effect is iteration count. Without references you re-roll until the model guesses your taste; with them, the first generation is already in the neighborhood, and credits go to refining instead of exploring.

This is the same reason film productions build moodboards before the shoot — the reference is the brief. LivePair just makes the brief machine-readable.

What happens to a file you upload

When you add an image or clip to your reference library, three things happen. The original lands in object storage. Its metadata — kind, labels, source — lands in the database. And a 1408-dimensional embedding from Vertex's multimodalembedding@001 lands in a vector index, in a namespace that belongs to your account and nobody else.

That embedding is the interesting part: text, images, and video share one vector space, so a written prompt can retrieve visual references directly — no manual tagging, no folder discipline.

The library holds up to 100 assets per account — images up to 8 MB, clips up to 40 MB. It's a working set, not an archive: the lookbook you actually generate from.

A generation with references, step by step

Say you write "neon-lit alley portrait, rain on the pavement" and your library already has a rainy neon photo plus a portrait lighting setup you liked. The system embeds your prompt into the same 1408-dimensional space the references live in — so "neon" and "rain" are now coordinates, not just words.

That vector queries two places at once: your private namespace and the shared moodboards. Candidates come back with scores — your rainy alley shot at 0.82, a neon-night pack frame at 0.79 — merged into one ranking. The top matches (up to four) become candidate media inputs.

Before anything reaches a model, retrieved references go through the exact gate a manual upload would: same policy check, same provider upload pipeline. Only then does the generation run — conditioned on media the search layer chose, inside a budget the model's input slots set.

If you'd rather steer: an agent can search first, show you the candidates, and pin only the ones you approve — nothing attaches until you say so.

Three ways a reference reaches the model

Pin it by id. If you know exactly which references you want — this palette, that lens feel — pass their ids in `referenceIds` and they attach to the generation inputs, up to four at a time. Deterministic, scriptable, what you want in production.

Let the prompt pick. Set `useReferences: true` and the prompt itself is embedded and matched against your library; the closest references fill any media input you left empty. Anything you attach explicitly always wins — retrieval only fills gaps.

Talk it out first. `POST /v1/agent/references/search` returns candidate references with scores and preview urls without attaching anything — so an agent or a chat UI can show you options, you pick, and the chosen ids go into the generation call. This is the flow we recommend for exploratory work: retrieval proposes, you dispose.

Moodboards: curated packs you didn't have to shoot

A moodboard is just a pile of pictures that share one look — the thing directors pin to the wall before a shoot. We publish twelve of them as shared packs, organized the way a colorist or DP would think: golden-hour, neon-night, teal-orange, noir-bw, flash-editorial, y2k, street-doc, asian-neon, vintage-film, silhouette-stage, product-clean, space-scifi.

Moodboards live in their own namespaces — readable by everyone, writable only by curation. A search can span your library and the packs at once, ranked by a single score — your own shots compete with the shared set on equal footing, and the best match wins.

An agent can do the picking end to end: list the moodboards, choose the one that fits your intent, search inside it, and pin the winners — you only have to approve the shortlist.

Every pack asset is harvested from license-clean sources — CC-licensed imagery, public-domain film archives, NASA — with source and license kept on the record.

Why isolation is structural, not a filter

Your account's reference namespace is the isolation boundary itself — not a `where user_id = …` clause that a query could forget. A retrieval request can physically only read from namespaces it's allowed: yours, plus the shared packs.

That matters more as libraries grow. A filter can be bypassed by a bug or an injection; a namespace can't leak rows it doesn't contain. Other users' references are simply not in the index your searches touch.

References also pass the same policy gate as direct uploads before a generation runs — retrieval can't smuggle media past the checks a manual upload would face.

The honest limits

Four pins per generation, one hundred assets per library, and videos larger than 8 MB can be stored and pinned by id but not semantically searched — the inline embedding ceiling is real.

Semantic search retrieves by meaning, which is exactly the feature and exactly the caveat: it finds references that look or feel like your prompt, not literal keyword matches. For exact choices, pin by id — that's what ids are for.

The reference library needs an authenticated identity — an lp_ API key or a wallet session. Anonymous pay-per-call traffic has no persistent library, because there'd be nowhere persistent to keep it.

FAQ

Is this RAG?

It's retrieval-augmented generation applied to media instead of text. The classic RAG loop — embed, index, retrieve top-k, feed into the model — runs verbatim; the retrieved objects just happen to be images and clips that condition a generation model rather than documents that ground an LLM.

Do other users' searches ever see my references?

No. Each account's references live in a dedicated vector namespace derived from its server-side identity — searches can't reach namespaces they aren't authorized for, and client-supplied scope parameters are never trusted.

What does it cost?

Library operations — upload, embed, search, list — are free. You only pay for generations that actually run, at the model's listed per-image or per-second price. Pinning references doesn't change the generation price.

How is this different from fine-tuning or a LoRA?

Fine-tuning rewrites model weights — minutes to hours, per concept, and irreversible per model version. References condition at request time: add one, remove one, swap the look between two calls. Training is the right tool for a permanent identity; references are the right tool for direction that changes per shot.

Can agents use it without the studio UI?

Yes — that's the primary surface. The MCP server exposes search_references, list_reference_packs, and a generate_image tool that accepts referenceIds and useReferences, so an agent can search, discuss options with you, and pin your picks — entirely over API.

Can the AI pick a moodboard for me?

Yes. list_reference_packs returns every curated moodboard; an agent can choose the one matching your intent, search inside it (search_references with the pack parameter), and pin the best matches. You approve the shortlist before anything attaches.