Image Graphics JSON Format

The Image Graphics 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"
          }
        }
      }
    },
    {
      "ASSET_ID_2": {
        "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": {
            "create_asset": true,
            "metadata": {
              "inherit": true,
              "src_asset_id": "ASSET_ID_2",
              "inherit_fields": ["siteID", "venueID"],
              "data": { "key1": "value1", "key2": "value2" }
            },
            "mode": "APPEND",
            "data_schema_id": 1
          }
        }
      }
    }
  ],
  "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 }
            }
          }
        ]
      }
    }
  ]
}

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": {}
    }
  ]
}