Language: EN
Start free

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), 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
Herofab campaign image · AI-generated
apparel_tryon

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.

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"
    }
  }'
Inputs

What to upload

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

RoleRequiredWhat to upload
garment
Product image
RequiredOne 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
OptionalThe scene to place the model in. A sharp, uncluttered photo works best.
garment_back
Product · back view
OptionalThe back of the same item, photographed the same way as the front.
garment_detail
Product · detail close-up
OptionalA close-up of the fabric, print, buckle or zipper, so small details stay accurate.
model
Model image
OptionalOne person facing the camera, arms away from the torso, in even light. Avoid sunglasses, bags or anything covering the body.
outfit_bottom
Outfit · bottom
OptionalTrousers, a skirt or shorts to style with your product. Shot flat or on a hanger, fully visible.
outfit_shoes
Outfit · shoes
OptionalThe shoes the model should wear with your product. A clear side or front shot of the pair.
outfit_top
Outfit · top
OptionalA top to style with your product, e.g. your own brand's shirt. Shot flat or on a hanger, fully visible.
Settings

Every setting and its values

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

SettingAllowed valuesDefault
garment_type
Product type
top, bottom, one_piece One-piece, bag, headwear Hat / headwear, jewelry, footwear Shoes, eyewear Glassesnone — required
aspect_ratio
Aspect ratio
1:1, 3:4, 4:5, 2:3, 9:16, 4:3, 16:93: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 imagestudio_white
expression
Expression
neutral, smileneutral
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, vestunspecified
gender
Gender
unspecified, female, maleunspecified
light
Light
scene_default Scene's own light, morning, golden_hour, overcastscene_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 pxnone
model_consent
Consent
true, falsefalse
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-upstanding_front
resolution
Resolution
2k, 4k2k
size
Size
XS, S, M, L, XL, XXLM
styling
Complete the look
plain, accessorized With accessoriesplain
view
View
front, front_back Front + back in one image, backfront

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
Ready-made settings

The app's workflow cards as API settings

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

Workflow cardProduct familiesparams
Show it on a modelJewelry{"garment_type":"jewelry"}
Close-up on a modelJewelry{"garment_type":"jewelry","pose":"close_up"}
Show it on a modelClothing{"garment_type":"top"}
Front and back on a modelClothing{"garment_type":"top","view":"front_back"}
On a model in the cityClothing{"garment_type":"top","background":"city_street"}
Show it on a modelFootwear{"garment_type":"footwear"}
Show it on a modelBags{"garment_type":"bag"}
Show it on a modelEyewear{"garment_type":"eyewear"}
Several images

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"
      ]
    }
  }'
Chain

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"
        }
      }
    ]
  }'
Credits

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.

Marketplaces

Where this image type is not accepted

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

Questions

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
Get started

Your next collection, shot this week.

20 credits at sign-up, no card required. Images made with free credits carry a watermark. Herofab also removes the watermark from those images once credits are purchased.