OpenAI Images

Generate and edit images with OpenAI's gpt-image models from any workflow.

This Module turns text prompts into images and applies prompt-guided edits to existing images (optionally constrained by a mask). Results land in a Session variable as a data URL and, if you ask, as a file, ready to send to the user or store.

How it works

Each Task sends one request to OpenAI's image endpoints and saves the result. Image inputs accept an https://… URL, a data:image/...;base64,… data URL, a file, or a {variable} containing one of those. gpt-image models return the image itself, not a hosted link, so the result is a data URL (data:image/png;base64,…); set Store the file in to also keep it as a file you can attach or save.

OpenAI retired DALL·E 2 and 3 on 12 May 2026 and retires gpt-image-1 on 23 October 2026. A Process that still names a retired model runs on gpt-image-2 instead, with a warning in the Session log; update the step's model when you see it.

Configuration

Each OpenAI Module is configured separately, per Environment. This Module has its own API key, so you can reuse the key you set on the core OpenAI Module or use a dedicated one (for example to track this capability's spend on its own).

Field	Type	Required	Description
OpenAI API Key	string	Yes	Your OpenAI API key (sk-...) for this Module. Stored securely. Find it in OpenAI Console → API keys → Create new secret key.
OpenAI Organization	string	No	Your OpenAI organization ID (e.g. org-abc123), if your account belongs to one.

Files. Image and mask sources accept a file as well as a URL or data URL: ref-session:{photo} or ref-storage:logo.png; see File fields. Both Tasks can also keep the image as a file: set Store the file in (and Also save it as for a saved file).

Tasks

All Tasks in this Module are Generic (all Channels): they run the same regardless of how the Session was started.

Output fields: type a variable name without braces (for example image) and pick its type (string, number, true/false, object, date). The Task saves its result there, and any later Task can use it by writing {image}.

OpenAIGenerateImageTask

Generates an image from a text prompt.

Property	Type	Required	Example	Description
Prompt	string	Yes	{imagePrompt}	Text prompt. Supports {variable} placeholders.
Model	string	Yes	gpt-image-2	gpt-image-2 (default), gpt-image-2.5-sunburst, gpt-image-2.5-flare, or any image model your account offers.
Size	string	No	1536x1024	auto (the model chooses), 1024x1024, 1536x1024 (landscape) or 1024x1536 (portrait).
Quality	choice	No	medium	low, medium or high. Empty: the model decides. Higher quality takes longer and costs more.
Background	choice	No	transparent	transparent or opaque. Transparent needs PNG or WebP.
File format	choice	No	webp	png (default), jpeg or webp.
Store the image in	string	Yes	image	Receives the image as a data URL.
Store the file in	file	No	imageFile	Optional: also keep the image as a file.

Example: Set Prompt = {imagePrompt}, Size = 1024x1024, Quality = medium, Store the image in = image, Store the file in = imageFile. With {imagePrompt} = "A watercolor lighthouse at dawn", the Task saves the image to image and the file to imageFile, which an OutputTask can attach.

OpenAIEditImageTask

Edits an existing image with a text prompt and an optional mask. Transparent pixels in the mask mark the areas to edit. It also makes variations: describe the variation in the prompt ("the same scene in winter").

Property	Type	Required	Example	Description
Prompt	string	Yes	{editPrompt}	What to change. Supports {variable} placeholders.
Model	string	Yes	gpt-image-2	Same models as Generate.
Image	string	Yes	{imageUrl}	A file, URL, data URL, or {variable} containing one of those.
Image file name	string	No	input.png	Filename including extension. Default input.png.
Mask	string	No	{maskUrl}	Optional. Same format as Image.
Mask file name	string	No	mask.png	Default mask.png.
Size, Quality, Background, File format		No		As for Generate.
Store the image in	string	Yes	editedImage	Receives the edited image as a data URL.
Store the file in	file	No	editedFile	Optional: also keep it as a file.

Example: Set Image = {imageUrl}, Mask = {maskUrl}, Prompt = Replace the sky with a starry night, Store the image in = editedImage. The Task edits only the transparent mask area and saves the result to editedImage.

Image variations. The old Variation task used an endpoint only DALL·E 2 served and was removed with it. Use Edit image with a prompt that describes the variation.

Common recipes

Generate an illustration and send it to the user

Ask the user what to draw, generate the image, and reply with it attached. Input and Output Tasks come from the Standard Module.

1. InputTask Output Variable = imagePrompt (e.g. the user types "A watercolor lighthouse at dawn").
2. OpenAIGenerateImageTask Prompt = {imagePrompt}, Size = 1024x1024, Store the image in = image, Store the file in = imageFile.
3. OutputTask Message = Here is your image., attachment = ref-session:{imageFile}.

Best practices

1. Keep a file, not a huge variable. For anything you send or keep, set Store the file in and pass the file on; data URLs are large.
2. Pick quality for the job. low is fast and cheap for drafts and thumbnails; high for final artwork.
3. Use JPEG or WebP for photos to keep files small; PNG or WebP when you need a transparent background.

Troubleshooting

… was retired by OpenAI; gpt-image-2 was used.

The step names a model OpenAI no longer serves. The image was made with gpt-image-2; change the step's model to remove the warning.

data: URL is huge

A multi-megabyte image as a data URL bloats the Session. Set Store the file in and keep only the file.

Error codes

Code	Name	Description
3005	TaskInvalidData	A required property is missing, a size or option is not valid, or an output field is not a valid variable name details
4001	ModuleException	OpenAI rejected the request (e.g. a policy-violating prompt) or returned no image details
4008	ModuleMissingConfiguration	The OpenAI API key is not set in this Module's Environment configuration details
4009	ModuleInputEmpty	The prompt or image source resolved to an empty value details
4012	ModuleInvalidData	The Session data could not be read or the image could not be loaded details
4022	ModuleLogWarning	The step's model is retired by OpenAI and its replacement was used details

See the Error Code Reference for the full list.

Related pages

• OpenAI Module: the family core, with chat, embeddings and moderation.