fashn-logo
FASHNAI

Model Swap

Model Swap enables you to change the identity of fashion models in existing images while preserving clothing and outfit details exactly as they appear. Transform skin tone, facial features, and hair while maintaining the garments, pose, and styling perfectly intact.

Model Specifications
  • Model Name: model-swap
  • Processing Time: 10-12 seconds
  • Supported Resolution: up to 1.05MP

Request

Transform fashion model identity while preserving clothing by submitting the source image to the universal /v1/run endpoint:

POSThttps://api.fashn.ai/v1/run

Request Examples

curl -X POST https://api.fashn.ai/v1/run \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
           "model_name": "model-swap",
           "inputs": {
             "model_image": "https://example.com/fashion-model.jpg",
             "prompt": "Asian woman with blue hair"
           }
         }'

Response

Returns a prediction ID for status polling:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "error": null
}

Request Parameters

Required Parameters

model_image
Required
image URL | base64

Source fashion model image containing the clothing and pose to preserve. The model's identity (face, skin tone, hair) will be transformed while keeping the outfit exactly as shown.

Base64 Format

Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)

Optional Parameters

promptstring

Description of the desired model identity transformation. Specify ethnicity, facial features, hair color, and other physical characteristics.

Default: Empty string (Random identity change)

background_changeboolean

Controls whether the background should be modified according to the prompt or preserved from the original image. When enabled, include background descriptions in your prompt.

  • true – Background will be changed according to the prompt description
  • false – Original background will be preserved exactly as in the source image

Default: false

disable_prompt_enhancementboolean

Disable prompt enhancement. When true, the prompt will be used exactly as provided, or a default prompt will be used if no prompt is provided.

Default: false

seedinteger

Sets random operations to a fixed state. Use the same seed to reproduce results with the same inputs, or different seed to force different results.

Default: 42
Range: 0 to 2^32 - 1

lora_urlfile URL

URL to a FLUX-based LoRA weights file (.safetensors) for custom identity generation. When provided, the LoRA will be loaded and applied during generation to maintain consistent character appearance across generations.

LoRA Requirements
  • Architecture: Must be FLUX-compatible LoRA weights
  • Format: .safetensors file format only
  • File Size: Must be under 256MB

Example: https://example.com/custom_identity.safetensors

output_format'png' | 'jpeg'

Specifies the desired output image format.

-png: Delivers the highest quality image, ideal for use cases such as content creation where quality is paramount.
-jpeg: Provides a faster response with a slightly compressed image, more suitable for real-time applications.

Default: png

return_base64boolean

When set to true, the API will return the generated image as a base64-encoded string instead of a CDN URL. The base64 string will be prefixed according to the output_format (e.g., data:image/png;base64,... or data:image/jpeg;base64,...).

This option offers enhanced privacy as user-generated outputs are not stored on our servers when return_base64 is enabled.

Default: false

Response Polling

After submitting your request, poll the status endpoint using the returned prediction ID. See API Fundamentals for complete polling details.

Successful Response

When your model swap completes successfully, the status endpoint will return:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "completed",
  "output": [
    "https://cdn.fashn.ai/123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1/output_0.png"
  ],
  "error": null
}

The output array contains URLs to your processed images with the transformed model identity while preserving the original clothing and styling.

Runtime Errors

Model Swap may encounter the following model-specific errors during processing:

NameCauseSolution
ImageLoadErrorThe pipeline was unable to load the model image from the provided inputs.For Image URLs:
  • Ensure the URL is publicly accessible and not restricted by permissions.
  • Verify that the Content-Type header specifies the correct image format (e.g., image/jpeg, image/png).
For Base64-encoded images:
  • Prefix the string with data:image/format;base64, where format is the image type (e.g., jpeg, png).
LoRALoadErrorFailed to download or load the LoRA weights file from the provided URL.
  • Ensure the LoRA URL is publicly accessible and returns a valid .safetensors file.
  • Check that the file size is under 256MB.
  • Ensure the LoRA is compatible with the FLUX.1-dev model.
ThirdPartyErrorA third-party processor failed or refused to handle the request.Most likely caused by content restrictions enforced by supporting services (e.g., prompt enhancement). If that’s the case, try modifying your image inputs or disable prompt enhancement. If the issue persists across different inputs, contact support@fashn.ai with the prediction ID.
PipelineErrorAn unexpected error occurred during the execution of the pipeline.Retry the request (you will not be charged for failed attempts). If the issue persists, please reach out to us at support@fashn.ai and include the prediction ID from the failed attempt to help us locate and address the issue promptly.

The Error Object

{
  "error": {
    "name": "PipelineError",
    "message": "The error message"
  }
}

Example of an error when polling the /status endpoint:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "failed",
  "error": {
    "name": "ImageLoadError",
    "message": "Error loading model image: The URL's Content-Type is not an image. Content-Type: text/plain;charset=UTF-8"
  }
}

If you encounter an unrecognized error, please contact us at support@fashn.ai.

For detailed implementation guidance and best practices:

Previous

Model Variation

Next

Reframe

On this page

RequestRequest ExamplesResponseRequest ParametersRequired ParametersOptional ParametersResponse PollingSuccessful ResponseRuntime ErrorsThe Error ObjectRelated Guides