Background Removal

Use a Background Removal data source to automatically strip image backgrounds and deliver clean PNG cutouts — or baked soft-shadow composites — to your templates.

What it is

A Background Removal data source is a special type (BACKGROUND_REMOVAL) that wraps a source data source and processes every image URL in one or more designated fields through an AI inference pipeline. The result is a transparent-background PNG stored in your workspace storage. Downstream workflows and templates read from the BG-removal data source exactly like any other.

The inference engine is REMBG (model: birefnet-general), running self-hosted on the render worker. After inference, optional post-processing — crop padding, CSS shadow presets, or baked SSN soft-shadow — is applied before the final PNG is cached.

When you'd use it

Your data source contains product photos with busy backgrounds and you need clean cutouts for ad templates.
You want a ground shadow baked into the PNG so it looks studio-ready without any CSS at render time.
You need to process the same source image across multiple workflows without paying the inference cost more than once (the cache ensures this automatically).
You want to strip backgrounds from images fetched from an external URL before they reach your template's image layer.

Quick start (user)

Create a Background Removal data source

Go to Dashboard → Data Sources (/dashboard/creative/data-sources).
Click New Data Source and select Background Removal as the type.
Choose a Source Data Source — this is the one whose image fields you want to process.
Select the Image fields to process (e.g. product_image, hero_shot). Only URL fields should be selected.
Configure Post-processing options (see settings reference below).
Click Create. ConnectWyze processes any existing source items immediately and continues processing new items as the source updates.

Use in a workflow

Point your workflow at the Background Removal data source instead of the original source. The _nobg field (or your configured outputSuffix) contains the processed image URL. Map it to any image layer in your template.

Settings reference

Configuration

Field	Type	Default	Description
Source data source	relation	—	The data source whose image fields will be processed.
Image fields	`string[]`	—	Field names that contain image URLs. Each URL in each listed field is processed independently.
Output suffix	string	`_nobg`	Suffix appended to the original field name to form the output field. `product_image` → `product_image_nobg`.
Process on source update	boolean	`true`	Automatically re-process images when the source item changes.

Post-processing options

Option	Type	Default	Description
Auto crop	boolean	`true`	Crops the output PNG to the subject's bounding box.
Crop padding	integer (%)	`5`	Padding around the subject after crop, expressed as a percentage of the longer dimension. Range 0–20.
Shadow style	enum	`NONE`	CSS or baked shadow applied to the cutout. See shadow modes below.

Shadow modes

Value	Type	Description
`NONE`	—	No shadow. Pure transparent PNG.
`DROP`	CSS	`drop-shadow(0 4px 8px rgba(0,0,0,0.25))` applied at render time.
`GROUND`	CSS	Elongated drop shadow under the subject, applied at render time.
`CUSTOM`	CSS	User-defined CSS `drop-shadow` layers configured in the data source settings.
`SSN_STUDIO`	Baked	Realistic overhead-IBL ground shadow generated by SSN inference and baked into the PNG. Suitable for studio overhead lighting (soft halo under subject).
`SSN_FORWARD`	Baked	Realistic forward-projected shadow (offset IBL), baked into the PNG.

CSS shadows (DROP, GROUND, CUSTOM) are applied at render time via CSS filter. They add no inference cost and do not change the cached PNG.

SSN shadows (SSN_STUDIO, SSN_FORWARD) are baked into the cached PNG during post-processing. The output is a padded square canvas with the subject in the upper portion and the shadow filling the bottom. Templates using SSN-processed images should treat the image as a pre-composited asset.

When SSN_STUDIO or SSN_FORWARD is selected, the Shadow tuning panel exposes three additional parameters:

Parameter	Range	Description
Intensity	0–1	Shadow opacity/strength.
Softness (gamma)	0.8–2.0	Shadow softness. Lower values produce harder edges.
Light angle (iblTopOffset)	0–8	IBL environment offset; controls where the shadow falls relative to the subject.

Credit cost

Each unique image URL processed by inference costs 1 credit. Cache hits are free.

Scenario	Credits used
Process 100 unique URLs	100
Same URL in 100 items	1 (99 cache hits)
Same URL in two separate workflows	1 total
Data source refresh — URLs unchanged	0
Same URL, different crop padding	1 (different `optionsHash`)

Credits come from the workspace balance (tier credits first, then purchased credits). If the workspace runs out of credits mid-processing, the remaining items are skipped with an error logged on the run.

Cache architecture

Background removal uses a two-tier cache:

Image URL
    │
    ▼  SHA256 hash(url)
BgRemovalRawCache  (keyed on workspaceId + urlHash + provider)
    │
    ├── HIT  → raw alpha PNG retrieved from storage
    │          (skips inference entirely)
    │
    └── MISS → run REMBG inference
               upload raw alpha PNG → store in BgRemovalRawCache
    │
    ▼  SHA256 hash(autoCrop + cropPadding + shadow + shadowConfig)
BgRemovalCache  (keyed on workspaceId + urlHash + provider + optionsHash)
    │
    ├── HIT  → return final processed PNG URL (free)
    │
    └── MISS → apply post-processing (crop, shadow)
               upload final PNG → store in BgRemovalCache
               deduct 1 credit

Raw cache (BgRemovalRawCache) stores the bare inference output (alpha PNG) before any post-processing. If you change only the crop padding or shadow style, the expensive inference step is skipped and only the cheaper post-processing step runs.

Final cache (BgRemovalCache) stores the fully post-processed PNG. If nothing about the image or its options has changed, the cached URL is returned immediately at zero cost.

Changing crop padding or shadow config invalidates the final cache and re-processes every item on next render. The raw alpha cache is reused, so credits are not charged again for inference — only the post-process pass runs.

ASCII diagram

Source item (image URL)
        │
        ▼
SHA256(url) → BgRemovalRawCache?
        │
        ├── HIT: raw PNG from storage
        │
        └── MISS: REMBG inference (birefnet-general)
                  → upload raw PNG
                  → write BgRemovalRawCache row
        │
        ▼
SHA256(options) → BgRemovalCache?
        │
        ├── HIT: return cached final PNG URL (0 credits)
        │
        └── MISS: post-process (autoCrop → shadow bake/CSS tag)
                  → upload final PNG
                  → write BgRemovalCache row
                  → deduct 1 credit
        │
        ▼
BG-removal item: { product_image_nobg: "https://..." }
        │
        ▼
Workflow → Template image layer

Troubleshooting

Symptom	Cause	Fix
Items show processing errors	REMBG service is unreachable or returned an error.	Check the BG removal run logs in Data Sources → [name] → Runs. If the error recurs, contact support with the run ID.
Output PNG looks correct but has no shadow	`SSN_STUDIO` / `SSN_FORWARD` was selected but the SSN worker was unavailable. The system throws an error rather than silently caching a shadowless result.	Check the SSN worker status. Re-trigger processing once the service is available.
Credits charged more than expected	Images were processed with different post-processing options (e.g. different crop padding), producing distinct `optionsHash` values — each unique option combination counts as a separate cache entry.	Standardise post-processing settings before running large batches.
Same image re-processed after data source update	The source image URL changed (even a query string change produces a different SHA256 hash).	Ensure source URLs are stable. If using redirects or signed URLs, resolve them to the canonical URL before feeding them in.
SSN output images look wider than expected	SSN bakes output to a padded square canvas. The subject occupies the upper portion; the shadow extends below.	Design your template image layer to accommodate square aspect ratio inputs.
`creditsPerImage` shows 0 for SSN	Correct. SSN inference runs locally — only the base REMBG inference step costs 1 credit. SSN is free on top.	No action needed.

Data Sources — create and manage source data sources.
Templates — bind BG-removal fields to template image layers.
Workflows — run bulk generation using a BG-removal data source.
Runs and creatives — monitor BG removal processing runs and browse results.
Troubleshooting — top-level rendering troubleshooting index.