Image Graphics (BG Remove Flow)

POST /api/v1/assets/addons/image_graphics

Submit an Image Graphics processing request. The API accepts a JSON payload with two top-level keys: assets and operations.

Important

All operations are optional, but at least one valid object in assets and one valid object in operations must be specified.
Operations are executed in the order listed. For example, bg_remove must be listed before bg_add.
Recommended order for multiple operations: Remove Background → Add Background → Add Graphics → Add Border

Additional notes:

If background is provided then canvas is not required and vice versa. If both are provided, canvas takes precedence and is placed on top of background.
border is scaled relative to the asset, background, or canvas. Background/canvas dimensions take precedence over asset dimensions.
background does not support the position attribute — it is always set to fit.
Asset positioning only works when there is a background or canvas. Ensure boundaries are valid: width/height of asset + x/y of position < width/height of background or canvas.

JSON Structure

{
  "assets": [
    {
      "ASSET_ID_1": {
        "options": {
          "canvas": { "size": { "width": 1000, "height": 1000 }, "color": "#ffffff" },
          "size": { "width": 500, "height": 500 },
          "crop": { "left": 0, "top": 0, "right": 200, "bottom": 300 },
          "position": { "x": 0, "y": 0 },
          "disposition": { "add_as_conversion": true, "create_asset": false, "conversion_name": "image-graphics" }
        }
      }
    }
  ],
  "operations": [
    { "bg_remove": { "options": { "mode": "portrait", "strength": "medium", "remove_artifacts": true } } },
    { "bg_add": { "options": { "color": "#ffffff", "image_id": "IMAGE_ASSET_ID", "mode": "as-is", "size": { "width": 1000, "height": 1000 } } } },
    { "border_add": { "options": { "image_id": "IMAGE_ASSET_ID" } } },
    { "graphics_add": { "graphics": [{ "type": "image", "options": { "image_id": "IMAGE_ASSET_ID", "position": { "x": 0, "y": 0 }, "size": { "width": 100, "height": 100 } } }] } }
  ]
}

Asset Options

Multiple assets can be passed in the request. Each asset can have its own options:

Parameter	Type	Description
`canvas`	JSON	(optional) Canvas options. Canvas is optional if `bg_add` is specified.
`canvas`.`color`	string	(optional) Color applied to the canvas. If not provided, set to transparent.
`canvas`.`size`	JSON	Canvas dimensions as `{ "width": ..., "height": ... }`.
`size`	JSON	(optional) Size of the output image as `{ "width": ..., "height": ... }`.
`crop`	JSON	(optional) Crop dimensions as `{ "left", "top", "right", "bottom" }` relative to original image size.
`position`	JSON	(optional) Position on canvas as `{ "x", "y" }`. Defaults to center.
`disposition`.`add_as_conversion`	boolean	If `true`, output is added as a conversion to the original asset. Default: `false`.
`disposition`.`create_asset`	boolean	If `true`, output is added as a new asset. Default: `false`.
`disposition`.`conversion_name`	string	Name for the conversion (max 30 alphanumeric characters). Required when `add_as_conversion` is `true`.
`disposition`.`mode`	string	Mode for metadata: `APPEND` or `REPLACE`.
`disposition`.`data_schema_id`	integer	Asset Schema ID for the new asset.
`disposition`.`metadata`	JSON	(optional) Metadata specification. Supports `inherit`, `src_asset_id`, `inherit_fields`, `data`.

Notes: If crop is provided, dimensions are relative to the original image size. When crop is specified, the asset is cropped first, then used in subsequent operations. If add_as_conversion is true, metadata is ignored. If inherit is true and inherit_fields is not provided, all source metadata is inherited.

Operations

Operation	Description
`bg_remove`	Remove background from the image. See Background Removal for parameter details.
`bg_add`	Add a background color or image behind the asset.
`border_add`	Add a border image around the asset.
`graphics_add`	Overlay one or more graphic images on top of the asset.

Options for bg_add: color (string), image_id (string), mode ("as-is" or "stretch"), size (JSON).

Options for border_add: image_id (string) — Asset ID of the border image.

Options for graphics_add: Each graphic has image_url or image_id, color, position, size.

Example: Remove Background and Add as Conversion

{
  "assets": [{ "ff4b207c2094489399238d52126a0a88": { "options": { "disposition": { "add_as_conversion": true, "conversion_name": "image-graphics" } } } }],
  "operations": [{ "bg_remove": {} }]
}

Example: Remove Background and Create New Asset

{
  "assets": [{ "ff4b207c2094489399238d52126a0a88": { "options": { "disposition": { "create_asset": true } } } }],
  "operations": [{ "bg_remove": {} }]
}

Response JSON

The API returns a JSON response:

{
    "job_id": 1234
}

Key	Value	Description
`job_id`	integer	The job ID to track the job

Use the Image Graphics Job API to retrieve the URL of the processed output image.

Request

Responses

Successful operation

Image Graphics (BG Remove Flow)

/api/v1/assets/addons/image_graphics

JSON Structure​

Asset Options​

Operations​

Example: Remove Background and Add as Conversion​

Example: Remove Background and Create New Asset​

Response JSON​

Request​

Responses​