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 INLINECODE0
• 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

CODEBLOCK0

Options

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

CODEBLOCK1

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

1. 1. Receive brief with vague style or mentioned inspiration
2. Translate query to English — Pexels works best in English
3. Run ONE search with INLINECODE14
4. Do NOT review or pick — pass ALL 3 references directly to generateimage
5. Generate with ALL references as inputimages (MANDATORY):

   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"],
     ...
   )
   

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:

1. 1. Search and download references as usual
2. Send ALL reference images in a SINGLE message via sessions_send:

   sessions_send(sessionKey="<REPLY_TO>", message="5 referencias de salón editorial:\n\nArchivo: /tmp/visual-refs/ref_01_xxx.jpg\nArchivo: /tmp/visual-refs/ref_02_xxx.jpg\nArchivo: /tmp/visual-refs/ref_03_xxx.jpg\nArchivo: /tmp/visual-refs/ref_04_xxx.jpg\nArchivo: /tmp/visual-refs/ref_05_xxx.jpg\n\n¿Cuál te gusta? Puedo usar una, mezclar varias, o buscar otras.", timeoutSeconds=0)
   

1. 3. Wait for user response before generating
2. Generate with the references the user chose as INLINECODE18

CRITICAL: Send references EXACTLY ONCE. Do NOT send them individually AND again in a summary. Do NOT re-send references you already sent. One single message with all file paths, that's it.

Only use this alternative flow when the user EXPLICITLY asks to see references first. Default is always: search → pass all → generate.

Script output

• - Images downloaded to --output as ref_01_<id>.jpg, ref_02_<id>.jpg...
• INLINECODE22 with metadata: path, description, author
• Attribution printed to stdout (required by Pexels guidelines)

Limits

• - Demo plan: 50 requests/hour — more than enough for creative use
• Downloaded resolution: ~1080px (regular) — optimal for visual reference
• Attribution: required for public apps, not for internal/creative use

Effective queries

• - Always in English — better results
• Be specific: "hero shot luxury car black studio" > INLINECODE24
• Include mood: "cozy home interior warm light bokeh", INLINECODE26
• By sector: "restaurant food flat lay", "fashion editorial outdoor", INLINECODE29