CountertopSwap for AI agents

CountertopSwap accepts a photo of a kitchen or bathroom and a material description. It returns a photorealistic image with the countertop, island top, and matching backsplash replaced — while preserving cabinets, appliances, lighting, and perspective. This tool can be used by AI agents to deliver instant visualization inside contractor sales flows, interior design assistants, renovation planners, and fabricator quoting tools.

The render endpoint requires an API key. Sign in to CountertopSwap, then visit /api-keys to create one. Pass the key in the x-api-key header on every request. Keys are revocable at any time. The full key value is shown only once at creation — store it in your secrets manager.

x-api-key: cts_live_a1b2c3...

Each successful render consumes 1 credit from the key owner's balance. Failed renders are automatically refunded. New accounts get 1 free trial credit. Top up at /billing ($5 for 20 renders, $15 for 100 renders, or $29/month unlimited Pro).

Track usage in real time on the /api-keys page — every request appears in the usage log with timestamp, endpoint, status, credits used, and any error message.

Use the unauthenticated health endpoint to verify the service is reachable before issuing render calls. No API key, no credits.

GET https://urbdulnhxberioelwleo.supabase.co/functions/v1/health

{
  "status": "ok",
  "service": "CountertopSwap Render API",
  "version": "1.1.0",
  "timestamp": "2026-04-25T12:00:00.000Z"
}

POST https://urbdulnhxberioelwleo.supabase.co/functions/v1/render-api

CORS is enabled for all origins. Rate-limited to 30 requests per key per hour. Supports automated visualization requests from server-side or browser agents.

curl -X POST https://urbdulnhxberioelwleo.supabase.co/functions/v1/render-api \
  -H "x-api-key: cts_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/my-kitchen.jpg",
    "material": "calacatta quartz with soft gold veining"
  }'

For agents that already hold an image as a binary file:

curl -X POST https://urbdulnhxberioelwleo.supabase.co/functions/v1/render-api \
  -H "x-api-key: cts_live_YOUR_KEY" \
  -F "image=@./kitchen.jpg" \
  -F "material=absolute black granite, polished"

{
  "result_url": "https://urbdulnhxberioelwleo.supabase.co/storage/v1/object/public/render-results/api-render/abc123.png",
  "material": "calacatta quartz with soft gold veining",
  "credits_used": 1,
  "render_id": "abc123-..."
}

All errors return JSON with a stable error code and a human-readable message. Example:

{
  "error": "insufficient_credits",
  "message": "Your account has no remaining render credits. Top up at https://countertopswap.com/billing"
}

• 401 missing_api_key — no x-api-key header sent.
• 401 invalid_api_key — key not recognized or revoked.
• 402 insufficient_credits — balance is 0; top up at /billing.
• 400 invalid_image — image_url missing, unreachable, not an image, or larger than 12MB.
• 400 invalid_material — material missing or not 2–300 characters.
• 400 unsupported_material — material doesn't reference a supported stone type. Response includes a supported array.
• 429 rate_limit_exceeded — more than 30 requests in the last hour for this key.
• 502 render_failed — upstream AI failure; credit auto-refunded.

quartz, granite, marble, quartzite, porcelain, soapstone, concrete, butcher block, wood, limestone, travertine, onyx, slate. The material string can be descriptive (e.g. "calacatta quartz with soft gold veining"), as long as it references one of these types.

• /openapi.json — full OpenAPI 3.0 spec with auth + error schemas.
• /.well-known/ai-plugin.json — ChatGPT-style plugin manifest.
• /.ai-capabilities.json — agent capability descriptor.
• /llms.txt — plain-text site summary.

CountertopSwap is built to be MCP-ready. The OpenAPI spec, plugin manifest, and capability file together let any agent framework (Model Context Protocol, ChatGPT plugins, custom LangChain or LlamaIndex tools) auto-discover the render capability and call it as a tool. As MCP server hosting matures we will expose the same render capability over an MCP transport at a stable URL.

• Source images: JPEG or PNG, max 12MB.
• Rate limit: 30 requests / API key / hour.
• Generated images are hosted on CountertopSwap's CDN.
• Do not submit images of people without consent. Do not use for unlawful purposes.