razbakov/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:

| Parameter | Required | Description | |-----------|----------|-------------| | generation_type | Yes | "video" or "image" | | source_uri | Yes | Beeble URI from upload, or a public URL | | alpha_mode | Yes | How to separate subject from background (see below) | | max_resolution | No | 720 or 1080 (default varies) | | prompt | No | Text describing desired output look | | reference_image_uri | No | Beeble URI or public URL of a reference image for style guidance | | alpha_uri | No | Required for custom alpha mode | | callback_url | No | Webhook URL for completion notification |

Alpha modes:

| Mode | When to use | |------|-------------| | auto | Default. AI detects and preserves the foreground subject automatically. Best for most cases. | | fill | Keep everything in the original scene, just transform lighting/style. No background replacement. | | select | Provide a first-frame mask image; AI propagates it across the video. For precise subject selection. | | custom | Provide a full frame-by-frame mask video. Maximum control. |

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 | Description | |--------|-------------| | render | The final transformed video — this is what you deliver | | source | The original re-encoded by Beeble (for comparison) | | alpha | The mask showing what was kept vs replaced |

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

| Error | Meaning | Fix | |-------|---------|-----| | VIDEO_TOO_MANY_FRAMES | Over 240 frames | Trim or split the video | | SOURCE_TOO_LARGE | File too big | Compress or reduce resolution before upload | | RATE_LIMIT_EXCEEDED | Over 5 requests/min | Wait and retry with backoff | | CONCURRENT_LIMIT_EXCEEDED | Over 10 in-flight jobs | Wait for running jobs to finish | | INSUFFICIENT_BALANCE | Credits depleted | Top up at developer.beeble.ai |

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