Video Relight

Video Relight with Beeble SwitchX

Transform lighting, backgrounds, and environments in video clips and images while preserving the original subject. Powered by the Beeble SwitchX API.

When to use

• Relight dark venue footage (e.g. dance festivals, meetups, talks)
• Replace messy backgrounds with clean/branded ones
• Give raw recordings a cinematic or studio look
• Process short clips for social media, thumbnails, or promotional content

Prerequisites

• BEEBLE_API_KEY environment variable set (get one at developer.beeble.ai)
• ffmpeg and ffprobe installed (for video inspection and trimming)
• curl available

Constraints

• Max 240 frames per job (~8s at 30fps, ~10s at 24fps). Longer videos must be split into chunks.
• Processing time: ~6 minutes for an 8-second clip (varies by resolution and queue).
• Cost: $0.10 per generation (pay-as-you-go).
• Output URLs expire after 72 hours. Re-poll the job status endpoint to get fresh URLs.

Workflow

1. Inspect the source video

Before anything, check the video specs to know what you're working with:

ffprobe -v quiet -print_format json -show_streams INPUT_FILE | python3 -c "
import json,sys
d=json.load(sys.stdin)
for s in d['streams']:
    if s['codec_type']=='video':
        fps = s.get('r_frame_rate','?')
        dur = s.get('duration','?')
        w, h = s.get('width','?'), s.get('height','?')
        print(f'Resolution: {w}x{h}, FPS: {fps}, Duration: {dur}s')
"

Calculate total frames: duration * fps. If over 240 frames, you need to trim or split.

2. Trim if needed

SwitchX accepts max 240 frames. Calculate the safe duration: 240 / fps seconds. Then trim:

ffmpeg -y -i INPUT_FILE -t SAFE_DURATION -c copy /tmp/switchx-clip.mp4

For longer videos, split into sequential chunks and process each separately. Reassemble with ffmpeg concat after all jobs complete.

3. Upload to Beeble

Create a presigned upload URL and upload the file:

# Get upload URL
UPLOAD_RESP=$(curl -s -X POST https://api.beeble.ai/v1/uploads \
  -H "x-api-key: $BEEBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "clip.mp4"}')

UPLOAD_URL=$(echo "$UPLOAD_RESP" | python3 -c "import json,sys; print(json.load(sys.stdin)['upload_url'])")
BEEBLE_URI=$(echo "$UPLOAD_RESP" | python3 -c "import json,sys; print(json.load(sys.stdin)['beeble_uri'])")

# Upload file
curl -s -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @/tmp/switchx-clip.mp4

For images, use the appropriate content type (image/png, image/jpeg).

4. Start generation

curl -s -X POST https://api.beeble.ai/v1/switchx/generations \
  -H "x-api-key: $BEEBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"generation_type\": \"video\",
    \"source_uri\": \"$BEEBLE_URI\",
    \"alpha_mode\": \"auto\",
    \"max_resolution\": 1080,
    \"prompt\": \"YOUR PROMPT HERE\"
  }"

Parameters:

Alpha modes:

5. Poll for completion

JOB_ID="the id from step 4"
while true; do
  RESULT=$(curl -s "https://api.beeble.ai/v1/switchx/generations/$JOB_ID" \
    -H "x-api-key: $BEEBLE_API_KEY")
  STATUS=$(echo "$RESULT" | python3 -c "import json,sys; print(json.load(sys.stdin)['status'])")
  PROGRESS=$(echo "$RESULT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('progress',0))")
  echo "Status: $STATUS, Progress: $PROGRESS%"
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    echo "$RESULT" | python3 -m json.tool
    break
  fi
  sleep 10
done

6. Download outputs

A completed job returns three output URLs:

OUTPUT_DIR="/path/to/output"
mkdir -p "$OUTPUT_DIR"

RENDER_URL=$(echo "$RESULT" | python3 -c "import json,sys; print(json.load(sys.stdin)['output']['render'])")
SOURCE_URL=$(echo "$RESULT" | python3 -c "import json,sys; print(json.load(sys.stdin)['output']['source'])")
ALPHA_URL=$(echo "$RESULT" | python3 -c "import json,sys; print(json.load(sys.stdin)['output']['alpha'])")

curl -s -o "$OUTPUT_DIR/render.mp4" "$RENDER_URL"
curl -s -o "$OUTPUT_DIR/source.mp4" "$SOURCE_URL"
curl -s -o "$OUTPUT_DIR/alpha.mp4" "$ALPHA_URL"

Prompt tips

The prompt describes how you want the output to look. Good prompts are specific about lighting and environment:

• Studio look: "Professional podcast studio with warm soft lighting, clean modern background with subtle neon accent lights, cinematic look"
• Outdoor daylight: "Bright natural daylight, outdoor park setting, soft shadows, golden hour warmth"
• Stage performance: "Concert stage with dramatic colored spotlights, haze, dark background, high contrast"
• Clean corporate: "Modern office with neutral lighting, white walls, minimalist background, even soft illumination"

Using a reference_image_uri alongside the prompt gives more precise control — upload a photo of the exact look you want.

Processing longer videos

For videos over 240 frames, split into chunks, process each, then reassemble:

# Split into 8-second chunks (at 30fps = 240 frames)
ffmpeg -i long_video.mp4 -c copy -segment_time 8 -f segment -reset_timestamps 1 /tmp/chunk_%03d.mp4

# Process each chunk through steps 3-6...

# Reassemble (create file list first)
for f in /tmp/output_chunk_*.mp4; do echo "file '$f'"; done > /tmp/chunks.txt
ffmpeg -f concat -safe 0 -i /tmp/chunks.txt -c copy final_output.mp4

Note: chunk boundaries may have visible seams since each is processed independently. For best results, overlap chunks slightly and crossfade.

Error handling

API reference

• Base URL: https://api.beeble.ai/v1
• Auth: x-api-key header
• Docs: https://developer.beeble.ai/docs
• Status page: https://status.beeble.ai
• Rate limits: 5 RPM write, 5 RPM read, 10 concurrent jobs