background_removal

Background Removal

Remove image backgrounds (OSS by default, or Gemini AI when useAI=true). PNG output.

Fields API: GET /v1/tools/background_removal/fields · public GET /api/developer/tools/public/background_removal/fields

Price: 80 API credits ($0.008) per successful_execution

Version: 1

Accepted types: image/jpeg, image/jpg, image/png, image/gif, image/webp

Max file: 50 MB

Timeout: 600000 ms

Batch jobs: supported · max 10 files · job ≤ 200 MB · docs

Optional parameters: edgeProfile, decontamination. AI-enhanced mode is not available on the Developer API.

Multipart fields

Normalized catalog for agents and UIs (same as the sandbox field picker). Send each name as a multipart form key with tool and file.

Name	Type	Default	Notes
decontamination	number	0	Decontamination
edgeProfile	enum · Crisp Cut, Soft Feather, Complex Hair/Fibers	"Crisp Cut"	Edge Profile
useAI	boolean	false	AI-related · When true, prefer Gemini AI removal. If AI fails, OSS removal still runs and the image result is returned with ai_error. Billed via ai_pricing only when AI succeeds.

Output schema

{
  "image_base64": "string",
  "mime_type": "image/png",
  "size_bytes": "number",
  "used_ai": "boolean",
  "ai_error": "object|null"
}

cURL

curl -X POST "$TOOLGRID_API_BASE/v1/execute" \
  -H "Authorization: Bearer tg_api_YOUR_SECRET" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -F "tool=background_removal" \
  -F "file=@photo.jpg" \
  -F "edgeProfile=Crisp Cut" \
  -F "decontamination=0"

Node.js (FormData)

Requires Node.js 18+ (global fetch/FormData/Blob). Set TOOLGRID_API_BASE and TOOLGRID_API_KEY.

import { readFile } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';

const API_BASE = process.env.TOOLGRID_API_BASE || 'http://localhost:5000';
const API_KEY = process.env.TOOLGRID_API_KEY; // tg_api_… — never log this

if (!API_KEY) {
  throw new Error('Set TOOLGRID_API_KEY');
}

const form = new FormData();
form.set('tool', 'background_removal');
form.set('file', new Blob([await readFile('./photo.jpg')]), 'photo.jpg');
form.set('edgeProfile', 'Crisp Cut');
form.set('decontamination', '0');

const res = await fetch(`${API_BASE}/v1/execute`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Idempotency-Key': randomUUID(),
  },
  body: form,
});

const body = await res.json();
if (!res.ok || !body.success) {
  console.error(body.error?.code, body.error?.message, body.request_id);
  process.exit(1);
}

console.log('request_id', body.request_id);
console.log('billing', body.billing);
// PNG as Base64 — decode to write a file if needed
console.log(body.result.mime_type, body.result.size_bytes);

Billing rules · Errors

Multipart fields

Normalized catalog for agents and UIs (same as the sandbox field picker). Send each name as a multipart form key with tool and file.

Name	Type	Default	Notes
decontamination	number	0	Decontamination
edgeProfile	enum · Crisp Cut, Soft Feather, Complex Hair/Fibers	"Crisp Cut"	Edge Profile
useAI	boolean	false	AI-related · When true, prefer Gemini AI removal. If AI fails, OSS removal still runs and the image result is returned with ai_error. Billed via ai_pricing only when AI succeeds.

curl -X POST "$TOOLGRID_API_BASE/v1/execute" \ -H "Authorization: Bearer tg_api_YOUR_SECRET" \ -H "Idempotency-Key: YOUR_UNIQUE_KEY" \ -F "tool=background_removal" \ -F "file=@photo.jpg" \ -F "edgeProfile=Crisp Cut" \ -F "decontamination=0"

Node.js (FormData)

Requires Node.js 18+ (global fetch/FormData/Blob). Set TOOLGRID_API_BASE and TOOLGRID_API_KEY.

import { readFile } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';

const API_BASE = process.env.TOOLGRID_API_BASE || 'http://localhost:5000';
const API_KEY = process.env.TOOLGRID_API_KEY; // tg_api_… — never log this

if (!API_KEY) {
  throw new Error('Set TOOLGRID_API_KEY');
}

const form = new FormData();
form.set('tool', 'background_removal');
form.set('file', new Blob([await readFile('./photo.jpg')]), 'photo.jpg');
form.set('edgeProfile', 'Crisp Cut');
form.set('decontamination', '0');

const res = await fetch(`${API_BASE}/v1/execute`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Idempotency-Key': randomUUID(),
  },
  body: form,
});

const body = await res.json();
if (!res.ok || !body.success) {
  console.error(body.error?.code, body.error?.message, body.request_id);
  process.exit(1);
}

console.log('request_id', body.request_id);
console.log('billing', body.billing);
// PNG as Base64 — decode to write a file if needed
console.log(body.result.mime_type, body.result.size_bytes);