nobg.sh API Developer Documentation

About

@nobg/api is a zero-config Node.js wrapper for the nobg.sh background removal API.

@nobg/api wraps the nobg.sh background removal API with a minimal, Node-first interface. It supports local files, buffers, and base64 payloads while exposing progress hooks to keep your UI responsive.

The SDK mirrors the REST endpoints, so you can switch between the CLI, direct HTTP requests, or the wrapper without changing your pipeline architecture.

Installation

Install the nobg.sh SDK before wiring it into your app or automation workflow.

Install the package from npm:

Terminal

npm i @nobg/api

The SDK ships as an ES module. For CommonJS projects, use dynamic import() or transpile during build time.

Parameters

Core arguments supported by the Node.js SDK. Mirror these when calling the REST API directly.

apiKey (string) — Required. Your nobg.sh API key.
inputImage (string | Buffer | { base64: string }) — Required. Path to a file, a Node buffer, or a base64 payload.
onDownloadProgress ((event) => void) — Optional Axios progress callback fired during downloads.
onUploadProgress ((event) => void) — Optional progress callback triggered while uploading the source image.
options — Optional configuration object:
format (webp | png) — Default webp. Target output format.
returnBase64 (boolean) — Default false. Return a base64 payload instead of writing to disk.
returnMask (boolean) — Default false. Set true to fetch the alpha mask only.
w (number) — Optional width. Keeps aspect ratio.
h (number) — Optional height. Keeps aspect ratio.
exact_resize (boolean) — Default false. Forces exact width × height (may distort).
angle (number) — Default 0. Rotate output in degrees.
expand (boolean) — Default true. Adds padding so rotated images are not cropped.
bg_color (string) — Optional solid background (hex or named color).

Environment Setup

Store secrets in a .env file to keep API keys out of source control.

Create a .env file in the project root and add your API key. Load it with dotenv or your framework's secret manager.

Terminal

NOBG_API_KEY=sk_live_your_api_key

Node.js Example

Full Node.js script demonstrating background removal with optional progress hooks.

Run this script as script.mjs or inside a server action. The SDK cleans up temporary files for you once you call cleanup().

JavaScript

import { removeBackground } from "@nobg/api"
import dotenv from "dotenv"

dotenv.config()

const apiKey = process.env.NOBG_API_KEY

const onDownloadProgress = console.log
const onUploadProgress = console.log

removeBackground({
  apiKey,
  inputImage: "./input.png", // string | Buffer | { base64: string }
  onDownloadProgress,
  onUploadProgress,
  options: {
    format: "png",
  },
}).then(({ outputPath, cleanup }) => {
  console.log("✅ background removed and saved under path =", outputPath)
  // cleanup() // optionally remove the processed file from disk
})

Showing Progress

Both progress hooks receive AxiosProgressEvent objects, enabling live UI updates.

Each callback fires multiple times during upload and download. Use the progress ratio or byte counts to drive progress bars.

Terminal

{ loaded: 65687, total: 68474, progress: 0.959, upload: true }
{ loaded: 68474, total: 68474, progress: 1, upload: true }
{ loaded: 1002, total: 68824, progress: 0.0145, download: true }
{ loaded: 68824, total: 68824, progress: 1, download: true }
✅ background removed and saved under path=/tmp/nobg--3339-DBqqeJ2eOs4D-.png

cURL Example

Remove backgrounds via cURL with optional resize, mask, and background parameters.

Terminal

curl -X POST "https://api.nobg.sh/v1/remove" \
  -H "Authorization: Bearer $NOBG_API_KEY" \
  -F "image=@/path/to/image.jpg" \
  -F "format=webp" \
  -F "w=800" \
  -F "h=600" \
  -F "exact_resize=false" \
  -F "mask=false" \
  -F "bg_color=#ffffffff" \
  -F "angle=0" \
  -F "expand=true"

Raw HTTP Example

Use multipart/form-data directly if you prefer to work without helper libraries.

HTTP

POST /v1/remove HTTP/1.1
Host: api.nobg.sh
Authorization: Bearer YOUR_NOBG_API_KEY
Content-Type: multipart/form-data; boundary=----BOUNDARY

------BOUNDARY
Content-Disposition: form-data; name="image"; filename="image.jpg"
Content-Type: image/jpeg

<binary data>
------BOUNDARY
Content-Disposition: form-data; name="format"
webp
------BOUNDARY
Content-Disposition: form-data; name="w"
800
------BOUNDARY
Content-Disposition: form-data; name="h"
600
------BOUNDARY
Content-Disposition: form-data; name="exact_resize"
false
------BOUNDARY
Content-Disposition: form-data; name="mask"
false
------BOUNDARY
Content-Disposition: form-data; name="bg_color"
#ffffffff
------BOUNDARY
Content-Disposition: form-data; name="angle"
0
------BOUNDARY
Content-Disposition: form-data; name="expand"
true
------BOUNDARY--

Python (requests) Example

Call the REST API from Python using the popular requests library.

Python

import os

import requests

API_KEY = os.getenv("NOBG_API_KEY", "YOUR_NOBG_API_KEY")
url = "https://api.nobg.sh/v1/remove"

headers = {"Authorization": f"Bearer {API_KEY}"}
files = {"image": open("/path/to/image.jpg", "rb")}
data = {
  "format": "webp",
  "w": 800,
  "h": 600,
  "exact_resize": "false",
  "mask": "false",
  "bg_color": "#ffffffff",
  "angle": 0,
  "expand": "true",
}

response = requests.post(url, headers=headers, files=files, data=data)
if response.ok:
    with open("output.webp", "wb") as file:
        file.write(response.content)
    print("Background removed successfully → saved as output.webp")
else:
    print("Error:", response.status_code, response.text)

Notes

Additional context and helpful links while you ship to production.

Built and hosted by the nobg.sh team in Germany.
Use the main-site navigation to reach pricing, bulk editing, apps, blog, FAQ, and contact resources.
Need help? Contact support@nobg.sh or message us via the in-app chat.