Skip to main content
POST
/
v1
/
project
/
create
/
remove-background
Remove Background
curl --request POST \
  --url https://api.hooked.so/v1/project/create/remove-background \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "media": "video_01"
}
'
{
  "success": true,
  "data": {
    "videoId": "vid_rbg_abc123xyz",
    "projectId": "proj_rbg_abc123xyz",
    "status": "STARTED"
  },
  "message": "Remove Background successfully created"
}
Try it out! Use the API playground on the right to test the Remove Background endpoint directly.

​
Overview

Remove Background automatically removes the background from your videos, creating a transparent background effect. Perfect for:
  • Product videos
  • Talking head videos
  • Social media content
  • Professional presentations
  • Green screen replacements
The API processes your video and returns a clean version with the background removed, ready to overlay on any content.

​
Endpoint

POST /v1/project/create/remove-background

​
Required Fields

​
media
string
required
Media ID of the video to process. The video must already be uploaded to your account.

​
Request Example

const response = await fetch('https://api.hooked.so/v1/project/create/remove-background', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HOOKED_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    media: 'video_01',
    webhook: 'https://yoursite.com/webhook',
    metadata: {
      campaignId: 'summer-launch-2024',
      variant: 'A',
      createdBy: 'marketing-automation'
    }
  })
});

const data = await response.json();
console.log('Video ID:', data.data.videoId);
console.log('Project ID:', data.data.projectId);

​
Response

{
  "success": true,
  "data": {
    "videoId": "vid_rbg_abc123xyz",
    "projectId": "proj_rbg_abc123xyz",
    "status": "STARTED"
  },
  "message": "Remove Background successfully created"
}

​
Webhook Notification

When your video is ready, we’ll POST to your webhook URL (if configured):
Webhook Payload
{
  "status": "COMPLETED",
  "data": {
    "videoId": "vid_rbg_abc123xyz",
    "status": "COMPLETED",
    "url": "https://cdn.hooked.so/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.hooked.so/shared/abc123xyz.mp4",
    "metadata": {
      "projectId": "proj_rbg_abc123xyz"
    }
  },
  "message": "Video completed"
}

​
Best Practices

Video Quality

Use high-quality source videos for best background removal results.

Good Lighting

Videos with good lighting and clear subject separation work best.

Avoid Motion Blur

Sharper videos work better for background removal.

Clear Separation

Ensure good contrast between subject and background.

​
Error Handling

ErrorDescriptionSolution
media: Video is requiredMissing media IDProvide a media ID string
media: Video not foundMedia ID doesn’t exist in your accountEnsure the media ID is correct and belongs to your team
media: Media must be a video fileMedia is not a video typeProvide a video media ID, not an image media ID
Not enough creditsInsufficient creditsTop up your account credits

​
Next Steps

List Videos

View all your created videos

Video Details

Check your video processing status

Webhooks Guide

Learn how to handle webhook notifications

Talking Avatar

Create talking avatar videos with AI avatars

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
media
string
required

Media ID of the video to process. The video must already be uploaded to your account.

Response

Remove Background created successfully

​
success
boolean
​
data
object
​
message
string