---
title: "Virtual try-on API: request, settings and credits | Herofab"
description: "Virtual try-on API reference: one POST /api/v1/jobs request, 8 inputs, 14 settings, 5 credits per image. Examples in cURL, Node.js and Python."
url: https://herofab.app/api/virtual-try-on
language: en
updated: 2026-11-17
---

# Virtual try-on API

The Herofab Virtual try-on API puts a garment, bag, hat, pair of shoes, pair of glasses or piece of jewelry on a model: send POST /api/v1/jobs with "tool": "apparel\_tryon" and the photo's asset id. Each image costs 5 credits ($0.20 to $0.60 before tax), and the finished image is reported by polling or by a signed job.succeeded webhook.

- tool: apparel\_tryon
- 5 credits per image
- 8 input roles
- 14 settings

Inputs, settings and allowed values: Herofab OpenAPI document ([app.herofab.app/api/v1/openapi.json](https://app.herofab.app/api/v1/openapi.json)), read 3 November 2026. Labels and upload tips: the Herofab app.

![Model in a black satin slip midi dress with an open back, holding a champagne coupe on a café terrace](https://herofab.app/img/ex/mohair-ava-1100.webp)

Herofab campaign image · AI-generated

## What the Virtual try-on API does

The garment can be photographed on a hanger, laid flat, on a mannequin or worn; bags, hats, shoes, glasses and jewelry go in the same garment slot. garment\_type is the only required setting: it tells the model where the product is worn, and garment\_category narrows it to one of 47 product types. A back photo enables the back view, outfit slots dress the rest of the look in your own pieces, and a photo of a real person can replace the generated model when consent is recorded in the request.

## Create the job

Upload the photo with POST /api/v1/assets first and put the returned id where ASSET\_ID stands.

```
curl https://app.herofab.app/api/v1/jobs \
  -H "Authorization: Bearer $HEROFAB_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  --json '{
    "tool": "apparel_tryon",
    "inputs": {
      "garment": "ASSET_ID"
    },
    "params": {
      "garment_type": "one_piece",
      "garment_category": "dress",
      "pose": "walking",
      "background": "studio_white",
      "aspect_ratio": "3:4"
    }
  }'
```

[API overview: upload, poll, download](https://herofab.app/api) · [Webhooks](https://herofab.app/api/webhooks)

## What to upload

Each input is an asset id. The upload tips are the ones the Herofab app shows next to each slot.

| Role | Required | What to upload |
| --- | --- | --- |
| `garment` Product image | Required | One item — a garment, bag, hat, shoes, glasses or jewelry — fully visible and shot straight on: flat lay, hanger, mannequin or worn; shoes, glasses and jewelry on a plain surface. Avoid folded, cropped or overlapping items. |
| `background_image` Background image | Optional | The scene to place the model in. A sharp, uncluttered photo works best. |
| `garment_back` Product · back view | Optional | The back of the same item, photographed the same way as the front. |
| `garment_detail` Product · detail close-up | Optional | A close-up of the fabric, print, buckle or zipper, so small details stay accurate. |
| `model` Model image | Optional | One person facing the camera, arms away from the torso, in even light. Avoid sunglasses, bags or anything covering the body. |
| `outfit_bottom` Outfit · bottom | Optional | Trousers, a skirt or shorts to style with your product. Shot flat or on a hanger, fully visible. |
| `outfit_shoes` Outfit · shoes | Optional | The shoes the model should wear with your product. A clear side or front shot of the pair. |
| `outfit_top` Outfit · top | Optional | A top to style with your product, e.g. your own brand's shirt. Shot flat or on a hanger, fully visible. |

## Every setting and its values

Settings go in params; a value outside the list is refused with 422.

| Setting | Allowed values | Default |
| --- | --- | --- |
| `garment_type` Product type | `top`, `bottom`, `one_piece` One-piece, `bag`, `headwear` Hat / headwear, `jewelry`, `footwear` Shoes, `eyewear` Glasses | none — required |
| `aspect_ratio` Aspect ratio | `1:1`, `3:4`, `4:5`, `2:3`, `9:16`, `4:3`, `16:9` | `3:4` |
| `background` Background | `studio_white` Studio · white, `studio_grey` Studio · grey, `outdoor`, `lifestyle`, `seaside_rocks`, `wooden_pier`, `city_street`, `whitewashed_village` Mediterranean village, `cafe_terrace` Café terrace, `garden`, `keep` Keep as is, `custom` My own image | `studio_white` |
| `expression` Expression | `neutral`, `smile` | `neutral` |
| `garment_category` Product category | `unspecified`, `abaya`, `backpack`, `beanie`, `blazer`, `blouse`, `boots`, `bracelet`, `brimmed_hat`, `bucket_hat`, `cap`, `cardigan`, `clutch`, `coat`, `crossbody_bag`, `dress`, `earrings`, `eyeglasses`, `flats`, `handbag`, `heels`, `hoodie`, `jacket`, `jeans`, `jumpsuit`, `knitwear` Knitwear / sweater, `leggings`, `loafers`, `necklace`, `ring`, `sandals`, `shirt`, `shorts`, `shoulder_bag`, `skirt`, `sneakers`, `sportswear` Sportswear set, `suit`, `sunglasses`, `sweatshirt`, `t_shirt` T-shirt, `tote_bag`, `tracksuit_bottoms`, `trousers`, `tunic`, `vest` | `unspecified` |
| `gender` Gender | `unspecified`, `female`, `male` | `unspecified` |
| `light` Light | `scene_default` Scene's own light, `morning`, `golden_hour`, `overcast` | `scene_default` |
| `marketplace` Marketplace size | `none`, `amazon` 1,600 × 1,600 px, `ebay` 1,600 × 1,600 px, `etsy` 2,000 × 2,000 px, `hepsiburada`, `shopify` 2,048 × 2,048 px, `trendyol` 1,200 × 1,800 px | `none` |
| `model_consent` Consent | `true`, `false` | `false` |
| `pose` Pose | `standing_front` Standing · front, `standing_three_quarter` Standing · three-quarter, `walking`, `hands_on_hips`, `hands_in_pockets`, `arms_crossed`, `leaning`, `sitting`, `looking_away`, `close_up` Close-up | `standing_front` |
| `resolution` Resolution | `2k`, `4k` | `2k` |
| `size` Size | `XS`, `S`, `M`, `L`, `XL`, `XXL` | `M` |
| `styling` Complete the look | `plain`, `accessorized` With accessories | `plain` |
| `view` View | `front`, `front_back` Front + back in one image, `back` | `front` |

### Rules between inputs and settings

- inputs.background\_image is used only when params.background is "custom", and that value needs it
- a photo of a real person in inputs.model needs params.model\_consent = "true"; a saved model (mannequin\_id) or a model generated earlier in the same chain does not
- params.view = "back" needs inputs.garment\_back

## The app's workflow cards as API settings

The Workflows page of the Herofab app opens this tool with these fixed settings.

| Workflow card | Product families | params |
| --- | --- | --- |
| Show it on a model | Jewelry | `{"garment_type":"jewelry"}` |
| Close-up on a model | Jewelry | `{"garment_type":"jewelry","pose":"close_up"}` |
| Show it on a model | Clothing | `{"garment_type":"top"}` |
| Front and back on a model | Clothing | `{"garment_type":"top","view":"front_back"}` |
| On a model in the city | Clothing | `{"garment_type":"top","background":"city_street"}` |
| Show it on a model | Footwear | `{"garment_type":"footwear"}` |
| Show it on a model | Bags | `{"garment_type":"bag"}` |
| Show it on a model | Eyewear | `{"garment_type":"eyewear"}` |

## One call, one image per value

POST /api/v1/batches with vary opens one job per value of pose. This request reserves 20 credits (4 × 5 credits).

```
curl https://app.herofab.app/api/v1/batches \
  -H "Authorization: Bearer $HEROFAB_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  --json '{
    "tool": "apparel_tryon",
    "inputs": {
      "garment": "ASSET_ID"
    },
    "params": {
      "garment_type": "one_piece",
      "garment_category": "dress",
      "background": "studio_white",
      "aspect_ratio": "3:4"
    },
    "vary": {
      "pose": [
        "standing_front",
        "walking",
        "hands_on_hips",
        "sitting"
      ]
    }
  }'
```

## Feed the result into the next tool

Two steps in one POST /api/v1/chains request; input\_role names where this tool's output goes. This chain reserves 9 credits.

```
curl https://app.herofab.app/api/v1/chains \
  -H "Authorization: Bearer $HEROFAB_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  --json '{
    "steps": [
      {
        "tool": "apparel_tryon",
        "inputs": {
          "garment": "ASSET_ID"
        },
        "params": {
          "garment_type": "one_piece",
          "garment_category": "dress",
          "background": "studio_white",
          "aspect_ratio": "3:4"
        }
      },
      {
        "tool": "reframe",
        "input_role": "source",
        "params": {
          "aspect_ratio": "9:16"
        }
      }
    ]
  }'
```

## What a request costs

5 credits per image. One credit costs $0.04 to $0.12 before tax depending on the plan or credit pack, so one image costs $0.20 to $0.60 before tax. resolution "4k" adds 1 credit.

[Credit costs of every tool](https://herofab.app/credits) · [Pricing](https://herofab.app/pricing)

## Where this image type is not accepted

These marketplaces rule out the image type this tool makes in their own published rules:

[Miinto](https://herofab.app/guides/miinto-image-requirements)

## Virtual try-on API questions

**How much does the Virtual try-on API cost?**

5 credits per image ($0.20 to $0.60 before tax), the same as in the app. resolution "4k" adds 1 credit.

**How do I get the front and the back of the same garment on a model?**

Upload the back photo as inputs.garment\_back. view "front\_back" puts both sides in one image; a batch with vary {"view": \["front", "back"\]} makes two separate images of the same model.

**Can my own model wear the product?**

Yes. Upload the person as inputs.model and send params.model\_consent "true"; without it the job is refused. A model created with model\_maker earlier in the same chain needs no consent value, because no real person is involved.

Related

[Virtual try-on in the app](https://herofab.app/tools/virtual-try-on) · [API overview: upload, poll, download](https://herofab.app/api) · [Webhooks](https://herofab.app/api/webhooks) · [Product studio API](https://herofab.app/api/product-photography)
