Render a person wearing one or more trial garments

POST

/v1/try-on

curl --request POST \
  --url https://example.com/v1/try-on \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "user_image": { "type": "asset", "asset_id": "01J7B7W8M3R4X5Y6Z7A8B9C0D1" }, "user_category": "FEMALE", "items": [ { "trial_image": { "type": "asset", "asset_id": "01J7B7W8M3R4X5Y6Z7A8B9C0D2" }, "trial_item_category": "top" } ] }'

Dispatch a virtual try-on: apply one or more trial garments to a person image. Pass the asset_id from POST /v1/uploads as the person and garment references. A narrowly-scoped Wardrobe credential may use the explicit wardrobe_legacy_key reference during migration. Returns 202 immediately with a job_id; poll GET /v1/jobs/{job_id}/events for live progress and GET /v1/jobs/{job_id} for the terminal render. Costs 10 credits, refunded automatically on any failure path.

Authorizations

• sk_*

Parameters

Header Parameters

X-Shopify-Hmac-Sha256

Any of:

string

string

null

null

Request Body^required

Media typeapplication/json

TryOnRequest

Try-on submission.

object

user_image

required

One of: discriminator: type

AssetIdReference

AssetIdReference

A durable, owner-resolved asset reference for canonical VTON.

object

type

Type

string

default: asset

Allowed value: asset

asset_id

required

Asset Id

Canonical asset ULID returned by POST /v1/uploads.

string

>= 26 characters <= 26 characters /^[0-9A-HJKMNP-TV-Z]{26}$/

WardrobeLegacyKeyReference

WardrobeLegacyKeyReference

A narrowly-authorized Wardrobe key awaiting trusted asset adoption.

object

type

Type

string

default: wardrobe_legacy_key

Allowed value: wardrobe_legacy_key

s3_key

required

S3 Key

Existing Wardrobe image key. Requires wardrobe:legacy-assets.

string

>= 1 characters <= 512 characters

user_category

Any of:

UserCategory

UserCategory

User gender category.

string

Allowed values: MALE FEMALE

null

null

items

required

Items

One to four trial items to apply to the user image.

Array<object>

>= 1 items <= 4 items

TryOnItemInput

One garment passed to canonical /v1/try-on.

Name the garment either by image reference (trial_image) or by one of your own products (product_public_id, from GET /v1/products) — exactly one. Studio resolves a product to its product shot, and inherits the product’s category and title unless you send your own (TRI-44).

object

trial_image

Any of:

Trial Image

One of: discriminator: type

AssetIdReference

AssetIdReference

A durable, owner-resolved asset reference for canonical VTON.

object

type

Type

string

default: asset

Allowed value: asset

asset_id

required

Asset Id

Canonical asset ULID returned by POST /v1/uploads.

string

>= 26 characters <= 26 characters /^[0-9A-HJKMNP-TV-Z]{26}$/

WardrobeLegacyKeyReference

WardrobeLegacyKeyReference

A narrowly-authorized Wardrobe key awaiting trusted asset adoption.

object

type

Type

string

default: wardrobe_legacy_key

Allowed value: wardrobe_legacy_key

s3_key

required

S3 Key

Existing Wardrobe image key. Requires wardrobe:legacy-assets.

string

>= 1 characters <= 512 characters

null

null

product_public_id

Any of:

string

string

>= 26 characters <= 26 characters

null

null

trial_item_category

Any of:

string

string

null

null

garment_title

Any of:

string

string

null

null

runtime_config

Any of:

object

object

key

additional properties

any

null

null

render_params

Any of:

RenderParams

RenderParams

Rendering options for the try-on output. Mirrors contracts.tryon.RenderParams.

object

resolution

Any of:

RenderResolution

RenderResolution

Output image-size tier, forwarded to the image model as image_size.

string

Allowed values: 0.5K 1K 2K 4K

null

null

null

null

view

Any of:

string

string

Allowed values: front back

null

null

Examples

Examplesingle_garment

One garment on a person image

{
  "user_image": {
    "type": "asset",
    "asset_id": "01J7B7W8M3R4X5Y6Z7A8B9C0D1"
  },
  "user_category": "FEMALE",
  "items": [
    {
      "trial_image": {
        "type": "asset",
        "asset_id": "01J7B7W8M3R4X5Y6Z7A8B9C0D2"
      },
      "trial_item_category": "top"
    }
  ]
}

Responses

202

Accepted — job queued. Poll /v1/jobs/{job_id} for progress.

Media typeapplication/json

WorkflowAcceptedResponse

Returned synchronously from any POST /v1/{name} (202).

object

request_id

required

Request Id

26-char ULID — correlates with the row in credit_operations.

string

job_id

required

Any of:

string

string

null

null

status

JobStatus

Studio’s job status at submit time. Almost always NOT_STARTED in this 202.

string

default: NOT_STARTED

Allowed values: NOT_STARTED SUCCESS FAILURE IN_PROGRESS

credits_cost

required

Credits Cost

Credits deducted from the calling client. Refunded automatically on any failure path.

integer

Example

{
  "request_id": "01JREQREQREQREQREQREQREQ00",
  "job_id": "01JOBJOBJOBJOBJOBJOBJOBJOB0",
  "status": "NOT_STARTED",
  "credits_cost": 10
}

402

Insufficient credit balance — the request cost exceeds the client’s balance. No job created.

Media typeapplication/json

Example

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Account balance is below the cost of this request.",
    "request_id": "01JREQREQREQREQREQREQREQ00"
  }
}

422

Request body failed validation (missing/invalid fields). No credits charged.

Media typeapplication/json

Example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body or parameters failed validation.",
    "request_id": "01JREQREQREQREQREQREQREQ00"
  }
}

429

Per-credential rate limit exceeded. Retry after a short backoff.

Media typeapplication/json

Example

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded; try again shortly.",
    "request_id": "01JREQREQREQREQREQREQREQ00"
  }
}