VFX Passes

Product ID: vfx_passes · Billing: Beeble Cloud credits Turn an image or video into passes you can use separately for relighting, background replacement, and compositing. VFX Passes uses SwitchLight 3.0; the API model ID is switchlight-3. The VFX Pass Generator product guide shows how the passes work together in a VFX workflow.

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/vfx_passes/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/vfx_passes/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/vfx_passes/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

Pass	Use it for
Base Color	Surface color separated from lighting.
Normal	Surface orientation for relighting.
Roughness, Specular, Metallic	Material response to light.
Alpha	Foreground opacity for background replacement.
Depth	Depth-based compositing and 3D integration.

The completed response below shows the JSON field names for these passes.

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": "switchlight-3",
  "billing_unit": "credits",
  "idempotency_key": "vfx_passes-example-001",
  "inputs": {
    "source": "beeble://uploads/your-upload-id/source.png"
  }
}

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

curl --fail-with-body https://api.beeble.ai/v1/products/vfx_passes/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/vfx_passes/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/vfx_passes/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 source metadata before estimating or submitting; you can omit media type, frame count, frame rate, and duration. See Billing & credits for spending caps and refunds.

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": "vfx_passes",
  "status": "success",
  "outputs": {
    "basecolor": {
      "png": "https://cdn.beeble.ai/example/basecolor.png?signed-parameters"
    },
    "normal": {
      "png": "https://cdn.beeble.ai/example/normal.png?signed-parameters"
    },
    "roughness": {
      "png": "https://cdn.beeble.ai/example/roughness.png?signed-parameters"
    },
    "specular": {
      "png": "https://cdn.beeble.ai/example/specular.png?signed-parameters"
    },
    "metallic": {
      "png": "https://cdn.beeble.ai/example/metallic.png?signed-parameters"
    },
    "alpha": {
      "png": "https://cdn.beeble.ai/example/alpha.png?signed-parameters"
    },
    "depth": {
      "png": "https://cdn.beeble.ai/example/depth.png?signed-parameters",
      "exr": "https://cdn.beeble.ai/example/depth.exr?signed-parameters"
    },
    "all": "https://cdn.beeble.ai/example/all-passes.zip?signed-parameters"
  }
}

For images, download a pass such as outputs.basecolor.png, or outputs.all for the archive. Video jobs return per-pass mp4 and sequence archives; outputs.all contains mp4 and png archive URLs.

Get started

Products

Core concepts

Integrations

Before you start

Models and inputs

Submit a job

Results and constraints

Completed response

​Before you start

​Models and inputs

​Submit a job

​Results and constraints

​Completed response

Before you start

Models and inputs

Submit a job

Results and constraints

Completed response