Tasks

Generate Image

Generate new images from a text prompt, or edit existing images using AI. Useful for AI-created visuals, product modifications, illustrations, thumbnails, and dynamic media assets.

# Example Uses

• Auto-generate a logo for a company or division
• Generate a picture for a PDF produced by the generate_pdf task
• Generate a cover image for a newsletter from its content
• Welcome a new user with a personalised image
• Generate an avatar based on a user's profile information
• Edit a product image to change its background
• Apply style or content changes to an existing image on a stub

# Detailed Description

This task supports two operations:

• Create — generates a new image from a text prompt
• Edit — modifies one or more existing images based on a text prompt

The operation is determined automatically: if you provide input_files the task will edit them, otherwise it will create a new image. You can also set operation explicitly to force one or the other.

Be as descriptive as possible in your prompt. Indicate the type of image you want — logo, banner, photo, painting, marketing material — and describe the style, colours, and content clearly.

# Supported Models

dall-e-2 and dall-e-3 are no longer supported.

# Basic Usage — Create

        {
  "tasktype": "generate_image",
  "taskapigatewayuuid": "e366a208-63a2-48ea-af74-e3e0abf703b4",
  "params": {
    "prompt": "A white cat sitting on a red sports car."
    "model": "gpt-image-2"
  }
}

      

# Basic Usage — Edit

        {
  "tasktype": "generate_image",
  "taskapigatewayuuid": "e366a208-63a2-48ea-af74-e3e0abf703b4",
  "params": {
    "prompt": "Change the car colour to blue.",
    "model": "gpt-image-2"
    "input_files": "~~stubpost.data.edit_files"
  }
}

      

# Parameters

# prompt

required

string

Describes what the image should look like. For edits, describe the change you want applied to the input image(s).

# model

optional

string

The image model to use.

Default: gpt-image-2

Supported: gpt-image-1 | gpt-image-1-mini | gpt-image-1.5 | gpt-image-2

# operation

optional

string

Forces the task to create a new image or edit existing ones. When set to auto, the operation is inferred from whether input_files is provided.

Default: auto

One Of: auto | create | edit

# input_files

optional

array

One or more Stubber file references to use as the base for an edit. Providing this triggers the edit operation when operation is auto. Up to 16 images are supported.

        [{ "fileuuid": "<fileuuid>" }]

      

# mask

optional

object

A Stubber file reference to an image that defines which area of the input image to edit. Only relevant for edit operations.

        { "fileuuid": "<fileuuid>" }

      

# filename

optional

string

The filename for the generated image stored on the Stubber file server.

Default: {stubref}_{stubpostuuid}_generate_image.{output_format}

# size

optional

string

The dimensions of the generated image.

Default: 1024x1024

Standard sizes: 1024x1024 | 1536x1024 | 1024x1536 | auto

Custom resolutions are also supported for gpt-image-2 — specify as WIDTHxHEIGHT where both values are divisible by 16, the aspect ratio is between 1:3 and 3:1, and the total resolution is at least 1024x1024.

# quality

optional

string

Controls the quality of the generated image. Higher quality increases generation time.

Default: auto

One Of: auto | high | medium | low

# background

optional

string

Controls whether the image background is transparent or opaque. Transparency is only supported on models that output PNG or WebP.

Default: auto

One Of: auto | transparent | opaque

# output_format

optional

string

The file format of the generated image.

Default: png

One Of: png | webp | jpeg

# input_fidelity

optional

string

How closely the edited image should follow the input image(s). Only relevant for edit operations.

One Of: high | low

# disable_model_response

optional

boolean

When true, the generated image will not be posted as an event on the stub. The image is still uploaded to the file server and available in the task payload.

Default: false

# Result

# Result