---
title: "Start Generation"
method: POST
path: "/v1/switchx/generations"
tags: ["switchx"]
---

# Start Generation

`POST /v1/switchx/generations`

Start a SwitchX compositing job.

## Request body

- CreateSwitchXRequest — Request to create and start a SwitchX generation job.
  - `generation_type` 'image' | 'video', required
  - `source_uri` string, required — URI of the source image or video. **Accepted URI types:** | Scheme | Description | |--------|-------------| | `beeble://uploads/{id}/{filename}` | From the [Uploads endpoint](/api-reference/uploads/create-upload-url) | | `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.
  - `prompt` string, 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_uri` string, nullable — URI of the reference image for style transfer. Accepts the same [URI types](#body-source-uri) 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_uri` string, nullable — URI of a custom alpha matte. Accepts the same [URI types](#body-source-uri) 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, 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.
  - `seed` integer, 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_resolution` integer, nullable — Maximum output resolution: 720 or 1080 (default: 1080)
  - `callback_url` string, nullable — HTTPS URL for webhook notification on completion or failure. See [Webhooks](/api/webhooks) for payload details.
  - `idempotency_key` string, 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.

## Response `200`

Successful Response

- SwitchXStatusResponse — Status response for a SwitchX job.
  - `id` string, required — Job identifier (swx_...)
  - `status` string, required — in_queue, processing, completed, or failed
  - `progress` integer, nullable — Progress percentage (0-100)
  - `generation_type` string, nullable — 'image' or 'video'
  - `alpha_mode` string, nullable — 'auto', 'fill', 'custom', or 'select'
  - `output` SwitchXOutputUrls — Signed URLs for SwitchX job outputs.
    - `render` string, nullable — Composited output URL
    - `source` string, nullable — Preprocessed source URL
    - `alpha` string, nullable — Alpha matte URL
  - `seed` integer, nullable — Random seed used for this generation (always present after job creation)
  - `error` string, nullable — Error message (present when status is failed)
  - `created_at` string, nullable — ISO 8601 timestamp when the job was created
  - `modified_at` string, nullable — ISO 8601 timestamp of the last status change
  - `completed_at` string, nullable — ISO 8601 timestamp when the job completed or failed
  - `webhook` WebhookStatus — Webhook delivery status for a generation job.
    - `status` string, nullable — 'pending', 'delivered', or 'failed'
    - `attempts` integer, nullable — Number of delivery attempts so far
    - `last_error` string, nullable — Error message from the last failed delivery attempt

---

[API](https://skmtc.dev/beeble/apis/beeble-developer-api.md) · [All operations](https://skmtc.dev/beeble/apis/beeble-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/beeble/beeble-developer-api/revisions/f35ce0de5d00/schema)