How It Works
Scanning, usage context, AI generation, and why AI Media Toolkit is built for safe bulk operations.
AI Media Toolkit is not “paste ALT into one field”. It is a media operations pipeline for WordPress sites with hundreds or thousands of images.
The big picture
flowchart LR
A[Scan library] --> B[Detect usage & language]
B --> C[Filter what to process]
C --> D[OpenAI vision API]
D --> E[Write metadata to attachment]
E --> F[Optional: SEO rename / featured image]
F --> G[Log history + backup]1. Scan
Scan images walks your Media Library (or only used images) and builds a list with:
- Current ALT, title, caption, description
- Whether metadata is incomplete
- Whether the filename looks like a camera/stock name (
IMG_1234.jpg) - Where the image is used (post, product, featured image, ACF, Bricks, etc.)
- Language (WPML / Polylang / site locale)
Scan results are cached so filters and pagination stay fast.
Why “used images only”?
Many sites have thousands of unused uploads. Processing only images referenced on the site saves API cost and focuses on SEO impact.
2. Usage context
The AI does not only “look at the picture”. It also receives context:
- Page or product title where the image appears
- Site-wide global context (your niche, tone, brand) from Settings
- Generation mode: Balanced, SEO-focused, or WCAG accessibility-first
For SEO filenames, the plugin builds a slug from product/page/post usage — not random words from the pixel content alone.
See Integrations for WooCommerce, ACF, Bricks, EtchWP, WPML.
3. AI generation
Each supported image is sent to OpenAI’s vision-capable model (default: gpt-4o-mini):
- Image (or URL) + structured prompt
- Returns ALT, title, caption, description in the detected or forced language
Smart complete fills only empty fields. Regenerate all overwrites everything (single-image action or explicit job mode).
You pay OpenAI directly (BYOK). Typical cost: a fraction of a cent per image with gpt-4o-mini.
4. Background queue (Pro)
Large libraries cannot run in one browser request. Pro runs jobs via WP-Cron:
- Configurable batch size and delay (rate limiting)
- Pause / resume / stop
- Live activity log + optional email report when finished
Job types include: missing ALT, incomplete metadata, SEO rename (bad or all), generate all + filename, fill missing featured images.
5. SEO filenames without breaking the site
WordPress and WooCommerce reference images by attachment ID, not filename.
When you SEO-rename a file:
- The ID stays the same
- The file on disk gets a new name
- Optional thumbnail regeneration and WooCommerce cache clear
- Backup snapshot before the operation
That is why rename is safer here than manually renaming files in FTP.
6. Safety layer
| Layer | Purpose |
|---|---|
| Auto-backup | Snapshot files + metadata + Woo relations before rename/replace |
| Rollback | Restore last operation from admin |
| History | Per-image log of metadata/filename changes with Restore (Pro) |
| Emergency repair | Fix attachments pointing at thumbnails or missing main files |
| Safe preview | Extra caution for destructive actions |
Backups live under wp-content/uploads/ai-media-toolkit-backups/ with directory protection — downloads go through authenticated admin handlers.
7. Quality & reports (Pro)
Analyze duplicates & quality scores your library:
- Duplicate / similar metadata groups
- Bad filenames
- Wrong language vs detected site language
- Low-quality generic text
- Broken or missing image sizes after renames
Export a CSV report for clients or archives.
Why this design?
| Problem | AIMT approach |
|---|---|
| Manual ALT is slow | Bulk queue + optional single-image control |
| Blind bulk AI is risky | Backups, history, rollback, filters |
| Rename breaks WooCommerce | Keep attachment ID; repair tools |
| Generic ALT hurts SEO | Usage context + SEO/WCAG modes |
| Agencies need trust | Reports, white-label (Agency), audit trail |