> ## Documentation Index > Fetch the complete documentation index at: https://developer.beeble.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Start Generation > Start a SwitchX compositing job. ## OpenAPI ````yaml https://api.beeble.ai/developer-api-docs/openapi.json post /v1/switchx/generations openapi: 3.1.0 info: title: Beeble Developer API description: API for SwitchX video-to-video compositing and media uploads. version: 1.0.0 servers: - url: https://api.beeble.ai description: Production security: - apiKeyAuth: [] paths: /v1/switchx/generations: post: tags: - switchx summary: Start Generation description: Start a SwitchX compositing job. operationId: create_switchx_job_v1_switchx_generations_post parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSwitchXRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SwitchXStatusResponse' components: schemas: CreateSwitchXRequest: properties: generation_type: $ref: '#/components/schemas/GenerationType' description: 'Output type: ''image'' or ''video''' examples: - video source_uri: type: string title: Source Uri description: >- 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: anyOf: - type: string maxLength: 2000 - type: 'null' title: Prompt description: >- 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: anyOf: - type: string - type: 'null' title: Reference Image Uri description: >- 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: $ref: '#/components/schemas/AlphaMode' description: '''auto'', ''fill'', ''custom'', or ''select''' examples: - select alpha_uri: anyOf: - type: string - type: 'null' title: Alpha Uri description: >- 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: anyOf: - type: integer minimum: 0 - type: 'null' title: Alpha Keyframe Index description: >- 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. examples: - 12 seed: anyOf: - type: integer maximum: 4294967295 minimum: 0 - type: 'null' title: Seed description: >- 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: anyOf: - type: integer - type: 'null' title: Max Resolution description: 'Maximum output resolution: 720 or 1080 (default: 1080)' default: 1080 examples: - 720 callback_url: anyOf: - type: string - type: 'null' title: Callback Url description: >- HTTPS URL for webhook notification on completion or failure. See [Webhooks](/api/webhooks) for payload details. idempotency_key: anyOf: - type: string maxLength: 256 minLength: 1 - type: 'null' title: Idempotency Key description: >- 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. type: object required: - generation_type - source_uri - alpha_mode title: CreateSwitchXRequest description: Request to create and start a SwitchX generation job. examples: - alpha_mode: auto generation_type: video max_resolution: 1080 prompt: cinematic relight, warm golden-hour key light source_uri: beeble://uploads/abc123/input.mp4 - alpha_keyframe_index: 12 alpha_mode: select alpha_uri: beeble://uploads/def456/keyframe.png generation_type: video prompt: studio softbox lighting source_uri: beeble://uploads/abc123/input.mp4 SwitchXStatusResponse: properties: id: type: string title: Id description: Job identifier (swx_...) status: type: string title: Status description: in_queue, processing, completed, or failed progress: anyOf: - type: integer - type: 'null' title: Progress description: Progress percentage (0-100) examples: - 72 generation_type: anyOf: - type: string - type: 'null' title: Generation Type description: '''image'' or ''video''' alpha_mode: anyOf: - type: string - type: 'null' title: Alpha Mode description: '''auto'', ''fill'', ''custom'', or ''select''' output: anyOf: - $ref: '#/components/schemas/SwitchXOutputUrls' - type: 'null' description: >- 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: anyOf: - type: integer - type: 'null' title: Seed description: >- Random seed used for this generation (always present after job creation) error: anyOf: - type: string - type: 'null' title: Error description: Error message (present when status is failed) created_at: anyOf: - type: string - type: 'null' title: Created At description: ISO 8601 timestamp when the job was created modified_at: anyOf: - type: string - type: 'null' title: Modified At description: ISO 8601 timestamp of the last status change completed_at: anyOf: - type: string - type: 'null' title: Completed At description: ISO 8601 timestamp when the job completed or failed webhook: anyOf: - $ref: '#/components/schemas/WebhookStatus' - type: 'null' description: >- Webhook delivery status (present only when a callback_url was provided) type: object required: - id - status title: SwitchXStatusResponse description: Status response for a SwitchX job. GenerationType: type: string enum: - image - video title: GenerationType AlphaMode: type: string enum: - auto - fill - custom - select title: AlphaMode SwitchXOutputUrls: properties: render: anyOf: - type: string - type: 'null' title: Render description: Composited output URL source: anyOf: - type: string - type: 'null' title: Source description: Preprocessed source URL alpha: anyOf: - type: string - type: 'null' title: Alpha description: Alpha matte URL type: object title: SwitchXOutputUrls description: Signed URLs for SwitchX job outputs. WebhookStatus: properties: status: anyOf: - type: string - type: 'null' title: Status description: '''pending'', ''delivered'', or ''failed''' attempts: anyOf: - type: integer - type: 'null' title: Attempts description: Number of delivery attempts so far examples: - 1 last_error: anyOf: - type: string - type: 'null' title: Last Error description: Error message from the last failed delivery attempt type: object title: WebhookStatus description: Webhook delivery status for a generation job. securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: Your [Developer API key](/api/authentication). ````