Skip to main content
POST
/
v1
/
switchx
/
generations
Start Generation
curl --request POST \
  --url https://api.beeble.ai/v1/switchx/generations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "source_uri": "<string>",
  "prompt": "<string>",
  "reference_image_uri": "<string>",
  "alpha_uri": "<string>",
  "alpha_keyframe_index": 12,
  "seed": 2147483647,
  "max_resolution": 720,
  "callback_url": "<string>",
  "idempotency_key": "<string>"
}
'
{
  "id": "<string>",
  "status": "<string>",
  "progress": 72,
  "generation_type": "<string>",
  "alpha_mode": "<string>",
  "output": {
    "render": "<string>",
    "source": "<string>",
    "alpha": "<string>"
  },
  "seed": 123,
  "error": "<string>",
  "created_at": "<string>",
  "modified_at": "<string>",
  "completed_at": "<string>",
  "webhook": {
    "status": "<string>",
    "attempts": 1,
    "last_error": "<string>"
  }
}

Authorizations

​
x-api-key
string
header
required

Your Developer API key.

Body

application/json

Request to create and start a SwitchX generation job.

​
generation_type
enum<string>
required

Output type: 'image' or 'video'

Available options:
image,
video
Example:

"video"

​
source_uri
string
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.

​
alpha_mode
enum<string>
required

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

Available options:
auto,
fill,
custom,
select
Example:

"select"

​
prompt
string | null

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.

Maximum string length: 2000
​
reference_image_uri
string | null

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_uri
string | null

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_index
integer | null

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.

Required range: x >= 0
Example:

12

​
seed
integer | null

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.

Required range: 0 <= x <= 4294967295
​
max_resolution
integer | null
default:1080

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

Example:

720

​
callback_url
string | null

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

​
idempotency_key
string | null

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.

Required string length: 1 - 256

Response

200 - application/json

Successful Response

Status response for a SwitchX job.

​
id
string
required

Job identifier (swx_...)

​
status
string
required

in_queue, processing, completed, or failed

​
progress
integer | null

Progress percentage (0-100)

Example:

72

​
generation_type
string | null

'image' or 'video'

​
alpha_mode
string | null

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

​
output
SwitchXOutputUrls · object

Output URLs (present when status is completed). URLs are signed and expire after 72 hours. Each call to this endpoint generates fresh signed URLs, so you can always re-fetch if a URL has expired.

​
seed
integer | null

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

​
error
string | null

Error message (present when status is failed)

​
created_at
string | null

ISO 8601 timestamp when the job was created

​
modified_at
string | null

ISO 8601 timestamp of the last status change

​
completed_at
string | null

ISO 8601 timestamp when the job completed or failed

​
webhook
WebhookStatus · object

Webhook delivery status (present only when a callback_url was provided)