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.

For consistent photoshoots, an optional premium face reference capability lets you swap to a specific identity and achieve repeatable, campaign‑ready results across sets.

Model Specifications

Model Name: model-swap
Lifecycle: experimental
Processing Time: 10-12 seconds
Supported Resolution: up to 1.05MP
Credits: 1 per image (4 per image with face_reference)

Request

Transform fashion model identity while preserving clothing by submitting the source image (and optionally a face reference) to the universal /v1/run endpoint:

POST`https://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

`prompt`string

Text guidance for identity or scene adjustments. If omitted, the system generates an appropriate prompt based on image analysis.

Default: Empty string (automatic prompt)

`face_reference`image URL | base64

Optional reference image to guide identity. When provided, the pipeline refines the model swap so both the body and face are aligned with the reference.

Default: None

`face_reference_mode`'match_base' | 'match_reference'

Additional fine control for identity guidance when face_reference is provided.

-match_base keeps the original photo’s head angle, gaze, and expression while applying the reference identity.
-match_reference favors the reference face’s pose and expression for maximum resemblance.

Default: match_reference

`seed`integer

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

`num_images`integer

Number of images to generate per request. Must be between 1 and 4.

Default: 1

`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_base64`boolean

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:

Name	Cause	Solution
`ImageLoadError`	The pipeline was unable to load the model image or the face reference image from the provided inputs.	For image URLs: ensure the URL is publicly accessible and returns an image Content-Type (for example, image/jpeg or image/png). For base64: prefix the string with `data:image/<format>;base64,` and verify that the data is valid.
`ThirdPartyError`	A third-party processor failed or refused to handle the request.	Most likely caused by content restrictions enforced by supporting services. Modify inputs and retry. If the issue persists across different inputs, contact support@fashn.ai with the prediction ID.
`PipelineError`	An unexpected error occurred during the execution of the pipeline.	Retry the request. You will not be charged for failed attempts. If the issue persists, contact support@fashn.ai and include the prediction ID so we can investigate.

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:

Image Preprocessing Best Practices - Optimize your source images for identity transformation

Model Swap

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

Response

model_imageRequiredimage URL | base64

promptstring

face_referenceimage URL | base64

face_reference_mode'match_base' | 'match_reference'

seedinteger

num_imagesinteger

output_format'png' | 'jpeg'

return_base64boolean

On this page