Start Generation
Start a SwitchX compositing job.
Request body
URI of the source image or video.
Accepted URI types:
| Scheme | Description |
|---|---|
| beeble://uploads/{id}/{filename} | From the Uploads endpoint |
| https://... | External URL |
| data:{mime};base64,... | Inline base64 (max 50 MB) |
Accepted formats:
| Generation type | Formats |
|---|---|
| image | PNG, JPEG, WebP |
| video | MP4, 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.
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.
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.
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.
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.
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.
Maximum output resolution: 720 or 1080 (default: 1080)
HTTPS URL for webhook notification on completion or failure. See Webhooks for payload details.
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
Job identifier (swx_...)
in_queue, processing, completed, or failed
Progress percentage (0-100)
'image' or 'video'
'auto', 'fill', 'custom', or 'select'
Random seed used for this generation (always present after job creation)
Error message (present when status is failed)
ISO 8601 timestamp when the job was created
ISO 8601 timestamp of the last status change
ISO 8601 timestamp when the job completed or failed
Example response
{
"progress": 72,
"webhook": {
"attempts": 1
}
}Changes
No recorded changes to this endpoint across all 1 revision of this API.