BEbeeble
switchx

Start Generation

Changed on

Start a SwitchX compositing job.

post/v1/switchx/generations

Request

  • Base URL
    https://api.beeble.ai
  • Auth
    API key in header x-api-key

Request body

billing_unit'usd' | 'credits' nullable

Defaults to USD for all keys. Set credits explicitly with an organization key. USD uses the key owner's Developer API account; credits use the bound organization pool.

generation_type'image' | 'video' required
source_uristring required

URI of the source image or video.

Accepted URI types:

SchemeDescription
beeble://uploads/{id}/{filename}From the Uploads endpoint
https://...External URL
data:{mime};base64,...Inline base64 (max 50 MB)

Accepted formats:

Generation typeFormats
imagePNG, JPEG, WebP
videoMP4, MOV (H.264 or HEVC). Max 240 frames.

Resolution: The source must not exceed 2,770,000 total pixels (width x height). Sources with extreme aspect ratios may be rejected.

promptstring nullable

Text description of desired output (max 2,000 chars).

At least one of prompt or reference_image_uri is required. You can provide both for more control over the output.

reference_image_uristring nullable

URI of the reference image for style transfer. Accepts the same URI types as source_uri.

At least one of reference_image_uri or prompt is required. You can provide both for more control over the output.

alpha_mode'auto' | 'fill' | 'custom' | 'select' required
alpha_uristring nullable

URI of a custom alpha matte. Accepts the same URI types as source_uri.

Required when alpha_mode is "custom" or "select".

  • select: Provide an alpha keyframe image (PNG/JPG grayscale) for a single reference frame. The AI propagates it across the video. By default the keyframe describes the first frame; set alpha_keyframe_index to use a different reference frame.
  • custom: Provide a full alpha matte matching the generation_type (image alpha for image generation, video alpha for video generation).

When using "auto" or "fill", the alpha is handled automatically and this field is ignored.

alpha_keyframe_indexinteger nullable

0-based index of the reference frame for alpha propagation when alpha_mode is "select" on a video.

The alpha keyframe supplied via alpha_uri describes the subject at this frame, and the AI propagates the matte across the rest of the video. Defaults to the first frame (0) when omitted.

Must be between 0 and frame_count - 1. Ignored for image generation and for the auto, fill, and custom modes.

seedinteger nullable

Random seed for reproducibility (0–4,294,967,295).

When omitted, a random seed is generated automatically so that identical requests produce different outputs. To reproduce an earlier result, pass the same seed value.

The seed used is always returned in the response.

Reproducibility note: Using the same seed with identical inputs produces visually consistent results suitable for iterative workflows and A/B comparisons. Due to the nature of GPU computation, outputs are near-identical rather than bit-for-bit exact — differences are imperceptible to the human eye.

max_resolutioninteger nullable

Maximum output resolution: 720 or 1080 (default: 1080)

callback_urlstring nullable

HTTPS URL for webhook notification on completion or failure. See Webhooks for payload details.

idempotency_keystring nullable

Idempotency key for safe retries.

If a job with the same key already exists for your account, the API returns the existing job's status instead of creating a duplicate.

Use a unique, deterministic key per logical request (e.g., your internal order ID). This prevents double-charges if your client retries due to network timeouts.

Example request

{
  "alpha_mode": "auto",
  "generation_type": "video",
  "max_resolution": 1080,
  "prompt": "cinematic relight, warm golden-hour key light",
  "source_uri": "beeble://uploads/abc123/input.mp4"
}

Response

Successful Response

organization_idstring nullable
billing_unit'usd' | 'credits'
credits_chargedinteger nullable
credit_billing_statestring nullable
idstring required

Job identifier (swx_...)

statusstring required

in_queue, processing, completed, or failed

progressinteger nullable

Progress percentage (0-100)

generation_typestring nullable

'image' or 'video'

alpha_modestring nullable

'auto', 'fill', 'custom', or 'select'

seedinteger nullable

Random seed used for this generation (always present after job creation)

errorstring nullable

Error message (present when status is failed)

created_atstring nullable

ISO 8601 timestamp when the job was created

modified_atstring nullable

ISO 8601 timestamp of the last status change

completed_atstring nullable

ISO 8601 timestamp when the job completed or failed

Example response

{
  "progress": 72,
  "webhook": {
    "attempts": 1
  }
}

Changes

  • 23d5ecf17bf7Revision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status