When to Use Batch Processing

Batch alt text generation is ideal when:

  • You have existing images without alt text – Process all images that were uploaded before enabling automatic alt text generation.
  • You want to bulk update your media library – Generate alt text for hundreds or thousands of images in one operation.
  • You’re migrating or importing content – Add alt text to images imported from another site or system.
  • You’ve disabled automatic generation temporarily – Catch up on images uploaded while the feature was off.

Batch processing runs in the background using WordPress Cron, so you can continue working while images are processed. The system automatically manages rate limiting and queues to ensure reliable performance.

Prerequisites

Before using batch alt text generation, ensure:

  • Batch operations are enabled – The “Enable batch alt text operations” toggle must be enabled in Cortex AI → Main → Batch Alt Text.
  • Text provider is configured – You must have an OpenAI API key set up in Cortex AI → Settings → Text. Image analysis requires OpenAI’s Vision API.
  • Manage options capability – You need administrator-level permissions to access plugin settings and run batch operations.

If the Batch Alt Text section doesn’t appear, check that your text provider (OpenAI) is properly configured with a valid API key.

Starting a Batch Alt Text Job

Accessing the Batch Alt Text Section

  1. Go to Cortex AI → Main in your WordPress admin menu.
  2. Scroll to the Batch Alt Text section.
  3. Ensure the “Enable batch alt text operations” toggle is enabled.

Running a Batch Operation

  1. Enable the toggle – If not already enabled, toggle on “Enable batch alt text operations”.
  2. Click “Run Batch Operation” – The button will check how many images need alt text.
  3. Review the count – A modal will appear showing how many images will be processed.
  4. Confirm the operation – Click “Continue” to start the batch job, or “Cancel” to abort.

The system will:

  • Count all images in your Media Library that don’t have alt text.
  • Show you the total number of images that will be processed.
  • Start processing in the background after confirmation.

What Gets Processed

Batch processing only includes images that:

  • Are image files – JPEG, PNG, WebP, GIF, and other image formats.
  • Don’t have alt text – Images with empty or missing alt text fields.
  • Are under 15MB – Images larger than 15MB are skipped (same limit as automatic generation).
  • Are in the Media Library – Only WordPress attachment posts with image MIME types.

Images that already have alt text are skipped. The batch operation will not overwrite existing alt text.

Monitoring Batch Progress

Once a batch operation starts, you can monitor its progress in real time.

Progress Display

The Batch Alt Text section shows:

  • Current progress – “Processing X of Y images…” with a visual progress bar.
  • Percentage complete – Visual progress bar showing completion percentage.
  • Cancel button – Option to stop the batch operation if needed.

Progress Updates

  • Automatic refresh – Progress updates every 2 seconds while the batch is running.
  • Real-time status – The display shows the current number of images processed out of the total.
  • Completion notification – When finished, you’ll see an admin notice with results.

Understanding Progress

The progress display shows:

  • Current – Number of images processed so far (successful + failed).
  • Total – Total number of images that need alt text.
  • Progress bar – Visual representation of completion percentage.

Processing happens in batches of 7 images at a time, with a 3-second delay between batches. This ensures the API isn’t overwhelmed and maintains reliable performance.

Canceling Batch Jobs

You can cancel an active batch operation at any time.

How to Cancel

  1. Find the progress display – Look for the progress bar in the Batch Alt Text section.
  2. Click “Cancel” – The cancel button appears next to the progress information.
  3. Confirmation – The batch operation stops immediately.

What Happens When You Cancel

  • Processing stops – No new images are processed after cancellation.
  • Already processed images – Images that were successfully processed before cancellation keep their generated alt text.
  • No completion notice – You won’t receive a completion notification for a cancelled batch.
  • Can restart – You can start a new batch operation at any time; it will only process remaining images.

Cancellation Errors

If cancellation fails (rare), you’ll see an error message. In this case:

  • Wait a moment – The batch may complete naturally.
  • Try again – Click cancel again if the batch is still running.
  • Check WordPress Cron – Ensure WordPress Cron is functioning properly on your site.

Batch Processing Details

How Batch Processing Works

  1. Initialization – The system finds all images without alt text and creates a batch state.
  2. Background processing – Images are processed in chunks using WordPress Cron.
  3. Rate limiting – Maximum 5 concurrent API requests, with automatic queuing for additional images.
  4. Progress tracking – Each image’s success or failure is tracked in the batch state.
  5. Completion – When all images are processed (or failed), you receive a completion notice.

Processing Speed

Batch processing is designed to be reliable, not fast:

  • 7 images per batch – Processed in chunks of 7 images.
  • 3-second delay – 3 seconds between each batch chunk.
  • 5 concurrent requests – Maximum 5 images analyzed simultaneously.
  • Automatic queuing – Additional images wait in queue when capacity is full.

For a large batch (e.g., 1000 images), expect processing to take several hours. The system is designed to run reliably in the background without impacting your site’s performance.

Error Handling

If an image fails during batch processing:

  • Tracked separately – Failed images are tracked but don’t stop the batch.
  • Error logging – Failures are logged to WordPress error logs.
  • Completion notice – Failed images are listed in the completion notice.
  • Can retry – You can run another batch operation; it will skip images that now have alt text.

Common reasons for failures:

  • API errors – Network issues or API service problems.
  • Invalid files – Corrupted or unsupported image formats.
  • File not found – Image was deleted before processing completed.
  • File too large – Images over 15MB are skipped.
  • API key issues – Invalid or expired OpenAI API key.

Completion and Results

Completion Notice

When a batch operation completes, you’ll see an admin notice at the top of your WordPress admin pages:

  • Success notice – Shows total number of images processed successfully.
  • Warning notice – If some images failed, shows successful count and lists failed images (up to 5, with “and X more” if additional failures).

Understanding Results

The completion notice shows:

  • Processed – Number of images that successfully received alt text.
  • Failed – Number of images that couldn’t be processed (with filenames listed).
  • Total – Total number of images that were in the batch.

After Completion

  • Review generated alt text – Check a few images in the Media Library to verify quality.
  • Edit as needed – You can always edit generated alt text for accuracy.
  • Retry failures – If images failed, you can manually add alt text or investigate the cause.
  • Run again – If new images are added without alt text, you can run another batch operation.

Best Practices

  1. Enable batch operations first – Toggle on “Enable batch alt text operations” before running.
  2. Check API configuration – Ensure OpenAI API key is valid and has sufficient credits.
  3. Run during low traffic – For large batches, consider running during off-peak hours (though processing happens in background).
  4. Monitor progress – Check the progress display periodically to ensure processing continues.
  5. Review results – After completion, spot-check generated alt text for quality and accuracy.
  6. Combine with automatic generation – Enable automatic alt text on upload to prevent future backlogs.

Troubleshooting

Batch Operation Won’t Start

  • Check the toggle – Ensure “Enable batch alt text operations” is enabled.
  • Verify OpenAI setup – Confirm OpenAI API key is configured in Cortex AI → Settings → Text.
  • Check permissions – Ensure you have administrator-level access.
  • Review browser console – Check for JavaScript errors that might prevent the operation from starting.

Progress Not Updating

  • Wait a moment – Progress updates every 2 seconds; allow time for refresh.
  • Refresh the page – Manually refresh the admin page to see current status.
  • Check WordPress Cron – Ensure WordPress Cron is functioning (check with a plugin like WP Crontrol).
  • Check batch state – The batch may have completed; look for a completion notice.

Batch Taking Too Long

  • This is normal – Large batches can take hours; processing is intentionally slow to avoid API rate limits.
  • Check progress – Verify the progress bar is advancing (even slowly).
  • Don’t cancel unnecessarily – Unless you need to stop immediately, let the batch complete.
  • Check API status – Verify OpenAI’s API is operational and not experiencing issues.

Images Not Being Processed

  • Check file size – Images over 15MB are skipped.
  • Verify image format – Only image files (JPEG, PNG, WebP, GIF, etc.) are processed.
  • Check existing alt text – Images that already have alt text are skipped.
  • Review error logs – Check WordPress error logs for specific failure reasons.

Completion Notice Not Appearing

  • Check other admin pages – The notice appears on any admin page, not just the plugin settings.
  • Look for dismissible notices – The notice may have been dismissed; check if it’s still in the database.
  • Review batch status – Use the status endpoint or check if the batch completed successfully.

Privacy and Data Considerations

Important: Batch alt text generation sends image files to OpenAI’s Vision API for analysis. This means:

  • External processing – Images leave your server and are processed by OpenAI.
  • API terms – Your use is subject to OpenAI’s terms of service and privacy policy.
  • Bulk processing – Many images are sent to external services during batch operations.
  • Permissions – Only enable batch processing for images you have permission to send to external services.

Consider your privacy requirements and any applicable regulations (e.g., GDPR, HIPAA) before running batch operations, especially for sites with sensitive or personal images.

Next Steps

Batch alt text generation makes it easy to add accessibility and SEO benefits to your entire media library, ensuring all your images have descriptive alt text without manual work.