{"openapi":"3.1.0","info":{"title":"TryOnCloud Virtual Try-On API","version":"1.0.0","summary":"Send a garment and a person photo, get the finished try-on image back in the same response.","description":"Synchronous by default: one POST /generate returns the PNG. Async jobs, batches of up to 500 and signed webhooks are also available. Photos are processed in memory and not stored unless result storage is enabled on your account. Credits never expire; failed try-ons are refunded. Docs: https://www.tryoncloud.com/docs","contact":{"name":"TryOnCloud","email":"info@tryoncloud.com","url":"https://www.tryoncloud.com/contact"},"termsOfService":"https://www.tryoncloud.com/terms"},"servers":[{"url":"https://www.tryoncloud.com/api/v1"}],"security":[{"ApiKey":[]}],"tags":[{"name":"Try-on"},{"name":"Async"},{"name":"Account"},{"name":"Service"}],"paths":{"/generate":{"post":{"tags":["Try-on"],"operationId":"generateTryOn","summary":"Generate a try-on","description":"Returns the finished image (PNG, about 1 megapixel) as the response body. Set your client timeout to 120 seconds. One successful try-on uses one credit; failed generations are refunded.","parameters":[{"name":"mock","in":"query","required":false,"schema":{"type":"boolean"},"description":"Test mode: validates everything, generates nothing, charges nothing. Returns the person image as PNG."},{"name":"X-Mock","in":"header","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"Same as ?mock=true."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7e]+$"},"description":"Your unique value for this request. A retry with the same key is never charged twice. Kept 24 hours. Reusing it with different images returns IDEMPOTENCY_MISMATCH."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"garment_image":{"type":"string","format":"binary","description":"Garment photo file."},"garment_url":{"type":"string","format":"uri","description":"Public https image URL, fetched server-side."},"person_image":{"type":"string","format":"binary","description":"Shopper photo file."},"person_base64":{"type":"string","description":"Shopper photo as base64, with or without a data: prefix."},"customer_id":{"type":"string","maxLength":128,"description":"Your own end-user id, for search and DELETE /customers/{id}."}},"description":"Send garment_image or garment_url, and person_image or person_base64."}},"application/json":{"schema":{"type":"object","properties":{"garment_url":{"type":"string","format":"uri"},"garment_base64":{"type":"string"},"person_base64":{"type":"string"},"customer_id":{"type":"string","maxLength":128}},"required":["person_base64"],"description":"Send garment_url or garment_base64, plus person_base64."}}}},"responses":{"200":{"description":"The finished try-on image.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-Credit-Was-Free":{"schema":{"type":"string","enum":["0","1"]},"description":"1 if the free allowance was used."},"X-Result-Id":{"schema":{"type":"string","format":"uuid"},"description":"Only when result storage is enabled. Use with DELETE /results/{id}."},"X-Mock":{"schema":{"type":"string","enum":["1"]},"description":"Present on test-mode responses."}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid input. Codes: BAD_INPUT, NO_PERSON, NO_GARMENT, BAD_IDEMPOTENCY_KEY.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key. Codes: NO_KEY, INVALID_KEY.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Out of credits or allowance, or the key reached its monthly limit. Codes: NO_CREDITS, QUOTA_EXCEEDED, FREE_TRIAL_USED, KEY_LIMIT_REACHED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Device blocked. Codes: DEVICE_BANNED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict. Nothing was charged. Codes: IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_REPLAY, IDEMPOTENCY_MISMATCH.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Image too large (15MB max). Codes: IMAGE_TOO_LARGE.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Blocked by content moderation. Refunded. Codes: CONTENT_FILTERED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Retry after the Retry-After seconds. Codes: RATE_LIMITED.","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Generation failed. Refunded; retry once. Codes: GENERATION_FAILED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits":{"get":{"tags":["Account"],"operationId":"getCredits","summary":"Check credits","responses":{"200":{"description":"Balance.","content":{"application/json":{"schema":{"type":"object","properties":{"credits_remaining":{"type":"integer","description":"Try-ons you can run now. Use this one."},"purchased_remaining":{"type":"integer"},"purchased_total":{"type":"integer"},"free_remaining":{"type":"integer"},"spends_from":{"type":"string","enum":["purchased","free_allowance"]}}}}}},"401":{"description":"Missing or invalid key. Codes: NO_KEY, INVALID_KEY.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (60 per minute per key). Codes: RATE_LIMITED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Temporary problem, retry. Codes: CREDITS_UNAVAILABLE.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/results/{id}":{"get":{"tags":["Account"],"operationId":"getResult","summary":"Download a stored result","description":"Results of async jobs and batches are kept 7 days; /generate results only when result storage is on.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The PNG.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not found or expired. Codes: NOT_FOUND.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Account"],"operationId":"deleteResult","summary":"Delete a stored result","description":"Only relevant when result storage is enabled (results are otherwise never stored). Stored results expire after 7 days anyway.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted (or already gone)."},"401":{"description":"Missing or invalid key. Codes: NO_KEY, INVALID_KEY.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found for this account. Codes: NOT_FOUND.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120 per minute per key). Codes: RATE_LIMITED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Delete failed, retry. Codes: DELETE_FAILED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generations":{"post":{"tags":["Async"],"operationId":"createGeneration","summary":"Start an async try-on","description":"Returns 202 with a job. Same image inputs as /generate plus person_url, customer_id, metadata and webhook_url. Purchased credits only; refunded on failure. Idempotency-Key returns the original job on retry.","parameters":[{"name":"mock","in":"query","required":false,"schema":{"type":"boolean"},"description":"Free test job that completes without a render."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/GenerationInput"}},"application/json":{"schema":{"$ref":"#/components/schemas/GenerationInput"}}}},"responses":{"200":{"description":"Idempotent replay: the job created by the first request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"202":{"description":"Job created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"400":{"description":"Invalid input. Codes: BAD_INPUT, NO_PERSON, NO_GARMENT, BAD_WEBHOOK_URL, BAD_IDEMPOTENCY_KEY.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key. Codes: NO_KEY, INVALID_KEY.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Credits or key limit. Codes: ASYNC_NEEDS_CREDITS, NO_CREDITS, KEY_LIMIT_REACHED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict. Codes: IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_MISMATCH.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Image too large. Codes: IMAGE_TOO_LARGE.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited or too many running jobs. Codes: RATE_LIMITED, TOO_MANY_JOBS.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generations/{id}":{"get":{"tags":["Async"],"operationId":"getGeneration","summary":"Get an async try-on","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"404":{"description":"Not found for this account. Codes: NOT_FOUND.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batches":{"post":{"tags":["Async"],"operationId":"createBatch","summary":"Start a batch of up to 500 try-ons","description":"Items use public https URLs. One credit per item is taken up front (all or nothing) and refunded for failed or cancelled items.","parameters":[{"name":"mock","in":"query","required":false,"schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","required":["garment_url","person_url"],"properties":{"garment_url":{"type":"string","format":"uri"},"person_url":{"type":"string","format":"uri"},"customer_id":{"type":"string","maxLength":128},"metadata":{"type":"object"}}}},"webhook_url":{"type":"string","format":"uri"}}}}}},"responses":{"202":{"description":"Batch created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"400":{"description":"Invalid input. Codes: BAD_INPUT, BATCH_TOO_LARGE, BAD_WEBHOOK_URL.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Credits or key limit. Codes: ASYNC_NEEDS_CREDITS, NO_CREDITS, KEY_LIMIT_REACHED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batches/{id}":{"get":{"tags":["Async"],"operationId":"getBatch","summary":"Get a batch and its items","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The batch with every item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"404":{"description":"Not found for this account. Codes: NOT_FOUND.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Async"],"operationId":"cancelBatch","summary":"Cancel items that have not started","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cancelled; credits refunded for cancelled items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"404":{"description":"Not found for this account. Codes: NOT_FOUND.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{customer_id}":{"delete":{"tags":["Account"],"operationId":"deleteCustomerData","summary":"Delete everything stored for one end user","parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"results_deleted":{"type":"integer"},"records_cleared":{"type":"integer"}}}}}},"500":{"description":"Some results could not be deleted; nothing was cleared. Retry. Codes: DELETE_FAILED.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/status":{"get":{"tags":["Service"],"operationId":"getStatus","summary":"Service status and recent speed","security":[],"responses":{"200":{"description":"Live service figures from real API traffic.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"window_hours":{"type":"integer"},"requests":{"type":"integer"},"success_rate":{"type":["number","null"]},"p50_ms":{"type":["integer","null"]},"p90_ms":{"type":["integer","null"]},"updated_at":{"type":"string","format":"date-time"}}}}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Your developer key, tk_dev_v1_... Keep it on your server."}},"schemas":{"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Human-readable message. Do not branch on it."},"code":{"type":"string","description":"Stable machine code. Branch on this."},"request_id":{"type":"string","description":"Same as the X-Request-Id header. Quote it to support."}}},"GenerationInput":{"type":"object","properties":{"garment_image":{"type":"string","format":"binary"},"garment_url":{"type":"string","format":"uri"},"garment_base64":{"type":"string"},"person_image":{"type":"string","format":"binary"},"person_url":{"type":"string","format":"uri"},"person_base64":{"type":"string"},"customer_id":{"type":"string","maxLength":128},"metadata":{"type":"object","description":"JSON object up to 2KB (a JSON string in multipart)."},"webhook_url":{"type":"string","format":"uri"}}},"Generation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"generation"},"status":{"type":"string","enum":["queued","processing","completed","failed","cancelled"]},"mock":{"type":"boolean"},"batch_id":{"type":["string","null"],"format":"uuid"},"customer_id":{"type":["string","null"]},"metadata":{"type":["object","null"]},"result_id":{"type":["string","null"]},"result_url":{"type":["string","null"],"format":"uri"},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}},"Batch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"batch"},"status":{"type":"string","enum":["processing","completed"]},"total":{"type":"integer"},"completed":{"type":"integer"},"failed":{"type":"integer"},"cancelled":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Generation"}},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}}},"headers":{"RequestId":{"schema":{"type":"string"},"description":"Unique id of this request. Quote it to support."},"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed per minute for this key (300) or account (600), whichever is tighter."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in the current minute."}}}}