igny8/igny8-ai-seo-wp-plugin/docs/COMPLETE_IMAGE_GENERATION_AUDIT.md

Complete Image Generation Process Audit

Summary

This document provides a comprehensive audit of the current image generation process in the Igny8 AI SEO plugin. The system has been reorganized with image generation functions moved to a dedicated module and improved queue processing.

Files Involved

• ai/writer/images/image-generation.php - Main image generation functions (featured & article images)
• core/admin/ajax.php - AJAX handlers for image generation requests
• assets/js/image-queue-processor.js - JavaScript queue processing and UI
• ai/modules-ai.php - Content generation response handler (saves image prompts)
• ai/openai-api.php - OpenAI DALL-E API integration
• ai/runware-api.php - Runware API integration

Functions and Purposes

• igny8_generate_featured_image_for_post() - Generates featured images using AI prompts
• igny8_generate_single_article_image() - Generates in-article images for specific sections
• igny8_ajax_ai_generate_single_image() - AJAX handler for single image generation
• igny8_add_inarticle_image_meta() - Saves image metadata to post meta
• igny8_format_image_prompts_for_ai() - Formats image prompts for AI content generation
• igny8_create_post_from_ai_response() - Saves image prompts from AI response

Overview

This document provides a comprehensive audit of the image generation process in the Igny8 AI SEO plugin, covering every function, hook, setting, and data flow from button click to final image save.

1. Entry Point - Generate Images Button

Location

• File: modules/components/actions-tpl.php
• Lines: 42-45
• Button ID: writer_drafts_generate_images_btn
• HTML:

<button id="writer_drafts_generate_images_btn" class="igny8-btn igny8-btn-accent" disabled>
    <span class="dashicons dashicons-format-image"></span> Generate Images
</button>

JavaScript Event Handler

• File: assets/js/image-queue-processor.js
• Function: processAIImageGenerationDrafts(postIds)
• Lines: 7-84
• Validation: Max 10 posts, requires selection

2. JavaScript Processing Flow

Main Processing Function

• File: assets/js/image-queue-processor.js
• Function: processAIImageGenerationDrafts(postIds)
• Lines: 7-84

Settings Retrieved

const desktopEnabled = window.IGNY8_PAGE?.imageSettings?.desktop_enabled || false;
const mobileEnabled = window.IGNY8_PAGE?.imageSettings?.mobile_enabled || false;
const maxInArticleImages = window.IGNY8_PAGE?.imageSettings?.max_in_article_images || 1;

Image Calculation

• Featured Images: Always 1 per post
• Desktop Images: maxInArticleImages per post (if enabled)
• Mobile Images: maxInArticleImages per post (if enabled)
• Total: postIds.length * imagesPerPost

Queue Processing

• Sequential Processing: One image at a time to avoid API limits
• Progress Tracking: Real-time progress updates with individual progress bars
• Error Handling: Continue processing on individual failures
• Modal Display: Shows progress for each image being generated

3. AJAX Handlers

Primary Handler

• File: core/admin/ajax.php
• Function: igny8_ajax_ai_generate_images_drafts()
• Lines: 2913-3150
• Hook: wp_ajax_igny8_ai_generate_images_drafts

Single Image Handler

• File: core/admin/ajax.php
• Function: igny8_ajax_ai_generate_single_image()
• Lines: 3283-3350
• Hook: wp_ajax_igny8_ai_generate_single_image
• Process:
  1. Validates task ID and retrieves WordPress post ID
  2. Calls appropriate generation function based on type
  3. Saves image metadata to post meta
  4. Returns success/error response

Supporting Handlers

• Image Counts: igny8_ajax_get_image_counts() (Lines 2645-2809)
• Single Image Queue: igny8_ajax_generate_single_image_queue() (Lines 2814-2908)
• Settings Save: igny8_ajax_save_image_settings() (Lines 4408-4457)
• Template Save: igny8_ajax_save_image_prompt_template() (Lines 4461-4505)

4. Settings and Configuration

WordPress Options

Option	Default	Purpose
igny8_desktop_enabled	'1'	Enable desktop image generation
igny8_mobile_enabled	'0'	Enable mobile image generation
igny8_max_in_article_images	1	Maximum in-article images per post
igny8_image_type	'realistic'	Image style type
igny8_image_provider	'runware'	AI provider for image generation
igny8_image_format	'jpg'	Output image format
igny8_negative_prompt	'text, watermark, logo, overlay, title, caption, writing on walls, writing on objects, UI, infographic elements, post title'	Negative prompt for image generation
igny8_image_prompt_template	'Create a high-quality {image_type} image to use as a featured photo for a blog post titled "{post_title}". The image should visually represent the theme, mood, and subject implied by the image prompt: {image_prompt}. Focus on a realistic, well-composed scene that naturally communicates the topic without text or logos. Use balanced lighting, pleasing composition, and photographic detail suitable for lifestyle or editorial web content. Avoid adding any visible or readable text, brand names, or illustrative effects. **And make sure image is not blurry.**'	Image prompt template

Settings Page

• File: modules/settings/general-settings.php
• Lines: 309-462
• Form Fields: Desktop/Mobile toggles, Max images dropdown, Image type, Provider, Format, Negative prompt, Template

5. Image Generation Functions

Core Generation Functions

• File: ai/writer/images/image-generation.php

Featured Image Generation

• Function: igny8_generate_featured_image_for_post($post_id, $image_size_type = 'featured')
• Lines: 24-200
• Process:
  1. Get featured image prompt from _igny8_featured_image_prompt
  2. Get image generation settings from WordPress options
  3. Build final prompt using template with placeholders
  4. Call AI provider (Runware/OpenAI) with appropriate dimensions
  5. Download image from AI provider URL
  6. Upload via media_handle_sideload()
  7. Set as featured image with set_post_thumbnail()
  8. Generate attachment metadata

In-Article Image Generation

• Function: igny8_generate_single_article_image($post_id, $device_type = 'desktop', $index = 1)
• Lines: 202-400
• Process:
  1. Get article image prompts from _igny8_article_images_data
  2. Extract prompt for specific index (prompt-img-1, prompt-img-2, etc.)
  3. Get image generation settings from WordPress options
  4. Build final prompt using template with placeholders
  5. Call AI provider with device-specific dimensions
  6. Download image from AI provider URL
  7. Upload via media_handle_sideload()
  8. Return attachment ID and metadata

Supporting Functions

• Image Dimensions: igny8_get_image_dimensions($size_preset, $provider) (Lines 1526-1558 in ai/modules-ai.php)
• Safe Quantity: igny8_calculate_safe_image_quantity($idea_data, $max_in_article_images) (Lines 918-933 in ai/modules-ai.php)
• Image Meta: igny8_add_inarticle_image_meta($post_id, $attachment_id, $label, $device, $section) (Lines 933-963 in ai/modules-ai.php)

6. AI Provider Integration

Runware API Integration

• File: ai/runware-api.php
• Function: igny8_runway_generate_image($prompt, $negative_prompt, $width, $height, $steps, $cfg_scale, $number_results, $output_format)
• API Endpoint: https://api.runware.ai/v1
• Authentication: API key via igny8_runware_api_key option
• Model: runware:97@1 (HiDream-I1 Full)
• Request Format:

  [
    {
      "taskType": "authentication",
      "apiKey": "api_key_here"
    },
    {
      "taskType": "imageInference",
      "taskUUID": "uuid_here",
      "positivePrompt": "prompt_text",
      "negativePrompt": "negative_prompt",
      "model": "runware:97@1",
      "width": 1024,
      "height": 1024,
      "steps": 30,
      "CFGScale": 7.5,
      "numberResults": 1,
      "outputFormat": "jpg"
    }
  ]
  

• Response Handling: Extract data[0].imageURL from response
• Error Handling: Log API errors, return error messages

OpenAI DALL-E Integration

• File: ai/openai-api.php
• Function: igny8_call_openai_images($prompt, $api_key, $model, $size, $quality, $style)
• API Endpoint: https://api.openai.com/v1/images/generations
• Authentication: API key via igny8_api_key option
• Model: dall-e-3
• Request Format:

  {
    "model": "dall-e-3",
    "prompt": "prompt_text",
    "n": 1,
    "size": "1024x1024",
    "quality": "standard",
    "style": "natural"
  }
  

• Response Handling: Extract data[0].url from response
• Error Handling: Log API errors, return error messages

Provider Detection and Selection

• Settings: igny8_image_provider option (runware or openai)
• API Key Validation: Check igny8_runware_api_key or igny8_api_key
• Dynamic Selection: Based on user settings in prompts page
• Fallback Handling: Return error if required API key not configured

Image Dimensions by Provider

• Runware Dimensions:
  • Featured: 1280x832
  • Desktop: 1024x1024
  • Mobile: 960x1280
• OpenAI Dimensions:
  • Featured: 1024x1024
  • Desktop: 1024x1024
  • Mobile: 1024x1024

7. Data Storage and Meta Keys

Post Meta Keys

Meta Key	Purpose	Data Type
_igny8_featured_image_prompt	Featured image AI prompt	Text
_igny8_article_images_data	In-article image prompts	JSON Array
_igny8_inarticle_images	Generated image metadata	JSON Object

Image Prompts Data Structure

[
  {
    "prompt-img-1": "A close-up of a neatly made bed showcasing a well-fitted duvet cover that enhances the aesthetic of the room."
  },
  {
    "prompt-img-2": "An image of tools laid out for measuring a duvet insert, including a measuring tape, notepad, and a flat surface."
  },
  {
    "prompt-img-3": "A detailed size chart displaying different duvet cover sizes alongside their corresponding duvet insert dimensions."
  },
  {
    "prompt-img-4": "An infographic illustrating common mistakes when choosing duvet covers, highlighting shrinkage risks and misreading labels."
  }
]

Image Metadata Structure

{
  "desktop-1": {
    "label": "desktop-1",
    "attachment_id": 1825,
    "url": "https://example.com/image.jpg",
    "device": "desktop",
    "section": 1
  },
  "mobile-1": {
    "label": "mobile-1",
    "attachment_id": 1826,
    "url": "https://example.com/image2.jpg",
    "device": "mobile",
    "section": 1
  }
}

8. Image Processing Workflow

Step-by-Step Process

1. Button Click: User selects posts and clicks "Generate Images"
2. Validation: Check selection count (max 10), get settings
3. Queue Building: Build image queue with featured and in-article images
4. Progress Modal: Show progress with individual progress bars
5. Sequential Processing: Process each image individually
6. Image Generation: For each image:
   • Get prompt from appropriate meta field
   • Call AI provider with settings
   • Download image from provider URL
   • Upload to WordPress Media Library
   • Save metadata to post meta
7. Progress Updates: Update UI with success/failure status
8. Completion: Show final results

Error Handling

• Download Failures: Log errors, continue with next image
• Upload Failures: Log errors, return failure status
• API Failures: Log errors, return failure status
• Progress Tracking: Update modal with success/failure counts
• JSON Parsing: Handle HTML content in prompts with wp_strip_all_tags()

9. Content Generation Integration

Image Prompts in Content Generation

• File: ai/modules-ai.php
• Function: igny8_create_post_from_ai_response($ai_response)
• Lines: 1119-1462
• Process:
  1. AI generates content with image prompts
  2. Featured image prompt saved to _igny8_featured_image_prompt
  3. In-article image prompts saved to _igny8_article_images_data
  4. HTML tags stripped from prompts using wp_strip_all_tags()
  5. JSON structure validated and saved

Prompt Template Processing

• Template: Uses {image_type}, {post_title}, {image_prompt} placeholders
• Replacement: Dynamic replacement with actual values
• Settings Integration: Uses all settings from prompts page

10. Image Generation Queue Mechanism

Queue Processing

• File: assets/js/image-queue-processor.js
• Function: processAIImageGenerationDrafts(postIds)
• Lines: 7-84
• Process: Sequential image generation with progress tracking

Queue Features

• Sequential Processing: One image at a time to avoid API limits
• Progress Tracking: Real-time progress updates with individual bars
• Error Handling: Continue processing on individual failures
• Batch Management: Handle multiple posts with image counts
• Modal Display: Shows detailed progress for each image

Queue Handler

• File: core/admin/ajax.php
• Function: igny8_ajax_ai_generate_single_image()
• Lines: 3283-3350
• Hook: wp_ajax_igny8_ai_generate_single_image

11. Debug and Logging

Debug Functions

• File: debug/module-debug.php
• Lines: 1185-1221 (HTML), 1447-1613 (JavaScript)
• Features:
  • Image generation logs interface
  • Refresh/clear buttons (refresh-image-gen, clear-image-gen)
  • Real-time event display (image-gen-events)
  • Status messages (image-gen-message, image-gen-details)
  • Global debug function (window.addImageGenDebugLog)

Comprehensive Logging System

• Event-Based Logging: IMAGE_GEN_EVENT_1 through IMAGE_GEN_EVENT_9
• Debug Events Array: $debug_events[] for detailed tracking
• Error Logging: error_log() with specific prefixes
• AI Event Logging: igny8_log_ai_event() for AI interactions

Logging Points

• AJAX Entry: error_log('Igny8: AJAX HANDLER CALLED - igny8_ajax_ai_generate_images_drafts')
• Task Validation: error_log('Igny8: IMAGE_GEN_EVENT_3 - Task IDs validated')
• Post Retrieval: error_log('Igny8: IMAGE_GEN_EVENT_4 - WordPress post IDs retrieved')
• Image Prompts: error_log('Igny8: IMAGE_GEN_EVENT_5 - Image prompts loaded')
• Featured Generation: error_log('Igny8: IMAGE_GEN_EVENT_6 - Featured image generation initiated')
• API Requests: error_log('Igny8: IMAGE_GEN_EVENT_7 - API request sent')
• Image URLs: error_log('Igny8: IMAGE_GEN_EVENT_8 - Image URL received')
• WordPress Save: error_log('Igny8: IMAGE_GEN_EVENT_9 - Saving image to WordPress')
• Success/Failure: error_log('Igny8: IMAGE_GEN_EVENT_9_SUCCESS/ERROR')

12. File Dependencies

Core Files

• ai/writer/images/image-generation.php - Main image generation functions
• core/admin/ajax.php - AJAX handlers
• assets/js/image-queue-processor.js - Queue processing JavaScript
• ai/modules-ai.php - Content generation response handler
• ai/openai-api.php - OpenAI DALL-E API integration
• ai/runware-api.php - Runware API integration

Settings Files

• modules/settings/general-settings.php - Main image generation settings page
• modules/thinker/prompts.php - Image prompt templates only
• modules/thinker/image-testing.php - Image testing interface
• modules/modules-pages/writer.php - Settings localization

Debug Files

• debug/module-debug.php - Debug interface

13. Hooks and Actions

WordPress Hooks

• wp_ajax_igny8_ai_generate_images_drafts - Main generation handler
• wp_ajax_igny8_ai_generate_single_image - Single image handler
• wp_ajax_igny8_generate_single_image_queue - Queue handler
• wp_ajax_igny8_get_image_counts - Image count preview
• wp_ajax_igny8_save_image_settings - Settings save
• wp_ajax_igny8_save_image_prompt_template - Template save
• wp_ajax_igny8_reset_image_prompt_template - Template reset

Internal Hooks

• transition_post_status - Post status changes
• save_post - Post save events

14. Security Considerations

Nonce Verification

• All AJAX handlers verify nonces
• Settings forms use proper nonce fields
• User capability checks for admin functions

Data Sanitization

• All input data sanitized with sanitize_text_field()
• File uploads handled via WordPress functions
• Image URLs validated before processing
• HTML tags stripped from prompts using wp_strip_all_tags()

15. Performance Considerations

Sequential Processing

• Images generated one at a time to avoid API limits
• Progress tracking for user feedback
• Error handling to continue processing

Media Library Integration

• Proper WordPress Media Library registration
• Automatic thumbnail generation
• Metadata attachment for SEO

16. Complete Function Reference

AJAX Handlers

• igny8_ajax_ai_generate_images_drafts() - Main generation
• igny8_ajax_ai_generate_single_image() - Single image
• igny8_ajax_generate_single_image_queue() - Queue processing
• igny8_ajax_get_image_counts() - Count preview
• igny8_ajax_save_image_settings() - Settings save
• igny8_ajax_save_image_prompt_template() - Template save
• igny8_ajax_reset_image_prompt_template() - Template reset

Generation Functions

• igny8_generate_featured_image_for_post() - Featured image
• igny8_generate_single_article_image() - In-article image
• igny8_get_image_dimensions() - Size calculation
• igny8_calculate_safe_image_quantity() - Quantity safety

Content Functions

• igny8_add_inarticle_image_meta() - Image metadata saving
• igny8_format_image_prompts_for_ai() - Prompt formatting
• igny8_create_post_from_ai_response() - Content generation response handler

Queue Processing Functions

• processAIImageGenerationDrafts() - Main queue processor
• generateAllImagesForPost() - Single post processing
• updateProgressModal() - Progress updates

API Functions

• igny8_runway_generate_image() - Runware API integration
• igny8_call_openai_images() - OpenAI DALL-E API integration

Settings Functions

• igny8_ajax_save_image_settings() - Settings save
• igny8_ajax_save_image_prompt_template() - Template save
• igny8_ajax_reset_image_prompt_template() - Template reset

17. Recent Changes and Improvements

Code Reorganization

• Image generation functions moved from ai/modules-ai.php to ai/writer/images/image-generation.php
• Dedicated module for image generation functionality
• Improved separation of concerns between content generation and image generation

Enhanced Error Handling

• JSON parsing improvements with HTML tag stripping
• Better error messages for debugging
• Graceful fallbacks for API failures

Improved Queue Processing

• Individual progress bars for each image
• Better error tracking and reporting
• Enhanced user feedback during processing

Settings Integration

• Dynamic settings from prompts page
• Template-based prompts with placeholder replacement
• Provider selection with appropriate API key validation

This audit covers every aspect of the current image generation process from initial button click to final image storage and metadata saving, including the complete queue mechanism, settings integration, and content generation workflow.