> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Remove Background

> Remove backgrounds from videos

<Note>
  **Try it out!** Use the API playground on the right to test the Remove Background endpoint directly.
</Note>

## 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

<Info>
  The API processes your video and returns a clean version with the background removed, ready to overlay on any content.
</Info>

***

## Endpoint

```
POST /v1/project/create/remove-background
```

***

## Required Fields

<ParamField body="media" type="string" required>
  Media ID of the video to process. The video must already be uploaded to your account.
</ParamField>

***

## Request Example

```javascript theme={null}
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

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "data": {
      "videoId": "vid_rbg_abc123xyz",
      "projectId": "proj_rbg_abc123xyz",
      "status": "STARTED"
    },
    "message": "Remove Background successfully created"
  }
  ```

  ```json Error Response - Validation Error theme={null}
  {
    "success": false,
    "message": "media: Video is required"
  }
  ```

  ```json Error Response - Invalid Video Type theme={null}
  {
    "success": false,
    "message": "media: Media must be a video file"
  }
  ```
</ResponseExample>

***

## Webhook Notification

When your video is ready, we'll POST to your webhook URL (if configured):

```json Webhook Payload theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Video Quality" icon="video">
    Use high-quality source videos for best background removal results.
  </Card>

  <Card title="Good Lighting" icon="lightbulb">
    Videos with good lighting and clear subject separation work best.
  </Card>

  <Card title="Avoid Motion Blur" icon="circle-stop">
    Sharper videos work better for background removal.
  </Card>

  <Card title="Clear Separation" icon="object-ungroup">
    Ensure good contrast between subject and background.
  </Card>
</CardGroup>

***

## Error Handling

| Error                               | Description                            | Solution                                                |
| ----------------------------------- | -------------------------------------- | ------------------------------------------------------- |
| `media: Video is required`          | Missing media ID                       | Provide a media ID string                               |
| `media: Video not found`            | Media ID doesn't exist in your account | Ensure the media ID is correct and belongs to your team |
| `media: Media must be a video file` | Media is not a video type              | Provide a video media ID, not an image media ID         |
| `Not enough credits`                | Insufficient credits                   | Top up your account credits                             |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="List Videos" icon="list" href="/api-reference/video/list">
    View all your created videos
  </Card>

  <Card title="Video Details" icon="video" href="/api-reference/video/details">
    Check your video processing status
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/guides/webhooks">
    Learn how to handle webhook notifications
  </Card>

  <Card title="Talking Avatar" icon="user" href="/api-reference/video/talking-avatar">
    Create talking avatar videos with AI avatars
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /v1/project/create/remove-background
openapi: 3.0.0
info:
  title: Hooked API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.hooked.so
security:
  - ApiKeyAuth: []
paths:
  /v1/project/create/remove-background:
    post:
      tags:
        - Videos
      summary: Remove Background
      description: Remove backgrounds from videos and add captions
      operationId: removeBackground
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - media
              properties:
                media:
                  type: string
                  description: >-
                    Media ID of the video to process. The video must already be
                    uploaded to your account.
            example:
              media: video_01
      responses:
        '200':
          description: Remove Background created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      videoId:
                        type: string
                      projectId:
                        type: string
                      status:
                        type: string
                  message:
                    type: string
              example:
                success: true
                data:
                  videoId: vid_rbg_abc123xyz
                  projectId: proj_rbg_abc123xyz
                  status: STARTED
                message: Remove Background successfully created
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              example:
                success: false
                message: 'media: Video is required'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              example:
                success: false
                message: Invalid API key
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````