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.

Lifecycle: Experimental · Released: August 13, 2025

Request body

Every call uses the universal POST /v1/run request body:

Field	Type	Required	Description
`model_name`	string	Yes	Must be `model-swap`.
`inputs`	object	Yes	Contains the endpoint-specific parameters documented under Input parameters.

Place all endpoint parameters inside inputs; they are not top-level request fields.

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
}

Input parameters

`model_image`
Required
image URL | data URI

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.

`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 | data URI

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. Using a face reference typically adds around 20 seconds to the processing time.

Default: Not set

`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

`resolution`'1k' | '2k' | '4k'

Output resolution tier. '1k' produces ~1 megapixel output, '2k' ~4 megapixels, and '4k' ~16 megapixels. Exact output dimensions depend on this tier and the image aspect ratio.

Default: 1k

`generation_mode`'fast' | 'balanced' | 'quality'

Sets the generation quality level. 'quality' produces the most detailed and realistic output but takes longer to process and costs more credits. 'fast' prioritizes speed and lower cost. If omitted, FASHN selects generation_mode automatically. For model-swap, omitted generation_mode is currently billed as 'fast' at 1k and as 'balanced' at 2k or 4k.

`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,...).

Privacy benefit: Outputs are available for up to 60 minutes instead of the standard three-day window. Request history contains only a <base64> placeholder.

Default: false

Technical limitations

Requirement	Limit
Image file size	30 MiB per image
Minimum dimensions	15 × 15 px
Aspect ratio	1:16 to 16:1

Inputs outside these limits fail with InputValidationError. The output resolution does not change the input limits.

Credit cost

`generation_mode` \ `resolution`	`1k`	`2k`	`4k`
`fast`	1	2	3
`balanced`	2	3	4
`quality`	3	4	5

Additional pricing rules:

face_reference adds +3 credits per output image.
num_images multiplies the total cost by the number of outputs requested.
If generation_mode is omitted, automatic pricing applies.

Processing time

Processing time depends on both resolution and generation_mode. The fastest configuration (fast + 1k) typically completes in around 10 seconds, balanced at 2k finishes in around 25 seconds, and the most intensive combination (quality + 4k) typically takes around 55 seconds. Using face_reference typically adds around 20 seconds on top of any configuration. Actual latency may vary with current server load.

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

Runtime errors for Model Swap use the shared set in Error Handling.

For detailed implementation guidance and best practices:

Prompting in FASHN ↗ - Learn how to write effective prompts for best results
Image Preprocessing Best Practices - Optimize your source images for identity transformation

Model Swap

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

Response

model_imageRequiredimage URL | data URI

promptstring

face_referenceimage URL | data URI

face_reference_mode'match_base' | 'match_reference'

resolution'1k' | '2k' | '4k'

generation_mode'fast' | 'balanced' | 'quality'

seedinteger

num_imagesinteger

output_format'png' | 'jpeg'

return_base64boolean

On this page