## Prerequisites

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

1. Go to [Developer Page](https://developer.beeble.ai/api-keys)
2. Sign up and accept the terms if you don’t have an account
3. Click **Create Key**

See [Authentication](https://developer.beeble.ai/docs/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

```bash
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

```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

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

```json
{
  "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

```bash
# 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

```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

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

```json
{
  "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

```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

```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`.

1. **Get Upload URLs**
   Create upload URLs for your files.

### cURL
   ```bash
   # 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
   ```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
   ```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()),
   ]);
   ```

2. **Upload Files**
   Upload each file to its upload URL.

### cURL
   ```bash
   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
   ```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
   ```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"),
     }),
   ]);
   ```

3. **Start Generation**
   Use the `beeble_uri` from the upload responses to start a generation.

### cURL
   ```bash
   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
   ```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
   ```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](https://developer.beeble.ai/docs/api-reference/switchx/start-generation#body-alpha-mode) for details.