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

# Start processing a video job

> Start background removal processing for an uploaded video.

**Important**: Credits are checked and deducted when you call this endpoint,
not when creating the job. Processing costs 1 credit per second of video.




## OpenAPI

````yaml https://videobgremover.com/openapi.yaml post /v1/jobs/{id}/start
openapi: 3.0.3
info:
  title: VideoBGRemover API
  version: 1.6.0
  description: >
    Remove backgrounds from videos using AI-powered processing. 


    The VideoBGRemover API allows you to:

    - Upload videos or provide URLs for processing

    - Remove backgrounds with customizable options

    - Generate transparent videos in multiple formats

    - Compose videos on custom backgrounds (server-side)

    - Track processing status and manage credits


    ## Authentication

    All API requests require authentication using an API key in the `X-Api-Key`
    header.


    ## Credits System

    Video processing costs 1 credit per second of video duration.
  contact:
    name: VideoBGRemover API Support
    url: https://videobgremover.com/contact
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.videobgremover.com
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Jobs
    description: Video processing job management
  - name: Credits
    description: Credit balance and usage
  - name: API
    description: API metadata and documentation
  - name: Webhooks
    description: Webhook delivery and history
paths:
  /v1/jobs/{id}/start:
    post:
      tags:
        - Jobs
      summary: Start processing a video job
      description: >
        Start background removal processing for an uploaded video.


        **Important**: Credits are checked and deducted when you call this
        endpoint,

        not when creating the job. Processing costs 1 credit per second of
        video.
      operationId: startJob
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Job ID returned from job creation
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartJobRequest'
            examples:
              default_green:
                summary: Default (Green Screen)
                value:
                  format: mp4
              color_background:
                summary: Color Background
                value:
                  background:
                    type: color
                    color: '#FF0000'
              transparent_webm:
                summary: Transparent WebM
                value:
                  background:
                    type: transparent
                    transparent_format: webm_vp9
              lottie_export:
                summary: Lottie JSON Export
                value:
                  background:
                    type: transparent
                    transparent_format: lottie
              gif_export:
                summary: Transparent GIF
                value:
                  background:
                    type: transparent
                    transparent_format: gif
              webp_export:
                summary: Transparent WebP
                value:
                  background:
                    type: transparent
                    transparent_format: webp
              pro_bundle:
                summary: Pro Bundle (Professional Workflow)
                value:
                  background:
                    type: transparent
                    transparent_format: pro_bundle
              composition_template:
                summary: Video Composition (Template)
                value:
                  background:
                    type: composition
                    composition:
                      template: ai_ugc_ad
                      background_url: https://example.com/background.mp4
                      background_type: video
                      background_audio_enabled: true
                      background_audio_volume: 0.8
              composition_custom:
                summary: Video Composition (Custom)
                value:
                  background:
                    type: composition
                    composition:
                      background_url: https://example.com/background.jpg
                      background_type: image
                      position: center
                      size_mode: canvas_percent
                      size_percent: 50
                      opacity: 1
              text_prompt_pro:
                summary: Text Prompt (Pro Model)
                value:
                  model: videobgremover-pro
                  prompt:
                    mode: text
                    text: person wearing red jacket
                  background:
                    type: transparent
                    transparent_format: webm_vp9
              auto_prompt_explicit:
                summary: Auto Mode (Explicit)
                value:
                  model: videobgremover-original
                  prompt:
                    mode: auto
                  background:
                    type: transparent
                    transparent_format: stacked_video
              auto_prompt_omitted:
                summary: Auto Mode (Omitted - Recommended)
                value:
                  model: videobgremover-light
                  background:
                    type: color
                    color: '#00FF00'
      responses:
        '200':
          description: Processing started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStarted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    StartJobRequest:
      type: object
      properties:
        format:
          type: string
          enum:
            - mp4
          default: mp4
          description: Output video format
        model:
          type: string
          enum:
            - videobgremover-original
            - videobgremover-light
            - videobgremover-pro
            - videobgremover-human
          default: videobgremover-original
          description: >
            AI model for background removal:

            - **videobgremover-original**: High-quality background removal. Best
            for detailed segmentation and complex scenes.

            - **videobgremover-light**: Fast and efficient background removal.
            Optimized for speed while maintaining good quality.

            - **videobgremover-pro**: Advanced background removal for complex
            objects. Enables text prompting for precise segmentation.

            - **videobgremover-human**: Fast matting algorithm optimized for
            portraits and facing people.
        prompt:
          $ref: '#/components/schemas/Prompt'
        background:
          $ref: '#/components/schemas/BackgroundOptions'
        webhook_url:
          type: string
          format: uri
          description: >-
            Webhook URL to notify when job completes or fails. **Must use HTTPS
            in production.**
    JobStarted:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Job identifier
        export_id:
          type: string
          format: uuid
          description: Export identifier (when background is specified)
        status:
          type: string
          enum:
            - processing
          description: Processing status
        created_at:
          type: string
          format: date-time
          description: Processing start time
        creditsUsed:
          type: number
          description: Credits deducted for this job
        video_length_seconds:
          type: number
          description: Video duration in seconds
        background:
          $ref: '#/components/schemas/BackgroundOptions'
    Prompt:
      type: object
      properties:
        mode:
          type: string
          enum:
            - auto
            - text
          default: auto
          description: >
            Prompting mode:

            - **auto**: Automatic background detection (default, works with all
            models)

            - **text**: Text-based prompt for specific subjects (only with
            videobgremover-pro)
        text:
          type: string
          description: >-
            Natural language description of the subject to keep in the video
            (required when mode is "text"). Examples: "person", "dog", "car with
            red paint"
      required:
        - mode
    BackgroundOptions:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - color
            - transparent
            - composition
          description: Background type
        color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          description: Hex color code (required when type is "color")
          example: '#FF0000'
        transparent_format:
          type: string
          enum:
            - webm_vp9
            - mov_prores
            - png_sequence
            - pro_bundle
            - stacked_video
            - stacked_video_mask_inverted
            - mask_video
            - mask_video_inverted
            - gif
            - webp
            - lottie
          description: Transparent output format (when type is "transparent")
        composition:
          $ref: '#/components/schemas/CompositionOptions'
          description: Composition parameters (required when type is "composition")
    APIError:
      type: object
      properties:
        error:
          type: string
          description: Error message
        details:
          type: string
          description: Additional error details
    CompositionOptions:
      type: object
      oneOf:
        - $ref: '#/components/schemas/CompositionTemplate'
        - $ref: '#/components/schemas/CompositionCustom'
    CompositionTemplate:
      type: object
      required:
        - template
      properties:
        template:
          type: string
          enum:
            - ai_ugc_ad
            - centered
            - picture_in_picture
            - fullscreen
          description: |
            Pre-configured composition template:
            - **ai_ugc_ad**: 9:16 centered layout optimized for social media ads
            - **centered**: Centered foreground with contain sizing
            - **picture_in_picture**: Small foreground in bottom-right corner
            - **fullscreen**: Foreground covers entire canvas
          example: ai_ugc_ad
        background_url:
          type: string
          format: uri
          description: URL to background image or video (required)
          example: https://example.com/background.mp4
        background_type:
          type: string
          enum:
            - image
            - video
          description: Type of background (auto-detected from URL if not specified)
        background_audio_enabled:
          type: boolean
          default: false
          description: Enable background audio (only for video backgrounds)
        background_audio_volume:
          type: number
          minimum: 0
          maximum: 1
          default: 1
          description: Background audio volume (0.0 to 1.0)
        export_format:
          type: string
          enum:
            - h264
          default: h264
          description: Export video codec
        export_crf:
          type: integer
          minimum: 0
          maximum: 51
          default: 23
          description: Export quality (lower = better quality, 0-51)
    CompositionCustom:
      type: object
      required:
        - background_url
        - background_type
      properties:
        background_url:
          type: string
          format: uri
          description: URL to background image or video
          example: https://example.com/background.mp4
        background_type:
          type: string
          enum:
            - color
            - image
            - video
          description: Type of background
        background_color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          description: Hex color (when background_type is "color")
        background_audio_enabled:
          type: boolean
          default: false
          description: Enable background audio (video backgrounds only)
        background_audio_volume:
          type: number
          minimum: 0
          maximum: 1
          default: 1
          description: Background audio volume
        position:
          type: string
          enum:
            - center
            - top_left
            - top_center
            - top_right
            - center_left
            - center_right
            - bottom_left
            - bottom_center
            - bottom_right
          default: center
          description: Anchor position for foreground placement
        offset_x:
          type: integer
          default: 0
          description: Horizontal offset in pixels from anchor
        offset_y:
          type: integer
          default: 0
          description: Vertical offset in pixels from anchor
        size_mode:
          type: string
          enum:
            - contain
            - cover
            - canvas_percent
            - px
            - scale
            - fit_width
            - fit_height
          default: contain
          description: |
            Foreground sizing mode:
            - **contain**: Fit within canvas, preserve aspect ratio
            - **cover**: Fill canvas, preserve aspect ratio (may crop)
            - **canvas_percent**: Size as percentage of canvas
            - **px**: Exact pixel dimensions
            - **scale**: Scale relative to original size
            - **fit_width**: Fit to canvas width
            - **fit_height**: Fit to canvas height
        size_percent:
          type: number
          description: Size percentage (when size_mode is "canvas_percent")
        size_width:
          type: number
          description: Width value (depends on size_mode)
        size_height:
          type: number
          description: Height value (depends on size_mode)
        opacity:
          type: number
          minimum: 0
          maximum: 1
          default: 1
          description: Foreground opacity (0.0 to 1.0)
        export_format:
          type: string
          enum:
            - h264
          default: h264
          description: Export video codec
        export_crf:
          type: integer
          minimum: 0
          maximum: 51
          default: 23
          description: Export quality (lower = better, 0-51)
  responses:
    BadRequest:
      description: Bad request - Invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
          examples:
            invalid_background:
              summary: Invalid background color
              value:
                error: >-
                  Invalid background color format. Must be hex color like
                  #FF0000
            missing_params:
              summary: Missing required parameters
              value:
                error: Must provide either (filename + content_type) OR video_url
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
          example:
            error: Invalid API key
    PaymentRequired:
      description: Payment Required - Insufficient credits
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
          example:
            error: Not enough credits available
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
          example:
            error: Job not found or does not belong to user
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
          example:
            error: Internal server error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key with format `vbr_` followed by 32 characters

````