babayaga 207cb53f6f media : background | watermark

2025-08-11 12:25:45 +02:00

14 KiB

Raw Blame History

Bria AI Background Remove CLI Documentation

The pm-media background:remove:bria command uses Bria AI's professional-grade background removal service for enterprise-quality results. Bria AI offers advanced features including content moderation, alpha channel preservation, and high-precision edge detection.

Installation
Setup
Basic Usage
Command Line Options
API Usage
Examples
Bria AI vs Replicate
Advanced Features
Performance Tips
Troubleshooting

Installation

npm install @polymech/media

Setup

1. Get Bria AI API Key

Visit Bria AI API Documentation
Register for an account
Get your API token from the dashboard
Copy your API token

2. Set API Key

You can provide your API key in multiple ways:

Option A: Configuration File (Recommended)

// In your config
{
  bria: {
    key: "your_bria_api_token_here"
  }
}

Option B: Environment Variable

export BRIA_API_TOKEN="your_bria_api_token_here"

Option C: Command Line Argument

pm-media background:remove:bria --src input.jpg --apiKey "your_bria_api_token_here"

Basic Usage

pm-media background:remove:bria --src <input> --dst <output> [options]

Required Parameters

--src: Source files (FILE|FOLDER|GLOB pattern)

Optional Parameters

--dst: Destination path (defaults to source location with modified name)
--apiKey: Bria API key (if not set via config or environment variable)

Command Line Options

Core Options

Option	Type	Default	Description
`--src`	string	required	Source files (FILE\|FOLDER\|GLOB)
`--dst`	string	-	Destination path
`--apiKey`	string	-	Bria API key

Bria AI Specific Options

Option	Type	Default	Description
`--sync`	boolean	true	Use synchronous processing
`--contentModeration`	boolean	false	Enable content moderation
`--preserveAlpha`	boolean	true	Preserve alpha channel from input

Utility Options

Option	Type	Default	Description
`--dry`	boolean	false	Preview mode (no API calls)
`--verbose`	boolean	false	Show detailed processing info
`--debug`	boolean	false	Enable debug messages
`--logLevel`	string	"info"	Log level (warn\|info\|debug\|error)

API Usage

Import the Library

import { 
  briaBackgroundRemove,
  removeBriaBackground,
  BriaBackgroundRemoveOptions 
} from '@polymech/media';

Single File Background Removal

import { removeBriaBackground } from '@polymech/media';

await removeBriaBackground(
  'input.jpg',
  'output.png',
  {
    apiKey: 'your_bria_api_token',
    sync: true,
    contentModeration: false,
    preserveAlpha: true
  }
);

Batch Processing API

import { briaBackgroundRemove } from '@polymech/media';

const options: BriaBackgroundRemoveOptions = {
  src: 'photos/*.jpg',
  dst: 'no-bg/',
  apiKey: process.env.BRIA_API_TOKEN,
  sync: true,
  contentModeration: true,
  preserveAlpha: true,
  // ... other IOptions
};

await briaBackgroundRemove(options);

Advanced Configuration

const enterpriseOptions: BriaBackgroundRemoveOptions = {
  src: 'professional/*.jpg',
  dst: 'processed/',
  apiKey: 'your_token',
  sync: true,
  contentModeration: true, // Enterprise content filtering
  preserveAlpha: true,     // Maintain transparency
  verbose: true
};

await briaBackgroundRemove(enterpriseOptions);

Examples

Example 1: Basic Background Removal

# Remove background from a single image
pm-media background:remove:bria \
  --src "photo.jpg" \
  --dst "no-background.png"

Example 2: Professional Batch Processing

# Process multiple images with content moderation
pm-media background:remove:bria \
  --src "photos/*.jpg" \
  --dst "processed/" \
  --contentModeration \
  --verbose

Example 3: E-commerce Product Images

# Professional product photography processing
pm-media background:remove:bria \
  --src "products/*.jpg" \
  --dst "catalog/" \
  --preserveAlpha \
  --sync

Example 4: Studio Photography Workflow

# High-quality portrait processing
pm-media background:remove:bria \
  --src "studio-photos/*.jpg" \
  --dst "final/" \
  --contentModeration \
  --preserveAlpha \
  --verbose

Example 5: Safe Content Processing

# Process with content moderation enabled
pm-media background:remove:bria \
  --src "user-uploads/*.jpg" \
  --dst "moderated/" \
  --contentModeration \
  --sync

Example 6: Dry Run Preview

# Preview what would be processed
pm-media background:remove:bria \
  --src "batch/*.jpg" \
  --dst "output/" \
  --dry \
  --verbose

Example 7: Alpha Channel Preservation

# Maintain original transparency
pm-media background:remove:bria \
  --src "images-with-alpha/*.png" \
  --dst "processed/" \
  --preserveAlpha

Bria AI vs Replicate

When to Use Bria AI

✅ Choose Bria AI for:

Enterprise/Commercial Use: Professional-grade service
Content Moderation: Built-in safety features
Alpha Channel Preservation: Advanced transparency handling
Consistent Quality: Enterprise-level reliability
Compliance: Content safety for business applications

When to Use Replicate

✅ Choose Replicate for:

Experimentation: Multiple model options
Custom Models: Access to specialized models
Alpha Matting: Fine-tuned edge refinement
Cost Optimization: Various pricing models
Flexibility: Different AI models for different use cases

Feature Comparison

Feature	Bria AI	Replicate
Quality	Enterprise-grade	High quality
Content Moderation	✅ Built-in	❌ Not available
Alpha Preservation	✅ Advanced	✅ Basic
Model Selection	❌ Single model	✅ Multiple models
Alpha Matting	❌ Not available	✅ Available
Enterprise Support	✅ Yes	❌ Community
Compliance	✅ Enterprise	❌ Basic

Advanced Features

Content Moderation

Bria AI includes built-in content moderation to ensure safe processing:

# Enable content moderation for user-generated content
pm-media background:remove:bria \
  --src "user-uploads/*.jpg" \
  --dst "safe-processed/" \
  --contentModeration \
  --verbose

Benefits:

Prevents processing of inappropriate content
Returns detailed error messages for failed moderation
Suitable for public-facing applications
Compliant with enterprise content policies

Alpha Channel Preservation

Advanced transparency handling for professional workflows:

# Preserve original alpha channel information
pm-media background:remove:bria \
  --src "complex-transparency/*.png" \
  --dst "processed/" \
  --preserveAlpha

Features:

Maintains partial transparency values
Preserves original alpha channel data
Professional-quality edge handling
Perfect for layered compositions

Synchronous vs Asynchronous Processing

# Synchronous (immediate results)
pm-media background:remove:bria --src input.jpg --dst output.png --sync

# Asynchronous (for large batches)
pm-media background:remove:bria --src "batch/*.jpg" --dst "output/" --sync false

File Format Support

Supported Input Formats

JPEG (.jpg, .jpeg)
PNG (.png)
WebP (.webp)

Output Format

PNG with transparency (recommended)
High-quality background removal
Preserves original image quality

Quality Guidelines

# Best quality settings
pm-media background:remove:bria \
  --src "high-res/*.jpg" \
  --dst "premium/" \
  --preserveAlpha \
  --sync \
  --verbose

Performance Tips

1. Use Synchronous Processing

# Recommended for most use cases
--sync true

2. Batch Processing Strategy

# Process in reasonable batches
pm-media background:remove:bria --src "batch1/*.jpg" --dst "output1/"
pm-media background:remove:bria --src "batch2/*.jpg" --dst "output2/"

3. Content Moderation for Safety

# Enable for user-generated content
--contentModeration

4. Alpha Channel Optimization

# Only when needed (slightly slower)
--preserveAlpha

Cost Considerations

Bria AI Pricing

Background removal costs per API call. Check current pricing at Bria AI Pricing.

Cost Optimization

# Test with dry run first
pm-media background:remove:bria --src "*.jpg" --dst "output/" --dry

# Use content moderation to avoid processing inappropriate content
--contentModeration

Troubleshooting

Common Issues

"Bria API key is required"

# Check configuration
echo $BRIA_API_TOKEN

# Or use command line
pm-media background:remove:bria --src input.jpg --apiKey "your_token"

"API error: 422"

Content moderation failed
Image contains inappropriate content
Check image content and try again

"API error: 403"

Invalid API token
Insufficient permissions
Check your Bria AI account status

Poor edge quality

Bria AI automatically optimizes edges
Use --preserveAlpha for complex transparency
Ensure high-quality input images

Debug Mode

Enable detailed logging:

pm-media background:remove:bria \
  --src "input/*" \
  --dst "output/" \
  --debug \
  --verbose

API Rate Limits

Monitor your API usage in Bria dashboard
Use appropriate batch sizes
Consider asynchronous processing for large batches

Integration Examples

E-commerce Workflow

#!/bin/bash
# Professional product photography pipeline

INPUT_DIR="$1"
OUTPUT_DIR="$2"

# Remove backgrounds with content moderation
pm-media background:remove:bria \
  --src "$INPUT_DIR/*.jpg" \
  --dst "$OUTPUT_DIR/no-bg/" \
  --contentModeration \
  --preserveAlpha \
  --verbose

# Create thumbnails
pm-media resize \
  --src "$OUTPUT_DIR/no-bg/*.png" \
  --dst "$OUTPUT_DIR/thumbs/" \
  --width 300 \
  --height 300 \
  --fit contain \
  --background white

Safe Content Processing

#!/bin/bash
# User-generated content processing with safety

pm-media background:remove:bria \
  --src "user-uploads/*.jpg" \
  --dst "processed/" \
  --contentModeration \
  --preserveAlpha \
  --verbose

echo "Safe processing complete"

Enterprise Batch Processing

#!/bin/bash
# Enterprise-grade batch processing

for dir in */; do
  if [ -d "$dir" ]; then
    echo "Processing directory: $dir"
    pm-media background:remove:bria \
      --src "$dir*.jpg" \
      --dst "enterprise-processed/$dir" \
      --contentModeration \
      --preserveAlpha \
      --sync \
      --verbose
  fi
done

Advanced Usage

Environment Configuration

# .env file
BRIA_API_TOKEN=your_token_here
CONTENT_MODERATION=true
PRESERVE_ALPHA=true

# Use in scripts
pm-media background:remove:bria \
  --src "*.jpg" \
  --dst "output/" \
  --contentModeration \
  --preserveAlpha

Quality Control Pipeline

#!/bin/bash
# Multi-stage quality control

INPUT="$1"
BASE_NAME=$(basename "$INPUT" .jpg)

# Process with Bria AI
pm-media background:remove:bria \
  --src "$INPUT" \
  --dst "bria-processed/${BASE_NAME}_bria.png" \
  --contentModeration \
  --preserveAlpha \
  --verbose

Conditional Processing

#!/bin/bash
# Smart processing based on content type

for image in *.jpg; do
  echo "Processing $image with Bria AI..."
  
  pm-media background:remove:bria \
    --src "$image" \
    --dst "processed/" \
    --contentModeration \
    --preserveAlpha
done

TypeScript Definitions

interface BriaBackgroundRemoveOptions extends IOptions {
  apiKey?: string;
  sync?: boolean;
  contentModeration?: boolean;
  preserveAlpha?: boolean;
}

declare function removeBriaBackground(
  inputPath: string,
  outputPath: string,
  options: BriaBackgroundRemoveOptions
): Promise<void>;

declare function briaBackgroundRemove(
  options: BriaBackgroundRemoveOptions
): Promise<any>;

Security & Compliance

API Key Security

Store API keys in configuration files or environment variables
Never commit API keys to version control
Use environment-specific configurations
Monitor API usage in Bria dashboard

Content Safety

Enable content moderation for user-generated content
Review failed moderation results
Implement appropriate content policies
Use Bria's enterprise compliance features

Contributing

For bug reports, feature requests, or contributions, please visit the project repository.

References

License

This tool is part of the @polymech/media package. Please refer to the package license for usage terms.

14 KiB Raw Blame History