Virtual Try-On Endpoint | Help Center

Endpoint Overview

The Virtual Try-On endpoint (POST /v1/try-on) accepts a garment image and a model image and returns a composited try-on result. It is the programmatic equivalent of the Studio try-on workflow and supports all the same configuration options.

Authentication is required via a Bearer token in the Authorization header. See the API Authentication tutorial for details.

Request Format

Send a multipart/form-data request with the following fields: garment_image (file), model_image (file or preset ID), quality (draft | standard | premium), and optional fit and pose parameters.

You can also pass image URLs instead of files by using the garment_url and model_url fields, which avoids the need to upload binary data.

Response Format

A successful response returns a JSON object with status, result_url (a signed URL valid for 24 hours), processing_time_ms, and metadata containing dimensions and quality tier used.

For asynchronous processing (large batches), the endpoint returns a job_id instead and you can poll GET /v1/jobs/{job_id} or configure a webhook to receive the result.

Code Examples

Below is a minimal cURL example:

curl -X POST https://api.huhu.ai/v1/try-on \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "garment_image=@shirt.png" \
  -F "model_image=preset:female-01" \
  -F "quality=standard"

SDKs for Python, Node.js, and Ruby wrap this endpoint with typed helpers. Install via pip install huhuai or npm install @huhuai/sdk.

Error Handling

Common errors include 400 Bad Request (missing required field), 413 Payload Too Large (image exceeds 20 MB), and 429 Too Many Requests (rate limit exceeded). Always check the error.code and error.message fields in the response body for actionable detail.