Developers

Try-On API

Base URL https://tryon.vidrip.app/api/v1. JSON in, JSON out. Secret keys (vk_test_… / vk_live_…) go in Authorization: Bearer from your server. The publishable key (vp_…) is for the widget on your pages.

Photo try-on

Give us a photo of the shopper and the product, get back an image of them wearing it. Jobs are asynchronous: you get a 202 with an id, then a webhook or a poll.

POST /api/v1/tryons
Authorization: Bearer vk_test_…
Idempotency-Key: order-123-tee

{ "person_image": "https://…/shopper.jpg",
  "garment_id": "gar_…",            // or "garment_image": "https://…/tee.jpg", "category": "tops"
  "quality": "balanced" }           // performance | balanced | quality

202 { "id": "…", "status": "queued", "eta_seconds": 12, … }

GET /api/v1/tryons/:id   → { "status": "done", "image_url": "https://…(signed, 7 days)", "cost_cents": 8 }
GET /api/v1/jobs/:id     → { "status", "position", "eta_seconds", "result" }

Errors are { error, code }. Images that fail moderation return 422 with person_image_rejected or garment_image_rejected.

Garments

Register products once so sessions and try-ons can reference them by id. A SKU is your natural key: posting it again updates the product.

POST /api/v1/garments
{ "sku": "TEE-001", "name": "Boxy tee", "category": "tops",
  "images": [{ "url": "https://…/front.jpg", "view": "front" }, { "url": "https://…/back.jpg", "view": "back" }],
  "product_url": "https://store.example/tee" }
→ 201 garment

GET  /api/v1/garments?sku=TEE-001
PATCH /api/v1/garments/:id   { "status": "disabled" }

Hosted sessions and the widget

A session is a hosted try-on page for one shopper and a set of garments. Mint it from your server with the secret key, or let the widget mint it in the browser with the publishable key (only from origins you allowed in the dashboard).

POST /api/v1/sessions
{ "skus": ["TEE-001"], "return_url": "https://store.example/cart", "metadata": { "cart": "c_9" } }
→ 201 { "id", "url": "https://tryon.vidrip.app/try/…", "embed_url": "…/embed/…", "expires_at" }

<script src="https://tryon.vidrip.app/widget.js" data-key="vp_…" data-skus="TEE-001"></script>

// or
VidripTryOn.open({ skus: ['TEE-001'], onAddToBag: (e) => cart.add('TEE-001') });

Webhooks

Set an endpoint in the dashboard; you get a signing secret once. Each delivery carries a vidrip-signature: t=…,v1=… header: HMAC-SHA256 of `${t}.${body}` with your secret. Reject anything older than five minutes. Retries back off over a day.

Event	When
`tryon.completed` / `tryon.failed`	A try-on finished. Payload is the try-on object.
`garment.ready`	A garment was registered or updated.
`session.converted`	The shopper tapped "Add to bag" in the hosted page: `{ session_id, garment_id, sku, size, metadata }`.
`ping`	Sent from the dashboard to test your endpoint.

Coming next

POST /api/v1/avatars (rigged body from a photo) and POST /api/v1/fits (drape and size recommendation) answer 501 until their milestones ship. The request shapes in the plan are final.