Skip to main content
POST
/
v1
/
switchx
/
generations
Start Generation
curl --request POST \
  --url https://api.modal.beeble.ai/v1/switchx/generations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "generation_type": "image",
  "source_uri": "<string>",
  "alpha_mode": "auto",
  "prompt": "<string>",
  "reference_image_uri": "<string>",
  "alpha_uri": "<string>",
  "seed": 2147483647,
  "max_resolution": 1080,
  "callback_url": "<string>",
  "idempotency_key": "<string>"
}
'
{
  "id": "<string>",
  "status": "<string>",
  "progress": 123,
  "generation_type": "<string>",
  "alpha_mode": "<string>",
  "output": {
    "render": "<string>",
    "source": "<string>",
    "alpha": "<string>"
  },
  "error": "<string>",
  "created_at": "<string>",
  "modified_at": "<string>",
  "completed_at": "<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
​
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
​
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 a first-frame alpha keyframe image (PNG/JPG grayscale). The AI propagates it across the video.
  • 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.

​
seed
integer | null

Reproducibility seed (0-4,294,967,295)

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

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

​
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)

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

​
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