Quickstart

1. Get Your API Key

Create an Account

Go to dash.poof.bg and sign up with your email, Google, GitHub, GitLab or Microsoft.

Copy Your API Key

Your API key is displayed on the dashboard. It starts with pk_.

Keep It Secret

Treat your API key like a password. Never commit it to version control or expose it in client-side code.

2. Make Your First Request

Choose your preferred method:

cURL
Python
TypeScript

curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: pk_your_api_key" \
  -F "file=@input.jpg" \
  -o output.png

Install the SDK:

pip install poofbg

Remove a background:

from poof import Poof

client = Poof(api_key="pk_your_api_key")

# From a file
result = client.remove_background("input.jpg")
result.save("output.png")

# From bytes
with open("input.jpg", "rb") as f:
    result = client.remove_background(f.read())
    result.save("output.png")

Install the SDK:

npm install @poof-bg/js

Remove a background:

import { Poof } from '@poof-bg/js';
import fs from 'fs/promises';

const poof = new Poof({ apiKey: 'pk_your_api_key' });

const result = await poof.removeBackground('input.jpg');
await fs.writeFile('output.png', Buffer.from(result.data));

3. See the Result

Your output file now contains the image with the background removed:

Before	After
Original photo with background	Transparent PNG, background removed

Success! You’ve made your first background removal request.

What’s Next?

Customize Output

Learn about formats, sizes, and background colors

Check Usage

Monitor your credit usage via the API

Handle Errors

Implement robust error handling

Explore Integrations

Use our official SDKs and integrations

Remove Video Backgrounds

Transparent WebM, ProRes or GIF, or MP4 on a solid colour, from clips and animated GIFs up to 5 minutes. Works best on a clearly separated subject

Poll a Job

Check a video job’s progress and download its result

Common Options

Here are some popular parameter combinations:

# Get a JPEG with white background
curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "format=jpg" \
  -F "channels=rgb" \
  -F "bg_color=#ffffff" \
  -o result.jpg

# Get a small preview (faster; every successful image request costs 1 credit regardless of size)
curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "size=preview" \
  -o preview.png

# Crop to subject bounds
curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "crop=true" \
  -o cropped.png

# Get just the grayscale alpha mask
curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "channels=alpha" \
  -o mask.png

Video

The same endpoint removes backgrounds from video; Poof detects the media type from the file content. A video is accepted with 202 and a job: wait for the job, then download its result_url. Video costs 5 credits per second of source video (10 above 30 fps). Animated GIF input is billed at 5 credits per second whatever its frame rate.

cURL
Python
TypeScript

# Submit a clip; the response is a job with an "id" and a "status_url"
curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@clip.mp4" \
  -F "format=webm"

# Poll until "status" is "completed", then download "result_url"
curl https://api.poof.bg/v1/jobs/job_8f3a1c2e9b7d4a10 \
  -H "x-api-key: YOUR_API_KEY"

from poof import Poof

client = Poof(api_key="pk_your_api_key")

job = client.remove_background("clip.mp4", format="webm")   # returns a Job
job = client.wait_for_job(job)
client.download(job, "clip-no-bg.webm")

Needs poofbg 0.3.0 or later.

import { Poof, isJob } from '@poof-bg/js';
import fs from 'fs/promises';

const poof = new Poof({ apiKey: 'pk_your_api_key' });

const submitted = await poof.removeBackground('clip.mp4', { format: 'webm' });
if (isJob(submitted)) {
  const job = await poof.waitForJob(submitted);
  const video = await fetch(job.resultUrl!);
  await fs.writeFile('clip-no-bg.webm', Buffer.from(await video.arrayBuffer()));
}

Needs @poof-bg/js 1.2.0 or later.

See the video background removal guide for limits, credits and output formats, Video for the full reference, and the Python and TypeScript SDK pages for the job helpers.

Getting Started

Video guides

API Reference

1. Get Your API Key

2. Make Your First Request

3. See the Result

What’s Next?

Customize Output

Check Usage

Handle Errors

Explore Integrations

Remove Video Backgrounds

Poll a Job

Common Options

Video

​1. Get Your API Key

​2. Make Your First Request

​3. See the Result

​What’s Next?

Customize Output

Check Usage

Handle Errors

Explore Integrations

Remove Video Backgrounds

Poll a Job

​Common Options

​Video

1. Get Your API Key

2. Make Your First Request

3. See the Result

What’s Next?

Common Options

Video