Overview - Beeble API Documentation

SwitchX

SwitchX is our flagship video-to-video model that lets you switch anything in a scene while perfectly keeping what matters. Unlike standard video generators, SwitchX uses the original pixels to drive the final output. By providing a Source Video, defining an Alpha Mask (to tell the AI what to keep), and providing a Reference Image (to dictate the new look), SwitchX seamlessly generates new elements and relights your original subject to match perfectly.

How It Works

  1. Upload Assets
    Use the Uploads API to securely upload your starting materials:

    • source_video
      required
      The original video you want to transform.
    • reference_image
      Your visual target. While not strictly required, we always strongly recommend providing one to achieve the highest quality and most accurate results.
    • alpha_mask
      A custom mask file. Whether you need to upload this depends entirely on which alpha_mode you choose in the next step.

  2. Start Generation
    Call the Generate endpoint to define your compositing job. Link your uploaded assets and configure the following parameters:

    • alpha_mode (required)
      Choose how SwitchX handles the scene:

      Mode Description
      Auto The AI automatically detects and masks the foreground subject.
      Select Provide an alpha mask for a single reference frame (the first frame by default, or any frame via alpha_keyframe_index), and our AI will propagate it across the entire video.
      Fill Keeps everything in the original scene exactly as it is (no masking applied).
      Custom Provide a full custom video mask for exact frame-by-frame control.

    • prompt (Recommended)
      A text description of the desired output video to further guide the AI on the specific style, lighting, or background details you want to generate.

  3. Poll or Webhook
    Video generation takes a little time. Check your job’s progress by polling our status endpoint, or set up a webhook callback to get notified the second it finishes.

  4. Download
    Retrieve the URL from the completed job and download your seamlessly composited, fully relighted final video!