ReferenceFind the facts

AI transformation reference

This page specifies the AI transformations, their GraphQL mutations and options, the records they produce, and how they interact with standard transformations.

Prerequisites

AI transformations require a valid ai-transform-token, and allow-ai-transforms must be enabled. Both are set on the web component. See DAT web component reference for these attributes.

Remove background

Removes the background from an image, leaving the subject on a transparent background.

  • Always available; no feature flag.

  • Executes immediately.

  • Returns a single result URL.

mutation RemoveBackground($url: String!) {
  ImageTransform_removeBackground(source: { url: $url }) {
    result
  }
}

Replace background

Replaces the image background using generative AI, with an optional text prompt.

  • Controlled by the replaceBackground feature flag.

  • Returns multiple variations.

  • Supports a text prompt to guide generation.

mutation GenerativeFill(
  $url: String!
  $options: ImageTransform_GenerativeFillOptionsInput
) {
  ImageTransform_generativeFill(source: { url: $url }, options: $options) {
    results
  }
}
Table 1. Options
Field Type Description

prompt

string

Text description to guide background generation.

variations

number

Number of alternative results to generate (default: 3).

Generative expand

Expands the canvas of an image beyond its original boundaries using AI-generated content.

  • Always available; no feature flag.

  • Not available when either dimension is 4000 pixels or greater (maximum: 3999).

  • Returns multiple variations.

  • Supports a text prompt and configurable placement and insets.

mutation GenerativeExpand(
  $url: String!
  $options: ImageTransform_BackgroundExpansionOptionsInput
) {
  ImageTransform_expandBackground(source: { url: $url }, options: $options) {
    results
  }
}
Table 2. Options
Field Type or values Description

placement.alignment.horizontal

left, center, right

Horizontal alignment of the original image within the expanded canvas.

placement.alignment.vertical

top, center, bottom

Vertical alignment of the original image within the expanded canvas.

placement.inset.top

number

Expansion in pixels above the image.

placement.inset.right

number

Expansion in pixels to the right.

placement.inset.bottom

number

Expansion in pixels below the image.

placement.inset.left

number

Expansion in pixels to the left.

size.width

number

Target canvas width (maximum: 3999).

size.height

number

Target canvas height (maximum: 3999).

prompt

string

Optional text to guide generation.

variations

number

Number of alternative results (default: 3).

AI transform records

AI transformations are tracked independently from standard transformations.

  • Each AI operation adds its result URL to the base URL history.

  • An AI transform record is stored with the operation type and any optional prompt.

  • The reset action undoes the last AI operation by reverting to the previous URL in the history.

  • AI transform records are included in the dat-selected-asset event payload.

Name Operation

background-removed

Remove background

background-replaced

Replace background

background-extended

Generative expand

Interaction with standard transformations

AI transformations and standard transformations operate on different layers.

  • Standard transformations (crop, resize, adjustments) are URL-encoded and appended to the base URL.

  • AI transformations modify the base URL itself, because the AI service returns a new image URL.

  • After an AI transformation, standard transformations are re-applied on top of the new base URL.

  • Both histories are preserved and included in event payloads.

See Standard transformation URL reference for the standard transformation URL scheme.

Related pages