Product to Model

Powered by best-in-class image editing AI, the Product to Model endpoint transforms product images into people wearing those products. It supports dual-mode operation: standard product-to-model (generates new person) and try-on mode (adds product to existing person).

This endpoint is designed specifically for wearable fashion items such as clothing, shoes, hats, jewelry, bags, and accessories.

Model Specifications

Model Name: product-to-model
Lifecycle: preview
Dual-Mode Operation: Product-only or Product + Model images
Processing Time: 12 seconds
Output Formats: PNG, JPEG
Delivery Methods: URL or Base64 encoding
Credits: 1 per image (4 per image with face_reference)

Request

Generate product-to-model images by submitting your product and optional model images 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": "product-to-model",
           "inputs": {
             "product_image": "http://example.com/path/to/product.jpg",
             "model_image": "http://example.com/path/to/person.jpg",
             "prompt": "professional office setting",
             "output_format": "png",
             "return_base64": false
           }
         }'

Response

Returns a prediction ID for status polling:

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

Request Parameters

`product_image`
Required
image URL | base64

URL or base64 encoded image of the product to be worn. Supports clothing, accessories, shoes, and other wearable fashion items.

`image_prompt`image URL | base64

Optional URL or base64 encoded inspiration image that guides pose, environment, and lighting while keeping the product centered in the final output.

Default: None

`model_image`image URL | base64

URL or base64 encoded image of the person to wear the product. When provided, enables try-on mode. When omitted, generates a new person wearing the product.

Cannot be combined with other image inputs (image_prompt, face_reference, or background_reference).

Default: None

`face_reference`image URL | base64

Optional face identity reference to guide who the generated person should look like. When provided, the pipeline refines identity to match the reference while keeping product fidelity.

Default: None

`face_reference_mode`'match_base' | 'match_reference'

Controls how the identity from face_reference influences pose and expression.

-match_reference favors the reference face’s pose and expression for maximum resemblance.

-match_base gives more weight to the prompt (or system default prompt if omitted) when generating the person's pose and expression.

Default: match_reference

`prompt`string

Additional instructions for person appearance (when model_image is not provided), styling preferences or background.

Examples: "man with tattoos", "tucked-in", "open jacket", "rolled-up sleeves", "studio background".

Default: None

`aspect_ratio`string

Desired aspect ratio for the output image. If omitted, the generation inherits the aspect ratio from the most specific image supplied (model_image → background_reference → image_prompt → product_image). Provide an explicit ratio to override that default even when using these image references.

Supported ratios: "1:1", "3:4", "4:3", "9:16", "16:9", "2:3", "3:2", "4:5", "5:4"

Default: Aspect ratio of the most specific image supplied

`resolution`string

Chooses the generation profile. '1k' produces precise, instruction-following results suited for consistent catalog imagery. '4k' unlocks creative, ultra high-definition renders with richer product detail but slightly less control over pose and styling.

Supported values: '1k', '4k'

Default: '1k'

`background_reference`image URL | base64

Background image used as the backdrop for generation. Ensures location consistency across generations. If a person appears in the image, they will be ignored and only the background will be used.

Default: None

`seed`integer

Seed for reproducible results. Must be between 0 and 2^32-1.

Default: 42

`num_images`integer

Number of images to generate in a single request. Must be between 1 and 4. Additional images consume more compute (and credits) and can increase processing time.

Default: 1

`output_format`string

Output image format.

"png" - PNG format, original quality
"jpeg" - JPEG format, smaller file size

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 data:image/png;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 product-to-model generation 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
}

Runtime Errors

If an error occurs during inference (while running the model), the API will return a 200 status code with a prediction status: failed. Additionally, an error object will be included under the error key in the response.

Name	Cause	Solution
`ImageLoadError`	The pipeline was unable to load the product image or 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).
`ContentModerationError`	Prohibited content detected in the provided product or model image. Content moderation is more sensitive when `model_image` contains an actual person (virtual try-on mode).	Review your product and model images to ensure they comply with content policies. Explicit or inappropriate imagery is prohibited, particularly when involving real people. Product photo generation without `model_image` provided operates under more permissive content policies. Rephrasing an instruction with more considerate fashion terminology can often resolve the issue. If you believe your content was incorrectly flagged, 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, 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.
`ThirdPartyError`	A third-party processor failed or refused to handle the request.	FASHN AI relies on external providers for tasks like captioning, moderation, and compute. These services can fail, be unavailable, or experience heavy load. Please retry, and if the issue persists, contact support@fashn.ai.

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 product 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.

Image Preprocessing Best Practices - Optimize your input images for better results
Data Retention & Privacy - Understand how FASHN handles your data

Product to Model

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

Response

product_imageRequiredimage URL | base64

image_promptimage URL | base64

model_imageimage URL | base64

face_referenceimage URL | base64

face_reference_mode'match_base' | 'match_reference'

promptstring

aspect_ratiostring

resolutionstring

background_referenceimage URL | base64

seedinteger

num_imagesinteger

output_formatstring

return_base64boolean

On this page

POST`https://api.fashn.ai/v1/run`

`product_image`
Required
image URL | base64

`image_prompt`image URL | base64

`model_image`image URL | base64

`face_reference`image URL | base64

`face_reference_mode`'match_base' | 'match_reference'

`prompt`string

`aspect_ratio`string

`resolution`string

`background_reference`image URL | base64

`seed`integer

`num_images`integer

`output_format`string

`return_base64`boolean