ClearMesh
Sign in Open Studio

ClearMesh product and API docs.

The current implementation is built around a web app, Vercel API proxy, authenticated sessions, billing hooks, library storage, and a GPU bridge ready for high-fidelity mesh generation.

Quickstart

Open /app, sign in with an email, enter a prompt or attach a public image URL, then submit a generation. The conversation returns an inline mesh viewer and opens a larger side editor for inspection and export.

Model bridge

The web layer treats generation as a provider-agnostic GPU bridge. Text-only prompts first generate a clean reference image, then the mesh worker turns that image into a GLB. The proxy keeps provider fields flexible so generation services can be swapped without rewriting the app UI.

API jobs

Submit generation requests through POST /v1/inference/jobs. Vercel normalizes every request to the current pipeline contract before billing or GPU submission, including the text-to-image reference stage, mesh generation, texture/UV pass, and edit metadata. Credits are reserved when the bridge accepts a job and refunded if the remote job reaches a failed or cancelled terminal state. The app polls GET /v1/inference/jobs/:id for status, artifact URLs, quality reports, and stored library metadata. When object storage is configured, Vercel also writes durable per-user job records with idempotent event history, available through GET /v1/inference/jobs. Job artifact URLs first stream live bridge bytes, then fall back to the stored library artifact after a successful mesh has been persisted.

Browser image references are stored through POST /v1/uploads?filename=reference.png. Send raw PNG, JPEG, or WebP bytes with the matching Content-Type; the API rejects unsupported formats and mismatched file signatures before storage. The response returns a signed /v1/uploads?action=file URL that can be passed into image-to-3D or edit jobs. Job reference URLs must be signed ClearMesh asset URLs or public HTTPS URLs; local, private-network, file, and data URLs are rejected before GPU submission.

  • mode: text_to_3d for prompt-only generation.
  • mode: image_to_3d for image-conditioned generation.
  • mode: edit_text or edit_image for feed-forward mesh edits.

API keys

Studio accounts can create API keys from /account. Use the returned token once as a scoped bearer credential for generation, uploads, and library reads or writes. Routes enforce the inference, uploads, and library scopes on API-key requests while signed-in browser sessions keep full account access.

Authorization: Bearer cmk_...

API keys are stored hashed, can be revoked from the account page, and are included as public metadata in account data exports without exposing the secret token.

Feed-forward editing

The editor sends a whole-mesh or part-targeted edit intent with object selection, local mask, material state, scene stats, recent editor operations, and an edit_brief. If an edit starts from a saved job, Vercel resolves the source mesh to a tokenized library artifact URL before submitting to the bridge, so edits can survive bridge restarts instead of relying only on in-memory job state.

Billing

The Vercel API exposes plan, subscription, quote, checkout, portal, webhook, and billing event routes. Quote and generation use the same credit estimator, canceled paid subscriptions fall back to the free effective tier until the billing provider marks them active again, and webhook deliveries are stored idempotently so retries or stale updates cannot overwrite newer subscription state.

Launch environment

A production deploy needs a small set of private backend credentials. Keep them in the host secret store, never in the browser bundle or public repository. The current web app runs on serverless API routes, uses durable object storage for account and mesh state, and sends generation work to a private GPU bridge; no separate SQL database is required for the current launch path.

  • Session signing secret, passwordless email credentials for browser accounts, and an optional private-beta access code as an invite gate.
  • Object storage credentials and bucket/prefix for uploads, durable jobs, generated meshes, API keys, billing events, and library artifacts.
  • GPU bridge URL and bearer token for real generation and feed-forward edits.
  • Billing secret, webhook secret, and paid-plan price IDs for checkout, portal, subscriptions, and credit limits.
  • Edge firewall and rate-limit policy for sign-in, uploads, generation, and attack-response handling.
  • Public app URL for checkout return links and same-origin session protections; production private exports and browser mutations require matching Origin or Referer headers.
  • Scoped smoke-test API keys for launch readiness probes.

Deploy health

Use GET /health or GET /api/health after every deploy. The endpoint reports whether session signing, browser auth method, private export and browser mutation security, object storage, uploads, edge protection, the inference GPU bridge, billing, and public return URLs are configured without exposing secret values.

For production launch sign-off, run scripts/product/run_static_ui_visual_smoke.py to capture pricing, Studio history, and mobile screenshots, then run scripts/product/check_production_readiness.py --strict with a visually approved generation bakeoff report that includes official reference mesh and preview evidence, plus the direct bridge and app E2E smoke reports. The strict check verifies public routes, Studio assets, authenticated inference config, visual quality approval, official-reference comparison evidence, and both smoke reports.

  • ok: true means production-critical checks are configured.
  • mode: preview means local preview meshes are explicitly enabled with CLEARMESH_ALLOW_LOCAL_PREVIEW=1 while the GPU bridge is missing.
  • mode: degraded means one or more production services need configuration, including the GPU bridge when preview is disabled.