Quickstart

Prerequisites

Create an API key in the Developer Portal.
Confirm SwitchX 2.0 access and Beeble Cloud credits. Complete any required consent in Beeble Cloud.
Prepare a source image as an uploaded Beeble URI, authorized CDN URL, public/presigned HTTPS URL, or base64 data URI.

Set BEEBLE_API_KEY in your environment. If your organization uses internal teams, set BEEBLE_TEAM_ID. If using an upload, use the same organization and team for the upload and job.

Submit your first job

Request parameters, body, and response schema Replace inputs.source with your media URI. The examples use an uploaded beeble_uri; you can put a public/presigned HTTPS URL or a complete base64 data URI in the same field without calling /v1/uploads. See media limits and inline examples. Save your request and keep its body and idempotency key unchanged on retries; use a new key for each new job.

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 '{
    "model_id": "switchx-2.0",
    "idempotency_key": "first-switchx-001",
    "inputs": {
      "source": "beeble://uploads/your-upload-id/source.png",
      "alpha_mode": "fill",
      "max_resolution": 720,
      "prompt": "Warm studio lighting",
      "mode": "standard"
    }
  }'

# Install: pip install requests
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.post(
    "https://api.beeble.ai/v1/products/switchx/jobs",
    headers=headers,
    json={
        "model_id": "switchx-2.0",
        "idempotency_key": "first-switchx-001",
        "inputs": {
            "source": "beeble://uploads/your-upload-id/source.png",
            "alpha_mode": "fill",
            "max_resolution": 720,
            "prompt": "Warm studio lighting",
            "mode": "standard",
        },
    },
    timeout=120,
)
response.raise_for_status()
job_id = response.json()["id"]
print(job_id)

// Run as a Node.js .mjs file.
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: JSON.stringify({
    model_id: "switchx-2.0",
    idempotency_key: "first-switchx-001",
    inputs: {
      source: "beeble://uploads/your-upload-id/source.png",
      alpha_mode: "fill",
      max_resolution: 720,
      prompt: "Warm studio lighting",
      mode: "standard",
    },
  }),
  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",
  "product": "switchx",
  "model_id": "switchx-2.0",
  "status": "processing",
  "billing_unit": "credits",
  "outputs": {}
}

Check Status & Download

Request parameters and response schema Use the returned id to check progress. Wait a few seconds between checks until success; stop on failed, cancelled, or credit_required.

JOB_ID="dap_example" # Replace with the id returned above.
curl --fail-with-body "https://api.beeble.ai/v1/product-jobs/$JOB_ID" \
  -H "x-api-key: $BEEBLE_API_KEY" \
  -H "X-Beeble-Team-Id: ${BEEBLE_TEAM_ID:-}"

# Reuse headers and job_id from the submission example.
status_response = requests.get(
    f"https://api.beeble.ai/v1/product-jobs/{job_id}",
    headers=headers,
    timeout=30,
)
status_response.raise_for_status()
job = status_response.json()
print(job)

// Reuse headers and jobId from the submission example.
const statusResponse = await fetch(
  `https://api.beeble.ai/v1/product-jobs/${jobId}`,
  { headers, signal: AbortSignal.timeout(30_000) },
)
if (!statusResponse.ok) throw new Error(await statusResponse.text())
const job = await statusResponse.json()
console.log(job)

Example response (200, success; abbreviated): URLs are illustrative.

{
  "id": "dap_example",
  "product": "switchx",
  "model_id": "switchx-2.0",
  "status": "success",
  "outputs": {
    "render": "https://cdn.beeble.ai/.../render.png",
    "source": "https://cdn.beeble.ai/.../source.png",
    "alpha": null
  }
}

Once the job succeeds, download outputs.render:

RENDER_URL="https://cdn.beeble.ai/.../render.png" # Use outputs.render from your job.
curl --fail-with-body --output output.png "$RENDER_URL"

if job["status"] != "success":
    raise RuntimeError(f"Job is not successful: {job['status']}")
with requests.get(job["outputs"]["render"], stream=True, timeout=60) as download:
    download.raise_for_status()
    with open("output.png", "wb") as target:
        for chunk in download.iter_content(chunk_size=1024 * 1024):
            target.write(chunk)

import { writeFile } from "node:fs/promises"

if (job.status !== "success")
  throw new Error(`Job is not successful: ${job.status}`)
const download = await fetch(job.outputs.render, {
  signal: AbortSignal.timeout(60_000),
})
if (!download.ok) throw new Error(await download.text())
await writeFile("output.png", Buffer.from(await download.arrayBuffer()))

The example relights the whole frame with fill, so outputs.alpha is null. For foreground masks and video controls, see SwitchX.

Next steps

Billing & credits: estimate costs and set a spending cap.
Jobs & retries: automate polling and handle timeouts safely.
Webhooks: receive completion notifications.

Get started

Products

Core concepts

Integrations

Prerequisites

Submit your first job

Check Status & Download

Next steps

​Prerequisites

​Submit your first job

​Check Status & Download

​Next steps

Prerequisites

Submit your first job

Check Status & Download

Next steps