Examples

Send a product and shopper photo for virtual try-on processing:

POST /v1/try-ons
Authorization: Bearer <api-key>
Content-Type: application/json
Idempotency-Key: <unique-key>

{
  "product_id": "prod_abc123",
  "shopper_photo_url": "https://your-cdn.com/photos/shopper.jpg",
  "callback_url": "https://your-server.com/webhooks/closku"
}

The API responds with the try-on ID and initial status. The result is delivered via webhook when processing completes.

Add or update a product in the Closku catalog:

PUT /v1/catalog/products/prod_abc123
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "title": "Classic Fit Oxford Shirt",
  "category": "top",
  "image_url": "https://your-cdn.com/products/oxford-shirt.jpg",
  "size_chart": {
    "S": { "chest": 36, "length": 28 },
    "M": { "chest": 38, "length": 29 },
    "L": { "chest": 40, "length": 30 }
  },
  "fabric": "100% Cotton Oxford Cloth",
  "color_variants": ["white", "blue", "pink"]
}

Products must have a resolution of at least 1000×1000px and a supported category (top, bottom, or dress) to be used in try-on requests.

Query current try-on usage and remaining capacity:

GET /v1/usage
Authorization: Bearer <api-key>

{
  "plan": "growth",
  "limit": 340,
  "used": 142,
  "remaining": 198,
  "reset_date": "2026-07-01T00:00:00Z"
}

Check usage before processing bulk try-on requests, especially during high-traffic periods. The remaining field tells you how many try-ons are available in the current billing cycle.

A webhook payload for a completed try-on looks like this:

{
  "event_id": "evt_xyz789",
  "event_type": "try_on_complete",
  "timestamp": "2026-06-01T14:30:00Z",
  "data": {
    "try_on_id": "to_def456",
    "product_id": "prod_abc123",
    "status": "completed",
    "result_url": "https://cdn.closku.io/renders/abc123.jpg",
    "processing_time_ms": 18420
  }
}

Your endpoint should return 200 within 5 seconds. Use the event_id for idempotency, since the same event may be delivered multiple times.