Image

See also

This is the generation-time override. To author an image layer's full schema at import time, see Design Import → Layer Types → Image.

Available properties

Property	Description
image_url	String. HTTP(s) URL of your image, max 2 048 characters. File size max 20 MB. Supported: jpeg, png, webp, svg, gif, tiff, avif. Tiff is only supported for printer designs. Print designs can accept much larger files (up to 500 MB) for large-format use cases.
image_encoded	String. Base64 encoded image. Ignored if image_url is provided
opacity	Integer 0–100. Opacity of the image
fitting_type	See Fitting Type
alignment	See Alignment
mask_name / mask_properties	See Mask
filter_name / filter_properties	See Filter
overlay_direction / overlay_color_1 / overlay_color_2	See Overlay
shadow_color / shadow_blur / shadow_offset_x / shadow_offset_y	See Shadow
remove_bg / remove_bg_properties	See Remove Background
auto_focus / auto_focus_properties	See Auto Focus
expand / expand_properties	See Expand
upscale / upscale_properties	See Upscale
text_to_image / text_to_image_properties	See Text to Image & Inpainting. Ignored if image_url or image_encoded is given

Fitting type

fitting_type defines how the image fills its bounding box:

• cover: Fills the area entirely without changing aspect ratio (may crop) — equivalent to CSS object-fit: cover
• fill: Scales the image to fit entirely within the box (may leave empty space) — equivalent to CSS object-fit: contain

fill is CSS contain, not CSS fill

If you're familiar with CSS, note that Abyssale's fill maps to CSS contain, not CSS fill.

Value	Result
"fitting_type": "fill"
"fitting_type": "cover"

Alignment

alignment overrides the default image alignment.

• One string: top, middle, bottom, left, center, right
• Two strings: vertical + horizontal, e.g. "top left", "middle right"

Either half may also be custom — the value the editor stores for a hand-positioned layer. It resolves to the centre of that axis, so "custom custom" is the centre of the box and "custom left" is the middle of the left edge.

Value	Result
cover + alignment: middle center
cover + alignment: middle right
fill + alignment: bottom center
fill + alignment: middle center

Mask

mask_name applies a shape mask to the image. Only rounded_corners takes a mask_properties object — every other value below ignores it. mask_properties.radius is a single number or a per-corner map {"tl": …, "tr": …, "br": …, "bl": …}; mask_properties.skew_y (−22…22) slants the mask:

Value	Description	Preview
circle	Circular mask
rounded_corners	Rounded corners. Requires mask_properties: { "radius": <integer> } — pixels on static / animated, the format's physical unit on printer (see Units on Print Designs). For the full shape including per-corner radii, see Design Import → Layer Types → Image → mask_properties.
blob	Blob shape
squircle	Squircle shape
pentagon	Pentagon shape
hexagon	Hexagon shape
parallelogram	Parallelogram shape
window	Arched-window shape

Filter

filter_name applies a color filter:

• grayscale: Converts image to grayscale
• duotone: Applies a duotone filter. Requires filter_properties: { "name": "<duotone_name>" }

Available duotone names: blue_green, blue_orange, deep_green_light_green, BrightRed_light_yellow, brown_pale_green, brown_beige, deep_blue_green, deep_blue_red, deep_purple_orange, deep_purple_beige, deep_purple_pale_green, deep_blue_pale_green

Filter	Preview	Filter	Preview	Filter	Preview
Original		grayscale		duotone: blue_orange
duotone: deep_green_light_green		duotone: BrightRed_light_yellow		duotone: brown_pale_green
duotone: brown_beige		duotone: deep_blue_green		duotone: deep_blue_red
duotone: deep_purple_orange		duotone: deep_purple_beige		duotone: deep_purple_pale_green
duotone: deep_blue_pale_green

Overlay

Adds a two-tone color overlay across the image. All three properties are required:

• overlay_direction: "horizontal", "vertical", or "diagonal"
• overlay_color_1: First color (hex or CMYK)
• overlay_color_2: Second color (hex or CMYK). Set both to the same color for a monochrome overlay

Not the linear-gradient(...) syntax

The blended look between the two colors below is sometimes called a "gradient overlay," but overlay_color_1 / overlay_color_2 are plain hex colors, not Abyssale's linear-gradient(...) string (see Colors & Gradients) — that string syntax is not accepted here. The two-tone blend is produced automatically from the two flat colors and the chosen overlay_direction.

Value	Result
Gradient horizontal (overlay_color_1: "#FF000080", overlay_color_2: "#0000FF1A")
Gradient vertical
Gradient diagonal
Monochrome (both colors the same)

Remove background

Automatically removes the background from an image using AI.

Deprecated on synchronous generation

remove_bg still works on synchronous generation and existing integrations keep working, but it is deprecated there and not recommended: removing a background is an extra AI round-trip before the render, and that endpoint is hard-capped at 10 seconds. A large or slow source image can push the whole call past the cap, so instead of your asset you get 500 internal_server_error.

Remove backgrounds with asynchronous generation instead — it has no completion bound.

auto_focus is not affected and remains fully supported on both: it runs on Abyssale's own detection model and is fast enough that it does not put the synchronous budget at risk.

Parameter	Type	Description	Default
remove_bg	Boolean	Activates background removal	false
remove_bg_properties	Object	Additional settings
↳ remove_bg_crop	Boolean	Trims edges after removal	false
↳ model	String	Background removal model to use, see Models below	bria-rmbg-2-0

{
  "remove_bg": true,
  "remove_bg_properties": {
    "remove_bg_crop": true,
    "model": "birefnet"
  }
}

Value	Result
"remove_bg": true
"remove_bg": true + "remove_bg_crop": true

Background-removal models

Model	Description
bria-rmbg-2-0	BRIA RMBG 2.0 — default model
birefnet	BiRefNet
pixelcut	Pixelcut
imageUtils	ImageUtils
ideogram	Ideogram

Auto focus

Automatically detects and focuses on specified objects using AI.

Parameter	Type	Description	Default
auto_focus	Boolean	Activates auto-focus	false
auto_focus_properties	Object	Additional settings
↳ model	String	"generic" or "people". "face" is deprecated	"generic"
↳ focus_objects	Array of strings	Objects to focus on (generic model only). Uses Open Images Dataset labels
↳ focus_framing	String	people model only: "face", "head", "shoulders", "full_body"	"face"
↳ focus_zoom	String	people model only: "off", "low", "medium", "max"	"max"
↳ focus_target	String	people model only: "largest", "left", "middle", "right", "all"	"all"

The five settings can also be sent at the top level

auto_focus_model, focus_objects, focus_framing, focus_zoom and focus_target are accepted beside auto_focus as well as inside auto_focus_properties — same values, same defaults. Note the name: the model is auto_focus_model at the top level and model inside the object.

{ "auto_focus": true, "auto_focus_model": "people", "focus_framing": "head" }

Both forms are supported. If you send the same setting twice, the one inside auto_focus_properties wins, being the more specific.

The face model is deprecated

Use the people model with focus_framing: "face" instead. It detects faces with the same model, and additionally honours focus_zoom and focus_target — which face ignores entirely, so a request combining them with face silently gets neither.

Because focus_framing already defaults to "face", the migration is usually just dropping one word:

// Before — deprecated
{ "auto_focus": true, "auto_focus_properties": { "model": "face" } }

// After — identical framing, and now zoom and target work
{ "auto_focus": true, "auto_focus_properties": { "model": "people" } }

"face" keeps working and existing requests do not break. No removal date is set; see the deprecation policy.

Generic model example:

{
  "auto_focus": true,
  "auto_focus_properties": {
    "model": "generic",
    "focus_objects": ["Woman", "Car"]
  }
}

Value	Result
auto_focus: false
model: "generic"
model: "people", focus_framing: "face"
focus_objects: ["man"]
focus_objects: ["woman"]
focus_objects: ["boy"]
focus_objects: ["woman", "boy"]

People model example:

{
  "auto_focus": true,
  "auto_focus_properties": {
    "model": "people",
    "focus_framing": "shoulders",
    "focus_zoom": "low",
    "focus_target": "right"
  }
}

Value	Result
people, shoulders, low zoom, right
people, shoulders, low zoom, left
people, head, max zoom, left

Expand

Extends an image beyond its original borders using AI, generating new content that continues the scene. This is useful when the image is smaller than its bounding box, or when alignment leaves empty space on one or more sides — instead of cropping or padding, the empty area is filled by AI-generated content that matches the source image.

Ignored on fitting_type: "cover"

cover already fills the entire bounding box, so there is no empty space for expand to fill — the property is ignored. expand only has an effect with fitting_type: "fill".

Asynchronous generation only

expand is rejected on synchronous generation with 400 invalid_payload — an AI generation takes far longer than that endpoint's 10-second budget, so the field is not part of its contract at all. Use asynchronous generation.

Parameter	Type	Description	Default
expand	Boolean	Activates AI expand	false
expand_properties	Object	Additional settings
↳ model	String	Expand model to use, see Models below	flux-2-pro-outpaint

{
  "image_0": {
    "image_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/v2/e0d292f2-ec21-11e9-a539-3c408bf94155/a0263d93-0cf9-4b35-a856-0916d915741f/v2_7af1c7bb-6cbd-40c8-b8f7-43f23a3fc655.webp",
    "fitting_type": "fill",
    "alignment": "middle left",
    "hidden": false,
    "expand": true,
    "expand_properties": {
      "model": "bria-expand"
    }
  }
}

fitting_type: "fill" combined with an off-center alignment leaves empty space in the bounding box; expand fills that space instead of leaving it blank.

Case	Before	After
alignment: "middle left"
Wide box, image centered horizontally
Tall box, image centered vertically

Expand models

Model	Description
flux-2-pro-outpaint	FLUX.2 Pro Outpaint — default model
image-outpaint	Image Outpaint
bria-expand	BRIA Expand

Upscale

Re-renders an image at a higher resolution using AI, recovering detail instead of stretching pixels. Use it when the source image is smaller or softer than the format it is placed in.

Asynchronous generation only

upscale is rejected on synchronous generation with 400 invalid_payload — an AI generation takes far longer than that endpoint's 10-second budget, so the field is not part of its contract at all. Use asynchronous generation.

Parameter	Type	Description	Default
upscale	Boolean	Activates AI upscale	false
upscale_properties	Object	Additional settings
↳ model	String	Upscale model to use, see Models below	seedvr-upscale
↳ upscale_factor	Number	Width and height multiplier: 1, 2, 3 or 4	2

{
  "image_0": {
    "image_url": "https://example.com/low-resolution-photo.png",
    "upscale": true,
    "upscale_properties": {
      "model": "seedvr-upscale",
      "upscale_factor": 3
    }
  }
}

A 493 × 700 px source, upscaled with seedvr-upscale. The detail column crops the same area of each output:

upscale_factor	Result	Detail
Original — 493 × 700 px
2 — 992 × 1408 px
4 — 1984 × 2800 px

Upscale models

Model	Description	upscale_factor	Max output
seedvr-upscale	SeedVR — default model	1, 2, 3, 4	64 MP
topaz-precision	Topaz Precision	1, 2, 3, 4	72 MP
crystal-upscaler	Crystal Upscaler	1, 2, 3, 4	16 MP
bria-increase-resolution	Bria Increase Resolution	2, 4	8192 px per side

Size limits

• The source image must be at least 128 × 128 px.
• The output is capped per model — see Max output above. Each side of the source is multiplied by upscale_factor, so a 1000 × 1000 px source at 4 gives 4000 × 4000 px, 16 MP. A request over the cap is refused: lower upscale_factor, use a smaller source, or pick a model with a higher cap.
• upscale_factor: 1 keeps the dimensions and only enhances detail — useful for a soft or compressed source that is already the right size.

Text to Image & Inpainting

Generates an image from a text description using AI, or edits an existing image with AI (inpainting). Ignored if image_url or image_encoded is provided.

Asynchronous generation only

text_to_image is rejected on synchronous generation with 400 invalid_payload — an AI generation takes far longer than that endpoint's 10-second budget, so the field is not part of its contract at all. Use asynchronous generation.

Parameter	Type	Description	Default
text_to_image	Boolean or String	Activates AI image generation. A string is a shorthand for the prompt — see below	false
text_to_image_properties	Object	Generation settings
↳ prompt	String	Description of the image to generate, or of the edit to apply in inpainting mode. At least 3 words — shorter prompts are rejected	Required
↳ model	String	Model to use, see Models below	nano-banana-2
↳ ratio	String	Aspect ratio or size of the output. Allowed values depend on the model — see Models	Model-dependent
↳ quality	String	Output quality/resolution. Only supported by some models — see Models	Model-dependent
↳ inpaint_images	Array of strings	URL(s) of the image(s) to edit. When provided, switches generation to inpainting mode instead of pure text-to-image

Prompt shorthand

Instead of true plus a properties object, you can pass the prompt directly as the value of text_to_image. Append comma-separated URLs to supply inpainting sources:

{
  "image_0": { "text_to_image": "a lavender field at golden hour" }
}

{
  "image_0": { "text_to_image": "replace the sky,https://example.com/source.jpg" }
}

Both are expanded into text_to_image_properties before validation, so the 3-word minimum applies either way.

Text to image

Without inpaint_images, a new image is generated purely from the prompt:

{
  "text_to_image": true,
  "text_to_image_properties": {
    "prompt": "A sleek, modern glass villa situated in the middle of a minimalist lavender field. Sharp lines, reflection of the blue sky in the windows, wide-angle shot, architectural photography style, hyper-realistic.",
    "model": "nano-banana-2",
    "ratio": "16:9",
    "quality": "2K"
  }
}

Result

Inpainting

With inpaint_images, the model edits the provided image(s) according to the prompt instead of generating from scratch:

{
  "text_to_image": true,
  "text_to_image_properties": {
    "prompt": "enhance the product by adding a background decoration to highlight the product",
    "model": "gpt-image-2",
    "ratio": "square_hd",
    "quality": "low",
    "inpaint_images": [
      "https://production-banners.s3-eu-west-1.amazonaws.com/.../v2_2e4388e8-161d-4b15-a5b6-895fcebe2943.jpeg"
    ]
  }
}

Reference image (inpaint_images)	Result

Text-to-image and inpainting models

Both text-to-image generation and inpainting use the same models. ratio accepts either aspect-ratio values (e.g. "16:9"), named sizes (e.g. "square_hd"), or pixel dimensions (e.g. "1024x1024") depending on the model. Models marked Not supported for quality ignore the quality parameter if it is provided.

Model	ratio values	Default ratio	quality values	Default quality
gemini-3-pro	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9, 5:4, 4:5	1:1	1K, 2K, 4K	1K
kling-image-o3	1:1, 8:1, 4:1, 21:9, 16:9, 3:2, 4:3, 5:4, 4:5, 3:4, 2:3, 9:16, 1:4, 1:8	1:1	1K, 2K, 4K	1K
wan-2.7	square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9	square_hd	Not supported	—
gpt-image-1.5	1024x1024, 1536x1024, 1024x1536	1024x1024	low, medium, high	low
flux-2-pro	square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9	square_hd	Not supported	—
qwen-2511	square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9	square_hd	Not supported	—
nano-banana	21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16	1:1	Not supported	—
nano-banana-2 (default model)	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9, 5:4, 4:5, 4:1, 1:4, 8:1, 1:8	1:1	0.5K, 1K, 2K, 4K	0.5K
nano-banana-pro	21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16	1:1	1K, 2K, 4K	1K
seedream-4.5	square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9, auto_2K, auto_4K	square_hd	Not supported	—
seedream-5-pro	square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9, auto_1K, auto_2K	square_hd	Not supported	—
gpt-image-2	square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9	square_hd	low, medium, high	low
gpt-image-2.5-sunburst	square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9	square_hd	low, medium, high, xhigh, max	low
gpt-image-2.5-flare	square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9	square_hd	low, medium, high, xhigh, max	low
grok-imagine	2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2	1:1	1k, 2k	1k
flux-2-klein-9b	square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9	square_hd	Not supported	—
gemini-2.5-flash	21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16	1:1	Not supported	—
gemini-3.1-flash	1:1, 8:1, 4:1, 21:9, 16:9, 3:2, 4:3, 5:4, 4:5, 3:4, 2:3, 9:16, 1:4, 1:8	1:1	0.5K, 1K, 2K, 4K	0.5K

image is not a property

Sending an image key on an image or logo element is explicitly rejected — the property is image_url (or image_encoded).

Related

• Logo — the reduced image variant
• Common properties — hidden and shadows