Virtual Try-On API

Read these first — they shape how you integrate.

• Synchronous & long-running. The request does everything in one call — fetches your two images, runs the AI generation, stores the result, and returns the final image URL. There is no queue, job id, or polling.
• Generation takes ~10–60 seconds. The server keeps the connection alive up to 120s. Raise your HTTP client's read timeout (e.g. 180s) or it will give up before the image is ready.
• You send image URLs, not file uploads. Both input images must be publicly reachable over http/https. The server downloads them itself.
• Output is a hosted PNG URL. The API never returns base64 — you get a permanent URL to the generated .png.

Every request requires a Bearer API key in the Authorization header:

Authorization: Bearer bnto_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Keys look like bnto_live_<random>.
• Keys are shown once, at creation time — store yours securely.
• A missing, malformed, revoked, or unknown key returns 401.
• Treat the key as a secret: never embed it in client-side/browser code or commit it to source control. Call the API from your backend.

Send a JSON body to the endpoint with your two image URLs.

Body schema:

{
  "model_name": "tryon-v1.6",
  "inputs": {
    "model_image": "https://example.com/person.jpg",
    "garment_image": "https://example.com/garment.jpg"
  }
}

Both images must satisfy all of the following, or the request fails with image_fetch_failed (400):

Output aspect ratio

The output's aspect ratio matches the model_image, snapped to the nearest supported ratio (e.g. 1:1, 16:9, 9:16, 4:3, 3:4, 4:5). For predictable framing, crop your person photo to the aspect ratio you want before submitting.

Tips for best results

• Use a clear, well-lit, front-facing photo of the person.
• Use a clean garment reference (flat-lay or on a model) where the item is fully visible. The garment's background is discarded, so it doesn't need to be plain.
• If the garment image includes accessories (shoes, hats, belts, glasses, bags, jewelry), they may also be applied.
• A full-body garment (dress/jumpsuit) replaces both top and bottom; a "top" is layered appropriately.

Success → 200 OK

{
  "id": "tryon_V1StGXR8Z5jdHi6BmyT8x",
  "model_name": "tryon-v1.6",
  "output": {
    "image_url": "https://pub-xxxx.r2.dev/outputs/tryon_V1StGXR8Z5jdHi6BmyT8x.png"
  },
  "created_at": "2026-06-21T12:00:00Z"
}

All errors share one envelope:

{ "error": { "code": "invalid_api_key", "message": "Invalid API key." } }

Validation errors (422) additionally include a details array describing which fields failed.

Handling guidance

• 429 — read the Retry-After response header (seconds) and back off before retrying.
• generation_failed / content_blocked — usually input-related. Try a clearer person photo or a different garment; retrying an identical content_blocked request rarely helps.
• image_fetch_failed — verify the URL is public, returns an image, is under 10 MB, and resolves to a public host.
• internal_error / storage_failed — transient; safe to retry with backoff.

• Default: 60 requests per minute per API key (some keys may have a custom limit).
• Enforced with a rolling 60-second window.
• Exceeding it returns 429 with a Retry-After header telling you how many seconds to wait.

The generation can take up to ~60s — every example sets a generous client timeout (~180s) so the connection stays open until the image is ready.

curl --max-time 180 -X POST https://api.benitoai.com/v1/tryon \
  -H "Authorization: Bearer bnto_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "model_name": "tryon-v1.6",
        "inputs": {
          "model_image": "https://example.com/person.jpg",
          "garment_image": "https://example.com/garment.jpg"
        }
      }'

• ☐ Bearer API key set in the Authorization header.
• ☐ Both image URLs are public http/https and return a PNG/JPEG/WebP/GIF.
• ☐ Each image is under 10 MB and loads within 10s.
• ☐ Person photo cropped to your desired output aspect ratio.
• ☐ HTTP client read timeout set to ~180s.
• ☐ Retry/backoff logic for 429 (honor Retry-After) and 5xx.