Skip to content
APIonWeb

Developer Docs

Responses

Browse documentation

Every successful call to /v1/virtual-try-on (and the status endpoint) returns JSON. The exact shape depends on whether the category is synchronous or still processing — see Virtual Try-On for which is which.

Synchronous success

Returned directly from the initial POST for real-time/3D categories, and from GET /v1/virtual-try-on/{request_id} once an async job finishes successfully:

200 OK 
{
  "request_id": "8f14e45f-2d1a-4b3c-9e4a-2f6b1c9d0e12",
  "status": "success",
  "category": "glasses",
  "result": {
    "image_url": "https://cdn.apionweb.com/results/8f14e45f....png"
  },
  "cost": {
    "amount": "0.05",
    "currency": "USD"
  },
  "processing_time_ms": 842
}
Field Description
request_id Unique id for this job. Use it to poll status or to match a webhook payload.
status processing, success, or failed.
category Echoes the category that was requested.
result.image_url URL of the rendered try-on image, once status is success.
cost.amount / cost.currency What this request was billed, only present when the result succeeded — see Usage & Billing.
processing_time_ms Server-side processing time in milliseconds.

Asynchronous: queued

For AI-generative categories, the initial POST returns immediately with just an id and a processing status:

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

Asynchronous: failed

If processing fails after the job was accepted (as opposed to being rejected outright at submission time), the status endpoint reports it with status: "failed" and an embedded error — this is never billed:

200 OK 
{
  "request_id": "3af9c2e1-7b4a-4d3e-9c1a-5e8f2b6d4a10",
  "status": "failed",
  "category": "shirt",
  "result": null,
  "cost": null,
  "error": {
    "code": "processing_failed",
    "message": "The try-on could not be generated from the provided images."
  }
}
A request that is rejected outright (bad auth, invalid input, insufficient balance) never reaches processing — it returns a non-2xx status with the standard error envelope instead. See Errors.