--- name: tryonanytime description: Virtual try-on as a tool — put any garment onto any person photo and get the result image back. Use this whenever a user asks to see how clothing looks on someone, preview an outfit, or try a garment from any store, via the TryOnAnytime MCP server (preferred) or its REST API. --- # TryOnAnytime — Virtual Try-On for Agents TryOnAnytime turns two public image URLs — a person photo and a garment image — into one generated image of that person wearing that garment. It is exposed as an MCP server (preferred) and as a plain REST API. Every call is authenticated with the user's Bearer API key and charged in credits. Base URL for all examples below: `https://tryonanytime.com` ## When to use - The user asks how a piece of clothing would look on a person ("would this jacket suit me?", "show this dress on my photo"). - The user wants to preview an outfit before buying: a garment from any store or product page plus a person photo. - A shopping / fashion assistant flow needs a generated try-on image to show the user, not just text advice. - Any time you hold two public image URLs (person + garment) and need the composite try-on image back. ## When NOT to use - General image editing — background removal, face swap, style transfer, upscaling. The model only transfers a garment onto a person. - Video or live-camera try-on. This interface is strictly photo in, photo out, one image per call. - Images the server cannot fetch or must not process: non-public URLs (localhost, private networks, cloud metadata addresses — rejected by the SSRF guard), or photos you have no right to use. - Textual sizing / fit / measurement answers. The tool returns an image, not measurements or advice. ## Setup 1. The user signs in at `https://tryonanytime.com` and opens `/settings/apikeys` to create a **secret key** (it starts with `sk_`). The full key is shown at creation — store it immediately in the agent's secret/config store. (It is also kept server-side, encrypted at rest when the deployment sets `CONFIG_ENCRYPTION_KEY`, so the user can copy it again from the same page.) 2. New accounts receive free initial credits when the deployment enables them; verify with `get_credit_balance` (MCP) or `GET /api/v1/me` (REST). **Security red lines** — the `sk_` key is the user's credential and spends the user's money: - Never print it in chat output, logs, or error messages. - Never commit it to a repository or paste it into source code. - Never send it anywhere except `https://tryonanytime.com` over HTTPS, as an `Authorization: Bearer sk_…` header. - In config files, reference an environment variable (e.g. `${TRYONANYTIME_API_KEY}`), never the literal key. - Publishable `pk_` keys are refused by this API — only `sk_` works. ## Preferred: MCP server **Endpoint:** `POST https://tryonanytime.com/api/mcp` Transport: JSON-RPC 2.0 over a single HTTP POST (Streamable-HTTP style, request/response only). **There is no SSE stream** — `GET` and `DELETE` answer `405`. A single request object gets a single response object; a batch array gets an array; a body of only notifications gets `202 Accepted` with an empty body. Send `Content-Type: application/json` and no browser `Origin` header (this endpoint is server-to-server only). Protocol surface: `initialize` (protocol version `2025-03-26`, serverInfo `tryonanytime/1.0.0`), `ping`, `tools/list`, `tools/call`, and the `notifications/initialized` notification. Auth is `Authorization: Bearer sk_…` on every POST; a missing or bad key is the one non-200 transport failure: HTTP `401 {"error":"invalid_api_key"}`. Every JSON-RPC-level failure stays HTTP 200 with an `error` object. Client config snippet (MCP servers JSON): ```json { "mcpServers": { "tryonanytime": { "type": "http", "url": "https://tryonanytime.com/api/mcp", "headers": { "Authorization": "Bearer ${TRYONANYTIME_API_KEY}" } } } } ``` ### Tools Call them with `{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"","arguments":{…}}}`. A successful call returns `result.content`: an array of `text` and `image` content items (images are base64). **`virtual_tryon`** — run a try-on. Charges 10 credits to the key owner. - Arguments (`additionalProperties: false`): - `person_url` (string, uri, **required**) — public http(s) URL of the person photo. - `garment_url` (string, uri, **required**) — public http(s) URL of the garment image. - `prompt` (string, optional) — extra instruction for the model; trimmed to 500 characters. Default: put the garment onto the person, keep person, pose and background unchanged. - Returns `content`: a `text` item with `{"task_id":"…","status":"succeeded","demo":false}` and — when the result image is already stored (the normal case, generation is synchronous) — an `image` item `{ "type": "image", "data": "", "mimeType": "image/png" }`. **`get_tryon_result`** — status and result of a task this key created. - Arguments: `task_id` (string, **required**) — the id returned by `virtual_tryon`. - Returns `content`: a `text` item with `{"status":"processing|succeeded|failed","created_at":""}`; when `succeeded`, also the `image` item with the result as base64; when `processing`, a text hint to call again in a few seconds. - A task owned by another key is indistinguishable from a missing one: JSON-RPC error `-32602` with `data.code: "not_found"`. **`get_credit_balance`** — credit balance of the account that owns the API key. - Arguments: none. - Returns `content`: a `text` item with `{"credits": 123}`. ## Fallback: REST API v1 Same base URL, same `Authorization: Bearer sk_…` header. All JSON responses use the envelope `{ "code": 0, "message": "ok", "data": … }`; errors are `{ "code": -1, "message": "" }` with a matching HTTP status. **`POST /api/v1/tryon`** — run a try-on (10 credits). Two input modes: - `application/json`: `{"person_url": "…", "garment_url": "…", "prompt"?}` — the server fetches both images (SSRF-guarded). - `multipart/form-data`: `person=`, plus `garment=` **or** `garment_url=`; optional `prompt`. Success: `200` with `data: {"id", "status": "succeeded", "result_url": "/api/v1/tryon/{id}/result", "demo"}`. **`GET /api/v1/tryon/{id}`** — task status. `200` with `data: {"id", "status": "processing|succeeded|failed", "result_url", "created_at"}`. Only the key that created the task can read it — anything else is `404 not_found`. **`GET /api/v1/tryon/{id}/result`** — the result image bytes (`Content-Type: image/png` or the sniffed type, `inline` disposition). `404` when the task is not yours or has no stored result. **`GET /api/v1/me`** — key owner identity and balance: `data: {"email", "credits"}`. ## Rules - **Images:** jpeg, png or webp only, detected by magic bytes — the declared file extension or Content-Type is ignored. Maximum 10 MB per image. - **URL mode:** the server fetches the URLs itself. Only `http:`/`https:` URLs; loopback, private, link-local and reserved IPs (e.g. `169.254.169.254`) and internal hostnames (`localhost`, `*.internal`, `*.local`) are rejected by the SSRF guard → `400 invalid_image`. Redirects are followed manually, re-validated at every hop, max 5 hops. - **Rate limits:** try-on calls — 5 s minimum interval per API key owner and 2 s per IP. Read calls (status / result / me) — 500 ms per key owner, 1 s per IP. On `429`, honor the `Retry-After` header (seconds) before retrying; never retry in a tight loop. - **Cost:** each try-on costs **10 credits**, charged atomically to the account that owns the API key; if generation fails after the charge, the credits are revoked automatically. On `402 insufficient_credits`, tell the user to top up at `https://tryonanytime.com/pricing`. - **Ownership:** status and result are visible only to the key that created the task. A foreign or unknown id returns `404 not_found` — treat it as final, never as a transient error worth retrying. - **Typical workflow:** `get_credit_balance` → `virtual_tryon` → if the image content came back, done; otherwise poll `get_tryon_result` (or `GET /api/v1/tryon/{id}`) every 2 s until `succeeded`, and give up after ~90 s. - **`demo: true`** means the deployment ran in demo mode (no model key configured) and echoed the person image as the result — the call is still charged. Do not present a demo result as a real try-on. ## Errors HTTP layer (REST, and MCP transport): | Status | `message` / body | Meaning / action | | ------ | ----------------------------------- | ----------------------------------------------------------------------- | | 401 | `invalid_api_key` | Missing, wrong, revoked or `pk_` Bearer key. Fix the key; do not retry. | | 400 | `invalid_image` | Bad input: unsupported format, >10 MB, unfetchable URL, SSRF-blocked host. | | 402 | `insufficient_credits` | Not enough credits — user tops up at `/pricing`. | | 404 | `not_found` | Task unknown or owned by another key. Final. | | 429 | `too_many_requests` | Rate limited — wait `Retry-After` seconds. | | 503 | `unavailable` | Try-on not available in this deployment; retry later. | | 500 | `tryon_failed` / `server_error` | Generation or server failure; charged credits are revoked. | | 405 | (MCP only, empty) | `GET`/`DELETE` on `/api/mcp` — no SSE stream; use POST. | | 403 | `origin_not_allowed` (MCP only) | Browser `Origin` header refused — call server-to-server. | | 415 | `unsupported_content_type` (MCP) | Body must be `application/json`. | | 413 | `payload_too_large` (MCP) | JSON-RPC body over 1 MB. | JSON-RPC layer (MCP, always HTTP 200): | Code | `message` | When / `data.code` | | ------- | ----------------- | ------------------------------------------------------------------------------- | | -32700 | `parse_error` | Body is not valid JSON. | | -32600 | `invalid_request` | Not a valid JSON-RPC 2.0 request. | | -32601 | `method_not_found`| Unknown method or unknown tool (`data.code: "unknown_tool"`). | | -32602 | `invalid_params` | Bad tool arguments — `missing_arguments`, `invalid_url`, `invalid_prompt`, `missing_task_id`, or `not_found` (foreign/unknown task). Also `invalid_image` when a fetched URL fails the image rules (`data.code`: `invalid_url`, `blocked_host`, `fetch_failed`, `too_large`, `too_many_redirects`, `invalid_image`). | | -32603 | internal | `insufficient_credits` (top up at `/pricing`), `tryon_unavailable` (retry later), `tryon_failed` (credits revoked). |