API Documentation
Everything you need to integrate the TryOnCloud virtual try-on API into your Shopify app, WooCommerce plugin, or custom platform.
Quick Start
Sign up and request reseller access
Create a free account at tryoncloud.com/signup. Then email info@tryoncloud.com with your use case. We will promote your account to reseller status within one business day.
Get your API key from the Reseller Dashboard
Log in and navigate to Dashboard → Reseller → API Key. Copy your key — treat it like a password. Never expose it in client-side code.
Make your first try-on call
Send a POST request with a user photo and a product image URL. The API returns a hosted result image URL.
curl -X POST https://www.tryoncloud.com/api/reseller/tryon \
-H "X-API-KEY: your_api_key_here" \
-F "user_image=@/path/to/user-photo.jpg" \
-F "product_image_url=https://your-store.com/product.jpg"Response
{
"success": true,
"resultUrl": "https://www.tryoncloud.com/api/result/abc-uuid-xyz"
}Display the resultUrl to your user
Render the resultUrl directly in an <img> tag or pass it to your frontend. The URL is publicly accessible — no authentication needed to display the image.
Endpoints
/api/reseller/tryonThe primary try-on endpoint. Accepts either multipart/form-data with a user photo file, or a JSON body with pre-uploaded gs:// URIs from the upload-url endpoint.
Authentication
Request — Option A: multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
| user_image | File | Yes | Person photo. JPEG, PNG, or WebP. Max 15MB. |
| product_image_url | string | Yes | Public URL of the product/garment image. |
Request — Option B: application/json (with pre-uploaded URIs)
| Field | Type | Required | Description |
|---|---|---|---|
| personImageUri | string | Yes | gs:// URI returned from /upload-url endpoint. |
| productImageUrl | string | Yes | Public URL of the product/garment image. |
Response
{ "success": true, "resultUrl": "https://www.tryoncloud.com/api/result/uuid" }Error Codes
| Status | Meaning |
|---|---|
| 401 | Invalid or missing API key |
| 403 | Account disabled — contact info@tryoncloud.com |
| 429 | Monthly quota reached — upgrade your plan |
| 422 | Bad image — unprocessable or unsupported format |
| 500 | Internal server error — retry after a few seconds |
/api/reseller/upload-urlGenerates signed upload URLs for large images. Upload directly from the browser or server using the returned uploadUrl (PUT request), then pass the gsUri to the /tryon endpoint.
Authentication
Request Body (application/json)
{
"personImage": { "contentType": "image/jpeg", "size": 512000 },
"productImage": { "contentType": "image/jpeg", "size": 256000 }
}Response
{
"personUpload": {
"uploadUrl": "https://storage.googleapis.com/...",
"gsUri": "gs://bucket/person/uuid.jpg"
},
"productUpload": {
"uploadUrl": "https://storage.googleapis.com/...",
"gsUri": "gs://bucket/product/uuid.jpg"
},
"expiresIn": "10 minutes"
}Upload your image to uploadUrl with a PUT request and the correct Content-Type header. Then pass gsUri as personImageUri in the /tryon call.
Code Examples
# Step 1 — Request upload URLs
curl -X POST https://www.tryoncloud.com/api/reseller/upload-url \
-H "X-API-KEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"personImage": { "contentType": "image/jpeg", "size": 512000 },
"productImage": { "contentType": "image/jpeg", "size": 256000 }
}'
# Step 2 — Upload person image directly to the signed URL
curl -X PUT "<personUpload.uploadUrl>" \
-H "Content-Type: image/jpeg" \
--data-binary @user-photo.jpg
# Step 3 — Call /tryon with the gs:// URIs
curl -X POST https://www.tryoncloud.com/api/reseller/tryon \
-H "X-API-KEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"personImageUri": "gs://bucket/person/uuid.jpg",
"productImageUrl": "https://your-store.com/product.jpg"
}'import FormData from "form-data"
import fetch from "node-fetch"
import fs from "fs"
const API_KEY = process.env.TRYON_API_KEY
async function runTryOn(userImagePath, productImageUrl) {
const form = new FormData()
form.append("user_image", fs.createReadStream(userImagePath))
form.append("product_image_url", productImageUrl)
const res = await fetch(
"https://www.tryoncloud.com/api/reseller/tryon",
{
method: "POST",
headers: { "X-API-KEY": API_KEY, ...form.getHeaders() },
body: form,
}
)
const data = await res.json()
if (!data.success) throw new Error(data.error || "Try-on failed")
return data.resultUrl
}
// Usage
runTryOn("./user.jpg", "https://store.com/kurta.jpg")
.then((url) => console.log("Result:", url))
.catch(console.error)import requests
API_KEY = "your_api_key_here"
API_URL = "https://www.tryoncloud.com/api/reseller/tryon"
def run_tryon(user_image_path: str, product_image_url: str) -> str:
with open(user_image_path, "rb") as img:
response = requests.post(
API_URL,
headers={"X-API-KEY": API_KEY},
files={"user_image": img},
data={"product_image_url": product_image_url},
)
response.raise_for_status()
data = response.json()
if not data.get("success"):
raise ValueError(data.get("error", "Try-on failed"))
return data["resultUrl"]
# Usage
result_url = run_tryon("user.jpg", "https://store.com/kurta.jpg")
print("Result:", result_url)<?php
$apiKey = 'your_api_key_here';
$apiUrl = 'https://www.tryoncloud.com/api/reseller/tryon';
function runTryOn(string $imagePath, string $productUrl, string $apiKey): string {
$cfile = new CURLFile($imagePath, 'image/jpeg', basename($imagePath));
$ch = curl_init($apiUrl);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ["X-API-KEY: $apiKey"],
CURLOPT_POSTFIELDS => [
'user_image' => $cfile,
'product_image_url' => $productUrl,
],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
if (!$data['success']) {
throw new Exception($data['error'] ?? 'Try-on failed');
}
return $data['resultUrl'];
}
$url = runTryOn('user.jpg', 'https://store.com/kurta.jpg', $apiKey);
echo "Result: $url
";Platform Integration Guides
Shopify App Integration
Build a Shopify embedded app using the Shopify CLI and App Bridge. Use App Proxy to route try-on requests through your server so your API key is never exposed to the browser.
- Create a Shopify app with
npm create @shopify/app@latest. - Add an App Proxy endpoint in your Partner Dashboard (e.g.
/a/tryon→ your server). - In your App Proxy handler, receive the user photo, call
POST /api/reseller/tryonwith your API key, and return theresultUrl. - Use Product Metafields to store the product image URL per variant — retrieve it on the product page to pass as
product_image_url. - Inject a “Try On” button into product pages via Theme App Extensions using Liquid and App Bridge JS.
- Set up recurring billing with Shopify's
appSubscriptionCreatemutation to charge merchants monthly.
WooCommerce Plugin Integration
Build a WordPress plugin that hooks into WooCommerce product pages. Use PHP cURL to proxy requests to TryOnCloud — never call the API from JavaScript directly.
- Register a custom REST endpoint in your plugin:
register_rest_route( 'tryon/v1', '/try', ... ). - Accept the uploaded user image and the product ID in the REST handler.
- Retrieve the product image URL via
wp_get_attachment_url( get_post_thumbnail_id( $product_id ) ). - Forward both to
POST /api/reseller/tryonvia cURL with your API key in the header. - Hook into
woocommerce_after_add_to_cart_buttonto inject a “Virtual Try-On” button on product pages. - Store the reseller API key in plugin settings under WooCommerce → Settings → Try-On.
Custom Store Integration
For headless storefronts, custom marketplaces, or fashion brand portals — call the TryOnCloud API from your own backend in any language.
- Create a server-side route (e.g.
POST /tryon) that accepts the user photo from your frontend. - Forward to
POST /api/reseller/tryonwith your API key. Return theresultUrlto the client. - For large user photos, use the
/upload-urlendpoint to get a signed URL, upload the photo from the browser directly, then call /tryon with thegsUri. - For async flows, store the result URL in your database and deliver it via WebSocket or polling endpoint.
Limits & Quotas
| Limit | Value | Notes |
|---|---|---|
| Monthly try-on quota | Plan-dependent | Resets on the 1st of each month. Upgrade anytime. |
| Per-IP rate limit | 60 requests / minute | Applies per IP. Use server-side proxying to avoid hitting this. |
| Max image size | 15 MB | Applies to both user_image and product images. |
| Supported formats | JPEG, PNG, WebP | HEIC and AVIF are not currently supported. |
| Result URL lifetime | 7 days | Cache or store the resultUrl if you need longer access. |
Ready to monetize your integration?
See exactly how much you can earn with our full revenue guide.