Quickstart

Prerequisites

To use the Beeble API, you need an API key.

Go to Developer Page
Sign up and accept the terms if you don’t have an account
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

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."
  }'

import requests

API_KEY = "YOUR_API_KEY"
HEADERS = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.beeble.ai/v1/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.",
    }
)

job_id = response.json()["id"]

const API_KEY = "YOUR_API_KEY";
const headers = {
  "x-api-key": API_KEY,
  "Content-Type": "application/json",
};

const res = await fetch(
  "https://api.beeble.ai/v1/switchx/generations",
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      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.",
    }),
  }
);

const { id: jobId } = await res.json();

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"

import time

while True:
    result = requests.get(
        f"https://api.beeble.ai/v1/switchx/generations/{job_id}",
        headers={"x-api-key": API_KEY}
    ).json()

    if result["status"] == "completed":
        output = result["output"]
        break
    if result["status"] == "failed":
        raise Exception(result.get("error"))

    time.sleep(5)

# Download the result
with open("output.mp4", "wb") as f:
    f.write(requests.get(output["render"]).content)

const sleep = (ms) => new Promise(r => setTimeout(r, ms));

let output;
while (true) {
  const res = await fetch(
    `https://api.beeble.ai/v1/switchx/generations/${jobId}`,
    { headers: { "x-api-key": API_KEY } }
  );
  const status = await res.json();

  if (status.status === "completed") {
    output = status.output;
    break;
  }
  if (status.status === "failed") throw new Error(status.error);

  await sleep(5000);
}

// Download the result
const fs = require("fs");
const renderRes = await fetch(output.render);
fs.writeFileSync("output.mp4", Buffer.from(await renderRes.arrayBuffer()));

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")

/**
 * Beeble SwitchX API — Complete Example
 * Usage: node beeble_quickstart.mjs
 */
import fs from "fs";

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

// 1. Start generation
console.log("Starting generation...");
const createRes = await fetch(`${BASE_URL}/switchx/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    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.",
  }),
});
const job = await createRes.json();
console.log(`Job created: ${job.id} (status: ${job.status})`);

// 2. Poll until complete
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
let result;
while (true) {
  const res = await fetch(`${BASE_URL}/switchx/generations/${job.id}`, {
    headers: { "x-api-key": API_KEY },
  });
  result = await res.json();
  console.log(`  Status: ${result.status} (${result.progress ?? 0}%)`);

  if (result.status === "completed") break;
  if (result.status === "failed") throw new Error(result.error);
  await sleep(5000);
}

// 3. Download result
console.log("Downloading result...");
const renderRes = await fetch(result.output.render);
fs.writeFileSync("output.mp4", Buffer.from(await renderRes.arrayBuffer()));
console.log("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.

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"}'

source_upload = requests.post(
    "https://api.beeble.ai/v1/uploads",
    headers=HEADERS,
    json={"filename": "source.mp4"}
).json()

reference_upload = requests.post(
    "https://api.beeble.ai/v1/uploads",
    headers=HEADERS,
    json={"filename": "reference.png"}
).json()

const [sourceUpload, referenceUpload] = await Promise.all([
  fetch("https://api.beeble.ai/v1/uploads", {
    method: "POST",
    headers,
    body: JSON.stringify({ filename: "source.mp4" }),
  }).then((r) => r.json()),

  fetch("https://api.beeble.ai/v1/uploads", {
    method: "POST",
    headers,
    body: JSON.stringify({ filename: "reference.png" }),
  }).then((r) => r.json()),
]);

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

with open("source.mp4", "rb") as f:
    requests.put(
        source_upload["upload_url"],
        headers={"Content-Type": "video/mp4"},
        data=f
    )

with open("reference.png", "rb") as f:
    requests.put(
        reference_upload["upload_url"],
        headers={"Content-Type": "image/png"},
        data=f
    )

const fs = require("fs");

await Promise.all([
  fetch(sourceUpload.upload_url, {
    method: "PUT",
    headers: { "Content-Type": "video/mp4" },
    body: fs.readFileSync("source.mp4"),
  }),
  fetch(referenceUpload.upload_url, {
    method: "PUT",
    headers: { "Content-Type": "image/png" },
    body: fs.readFileSync("reference.png"),
  }),
]);

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."
  }'

response = requests.post(
    "https://api.beeble.ai/v1/switchx/generations",
    headers=HEADERS,
    json={
        "generation_type": "video",
        "source_uri": source_upload["beeble_uri"],
        "reference_image_uri": reference_upload["beeble_uri"],
        "alpha_mode": "auto",
        "prompt": "Your prompt describing the desired output.",
    }
)

job_id = response.json()["id"]

const res = await fetch(
  "https://api.beeble.ai/v1/switchx/generations",
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      generation_type: "video",
      source_uri: sourceUpload.beeble_uri,
      reference_image_uri: referenceUpload.beeble_uri,
      alpha_mode: "auto",
      prompt: "Your prompt describing the desired output.",
    }),
  }
);

const { id: jobId } = await res.json();

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:

Mode	Alpha Mask Required
auto	Not needed — the AI detects the foreground automatically
fill	Not needed — keeps everything as-is
select	Single reference-frame alpha — the AI propagates it across the video (defaults to the first frame; pick another with `alpha_keyframe_index`)
custom	Full 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

Get Started

Uploads

SwitchX

Account

Resources

Prerequisites

Try It — One Command

Source Video

Alpha Video

Reference Image

Output

Check Status & Download

Complete Script

Using Your Own Videos

Alpha Modes

Next Steps

SwitchX API

Uploads

​Prerequisites

​Try It — One Command

Source Video

Alpha Video

Reference Image

Output

​Check Status & Download

​Complete Script

​Using Your Own Videos

​Alpha Modes

​Next Steps

SwitchX API

Uploads

Prerequisites

Try It — One Command

Check Status & Download

Complete Script

Using Your Own Videos

Alpha Modes

Next Steps