Vrool API Documentation

Overview

The Vrool Fashion Makeover API dresses a person photo in the clothing you supply and returns a realistic AI-generated image. It is designed for ecommerce stores, marketplaces, fashion apps and agencies who want virtual try-on without running their own AI.

• All AI runs on Vrool servers — you never handle or see model keys.
• Simple JSON in, image out. No SDK required.
• Credit-metered with a free sandbox to test before you pay.
• The result image is returned inline — Vrool keeps no copy, so you store it on your own platform.

See it in action

Send a customer photo plus your product image. The API returns the customer realistically wearing that product.

Add bottom_image, shoes_image or outfit_image to dress the full look. The person's face, pose and background are preserved — only the clothing changes.

What you can build

The Fashion Makeover API powers virtual try-on anywhere your customers shop.

Getting started

Base URLs

POST https://vrool.com/api/v1/fashion/makeover

Also reachable at: https://vrool.com/content/plugins/vrool_ai/api/makeover.php

All requests use HTTPS. The same endpoint serves sandbox and live traffic — the key you use decides the mode.

Authentication

Every request needs your public key and secret key. Send them in the Authorization header:

Authorization: Bearer PUBLIC_KEY:SECRET_KEY

Or as separate headers:

X-Api-Key: PUBLIC_KEY
X-Api-Secret: SECRET_KEY

Keep your secret key server-side. Never expose it in browsers or mobile apps. If a key leaks, rotate or revoke it instantly in the Developer Portal.

Sandbox vs Live

The response includes a "mode" field so you always know which key handled the request.

Fashion Makeover

Send a person image plus one or more garment images. Each image can be a public HTTPS URL or a base64 data URI.

curl -X POST https://vrool.com/api/v1/fashion/makeover \
  -H "Authorization: Bearer PUBLIC_KEY:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person_image": "https://yourcdn.com/user.jpg",
    "top_image": "https://yourcdn.com/top.jpg",
    "bottom_image": "https://yourcdn.com/jeans.jpg",
    "shoes_image": "https://yourcdn.com/trainers.jpg",
    "attributes": { "gender": "female", "notes": "" }
  }'

Request parameters

At least one garment image is required. Up to 4 garment images are combined into one outfit. You can also send a generic array: garments: [{ "src": "...", "label": "top" }].

Image requirements

• Formats: JPG, PNG, WEBP or GIF.
• Max size: 12 MB per image.
• Person photo: clear, well-lit, full or upper body facing the camera gives the best result.
• Garment photo: the product on a plain background (or a clean product shot) works best.
• URLs must be publicly reachable over HTTPS. Private, localhost and internal addresses are rejected for security.

Code examples

const res = await fetch("https://vrool.com/api/v1/fashion/makeover", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + PUBLIC_KEY + ":" + SECRET_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    person_image: "https://yourcdn.com/user.jpg",
    top_image: "https://yourcdn.com/top.jpg"
  })
});
const data = await res.json();
// The image is returned inline — store it on YOUR platform.
const bytes = Uint8Array.from(atob(data.image_base64), c => c.charCodeAt(0));
// e.g. upload `bytes` to your own storage, or use data.image_data_uri directly.

<?php
$ch = curl_init("https://vrool.com/api/v1/fashion/makeover");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer {$publicKey}:{$secretKey}",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "person_image" => "https://yourcdn.com/user.jpg",
    "top_image"    => "https://yourcdn.com/top.jpg",
  ]),
]);
$data = json_decode(curl_exec($ch), true);
// Save the returned image on YOUR platform:
file_put_contents("makeover." . $data["image_format"], base64_decode($data["image_base64"]));

import requests, base64

res = requests.post(
    "https://vrool.com/api/v1/fashion/makeover",
    headers={"Authorization": f"Bearer {public_key}:{secret_key}"},
    json={
        "person_image": "https://yourcdn.com/user.jpg",
        "top_image": "https://yourcdn.com/top.jpg",
    },
)
data = res.json()
# Save the returned image on YOUR platform:
with open(f"makeover.{data['image_format']}", "wb") as f:
    f.write(base64.b64decode(data["image_base64"]))

Responses

A successful call returns HTTP 200 with the generated image inline as base64. Vrool does not keep a copy — decode and store it on your own platform.

{
  "success": true,
  "request_id": 10432,
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "image_format": "png",
  "image_data_uri": "data:image/png;base64,iVBORw0KGgoAAA...",
  "credits_used": 1,
  "credits_remaining": 99,
  "mode": "sandbox",
  "time_ms": 8421
}

Errors return a non-2xx status with:

{
  "success": false,
  "error": { "code": "insufficient_credits", "message": "Not enough API credits. Please top up." }
}

Error codes

Credits are deducted before processing and automatically refunded if generation fails, so you are never charged for a failed generation.

Rate limits

• Per minute: 60 requests
• Per day: 5,000
• Per month: 100,000

Exceeding a limit returns HTTP 429. Enterprise accounts can request higher limits — contact support.

Signed requests optional

For extra security you can sign the raw request body with your secret using HMAC-SHA256 and send it as a header:

X-Vrool-Signature: base64(hmac_sha256(rawBody, SECRET_KEY))

<?php
$body = json_encode(["person_image" => $personUrl, "top_image" => $topUrl]);
$signature = base64_encode(hash_hmac("sha256", $body, $secretKey, true));
// send header:  X-Vrool-Signature: $signature

Signing is currently optional. Your account can require it for all traffic.

Buying credits

Each generation costs 1 credit (≈ £0.060). 5 free sandbox credits on signup. Buy credit packs securely by card in the Developer Portal — credits are added instantly.

Need higher volume or custom pricing? Contact Vrool for an enterprise plan.

Best practices

• Call the API only from your backend so your secret key stays private.
• Store the returned image on your own storage/CDN — Vrool does not retain it.
• Handle 429 responses with exponential backoff and retry.
• Watch credits_remaining and top up before you run out.
• Log request_id for every call to make support and reconciliation easy.
• Use an IP allowlist and key rotation from the portal for tighter security.

Support & versioning

This is API v1. Breaking changes will ship under a new version path so your integration keeps working.

Manage keys, credits and usage anytime in the Developer Portal: https://vrool.com/developers