Search docs

Search the TryOnCloud API docs

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:

  1. Give it the docs. Every page has a Markdown version (add .md to the URL, or use Copy page at the top). The whole reference is also at /llms-full.txt.
  2. 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

AssistantPut the contract below in
Claude CodeCLAUDE.md in your project root
CodexAGENTS.md in your project root
Cursor.cursor/rules/tryoncloud.mdc, or paste into the chat
Any otherPaste 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".