Developer Documentation
API Reference
REST API documentation for integrating BGBlur video and image processing into your application. Covers authentication, endpoints, limits, requests, and responses.
Getting Started
Everything you need to start integrating BGBlur API into your applications.
Authentication
All API requests use bearer token authentication. API keys can be generated from the developer dashboard and are stored hashed in the database. Keys are shown in plain text only once at creation time.
Authorization: Bearer vba_your_api_keyBase URL
All API endpoints are prefixed with the base URL. Use HTTPS for all requests to ensure secure transmission of your API keys and data.
https://www.bgblur.com/api/v2Video Processing Endpoints
Process videos with various anonymization and enhancement capabilities. All endpoints support both synchronous and asynchronous processing with job status monitoring.
POST /api/v2/videos/background-blur
POST /api/v2/videos/face-blur
POST /api/v2/videos/license-plate-blur
POST /api/v2/videos/object-removal
POST /api/v2/videos/blur-anything
POST /api/v2/videos/face-anonymization
GET /api/v2/jobs/{job_id}Image Processing Endpoints
Process images with background removal, face detection, and privacy features. Supports various image formats including JPEG, PNG, and WEBP.
POST /api/v2/images/blur-background
POST /api/v2/images/remove-background
POST /api/v2/images/portrait-enhance
POST /api/v2/images/face-blur
POST /api/v2/images/license-plate-blur
POST /api/v2/images/blur-anything
POST /api/v2/detect/nsfwFeature Workflow
For local files, first request an upload URL, upload the media to S3, then call the feature endpoint with the returned image_url or video_url. Video APIs return a job_id; poll the job endpoint for the final result.
1. POST /api/v2/uploads/image or /api/v2/uploads/video
2. PUT the local file to upload_url
3. POST the returned image_url or video_url to a feature endpoint
4. For video jobs, GET /api/v2/jobs/{job_id}Advanced Topics
Rate limits, error handling, and best practices for production deployments.
Rate Limits
API rate limits vary by subscription tier. Free tier: 100 requests/day, Pro: 1,000 requests/day, Enterprise: Custom limits. Rate limit headers are included in all responses.
X-RateLimit-Limit: Total requests allowed per window
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when the limit resetsError Handling
The API uses standard HTTP status codes. Error responses include a JSON body with error details and suggested actions.
{
"error": {
"code": "unauthorized",
"message": "Invalid API key",
"status": 401
}
}Request Format
All POST requests accept either JSON or multipart/form-data. Use multipart for file uploads. Include Content-Type header matching your request format.
curl -X POST https://www.bgblur.com/api/v2/videos/face-blur \
-H "Authorization: Bearer vba_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/interview.mp4",
"duration_seconds": 60,
"blur_strength": 0.7
}'Response Format
All responses are JSON formatted. Successful requests return 200 OK with result data. Async jobs return 202 Accepted with a job ID for status polling.
{
"success": true,
"job_id": "job_abc123",
"status": "queued",
"credits_used": 12,
"remaining_credits": 488
}API v2 Endpoints
Each endpoint page includes the method, request body, response body, example cURL, and implementation notes.
Image
/api/v2/images/blur-backgroundBlur the background of an image while preserving the foreground subject.
/api/v2/images/remove-backgroundRemove an image background. Use output_transparent for alpha output or background_color for a flat fill.
/api/v2/images/portrait-enhanceEnhance portrait images with face enhancement and depth effect options.
/api/v2/images/face-blurDetect faces in an image and blur or pixelate them.
/api/v2/images/license-plate-blurDetect vehicle license plates in an image and blur or pixelate them.
/api/v2/images/blur-anythingBlur objects matching a text prompt in an image.
Video
/api/v2/videos/background-blurBlur the background of a video. Returns an async job ID.
/api/v2/videos/face-blurDetect and blur faces across video frames. Returns an async job ID.
/api/v2/videos/license-plate-blurDetect and blur license plates across video frames. Returns an async job ID.
/api/v2/videos/object-removalRemove a named object from a video. object_text is required and must be 40 characters or less.
/api/v2/videos/blur-anythingBlur objects matching a text prompt across a video. Returns an async job ID.
/api/v2/videos/face-anonymizationAnonymize faces in a video using BGBlur face anonymization workflow. Returns an async job ID.
Account
Additional Resources
Explore more integration options and developer tools.