# 3DPAKS

> Photorealistic packaging mockups rendered from a real specification —
> real millimetres, real dielines, real artwork — rather than a text
> prompt. Bottles, cans, cartons, pouches and bags, each backed by either
> a parametric generator or a licensed 3D mesh.

3DPAKS is built to be used by agents as well as people. Everything below
is a plain HTTP API — no browser session required to read the catalogue
or build a spec; a signed-in account with export credits is only needed
to produce a clean, full-resolution image instead of a watermarked
preview.

## Quick start for an agent

1. `GET /api/forms` — the full packaging catalogue (id, name, category, artwork canvas size).
2. `GET /api/schema` — JSON Schema for a scene spec.
3. `POST /api/scene` — turn a plain-language description into a scene spec.
4. Use the [MCP server](/mcp-server/) to actually render one — 3dpaks renders
   client-side (WebGL), so producing an image means driving a real browser,
   not calling a JSON endpoint. The MCP server does that for you.

## Auth & credits

- No password. `POST /api/auth/request-link` with an email sends (or, in
  an unconfigured dev deployment, returns) a one-time sign-in link.
- Once signed in via a browser, mint a long-lived API key with
  `POST /api/auth/api-key` — an agent authenticates with
  `Authorization: Bearer <token>` on every request from then on.
- `GET /api/me` reports whether the caller is signed in and its credit
  balance.
- Every export is a mockup — low-res, watermarked — unless the account
  has credits. `GET /api/credits/packs` lists what's for sale;
  `POST /api/credits/checkout` returns a Stripe Checkout URL. Buying
  credits is a real payment; this API never asks an agent to handle card
  details itself — it hands back a URL for a human to complete.

## API reference

| Endpoint | Method | Auth | Purpose |
| --- | --- | --- | --- |
| `/api/forms` | GET | none | Packaging catalogue |
| `/api/schema` | GET | none | Scene spec JSON Schema |
| `/api/defaults` | GET | none | The spec an empty session starts from |
| `/api/scene` | POST | none | Prompt → scene spec |
| `/api/auth/request-link` | POST | none | Start sign-in |
| `/api/auth/verify` | GET | none (consumes a link) | Finish sign-in, sets a session |
| `/api/auth/api-key` | POST / GET | session | Mint / list API keys |
| `/api/me` | GET | optional | Who's calling, credit balance |
| `/api/credits/packs` | GET | none | What's for sale |
| `/api/credits/checkout` | POST | session or key | Stripe Checkout URL |
| `/api/export/authorize` | POST | session or key | Spend a credit, authorize one clean export |

Full detail, request/response shapes and the MCP server itself:
[github.com/marcgough/3dpaks](https://github.com/marcgough/3dpaks) —
see `mcp-server/README.md`.

## What this is not

There is no server-side image-generation endpoint. `/api/scene` returns
a *specification* of a pack, not a picture of one — turning that into
pixels happens in a browser (the human's, or the MCP server's headless
one), because that is genuinely where the rendering happens; there is no
hidden faster path.