API Documentation

Everything you need to integrate the TryOnCloud virtual try-on API into your Shopify app, WooCommerce plugin, or custom platform.

Quick Start

1

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.

2

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.

3

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
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

JSON
{
  "success": true,
  "resultUrl": "https://www.tryoncloud.com/api/result/abc-uuid-xyz"
}
4

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

POST/api/reseller/tryon

The 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

X-API-KEY: your_api_key_here

Request — Option A: multipart/form-data

FieldTypeRequiredDescription
user_imageFileYesPerson photo. JPEG, PNG, or WebP. Max 15MB.
product_image_urlstringYesPublic URL of the product/garment image.

Request — Option B: application/json (with pre-uploaded URIs)

FieldTypeRequiredDescription
personImageUristringYesgs:// URI returned from /upload-url endpoint.
productImageUrlstringYesPublic URL of the product/garment image.

Response

JSON
{ "success": true, "resultUrl": "https://www.tryoncloud.com/api/result/uuid" }

Error Codes

StatusMeaning
401Invalid or missing API key
403Account disabled — contact info@tryoncloud.com
429Monthly quota reached — upgrade your plan
422Bad image — unprocessable or unsupported format
500Internal server error — retry after a few seconds
POST/api/reseller/upload-url

Generates 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

X-API-KEY: your_api_key_here

Request Body (application/json)

JSON
{
  "personImage":  { "contentType": "image/jpeg", "size": 512000 },
  "productImage": { "contentType": "image/jpeg", "size": 256000 }
}

Response

JSON
{
  "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

cURL— Full upload + try-on flow
cURL
# 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"
  }'
Node.js— FormData multipart upload
JavaScript
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)
Python— requests library
Python
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— cURL with CURLFile
PHP
<?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.

  1. Create a Shopify app with npm create @shopify/app@latest.
  2. Add an App Proxy endpoint in your Partner Dashboard (e.g. /a/tryon → your server).
  3. In your App Proxy handler, receive the user photo, call POST /api/reseller/tryon with your API key, and return the resultUrl.
  4. Use Product Metafields to store the product image URL per variant — retrieve it on the product page to pass as product_image_url.
  5. Inject a “Try On” button into product pages via Theme App Extensions using Liquid and App Bridge JS.
  6. Set up recurring billing with Shopify's appSubscriptionCreate mutation 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.

  1. Register a custom REST endpoint in your plugin: register_rest_route( 'tryon/v1', '/try', ... ).
  2. Accept the uploaded user image and the product ID in the REST handler.
  3. Retrieve the product image URL via wp_get_attachment_url( get_post_thumbnail_id( $product_id ) ).
  4. Forward both to POST /api/reseller/tryon via cURL with your API key in the header.
  5. Hook into woocommerce_after_add_to_cart_button to inject a “Virtual Try-On” button on product pages.
  6. 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.

  1. Create a server-side route (e.g. POST /tryon) that accepts the user photo from your frontend.
  2. Forward to POST /api/reseller/tryon with your API key. Return the resultUrl to the client.
  3. For large user photos, use the /upload-url endpoint to get a signed URL, upload the photo from the browser directly, then call /tryon with the gsUri.
  4. For async flows, store the result URL in your database and deliver it via WebSocket or polling endpoint.

Limits & Quotas

LimitValueNotes
Monthly try-on quotaPlan-dependentResets on the 1st of each month. Upgrade anytime.
Per-IP rate limit60 requests / minuteApplies per IP. Use server-side proxying to avoid hitting this.
Max image size15 MBApplies to both user_image and product images.
Supported formatsJPEG, PNG, WebPHEIC and AVIF are not currently supported.
Result URL lifetime7 daysCache 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.