API v2 · Video

Video Face Blur

Detect and blur faces across video frames. Returns an async job ID.

POST/api/v2/videos/face-blur

Authentication

Send your API key as a bearer token on every request.

Header

Authorization: Bearer vba_your_api_key

Request Body

Send JSON with these fields. Required fields must be present unless marked optional.

Field	Type	Required	Description
video_url	string URL	Yes	Public or BGBlur-uploaded video URL to process.
duration_seconds	number	No	Duration used for credit estimation and processing bounds. Send this when known.
blur_strength	number	No	Blur amount from 0 to 1. Default is 0.7.
pixelated	boolean	No	Use pixelation instead of gaussian blur. Default false.
face_blur_mode	string	No	gaussian, pixelated, or another supported face blur mode. Defaults from pixelated flag.
emoji	string	No	Emoji overlay value when using emoji face mode. Default is sunglasses face.

⚠

Media must be publicly accessible. Pass a direct URL from a public storage bucket — e.g. AWS S3, Google Cloud Storage, Cloudinary, Cloudflare R2, Backblaze B2, Uploadcare, or any CDN URL. Private, signed, or localhost URLs will fail. Supported formats: MP4, MOV.

JSON

{
  "video_url": "https://example.com/interview.mp4",
  "duration_seconds": 60,
  "blur_strength": 0.7,
  "pixelated": false,
  "face_blur_mode": "gaussian",
  "emoji": "😎"
}

Response

Successful responses use JSON. Video feature endpoints return an async job_id rather than the final processed video immediately.

Field	Type	Required	Description
success	boolean	Yes	True when the job was accepted.
job_id	string	Yes	Use this with GET /api/v2/jobs/{job_id}.
status	string	Yes	Initial job status, usually queued.
feature	string	No	Feature name submitted for processing.
credits_used	number	Yes	Credits reserved or charged for the job.
remaining_credits	number	Yes	Credit balance after job creation.

JSON

{
  "success": true,
  "job_id": "job_abc123",
  "status": "queued",
  "feature": "face-blur",
  "credits_used": 12,
  "remaining_credits": 488
}

Example

curl

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,
  "pixelated": false,
  "face_blur_mode": "gaussian",
  "emoji": "😎"
}'

Tips

Video endpoints are async. Store job_id and poll GET /api/v2/jobs/{job_id}.
Send duration_seconds when you know it so credit estimation is accurate.
Use the upload video endpoint for local files before calling a video feature endpoint.

Back to API Reference