@carve.photos/sdk

Remove backgrounds from images and videos with the Carve.Photos API. Node.js SDK with TypeScript support, zero dependencies, and automatic polling — pass a file, get the result.

Installation

npm install @carve.photos/sdk

Quick Start

Remove background from image

const { CarveClient } = require("@carve.photos/sdk");

const client = new CarveClient("YOUR_API_KEY");

// Simple usage
const result = await client.removeBackground("photo.jpg");
await result.save("result.png");

// With parameters
const result = await client.removeBackground("photo.jpg", {
  format: "webp",
  size: "hd",
  bgColor: "#FFFFFF",
  crop: true,
  cropMargin: "5%",
});
await result.save("result.webp");

Remove background from video

const { CarveClient } = require("@carve.photos/sdk");

const client = new CarveClient("YOUR_API_KEY");

// Simple usage
const result = await client.removeBackgroundVideo("video.mp4");
await result.save("result.mp4");

// With parameters
const result = await client.removeBackgroundVideo("video.mp4", {
  format: "mp4",
  processingType: "human",
  backgroundColor: "#00B140",
  startTimeSec: 2.0,
  endTimeSec: 8.5,
});
await result.save("result.mp4");

Check balance

const balance = await client.getBalance();
console.log(`Balance: ${balance.total} credits`);

API Key

Get your API key at carve.photos/profile.
Free credits are included with registration.

Features

• Images: PNG, JPEG, WebP, AVIF — up to 25 megapixels
• Video: MP4, MOV, WEBM — up to 4K, 30 seconds
• TypeScript: Full type definitions included
• Zero dependencies: Uses native fetch (Node 18+)
• Automatic polling: SDK handles status polling internally

Error Handling

const { CarveClient, CarveError } = require("@carve.photos/sdk");

const client = new CarveClient("YOUR_API_KEY");

try {
  const result = await client.removeBackground("photo.jpg");
  await result.save("result.png");
} catch (error) {
  if (error instanceof CarveError) {
    console.error(`Error: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);
    console.error(`Detail: ${JSON.stringify(error.detail)}`);
  }
}

Documentation

• API Documentation
• Swagger
• Pricing

License

MIT