# WEARFITS Shoes & Bags 3D/AR Try-On Integration Guide
> Source: https://tryon.wearfits.com/docs/integration-shoes.html
> Markdown version for AI/LLM ingestion and developer reference.
---
Integrate AI-powered 3D/AR try-on for **shoes and bags** into your e-commerce website.
## About Shoes & Bags 3D/AR Try-On
WEARFITS Shoes & Bags 3D/AR Try-On is a cutting-edge solution that transforms product photos into **interactive 3D models**. Shoes get a full AR try-on experience — customers can see how footwear looks in real-world scale using their smartphone camera. Bags get an interactive 3D viewer so customers can inspect the product from every angle.
Upload 1-4 images of a shoe or bag, and our AI generates a high-quality 3D model that can be viewed on any mobile device via a simple QR code scan.
Key benefits include **increased customer confidence**, **reduced returns**, and an **innovative shopping experience** that differentiates your brand.
### Core Features
- **AI 3D Generation**: Advanced AI converts 2D product photos into detailed 3D models automatically — works for both shoes and bags.
- **Instant AR / 3D Viewer**: Generated models are instantly available via QR code — shoes get AR try-on, bags get a 3D viewer. No app required.
- **Simple API**: RESTful API with job-based processing. Submit images, poll for status, get the viewer URL.
- **Mobile Optimized**: AR/3D viewer works on all modern smartphones with WebXR support.
## Table of Contents
- [Overview](#overview)
- [How It Works](#how-it-works)
- [API Reference](#api-reference)
- [Frontend Integration](#frontend-integration)
- [Best Practices](#best-practices)
- [Image Dataset Template for 2D to 3D Conversion](#image-dataset-template-for-2d-to-3d-conversion)
- [Support](#support)
## Overview
The WEARFITS Shoes & Bags 3D/AR Try-On enables customers to visualize footwear and handbags from AI-generated 3D models. The process is simple:
1. **Upload Images** - Submit 1-4 photos of a shoe or bag
2. **AI Processing** - Our AI generates a 3D model (takes 1-5 minutes)
3. **Viewer Ready** - Receive a viewer URL with QR code (AR for shoes, 3D for bags)
4. **Customer Experience** - Customers scan the QR code to inspect the product
## How It Works
### 1. Image Upload
Upload 1-4 high-quality images of the product. Multiple angles improve 3D model quality:
- **Single image** - Use a perspective view showing the front and side (3/4 angle)
- **Multiple images** - Front, side, back, and top views for best results
Shoes and bags follow the same upload flow; use the `options.productType` hint (see API Reference) to tell the backend which one it is, or pass `"auto"` to let it auto-detect.
### 2. 3D Model Generation
Our AI processes the images using state-of-the-art 3D reconstruction technology. The best model is automatically selected for optimal results.
### 3. AR / 3D Viewer
Once processing completes, you receive a viewer URL:
- **Shoes** → AR try-on URL (`/tryon?object=...`). Customers scan the QR code and see the shoe in augmented reality at real-world scale.
- **Bags** → 3D viewer URL (`/viewer?object=...`). Customers inspect the bag from every angle in an interactive 3D viewer. AR try-on is shoe-specific and not available for bags.
Either way, customers can:
- Scan the QR code with their smartphone
- View and rotate the 3D model
- See realistic proportions and materials
## API Reference
### Base URL
```text
https://api.wearfits.com/v1
```
### Authentication
All requests require an API key in the header:
```http
X-API-Key: your-api-key
```
### 1. Upload Base 3D Model (Optional)
If you already have a 3D model of the product in `.glb` format, you can upload it directly to bypass the AI 2D-to-3D generation phase. Works for both shoes and bags.
```http
POST /v1/files/upload
Content-Type: multipart/form-data
```
#### Request Fields
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | file | Yes | The `.glb` base 3D model (max 50MB) |
#### Response
```json
{
"url": "https://storage.wearfits.com/uploads/abc-123.glb"
}
```
### 2. Submit 3D Generation Job
The `/v1/shoe-3d` endpoint handles **both shoes and bags** — the historical name is retained for backwards compatibility. Use `options.productType` to indicate the product type (or `"auto"` to detect it).
```http
POST /v1/shoe-3d
{
"images": [
"https://example.com/product-front.jpg",
"https://example.com/product-side.jpg"
],
"glbInput": "https://storage.wearfits.com/uploads/abc-123.glb",
"options": {
"uploadToWearFits": true,
"productType": "auto",
"enhanceTexture": true,
"genaiQuality": "high",
"smoothNormals": true
}
}
```
#### Request Fields
| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `images` | array | Yes | — | Array of image URLs or base64 data URLs (1-4 images) |
| `glbInput` | string | No | — | Optional URL of a pre-uploaded `.glb` model to bypass AI mesh generation (texture extraction only) |
| `options.uploadToWearFits` | boolean | Yes\* | `false` | Must be `true` to get the AR viewer URL in the completed response |
| `options.rightShoe` | boolean | No | `false` | Set to `true` if the image shows the right shoe (shoes only) |
| `options.enhanceTexture` | boolean | No | `true` | Apply AI texture enhancement to the generated model |
| `options.genaiQuality` | string | No | `"standard"` | Quality preset for 3D generation. Accepted: `"standard"`, `"high"` |
| `options.skipCache` | boolean | No | `false` | Force a fresh generation, bypassing any cached result for the same inputs |
| `options.smoothNormals` | boolean | No | `true` | Smooth the generated mesh normals for a softer shaded surface. Set to `false` to preserve faceted geometry |
| `options.pipelineVariant` | string | No | `"A"` | Select generation pipeline. `"B"` enables the beta pipeline (experimental) |
| `options.productType` | string | No | `"shoe"` | Product type hint. `"auto"` lets the backend detect the product (e.g. bags). Non-shoe products generate a 3D viewer link instead of AR try-on |
\* Required to receive `wearfitsTryOn.viewerUrl` in the completed response. Without it you only get the raw `.glb` URL in `results[].url`.
#### Response
```json
{
"jobId": "d6543a37-7867-4986-af23-856501c1338d"
}
```
### 3. Check Job Status
```http
GET /v1/jobs/{jobId}
```
#### Response (Processing)
```json
{
"id": "d6543a37-7867-4986-af23-856501c1338d",
"status": "processing",
"progress": {
"stage": "generating_3d_model",
"percentage": 45
}
}
```
#### Response (Completed)
```json
{
"id": "d6543a37-7867-4986-af23-856501c1338d",
"status": "completed",
"mode": "shoe-3d",
"results": [
{
"url": "https://storage.example.com/model.glb",
"expiresAt": "2026-01-22T00:43:10.895Z"
}
],
"wearfitsTryOn": {
"modelId": "shoe-model-123",
"colorId": "color-456",
"viewerUrl": "https://dev.wearfits.com/tryon/shoe/shoe-model-123/color-456"
},
"progress": {
"stage": "completed",
"percentage": 100
}
}
```
#### Job Status Values
| Status | Description |
| --- | --- |
| `queued` | Job is waiting to be processed |
| `validating` | Validating input images |
| `processing` | Generating 3D model |
| `uploading` | Uploading to WEARFITS AR platform |
| `completed` | Job finished successfully |
| `failed` | Job failed (check error field) |
## Frontend Integration
Once you've generated the viewer URL via the API (backend), add a "Try On" / "View in 3D" button to your product pages.
### Viewer URL Formats
```text
# Shoes — AR try-on (WebXR)
https://dev.wearfits.com/tryon?object={id}
# Bags (and other non-shoe products) — 3D viewer
https://dev.wearfits.com/viewer?object={id}
```
The completed job response returns the correct URL in `wearfitsTryOn.viewerUrl` based on the detected product type. For shoes, the frontend may convert `/viewer?` → `/tryon?` to enable AR mode; for bags, keep the `/viewer?` URL as-is. Store the resulting URL in your product database.
### Simple Button Link
```html
Try On in AR
```
### Button with QR Code
```html
```
### Dynamic JavaScript Example
```javascript
// Product data from your backend (viewer URL already generated)
const product = {
id: 'sku-001',
name: 'Running Sneaker', // or a handbag, etc.
productType: 'shoe', // 'shoe' | 'bag'
viewerUrl: 'https://dev.wearfits.com/tryon?object=abc123'
};
// Generate QR code URL
function getQrCodeUrl(url) {
return `https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=${encodeURIComponent(url)}`;
}
// Add a viewer button to the product page.
// Shoes get "Try On in AR"; non-shoe products get "View in 3D".
function addViewerButton(product) {
const button = document.createElement('a');
button.href = product.viewerUrl;
button.target = '_blank';
button.className = 'tryon-button';
button.textContent = product.productType === 'shoe'
? 'Try On in AR'
: 'View in 3D';
document.querySelector('.product-actions').appendChild(button);
}
```
## Best Practices
### 1. Image Requirements (for API)
- Use high-quality images (minimum 500x500px, recommended 1000x1000px)
- White or neutral background for best results
- Good lighting without harsh shadows
- Multiple angles improve 3D quality significantly
- Supported formats: JPEG, PNG, WebP
### 2. Backend Integration
- Pre-generate 3D models when shoes or bags are added to your catalog
- Store viewer URLs (AR or 3D) in your product database
- 3D generation takes 1-5 minutes - run as a background job
- Cache generated viewer URLs by product ID
### 3. Frontend User Experience
- Place the "Try On in AR" / "View in 3D" button prominently on product pages
- Provide clear instructions for QR code scanning
- Offer both a QR code and a direct link for flexibility
- Consider showing the QR code on desktop and a direct button on mobile
- Use product-type-aware copy: "Try On in AR" for shoes, "View in 3D" for bags
### 4. Job Persistence
The WEARFITS photo-to-3D app automatically persists in-progress jobs across page reloads:
- If a user refreshes the page during 3D model generation, the job will automatically resume
- Pending jobs are stored in localStorage with a 15-minute expiration
- Once the job completes or fails, the pending state is cleared
- This ensures users don't lose their progress if they accidentally navigate away
## Image Dataset Template for 2D to 3D Conversion
Capture your product from up to 9 angles (2-4 recommended) for optimal 3D model generation. The same angle coverage applies to both shoes and bags — think of it as "walk around the product".
### Recommended Views
- Left 3/4 Perspective (**Required**)
- Right 3/4 Perspective (**Required**)
- Left Back 3/4 Perspective
- Left Profile Elevation
- Right Profile Elevation
- Top Plan View
- Front View
- Rear View
- Bottom / Sole Plan View (sole for shoes, base for bags)
### Technical Specs
- Images: JPG or PNG
- Minimum resolution: 2000x2000px
- Background: White or solid background
- One product per image — no hands, mannequins, or distracting elements
## Support
For technical support and API access, [contact our support team](https://wearfits.com/contact?s=support).
Related guide: [View Clothing Try-On Integration Guide](https://tryon.wearfits.com/docs/integration.html)