Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Switchx Image To Image

Model id: beeble/switchx-image-to-image. SwitchX is an image-to-image compositing model by Beeble that replaces a scene element while preserving the original subject, with automatic subject detection

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

  • beeble/switchx-image-to-image

Model Overview

SwitchX is an image-to-image 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 for the AI/ML API yet, feel free to use our Quickstart guide.

API Schema

post
Body
modelstring · enumRequiredPossible values:
image_urlstring · uriRequired

URL of the source image to recomposite. Allowed formats: JPEG, PNG, WEBP. 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
post/v1/images/generations
curl --request POST \
  --url 'https://api.aimlapi.com/v1/images/generations' \
  --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{"model": "beeble/switchx-image-to-image", "image_url": "https://example.com/input.jpg", "prompt": "Describe what you want the model to generate."}'
200

Successful response.

{
  "data": [
    {
      "url": "https://cdn.aimlapi.com/generations/hedgehog/1749730923700-29fe35d2-4aef-4bc5-a911-6c39884d16a8.png",
      "b64_json": null
    }
  ],
  "meta": {
    "usage": {
      "credits_used": 120000,
      "usd_spent": 0.06
    }
  }
}

Quick Example

Let's generate a new image using the one from the flux/dev Quick Example as a reference — and make a simple change to it with a prompt.

Response
Reference Image
Generated Image

More generated images

"Add a crown to the T-rex's head."

"Add a couple of silver wings"

"Remove the dinosaur. Place a book and a bouquet of wildflowers in blue and pink tones on the lounge chair. Let a light foamy surf gently wash the bottom of the chair. Don't change anything else."

"Make the dinosaur sit on a lounge chair with its back to the camera, looking toward the water. The setting sun has almost disappeared below the horizon."

Example #2: Combine two images

This time, we’ll pass two images to the model: our dinosaur and a solid blue mug. We'll ask the model to place the dinosaur onto the mug as a print.

Our input images

Our chilling T-rex

Our blue mug

Response
"Place this image with the t-rex on this mug from the second image as a print. Make it look fit and natural."

Last updated

Was this helpful?