Switchx Video To Video

This documentation is valid for the following list of our models:

• beeble/switchx-video-to-video

Try in Playground

Model Overview

SwitchX is a video-to-video compositing model by Beeble that replaces a scene element while preserving the original subject, with automatic subject detection and seamless relighting to match a reference image. Does not support tools/function calling.

Setup your API Key

If you don't have an API key yet, use our Quickstart guide.

How to Make a Call

Step-by-Step Instructions

Generating a video involves sequentially calling two endpoints:

• Create and submit a video generation task. The response contains a generation ID.

• Poll the retrieval endpoint with that generation ID until the status is completed.

API Schemas

Create a video generation task and send it to the server

post

Body

application/json

modelstring · enumRequiredPossible values:

video_urlstring · uriRequired

URL of the source video to recomposite. Allowed formats: MP4, MOV (H.264 or HEVC), up to 240 frames. Source must not exceed 2,770,000 total pixels.

alpha_urlstring · uriOptional

URL of the alpha mask. Required when alpha_mode is "custom" or "select"; ignored for "auto" and "fill". A mask video for video-to-video, a mask image for image-to-image.

reference_image_urlstring · uriOptional

URL of the reference image defining the target look and lighting for the replaced region. Allowed formats: JPEG, PNG, WEBP. At least one of reference_image_url or prompt must be provided.

alpha_modestring · enumOptional

Subject masking strategy: "auto" (AI auto-detects the subject), "fill" (no masking), "select" (propagate a mask from one keyframe), or "custom" (frame-by-frame mask supplied via alpha_url). Defaults to "auto".

Default: autoPossible values:

max_resolutioninteger · enumOptional

Maximum output resolution (longer side) in pixels: 720 or 1080. Defaults to 1080. 1080 costs more than 720.

Default: 1080Possible values:

alpha_keyframe_indexintegerOptional

Frame index (0-based) whose mask is propagated when alpha_mode is "select" on a video. Defaults to the first frame. Ignored for image generation and for the auto, fill, and custom modes.

seedinteger · max: 4294967295Optional

Random seed (0–4294967295) for reproducibility. Omit for a random seed. The seed used is always returned in the response.

promptstring · max: 2000Optional

Text description of the desired output to guide the generation (max 2000 characters). At least one of prompt or reference_image_url must be provided.

Responses

200

Successful response.

application/json

idstringRequired

The ID of the generated video.

Example: 60ac7c34-3224-4b14-8e7d-0aa0db708325

statusstring · enumRequired

The current status of the generation task.

Example: completedPossible values:

post/v2/video/generations

cURLJavaScriptPython

curl --request POST \
  --url 'https://api.aimlapi.com/v2/video/generations' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{"model": "beeble/switchx-video-to-video", "video_url": "https://example.com/input.jpg", "prompt": "Describe what you want the model to generate."}'

200

Successful response.

{
  "id": "60ac7c34-3224-4b14-8e7d-0aa0db708325",
  "status": "completed",
  "video": {
    "url": "https://cdn.aimlapi.com/generations/hedgehog/1759866285599-0cdfb138-c03a-49d4-a601-4f6413e27b15.mp4"
  },
  "error": {
    "name": "text",
    "message": "text"
  },
  "meta": {
    "usage": {
      "credits_used": 120000,
      "usd_spent": 0.06
    }
  }
}

Retrieve the generated video from the server

Poll this endpoint with the generation_id returned by the submit request. When the status is completed, the response includes the generated video URL.

get

Authorizations

access-token

AuthorizationstringRequired

Bearer key

Query parameters

generation_idstringRequiredExample: <REPLACE_WITH_YOUR_GENERATION_ID>

Responses

200Success

application/json

idstringRequired

The ID of the generated video.

Example: 60ac7c34-3224-4b14-8e7d-0aa0db708325

statusstring · enumRequired

The current status of the generation task.

Example: completedPossible values:

get/v2/video/generations

cURLJavaScriptPython

curl -L \
  --request GET \
  --url 'https://api.aimlapi.com/v2/video/generations?generation_id=<REPLACE_WITH_YOUR_GENERATION_ID>' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>'

200Success

{
  "id": "60ac7c34-3224-4b14-8e7d-0aa0db708325",
  "status": "completed",
  "video": {
    "url": "https://cdn.aimlapi.com/generations/hedgehog/1759866285599-0cdfb138-c03a-49d4-a601-4f6413e27b15.mp4"
  },
  "error": {
    "name": "text",
    "message": "text"
  },
  "meta": {
    "usage": {
      "credits_used": 120000
    }
  }
}

Code Example

The examples submit a generation task and poll every 15 seconds until the final result is available.

Python

import requests
import time

api_key = "<YOUR_AIMLAPI_KEY>"
url = "https://api.aimlapi.com/v2/video/generations"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

generation = requests.post(url, headers=headers, json={'model': 'beeble/switchx-video-to-video', 'video_url': 'https://example.com/input.jpg', 'prompt': 'Describe what you want the model to generate.'})
generation.raise_for_status()
generation_id = generation.json()["id"]

while True:
    result = requests.get(
        url,
        headers=headers,
        params={"generation_id": generation_id},
    )
    result.raise_for_status()
    data = result.json()
    if data.get("status") not in ("queued", "generating"):
        print(data)
        break
    time.sleep(15)

JavaScript

Response

{
  "id": "60ac7c34-3224-4b14-8e7d-0aa0db708325",
  "status": "completed",
  "video": {
    "url": "https://cdn.aimlapi.com/generations/hedgehog/1759866285599-0cdfb138-c03a-49d4-a601-4f6413e27b15.mp4"
  },
  "error": {
    "name": "<name>",
    "message": "<message>"
  },
  "meta": {
    "usage": {
      "credits_used": 120000,
      "usd_spent": 0.06
    }
  }
}