> ## Documentation Index
> Fetch the complete documentation index at: https://developer.beeble.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Generate a composited video with SwitchX in minutes

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

<Note>
  See [Authentication](/docs/authentication) for details on obtaining and using
  your API key.
</Note>

***

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

<CardGroup cols={2}>
  <Card title="Source Video">
    <video src="https://cdn.beeble.ai/public/developer-api/source.mp4" autoPlay loop muted playsInline style={{ display: "block", margin: 0 }} />
  </Card>

  <Card title="Alpha Video">
    <video src="https://cdn.beeble.ai/public/developer-api/alpha.mp4" autoPlay loop muted playsInline />
  </Card>

  <Card title="Reference Image">
    <img src="https://cdn.beeble.ai/public/developer-api/reference.png" alt="Reference image" style={{ display: "block", margin: 0 }} />
  </Card>

  <Card title="Output">
    <video src="https://cdn.beeble.ai/public/developer-api/output.mp4" autoPlay loop muted playsInline />
  </Card>
</CardGroup>

<CodeGroup>
  ```bash cURL theme={null}
  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 theme={null}
  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 theme={null}
  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();
  ```
</CodeGroup>

**Response (201):**

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  # 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 theme={null}
  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 theme={null}
  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()));
  ```
</CodeGroup>

**Response (completed):**

```json theme={null}
{
  "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"
}
```

<Note>
  Output URLs expire after **72 hours**. You can always re-fetch fresh URLs by calling the status endpoint again.
</Note>

***

## Complete Script

A single copy-paste script that creates a generation, polls until complete, and downloads the result.

<CodeGroup>
  ```python Python theme={null}
  """
  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")
  ```

  ```javascript JavaScript theme={null}
  /**
   * 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");
  ```
</CodeGroup>

***

## Using Your Own Videos

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

<Steps>
  <Step title="Get Upload URLs">
    Create upload URLs for your files.

    <CodeGroup>
      ```bash cURL theme={null}
      # 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 theme={null}
      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 theme={null}
      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()),
      ]);
      ```
    </CodeGroup>
  </Step>

  <Step title="Upload Files">
    Upload each file to its upload URL.

    <CodeGroup>
      ```bash cURL theme={null}
      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 theme={null}
      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 theme={null}
      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"),
        }),
      ]);
      ```
    </CodeGroup>
  </Step>

  <Step title="Start Generation">
    Use the `beeble_uri` from the upload responses to start a generation.

    <CodeGroup>
      ```bash cURL theme={null}
      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 theme={null}
      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 theme={null}
      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();
      ```
    </CodeGroup>

    Then poll for status and download the result as shown above.
  </Step>
</Steps>

### 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](/docs/api-reference/switchx/start-generation#body-alpha-mode) for details.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="SwitchX API" icon="wand-magic-sparkles" href="/docs/api-reference/switchx/start-generation">
    Full endpoint reference
  </Card>

  <Card title="Uploads" icon="upload" href="/docs/api-reference/uploads/create-upload-url">
    Upload endpoint reference
  </Card>
</CardGroup>