Billing & credits

Beeble Cloud credits

Product jobs use your organization’s Beeble Cloud credits—the same balance used in Beeble Cloud. Where applicable, charges also count toward the selected internal team’s budget. Personal credits are never a fallback. Product estimates and jobs default to billing_unit: "credits". You can omit this field or set it explicitly. USD is not supported on these endpoints; sending "usd" returns UNSUPPORTED_BILLING_UNIT.

Estimate before submitting

Request parameters, body, and response schema Call POST /v1/products/{product}/estimate with the same model and inputs you plan to submit. It validates the inputs and quotes the cost without creating a job or charging credits. No idempotency key is required. Estimates may download HTTPS media or decode data URIs and store files for validation. A separate submission may fetch the media again: keep presigned URLs valid and their contents unchanged through both calls. For a stable input that you control, upload the file first. Use a supported media URI for inputs.source and set BEEBLE_API_KEY. The examples use a Beeble upload URI; HTTPS and data URIs go in the same field. For internal teams, also set BEEBLE_TEAM_ID.

curl --fail-with-body https://api.beeble.ai/v1/products/switchx/estimate \
  -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",
    "inputs": {
      "source": "beeble://uploads/your-upload-id/source.mp4",
      "prompt": "Warm studio lighting",
      "alpha_mode": "fill"
    }
  }'

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/estimate",
    headers=headers,
    json={
        "model_id": "switchx-2.0",
        "inputs": {
            "source": "beeble://uploads/your-upload-id/source.mp4",
            "prompt": "Warm studio lighting",
            "alpha_mode": "fill",
        },
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())

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/estimate",
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      model_id: "switchx-2.0",
      inputs: {
        source: "beeble://uploads/your-upload-id/source.mp4",
        prompt: "Warm studio lighting",
        alpha_mode: "fill",
      },
    }),
    signal: AbortSignal.timeout(120_000),
  },
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())

Example response (200, abbreviated; amount is illustrative):

{
  "product": "switchx",
  "model_id": "switchx-2.0",
  "billing_unit": "credits",
  "estimated_credits": 100
}

Use the same organization, team, model, and inputs for the estimate and submission. The response includes estimated_credits and, where available, source metadata.

Set a per-job ceiling

Set max_credits to cap the charge, including zero to allow no charge. To use your estimate as the ceiling, copy estimated_credits into this field. If omitted, the server uses a current quote. An estimate reserves neither price nor credits. Submission quotes again and checks the measured cost against the ceiling before charging.

Charges and refunds

credits_charged reports the actual charge supplied by the product. A null value means no actual charge has been reported; it is not zero or an estimate. refunded reports the product’s refund state. A null value means the state is unreported. A failed job does not prove a refund has completed. SwitchX product jobs currently leave refunded as null, while their normal refund process still runs.

Track usage

API jobs appear alongside web usage in your organization’s Beeble Cloud usage totals. For a timed-out submission, follow safe retries before considering a new job.

Existing SwitchX generations with organization keys

/v1/switchx/generations retains its USD default, including for organization keys. Explicit billing_unit: "credits" charges the bound organization’s Beeble Cloud credits, without falling back to personal credits. USD uses the key owner’s Developer API billing account.If USD billing is unavailable or its balance is insufficient, a 402 response may advise submitting a new request with billing_unit: "credits" and a new idempotency key. The server never switches payment units itself. Changing the billing unit under an existing key returns 409.Legacy generation responses use organization_id, billing_unit, credits_charged, and credit_billing_state. Failed or cancelled credit jobs refund their original organization pool and team budget. allocation_pending means team budget restoration is retrying; manual requires support to reconcile an uncertain ledger operation. Poll the legacy job for the current state: a failure webhook does not confirm that its refund has finished. Product jobs use the separate refunded contract described above.

Get started

Products

Core concepts

Integrations

Beeble Cloud credits

Estimate before submitting

Set a per-job ceiling

Charges and refunds

Track usage

​Beeble Cloud credits

​Estimate before submitting

​Set a per-job ceiling

​Charges and refunds

​Track usage

Beeble Cloud credits

Estimate before submitting

Set a per-job ceiling

Charges and refunds

Track usage