VirtuFit
Start your 14-day trial
Developer reference

VirtuFit API reference

One REST surface and one MCP toolset for virtual try-on. Every request is metered in credits, versioned by schema, and observable through signed webhooks.

Request sandbox keys
Quickstart

Three steps to your first render

A try-on job needs one product image, one shopper photo, and a garment type. The call returns immediately with a job ID; the finished image arrives by webhook and by polling.

  1. Create a sandbox key

    Keys are scoped to an environment. Sandbox keys render watermarked images and never consume billable credits.

  2. Create a try-on job

    Send a product image, a shopper photo, and the garment type. Validation runs before any credit is charged.

  3. Read the result

    Receive a signed webhook, or poll the job endpoint until the status moves to succeeded.

create-job.sh POST 
curl https://api.virtufit.space/v1/tryon \
  -H "Authorization: Bearer $VIRTUFIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "garment_image": "https://cdn.yourstore.com/tee-flatlay.jpg",
    "shopper_photo": "https://cdn.yourstore.com/shopper.jpg",
    "garment_type":  "upper",
    "quality":       "hd",
    "webhook_url":   "https://yourstore.com/hooks/virtufit"
  }'
Base URL https://api.virtufit.space/v1 1 credit
Authentication

Bearer keys, separated by environment

Every request carries a secret key in the Authorization header. Keys are issued per environment so a test integration can never touch production data or billable credits.

  • Sandbox keys return watermarked renders and charge nothing.
  • Live keys are metered in credits and can be rotated at any time.
  • Keys are shown once at creation and never rendered again in the dashboard.
Header Value
Authorization Bearer <key>
Content-Type application/json
Idempotency-Key Optional. Reuse a key to make retries safe and avoid duplicate credits.
VirtuFit-Version Optional. Pins a schema version, for example 2026-01-01.
Endpoints

The full surface

Six endpoints cover rendering, validation, size guidance, credit accounting, and webhook management. All paths are relative to the base URL.

Method Path Purpose
POST /v1/tryon Create a try-on job from a garment image and a shopper photo.
GET /v1/jobs/{id} Read the status, inputs, credits charged, and result URLs of one job.
GET /v1/jobs List jobs with filters for status, garment type, and time range.
POST /v1/garments/validate Check a product image against the input guidelines before rendering.
POST /v1/size-guide Return body-measurement to size recommendations for a garment.
GET /v1/credits Read the current allowance, usage, and overage rate for the plan.
Request body

Parameters for POST /v1/tryon

Only three fields are required. Everything else tunes quality, framing, or delivery.

Field Type Description
garment_image string (URL) Flat-lay, packshot, or on-model product photo. JPEG or PNG, shortest side from 800 px.
shopper_photo string (URL) Full-body or three-quarter photo of the shopper. Deleted automatically after the render window.
garment_type string One of upper, lower, or full_set.
quality string standard or hd. Defaults to standard.
webhook_url string (URL) Receives a signed payload when the job reaches a terminal state.
metadata object Up to 20 key-value pairs echoed back on the job and in webhook events.
upper

Tops and outerwear

Shirts, tees, knitwear, jackets, and blazers. Preserves collar shape, seams, and sleeve drape.

lower

Bottoms

Trousers, jeans, skirts, and shorts. Preserves waistband position, hem length, and fabric fall.

full_set

Dresses and full outfits

Dresses, jumpsuits, and coordinated sets. Renders head-to-toe with one request.

Responses

Jobs, statuses, and errors

A create call returns 202 Accepted with a job object. Poll the job endpoint or wait for the webhook: the payload shape is identical.

job.json 202 Accepted 
{
  "id": "job_8fd21c",
  "status": "queued",
  "garment_type": "upper",
  "quality": "hd",
  "credits_charged": 0,
  "result": {
    "image_url": null,
    "expires_at": null
  },
  "created_at": "2026-03-04T09:12:41Z"
}
Credits are charged only when status becomes succeeded job_8fd21c
Status or code Meaning
queued · running The job is accepted and rendering. Credits are held but not yet charged.
succeeded Render complete. The signed image URL is available and credits are charged.
rejected An input failed validation. Nothing is charged and the reason is returned.
failed An internal error ended the job. Retries are free and the job can be re-run as-is.
401 · 403 Missing, malformed, or environment-mismatched key.
422 A parameter is missing or outside its allowed range; the response names the field.
429 Rate or plan limit reached. A Retry-After header states when to resume.
Webhooks

Signed events, no polling required

Every state change can be delivered to your endpoint as a signed event. Verify the signature header, then treat the payload exactly like a job read response.

  • tryon.succeeded — render ready, with the signed image URL.
  • tryon.rejected — an input failed validation, with the reason.
  • tryon.failed — an internal error; the render can be retried at no cost.
  • Deliveries retry with backoff and are discarded once acknowledged.
verify-webhook.js HMAC 
// Compare the signature header before trusting the body
const expected = hmac(secret, rawBody, "sha256");
const received = headers["virtufit-signature"];

if (!timingSafeEqual(expected, received)) {
  return response.status(400).end();
}

const event = JSON.parse(rawBody);
if (event.type === "tryon.succeeded") {
  publish(event.data.result.image_url);
}
Header virtufit-signature HMAC-SHA256
MCP server

Try-on as a tool call for AI agents

The Model Context Protocol server exposes the same engine to any MCP-compatible client. Tool schemas are versioned alongside the REST API, so upgrades never break live agent flows.

Tool Returns
tryon_render A job handle plus the finished image once the render completes.
tryon_validate_garment Whether a product image is usable, with the reason if it is not.
tryon_size_guide Size recommendations from shopper measurements and garment measurements.
tryon_job_status The current state and credit accounting for a known job ID.
tools.json MCP 
{
  "name": "tryon_render",
  "description": "Render a garment on a shopper photo.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "garment_image": { "type": "string" },
      "shopper_photo": { "type": "string" },
      "garment_type":  { "enum": ["upper", "lower", "full_set"] }
    },
    "required": ["garment_image", "shopper_photo", "garment_type"]
  }
}
Standard MCP tool contract v1
Credits & limits

Metering you can predict

One successful render costs one credit regardless of garment type. Failed, rejected, and invalid renders are never charged.

Plan Included per month Overage per render
Starter 600 credits $0.009
Growth 2,400 credits $0.007
Scale 10,000 credits $0.005
Rate limits Plan-based requests per minute, returned in the 429 response with a Retry-After header.

Get keys and render your first outfit

Sandbox keys are issued the same business day. Bring your catalog, and we will review your first successful renders with you before you go live.

Request sandbox keys See pricing