Skip to main content

Function: removeBackground()

removeBackground(opts): Promise<BackgroundRemovalResult>

Defined in: packages/agentos/src/api/removeBackground.ts:104

Cuts the subject of an image out of its background: the subject on a transparent PNG (or WebP), as a URL on the provider's storage or as bytes.

The built-in provider is fal's BiRefNet v2 (fal-ai/birefnet/v2), called through fal's synchronous API with FAL_API_KEY (or the call's apiKey). Other backends implement IBackgroundRemovalProvider and register with registerBackgroundRemovalProvider(id, provider).

Parameters​

opts​

RemoveBackgroundOptions

The image and how to return the cut-out.

Returns​

Promise<BackgroundRemovalResult>

The cut-out, the matte with returnMask, the provider and model, and the call's duration.

Throws​

invalid_request before any request for an image it cannot send or a malformed option, and for an answer the provider refuses (fal: 400, 413, 422); provider_failed for any other failure; timeout when timeoutMs passes. A failed answer carries its HTTP status.

Throws​

When the provider id is unknown or its key is missing.

Throws​

The reason of opts.signal when the caller aborts.

Example​

import fs from 'node:fs';
import { removeBackground } from '@framers/agentos';

// The cut-out's URL (fal's CDN).
const { image } = await removeBackground({ image: 'https://example.com/hero.png' });

// The cut-out's bytes, and the matte.
const { image: png, mask } = await removeBackground({
image: fs.readFileSync('hero.jpg'),
output: 'buffer',
returnMask: true,
});
fs.writeFileSync('hero-cut.png', png.buffer!);