SwitchX

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.

Before you start

Create an API key for an organization with this product enabled.
Prepare your media as Beeble URIs, authorized CDN URLs, public/presigned HTTPS URLs, or base64 data URIs.
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.

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:-}"

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

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

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

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 · Response. 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. Use a unique idempotency_key for each new job; keep it unchanged on retries.

{
  "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.

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

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)

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)

Response (202, abbreviated):

{
  "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 for spending caps and refunds.

Finish a SwitchX 2.0 result

Use SwitchX 2.0 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 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 and API Reference.

Completed response

Poll the job 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.

{
  "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.

Get started

Products

Core concepts

Integrations

Before you start

Models and inputs

Submit a job

Results and constraints

Finish a SwitchX 2.0 result

Existing SwitchX generations

Completed response

​Before you start

​Models and inputs

​Submit a job

​Results and constraints

​Finish a SwitchX 2.0 result

​Existing SwitchX generations

​Completed response

Before you start

Models and inputs

Submit a job

Results and constraints

Finish a SwitchX 2.0 result

Existing SwitchX generations

Completed response