Developer API
Image generation, inside your product.
Connect your backend to Virtual Try On with a dedicated API key. Create private images, follow their progress, and download results using the same account credits.
Keep your key on your server
Call this API from your own backend. Store the key in an environment variable. Do not put it in browser code, mobile app bundles, URLs, source control, or chat messages.
API keys
Create a separate key for each integration. Choose only the permissions it needs, set an expiry, and revoke it when access is no longer required. Keys cannot manage your billing or account profile.
Sign in to create and manage your API keys.
Quick start
1. Create an API key
Sign in below, give your integration a name, and copy the key when it appears. You can create up to five active keys.
2. Submit an image task
Use a new Idempotency-Key for each new image. To retry a request after a timeout, reuse that key with exactly the same body to avoid creating and charging for another task.
curl https://virtualtryon.art/api/v1/images \
-H "Authorization: Bearer $VTO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: store-order-1042" \
-d '{
"prompt": "Dress the person in the outfit from the second image.",
"reference_images": [
"https://your-store.com/person.jpg",
"https://your-store.com/outfit.jpg"
],
"aspect_ratio": "3:4",
"resolution": "1K"
}'{
"id": "YOUR_TASK_ID",
"status": "queued",
"credits": 1,
"status_url": "/api/v1/images/YOUR_TASK_ID",
"created_at": "2026-11-12T08:00:00.000Z"
}3. Poll for the result
Use the returned id to check progress. Poll about once every five seconds and stop at completed or failed.
curl https://virtualtryon.art/api/v1/images/YOUR_TASK_ID \
-H "Authorization: Bearer $VTO_API_KEY"{
"id": "YOUR_TASK_ID",
"status": "completed",
"images": ["/api/v1/images/YOUR_TASK_ID/content?index=0"]
}4. Download the image
When completed, download a URL from images using your API key. Download through your backend, then serve the file to your customer.
curl "https://virtualtryon.art/api/v1/images/YOUR_TASK_ID/content?index=0" \
-H "Authorization: Bearer $VTO_API_KEY" \
--output result.pngServer-side JavaScript
Use an environment variable and save the task ID in your application. Never expose the key to your visitors.
// Run on your server. Keep VTO_API_KEY in secret storage.
const response = await fetch("https://virtualtryon.art/api/v1/images", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.VTO_API_KEY,
"Content-Type": "application/json",
"Idempotency-Key": "store-order-1042",
},
body: JSON.stringify({
prompt: "A studio product photo of a linen shirt.",
aspect_ratio: "3:4",
resolution: "1K",
}),
});
const result = await response.json();
if (!response.ok) throw new Error(result.error?.message || "Request failed");
// Save result.id, then poll result.status_url from your backend.Authentication
Every API request, including result downloads, requires Authorization: Bearer YOUR_API_KEY. A website login cookie is not accepted by the public API.
Request fields
| Field | Description |
|---|---|
| prompt | Required. Instructions describing the image or edit; up to 5,000 characters. |
| reference_images | Optional. Up to 16 public HTTPS image URLs; no private network or localhost URLs. |
| aspect_ratio | Optional. Defaults to auto. Common values: 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9. |
| resolution | Optional. 1K, 2K, or 4K; defaults to 1K. |
| Idempotency-Key | Required header for creation. 1–128 letters, digits, periods, hyphens, or underscores. |
Requests accept only these fields. Task ownership, billing, and visibility are determined by the server.
Limits and credits
Each key allows 60 requests per minute, including status checks and downloads. At most 20 unfinished tasks may be queued per account. On 429, wait for Retry-After before retrying.
1K costs 1 credit, 2K costs 3 credits, and 4K costs 5 credits. API requests use your existing account balance and create private tasks.
Result downloads follow the same watermark entitlement as the website. Daily key budgets count accepted reservations and do not increase again after a refund.
Responses and errors
A successful submission returns 202. Status is queued, processing, completed, or failed. Result URLs stay on this service and require your API key.
| 400 | Invalid request |
|---|---|
| 401 | Missing, expired, or revoked key |
| 402 | Insufficient credits |
| 403 | Key does not have the required permission |
| 404 | Task not found in your account |
| 409 | Idempotency key already used with a different request |
| 413 | Request body is too large |
| 415 | Content-Type must be application/json |
| 422 | Content policy requirements were not met |
| 429 | Request or queue limit reached |
| 503 | Service temporarily unavailable |