Endpoints

Upload image

Send an image file straight to Clothsy AI and get back an id. Use the id in place of an image URL when you create a try-on — no storage bucket or signed URLs needed on your side.

POSThttps://fabricvton-api.onrender.com/api/v1/images

Uploading is free: no credit is used. An uploaded image can be used by your account for 24 hours, in as many try-ons as you like. Uploading images explains when and why to use it.

Headers

Header	Type	Description
`Authorization`	required	`Bearer` followed by your API key.
`Content-Type`	required	`multipart/form-data`. Your HTTP client sets this, including the boundary, when you send a form.

Body

A multipart form with a single field:

Field	Type	Description
`file`	file, required	The image. JPEG or PNG, up to 4 MB. For a shopper photo, one adult, ideally full-length and facing the camera.

Example

curl

curl -X POST https://fabricvton-api.onrender.com/api/v1/images \
  -H "Authorization: Bearer $CLOTHSY_API_KEY" \
  -F "file=@shopper.jpg;type=image/jpeg"

Response

201 Created

{
  "id": "img_5Hq2mV8xKc3TnR7w",
  "expiresAt": "2026-10-01T09:30:00.000Z"
}

Field	Type	Description
`id`	string	Starts with `img_`. Send it as `personImageId` or `garmentImageId` when you create a try-on.
`expiresAt`	string	ISO 8601 time, 24 hours after the upload. After this the id stops working for good; upload the image again if you still need it.

Errors

Status	Code	When
400	`UNSUPPORTED_IMAGE`	The file isn't a JPEG or PNG.
401	`INVALID_API_KEY`	The key is missing, malformed or revoked.
413	`IMAGE_TOO_LARGE`	The file is larger than 4 MB. Resize it to about 1600 px and try again.
429	`RATE_LIMITED`	More than 30 uploads in a minute. Wait for the Retry-After header.
500	`INTERNAL_ERROR`	Something went wrong on our side. Retry after a moment.
503	`UNAVAILABLE`	The service is briefly unavailable. Retry after a short wait.

Every code is described in Errors & limits.