AI Image Field for Drupal

AI Image for Drupal

Generate images from a text prompt, straight from an image field or from the
CKEditor 5 toolbar.

CONTENTS OF THIS FILE

• Introduction
• Requirements
• Installation
• Configuration
• Image sizes
• Alt text and captions
• Upgrading from 1.x
• Permissions

INTRODUCTION

This module adds two ways to create images with AI:

• An AI Image Generator widget for image fields. Enter a prompt, generate
  candidates, and attach the one you want.
• An AI Image Generator button for CKEditor 5, which inserts the generated
  image into the body.

As of 2.0 the module holds no vendor connection of its own. Every request goes
through the AI module using its
text_to_image operation type, so any provider implementing that operation
works: OpenAI, Amazon Bedrock, Stability AI, a self-hosted model, and so on.

REQUIREMENTS

• Drupal 11.2 or newer (including Drupal 12), and PHP 8.3+.
• AI (ai) 1.x or 2.x, and at least one AI
  provider module that supports the "Text to Image" operation type, for example
  AI Provider OpenAI.

Drupal 10 is not supported. The AI module requires Drupal 10.5 or 11.2+, and
its 2.x branch drops Drupal 10 entirely, so 2.0 of this module follows suit.
Sites still on Drupal 10 should stay on the 1.x branch.

INSTALLATION

Install as you would normally install a contributed Drupal module. Visit
https://www.drupal.org/node/1897420 for further information.

composer require drupal/openai_image
drush en openai_image

CONFIGURATION

1. Set up your AI provider first: install a provider module, add its API key
   through the Key module, and enable it under
   Administration > Configuration > AI > AI settings.
2. Optionally visit Administration > Configuration > System > AI Image to
   pick a specific provider and model for image generation. Left on
   Site default, the module follows whichever provider is set as the
   site-wide default for "Text to Image".
3. Grant the Generate images with AI permission to the roles that should be
   able to generate images.
4. For any image field, select the AI Image Generator form widget and set
   how many images each generation returns and which size preset to use.
5. For CKEditor 5, add the AI Image Generator button to the toolbar of a
   text format. The editor uses the number and size configured on the module
   settings page.

IMAGE SIZES

The size select offers presets first, then every exact size the configured
provider and model support.

Presets save you from thinking about pixels, and adapt when you switch
provider:

Preset Behaviour Original No size is sent; the provider uses its own default. Small The smallest size the provider advertises. Medium A middle size. Large The largest size the provider advertises.

Exact sizes are listed underneath, labelled by orientation, and read live
from the provider. With OpenAI's gpt-image models that is:

1024x1024 (square)   1024x1536 (portrait)   1536x1024 (landscape)
1024x1792 (portrait) 1792x1024 (landscape)

Presets only ever reach three of those, so pick an exact size when you want a
specific shape — portrait, for instance, is not reachable through a preset.

Providers that do not advertise their sizes fall back to 512x512, 1024x1024 and
1792x1024 for the presets. Any explicit WIDTHxHEIGHT value is passed straight
through, so sizes configured before presets existed keep behaving as they did.

ALT TEXT AND CAPTIONS

The prompt is what the image was generated from, so it doubles as a
description:

• Image fields — the prompt is offered as the alt text of the image you
  attach. It is only a default: alt text you have already written is never
  overwritten, and long prompts are truncated to the 512 characters Drupal
  allows.
• CKEditor 5 — the prompt is set as both the alt text and the caption of
  the inserted image. The caption is only added when the text format allows
  captions (the Caption images filter, filter_caption); otherwise just the
  alt text is set.

Note that the image resize dropdown in CKEditor 5 offers only Original. That
is Drupal core's own configuration for its image resize plugin and applies to
every image, not just generated ones. Images are resized by dragging their
handles.

UPGRADING FROM 1.x

Run database updates (drush updb) after updating the code. The update:

• Removes the OpenAI API key this module used to store. Keys now live in the
  AI module's provider configuration, managed by the Key module.
• Clears the stored model, since model IDs are now provider specific. Pick a
  provider and model again, or leave the setting on the site default.

Three things need attention by hand after updating:

• Drupal version. 2.0 requires Drupal 11.2+ and PHP 8.3+. Update Drupal
  before updating this module; on Drupal 10 the update will not be offered.

• Permissions. Generating images used to require only "access content".
  It now requires the new Generate images with AI permission, so grant that
  to the appropriate roles. Nothing can generate images until you do.

• Dependencies. The openai-php/client library is no longer required by
  this module. The AI provider you install brings its own.

Generated images are now written to the site's own files directory as
temporary files at generation time, and only made permanent once a user
attaches one. Images that are generated but never used are cleaned up by cron.

PERMISSIONS

Permission Purpose administer openai_image configuration Choose the provider and model. generate openai_image images Send prompts and save the results. Each generation consumes provider credits, so grant it only to trusted roles.