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

> ## Agent Instructions
> This site documents two API families. Choose the family before generating integration code and keep its request fields, billing, statuses, responses, and webhooks together.
> SwitchX API: POST /v1/switchx/generations; use /quickstart and /authentication. Completed generation files are under output.
> Enterprise API: POST /v1/products/{product}/jobs and GET /v1/product-jobs/{job_id}; use /enterprise/quickstart and /products. Check /enterprise for current access requirements. Completed product files are under outputs.
> For product jobs, fetch model-specific input_schema from GET /v1/products/{product}/models. OpenAPI defines the common job response; product guides show illustrative completed outputs. Do not treat output examples as exhaustive schemas.
> SwitchX 2.0 Finish uses the separate switchx_finish product and model_id switchx-2.0. Follow /products/switchx-finish: pass inputs.parent_job_id (a completed Standard switchx product generation's public dap_ ID owned by the same key owner, organization, and team) and inputs.target_resolution (1080 or 2160), without uploading media. Fast results, Finish results, and legacy SwitchX API generations cannot be parents. Estimate the transition, then submit and poll the new child ID; result files are under outputs.
> For product APIs, authenticate with an Organization API Key in x-api-key and keep the same organization and X-Beeble-Team-Id context for uploads, estimates, submissions, and reads. Use Beeble Cloud credits; product routes do not support USD.
> Follow /enterprise/llms-txt for the product API workflow: discover products and models, upload media, estimate credits, submit with an idempotency_key, and poll or receive webhooks. On an uncertain submission, retry the same body and key; do not create a replacement job.
> Product-job success is status=success; stop polling on failed, cancelled, or credit_required. Use the chosen product guide for completed response examples and download fields. Refer to /enterprise/errors, /enterprise/rate-limits, /guides/billing, and /guides/jobs for failures, limits, and refunds.

# SwitchX

> Replace environments and relight your subject with SwitchX 1.0 or 2.0.

**Product ID:** `switchx`

**Billing:** Beeble Cloud credits

Use SwitchX to replace an environment, relight a subject, or restyle a shot
while preserving the source performance. The alpha mask controls which regions
are regenerated; a reference image guides the lighting and appearance.

For reference-image preparation and visual examples, see the
[SwitchX product guide](https://docs.beeble.ai/beeble/switchx).

## Before you start

1. Create an [API key](/docs/enterprise/authentication) for an organization with this product enabled.
2. [Prepare your media](/docs/guides/uploads#choose-a-media-input) as Beeble URIs, authorized CDN URLs, public/presigned HTTPS URLs, or base64 data URIs.
3. Select an available model below; complete any required consent in Beeble Cloud.

## Models and inputs

Set `BEEBLE_API_KEY` and, for internal teams, `BEEBLE_TEAM_ID`.

<CodeGroup>
  ```bash cURL theme={null}
  curl --fail-with-body "https://api.beeble.ai/v1/products/switchx/models" \
    -H "x-api-key: $BEEBLE_API_KEY" \
    -H "X-Beeble-Team-Id: ${BEEBLE_TEAM_ID:-}"
  ```

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

  headers = {"x-api-key": os.environ["BEEBLE_API_KEY"]}
  if team_id := os.environ.get("BEEBLE_TEAM_ID"):
      headers["X-Beeble-Team-Id"] = team_id

  response = requests.get(
      "https://api.beeble.ai/v1/products/switchx/models",
      headers=headers,
      timeout=30,
  )
  response.raise_for_status()
  print(json.dumps(response.json(), indent=2))
  ```

  ```javascript JavaScript theme={null}
  const headers = { "x-api-key": process.env.BEEBLE_API_KEY }
  if (process.env.BEEBLE_TEAM_ID) {
    headers["X-Beeble-Team-Id"] = process.env.BEEBLE_TEAM_ID
  }
  const response = await fetch(
    "https://api.beeble.ai/v1/products/switchx/models",
    {
      headers,
      signal: AbortSignal.timeout(30_000),
    },
  )
  if (!response.ok) throw new Error(await response.text())
  console.log(JSON.stringify(await response.json(), null, 2))
  ```
</CodeGroup>

**Response (200):** `models` contains each model's `id`, `name`,
`input_schema`, and any `requires_consent` value. Use the selected model's
`input_schema` for required inputs, types, defaults, and supported values.

[Request parameters and response schema](/docs/api-reference/products/list-product-model-input-schemas)

| Model       | API model ID  | Controls                                   |
| ----------- | ------------- | ------------------------------------------ |
| SwitchX 1.0 | `switchx-1.0` | Original relighting and compositing model. |
| SwitchX 2.0 | `switchx-2.0` | Adds the `camera_tracking` control.        |

Read the model schema for supported resolutions and frame limits.

Use `alpha_mode: "auto"` to isolate the main subject, or `"fill"` to relight
and restyle the whole frame. A reference image should show the subject and
environment together so it communicates how the subject should be lit.
For SwitchX 2.0 video, `camera_tracking` controls whether the generated
environment follows the source camera motion.

## Submit a job

**Schemas:** [Request body](/docs/enterprise/schemas/product-job-request) ·
[Response](/docs/enterprise/schemas/product-job). The `inputs` object follows your
selected model's `input_schema` above.

Save as `request.json` with your media URIs. The Beeble URIs below can be replaced
with any [supported single-file media input](/docs/guides/uploads#choose-a-media-input). Use a unique `idempotency_key`
for each new job; keep it unchanged on retries.

```json theme={null}
{
  "model_id": "switchx-2.0",
  "billing_unit": "credits",
  "idempotency_key": "switchx-example-001",
  "inputs": {
    "source": "beeble://uploads/your-upload-id/source.png",
    "generation_type": "image",
    "prompt": "Warm studio lighting",
    "alpha_mode": "fill",
    "max_resolution": 720,
    "mode": "standard"
  }
}
```

Python requires `requests`; JavaScript examples run in Node.js.

<CodeGroup>
  ```bash cURL theme={null}
  curl --fail-with-body https://api.beeble.ai/v1/products/switchx/jobs \
    -H "x-api-key: $BEEBLE_API_KEY" \
    -H "X-Beeble-Team-Id: ${BEEBLE_TEAM_ID:-}" \
    -H "Content-Type: application/json" \
    --data-binary @request.json
  ```

  ```python Python theme={null}
  import json
  import os
  from pathlib import Path

  import requests

  headers = {"x-api-key": os.environ["BEEBLE_API_KEY"]}
  if team_id := os.environ.get("BEEBLE_TEAM_ID"):
      headers["X-Beeble-Team-Id"] = team_id

  response = requests.post(
      "https://api.beeble.ai/v1/products/switchx/jobs",
      headers=headers,
      json=json.loads(Path("request.json").read_text()),
      timeout=120,
  )
  response.raise_for_status()
  job_id = response.json()["id"]
  print(job_id)
  ```

  ```javascript JavaScript theme={null}
  import { readFile } from "node:fs/promises"

  const headers = {
    "x-api-key": process.env.BEEBLE_API_KEY,
    "Content-Type": "application/json",
  }
  if (process.env.BEEBLE_TEAM_ID) {
    headers["X-Beeble-Team-Id"] = process.env.BEEBLE_TEAM_ID
  }

  const response = await fetch("https://api.beeble.ai/v1/products/switchx/jobs", {
    method: "POST",
    headers,
    body: await readFile("request.json", "utf8"),
    signal: AbortSignal.timeout(120_000),
  })
  if (!response.ok) throw new Error(await response.text())
  const { id: jobId } = await response.json()
  console.log(jobId)
  ```
</CodeGroup>

**Response (202, abbreviated):**

```json theme={null}
{
  "id": "dap_example",
  "status": "processing",
  "outputs": {}
}
```

## Results and constraints

The server measures the source, so `generation_type` and `frame_count` can be
omitted. A supplied media type must match the file. Use `alpha` for a finished
custom matte, or `alpha_keyframe` with `alpha_keyframe_index` for the product
API's `keyframe` mode. Source and custom-alpha uploads must not exceed 5 GB.

With `alpha_mode: "fill"`, `outputs.alpha` is `null`.

See [Billing & credits](/docs/guides/billing) for spending caps and refunds.

## Finish a SwitchX 2.0 result

Use [SwitchX 2.0 Finish](/docs/products/switchx-finish) to render a completed Standard
image or video at a higher resolution. Finish uses the separate `switchx_finish`
product and reuses the parent's source, mask, and settings without another upload.
Supported transitions are 720 → 1080, 720 → 2160, and 1080 → 2160, subject to
the original source size.

Pass the original product generation's public `dap_…` ID as `inputs.parent_job_id`.
Finish results and jobs from `/v1/switchx/generations` cannot be parents.
The [Finish guide](/docs/products/switchx-finish) covers eligibility,
transition estimates, submission, and retrieving the new result.

## Existing SwitchX generations

Existing integrations continue to use `/v1/switchx/generations`. Choose
**SwitchX API** in the documentation selector for its [quickstart](/docs/quickstart)
and [API Reference](/docs/api-reference/switchx/start-generation).

## Completed response

[Poll the job](/docs/guides/jobs#poll-for-completion) using the returned `id` until
`status` is `success`. Stop on `failed`, `cancelled`, or `credit_required`.

**Example response (200, success; abbreviated):** URLs are illustrative.
Available outputs depend on the model and input media.

```json theme={null}
{
  "id": "dap_example",
  "product": "switchx",
  "status": "success",
  "outputs": {
    "render": "https://cdn.beeble.ai/example/render.png?signed-parameters",
    "source": "https://cdn.beeble.ai/example/source.png?signed-parameters",
    "alpha": null
  }
}
```

Download `outputs.render`. With `alpha_mode: "fill"`, `outputs.alpha` is `null`.