Face to Model

The Face to Model endpoint transforms face images into try-on ready upper-body avatars. It converts cropped headshots or selfies into full upper-body representations that can be used in virtual try-on applications when full-body photos are not available, while preserving facial identity.

Model Specifications

Model Name: face-to-model
Lifecycle: experimental
Processing Time: 12 seconds
Output Formats: PNG, JPEG
Delivery Methods: URL or Base64 encoding
Credits: 1

Request

Transform face images into professional model shots by submitting the face image 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": "face-to-model",
           "inputs": {
             "face_image": "http://example.com/path/to/headshot.jpg",
             "output_format": "jpeg"
           }
         }'

Response

Returns a prediction ID for status polling:

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

Request Parameters

`face_image`
Required
image URL | base64

URL or base64 encoded image of the face to transform into an upper-body avatar. The AI will analyze facial features, hair, and skin tone to create a representation suitable for virtual try-on applications.

`prompt`string

Optional styling or body shape guidance for the avatar representation. Examples: "athletic build", "curvy figure", "slender frame".

If you don't provide a prompt, the body shape will be inferred from the face image.

`aspect_ratio`string

Desired aspect ratio for the output image. Only vertical ratios are supported. Images will always be extended downward to fit the aspect ratio.

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

Default: 2:3

`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

`output_format`string

Specifies the output image format.

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

Default: "jpeg"

`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 face-to-model avatar creation completes successfully, the status endpoint will return:

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

The images array contains URLs to your upper-body avatars with preserved facial identity, ready for virtual try-on applications.

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 face 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 face image.	Review your face image to ensure it complies with content policies. Explicit or inappropriate imagery is prohibited, particularly when involving human subjects. Ensure the face image shows an appropriate human subject for avatar creation. 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.
`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.
`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.

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 face 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

Face to Model

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

Response

face_imageRequiredimage URL | base64

promptstring

aspect_ratiostring

seedinteger

output_formatstring

return_base64boolean