Visual Alchemist
The "Zen Garden" for your WordPress Media Library. This plugin uses Artificial Intelligence to read your images, understand their content, and automatically rewrite filenames, alt text, and compress them to be perfect for SEO.
Core Philosophy: We believe in "Non-Destructive Editing". Every single physical change or rename made by this plugin is backed up first. You can always revert to the original file with one click using the Time Vault.
01. Install & License
After purchasing, check your email. You will receive a receipt containing a download link for visual-alchemist.zip. Download this file to your desktop. Do not unzip it yet. WordPress handles the zip file directly.
Log in to your WordPress Admin Dashboard. Navigate to Plugins > Add New. Click the "Upload Plugin" button at the very top of the screen. Select the zip file you just downloaded and click "Install Now".
Upon activation, you will be redirected to a Setup Screen powered by Freemius (our security partner). You need to enter your License Key here to unlock the features.
Your License Key was included in the Welcome Email sent immediately after purchase. It is a long string of random characters. Copy it, paste it into the activation box, and click "Agree & Activate".
02. OpenAI Connection
Visual Alchemist acts as a bridge between your website and OpenAI's "Vision" model (the same brain behind ChatGPT). To make this connection work, you need a secret key.
Step-by-Step Guide
-
Log in to OpenAI:
Visit platform.openai.com/api-keys. You can use your existing ChatGPT account or create a new developer account. -
Add Billing Balance:
OpenAI APIs require a pre-paid balance. Go to the Billing section and add $5 or $10. (Processing an image costs fractions of a cent, so $5 will last a very long time). -
Create a New Key:
Navigate back to the API Keys section. Click the button labeled + Create new secret key. A popup will appear. Enter "Visual Alchemist" as the name. Click "Create". -
Copy the Key (Crucial!):
You will see a code starting withsk-proj-.... Copy this immediately. For security reasons, OpenAI will never show you this full code again. If you lose it, you must generate a new one. -
Save in WordPress:
Return to your WordPress Dashboard. Click Visual Alchemist in the sidebar. Click the Settings (Gear Icon) card. Paste your key into the "OpenAI API Key" field and click Save.
Are you building your site on a local computer (e.g., LocalWP, XAMPP, `.local` domain)? Usually, OpenAI cannot "see" images on your private computer.
Visual Alchemist fixes this automatically. If we detect a local environment, the plugin converts your image into a specialized code format (Base64) and sends that directly to the AI, bypassing the need for a public URL. You don't need to change any settings for this to work.
3. Language & Translation
Visual Alchemist doesn't just generate English text. It works in any language supported by GPT-4.
In the Settings panel, find the Target Language field. It defaults to "English". You can type literally anything here, and the AI will adapt its output style.
"Spanish (Mexico)"
ResultGenerated Alt Text will be in Mexican Spanish.
"Professional French"
ResultFormal French descriptions suitable for business sites.
The Homunculus
The "Homunculus" is the name of our background automation engine. Think of it as a tireless digital butler that lives in your server.
Once you activate it in the settings, the Homunculus watches your Media Library. Every time you upload a new image, the Homunculus wakes up, grabs the image, sends it to the AI for analysis, applies your compression rules, and updates the file—all without you clicking a single button.
Queue & Staggering Logic
What happens if you drag-and-drop 50 images at once? Will your server crash? No.
When you upload multiple files, the Homunculus doesn't process them all instantly. Instead, it puts them into a "Wait Room" (Queue) with a random delay (0-5 seconds) for each. This ensures your server CPU doesn't spike.
The system processes images one by one. As soon as Image A is finished, the system automatically checks the queue and triggers Image B. This creates a smooth, continuous flow that is gentle on your hosting resources.
Smart Context Intelligence
In the Homunculus and Mass Transmute settings, toggle "Use Post Title for Context" to ON.
Usually, an AI looks at an image in isolation. If you upload a photo of a cat, it names it cat-sitting.jpg. However, if that photo is for an article about "Veterinary Care", you want the filename to reflect that.
How it works: When enabled, the engine checks where you attached the image. If you are writing a blog post titled "Top 10 Coffee Shops in London", it sends that title to the AI along with the image to influence the SEO generation.
Without Context: hot-coffee-cup.jpg
With Context: london-coffee-shop-latte.jpg
Mass Transmute
While the Homunculus handles new uploads, Mass Transmute is designed to fix your history. It allows you to scan thousands of existing images and fix them in bulk.
The Browser Rule
Important: When running a Batch Transmute, you must keep the browser tab open. The process is orchestrated by your browser (Client-Side) to prevent server timeouts. If you close the tab, the batch stops (don't worry, you can resume it anytime).
Advanced Filters
The Scanner allows you to target very specific groups of images so you don't waste AI credits on images that are already perfect.
| Filter | Description |
|---|---|
| Source |
|
| Search Mode |
Contains: Standard search (e.g., find all images with "IMG"). Regex: Advanced pattern matching. Useful for developers. Example: ^DSC_\d+ finds files starting with DSC_ followed by numbers.
|
| Issue Detection |
You can ask the scanner to only show images that are broken in specific ways: Missing Alt Text Chaotic Filename |
04. Configuration Guide
Naming Patterns & SEO
How do you want your files to look? Visual Alchemist offers several "Recipes" for renaming your physical media files.
fresh-coffee-beans.jpg
The AI analyzes the image and creates the shortest, most descriptive keyword possible. Best for general SEO.
starbucks-fresh-coffee.jpg
Prefixes every image with your website's name. Excellent for branding, ensuring your brand name appears in Google Image Search.
fresh-coffee-2026-02-18.jpg
Appends the current date. Useful for news sites or photographers who need to sort files chronologically.
fresh_coffee_beans.jpg
Uses underscores instead of hyphens. Preferred by some developers and specific legacy database systems.
Optimization & Delivery
Beyond text, Visual Alchemist optimizes the physical file to ensure your site passes Google Core Web Vitals.
Stop authors from uploading 6000x4000 raw photos directly from their cameras. When enabled, the plugin checks the dimensions. If it exceeds your maximum limit (e.g., 2048px), it proportionally scales the image down before applying compression. This saves massive amounts of server disk space.
Convert bulky JPGs and PNGs into modern formats automatically. The plugin updates the WordPress database so your frontend instantly serves the new, lightweight file.
- WebP: The standard for modern web performance. Excellent compression and supported by 99% of browsers.
- AVIF: The bleeding-edge format. Up to 30% smaller than WebP with better quality. Note: AVIF and WebP are mutually exclusive toggles.
Standard WordPress image compression is often too weak. Using the Quality slider, you can dial in the exact compression level. 80% is our recommended sweet spot for visual fidelity and fast loading times.
We strongly recommend keeping this checked. PNG files often contain transparent backgrounds (like site logos). Converting a transparent PNG to WebP/AVIF can sometimes cause "halos" or white edges if the server library isn't perfect. By enabling "Skip PNGs", the plugin will aggressively optimize your photos (JPGs) but leave your delicate transparent assets alone.
Privacy & Protection
Secure your intellectual property and protect the privacy of your users and photographers.
Every time a photo is uploaded from an iPhone or DSLR camera, it contains hidden metadata called EXIF. This data includes the exact GPS coordinates of where the photo was taken, the date, and camera details. When enabled, Visual Alchemist acts as "Invisible Ink," mathematically wiping all GPS and EXIF data from the file to protect your privacy and reduce file bloat.
The "Royal Seal" feature. Protect your images from theft by automatically stamping a logo onto them during upload or batch processing.
- Requires the full
https://URL to your logo. - Pro Tip: Use a PNG with a transparent background.
- For perfect transparent blending, pre-fade your logo in Photoshop and keep the plugin's Opacity slider at 100%.
Time Vault (Backups)
The Time Vault is your safety net. Before Visual Alchemist renames or modifies a single pixel of your image, it performs a Full Snapshot.
What gets backed up?
- The original physical file (moved to a secure folder:
/visual-alchemist-backups/). - The original filename.
- The original Alt Text, Caption, and Description.
- The original Post Title and Slug.
How to Restore
If you don't like how the AI renamed a file, go to the Dashboard, look at the Time Vault widget, find the image, and click Restore. It will instantly revert everything to exactly how it was before the plugin touched it.
05. Troubleshooting
If things aren't working as expected, consult this glossary of error codes and fixes.
error_no_key
Cause: You haven't saved your OpenAI API Key yet.
Fix: Go to the Settings tab and paste your sk-... key.
429 Too Many Requests
Cause: You have run out of credits on your OpenAI account, or you are sending images too fast.
Fix: Check your billing status at OpenAI Billing. If you have credits, just wait 1 minute and click "Retry Stuck" in the Queue widget.
Sometimes WordPress "Cron" (the internal server clock) stops ticking if no one visits your site for a while.
Fix: Click the Retry Stuck button in the Dashboard widget. This forces the system to wake up and process the next item immediately.
Cause 1: The URL provided for the watermark image is broken, blocked by a firewall, or not a direct link to an image (e.g., ends in `.png`).
Cause 2: Your server is missing the PHP `GD` extension (very rare).
Fix: Check the Debug Logs (see below). Ensure the watermark URL opens directly in a new browser tab.
OpenAI's Vision model natively rejects `.avif` files. However, Visual Alchemist handles this for you. If you try to mass-transmute an AVIF file, the plugin silently generates a tiny, temporary JPEG in the background, shows that to the AI to get the SEO data, and then deletes the temp file. You do not need to change any settings.
If you are technical, you can see exactly what is happening under the hood. In the Dashboard, look at the bottom-right of the Homunculus Queue widget for a tiny button labeled 🐞 Show Debug Logs. This reveals the raw server output and will tell you exactly why a process failed.