Athenian Batch AI Image Generation

Developer starting point

This baseline documents the reviewed batch-image architecture. It does not claim that an external AI request, generated image, ZIP artifact, or product-media mutation has been exercised.

User Workflow

1. A user visits a page containing the [athenian_batch_image_generation] shortcode.
2. The user creates prompt rows manually, imports a CSV, or uses the AI Batch Planner.
3. The user submits the batch with a batch name and notification email.
4. The plugin creates a job record and one job item per prompt row.
5. A queue worker processes pending job items through the OpenAI Images API.
6. Successful image bytes are imported into the WordPress Media Library.
7. Completed images are bundled into a ZIP archive.
8. The requester receives an email when the batch is finished.
9. Administrators can view recent batches and manually run the queue from wp-admin.

---

Technical Architecture

Bootstrap File

athenian-batch-image-generation.php defines plugin metadata, constants, activation/deactivation hooks, and loads the plugin classes.

Defined constants:

ABIG_VERSION
ABIG_PLUGIN_FILE
ABIG_PLUGIN_DIR
ABIG_PLUGIN_URL

Activation behavior:

• Creates or updates custom database tables through ABIG_Repository::install().
• Seeds default settings through ABIG_Settings::maybe_seed_defaults().

Deactivation behavior:

• Unschedules the recurring abig_process_queue cron event.

Primary Classes

| File | Responsibility | | --- | --- | | includes/class-abig-plugin.php | Main service container, component wiring, cron registration, lifecycle coordination. | | includes/class-abig-settings.php | Settings defaults, registration, sanitization, and retrieval. | | includes/class-abig-repository.php | Custom table creation, job persistence, item persistence, status updates, job refresh logic. | | includes/class-abig-openai-client.php | OpenAI Responses API planner calls and OpenAI Images API generation calls. | | includes/class-abig-processor.php | Queue execution, image generation orchestration, Media Library sideloading, finalization. | | includes/class-abig-zip-builder.php | ZIP archive generation for completed image batches. | | includes/class-abig-notifier.php | Completion email creation and delivery. | | includes/class-abig-admin.php | wp-admin settings page, queue button, and recent batch table. | | includes/class-abig-shortcode.php | Frontend shortcode rendering, batch submission handling, AI planner AJAX endpoint. |

Asset Files

| File | Responsibility | | --- | --- | | assets/js/frontend.js | CSV parsing, row management, AI planner request handling, frontend table population. | | assets/js/admin.js | Manual queue processing button behavior in wp-admin. | | assets/css/frontend.css | Frontend shortcode layout and visual styling. | | assets/css/admin.css | Admin dashboard layout and visual styling. |

---

Custom Database Tables

The plugin creates two custom tables using dbDelta().

wp_abig_jobs

Stores batch-level information.

| Column | Purpose | | --- | --- | | id | Primary batch/job ID. | | batch_name | Human-readable batch name. | | requester_email | Email address for completion notification. | | requester_user_id | WordPress user ID when submitted by a logged-in user. | | status | Batch lifecycle status. | | source | Submission source, currently shortcode. | | total_items | Number of prompt rows in the batch. | | completed_items | Count of successfully generated images. | | failed_items | Count of failed rows. | | zip_path | Server path to ZIP archive. | | zip_url | Public URL to ZIP archive. | | completion_notified | Whether the completion email has been sent. | | started_at | First processing timestamp. | | completed_at | Completion timestamp. | | created_at | Creation timestamp. | | updated_at | Last update timestamp. |

Indexes:

• Primary key on id.
• Index on status.
• Index on requester_email.

wp_abig_job_items

Stores one row per requested image.

| Column | Purpose | | --- | --- | | id | Primary item ID. | | job_id | Parent batch/job ID. | | row_index | Original row order. | | prompt | Main image prompt. | | negative_prompt | Optional negative prompt. | | size | Requested image size. | | quality | Requested image quality. | | background | Background mode. | | output_format | Output file format. | | filename | Desired extension-free filename. | | status | Item lifecycle status. | | attachment_id | WordPress Media Library attachment ID. | | generated_url | Final generated image URL. | | remote_request_id | OpenAI request ID, when returned. | | error_message | Stored failure message for failed rows. | | item_meta | JSON metadata placeholder for future extensions. | | created_at | Creation timestamp. | | updated_at | Last update timestamp. | | completed_at | Completion timestamp. |

Indexes:

• Primary key on id.
• Index on job_id.
• Index on status.

---

OpenAI Integration

Planner Request

The AI Batch Planner calls:

https://api.openai.com/v1/responses

The planner model is configurable and defaults to:

gpt-4.1-mini

The plugin asks the planner to return JSON using this shape:

[
  {
    "prompt": "",
    "negative_prompt": "",
    "filename": "",
    "size": "1024x1024",
    "quality": "auto",
    "background": "auto",
    "output_format": "png"
  }
]

The response text is normalized to remove Markdown code fences before JSON parsing. Rows without a prompt are discarded.

Image Generation Request

The image worker calls:

https://api.openai.com/v1/images/generations

The image model is configurable and defaults to:

gpt-image-1

The plugin sends one generation request per job item with:

• model
• prompt
• n = 1
• size
• quality
• background
• output_format
• user = abig-job-{job_id}

The plugin expects b64_json image data, decodes it, saves it to a temporary file, and imports it into the Media Library.

Negative Prompt Handling

The plugin does not send a separate negative prompt field to the image API. Instead, it appends negative prompt guidance to the main prompt as:

Avoid: {negative_prompt}

---

Admin Settings

Default settings are stored in the abig_settings option.

| Setting | Default | Purpose | | --- | --- | --- | | openai_api_key | Empty | API key used for planner and image requests. | | image_model | gpt-image-1 | Model used for image generation. | | planner_model | gpt-4.1-mini | Model used for AI row planning. | | default_size | 1024x1024 | Default image size. | | default_quality | auto | Default quality value. | | default_background | auto | Default background mode. | | default_output_format | png | Default generated file format. | | max_rows_per_batch | 24 | Maximum rows accepted per batch. | | max_items_per_run | 3 | Maximum queue items processed per cron/manual run. | | zip_retention_days | 7 | Stored retention setting for future cleanup behavior. | | email_subject | Your Athenian image batch is ready | Completion email subject. | | email_from_name | Site name | Completion email sender name. | | email_from_address | Site admin email | Completion email sender address. |

Supported frontend/admin option values include:

| Field | Supported Values | | --- | --- | | Size | 1024x1024, 1536x1024, 1024x1536 | | Quality | auto, low, medium, high | | Background | auto, opaque, transparent | | Output format | png, jpeg, webp |

---

Hooks, Actions, and AJAX Endpoints

Shortcode

[athenian_batch_image_generation]

Cron Event

abig_process_queue

Registered schedule:

abig_every_five_minutes

The schedule runs every five minutes. On batch submission, the plugin also schedules a single event approximately 10 seconds later to begin processing promptly.

Form Submission Actions

admin_post_abig_submit_batch
admin_post_nopriv_abig_submit_batch

These allow both logged-in and logged-out submissions when the shortcode is available on a page.

Frontend Planner AJAX Actions

wp_ajax_abig_generate_prompt_rows
wp_ajax_nopriv_abig_generate_prompt_rows

These generate prompt rows from a creative brief.

Admin Queue AJAX Action

wp_ajax_abig_process_queue_now

This is protected by manage_options capability and the abig_process_queue_now nonce.

---

Security and Validation Notes

The plugin includes several important baseline safeguards:

• Direct file access guards with ABSPATH checks.
• WordPress nonce checks for batch submission and AJAX actions.
• manage_options capability check for manual queue execution.
• Sanitization for settings, prompts, email addresses, filenames, and planner output rows.
• Use of WordPress Media Library sideloading APIs.
• Use of wp_safe_redirect() after frontend submission.
• API failures are captured as WP_Error objects and stored on failed rows.

Important Access-Control Considerations

The shortcode submission endpoint and AI planner endpoint both include logged-out variants. This is useful for public or customer-facing portals, but it also means page-level access control should be handled intentionally.

Recommended production options:

• Place the shortcode behind a membership, account, or client portal page when generation should not be public.
• Add role-based shortcode access controls if only certain users should submit batches.
• Add rate limiting, CAPTCHA, Turnstile, or credit/account checks for public-facing use.
• Add per-user or per-email batch history and quotas.
• Add stronger validation against unsupported size, quality, background, or output format values server-side.

ZIP Access Consideration

ZIP files are currently written to the public uploads directory. This is convenient for download delivery, but a stricter portal may need signed URLs, expiring download tokens, or a permission-checked download endpoint.

---

Example CSV Template

prompt,negative_prompt,filename,size,quality,background,output_format
"Premium powder coating product hero image on a dark industrial workbench","blurry, distorted text, low quality","powder-hero-dark-industrial","1024x1024","high","opaque","png"
"Transparent-background product cutout of a powder coating sample jar","shadow artifacts, extra labels","powder-sample-cutout","1024x1024","high","transparent","png"
"Lifestyle image of a creator packing custom printed merchandise","messy hands, watermark, unreadable logo","creator-packaging-lifestyle","1536x1024","auto","opaque","webp"

---

Implementation Strengths

• Clean class-based plugin structure.
• Dedicated repository layer for custom database operations.
• Clear separation between admin UI, frontend shortcode UI, OpenAI client, processor, ZIP builder, and notifier.
• Queue-backed architecture instead of long-running frontend requests.
• Media Library integration for generated assets.
• ZIP delivery for completed batches.
• AI planner adds value before image generation by helping teams structure prompts.
• Configurable model, generation defaults, queue limits, and email settings.
• Recent batch visibility in wp-admin.
• PHP syntax verified successfully across all plugin PHP files in the inspected package.

---