Image generation

Every post wants a header image and most of us don’t have one. The image generator takes a prompt, gets an image back from OpenAI or Gemini, uploads it to your media folder and drops it into the body or a frontmatter image field. There’s also an Edit with AI route for images you already have.

It needs a provider that can make images, which means OpenAI (gpt-image-2) or Gemini (gemini-3-pro-image-preview or gemini-2.5-flash-image). Anthropic can’t, and custom endpoints are never asked to. If your current provider is the wrong one, the modal says so and points you at AI Settings.

Generating an image#

Open the toolbar AI menu and pick Generate Image. Describe the image, choose your options and click Generate. A preview appears when it’s done.

The options depend on the provider:

OpenAI images are always generated at medium quality and come back as PNG. Gemini returns whatever format it likes, and Emet keeps it.

Reference images (Gemini only)#

Gemini can take images as part of the prompt, which is how you get “the same illustration style as the last one” or “this photo, but at dusk”. Add them with Upload (JPEG, PNG or WebP from your computer), Browse (pick something already in your media library) or by dragging files onto the modal. Thumbnails appear above the buttons; hover and click the cross to remove one. Adding the first reference image also sets the aspect ratio dropdown to match it.

Using the result#

Once there’s a preview, the footer offers:

• Insert Image uploads the file and inserts it into the body at the cursor position you had when you opened the modal.
• Set as {field}, one button per image-type field in the section, uploads and writes the public path into that frontmatter field.
• Retry runs the same prompt again, for when the first attempt is nearly right.
• New clears everything for a fresh prompt.

There’s an Image name (optional) box under the preview. Fill it in and the file is saved as a slug of that name plus the right extension (my-hero-image.png). Leave it blank and you get {timestamp}-ai-generated.png, where the timestamp is milliseconds since the epoch; descriptive it isn’t, so it’s worth naming them.

The upload goes to your configured media folder (static/images by default) with the commit message “Add AI-generated image: {filename}”, and the inserted path uses the public path (/images by default). Both come from media in site.yaml.

Editing an existing image#

Images you already have can be reworked rather than regenerated from scratch. There are three ways in, all needing an image-capable provider:

• Click an image in the visual editor and use the sparkles button next to the alt text field.
• Select an image in the media library and click Edit with AI. The library opened from an image field’s Browse button in the frontmatter panel has the same button, and the result goes into that field.

Each opens the generator with the existing image already loaded as a reference and the aspect ratio set to match. Describe the change, generate, and you get one extra footer button: Replace {name}, which overwrites the original file in place with the commit message “Replace image: {name}”. Because the path doesn’t change, every page that uses the image picks up the new version. Insert Image is still there if you’d rather keep both.

Note that reference images are a Gemini feature, so with OpenAI selected the original image is shown but not sent; you’re effectively generating from the prompt alone.

From the chat#

The chat panel has a generate_image tool. Ask for “a header image of a lighthouse at night” and the model will propose a generation, which you approve or deny. It uploads the file as ai-{timestamp}.png (or .jpg) and tells the model the path; it’s then up to the model (and you) to put it somewhere. The size and quality options are available to the model; the Gemini-specific ones aren’t.

Configuration#

ai:
  enabled: true
  features:
    imageGeneration: true

media:
  folder: static/images
  public_path: /images

imageGeneration: false hides Generate Image and every Edit with AI button. See Providers for setting up OpenAI or Gemini.