Build with AI
AI coding assistants
Build the integration with Claude Code, Codex or Cursor.
Let Claude Code, Codex or Cursor write the integration for you. Two ways:
- Give it the docs. Every page has a Markdown version (add
.mdto the URL, or use Copy page at the top). The whole reference is also at /llms-full.txt. - Connect the MCP server so the assistant can read these docs and run real try-ons while it builds. See MCP server.
Where to put the instructions
| Assistant | Put the contract below in |
|---|---|
| Claude Code | CLAUDE.md in your project root |
| Codex | AGENTS.md in your project root |
| Cursor | .cursor/rules/tryoncloud.mdc, or paste into the chat |
| Any other | Paste into the chat |
Then ask: "Add TryOnCloud virtual try-on using the contract in CLAUDE.md" (or AGENTS.md). Keep your key in an environment variable such as TRYONCLOUD_API_KEY, never in the file.
The contract
text
You are integrating the TryOnCloud Developer API into my app.
ENDPOINT
POST https://www.tryoncloud.com/api/v1/generate
Test mode (free, nothing generated or stored): add ?mock=true
AUTH
Header X-API-KEY, read from env TRYONCLOUD_API_KEY (starts with tk_dev_v1_)
REQUEST: multipart/form-data OR JSON. Two images required:
garment_image (file) OR garment_url (public https URL) OR garment_base64
person_image (file) OR person_base64
JPEG, PNG, WebP or HEIC, up to 15MB each.
Optional: customer_id (my own end-user id, max 128 chars).
Optional header: Idempotency-Key (a new UUID per try-on; reuse it only
when retrying that same try-on, so it is never charged twice).
RESPONSE
200 -> the response BODY IS the finished try-on image (image/png).
Read it as bytes, do NOT JSON.parse it. Store it yourself.
Headers: X-Request-Id (log it), X-Credit-Was-Free, X-Result-Id
(only if result storage is enabled), X-Mock: 1 in test mode.
non-200 -> JSON { "error": string, "code": string }:
401 NO_KEY, INVALID_KEY | 400 BAD_INPUT, NO_PERSON, NO_GARMENT
402 NO_CREDITS, QUOTA_EXCEEDED, FREE_TRIAL_USED, KEY_LIMIT_REACHED
403 DEVICE_BANNED | 409 IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_REPLAY,
IDEMPOTENCY_MISMATCH (not charged)
413 IMAGE_TOO_LARGE | 422 CONTENT_FILTERED (refunded)
429 RATE_LIMITED (wait Retry-After) | 500 GENERATION_FAILED (refunded)
OTHER ENDPOINTS
GET https://www.tryoncloud.com/api/v1/credits -> { credits_remaining, ... }
DELETE https://www.tryoncloud.com/api/v1/results/<id> -> 204
Async (only if I ask for it): POST /api/v1/generations -> 202 job;
GET /api/v1/generations/<id>; POST /api/v1/batches (<= 500 URL items);
signed webhooks generation.completed / generation.failed / batch.completed
(verify x-tryoncloud-signature-v2 = HMAC-SHA256 of "<timestamp>.<raw body>").
Spec: https://www.tryoncloud.com/api/v1/openapi.json
RULES
- Call from my server only, never the browser; never expose the key.
- Client timeout 120 seconds; a typical result takes about 20 seconds.
- Build and test with ?mock=true first, then remove it.
- Retry 500 once and 429 after Retry-After. Never loop on 402.
- Only send photos of adults who agreed to the try-on.
Write production code for [MY STACK] that uploads two images, calls this
endpoint, handles every error code above, and saves/returns the PNG.Replace [MY STACK] with yours, for example "a Next.js route handler", "Laravel", "Django" or "Express".