Skip to main content

​
Prerequisites

To use the Beeble API, you need an API key.
  1. Go to Developer Page
  2. Sign up and accept the terms if you don’t have an account
  3. Click Create Key
See Authentication for details on obtaining and using your API key.

​
Try It — One Command

Run this single command to generate a video using our sample assets. Replace YOUR_API_KEY with your key. Here’s what you’ll be working with:

Source Video

Alpha Video

Reference Image

Reference image

Output

curl -X POST https://api.beeble.ai/v1/switchx/generations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generation_type": "video",
    "source_uri": "https://cdn.beeble.ai/public/developer-api/source.mp4",
    "reference_image_uri": "https://cdn.beeble.ai/public/developer-api/reference.png",
    "alpha_uri": "https://cdn.beeble.ai/public/developer-api/alpha.mp4",
    "alpha_mode": "custom",
    "max_resolution": 720,
    "prompt": "Video depicts a young woman with long red hair and freckles, smiling and gently looking to her right, as she walks through the sun-dappled courtyard of a traditional Korean palace."
  }'
Response (201): 
{
  "id": "YOUR_GENERATION_ID...",
  "status": "in_queue",
  "progress": 0,
  "generation_type": "video",
  "alpha_mode": "custom",
  "output": null,
  "error": null,
  "created_at": "2026-02-23T10:00:00Z",
  "modified_at": "2026-02-23T10:00:00Z",
  "completed_at": null
}

​
Check Status & Download

Poll the job status until it completes, then download the result. 
# Check status (repeat until "completed")
# Replace YOUR_GENERATION_ID with the "id" from the response above
curl https://api.beeble.ai/v1/switchx/generations/YOUR_GENERATION_ID \
  -H "x-api-key: YOUR_API_KEY"

# Download the result
# Replace with the "render" URL from the completed response
curl -o output.mp4 "RENDER_URL_FROM_OUTPUT"
Response (completed): 
{
  "id": "YOUR_GENERATION_ID",
  "status": "completed",
  "progress": 100,
  "generation_type": "video",
  "alpha_mode": "custom",
  "output": {
    "render": "https://cdn.beeble.ai/.../output.mp4",
    "source": "https://cdn.beeble.ai/.../source.mp4",
    "alpha": "https://cdn.beeble.ai/.../alpha.mp4"
  },
  "created_at": "2026-02-23T10:00:00Z",
  "modified_at": "2026-02-23T10:05:00Z",
  "completed_at": "2026-02-23T10:05:00Z"
}
Output URLs expire after 72 hours. You can always re-fetch fresh URLs by calling the status endpoint again.

​
Complete Script

A single copy-paste script that creates a generation, polls until complete, and downloads the result. 
"""
Beeble SwitchX API — Complete Example
Install: pip install requests
Usage:   python beeble_quickstart.py
"""
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.beeble.ai/v1"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# 1. Start generation using sample assets
print("Starting generation...")
response = requests.post(
    f"{BASE_URL}/switchx/generations",
    headers=HEADERS,
    json={
        "generation_type": "video",
        "source_uri": "https://cdn.beeble.ai/public/developer-api/source.mp4",
        "reference_image_uri": "https://cdn.beeble.ai/public/developer-api/reference.png",
        "alpha_uri": "https://cdn.beeble.ai/public/developer-api/alpha.mp4",
        "alpha_mode": "custom",
        "max_resolution": 720,
        "prompt": "Video depicts a young woman with long red hair and freckles, "
                  "smiling and gently looking to her right, as she walks through "
                  "the sun-dappled courtyard of a traditional Korean palace.",
    },
)
response.raise_for_status()
job = response.json()
job_id = job["id"]
print(f"Job created: {job_id} (status: {job['status']})")

# 2. Poll until complete
while True:
    result = requests.get(
        f"{BASE_URL}/switchx/generations/{job_id}",
        headers={"x-api-key": API_KEY},
    ).json()

    status = result["status"]
    progress = result.get("progress", 0)
    print(f"  Status: {status} ({progress}%)")

    if status == "completed":
        break
    if status == "failed":
        raise Exception(f"Job failed: {result.get('error')}")

    time.sleep(5)

# 3. Download result
render_url = result["output"]["render"]
print(f"Downloading result...")
with open("output.mp4", "wb") as f:
    f.write(requests.get(render_url).content)
print("Saved to output.mp4")

​
Using Your Own Videos

To use your own source video, alpha mask, or reference image, upload them first to get a beeble_uri.
1

Get Upload URLs

Create upload URLs for your files.
# Upload source video
curl -X POST https://api.beeble.ai/v1/uploads \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "source.mp4"}'

# Upload reference image
curl -X POST https://api.beeble.ai/v1/uploads \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "reference.png"}'
2

Upload Files

Upload each file to its upload URL.
curl -X PUT "YOUR_SOURCE_UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @source.mp4

curl -X PUT "YOUR_REFERENCE_UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @reference.png
3

Start Generation

Use the beeble_uri from the upload responses to start a generation.
curl -X POST https://api.beeble.ai/v1/switchx/generations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generation_type": "video",
    "source_uri": "YOUR_SOURCE_BEEBLE_URI",
    "reference_image_uri": "YOUR_REFERENCE_BEEBLE_URI",
    "alpha_mode": "auto",
    "prompt": "Your prompt describing the desired output."
  }'
Then poll for status and download the result as shown above.

​
Alpha Modes

Whether you need to upload an alpha mask depends on the alpha_mode you choose:
ModeAlpha Mask Required
autoNot needed — the AI detects the foreground automatically
fillNot needed — keeps everything as-is
selectFirst-frame alpha only — the AI propagates it across the video
customFull video mask required for frame-by-frame control
See the alpha_mode field in Start Generation for details.

​
Next Steps

SwitchX API

Full endpoint reference

Uploads

Upload endpoint reference