Visual References

Search and download visual reference images from Pexels to inspire image or video generation. Use when you need style references, mood boards, composition or color palette inspiration before generating an asset.

vdKroon@vdkroon

Install

openclaw skills install @vdkroon/visual-references

Visual References (Pexels)

Download visual references from Pexels to inspect style, mood, and composition before generating.

When to use

Use when:

The brief mentions a specific style, mood, palette, or visual reference ("I want something minimalist", "editorial style", "something like X")
The client wants aesthetic coherence with something real or existing
The brief is visually vague and searching references would improve the result

Don't use when:

The brief is straightforward with no visual ambiguity (colors, text, and layout already defined)
You already have references in input_images
It's a minor edit of a previously delivered image
The brief doesn't mention style and the image is functional/technical

Prerequisites

Requires the PEXELS_API_KEY environment variable (free Pexels API key). The script will fail if the key is not configured. Get one at https://pexels.com/api.

Basic usage

bash

python3 ~/.openclaw/workspace/skills/visual-references/scripts/visual_ref.py "QUERY" [options]

Options

Flag	Default	Description
`--count N`	5	Number of images
`--output DIR`	`/tmp/visual-refs`	Output folder
`--orientation`	—	`landscape`, `portrait`, `square`
`--list-only`	—	List URLs only, no download

Output directory rule (MANDATORY)

ALWAYS use --output /tmp/visual-refs as the output directory. Do NOT invent unique folder names like visual-refs-salon-v2, visual-refs-v3, etc. The script automatically cleans the output folder before each search, so using the same folder every time is safe and prevents accumulation of old references.

Examples

bash

# References for a real estate hero image
python3 visual_ref.py "luxury real estate minimalist nordic" --count 5 --orientation landscape --output /tmp/visual-refs

# Square thumbnails for social media
python3 visual_ref.py "personal branding outdoor golden hour" --count 5 --orientation square --output /tmp/visual-refs

# List only, no download
python3 visual_ref.py "product photography white background" --list-only

IMPORTANT: Usage limits

Maximum 3 searches per task. One main query, up to two refinements. Do NOT run dozens of searches looking for the perfect reference.
Use --count 5 (not 5) to keep it fast.
Pick the best reference from what you get and move on to generation. The references are inspiration, not the final product.

Workflow when you decide to use it

Receive brief with vague style or mentioned inspiration
Translate query to English — Pexels works best in English
Run ONE search with --count 5
Do NOT review or pick — pass ALL 3 references directly to generate_image

Generate with ALL references as input_images (MANDATORY):

text

generate_image(
  prompt: "description of the NEW asset to generate (subject, scene, format) — do NOT describe the references, the model sees them",
  input_images: ["/path/to/ref_01_xxx.jpg", "/path/to/ref_02_xxx.jpg", "/path/to/ref_03_xxx.jpg"],
  ...
)

The generation model sees all references and picks the best style elements. Your prompt describes WHAT to create, not the style — the style comes from the reference images.

IMPORTANT: Do NOT waste tokens reviewing references with read. Do NOT pick a favorite. Pass all downloaded references as input_images and let the generation model decide.

Alternative: user picks references (only when requested)

If the brief explicitly asks to see references first ("enséñame referencias", "muéstrame antes de generar", "quiero elegir yo"), use this flow instead:

Search and download references as usual

Send ALL reference images in a SINGLE message via sessions_send: