Remove Background

curl --request POST \
  --url https://api.dreep.cloud/api/v1/bg-remove \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form format=png \
  --form folder=products/cutouts \
  --form folderId=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form autoCreateFolders=true

import requests

url = "https://api.dreep.cloud/api/v1/bg-remove"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "format": "png",
    "folder": "products/cutouts",
    "folderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "autoCreateFolders": "true"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('format', 'png');
form.append('folder', 'products/cutouts');
form.append('folderId', '3c90c3cc-0d44-4b50-8888-8dd25736052a');
form.append('autoCreateFolders', 'true');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.dreep.cloud/api/v1/bg-remove', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dreep.cloud/api/v1/bg-remove",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\n\r\npng\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folder\"\r\n\r\nproducts/cutouts\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folderId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"autoCreateFolders\"\r\n\r\ntrue\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dreep.cloud/api/v1/bg-remove"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\n\r\npng\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folder\"\r\n\r\nproducts/cutouts\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folderId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"autoCreateFolders\"\r\n\r\ntrue\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dreep.cloud/api/v1/bg-remove")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\n\r\npng\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folder\"\r\n\r\nproducts/cutouts\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folderId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"autoCreateFolders\"\r\n\r\ntrue\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dreep.cloud/api/v1/bg-remove")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\n\r\npng\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folder\"\r\n\r\nproducts/cutouts\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folderId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"autoCreateFolders\"\r\n\r\ntrue\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "asset": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "storageKey": "<string>",
    "url": "<string>",
    "format": "png",
    "width": 123,
    "height": 123,
    "sizeBytes": 123
  }
}

{
  "error": true,
  "message": "Invalid request parameters",
  "code": "invalid_request"
}

{
  "error": true,
  "message": "Invalid request parameters",
  "code": "invalid_request"
}

Background Removal

Remove Background

Upload an image and get back a cutout of the subject with a transparent background, saved to your Dreep storage as a new asset.

The cutout keeps its alpha channel — it is never flattened onto a colour. To serve it on a background, pass bg to the fetch endpoint (/api/v1/fetch/{id}?bg=ffffff). That runs as an ordinary transformation, so a single removal can serve any number of background colours without being charged again.

Background removals are billed from a consumable add-on rather than a plan allowance. With no credits remaining the endpoint returns 402.

POST

api

bg-remove

Remove Background

curl --request POST \
  --url https://api.dreep.cloud/api/v1/bg-remove \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form format=png \
  --form folder=products/cutouts \
  --form folderId=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form autoCreateFolders=true

import requests

url = "https://api.dreep.cloud/api/v1/bg-remove"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "format": "png",
    "folder": "products/cutouts",
    "folderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "autoCreateFolders": "true"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('format', 'png');
form.append('folder', 'products/cutouts');
form.append('folderId', '3c90c3cc-0d44-4b50-8888-8dd25736052a');
form.append('autoCreateFolders', 'true');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.dreep.cloud/api/v1/bg-remove', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dreep.cloud/api/v1/bg-remove",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\n\r\npng\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folder\"\r\n\r\nproducts/cutouts\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folderId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"autoCreateFolders\"\r\n\r\ntrue\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dreep.cloud/api/v1/bg-remove"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\n\r\npng\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folder\"\r\n\r\nproducts/cutouts\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folderId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"autoCreateFolders\"\r\n\r\ntrue\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dreep.cloud/api/v1/bg-remove")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\n\r\npng\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folder\"\r\n\r\nproducts/cutouts\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folderId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"autoCreateFolders\"\r\n\r\ntrue\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dreep.cloud/api/v1/bg-remove")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\n\r\npng\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folder\"\r\n\r\nproducts/cutouts\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"folderId\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"autoCreateFolders\"\r\n\r\ntrue\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "asset": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "storageKey": "<string>",
    "url": "<string>",
    "format": "png",
    "width": 123,
    "height": 123,
    "sizeBytes": 123
  }
}

{
  "error": true,
  "message": "Invalid request parameters",
  "code": "invalid_request"
}

{
  "error": true,
  "message": "Invalid request parameters",
  "code": "invalid_request"
}

Choosing a background colour

The cutout is stored with its transparency intact and is never flattened onto a colour. To put it on a background, pass bg to the fetch endpoint:

# transparent — the stored cutout
https://api.dreep.cloud/api/v1/fetch/7fa3d9e0.png

# on white
https://api.dreep.cloud/api/v1/fetch/7fa3d9e0.png?bg=ffffff

# on brand navy, resized, as WebP
https://api.dreep.cloud/api/v1/fetch/7fa3d9e0.png?bg=1e3a8a&width=800&format=webp

bg is hex without a leading #. Three, six, or eight characters — the eight-character form carries alpha. This is why the colour is applied at delivery rather than baked in: one removal serves any number of backgrounds. Each colour is an ordinary transformation, cached permanently after its first request, so you are not charged another removal for it.

Saving to a folder

Name a destination and the cutout is stored there. Use folder (a path, created on demand) or folderId (a UUID):

curl -X POST "https://api.dreep.cloud/api/v1/bg-remove" \
  -H "Authorization: Bearer drp_live_xxxxx" \
  -F "[email protected]" \
  -F "folder=products/cutouts"

With no folder given, the cutout is saved to the project’s default folder. See Folders & Paths.

Output format

PNG by default. Pass format=webp for a smaller file at the same transparency:

curl -X POST "https://api.dreep.cloud/api/v1/bg-remove" \
  -H "Authorization: Bearer drp_live_xxxxx" \
  -F "[email protected]" \
  -F "format=webp"

{
  "asset": {
    "id": "7fa3d9e0-fec9-4a76-ac53-4b576500b43a",
    "storageKey": "originals/2b9b4e61/7fa3d9e0.webp",
    "url": "https://api.dreep.cloud/api/v1/fetch/7fa3d9e0.webp",
    "format": "webp",
    "width": 1200,
    "height": 1600,
    "sizeBytes": 184320
  }
}

Only png and webp are accepted. JPEG has no alpha channel, so a cutout encoded as JPEG would arrive with a solid background and silently lose the transparency you paid for.

Billing

Background removals come from a consumable add-on, not a plan allowance — no plan includes them by default. Each successful removal spends one credit. With no credits left the endpoint returns 402 with code: "LIMIT_EXCEEDED" and featureKey: "bg_removals". Credits are only spent once the cutout is stored, so a failed request costs nothing.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data

file

required

The image to cut out. JPEG, PNG or WebP.

format

enum<string>

default:png

Output format. Only alpha-capable formats are accepted — a cutout encoded as JPEG would lose its transparency.

Available options:

png,

webp

folder

string

Slug path of the folder to save the cutout into, relative to the project root. Missing folders are created.

Example:

"products/cutouts"

folderId

string<uuid>

UUID of an existing folder to save the cutout into. Mutually exclusive with folder.

autoCreateFolders

enum<string>

default:true

Set to false to require that folder already exists.

Available options:

true,

false

Response

Background removed

asset

object

The stored cutout.

Show child attributes

Upload

OCR

Background Removal

Media

Folders

Presets

Usage & Billing

Remove Background

Choosing a background colour

Saving to a folder

Output format

Billing

Authorizations

Body

Response

​Choosing a background colour

​Saving to a folder

​Output format

​Billing

Authorizations

Body

Response

Choosing a background colour

Saving to a folder

Output format

Billing