Documentation

Set it up in ten minutes.

Everything here applies to Max Image Hero on a stock WordPress install. Sections marked Pro need the Pro add-on active alongside the free plugin. Button and field names are written exactly as they appear in WordPress.

Install and first upload

Go to Plugins → Add New Plugin, search for Max Image Hero, then install and activate it.
Open Max Image Hero → Settings. Check the Optimization section — especially Max width (px) and Target file size (KB) — and make sure Auto-optimize on upload is ticked.
Upload an image as you normally would. It is resized and compressed using those settings.
Click the image in the Media Library. The attachment details now include a Max Image Hero panel for alt text, and an Edit with Max Image Hero button that opens the visual editor.

The WordPress attachment details screen with the Max Image Hero panel showing an alt text field, and an Edit with Max Image Hero button. — The Max Image Hero panel inside the attachment details.

If Original file handling is set to Ask me on every upload, a notice appears after uploading: Max Image Hero kept the original file so this edit stays reversible. Choose Keep to hold on to it, or Discard now to delete it. Discarded originals cannot be restored.

A dark notice over the media grid reading Max Image Hero kept the original file so this edit stays reversible (about 210 KB), with Keep and Discard now buttons. — The keep-or-discard notice after an upload.

Requires WordPress 6.5+ and PHP 7.4+. Works with Gutenberg, the Classic Editor and any page builder that uses the native media library.

The visual editor

Open it from Max Image Hero → Visual Editor and choose an image, or click Edit with Max Image Hero on any attachment.

The Max Image Hero visual editor with a photo loaded, a crop box and focal point marker over the image, and side panels for composition, alt text, and file and versions. — The visual editor, with the crop area and focal point set.

Crop area: Drag the box, or focus it and use the arrow keys. Tick Lock aspect ratio to keep its shape.
Zoom: Scales the image within the crop.
Focal point: The part of the image that should stay in view when it is cropped for different layouts. Click the image, use the arrow keys, or type X and Y values.
Alt text: Edit it directly, or generate it — see file names and AI vision.
When saving: Update this image edits it in place. Save as a new image leaves the original untouched and opens the new copy in the editor.

Settings

Everything lives at Max Image Hero → Settings.

Optimization

Max width (px): Uploads wider than this are resized down. Set it to 0 to turn resizing off.
Target file size (KB): Optimization aims for this size.
Quality (target): The compression quality JPEG and WebP output starts from.
Quality floor (minimum): The lowest quality it will ever use. If the target size cannot be reached above the floor, it stops at the floor rather than degrade the image further.
Auto-optimize on upload: Resizes and compresses new uploads with the settings above.
Original file handling: Ask me on every upload, Always keep the original, or Always delete the original after optimizing. Only a kept original can be restored later.

Formats, media button and accessibility

WebP conversion: Writes a WebP copy next to the original format. Support is detected from your server; if your host cannot produce WebP, the setting has no effect and the screen says so.
Add Media button mode: Augment (recommended) adds Max Image Hero alongside the normal media flow. Intercept opens the Max Image Hero studio first, with a link back to the native uploader.
Alt-text accessibility checker: Flags missing, empty or low-quality alt text in the media modal.
Remove all data on uninstall: When the plugin is deleted, also delete its settings and the data it stored on attachments, such as focal points and crops.

Alt text from file names

In the visual editor’s alt text panel, Generate Alt Text from file name turns the file name into readable text: separators become spaces, the extension is dropped, and the result is sentence-cased. Generate title from file name does the same for the title.

The visual editor with lake-at-dusk loaded: the crop area and focal point over the image, the Composition panel with zoom, focal point and crop fields, and the Alt text field reading Lake at dusk above the Generate Alt Text from file name button.

Works well: team-photo-2024.jpg → “Team photo 2024”
Does not help: IMG_20240312_101512.jpg → “Img 20240312 101512”. Camera and export names carry no meaning, so the result carries none either.

It is only as good as the file name. Use it to fill blanks quickly on well-named files, then give anything important a proper description — by hand or with AI vision.

AI vision alt text Pro

This describes what is actually in the picture, using a vision model you choose. Go to Max Image Hero → AI Alt Text:

Choose a Provider: OpenAI, Anthropic, Google, or Custom / self-hosted (OpenAI-compatible) for your own server — Ollama, vLLM, LM Studio or a gateway.
Paste your API key. It is stored encrypted and never sent back to the browser.
For a custom endpoint, fill in Endpoint URL (the API root — /chat/completions is added automatically) and pick the Auth header style.
Click Load models and pick one from the list. For a hosted provider you can leave Model blank to use a low-cost default.
Click Save settings, then Send a test image. It sends your most recent Media Library image and shows the reply.

The AI Alt Text settings screen with Anthropic selected, the stored API key masked, the model claude-sonnet-5 beside a Load models button, and a successful test reply describing a dark rocky cliff over a calm ocean. — A provider set up and a model loaded. The stored key is shown masked.

Known-good models: gpt-4o-mini, claude-haiku-4-5-20251001, gemini-2.0-flash
Turning it on: Saving a provider and key is the on switch. There is no separate checkbox.
Turning it off: Tick Remove stored key and save. No image is sent anywhere without a saved key.
Where it appears: A Generate Alt Text with AI button in the visual editor, an AI option on the Bulk Alt Text & Titles screen, and a Set alt text with AI Media Library bulk action.
Cost: Each image is one request to your provider, billed by them at their rate. We add no markup and never proxy your images.

Images are resized to 1024 px before they are sent, which keeps the cost per image down and means nothing full-resolution leaves your server. Generated text is marked AI-generated — review and edit as needed.

Bulk runs Pro

Max Image Hero → Bulk Alt Text & Titles fills the whole library at once.

Tick the fields to Fill: Alt text, Title, or both.
Under Alt text from, choose The file name or AI vision — describe the image itself. Titles always come from the file name.
Choose Only fill blanks (the safe default — it never touches text a person wrote) or Overwrite existing values.
Choose All images or Only images with no alt text.
Click Preview to see the proposed text for a sample, then Apply.

The Bulk Alt Text and Titles screen after clicking Preview, showing a table of images with their current and proposed alt text, and an Apply button. — Preview shows the first images in scope; Apply runs over all of them.

Work is saved batch by batch, with a progress bar, so a large library never times out a request. Cancel finishes the current batch and stops.
A title still counts as blank while it is the file name WordPress set on upload, so blanks-only will replace it.

The Media Library list view also gets bulk actions: Set alt text from file name, Set title from file name and, with a provider configured, Set alt text with AI, which runs behind a progress bar.

The Media Library list view with a progress window titled Generating alt text with AI, showing a progress bar and a count of images processed. — Set alt text with AI running from the Media Library.

Optimization report Pro

Max Image Hero → Optimization Report lists every image Max Image Hero has optimized on the site, and what it saved. The totals at the top — Images optimized, Original weight, After optimization and Total saved — are the numbers to put in front of a client.

The Optimization Report screen with totals for images optimized, original weight, weight after optimization and total saved, above a table of images with their original size, optimized size, saving and quality.

Each row shows the original and optimized size, the saving, the quality it settled on, and whether the original was kept. The Licensing review section lives on this screen too.

Licensing review Pro

A local check for images that look like unlicensed stock. It reads the file name and the copyright and credit fields WordPress parsed from the image’s embedded metadata on upload. It never contacts another service.

Flagged — looks like unlicensed stock: Names a paid stock agency, such as shutterstock_1288414702.jpg or Getty in the credit field.
Worth a review: A long numeric export ID, wording like “royalty free”, embedded copyright you should confirm, or a source such as Freepik or Envato whose free tier needs a visible credit.
No signals found: Nothing looked wrong. That is not the same as confirmed licensed.

Three ways to run it:

One image: the Licensing review box on the attachment edit screen — click Check now.
A selection: in the Media Library list view, choose Check for possible licensing issues from Bulk actions.
The whole library: Max Image Hero → Optimization Report, Licensing review section, Scan library. It works through the library in batches and reloads when finished.

The Licensing review section of the Optimization Report, showing how many images were checked and a table of flagged and review items with the reasons for each. — Results on the report screen, with the reason for each flag.

The Licensing review box on an attachment edit screen, showing a result badge, the reasons, when it was checked, and a Check now button. — The per-image check on the attachment edit screen.

Advisory only. The scan cannot know whether you bought a license. It points you at images a person should check. It is not legal advice.

Rename, replace, restore

All three are in the File & versions panel of the visual editor.

The File and versions panel in the visual editor, showing the title and file name fields, a note saying the file was last renamed with a Rename back button, and buttons for Rename file, Upload new version and Restore original.

Rename file: Changes the file name and every generated size. The old URL gets a 301 redirect to the new one, so existing links keep working.
Rewrite references Pro: Tick Also rewrite references to the old URL in post content to update the links in your content as well, instead of relying on the redirect.
Rename back: After a rename, the panel shows the previous name with a Rename back button that undoes it.
Upload new version: Replaces the image but keeps its file name and URL, so every page using it updates. Crop and optimization are reset.
Restore original: Undoes every crop, resize and optimization made in the editor. Needs a kept original — see Original file handling.

Your Pro license

Install and activate the free plugin first. Pro is an add-on and will not load without it.
Upload and activate Max Image Hero Pro.
Go to Max Image Hero → License, paste your License key and click Save license. The status changes to Active — Pro features unlocked.

The Max Image Hero Pro license screen showing the license key field and an Active, Pro features unlocked status.

A Multisite network counts as one site on Studio and above.
If a license lapses, Pro features switch off and updates stop. The free plugin keeps working and nothing is deleted.

Pricing and what counts as a site →

Troubleshooting

“The vision provider returned HTTP 404”: The model is not available to your key. Click Load models and pick from the list rather than typing a name — aliases ending in -latest often do not resolve.
“Could not load models — check the key and endpoint”: The key was rejected, or a custom Endpoint URL is wrong. Enter the API root only; /chat/completions is added for you.
“AI alt text is not configured”: Save a provider and a key on the AI Alt Text screen. That is what switches the feature on.
“No description came back”: The provider answered with an error. Turn on WP_DEBUG and the provider’s message is written to the debug log.
“Upload an image to the media library first”: Send a test image uses your most recent upload, so there has to be one.
The API key field shows dots: That is expected. The key is stored encrypted and never sent back to the browser. Type a new one to replace it.
WebP files are not being created: Your server cannot produce WebP. The Formats section of the settings screen says so when that is the case.
Pro screens are missing: Check that both plugins are active and that Max Image Hero → License shows Active.
“A batch failed — reload and try the rest”: Earlier batches are already saved. Reload and run again with Only fill blanks to pick up where it stopped.

Still stuck? Send us the details and we will take a look.