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

# Check job processing status

> Check the current status of a video processing job and get download URLs when complete.




## OpenAPI

````yaml https://videobgremover.com/openapi.yaml get /v1/jobs/{id}/status
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}/status:
    get:
      tags:
        - Jobs
      summary: Check job processing status
      description: >
        Check the current status of a video processing job and get download URLs
        when complete.
      operationId: getJobStatus
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Job ID to check status for
      responses:
        '200':
          description: Job status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
              examples:
                job_created:
                  summary: Job just created
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    status: created
                    filename: my-video.mp4
                    created_at: '2023-12-01T10:00:00Z'
                    length_seconds: null
                    thumbnail_url: null
                    transparent_thumbnail_url: null
                    processed_video_url: null
                    processed_mask_url: null
                    message: null
                    background: null
                    output_format: null
                    export_id: null
                job_processing:
                  summary: Job currently processing
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    status: processing
                    filename: my-video.mp4
                    created_at: '2023-12-01T10:00:00Z'
                    length_seconds: 30.5
                    thumbnail_url: >-
                      https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_thumb.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600
                    transparent_thumbnail_url: null
                    processed_video_url: null
                    processed_mask_url: null
                    message: Processing video with red background
                    background:
                      type: color
                      color: '#FF0000'
                    output_format: mp4
                    export_id: exp_red_bg_123
                job_completed_default:
                  summary: Job completed with default green screen
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    status: completed
                    filename: my-video.mp4
                    created_at: '2023-12-01T10:00:00Z'
                    length_seconds: 30.5
                    thumbnail_url: >-
                      https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_thumb.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600
                    transparent_thumbnail_url: >-
                      https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_transparent_thumb.png?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600
                    processed_video_url: >-
                      https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000.mp4?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600
                    processed_mask_url: >-
                      https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_mask.mp4?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600
                    message: Processing completed successfully
                    background: null
                    output_format: null
                    export_id: null
                job_completed_transparent:
                  summary: Job completed with transparent WebM
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    status: completed
                    filename: my-video.mp4
                    created_at: '2023-12-01T10:00:00Z'
                    length_seconds: 30.5
                    thumbnail_url: >-
                      https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_thumb.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600
                    transparent_thumbnail_url: >-
                      https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_transparent_thumb.png?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600
                    processed_video_url: >-
                      https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000.webm?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600
                    processed_mask_url: >-
                      https://storage.googleapis.com/videobg-processed/550e8400-e29b-41d4-a716-446655440000_mask.mp4?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=3600
                    message: Processing completed successfully
                    background:
                      type: transparent
                      transparent_format: webm_vp9
                    output_format: webm
                    export_id: exp_webm_vp9_456
                job_failed:
                  summary: Job failed with error
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    status: failed
                    filename: my-video.mp4
                    created_at: '2023-12-01T10:00:00Z'
                    length_seconds: null
                    thumbnail_url: null
                    transparent_thumbnail_url: null
                    processed_video_url: null
                    processed_mask_url: null
                    message: 'Video too large: 1250.5MB'
                    background:
                      type: color
                      color: '#FF0000'
                    output_format: mp4
                    export_id: exp_red_bg_123
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    JobStatus:
      type: object
      required:
        - id
        - status
        - filename
        - created_at
      properties:
        id:
          type: string
          format: uuid
          description: Job identifier
        export_id:
          type: string
          format: uuid
          description: Export identifier (only present for API calls with background)
          nullable: true
        status:
          type: string
          enum:
            - created
            - uploaded
            - processing
            - completed
            - failed
          description: Current job status
        filename:
          type: string
          description: Original filename
        created_at:
          type: string
          format: date-time
          description: Job creation time
        length_seconds:
          type: number
          description: Video duration in seconds
          nullable: true
        thumbnail_url:
          type: string
          format: uri
          description: Signed URL for video thumbnail
          nullable: true
        transparent_thumbnail_url:
          type: string
          format: uri
          description: Signed URL for transparent thumbnail
          nullable: true
        processed_video_url:
          type: string
          format: uri
          description: Signed URL for processed video (when completed)
          nullable: true
        processed_mask_url:
          type: string
          format: uri
          description: Signed URL for video mask (when completed)
          nullable: true
        message:
          type: string
          description: Status message
          nullable: true
        background:
          allOf:
            - $ref: '#/components/schemas/BackgroundOptions'
          description: Background options (only present for API calls with background)
          nullable: true
        output_format:
          type: string
          description: Output file format (only present for API calls with background)
          nullable: true
    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:
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIError'
          example:
            error: Invalid API key
    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

````