Quickstart - Beeble API Documentation

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

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

Python

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

JavaScript

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.

cURL

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

Python

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)

JavaScript

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.

Python

"""
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("Downloading result...")
with open("output.mp4", "wb") as f:
    f.write(requests.get(render_url).content)
print("Saved to output.mp4")

JavaScript

/**
 * 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.

cURL

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

Python

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

JavaScript

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

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

Python

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
    )

JavaScript

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

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

Python

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

JavaScript

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.