

=== WPStack AI ALT Genius ===

Contributors: wpstack

Tags: images, alt text, seo, accessibility, media library, ai, wpstack

Requires at least: 6.0

Tested up to: 7.0

Stable tag: 1.0.0

License: GPLv2 or later

License URI: http://www.gnu.org/licenses/gpl-2.0.html

Automatically generates descriptive Alt Text, Titles, Captions, and Descriptions for your Media Library images using AI via OpenRouter, OpenAI, NVIDIA NIM, or MiniMax.

== Description ==

WPStack AI ALT Genius is a complete solution for automating image SEO and accessibility on your WordPress site. It uses Artificial Intelligence to analyze your images and generate descriptive, context-aware Alt Text, Titles, Captions, and Descriptions.

By connecting to your choice of AI provider (OpenRouter, OpenAI, NVIDIA NIM, or MiniMax), this plugin bypasses expensive monthly subscriptions, giving you direct access to the world's best AI models at the lowest possible cost.

**🚀 Key Features**

**One-Click Manual Generation:** Instantly generate metadata for individual images directly from the Media Library list view. Perfect for new uploads or refining specific images.

**Automated Background Processing:** Process your entire back catalog automatically using the built-in Cron scheduler. Configure batch sizes and intervals to suit your server's capacity.

**Context-Aware Descriptions:** The AI reads the Title and Content of the post/page the image is attached to. This ensures the generated Alt Text is relevant to your specific article, not just a generic description of the visual.

**Global Context:** Add custom instructions (e.g., "Always mention our brand name 'Acme Corp'") that apply to every image generated.

**Smart Error Handling:**

**Retry Failed:** Automatically logs failed attempts. You can retry all failed images with one click from the settings page.

**JSON Fixer:** A specialized tool to scan and fix images where the AI might have accidentally saved raw code instead of text.

**Detailed Logging:** View the exact generation timestamp, source (Manual vs Cron), and any error messages directly in the "Edit Media" screen.

**Cost Control:** You bring your own API key. You pay only for exactly what you use, with no markup.

**Format Control:** Choose exactly which file types to process (JPG, PNG, WEBP, etc.).

**🧠 Why OpenRouter?**

OpenRouter is an AI aggregator that offers significant benefits for WordPress users:

**Cheaper:** Models like Google Gemini 1.5 Flash are incredibly affordable (often fractions of a cent per image).

**Flexible:** Switch models instantly. If a new model is released tomorrow, you can simply paste its ID and use it immediately.

**No Middleman:** You use your own API key.

**💡 Context & Prompts**

You can customize exactly how the AI behaves using placeholders in your prompts:

**Examples of Global Context:**

    Inputs:
    – Page Topic: [{post_title}]
    – Page Content: [{post_content}]
    – Image: [attached image]

Examples of Alt Text Prompt:

    Role: Web Accessibility and SEO Expert.
    Task: Generate a single, optimized alt text string (MAX 125 characters) for the provided image, situated within the context of inputs.

Examples of Alt Text Prompt:

    Role: SEO Copywriting Specialist.
    Task: Generate 1 optimized image title based on the provided topic and attached image.

== External Services ==

This plugin uses third-party AI providers to generate image metadata. You must obtain an API key for at least one of the supported providers.

Supported Providers:

> **OpenRouter** (Recommended)
> Service URL: https://openrouter.ai/
> Data Sent: Image URLs, Post Titles, Post Content (context)
> Terms of Service: https://openrouter.ai/terms
> Privacy Policy: https://openrouter.ai/privacy
> API Key Format: sk-or-...

> **OpenAI**
> Service URL: https://api.openai.com/
> Data Sent: Image URLs, Post Titles, Post Content (context)
> Terms of Service: https://openai.com/policies
> Privacy Policy: https://openai.com/privacy
> API Key Format: sk-...

> **NVIDIA NIM**
> Service URL: https://integrate.api.nvidia.com/
> Data Sent: Image URLs, Post Titles, Post Content (context)
> Terms of Service: https://build.nvidia.com/nim/terms-of-use
> Privacy Policy: https://www.nvidia.com/en-us/privacy/
> API Key Format: nvapi-...

> **MiniMax**
> Service URL: https://platform.minimax.io/
> Data Sent: Image URLs, Post Titles, Post Content (context)
> Terms of Service: https://platform.minimax.io/terms
> Privacy Policy: https://platform.minimax.io/privacy
> API Key Format: your-api-key

**Note:** You must obtain your own API key from your chosen provider. The plugin sends image URLs and contextual post data to the selected provider's chat completions API endpoint. No other data is collected.

== Installation ==

Upload the plugin folder to the /wp-content/plugins/ directory.

Activate the plugin through the 'Plugins' menu in WordPress.

Navigate to Settings > AI ALT Genius to configure the plugin.

**Upgrading from KooKoo AI Alt Text Creator:** Replace the old plugin folder with `wpstack-ai-alt-genius`, then activate **WPStack AI ALT Genius** on the Plugins screen. Your API keys, settings, and generated metadata are preserved automatically.

== Configuration ==

1-API Configuration

**AI Provider:** Choose between OpenRouter, OpenAI, NVIDIA NIM, or MiniMax. Each provider has different models and pricing.

**API Key:** Enter your API key for the selected provider. The placeholder changes to match the expected format (e.g., sk-or-... for OpenRouter, sk-... for OpenAI, nvapi-... for NVIDIA, your-api-key for MiniMax).

**Model Selection:** Choose the model you wish to use from the dynamic dropdown menu. Models with a camera icon support image/vision analysis. The list updates automatically when you switch providers.

2-Generation Options

**Global Context:** Instructions sent with every request. Great for setting the "persona" of the AI.

**Supported Image Formats:** Define which file extensions the plugin should process.

**Enable Alt Text / Title / Caption / Description:** Toggle which metadata fields you want to generate.

**Prompts:** Customize the specific instructions for generating Alt Text vs Titles.

**Save Generation Info:** Enables logging of timestamps and error messages to the database.

3-Bulk Generation (Cron)

**Enable Background Processing:** Turns on the automatic generator.

**Batch Size:** How many images to process per run. Keep this low (1-2) to prevent server timeouts.

**Interval:** How often the job runs (in minutes).

== Frequently Asked Questions ==

= What AI models are supported? =

OpenRouter supports a vast array of models from all major providers. As of the latest update, supported model families include (but are not limited to):

    Google: Gemini, PaLM
    
    OpenAI: GPT (GPT-3.5, GPT-4, GPT-4o, etc.)
    
    Anthropic: Claude (Haiku, Sonnet, Opus)
    
    Meta: Llama
    
    Mistral AI: Mistral, Mixtral, Codestral
    
    DeepSeek: DeepSeek Chat/Coder
    
    Qwen: Qwen (Alibaba)
    
    Microsoft: WizardLM, Phi
    
    Perplexity: Perplexity Online/Chat
    
    X.ai: Grok
    
    Cohere: Command
    
    Nvidia: Nemotron
    
    Amazon: Nova, Bedrock
    
    Databricks: DBRX
    
    Nous Research: Hermes
    
    Liquid: Liquid
    
    Arcee AI: Arcee
    
    Moonshot AI: Kimi
    
    Z.ai: GLM
    
    MiniMax: MiniMax

Additionally, OpenAI, NVIDIA NIM, and MiniMax provide their own model lists accessible directly through their APIs.
You can find specific Model IDs on the OpenRouter Models page, or check the OpenAI Model list, NVIDIA NIM catalog, and MiniMax platform.

= Does this plugin modify my actual image files? =

No. It only updates the metadata (Alt Text, Title, Caption, Description) in the WordPress database. Your physical image files remain untouched.

= Will it overwrite my existing Alt Text? =

Bulk Generation (Background): No. The background process automatically skips any image that has already been successfully processed by the plugin to save you money and preserve your data.

Manual Generation (Button): Yes. If you click the "Regenerate" button on a specific image in the Media Library, it will overwrite the existing text with the new AI result.

= What happens if I uninstall the plugin? =

If you delete the plugin via the Plugins screen:

It will clean up its own settings and temporary statistics.

It will remove internal logs (timestamps, error logs).

Crucially: The Alt Text, Titles, Captions, and Descriptions generated for your images will remain. They become part of your site's standard content and are not deleted.

= My bulk generation seems stuck. What do I do? =

Go to Settings > AI ALT Genius. Look at the "Statistics" box.

Check the "Failed" count. If images are failing, check the "Edit Media" screen of a failed image to see the error message.

Use the "Retry Failed Images" button to move them back to the pending queue.

Use the "Reset Cron Progress" button if you want to completely restart the analysis from scratch (this allows the plugin to look at all images again).

== Changelog ==

= 1.0.0 =

* Initial public release of WPStack AI ALT Genius.
* Generates alt text, title, caption, and description for Media Library images in a single AI vision request.
* Supports OpenRouter, OpenAI, NVIDIA NIM, and MiniMax (bring your own API key).
* Manual generation from the Media Library list view and attachment editor sidebar.
* Background WP-Cron batch processing with configurable batch size and interval.
* Context-aware prompts using parent post title and content (`{post_title}`, `{post_content}`) plus global site instructions.
* Per-field enable toggles and fully customizable prompts for each metadata type.
* Dynamic model selector with vision-capable model detection and custom model ID fallback.
* Up to three NVIDIA API keys with round-robin rotation and parallel cron distribution.
* Statistics dashboard: total, processed, failed, pending, and progress bar.
* Maintenance tools: Reset Progress, Retry Failed, and Fix JSON Errors.
* Top-level admin menu with custom icon, branded settings header, and WPStack / Miracuves footer linkbacks.
* Secure API key handling (masked fields; blank save preserves existing keys).
* Generation audit meta on attachments (timestamp and manual/cron source).
* Upgrade-safe option and meta keys for sites migrating from earlier builds.
* Clean uninstall removes plugin options, transients, and plugin meta (preserves generated alt text).