Developer Docs

Examples

Browse documentation

Introduction

API Reference

Account & Billing

Resources

Examples
FAQ

Worked examples that go beyond a single request — submitting an asynchronous job and polling it to completion, and handling errors the way a production integration should.

Submit and poll an async job

A complete workflow for an AI-generative category (dress, in this case): submit the request, then poll the status endpoint every couple of seconds until it's no longer processing. For production use, prefer a webhook over polling where you can.

# 1. Submit the job
curl -s -X POST https://apionweb.com/v1/virtual-try-on \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "dress",
    "person_image": "https://example.com/person.jpg",
    "product_image": "https://example.com/dress.jpg"
  }'
# => { "request_id": "3af9c2e1-...", "status": "processing" }

# 2. Poll until it's done
curl -s https://apionweb.com/v1/virtual-try-on/3af9c2e1-... \
  -H "Authorization: Bearer YOUR_API_KEY"

<?php

function post(string $url, array $body): array
{
    $ch = curl_init($url);
    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($body),
    ]);

    return json_decode(curl_exec($ch), true);
}

function get(string $url): array
{
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
    ]);

    return json_decode(curl_exec($ch), true);
}

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

while (true) {
    $status = get("https://apionweb.com/v1/virtual-try-on/{$job['request_id']}");

    if ($status['status'] !== 'processing') {
        break;
    }

    sleep(2);
}

use Illuminate\Support\Facades\Http;

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

$result = null;

while (true) {
    $status = Http::withToken('YOUR_API_KEY')
        ->get("https://apionweb.com/v1/virtual-try-on/{$job['request_id']}")
        ->json();

    if ($status['status'] !== 'processing') {
        $result = $status;
        break;
    }

    sleep(2);
}

async function submit() {
  const res = 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: 'dress',
      person_image: 'https://example.com/person.jpg',
      product_image: 'https://example.com/dress.jpg',
    }),
  });

  return res.json();
}

async function pollUntilDone(requestId) {
  while (true) {
    const res = await fetch(`https://apionweb.com/v1/virtual-try-on/${requestId}`, {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
    });
    const status = await res.json();

    if (status.status !== 'processing') {
      return status;
    }

    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
}

const job = await submit();
const result = await pollUntilDone(job.request_id);

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

function request(method, path, body) {
  return new Promise((resolve, reject) => {
    const payload = body ? JSON.stringify(body) : undefined;
    const req = https.request(`https://apionweb.com${path}`, {
      method,
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
        ...(payload ? { 'Content-Length': Buffer.byteLength(payload) } : {}),
      },
    }, (res) => {
      let data = '';
      res.on('data', (chunk) => (data += chunk));
      res.on('end', () => resolve(JSON.parse(data)));
    });
    req.on('error', reject);
    if (payload) req.write(payload);
    req.end();
  });
}

(async () => {
  const job = await request('POST', '/v1/virtual-try-on', {
    category: 'dress',
    person_image: 'https://example.com/person.jpg',
    product_image: 'https://example.com/dress.jpg',
  });

  let status;
  do {
    await new Promise((resolve) => setTimeout(resolve, 2000));
    status = await request('GET', `/v1/virtual-try-on/${job.request_id}`);
  } while (status.status === 'processing');

  console.log(status);
})();

import time
import requests

HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

job = requests.post(
    "https://apionweb.com/v1/virtual-try-on",
    headers=HEADERS,
    json={
        "category": "dress",
        "person_image": "https://example.com/person.jpg",
        "product_image": "https://example.com/dress.jpg",
    },
).json()

while True:
    status = requests.get(
        f"https://apionweb.com/v1/virtual-try-on/{job['request_id']}",
        headers=HEADERS,
    ).json()

    if status["status"] != "processing":
        break

    time.sleep(2)

Branching on error codes

Handle each error meaningfully instead of showing a generic failure — see the full list on Errors.

Laravel

use Illuminate\Support\Facades\Http;

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

if ($response->failed()) {
    $code = $response->json('error.code');

    match ($code) {
        'insufficient_balance' => $this->promptUserToRecharge(),
        'rate_limit_exceeded' => $this->retryLater($response),
        'invalid_image', 'invalid_model' => $this->reportBadInput($response->json('error.message')),
        default => $this->logUnexpectedError($response->status(), $code),
    };

    return;
}

$result = $response->json();

Polling with backoff on rate limits

If you're polling frequently, back off when you hit 429 rate_limit_exceeded instead of retrying immediately — see Rate Limits.

Python

import time
import requests

def poll_with_backoff(request_id, headers, max_attempts=8):
    delay = 1

    for attempt in range(max_attempts):
        response = requests.get(
            f"https://apionweb.com/v1/virtual-try-on/{request_id}",
            headers=headers,
        )

        if response.status_code == 429:
            time.sleep(delay)
            delay = min(delay * 2, 30)
            continue

        data = response.json()

        if data.get("status") != "processing":
            return data

        time.sleep(2)

    raise TimeoutError("Try-on did not finish in time")