API_Calls_Docs/curl_api_docs.md

# SM4LL-VTON Demo API – cURL Usage Guide

This document describes how to interact with the SM4LL-VTON Gradio app via HTTP API using `cURL` commands. The app exposes a `/gradio_api/call/generate` endpoint for programmatic access to the virtual try-on functionality.

---

## Base URL

This is the current deployed endpoint:
```
https://sm4ll-vton-sm4ll-vton-demo.hf.space/gradio_api/call/generate
```

---

## Main Endpoint: `/gradio_api/call/generate`

### Description
Submit a request to generate a virtual try-on result using a base image (person), a product image (garment), and a workflow type. Optionally, a mask image can be provided.

### HTTP Method
`POST`

### Endpoint

```
https://sm4ll-vton-sm4ll-vton-demo.hf.space/gradio_api/call/generate
```

It should be changed to the correct domain once a Gradio instance is working on YourMirror.io

### Request Format
- Content-Type: `application/json`
- Required fields in the `data` array:
  - `data[0]`: Base image (object: `{ "path": "<url or file path>", "meta": {"_type": "gradio.FileData"} }`)
  - `data[1]`: Product image (object: `{ "path": "<url or file path>", "meta": {"_type": "gradio.FileData"} }`)
  - `data[2]`: Workflow type (string: `eyewear`, `footwear`, `dress`, or `top`)
  - `data[3]`: Mask image (object as above, or `null` if not used)

### Example cURL Request
```
curl -X POST "https://sm4ll-vton-sm4ll-vton-demo.hf.space/gradio_api/call/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"path": "base_image_url.jpg", "meta": {"_type": "gradio.FileData"}},
      {"path": "product_image_url.jpg", "meta": {"_type": "gradio.FileData"}},
      "eyewear",
      null
    ]
  }'
```
- Replace `base_image_url.jpg` and `product_image_url.jpg` with the URLs or file paths to your images. (For local files, you must first upload them to a public URL or use Gradio's temp storage)
- For other workflow types, use `footwear`, `dress`, or `top` for `data[2]`.
- For the optional mask image, use the same object format as above, or set to `null`.

---

#### Accepted Workflow Types

Currently, the accepted workflow types and their corresponding models are:
- eyewear: sunglassesVTON
- footwear: footwearVTON
- dress: fullbodyVTON
- top: topgarmentVTON

Future available types and models will be:
- bottom: bottomgarmentVTON
- lookbook: lookbookVTON

---

## Response
- On success: Returns a JSON object with a `data` field containing a base64-encoded PNG image of the result.
- On error: Returns a JSON object with an `error` field describing the issue (e.g., rate limit, NSFW content, missing images).

---

### Example Success Response
```
{
  "data": [
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ],
  "is_generating": false, ...
}
```

### Example Error Response
```
{
  "error": "Product image contains inappropriate content. Please use a different image."
}
```

---

#### Requesting a processed result

To request a process result, you need to retrieve the event_id from the initial cURL request's responde.
For a XYZ event_id, you then need to construct a new cURL request:

```
curl -N "https://sm4ll-vton-sm4ll-vton-demo.hf.space/gradio_api/call/generate/XYZ"
```

The responde will be in the following form:

```
event: heartbeat
data: null

event: heartbeat
data: null

[...]

event: complete
data: [{"path": "path/to/tmp/gradio/storage", "url": "url/of/resulting/image", "size": null, "orig_name": "image.webp", "mime_type": null, "is_stream": false, "meta": {"_type": "gradio.FileData"}}]
```

You can then download the resulting image by using a new cURL command or any other way to download images from URLs, referencing the url/of/resulting/image obtained in the previous step via cURL -N. For example:

```
curl -o result.png "url/of/resulting/image"
```

---

#### With Optional Mask Image
```
curl -X POST "https://sm4ll-vton-sm4ll-vton-demo.hf.space/gradio_api/call/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"path": "base_image_url.jpg", "meta": {"_type": "gradio.FileData"}},
      {"path": "product_image_url.jpg", "meta": {"_type": "gradio.FileData"}},
      "dress",
      {"path": "mask_image_url.png", "meta": {"_type": "gradio.FileData"}}
    ]
  }'
```

---

## Notes
- **Rate Limiting:** Max 30 requests per IP per hour. Exceeding this will return an error.
- **NSFW Filter:** Product images are checked for explicit content and may be rejected.
- **Supported Formats:** JPG, JPEG, PNG, WEBP (GIF/AVIF not supported).
- **Authentication:** No authentication is required for public Hugging Face Spaces. If deployed privately, include the necessary headers/tokens.
- **Image Upload:** Images must be accessible via a public URL or sent to Gradio's temporary storage.