See a product on the shopper's body

POST

/v1/tryon

curl --request POST \
  --url 'https://api.tryyoursize.com/v1/tryon?view=full&start=true' \
  --header 'Content-Type: application/json' \
  --header 'TYS-Publishable-Key: <TYS-Publishable-Key>' \
  --data '{ "product": "example", "basics": { "sex": "female", "age_years": 1, "height_mm": 1, "weight_kg": 1 }, "measurements": [ { "code": "neck_girth", "value_mm": 1, "source": "tape_self" } ], "body_state": [ 1 ] }'

• Production (test and live mode are chosen by the key)

Key: publishable (pk_test_… / pk_live_…), from an origin registered for the key.

Shows every size of the product’s published garment on the body and recommends a size (from a few seconds to about 2 minutes). A body already shown with this garment version answers 200 at once; otherwise 202 and a job to poll. Every answer carries a new viewer_token, the only way (with the shopper’s session) to read the job. With a shopper session (Authorization: Bearer tys_sess_…) the try-on is linked to the shopper and, in live mode, delivering a done result records the store connection and the size the store receives.

Authorizations

• PublishableKey

Parameters

Query Parameters

view

string

default: full

Allowed values: full summary

full (default) answers with the whole result (meshes for every size, MBs). summary leaves result out and answers summary instead (the recommended size and the sizes that can be worn, a few bytes): for the size-guide button and the store’s recommended-size event, which never need the meshes.

start

boolean

default: true

false answers only with an existing result and never queues a simulation: a done or running try-on of this body, or 404 (“not simulated yet”). With view=summary, a miss may answer 200 with a size estimate instead (status: done, empty id, summary.method: estimate). Page views (the size-guide and inline elements) use it; a full simulation starts only on an explicit shopper action (“See it on you”).

Request Body^required

Media typeapplication/json

The product and the shopper’s body as on screen: the same body as /v1/bodies/preview, with the preview’s body_state (required; opaque).

object

product

required

The product’s SKU / style ID in the store (what the shop passes to the element).

string

>= 1 characters <= 120 characters

basics

required

object

sex

required

string

Allowed values: female male

age_years

required

integer

>= 1

height_mm

required

number format: double

weight_kg

required

number format: double

measurements

Array<object>

<= 64 items

object

code

required

Body measurement from set v1.

string

Allowed values: neck_girth shoulder_width arm_length armscye_girth upper_arm_girth wrist_girth chest_girth underbust_girth bust_point_to_bust_point shoulder_to_bust_point back_length waist_girth front_waist_arc high_hip_girth abdomen_girth hip_girth front_hip_arc thigh_girth knee_girth calf_girth ankle_girth inseam outseam crotch_length

value_mm

required

Measured value in millimetres.

number format: double

source

required

string

Allowed values: tape_self tape_helper flat_garment estimated

body_state

required

The body_state of the body preview on screen.

Array<number>

<= 64 items

Responses

200

Done (an existing result)

Media typeapplication/json

A try-on: every size of the product’s published garment shown on the body. Poll GET /v1/tryon/{tryon_id} every ~2 s until status is done or failed. A repeated try-on of the same garment version and body answers at once.

object

id

required

The try-on’s id (uuid). Empty only for a size estimate (POST ?start=false&view=summary answered with no try-on of this body); there is nothing to poll.

string

viewer_token

Only in the answer to POST /v1/tryon: the window’s proof that it may read this try-on. Send it as Authorization: Bearer tys_view_… to GET /v1/tryon/{tryon_id}. Stored hashed; never sent again.

string

status

required

string

Allowed values: queued running done failed

progress

required

object

sizes_done

required

integer

sizes_total

required

integer

result

Present when status is done, and while it runs: the sizes computed so far, each with method (simulated) and state (preview: shown early, may still change; settled; refining: still being computed, no mesh yet; simulated). The try-on result for the window: body mesh and body_state (no basics, no tape measurements), garment with its fabric and estimated POMs, recommended size and per-size meshes, pressure kPa, ease mm and zones. Binary arrays are base64 little-endian; per-vertex values are rounded to display precision.

object

key

additional properties

any

summary

Present when status is done and the request asked for view=summary: what a store may receive (sizes only, never measurements). Size labels are the garment’s (Studio) sizes; map them with shop_sizes from GET /v1/products/{product}/tryon.

object

recommended_size

The recommended size; absent when no size can be worn.

string

no_size_fits

required

boolean

wearable_sizes

required

Sizes that can be worn on this body (judged on this body), smallest to largest.

Array<string>

method

How the size was determined: estimate (a size estimate, no try-on of this body yet) or simulated (from the try-on of this body). A coarse informational label: do not build logic on its values.

string

Allowed values: estimate simulated

recommendation

The size answer with its method. On the first answer of a try-on it may already be there (method: estimate) while the 3D view is computed; once done it is the try-on’s own size. An estimate is final (ready or none) only when it is certain for this body; otherwise the status is computing, no size is named, and the try-on’s 3D view gives it.

object

recommended_size

string

nullable

method

required

Same as summary.method. A coarse informational label; do not build logic on its values.

string

Allowed values: estimate simulated

status

required

string

Allowed values: ready none computing unavailable

wearable_sizes

Array<string>

error

Present when status is failed.

object

code

required

INVALID_BODY, UNSUPPORTED_CATEGORY, MISSING_POM, INVALID_POM, INVALID_FABRIC, NO_SIZES, UNAVAILABLE or ENGINE_ERROR.

string

message

required

string

Example

{
  "status": "queued",
  "summary": {
    "method": "estimate"
  },
  "recommendation": {
    "method": "estimate",
    "status": "ready"
  }
}

202

Queued or running; poll GET /v1/tryon/{tryon_id}

Media typeapplication/json

A try-on: every size of the product’s published garment shown on the body. Poll GET /v1/tryon/{tryon_id} every ~2 s until status is done or failed. A repeated try-on of the same garment version and body answers at once.

object

id

required

The try-on’s id (uuid). Empty only for a size estimate (POST ?start=false&view=summary answered with no try-on of this body); there is nothing to poll.

string

viewer_token

Only in the answer to POST /v1/tryon: the window’s proof that it may read this try-on. Send it as Authorization: Bearer tys_view_… to GET /v1/tryon/{tryon_id}. Stored hashed; never sent again.

string

status

required

string

Allowed values: queued running done failed

progress

required

object

sizes_done

required

integer

sizes_total

required

integer

result

Present when status is done, and while it runs: the sizes computed so far, each with method (simulated) and state (preview: shown early, may still change; settled; refining: still being computed, no mesh yet; simulated). The try-on result for the window: body mesh and body_state (no basics, no tape measurements), garment with its fabric and estimated POMs, recommended size and per-size meshes, pressure kPa, ease mm and zones. Binary arrays are base64 little-endian; per-vertex values are rounded to display precision.

object

key

additional properties

any

summary

Present when status is done and the request asked for view=summary: what a store may receive (sizes only, never measurements). Size labels are the garment’s (Studio) sizes; map them with shop_sizes from GET /v1/products/{product}/tryon.

object

recommended_size

The recommended size; absent when no size can be worn.

string

no_size_fits

required

boolean

wearable_sizes

required

Sizes that can be worn on this body (judged on this body), smallest to largest.

Array<string>

method

How the size was determined: estimate (a size estimate, no try-on of this body yet) or simulated (from the try-on of this body). A coarse informational label: do not build logic on its values.

string

Allowed values: estimate simulated

recommendation

The size answer with its method. On the first answer of a try-on it may already be there (method: estimate) while the 3D view is computed; once done it is the try-on’s own size. An estimate is final (ready or none) only when it is certain for this body; otherwise the status is computing, no size is named, and the try-on’s 3D view gives it.

object

recommended_size

string

nullable

method

required

Same as summary.method. A coarse informational label; do not build logic on its values.

string

Allowed values: estimate simulated

status

required

string

Allowed values: ready none computing unavailable

wearable_sizes

Array<string>

error

Present when status is failed.

object

code

required

INVALID_BODY, UNSUPPORTED_CATEGORY, MISSING_POM, INVALID_POM, INVALID_FABRIC, NO_SIZES, UNAVAILABLE or ENGINE_ERROR.

string

message

required

string

Example

{
  "status": "queued",
  "summary": {
    "method": "estimate"
  },
  "recommendation": {
    "method": "estimate",
    "status": "ready"
  }
}

400

Invalid request

Media typeapplication/json

Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.

object

error

required

string

status

required

integer

code

Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

401

Missing or invalid credentials

Media typeapplication/json

Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.

object

error

required

string

status

required

integer

code

Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

403

Not allowed

Media typeapplication/json

Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.

object

error

required

string

status

required

integer

code

Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

404

No published garment for the product, or (start=false) this body was not simulated yet

Media typeapplication/json

Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.

object

error

required

string

status

required

integer

code

Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

422

The content is rejected (e.g. a body that cannot be rebuilt)

Media typeapplication/json

Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.

object

error

required

string

status

required

integer

code

Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}

503

A dependency is temporarily unavailable; retry later

Media typeapplication/json

Every error has this shape. error is a human-readable message, status the HTTP status. code is stable and machine-readable; doc_url links its explanation; request_id identifies the request (also in the X-Request-ID response header): quote it to support.

object

error

required

string

status

required

integer

code

Stable error code, e.g. invalid_request, unauthorized, reauth_required, payment_required, forbidden, not_found, conflict, unprocessable, rate_limited, internal_error, not_implemented, unavailable, invalid_api_version, idempotency_key_in_use, idempotency_key_reused, invalid_idempotency_key, handle_expired, handle_invalid.

string

doc_url

string format: uri

request_id

string

Example

{
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found"
}