API_GUIDE.md

# API Guide — Change Clothes in a Video

Space: **`kulkas2pintu/Video_to_video_WAN`**
Host: `https://kulkas2pintu-video-to-video-wan.hf.space`

Changes a person's clothing in a video from a text prompt:

1. trims the clip,
2. finds the frame where the person shows the most of their full body,
3. edits that frame's outfit with **FireRed** using your prompt,
4. re-inserts that re-clothed person into the video with **Wan 2.2 Animate**,
   keeping the original motion and scene.

---

## ZeroGPU quota — read this first

This Space runs on ZeroGPU. Quota is **not** wall-clock seconds — it depends on
the GPU size a call uses:

```
xlarge :  quota = declared_duration × 2      (full GPU)
large  :  quota = declared_duration × 1.5    (half GPU, 1.5× the wall time)
```

The FireRed step runs on a **separate Space** and the Wan step runs here. Both
are billed to **your** account, out of the same daily budget.

| Account | Daily quota | = real GPU seconds |
|---|---:|---:|
| Unauthenticated | 120 | 60 |
| **Free** | **300** | **150** |
| PRO | 2400 | 1200 |

Admission is checked against the *declared* duration, so the **tier** you pick
decides whether your call is even accepted:

| tier | FireRed (remote) | Wan (here) | Total | Free (300)? |
|---|---:|---:|---:|:--|
| **`free`** | ~19 s | 255 s (`large`) | **~274 s** | ✅ fits |
| `pro` | ~19 s | 500 s (`xlarge`) | ~519 s | ❌ rejected |

**A rejected call costs nothing** (no worker is spawned), so an over-quota
attempt is harmless — it just fails fast.

---

## Endpoints

| Endpoint | Purpose | GPU cost |
|---|---|---|
| `/quota_probe` | Reports what a run will reserve. | **0** (not a GPU call) |
| `/change_clothes` | Run the full pipeline. | see table above |

> `/quota_probe` used to be a real GPU call reserving 580 quota — which a free
> account could never pass. It is now a plain informational endpoint costing
> nothing, and it returns a **descriptive string, not `"ok"`**.

---

## `/change_clothes`

### Inputs (positional order)

| # | Name | Type | Required | Default | Notes |
|---|------|------|----------|---------|-------|
| 1 | `video` | video file | yes | — | Must be `{"video": handle_file(path_or_url), "subtitles": None}` — a bare `handle_file()` fails with a `VideoData` validation error. |
| 2 | `prompt` | `str` | yes | — | The new outfit, e.g. `"a red hoodie and black jeans"`. |
| 3 | `resolution_choice` | `"Low Res"` \| `"Medium Res"` | no | `"Low Res"` | `Low Res` = 640×368, `Medium Res` = 832×480. **Forced to Low Res when `tier="free"`.** |
| 4 | `tier` | `"free"` \| `"pro"` | no | `"free"` | Quota/quality profile — see below. |

`tier` was added last, so existing 3-argument callers keep working (they get
`"free"`).

### What each tier produces

| tier | clip out | frames | segment | steps | resolution |
|---|---|---:|---:|---:|---|
| `free` | **10.0 s** @ 8 fps | 80 | 81 | 5 | Low Res (forced) |
| `pro` | **9.5 s** @ 8 fps | 76 | 77 | 8 | your choice |

> There are **no** `seed` / `guidance_scale` parameters. FireRed's settings are
> fixed internally (4 steps, CFG 1.0, random seed).

### Outputs (in order)

| # | Name | Type | Notes |
|---|------|------|-------|
| 1 | `result` | video | The finished video (filepath). |
| 2 | `edited_reference_frame_firered` | image | The re-clothed still FireRed produced. |
| 3 | `status` | `str` (markdown) | Status, timings, and quota reserved. |

---

## Python (`gradio_client`)

```bash
pip install gradio_client
```

### Use `submit()`, not `predict()` — this is a long job

A run takes several minutes (CPU pose extraction, then the GPU stages, plus any
queue wait). `predict()` blocks the whole time and is easy to time out.

```python
import time
from gradio_client import Client, handle_file

client = Client("kulkas2pintu/Video_to_video_WAN", hf_token="hf_...")

# Optional: see what a run will reserve (costs nothing, returns a description)
print(client.predict("free", api_name="/quota_probe"))

job = client.submit(
    {"video": handle_file("my_clip.mp4"), "subtitles": None},   # 1 video
    "a red hoodie and black jeans",    # 2 prompt
    "Low Res",                         # 3 resolution_choice
    "free",                            # 4 tier
    api_name="/change_clothes",
)

while not job.done():
    print("status:", job.status().code)
    time.sleep(10)

video_path, ref_image, status = job.result()
print(status)
print("result video:", video_path)
```

`video_path` is a temp file the client downloaded — copy it somewhere permanent
if you want to keep it. `handle_file` also accepts a URL.

---

## JavaScript (`@gradio/client`)

```bash
npm i @gradio/client
```

```js
import { Client } from "@gradio/client";

const app = await Client.connect("kulkas2pintu/Video_to_video_WAN", {
  hf_token: "hf_...",
});

const videoBlob = new Blob([await (await fetch("my_clip.mp4")).arrayBuffer()]);

const out = await app.predict("/change_clothes", [
  videoBlob,                        // 1 video
  "a red hoodie and black jeans",   // 2 prompt
  "Low Res",                        // 3 resolution_choice
  "free",                           // 4 tier
]);

console.log(out.data); // [result video, reference image, status]
```

---

## Raw HTTP (curl)

```bash
HOST=https://kulkas2pintu-video-to-video-wan.hf.space
TOKEN=hf_...

# (0) upload the video, get its server path
FILE=$(curl -s -H "Authorization: Bearer $TOKEN" \
  -F "files=@my_clip.mp4" "$HOST/gradio_api/upload" \
  | python -c "import sys,json;print(json.load(sys.stdin)[0])")

# (1) start the job -> returns an event id   (NOTE: 4 data items)
EVENT=$(curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"data\":[{\"video\":{\"path\":\"$FILE\"},\"subtitles\":null},\"a red hoodie and black jeans\",\"Low Res\",\"free\"]}" \
  "$HOST/gradio_api/call/change_clothes" \
  | python -c "import sys,json;print(json.load(sys.stdin)['event_id'])")

# (2) stream the result
curl -s -N -H "Authorization: Bearer $TOKEN" "$HOST/gradio_api/call/change_clothes/$EVENT"
```

---

## Authentication

- The Space is public, but ZeroGPU is quota-metered per account.
- Pass an `hf_token`; GPU time is billed against **that token's account**.
- With `tier="free"`, a free account fits **one 10-second generation per day**
  (~274 of 300 quota). A second run that day will be rejected.
- With `tier="pro"` you need a PRO account (~519 quota per run of 2400/day).

---

## Errors you may hit

| Error | Meaning | What to do |
|---|---|---|
| `You have exceeded your ... quota (Xs requested vs Ys left)` | Not enough quota for the tier you chose. | Use `tier="free"`, or wait for the daily reset. Nothing was charged. |
| `'GPU task aborted'` | The GPU call exceeded its reserved time (or OOM'd). | Retry; report the `generate:` timing from the logs. |
| `AcceleratorError: uncorrectable ECC error` | The assigned ZeroGPU card is **faulty hardware**. | Restart the Space to re-schedule onto a healthy node. Not a code bug. |
| `FREE tier needs ...segment_frame_length...` | The installed diffusers build can't do the cheap free path. | Use `tier="pro"`, or pin `diffusers==0.39.0`. |
| HTTP `500` / `503` on the page | Container busy/restarting — normal for a heavy ZeroGPU Space. | Retry in a moment. |

---

## Notes & limits

- **Output is 8 fps.** Frame counts are capped so generation fits exactly one
  pipeline segment inside the ZeroGPU per-call time limit.
- **One person.** The pipeline picks the most full-body person frame.
- **Cold start** additionally downloads/loads model weights (several minutes).
- **Identity vs. realism.** Wan Animate regenerates the person from the
  reference, so the face can drift slightly and the background is re-rendered.
- Queue holds up to 20 jobs; GPU runs are serialized.