SEOImageOptimiser–UserDocumentation

Last updated: 7 November 2025

1. Overview

SEO Image Optimiser is a WordPress plugin that automatically optimises your Media Library images and delivers them in modern formats, without breaking your theme:

  • Optimises JPEG/PNG images and can generate WebP and AVIF variants (AVIF conversion is available via the API, Local processing for AVIF is dependant on your webhosts configuration).
  • Outputs responsive, SEO-friendly <picture> markup or server-level rewrites (Apache).
  • Adds tools directly inside the Media Library to reprocess or restore images.
  • Provides optional Smart Alt & Titles (AI) to generate alt text and titles for your images (variable monthly quota dependant on api key).
  • Keeps restorable backups of originals so you can roll back changes safely.

2. Requirements & Installation

2.1 Requirements

  • WordPress 5.8 or higher.
  • PHP 7.4 or higher.
  • Access to install plugins (WordPress Administrator role).
  • For Local AVIF/WebP: Imagick or GD with respective format support enabled on the server.

2.2 Install the Plugin

  1. Log in to your WordPress admin dashboard.
  2. Go to Plugins > Add New.
  3. Click Upload Plugin.
  4. Select seo-image-optimiser.zip from your computer.
  5. Click Install Now.
  6. Once installed, click Activate.

After activation, a new top-level admin menu SEO Image Optimiser will appear with subpages: Dashboard, Settings, Restore Originals, Smart Alt & Titles, Cloud Services.

3. How Optimisation Works

  • When you upload an image to the Media Library, the plugin hooks into the standard WordPress functions and runs its optimiser for that attachment.
  • For existing images, you can start a background job from the Dashboard. This uses a safe queue and a scheduled event (sio_cron_process_tick) to process images in batches.
  • Optimisation:
    • Adjusts JPEG/PNG quality based on your settings.
    • Generates WebP and, where enabled and supported, AVIF.
    • Stores backups of originals as filename.sio-orig so you can restore them later if required.
  • Delivery:
    • Picture mode: wraps images in <picture> with <source> elements for AVIF/WebP.
    • Rewrite mode: writes .htaccess rules (Apache) to serve next-gen formats without changing HTML.
    • Disabled: optimise files only (no output changes).
  • A small health check runs via AJAX to confirm cron scheduling, WebP/AVIF support, image library availability, upload dir writability, and current delivery mode.

4. Screens & Features

4.1 Dashboard

Go to SEO Image Optimiser > Dashboard. This is your control centre for background processing and quick stats.

  • Health panel: coloured badges showing:
    • WP cron scheduling status.
    • WebP and AVIF support (Imagick/GD).
    • Available image library (Imagick or GD).
    • Uploads directory writability.
    • Current delivery mode (Picture vs Rewrite).
  • Processing mode section: select to process images via the API or Locally on your server.
  • Progress dial: shows processed vs total images in the current job, with:
    • Start / Resume – queues images and starts background processing.
    • Pause – pauses the current job safely.
    • Status text details the current state of the plugin (e.g. “Ready”, “Processing…”, “Quota reached” for Lite API Keys).
  • Job cards: show counts for:
    • Images in queue (remaining).
    • Processed in this run.
    • Pending / not yet processed.
  • Library Snapshot: a panel that shows the total number of processable images, and how many currently have WebP and AVIF variants. Includes a Refresh button.

4.2 Settings

Go to SEO Image Optimiser > Settings. This screen controls how files are optimised and delivered.

Quality & formats

  • Quality: global JPEG/PNG quality (default 82). Lower means smaller files; the UI suggests 75–85 as a sensible range.
  • AVIF Quality (Pro): optional override for AVIF quality. If blank, the global quality is used.
  • Skip AVIF for small images: minimum width in pixels for generating AVIF. Above 0, AVIF is only created for images at or above that width to avoid tiny images being over-compressed.
  • Generate WebP / AVIF: a checkbox to toggle creation of next-gen formats alongside originals. WebP is available on supported servers; AVIF generation is available for Pro/unlimited API Keys when the server supports it.

Delivery & behaviour

  • Delivery Mode:
    • Picture – updates HTML with <picture> markup (recommended; best per-device sizing and SEO-friendly).
    • Rewrite – adds .htaccess rules for Apache to serve AVIF/WebP at server level. Outputs a Vary: Accept header. Won’t work on Nginx/IIS without equivalent rules.
    • Disabled – only optimises files on disk; no HTML or rewrite changes.
  • Preferred format when both AVIF & WebP exist: when both variants are available, choose which is preferred in the <picture> markup (AVIF by default, or WebP).
  • Container width: approximate maximum width (in pixels) of your main content area. Used when calculating sizes attributes in Picture mode to keep responsive images behaving correctly in your theme.
  • Debug mode: when enabled, extra information is logged to your PHP error_log, and an admin-bar badge (“SIO: PICTURE/REWRITE/DISABLED”) appears on the front end for admins.

Server config helpers

  • Apache rules (Rewrite mode): automatically written into .htaccess between a dedicated marker.
  • Nginx snippet: copy-and-paste config snippet shown in the UI if you’re on Nginx.
  • IIS snippet: example URL Rewrite rule snippet for IIS servers.

4.3 Media Library Tools

The plugin integrates directly with the native Media Library and attachment details panel.

  • Automatic optimisation on upload: when WordPress generates attachment metadata for an image, the plugin runs its optimiser for that image.
  • Row action: in Media > Library (list view) you’ll see an action “Optimize with SEO Image Optimiser” that queues the selected image for reprocessing.
  • Bulk action: in the Media Library bulk actions dropdown, choose “Optimize with SEO Image Optimiser” to queue multiple selected images.
  • Attachment details panel: when you open an image, a “SEO Image Optimiser” panel is injected that shows:
    • Whether WebP and/or AVIF variants exist, including approximate size.
    • Estimated savings, if available.
    • Buttons to Reprocess (re-optimise the image using current settings) and Restore Original (restore from the .sio-orig backup and remove WebP/AVIF).

4.4 Restore Originals

Go to SEO Image Optimiser > Restore Originals (or use the Restore card on the Settings screen). This section lets you scan and restore images that have backups.

  • Click Scan & Restore to search your uploads folder for images with .sio-orig backups and matching .webp/.avif files.
  • The plugin will restore the original files and remove associated next-gen variants for any images you choose to restore.
  • This is useful if you’ve changed your optimisation strategy or quality settings and want to revert specific images or chunks of your library before re-optimising.

4.5 Smart Alt & Titles (AI)

Go to SEO Image Optimiser > Smart Alt & Titles. This feature uses an external captioning service to propose alt text and titles for your images. The number of images you can process is dependent on your API Key.

  • If no API key is active, or your Lite quota is exhausted, the page displays a notice with links to activate or upgrade your API Key instead of the main UI.

Keywords & status

  • Site / brand keywords: textarea where you can enter phrases describing your brand, locations, or niche. These are blended into generated alt text.
  • Save keywords: button to save the keywords as a persistent option (used for future suggestions).
  • Generate Suggestions: main button to request AI suggestions for the current page of images.
  • Status indicator: shows states like “Ready”, “Saving keywords”, “Generating…”, “Suggestions generated. Review and click Apply.”
  • Usage indicator: text like “This month: X / Y SmartAlt suggestions” based on your api key usage data.

Filter & image table

  • Filter images: a simple filter/search bar (by text and basic status) that reloads the page with filtered results.
  • Image list: paginated table (20 images per page) showing for each image:
    • Thumbnail preview.
    • Current alt text and title.
    • Suggested alt text and title (after generation).
    • Row-level buttons to Generate a suggestion and Apply it.
  • Apply all on this page: buttons at the top and bottom to apply all currently enabled suggestions for the 20 images on screen.
  • Pagination: “Prev 20” / “Next 20” buttons to move through your Media Library attachments.
  • A safety note at the bottom reminds you that suggestions are filtered for rude/offensive language, but should still be reviewed before saving.

4.6 API Key

Go to SEO Image Optimiser > Cloud Services to save or remove your api key from a site.

  • When no API key is saved, the page shows an activation form with:
    • API key field.
    • Save API Key button (posts to a secure admin endpoint).
    • Link to fetch or purchase an API Key from the Web Wonderland store.
  • When active, the header displays:
    • API Key type (Lite, Pro, or Unlimited).
    • Connection State.
    • Masked Key details.
  • A Remove Key button lets you disconnect the API Key from this site.

5. Common Tasks

5.1 Optimise your existing Media Library

  1. Set your preferred quality and delivery options under SEO Image Optimiser > Settings.
  2. Go to SEO Image Optimiser > Dashboard.
  3. Click Start / Resume to enqueue images and begin the optimisation job.
  4. Leave the tab open while the first batch processes. Afterward, WordPress cron will continue running jobs in the background as your site receives traffic.
  5. Watch the progress ring, job cards, and library snapshot to see how many images have been processed and which formats are available.

5.2 Reprocess or restore a single image

  1. Open Media > Library.
  2. Click an image to open the attachment details panel.
  3. In the SEO Image Optimiser panel:
    • Click Reprocess to optimise again with your current settings (e.g. different quality or delivery mode).
    • Click Restore Original to roll back to the pre-optimised file and remove WebP/AVIF variants.

5.3 Generate AI alt text and titles

  1. Activate an API Key under the Cloud Services page.
  2. Go to Smart Alt & Titles.
  3. Enter your site/brand keywords and click Save keywords.
  4. Use the filter bar if desired, then click Generate Suggestions.
  5. Review suggestions row by row; click Apply to accept them, or use Apply all on this page once you’re happy.

6. Privacy & Data

  • In local mode, image optimisation and metadata updates happen on your own server and are stored in your WordPress database and uploads folder.

    Via the API, images are securely downloaded by the image api and processed then sent back for storage on your server. No data is saved after the image has been processed.
  • The plugin keeps backups of originals as .sio-orig files until you choose to restore or remove them.
  • If you enable Smart Alt, image data is sent to an external captioning service through the plugin’s configured proxy endpoint. No visitor data or tracking cookies are added by the plugin itself.
  • AI-generated alt text and titles are stored only as Media Library metadata within your site.
  • You should update your site’s privacy policy to disclose any external processing you enable (for example, AI captioning services used by Smart Alt).

7. Troubleshooting

7.1 Optimised images not appearing on the front end

  • If processed locally, check that the health panel in the Dashboard is all green.
  • Verify your delivery mode in Settings (Picture or Rewrite).
  • Clear any caching plugins and CDN cache, then hard-refresh your browser.
  • Make sure the images are loaded from the WordPress uploads folder, not hard-coded URLs in your theme or page builder.

    Images served from remote sources like CDN's or cloud storage can't be servered using rewrite or picture modes.

7.2 Cron / processing doesn’t seem to run

  • Click Start / Resume on the Dashboard at least once to schedule the cron event.
  • Confirm that your site gets regular traffic (WordPress cron requires visits to trigger).
  • In Debug mode, check your error_log for messages prefixed with [SIO].

7.3 Smart Alt quota reached (Lite)

  • The Dashboard and Smart Alt page will show that your monthly limit has been reached.
  • You can wait for the next monthly reset, or follow the upgrade link to move to a Pro/Unlimited plan.

8. Support

For help with the Web Wonderland SEO Image Optimiser, API Key questions, or feature suggestions:

  • Check the plugin readme and built-in help text on each screen.
  • Send an email to support@webwonderland.co.uk.
  • When opening a support request, include your WordPress version, PHP version, hosting type, and any relevant log messages from Debug mode.
Get in Touch