Developer Docs

Virtual Try-On

Browse documentation

Introduction

API Reference

Account & Billing

Resources

Examples
FAQ

The Virtual Try-On API renders a product onto a photo of a person. One endpoint handles every supported category; the shape of the request body and how quickly you get a result both depend on which category you send.

POST /v1/virtual-try-on

GET /v1/virtual-try-on/{request_id}

Category	Engine	Processing	Image field
glasses, sunglasses, hats, jewelry, shoes	Real-time / 3D	Synchronous	product_model
shirt, tshirt, dress, jacket, pants, full_outfit	AI-generative	Asynchronous	product_image

Synchronous example — glasses

Real-time/3D categories (glasses, sunglasses, hats, jewelry, shoes) take a product_model URL and typically return the finished result in the same response:

curl -X POST https://apionweb.com/v1/virtual-try-on \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "glasses",
    "person_image": "https://example.com/person.jpg",
    "product_model": "https://example.com/glasses-model.glb"
  }'

<?php

$ch = curl_init('https://apionweb.com/v1/virtual-try-on');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'category' => 'glasses',
        'person_image' => 'https://example.com/person.jpg',
        'product_model' => 'https://example.com/glasses-model.glb',
    ]),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://apionweb.com/v1/virtual-try-on', [
        'category' => 'glasses',
        'person_image' => 'https://example.com/person.jpg',
        'product_model' => 'https://example.com/glasses-model.glb',
    ]);

$result = $response->json();

const response = await fetch('https://apionweb.com/v1/virtual-try-on', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    category: 'glasses',
    person_image: 'https://example.com/person.jpg',
    product_model: 'https://example.com/glasses-model.glb',
  }),
});

const result = await response.json();

const https = require('node:https');

const payload = JSON.stringify({
  category: 'glasses',
  person_image: 'https://example.com/person.jpg',
  product_model: 'https://example.com/glasses-model.glb',
});

const req = https.request('https://apionweb.com/v1/virtual-try-on', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(payload),
  },
}, (res) => {
  let data = '';
  res.on('data', (chunk) => (data += chunk));
  res.on('end', () => console.log(JSON.parse(data)));
});

req.write(payload);
req.end();

import requests

response = requests.post(
    'https://apionweb.com/v1/virtual-try-on',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'category': 'glasses',
        'person_image': 'https://example.com/person.jpg',
        'product_model': 'https://example.com/glasses-model.glb',
    },
)

result = response.json()

Asynchronous example — shirt

AI-generative categories (shirt, tshirt, dress, jacket, pants, full_outfit) take a product_image URL and are queued for processing. The initial POST returns immediately with a job id:

curl -X POST https://apionweb.com/v1/virtual-try-on \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "shirt",
    "person_image": "https://example.com/person.jpg",
    "product_image": "https://example.com/shirt.jpg",
    "webhook_url": "https://your-app.com/webhooks/apionweb"
  }'

<?php

$ch = curl_init('https://apionweb.com/v1/virtual-try-on');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'category' => 'shirt',
        'person_image' => 'https://example.com/person.jpg',
        'product_image' => 'https://example.com/shirt.jpg',
    ]),
]);

$job = json_decode(curl_exec($ch), true);
curl_close($ch);

// $job['request_id'] — poll GET /v1/virtual-try-on/{request_id}

use Illuminate\Support\Facades\Http;

$job = Http::withToken('YOUR_API_KEY')
    ->post('https://apionweb.com/v1/virtual-try-on', [
        'category' => 'shirt',
        'person_image' => 'https://example.com/person.jpg',
        'product_image' => 'https://example.com/shirt.jpg',
    ])
    ->json();

// $job['request_id'] — poll GET /v1/virtual-try-on/{request_id}

const response = await fetch('https://apionweb.com/v1/virtual-try-on', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    category: 'shirt',
    person_image: 'https://example.com/person.jpg',
    product_image: 'https://example.com/shirt.jpg',
  }),
});

const job = await response.json();
// job.request_id — poll GET /v1/virtual-try-on/{request_id}

const https = require('node:https');

const payload = JSON.stringify({
  category: 'shirt',
  person_image: 'https://example.com/person.jpg',
  product_image: 'https://example.com/shirt.jpg',
});

const req = https.request('https://apionweb.com/v1/virtual-try-on', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(payload),
  },
}, (res) => {
  let data = '';
  res.on('data', (chunk) => (data += chunk));
  res.on('end', () => {
    const job = JSON.parse(data);
    // job.request_id — poll GET /v1/virtual-try-on/{request_id}
  });
});

req.write(payload);
req.end();

import requests

job = requests.post(
    'https://apionweb.com/v1/virtual-try-on',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'category': 'shirt',
        'person_image': 'https://example.com/person.jpg',
        'product_image': 'https://example.com/shirt.jpg',
    },
).json()

# job['request_id'] — poll GET /v1/virtual-try-on/{request_id}

The response while the job is still running:

200 OK

{
  "request_id": "3af9c2e1-7b4a-4d3e-9c1a-5e8f2b6d4a10",
  "status": "processing"
}

Poll the status endpoint with the returned request_id until status is success or failed — or skip polling entirely by including a webhook_url in the original request (see Webhooks).

GET /v1/virtual-try-on/{request_id}

GET https://apionweb.com/v1/virtual-try-on/3af9c2e1-7b4a-4d3e-9c1a-5e8f2b6d4a10
Authorization: Bearer YOUR_API_KEY

Once finished, the status endpoint returns the same shape as a synchronous response:

200 OK

{
  "request_id": "3af9c2e1-7b4a-4d3e-9c1a-5e8f2b6d4a10",
  "status": "success",
  "category": "shirt",
  "result": {
    "image_url": "https://cdn.apionweb.com/results/3af9c2e1....png"
  },
  "cost": {
    "amount": "0.15",
    "currency": "USD"
  },
  "processing_time_ms": 6420
}

Full outfit

full_outfit combines several garments in one asynchronous request via a products array instead of a single image field:

application/json

{
  "category": "full_outfit",
  "person_image": "https://example.com/person.jpg",
  "products": [
    { "type": "shirt", "image": "https://example.com/shirt.jpg" },
    { "type": "pants", "image": "https://example.com/pants.jpg" }
  ]
}

person_image, product_model, and product_image are publicly reachable URLs, not uploaded files — host the image somewhere APIonWeb's servers can fetch it. See Requests for field details.

Next: Requests for full field-by-field detail, or Responses for the response schema.

Virtual Try-On

Categories

Synchronous example — glasses

Asynchronous example — shirt

Full outfit