Model Create

Model Create enables you to generate realistic fashion models with simple, intuitive prompts or reference images.

Model Specifications

Model Name: model-create
Lifecycle: experimental
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 fashion models by submitting your prompt and optional reference assets 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-create",
           "inputs": {
             "prompt": "Full body shot, woman wearing a white t-shirt and dark blue biker shorts"
           }
         }'

Response

Returns a prediction ID for status polling:

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

Request Parameters

Required Parameters

`prompt`
Required
string

Prompt for the model image generation. Describes the desired fashion model, clothing, pose, and scene.

Optional Parameters

`image_reference`image URL | base64

Optional image to guide composition and pose. The AI won't copy the exact details from the image, but will use it as inspiration.

You can control whether to copy just the pose or the exact silhouette using the prompt parameter with natural language.

Base64 Format

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

`aspect_ratio`string

Defines the width-to-height ratio of the generated image.

When image_reference is provided, the output inherits the reference image's aspect ratio. Supply an explicit aspect_ratio to override that default.

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

Default: 1:1

`face_reference`image URL | base64

Optional portrait image that locks in a specific identity across generations.

Only available when resolution is set to 1k.
Consumes 4 credits per image.
Adds roughly 20-30 seconds of processing time.

Use this to achieve model consistency across generations without training a custom checkpoint.

`face_reference_mode`'match_base' | 'match_reference'

Controls how the provided face_reference shapes pose and expression.

-match_base prioritizes the prompt and base generation, keeping the original pose while adapting the reference face to those instructions.
-match_reference aligns the generated model closely with the reference face’s pose, gaze, and expression for maximum resemblance.

Default: match_reference

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

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

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

Default: '1k'

`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. Each image consumes one credit (or four credits when face_reference is present).

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 returns the generated image as a base64 string instead of a CDN URL. The base64 output is prefixed according to output_format (e.g., data:image/png;base64,... or data:image/jpeg;base64,...).

Enables stricter privacy because images are never uploaded to our CDN and are only available for 60 minutes after completion.

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 creation 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 generated fashion model images based on your prompt and optional reference parameters.

Runtime Errors

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

Name Cause Solution

Name	Cause	Solution
`ImageLoadError`	The pipeline was unable to load the `image_reference` or `face_reference` 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).
`ThirdPartyError`	A third-party processor (captioning, safety, or upscaling) 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, 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.

ImageLoadError

The pipeline was unable to load the image_reference or face_reference 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).

ThirdPartyError A third-party processor (captioning, safety, or upscaling) 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, 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 reference 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 reference images

Model Create

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

Response

promptRequiredstring

image_referenceimage URL | base64

aspect_ratiostring

face_referenceimage URL | base64

face_reference_mode'match_base' | 'match_reference'

resolution'1k' | '4k'

seedinteger

num_imagesinteger

output_format'png' | 'jpeg'

return_base64boolean

On this page