Civitai Developer

Appearance

Image background removal ​

The imageBackgroundRemoval step type takes an image and returns the same image with its background removed, as a transparent-background cutout. Segmentation runs on BiRefNet on Civitai's Comfy workers, with blur-fusion foreground estimation to clean up edge fringing — no model selection or tuning knobs to worry about.

Common uses:

  • Product shots and profile pictures — isolate the subject for compositing
  • Sticker / thumbnail pipelines (chain imageGen → imageBackgroundRemoval)
  • Preparing cutouts for downstream layout tools that expect an alpha channel

Prerequisites ​

The simplest request ​

Use the per-recipe endpoint when you're processing one image and don't need webhooks or multi-step chaining:

http
POST https://orchestration.civitai.com/v2/consumer/recipes/imageBackgroundRemoval?wait=60
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "image": "https://image.civitai.com/.../00890-23.jpeg"
}
POST/v2/consumer/recipes/imageBackgroundRemoval
Set your Civitai API token via the Token button in the navbar to enable Try It.
Request body — edit to customize (e.g. swap the image URL or prompt)
Valid JSON

The defaults produce a PNG with the alpha channel carrying the cutout. The recipe endpoint responds with the step's output object directly — the image blob described in Reading the result.

Via the generic workflow endpoint ​

Equivalent request through SubmitWorkflow — use this path when you need webhooks, tags, or to chain with other steps:

http
POST https://orchestration.civitai.com/v2/consumer/workflows?wait=60
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "steps": [{
    "$type": "imageBackgroundRemoval",
    "input": {
      "image": "https://image.civitai.com/.../00890-23.jpeg",
      "format": "webp"
    }
  }]
}
POST/v2/consumer/workflows
Set your Civitai API token via the Token button in the navbar to enable Try It.
Request body — edit to customize (e.g. swap the image URL or prompt)
Valid JSON

Input fields ​

See the ImageBackgroundRemovalInput schema for the full definition.

FieldRequiredDefaultNotes
image✅—URL, data URL, or raw Base64 string. Civitai CDN URLs work directly.
formatpngpng or webp. Both preserve the alpha channel; WebP produces smaller files.

The segmentation mask is computed at 1024×1024 and upscaled to the source resolution, so extremely fine detail (individual hairs, fur wisps) on very large sources resolves at the mask's precision, not the source's. The foreground pass runs at full source resolution.

Chaining: generate then cut out ​

Produce an image and strip its background in a single submission:

json
{
  "steps": [
    {
      "$type": "imageGen",
      "name": "hero",
      "input": {
        "engine": "flux2",
        "model": "klein",
        "operation": "createImage",
        "modelVersion": "4b",
        "prompt": "Product photo of a vintage camera on a cluttered wooden desk",
        "width": 1024,
        "height": 1024
      }
    },
    {
      "$type": "imageBackgroundRemoval",
      "name": "hero-cutout",
      "input": {
        "image": {
          "$ref": "hero",
          "path": "output.images[0].url"
        }
      }
    }
  ]
}

The { "$ref": "hero", "path": "output.images[0].url" } reference creates a dependency — hero-cutout doesn't start until hero succeeds, and its image field is filled in with the generated image's signed URL at runtime. See Workflows → Dependencies for the full reference syntax.

POST/v2/consumer/workflows
Set your Civitai API token via the Token button in the navbar to enable Try It.
Request body — edit to customize (e.g. swap the image URL or prompt)
Valid JSON

For the reverse composition — placing the cutout on a new background, resizing it, or converting formats — chain an Image conversion step after this one.

Reading the result ​

A successful imageBackgroundRemoval step emits a single image blob. Through SubmitWorkflow / GetWorkflow it arrives inside the workflow envelope shown below; the per-recipe endpoint returns the inner output object on its own.

json
{
  "status": "succeeded",
  "steps": [{
    "name": "0",
    "$type": "imageBackgroundRemoval",
    "status": "succeeded",
    "output": {
      "image": {
        "id": "blob_....png",
        "width": 512,
        "height": 768,
        "available": true,
        "url": "https://.../signed.png",
        "urlExpiresAt": "2027-07-16T17:25:34.0666142Z"
      }
    }
  }]
}

Fields:

  • image — the cutout blob (singular — the step always returns exactly one image). width and height match the source image; background removal never resizes.
  • available — false until the worker has uploaded the result; on a terminal succeeded workflow it's true.

Blob URLs are signed and expire — refetch the workflow or call GetBlob for a fresh URL.

Runtime ​

Execution is dominated by a fixed cost: the segmentation mask always runs at 1024×1024 regardless of source size, so wall time moves only slightly with resolution — roughly 5 s of GPU execution plus ~0.6 s per megapixel of source, before queue and container overhead. A single request comfortably fits wait=60.

Resubmitting the same image + format typically serves the previous output from cache — see Workflows → Result caching.

Cost ​

Billed in Buzz on the workflow's transactions. Use whatif=true for an exact preview; see Payments (Buzz) for currency selection.

Cost tracks estimated runtime, which is floor-dominated — source resolution moves the price only slightly:

megapixels = width × height / 1 000 000
buzz       = max(1, round((4.7 + 0.6 × megapixels) × 10 / 8))
ShapeBuzz
512×768 source6
1024×1024 source7
2048×2048 source9
4096×4096 source18

The format choice doesn't affect the Buzz price.

Troubleshooting ​

SymptomLikely causeFix
400 with "Input image failed to download from URL."URL not publicly reachable, or data URL malformedMake sure the URL is fetchable without auth; re-encode the Base64 payload.
400 with "The JSON value could not be converted to … ImageBackgroundRemovalFormat"format outside png / webpUse one of the two supported values; chain Image conversion for other formats.
400 with "missing required properties including: 'image'"Empty or misspelled bodyimage is the only required field.
Halo or soft edges around fine detail (hair, fur)Mask precision is capped at 1024×1024Expected on very large sources; downscale before submitting if the cutout will be displayed small anyway.
Request timed out (wait expired)Busy queueResubmit via SubmitWorkflow with wait=0 and poll, or use a webhook.

Civitai Developer Documentation

© 2026 Civitai