Overview
This article explains the logic WrkMate uses when resolving an image request. It covers the priority order, how stock searches work, when AI generation is triggered, how image dimensions are chosen, what happens when nothing is found, and how confirmation works before any file is written.
The priority order
Every image request goes through three stages in order. WrkMate stops as soon as it finds a suitable result.
Stage 1: User-uploaded assets
WrkMate checks your public_html/images/ folder first. It looks for files whose names or apparent content match the context of your request. For example, if you ask for a logo and a file called logo.png or brand-logo.jpg exists in that folder, WrkMate will offer it.
This stage only runs if you have files in that folder. If the folder is empty or does not exist, WrkMate moves immediately to stage 2.
Stage 2: Stock photo search
If no uploaded asset is suitable, WrkMate queries Unsplash and (if you have a Pexels key) Pexels. The search runs automatically for most image requests without any additional setup beyond the optional API keys.
WrkMate picks the highest-quality result from the search and downloads it to your hosting account. If the search returns no results or all results are unsuitable for the context, WrkMate moves to stage 3 only if generation has been explicitly requested. It will not fall through to generation automatically on a failed stock search.
Stage 3: AI image generation
Generation is triggered in two situations only:
- You explicitly ask for a generated image in your prompt (using words like "generate", "create", "AI image", "custom illustration", or similar).
- You have explicitly asked for generation as a fallback and no stock result was suitable.
Generation is never triggered automatically during a page build or any other task where you have not specifically requested it. If stock search fails and you did not ask for generation, WrkMate will tell you it could not find a suitable image and ask what you would like to do next.
Generation requires either an OpenAI key (for DALL-E 3) or a Google Gemini key (for Gemini Imagen) saved to your WrkMate settings. If neither key is present and generation is requested, WrkMate will explain the requirement and stop.
How the stock search works
WrkMate extracts keywords from your request and from the context of the section or page you are working on. For a request like "find a hero image for a law firm homepage", the search terms might include words like "professional", "legal", "office", and "business".
Both Unsplash and Pexels are queried if keys for both are present. Results are ranked by relevance and image quality signals (resolution, aspect ratio suitability for the target section). The top result is selected.
WrkMate adds orientation and size preferences to the query based on the intended use. Hero images are searched with a landscape preference. Portrait or profile images get a portrait preference. Square crops are used for icons and small thumbnails.
How image size is chosen
WrkMate selects a download size based on how the image will be used:
- Full-width hero or banner: Wide landscape format, minimum 1920px wide where available from the source.
- Section background: Landscape format, 1280px or larger.
- Card or feature block image: Landscape or square depending on card layout, typically 800px wide.
- Profile or portrait: Portrait orientation, typically 600x800px or similar.
- Icon: Square, typically 512x512px or the closest available from stock. For AI generation, 1024x1024px.
- Favicon source: Square, 1024x1024px, always via generation (stock photos are not suitable for favicons).
For AI-generated images, the size is set in the generation prompt directly. DALL-E 3 supports 1024x1024, 1792x1024 (wide landscape), and 1024x1792 (tall portrait). WrkMate selects the appropriate format automatically based on context.
What happens if no image is found
If all three stages fail or are unavailable for a given request, WrkMate reports what it tried and why it could not complete the task. It does not silently skip the image or insert a placeholder. Possible outcomes:
- No uploaded asset found and stock search returned no results: WrkMate reports this and asks if you want to try generation or provide a different description.
- Generation was requested but no API key is saved: WrkMate explains which key is needed and how to add it.
- Generation was requested but the API call failed: WrkMate reports the error (for example, billing limit or invalid key) and does not save any file.
Confirmation before writing to the site
Saving an image file to your hosting account is a one-step action that WrkMate confirms with you before executing. After it resolves an image, it shows you:
- The source (uploaded asset, Unsplash, Pexels, DALL-E 3, or Gemini Imagen)
- The proposed filename and save path (for example,
public_html/images/hero-bg.jpg) - A thumbnail preview if your browser supports it, or a description of the image
You then confirm or cancel. If you confirm, the file is written to your hosting account and the path is returned to you in the chat.
Inserting that path into an HTML file is a separate action. After the image is saved, you need to tell WrkMate to add it to a specific page. It will show you the exact line it plans to change and ask for confirmation again before writing to the HTML file.
If a file with the target filename already exists, WrkMate will warn you before overwriting it. You can instruct it to use a different filename or to proceed with the overwrite.
Using multiple images in one request
When you ask for images for several sections at once, WrkMate resolves them sequentially and lists all proposed saves before asking for a single confirmation. This avoids multiple back-and-forth steps. If any one image cannot be resolved, WrkMate lists it as unresolved and proceeds with the rest, giving you a full summary before asking for confirmation on the ones it did find.
