開發者 API

將圖像生成接入你的產品。

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.

Your backendVirtual Try On APIPrivate image

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 金鑰

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.

登入後即可建立和管理 API 金鑰。

快速開始

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.

POST /api/v1/images
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"
  }'
202 Accepted
{
  "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.

GET /api/v1/images/{id}
curl https://virtualtryon.art/api/v1/images/YOUR_TASK_ID \
  -H "Authorization: Bearer $VTO_API_KEY"
200 OK
{
  "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.

GET /api/v1/images/{id}/content?index=0
curl "https://virtualtryon.art/api/v1/images/YOUR_TASK_ID/content?index=0" \
  -H "Authorization: Bearer $VTO_API_KEY" \
  --output result.png

Server-side JavaScript

Use an environment variable and save the task ID in your application. Never expose the key to your visitors.

Node.js · server only
// 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.

請求欄位

FieldDescription
promptRequired. Instructions describing the image or edit; up to 5,000 characters.
reference_imagesOptional. Up to 16 public HTTPS image URLs; no private network or localhost URLs.
aspect_ratioOptional. Defaults to auto. Common values: 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9.
resolutionOptional. 1K, 2K, or 4K; defaults to 1K.
Idempotency-KeyRequired 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.

1K
1积分
2K
3积分
4K
5积分

回應與錯誤

A successful submission returns 202. Status is queued, processing, completed, or failed. Result URLs stay on this service and require your API key.

400Invalid request
401Missing, expired, or revoked key
402Insufficient credits
403Key does not have the required permission
404Task not found in your account
409Idempotency key already used with a different request
413Request body is too large
415Content-Type must be application/json
422Content policy requirements were not met
429Request or queue limit reached
503Service temporarily unavailable