# Authentication
Source: https://dev.docs.beeble.ai/api/authentication

How to obtain and use your Beeble API key

The Beeble API uses API keys for authentication. Each request must include your API key in the request headers.

## Getting Your API Key

<Steps>
  <Step title="Sign in to Beeble">
    Go to [app.beeble.ai](https://app.beeble.ai) and sign in to your
    account.
  </Step>

  <Step title="Navigate to Account Settings">
    Click on your profile and go to **Account Settings**.
  </Step>

  <Step title="Issue API Key">
    In the **API Key** section, click **Issue API Key** to generate a new
    key.
  </Step>

  <Step title="Save Your Key">
    Copy and securely store your API key immediately. For security reasons,
    you won't be able to view it again.
  </Step>
</Steps>

<Warning>
  Your API key will only be displayed once upon creation. Make sure to
  copy and store it in a secure location before closing the dialog.
</Warning>

## Using Your API Key

Include your API key in the `x-api-key` header with every request:

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.beeble.ai/v1/uploads",
      headers={
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={"filename": "source.mp4"}
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.beeble.ai/v1/uploads", {
      method: "POST",
      headers: {
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({ filename: "source.mp4" }),
  });
  ```
</CodeGroup>

## Revoking Your API Key

If you need to revoke your API key:

1. Go to [app.beeble.ai](https://app.beeble.ai) and navigate to your Account page
2. In the **API Key** section, click the **Revoke** button
3. Confirm the revocation

<Note>
  After revoking your API key, all requests using that key will be rejected.
  You can issue a new key at any time.
</Note>


# Errors
Source: https://dev.docs.beeble.ai/api/errors

Error codes and error response format

The Beeble API uses conventional HTTP status codes and returns structured error responses with machine-readable error codes.

## Error Response Format

All errors follow this format:

```json theme={null}
{
    "detail": {
        "message": "Human-readable error description",
        "code": "ERROR_CODE"
    }
}
```

| Field     | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| `message` | string | Human-readable description of the error |
| `code`    | string | Machine-readable error code             |

***

## Error Codes

### Validation Errors (400)

Returned when request parameters are invalid or missing.

| Code                      | Description                                             |
| ------------------------- | ------------------------------------------------------- |
| `INVALID_GENERATION_TYPE` | `generation_type` must be `"image"` or `"video"`        |
| `INVALID_ALPHA_MODE`      | `alpha_mode` must be `"auto"`, `"fill"`, or `"custom"`  |
| `INVALID_MAX_RESOLUTION`  | `max_resolution` must be `720` or `1080`                |
| `MISSING_STYLE_INPUT`     | Neither `reference_image_uri` nor `prompt` was provided |
| `MISSING_SOURCE`          | `source_uri` is required                                |
| `MISSING_ALPHA`           | `alpha_uri` required when `alpha_mode` is `"custom"`    |
| `ALPHA_TYPE_MISMATCH`     | Alpha type doesn't match source (image vs video)        |
| `INVALID_URI`             | URI format invalid or file type could not be determined |
| `SOURCE_UNREACHABLE`      | Source, alpha, or reference URI is not reachable        |
| `INVALID_FILENAME`        | Filename invalid or unsupported extension               |
| `INVALID_CALLBACK_URL`    | Callback URL is not valid HTTPS or is unreachable       |

### Authentication Errors (401)

Returned when API key authentication fails.

| Code              | Description                   |
| ----------------- | ----------------------------- |
| `INVALID_API_KEY` | API key is missing or invalid |
| `EXPIRED_API_KEY` | API key has expired           |

### Billing Errors (402)

Returned when your account lacks sufficient credits.

| Code                   | Description                           |
| ---------------------- | ------------------------------------- |
| `INSUFFICIENT_CREDITS` | Not enough credits for this operation |

### Authorization Errors (403)

Returned when you don't have permission to access a resource.

| Code            | Description                            |
| --------------- | -------------------------------------- |
| `ACCESS_DENIED` | You don't have access to this resource |

### Not Found Errors (404)

Returned when the requested resource doesn't exist.

| Code              | Description                              |
| ----------------- | ---------------------------------------- |
| `JOB_NOT_FOUND`   | Job doesn't exist or is not owned by you |
| `ASSET_NOT_FOUND` | Uploaded asset not found                 |

### Rate Limiting (429)

Returned when you exceed the request rate limit.

| Code                  | Description       |
| --------------------- | ----------------- |
| `RATE_LIMIT_EXCEEDED` | Too many requests |

### Server Errors (500)

Returned when an internal error occurs. These are not caused by your request.

| Code                      | Description                        |
| ------------------------- | ---------------------------------- |
| `INTERNAL_ERROR`          | Unexpected server error            |
| `CREDIT_DEDUCTION_FAILED` | Failed to process credit deduction |
| `UPLOAD_URL_FAILED`       | Failed to generate upload URL      |
| `JOB_QUEUE_FAILED`        | Failed to queue job for processing |


# Quickstart
Source: https://dev.docs.beeble.ai/api/quickstart

Generate a composited video with SwitchX in minutes

## Prerequisites

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

1. [Sign up](https://app.beeble.ai) if you don't have an account
2. Go to [Account Settings → API Key](https://app.beeble.ai/account)
3. Click **Issue API Key**

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

***

<Steps>
  <Step title="Upload: Get an Upload URL">
    Create an upload and get a URL for your source file.

    <CodeGroup>
      ```bash cURL theme={null}
      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"}'
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          "https://api.beeble.ai/v1/uploads",
          headers={
              "x-api-key": "YOUR_API_KEY",
              "Content-Type": "application/json"
          },
          json={"filename": "source.mp4"}
      )

      upload = response.json()
      upload_url = upload["upload_url"]
      beeble_uri = upload["beeble_uri"]
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch("https://api.beeble.ai/v1/uploads", {
        method: "POST",
        headers: {
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ filename: "source.mp4" }),
      });

      const { upload_url: uploadUrl, beeble_uri: beebleUri } =
        await response.json();
      ```
    </CodeGroup>

    Then upload your file to the upload URL:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X PUT "${UPLOAD_URL}" \
        -H "Content-Type: video/mp4" \
        --data-binary @source.mp4
      ```

      ```python Python theme={null}
      with open("source.mp4", "rb") as f:
          requests.put(
              upload_url,
              headers={"Content-Type": "video/mp4"},
              data=f
          )
      ```

      ```javascript JavaScript theme={null}
      const file = fs.readFileSync("source.mp4");

      await fetch(uploadUrl, {
        method: "PUT",
        headers: { "Content-Type": "video/mp4" },
        body: file,
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Generate: Start SwitchX">
    Start a compositing job with your uploaded source.

    <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": "'"${BEEBLE_URI}"'",
          "prompt": "cinematic studio lighting",
          "alpha_mode": "auto"
        }'
      ```

      ```python Python theme={null}
      response = requests.post(
          "https://api.beeble.ai/v1/switchx/generations",
          headers={
              "x-api-key": "YOUR_API_KEY",
              "Content-Type": "application/json"
          },
          json={
              "generation_type": "video",
              "source_uri": beeble_uri,
              "prompt": "cinematic studio lighting",
              "alpha_mode": "auto",
          }
      )

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

      ```javascript JavaScript theme={null}
      const res = await fetch("https://api.beeble.ai/v1/switchx/generations", {
        method: "POST",
        headers: {
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          generation_type: "video",
          source_uri: beebleUri,
          prompt: "cinematic studio lighting",
          alpha_mode: "auto",
        }),
      });

      const { id: jobId } = await res.json();
      ```
    </CodeGroup>

    **Response:**

    ```json theme={null}
    {
      "id": "swx_abc123..."
    }
    ```
  </Step>

  <Step title="Poll: Check Job Status">
    Poll the job status until it completes.

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.beeble.ai/v1/switchx/generations/swx_abc123 \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```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": "YOUR_API_KEY"}
          ).json()

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

          time.sleep(5)
      ```

      ```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": "YOUR_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);
      }
      ```
    </CodeGroup>

    **Response (completed):**

    ```json theme={null}
    {
      "id": "swx_abc123",
      "status": "completed",
      "progress": 100,
      "generation_type": "video",
      "alpha_mode": "auto",
      "output": {
        "render": "https://cdn.beeble.ai/.../render.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"
    }
    ```
  </Step>

  <Step title="Download: Get Results">
    Download the composited output.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -o render.mp4 "https://cdn.beeble.ai/.../render.mp4"
      ```

      ```python Python theme={null}
      with open("render.mp4", "wb") as f:
          f.write(requests.get(output["render"]).content)
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch(output.render);
      fs.writeFileSync("render.mp4", Buffer.from(await res.arrayBuffer()));
      ```
    </CodeGroup>

    <Note>
      Output URLs expire after a limited time. Download results promptly.
    </Note>
  </Step>
</Steps>

***

## Next Steps

<CardGroup>
  <Card title="SwitchX API" icon="wand-magic-sparkles" href="/api/switchx">
    Full endpoint reference
  </Card>

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


# SwitchX
Source: https://dev.docs.beeble.ai/api/switchx

AI-powered video-to-video compositing API

SwitchX is a video-to-video model that switches anything but keeps what matters. Provide a source image or video, a reference image and/or text prompt, and SwitchX generates a composited result.

<Info>
  Jobs created via the API are **not visible** in
  [app.beeble.ai](https://app.beeble.ai).
</Info>

<Steps>
  <Step title="Upload">
    [Upload your files](/api/uploads) to get `beeble://` URIs
  </Step>

  <Step title="Generate">
    [Start a generation](#start-generation) with your source and lighting inputs
  </Step>

  <Step title="Poll or Webhook">
    [Check job status](#get-job-status) until completed, or use [webhook
    callbacks](#webhook-callbacks) to receive notifications
  </Step>

  <Step title="Download">
    Get composited output from `output` URLs
  </Step>
</Steps>

***

## Start Generation

<Card>
  <code>POST</code>
  `/v1/switchx/generations`
</Card>

Start a SwitchX compositing job. Credits are pre-charged and refunded on failure.

### Request

| Header      | Type   | Required | Description                         |
| ----------- | ------ | -------- | ----------------------------------- |
| `x-api-key` | string | Yes      | [Your API key](/api/authentication) |

| Body                  | Type   | Required  | Description                                                                                                           |
| --------------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------- |
| `generation_type`     | string | Yes       | `"image"` or `"video"`                                                                                                |
| `source_uri`          | string | Yes       | URI of the source image or video                                                                                      |
| `reference_image_uri` | string | No\*      | URI of the reference image for style transfer                                                                         |
| `prompt`              | string | No\*      | Text description of desired output (max 2000 chars)                                                                   |
| `alpha_mode`          | string | Yes       | `"auto"`, `"fill"`, or `"custom"`                                                                                     |
| `alpha_uri`           | string | If custom | URI of custom alpha matte (required when `alpha_mode=custom`)                                                         |
| `seed`                | int    | No        | Reproducibility seed (0-4294967295)                                                                                   |
| `max_resolution`      | int    | No        | `720` or `1080` (default: `1080`)                                                                                     |
| `callback_url`        | string | No        | HTTPS URL for webhook notification on completion/failure                                                              |
| `idempotency_key`     | string | No        | Key for safe retries (max 256 chars). If a job with this key exists, returns its status instead of creating a new one |

<Note>
  **\*** At least one of `reference_image_uri` or `prompt` must be provided.
  You can provide both for more control over the output.
</Note>

<Note>
  `alpha_uri` is only required when `alpha_mode` is set to `"custom"`. When
  using `"auto"` or `"fill"`, the alpha is handled automatically.
</Note>

**URI types accepted:**

* `beeble://uploads/{id}/{filename}` — from the [uploads endpoint](/api/uploads)
* `https://...` — external URL (server downloads it)
* `data:video/mp4;base64,...` — inline base64 (small files only)

### Idempotency

Pass an `idempotency_key` to safely retry requests. If a job with the same key already exists for your account, the API returns the existing job's status instead of creating a duplicate.

<Tip>
  Use a unique, deterministic key per logical request (e.g., your internal order ID). This prevents double-charges if your client retries due to network timeouts.
</Tip>

### Response

| Property          | Type   | Optional | Description                                             |
| ----------------- | ------ | -------- | ------------------------------------------------------- |
| `id`              | string | No       | Job ID (`swx_...`)                                      |
| `status`          | string | No       | `in_queue` (or existing job's status if idempotent hit) |
| `progress`        | int    | Yes      | Progress percentage (0-100)                             |
| `generation_type` | string | Yes      | `"image"` or `"video"`                                  |
| `alpha_mode`      | string | Yes      | Alpha mode used                                         |
| `output`          | object | Yes      | Output URLs (if idempotent hit on completed job)        |
| `error`           | string | Yes      | Error message (if idempotent hit on failed job)         |
| `created_at`      | string | Yes      | ISO timestamp                                           |
| `modified_at`     | string | Yes      | ISO timestamp                                           |
| `completed_at`    | string | Yes      | ISO timestamp                                           |

### Example

<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": "beeble://uploads/upload_xxx/source.mp4",
      "reference_image_uri": "https://example.com/ref.png",
      "prompt": "cinematic studio lighting",
      "alpha_mode": "auto",
      "max_resolution": 1080
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.beeble.ai/v1/switchx/generations",
      headers={
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "generation_type": "video",
          "source_uri": "beeble://uploads/upload_xxx/source.mp4",
          "reference_image_uri": "https://example.com/ref.png",
          "prompt": "cinematic studio lighting",
          "alpha_mode": "auto",
          "max_resolution": 1080,
      }
  )

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

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.beeble.ai/v1/switchx/generations", {
      method: "POST",
      headers: {
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          generation_type: "video",
          source_uri: "beeble://uploads/upload_xxx/source.mp4",
          reference_image_uri: "https://example.com/ref.png",
          prompt: "cinematic studio lighting",
          alpha_mode: "auto",
          max_resolution: 1080,
      }),
  });

  const { id: jobId } = await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
    "id": "swx_abc123",
    "status": "in_queue",
    "progress": 0,
    "generation_type": "video",
    "alpha_mode": "auto",
    "output": null,
    "error": null,
    "created_at": "2026-02-23T10:00:00Z",
    "modified_at": "2026-02-23T10:00:00Z",
    "completed_at": null
}
```

***

## Get Job Status

<Card>
  <code>GET</code>
  `/v1/switchx/generations/{job_id}`
</Card>

Poll the job status until it completes.

### Request

| Header      | Type   | Required | Description                         |
| ----------- | ------ | -------- | ----------------------------------- |
| `x-api-key` | string | Yes      | [Your API key](/api/authentication) |

| Path     | Type   | Required | Description                     |
| -------- | ------ | -------- | ------------------------------- |
| `job_id` | string | Yes      | Job ID from generation response |

### Response

| Property          | Type   | Optional | Description                                        |
| ----------------- | ------ | -------- | -------------------------------------------------- |
| `id`              | string | No       | Job identifier                                     |
| `status`          | string | No       | `in_queue`, `processing`, `completed`, or `failed` |
| `progress`        | int    | Yes      | Progress percentage (0-100)                        |
| `generation_type` | string | Yes      | `"image"` or `"video"`                             |
| `alpha_mode`      | string | Yes      | `"auto"`, `"fill"`, or `"custom"`                  |
| `output`          | object | Yes      | Output URLs (when `completed`)                     |
| `error`           | string | Yes      | Error message (when `failed`)                      |
| `created_at`      | string | Yes      | ISO timestamp when job was created                 |
| `modified_at`     | string | Yes      | ISO timestamp of last update                       |
| `completed_at`    | string | Yes      | ISO timestamp when job completed                   |

**`output`** (when completed):

| Property | Type   | Description             |
| -------- | ------ | ----------------------- |
| `render` | string | Composited output URL   |
| `source` | string | Preprocessed source URL |
| `alpha`  | string | Alpha matte URL         |

<Warning>Output URLs expire after a limited time. Download results promptly.</Warning>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.beeble.ai/v1/switchx/generations/swx_abc123 \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import time

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

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

      time.sleep(5)
  ```

  ```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": "YOUR_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);
  }
  ```
</CodeGroup>

**Response (in\_queue):**

```json theme={null}
{
    "id": "swx_abc123",
    "status": "in_queue",
    "progress": 0,
    "generation_type": "video",
    "alpha_mode": "auto",
    "output": null,
    "error": null,
    "created_at": "2026-02-23T10:00:00Z",
    "modified_at": "2026-02-23T10:00:00Z",
    "completed_at": null
}
```

**Response (completed):**

```json theme={null}
{
    "id": "swx_abc123",
    "status": "completed",
    "progress": 100,
    "generation_type": "video",
    "alpha_mode": "auto",
    "output": {
        "render": "https://cdn.beeble.ai/.../render.mp4",
        "source": "https://cdn.beeble.ai/.../source.mp4",
        "alpha": "https://cdn.beeble.ai/.../alpha.mp4"
    },
    "error": null,
    "created_at": "2026-02-23T10:00:00Z",
    "modified_at": "2026-02-23T10:05:00Z",
    "completed_at": "2026-02-23T10:05:00Z"
}
```

***

## List Jobs

<Card>
  <code>GET</code>
  `/v1/switchx/generations`
</Card>

List your SwitchX jobs with pagination.

### Request

| Header      | Type   | Required | Description                         |
| ----------- | ------ | -------- | ----------------------------------- |
| `x-api-key` | string | Yes      | [Your API key](/api/authentication) |

| Query        | Type   | Default | Description              |
| ------------ | ------ | ------- | ------------------------ |
| `limit`      | int    | 20      | Results per page (1-100) |
| `page_token` | string | —       | Pagination cursor        |

### Response

```json theme={null}
{
    "jobs": [
        {
            "id": "swx_abc123",
            "status": "completed",
            "progress": 100,
            "generation_type": "video",
            "alpha_mode": "auto",
            "created_at": "2026-02-23T10:00:00Z",
            "modified_at": "2026-02-23T10:05:00Z",
            "completed_at": "2026-02-23T10:05:00Z"
        }
    ],
    "next_page_token": "base64..."
}
```

***

## Webhook Callbacks

Instead of polling for job status, provide a `callback_url` when starting generation to receive a webhook notification when the job completes or fails.

### Using Webhooks

Include the `callback_url` parameter in your generation request:

<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": "beeble://uploads/upload_xxx/source.mp4",
      "reference_image_uri": "https://example.com/ref.png",
      "alpha_mode": "auto",
      "callback_url": "https://your-server.com/webhook"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.beeble.ai/v1/switchx/generations",
      headers={
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "generation_type": "video",
          "source_uri": "beeble://uploads/upload_xxx/source.mp4",
          "reference_image_uri": "https://example.com/ref.png",
          "alpha_mode": "auto",
          "callback_url": "https://your-server.com/webhook",
      }
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.beeble.ai/v1/switchx/generations", {
      method: "POST",
      headers: {
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          generation_type: "video",
          source_uri: "beeble://uploads/upload_xxx/source.mp4",
          reference_image_uri: "https://example.com/ref.png",
          alpha_mode: "auto",
          callback_url: "https://your-server.com/webhook",
      }),
  });
  ```
</CodeGroup>

### Webhook Payload

When the job completes or fails, a `POST` request will be sent to your `callback_url`.

**Success:**

```json theme={null}
{
    "id": "swx_abc123",
    "status": "completed",
    "output": {
        "render": "https://cdn.beeble.ai/.../render.mp4",
        "source": "https://cdn.beeble.ai/.../source.mp4",
        "alpha": "https://cdn.beeble.ai/.../alpha.mp4"
    },
    "completed_at": "2026-02-23T10:05:00Z"
}
```

**Failure:**

```json theme={null}
{
    "id": "swx_abc123",
    "status": "failed",
    "completed_at": "2026-02-23T10:05:00Z",
    "error": "Processing failed"
}
```

<Note>
  Your webhook endpoint should return a `2xx` status code to acknowledge
  receipt.
</Note>

***

## Errors

The following validation errors (400) are specific to SwitchX endpoints:

| Code                      | Description                                             |
| ------------------------- | ------------------------------------------------------- |
| `INVALID_GENERATION_TYPE` | `generation_type` must be `"image"` or `"video"`        |
| `INVALID_ALPHA_MODE`      | `alpha_mode` must be `"auto"`, `"fill"`, or `"custom"`  |
| `INVALID_MAX_RESOLUTION`  | `max_resolution` must be `720` or `1080`                |
| `MISSING_STYLE_INPUT`     | Neither `reference_image_uri` nor `prompt` was provided |
| `MISSING_ALPHA`           | `alpha_uri` required when `alpha_mode` is `"custom"`    |
| `ALPHA_TYPE_MISMATCH`     | Alpha type doesn't match source (image vs video)        |
| `INVALID_URI`             | URI format invalid or file type could not be determined |
| `SOURCE_UNREACHABLE`      | Source, alpha, or reference URI is not reachable        |
| `INVALID_CALLBACK_URL`    | Callback URL is not valid HTTPS or is unreachable       |

<Note>
  See [Errors](/api/errors) for authentication, billing, rate limiting, and other common error codes.
</Note>


# Uploads
Source: https://dev.docs.beeble.ai/api/uploads

Create upload URLs for media files

Upload media files to Beeble for use with the SwitchX API. The uploads endpoint returns an upload URL for direct file upload and a `beeble://` URI to reference the file in generation calls.

***

## Create Upload

<Card>
  <code>POST</code>
  `/v1/uploads`
</Card>

Create an upload URL for a media file.

### Request

| Header      | Type   | Required | Description                         |
| ----------- | ------ | -------- | ----------------------------------- |
| `x-api-key` | string | Yes      | [Your API key](/api/authentication) |

| Body       | Type   | Required | Description                           |
| ---------- | ------ | -------- | ------------------------------------- |
| `filename` | string | Yes      | Filename with extension (3-255 chars) |

<Note>
  **Accepted extensions:** `.mp4`, `.mov`, `.png`, `.jpg`, `.jpeg`, `.webp`
</Note>

### Response

| Property     | Type   | Description                                      |
| ------------ | ------ | ------------------------------------------------ |
| `id`         | string | Unique upload identifier (`upload_` prefix)      |
| `upload_url` | string | URL for uploading your file                      |
| `beeble_uri` | string | `beeble://` URI to reference in generation calls |

<Note>
  The `upload_url` expires after **1 hour**. Complete your upload before it expires.
</Note>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.beeble.ai/v1/uploads \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"filename": "my_video.mp4"}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.beeble.ai/v1/uploads",
      headers={
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={"filename": "my_video.mp4"}
  )

  upload = response.json()
  upload_url = upload["upload_url"]
  beeble_uri = upload["beeble_uri"]
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.beeble.ai/v1/uploads", {
      method: "POST",
      headers: {
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({ filename: "my_video.mp4" }),
  });

  const { upload_url: uploadUrl, beeble_uri: beebleUri } =
      await response.json();
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
    "id": "upload_7kHs9mNx2pQ...",
    "upload_url": "https://storage.beeble.ai/...?X-Amz-Signature=...",
    "beeble_uri": "beeble://uploads/upload_7kHs9mNx2pQ.../my_video.mp4"
}
```

***

## Upload Your File

Use the `upload_url` from the response to upload your file with a `PUT` request.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "${UPLOAD_URL}" \
    -H "Content-Type: video/mp4" \
    --data-binary @my_video.mp4
  ```

  ```python Python theme={null}
  with open("my_video.mp4", "rb") as f:
      requests.put(
          upload_url,
          headers={"Content-Type": "video/mp4"},
          data=f
      )
  ```

  ```javascript JavaScript theme={null}
  const file = fs.readFileSync("my_video.mp4");

  await fetch(uploadUrl, {
      method: "PUT",
      headers: { "Content-Type": "video/mp4" },
      body: file,
  });
  ```
</CodeGroup>

<Warning>
  Uploaded files are automatically deleted after **24 hours**. Start your
  generation job before the file expires.
</Warning>

***

## Using beeble:// URIs

After uploading, use the returned `beeble_uri` to reference your file in SwitchX generation calls:

```
beeble://uploads/{upload_id}/{filename}
```

Pass this URI as the `source_uri`, `reference_image_uri`, or `alpha_uri` field when [starting a SwitchX generation](/api/switchx#start-generation).

***

## Errors

The following validation error (400) is specific to the uploads endpoint:

| Code               | Description                               |
| ------------------ | ----------------------------------------- |
| `INVALID_FILENAME` | Filename invalid or unsupported extension |

<Note>
  See [Errors](/api/errors) for authentication, rate limiting, and other common error codes.
</Note>


# Overview
Source: https://dev.docs.beeble.ai/index

Beeble API for AI-powered visual effects

The Beeble API provides AI-powered compositing for images and videos.

<Card title="Quickstart — SwitchX" icon="rocket" href="/api/quickstart">
  Make your first API call in minutes
</Card>

***

## SwitchX

SwitchX is a video-to-video model that switches anything but keeps what matters. Upload your source media, provide a reference image and/or text prompt, and get a transformed result.

### How It Works

<Steps>
  <Step title="Upload">
    Upload your files via the [Uploads API](/api/uploads)
  </Step>

  <Step title="Generate">Start a compositing generation job</Step>

  <Step title="Poll or Webhook">
    Check status or receive webhook callbacks
  </Step>

  <Step title="Download">Get composited output</Step>
</Steps>

***

## Quick Reference

|              |                            |
| ------------ | -------------------------- |
| **Base URL** | `https://api.beeble.ai/v1` |
| **Auth**     | `x-api-key` header         |
| **Input**    | Images + Videos via upload |
| **Output**   | Composited image or video  |

***

## Get Started

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/api/quickstart">
    Make your first API call in minutes
  </Card>

  <Card title="SwitchX API" icon="wand-magic-sparkles" href="/api/switchx">
    Full SwitchX endpoint reference
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Uploads" icon="upload" href="/api/uploads">
    Upload files for SwitchX
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    Get your API key
  </Card>
</CardGroup>