Background Remover

Product ID: background_remover · Billing: Beeble Cloud credits Extract an alpha matte from an image or video for compositing. See the Background Remover product guide for matte examples and advice on preparing footage.

Before you start

Create an API key for an organization with this product enabled.
Prepare your media as Beeble URIs, authorized CDN URLs, public/presigned HTTPS URLs, or base64 data URIs.
Select an available model below; complete any required consent in Beeble Cloud.

Models and inputs

Set BEEBLE_API_KEY and, for internal teams, BEEBLE_TEAM_ID.

curl --fail-with-body "https://api.beeble.ai/v1/products/background_remover/models" \
  -H "x-api-key: $BEEBLE_API_KEY" \
  -H "X-Beeble-Team-Id: ${BEEBLE_TEAM_ID:-}"

import json
import os
import requests

headers = {"x-api-key": os.environ["BEEBLE_API_KEY"]}
if team_id := os.environ.get("BEEBLE_TEAM_ID"):
    headers["X-Beeble-Team-Id"] = team_id

response = requests.get(
    "https://api.beeble.ai/v1/products/background_remover/models",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

const headers = { "x-api-key": process.env.BEEBLE_API_KEY }
if (process.env.BEEBLE_TEAM_ID) {
  headers["X-Beeble-Team-Id"] = process.env.BEEBLE_TEAM_ID
}
const response = await fetch(
  "https://api.beeble.ai/v1/products/background_remover/models",
  {
    headers,
    signal: AbortSignal.timeout(30_000),
  },
)
if (!response.ok) throw new Error(await response.text())
console.log(JSON.stringify(await response.json(), null, 2))

Response (200): models contains each model’s id, name, input_schema, and any requires_consent value. Use the selected model’s input_schema for required inputs, types, defaults, and supported values. Request parameters and response schema

Model	Use it for
MatAnyone	General background removal and foreground-mask propagation through a video.
CorridorKey	Green-screen keying, including green-spill removal and matte refinement.

Submit a job

Schemas: Request body · Response. The inputs object follows your selected model’s input_schema above. Save as request.json with your media URIs. The Beeble URIs below can be replaced with any supported single-file media input. Use a unique idempotency_key for each new job; keep it unchanged on retries.

{
  "model_id": "matanyone",
  "billing_unit": "credits",
  "idempotency_key": "background_remover-example-001",
  "inputs": {
    "source": "beeble://uploads/your-upload-id/source.mp4"
  }
}

Python requires requests; JavaScript examples run in Node.js.

curl --fail-with-body https://api.beeble.ai/v1/products/background_remover/jobs \
  -H "x-api-key: $BEEBLE_API_KEY" \
  -H "X-Beeble-Team-Id: ${BEEBLE_TEAM_ID:-}" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

import json
import os
from pathlib import Path

import requests

headers = {"x-api-key": os.environ["BEEBLE_API_KEY"]}
if team_id := os.environ.get("BEEBLE_TEAM_ID"):
    headers["X-Beeble-Team-Id"] = team_id

response = requests.post(
    "https://api.beeble.ai/v1/products/background_remover/jobs",
    headers=headers,
    json=json.loads(Path("request.json").read_text()),
    timeout=120,
)
response.raise_for_status()
job_id = response.json()["id"]
print(job_id)

import { readFile } from "node:fs/promises"

const headers = {
  "x-api-key": process.env.BEEBLE_API_KEY,
  "Content-Type": "application/json",
}
if (process.env.BEEBLE_TEAM_ID) {
  headers["X-Beeble-Team-Id"] = process.env.BEEBLE_TEAM_ID
}

const response = await fetch(
  "https://api.beeble.ai/v1/products/background_remover/jobs",
  {
    method: "POST",
    headers,
    body: await readFile("request.json", "utf8"),
    signal: AbortSignal.timeout(120_000),
  },
)
if (!response.ok) throw new Error(await response.text())
const { id: jobId } = await response.json()
console.log(jobId)

Response (202, abbreviated):

{
  "id": "dap_example",
  "status": "processing",
  "outputs": {}
}

Results and constraints

The server measures media type and frame count; generation_type and frame_count can be omitted. See Billing & credits for spending caps and refunds.

Completed response

Poll the job using the returned id until status is success. Stop on failed, cancelled, or credit_required. Example response (200, success; abbreviated): URLs are illustrative. Available outputs depend on the model and input media.

{
  "id": "dap_example",
  "product": "background_remover",
  "status": "success",
  "outputs": {
    "alpha": "https://cdn.beeble.ai/example/alpha.mp4?signed-parameters"
  }
}

Download outputs.alpha for the matte. A foreground result, when available, is returned as outputs.foreground.

Get started

Products

Core concepts

Integrations

Before you start

Models and inputs

Submit a job

Results and constraints

Completed response

​Before you start

​Models and inputs

​Submit a job

​Results and constraints

​Completed response

Before you start

Models and inputs

Submit a job

Results and constraints

Completed response