---
title: "Create a new prediction"
method: POST
path: "/v1/run"
tags: ["Predictions"]
---

# Create a new prediction

`POST /v1/run`

Submit a prediction request for AI-powered fashion processing. Supports multiple model types including:
- Virtual try-on (tryon-v1.6)
- Model creation (model-create)
- Model variation (model-variation)
- Model swap (model-swap)
- Product to model (product-to-model)
- Face to model (face-to-model)
- Background operations (background-remove, background-change)
- Image reframing (reframe)
- Image to video (image-to-video)
- Image editing (edit)

All requests use the versioned format with model_name and inputs structure.

## Query parameters

- `webhook_url` string, uri

## Request body

- union
  - TryOnRequest
    - `model_name` 'tryon-v1.6', required — Virtual Try-On v1.6 enables realistic garment visualization using just a single photo of a person and a garment
    - `inputs` TryOnInputs, required
      - `model_image` string, required — Primary image of the person on whom the virtual try-on will be performed. Models Studio users can use their saved models by passing `saved:<model_name>`. Base64 images must include the proper prefix (e.g., `data:image/jpg;base64,<YOUR_BASE64>`)
      - `garment_image` string, required — Reference image of the clothing item to be tried on the `model_image`. Base64 images must include the proper prefix (e.g., `data:image/jpg;base64,<YOUR_BASE64>`)
      - `category` 'auto' | 'tops' | 'bottoms' | 'one-pieces' — Use `auto` to enable automatic classification of the garment type. For flat-lay or ghost mannequin images, the system detects the garment type automatically. For on-model images, full-body shots default to a full outfit swap. For focused shots (upper or lower body), the system selects the most likely garment type (tops or bottoms).
      - `segmentation_free` boolean — Direct garment fitting without clothing segmentation, enabling bulkier garment try-ons with improved preservation of body shape and skin texture. Set to `false` if original garments are not removed properly.
      - `moderation_level` 'conservative' | 'permissive' | 'none' — Sets the content moderation level for garment images. - `conservative` enforces stricter modesty standards suitable for culturally sensitive contexts. Blocks underwear, swimwear, and revealing outfits. - `permissive` allows swimwear, underwear, and revealing garments, while still blocking explicit nudity. - `none` disables all content moderation. **This technology is designed for ethical virtual try-on applications. Misuse—such as generating inappropriate imagery without consent—violates our Terms of Service. Setting moderation_level: none does not remove your responsibility for ethical and lawful use. Violations may result in service denial.**
      - `garment_photo_type` 'auto' | 'flat-lay' | 'model' — Specifies the type of garment photo to optimize internal parameters for better performance. `model` is for photos of garments on a model, `flat-lay` is for flat-lay or ghost mannequin images, and `auto` attempts to automatically detect the photo type.
      - `mode` 'performance' | 'balanced' | 'quality' — Specifies the mode of operation. - `performance` mode is faster but may compromise quality (5 seconds). - `balanced` mode is a perfect middle ground between speed and quality (8 seconds). - `quality` mode is slower, but delivers the highest quality results (12–17 seconds).
      - `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.
      - `num_samples` integer — Number of images to generate in a single run. Image generation has a random element in it, so trying multiple images at once increases the chances of getting a good result.
      - `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 like consumer virtual try-on experiences.
      - `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,...`). This option offers enhanced privacy as user-generated outputs are not stored on our servers when `return_base64` is enabled.
  - ProductToModelRequest
    - `model_name` 'product-to-model', required — 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)
    - `inputs` ProductToModelInputs, required
      - `product_image` string, required — URL or base64 encoded image of the product to be worn. Supports clothing, accessories, shoes, and other wearable fashion items. Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)
      - `model_image` string — 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. Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)
      - `image_prompt` string — Optional URL or base64 of an inspiration image to guide pose, environment, and lighting while keeping the final edit product-centric.
      - `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", "professional office setting" **Default:** None
      - `aspect_ratio` '1:1' | '2:3' | '3:4' | '4:5' | '5:4' | '4:3' | '3:2' | '16:9' | '9:16' — Desired aspect ratio for the output image. Only applies when `model_image` is not provided (standard product-to-model mode). When `model_image` is provided (try-on mode), this parameter is ignored and the output will match the `model_image`'s aspect ratio. **Default:** product_image's aspect ratio (standard mode only)
      - `resolution` '1k' | '4k' — Resolution setting for the output image.
      - `seed` integer — Seed for reproducible results. Use the same seed to reproduce results with the same inputs, or different seed to force different results. Must be between 0 and 2^32-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.
      - `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.
  - FaceToModelRequest
    - `model_name` 'face-to-model', required — 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.
    - `inputs` FaceToModelInputs, required
      - `face_image` string, required — 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. Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)
      - `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. **Default:** Empty string
      - `aspect_ratio` '1:1' | '4:5' | '3:4' | '2:3' | '9:16' — Desired aspect ratio for the output image. Only vertical ratios are supported. Images will always be extended downward to fit the aspect ratio. **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.
      - `output_format` 'png' | 'jpeg' — 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`
  - ModelCreateRequest
    - `model_name` 'model-create', required — Model creation endpoint
    - `inputs` ModelCreateInputs, required
      - `prompt` string, required — Prompt for the model image generation. Describes the desired fashion model, clothing, pose, and scene.
      - `aspect_ratio` '1:1' | '2:3' | '3:4' | '4:5' | '5:4' | '4:3' | '3:2' | '16:9' | '9:16' — Defines the width-to-height ratio of the generated image. This parameter controls the canvas dimensions for text-only generation. When image_reference is provided, the output inherits the reference image's aspect ratio and this parameter is ignored. **Supported Resolutions** Each aspect ratio corresponds to a specific resolution optimized for ~1MP output: | Aspect Ratio | Resolution | Use Case | |--------------|------------|----------| | 1:1 | 1024 × 1024 | Square format, social media | | 2:3 | 832 × 1248 | Portrait, fashion photography | | 3:4 | 880 × 1176 | Standard portrait | | 4:5 | 912 × 1144 | Instagram portrait | | 5:4 | 1144 × 912 | Landscape portrait | | 4:3 | 1176 × 880 | Traditional landscape | | 3:2 | 1176 × 784 | Wide landscape | | 16:9 | 1360 × 768 | Widescreen, banners | | 9:16 | 760 × 1360 | Vertical video format |
      - `image_reference` string — Optional reference image that guides the generation process. The model extracts structural information from this image to control the output composition. Processing Behavior: - Aspect Ratio: Output automatically matches the reference image's dimensions. - Guidance Type: Controlled by the reference_type parameter (pose or silhouette) - Image Processing: Automatically resized while preserving aspect ratio Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)
      - `reference_type` 'pose' | 'silhouette' — Type of reference to use when image_reference is provided. - `pose` matches the body position and stance from the reference image. - `silhouette` matches the outline and shape from the reference image. **Default is applied only if image_reference is provided**
      - `seed` integer — Random seed for reproducible results
      - `disable_prompt_enhancement` boolean — Disable prompt enhancement. When true, the prompt will be used as is, or a default prompt will be used if no prompt is provided.
      - `lora_url` string — URL to a FLUX-based LoRA weights file (.safetensors) for custom identity generation. When provided, the LoRA will be loaded and applied during generation to maintain consistent character appearance across generations. Must be FLUX-compatible LoRA weights in .safetensors format, under 256MB.
      - `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.
      - `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,...`). This option offers enhanced privacy as user-generated outputs are not stored on our servers when `return_base64` is enabled.
  - ModelVariationRequest
    - `model_name` 'model-variation', required — Model variation endpoint for creating variations from existing model images
    - `inputs` ModelVariationInputs, required
      - `model_image` string, required — Source fashion model image to create variations from. The variation will maintain the core composition while introducing controlled modifications. Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)
      - `variation_strength` 'subtle' | 'strong' — Controls the intensity of variations applied to the source image. - `subtle` - Minor adjustments that preserve most of the original characteristics while introducing small variations. - `strong` - More significant modifications that create noticeable differences while maintaining the core composition.
      - `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.
      - `lora_url` string — URL to a FLUX-based LoRA weights file (.safetensors) for custom identity generation. When provided, the LoRA will be loaded and applied during generation to maintain consistent character appearance across generations. Must be FLUX-compatible LoRA weights in .safetensors format, under 256MB.
      - `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.
      - `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,...`). This option offers enhanced privacy as user-generated outputs are not stored on our servers when `return_base64` is enabled.
  - ModelSwapRequest
    - `model_name` 'model-swap', required — Model swap endpoint for transforming model identity while preserving clothing and pose
    - `inputs` ModelSwapInputs, required
      - `model_image` string, required — 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. Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)
      - `prompt` string — Description of the desired model identity transformation. Specify ethnicity, facial features, hair color, and other physical characteristics. **Default: Empty string (Random identity change)**
      - `background_change` boolean — Controls whether the background should be modified according to the prompt or preserved from the original image. When enabled, include background descriptions in your prompt. - `true` - Background will be changed according to the prompt description. - `false` - Original background will be preserved exactly as in the source image.
      - `disable_prompt_enhancement` boolean — Disable prompt enhancement. When true, the prompt will be used exactly as provided, or a default prompt will be used if no prompt is provided.
      - `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.
      - `lora_url` string — URL to a FLUX-based LoRA weights file (.safetensors) for custom identity generation. When provided, the LoRA will be loaded and applied during generation to maintain consistent character appearance across generations. Must be FLUX-compatible LoRA weights in .safetensors format, under 256MB.
      - `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.
      - `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,...`). This option offers enhanced privacy as user-generated outputs are not stored on our servers when `return_base64` is enabled.
  - ReframeRequest
    - `model_name` 'reframe', required — Image reframing endpoint
    - `inputs` ReframeInputs, required
      - `image` string, required — Source image to extend or reframe. The AI will intelligently generate new content to expand the image based on the selected mode and parameters. Resolution Handling: Output resolution is limited to 1MP. If your image is already at or above this size, it will be downsampled so that, after any extensions are applied, the final result fits within the 1MP limit. Base64 Format: Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)
      - `mode` 'direction' | 'aspect_ratio' — Selects the reframing operation mode. - `direction` - Directed zoom-out: extend image in specific directions to reveal more content. - `aspect_ratio` - Canvas adjustment: transform image to match a target aspect ratio. **Note: direction mode requires target_direction, aspect_ratio mode requires target_aspect_ratio.**"
      - `target_direction` 'both' | 'down' | 'up' — Direction of image extension when using mode: 'direction'. This parameter is ignored when mode: 'aspect_ratio'. - `both` - Expand in both directions (zoom out effect). - `down` - Expand only downward (reveal lower content, e.g., show full body from upper body shot). - `up` - Expand only upward (reveal upper content, e.g., show face from headless shot).
      - `target_aspect_ratio` '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' — Target aspect ratio for the output canvas when using mode: 'aspect_ratio'. This parameter is ignored when mode: 'direction'. **Supported Aspect Ratios** Each aspect ratio corresponds to a specific resolution optimized for ~1MP output: | Aspect Ratio | Resolution | Use Case | |--------------|------------|----------| | 1:1 | 1024 × 1024 | Square format, social media | | 2:3 | 832 × 1248 | Portrait, fashion photography | | 3:2 | 1248 × 832 | Standard landscape | | 3:4 | 880 × 1176 | Standard portrait | | 4:3 | 1176 × 880 | Traditional landscape | | 4:5 | 912 × 1144 | Instagram portrait | | 5:4 | 1144 × 912 | Instagram landscape | | 9:16 | 760 × 1360 | Vertical video format | | 16:9 | 1360 × 760 | Horizontal video format |
      - `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.
      - `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.
      - `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,...`). This option offers enhanced privacy as user-generated outputs are not stored on our servers when `return_base64` is enabled.
  - BackgroundChangeRequest
    - `model_name` 'background-change', required — Background change endpoint
    - `inputs` BackgroundChangeInputs, required
      - `image` string, required — Source image containing the subject to preserve. The AI will automatically detect and separate the foreground subject from the background. Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)
      - `prompt` string, required — Description of the desired new background (e.g., 'beach sunset', 'modern office', 'forest clearing'). The AI generates a new background based on this description and harmonizes it with the preserved foreground subject.
      - `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.
      - `disable_prompt_enhancement` boolean — Disable prompt enhancement for the background description. When `true`, the background prompt will be used exactly as provided.
      - `output_format` 'png' | 'jpeg' — Specifies the 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.
      - `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,...`). This option offers enhanced privacy as user-generated outputs are not stored on our servers when `return_base64` is enabled.
  - BackgroundRemoveRequest
    - `model_name` 'background-remove', required — Background removal endpoint
    - `inputs` BackgroundRemoveInputs, required
      - `image` string, required — Source image to remove the background from. The AI will automatically detect the main subject and create a clean cutout with transparent background. Base64 images must include the proper prefix (e.g., data:image/jpg;base64,<YOUR_BASE64>)
      - `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.
  - ImageToVideoRequest
    - `model_name` 'image-to-video', required — Image to Video turns a single image into a short motion clip, with tasteful camera work and model movements tailored for fashion.
    - `inputs` ImageToVideoInputs, required
      - `image` string, required — Source image to animate into a short video. Base64 images must include the proper prefix (e.g., `data:image/jpg;base64,<YOUR_BASE64>`)
      - `prompt` string — Optional motion guidance. Detailed prompting is not recommended because motion is difficult to control precisely. For the best results, leave this field empty and allow the system to plan motion automatically. If you include guidance, keep it short and concrete (e.g., "raising hand to touch face").
      - `negative_prompt` string — Optional cues to avoid undesirable motion or framing.
      - `duration` 5 | 10 — Duration of the generated video in seconds.
      - `resolution` '480p' | '720p' | '1080p' — Target video resolution used by the internal video engine.
  - EditRequest
    - `model_name` 'edit', required — Versatile post-processing to restyle shots, adjust views, and fix details while preserving identity and product fidelity.
    - `inputs` EditInputs, required
      - `image` string, required — Source image to edit. The AI will apply the requested modifications based on your prompt while preserving the overall composition and identity of the image. Base64 images must include the proper prefix (e.g., `data:image/jpg;base64,<YOUR_BASE64>`)
      - `prompt` string, required — Natural language description of the edit to apply. Be specific about what you want to change. **Examples:** "change the dress to red", "add sunglasses", "make the background a beach sunset", "change the shirt to a floral pattern"
      - `image_context` string — Optional URL or base64 of a context image to guide the edit. This image provides additional visual context that influences how the edit is applied. Base64 images must include the proper prefix (e.g., `data:image/jpg;base64,<YOUR_BASE64>`)
      - `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.
      - `num_images` integer — Number of images to generate in a single run. Image generation has a random element in it, so trying multiple images at once increases the chances of getting a good result.
      - `resolution` '1k' | '4k' — Resolution setting for the output image.
      - `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.
      - `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,...`). This option offers enhanced privacy as user-generated outputs are not stored on our servers when `return_base64` is enabled.

## Response `200`

Prediction created successfully

- PredictionResponse
  - `id` string, required — Unique prediction identifier
  - `error` string, nullable, required — Error message if prediction failed to start

## Other responses

- `400` — Bad request - Invalid request format. Check request structure and required parameters.
- `401` — Unauthorized - Invalid/missing API key. Verify your API key in the Authorization header.
- `429` — Too many requests - Implement request throttling, wait for current requests to complete, or purchase more credits.
- `500` — Internal server error - Server error. Retry after delay, contact support if persistent.

## Changes

- **2025-12-18** `cea4763bf526` — 1 info
  - added the new optional request property `oneOf[#/components/schemas/EditRequest]/inputs/image_context`
- **2025-12-01** `c146ae092a9f` — 2 info
  - added `edit` mapping keys to the request discriminator
  - added `#/components/schemas/EditRequest` to the request body `oneOf` list
- **2025-10-15** `f51f241d9ad7` — 2 info
  - added `image-to-video` mapping keys to the request discriminator
  - added `#/components/schemas/ImageToVideoRequest` to the request body `oneOf` list
- **2025-10-08** `dca2c53b7e69` — 2 info
  - added the new optional request property `oneOf[#/components/schemas/ProductToModelRequest]/inputs/image_prompt`
  - added the new optional request property `oneOf[#/components/schemas/ProductToModelRequest]/inputs/resolution`
- **2025-09-19** `7d899619601b` — 1 breaking, 1 warning, 2 info
  - added the new required request property `oneOf[#/components/schemas/BackgroundChangeRequest]/inputs/prompt`
  - removed the request property `oneOf[#/components/schemas/BackgroundChangeRequest]/inputs/background_prompt`
  - added `face-to-model` mapping keys to the request discriminator
  - added `#/components/schemas/FaceToModelRequest` to the request body `oneOf` list

[Full history](https://skmtc.dev/fashn-ai/apis/fashn-api/changes/v1/run/post.md)

---

[API](https://skmtc.dev/fashn-ai/apis/fashn-api.md) · [All operations](https://skmtc.dev/fashn-ai/apis/fashn-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fashn-ai/apis/fashn-api/revisions/cea4763bf526?raw)