# Model Create

Generate realistic fashion models using textual prompts or reference images

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

**Lifecycle:** [Experimental](/api-overview/model-lifecycle) · **Released:** August 11, 2025

## Request body

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

| Field        | Type   | Required | Description                                                                                       |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `model_name` | string | Yes      | Must be `model-create`.                                                                           |
| `inputs`     | object | Yes      | Contains the endpoint-specific parameters documented under [Input parameters](#input-parameters). |

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

## Request

Generate fashion models by submitting your prompt and optional reference assets to the universal `/v1/run` endpoint:

    #### Request examples

        ```bash
        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"
                   }
                 }'
        ```

        ```js
        fetch('https://api.fashn.ai/v1/run', {
          method: 'POST',
          body: JSON.stringify({
            model_name: "model-create",
            inputs: {
              prompt: "Full body shot, woman wearing a white t-shirt and dark blue biker shorts"
            }
          }),
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json',
          }
        });
        ```

        ```python
        import requests

        response = requests.post(
          "https://api.fashn.ai/v1/run",
          headers={
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json"
          },
          json={
            "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:

          **Example Response:**

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

## Input parameters

**prompt** (`string`) *required*

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

**image_reference** (`image URL | data URI`)

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.

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

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

- When face_reference is used, output resolution is capped at 2K regardless of the requested resolution tier.
- Adds `3` credits per image.
- Typically adds around `20` 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 | 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-create`, 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. Additional images consume more compute (and credits) and can increase processing time.

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

**Privacy benefit:** Outputs are available for up to 60 minutes instead of the standard three-day window. Request history contains only a `` 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](/api-overview/api-fundamentals#status-polling) for complete polling details.

### Successful response

When your model creation completes successfully, the status endpoint will return:

```json
{
  "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

Runtime errors for Model Create use the shared set in [Error Handling](/api-overview/error-handling#common-runtime-errors).

## Related guides

For detailed implementation guidance and best practices:

- **[Image Preprocessing Best Practices](/guides/image-preprocessing-best-practices)** - Optimize your reference images