API Reference
Programmatic access to StencilCut for agents, MCP servers, and scripts. Every request is authenticated with an API key created on the API keys page and consumes credits from the key owner's account — generation costs 1 credit per job, exactly like the web builder.
Base URL & authentication
https://laserart-api.ameerbaker2.workers.dev Authorization: Bearer lsr_live_YOUR_KEY
Keys can carry a monthly quota (set at creation). When a quota is exhausted the API returns 429; revoked keys return 401. Requests to endpoints outside your key's scope return 403.
Quick start
# 1. Start a generation job
curl -X POST https://laserart-api.ameerbaker2.workers.dev/v1/generate \
-H "Authorization: Bearer lsr_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"geometric mountain","style":"STENCIL","category":"abstract-geometric"}'
# → { "jobId": "..." }
# 2. Poll until completed (or subscribe to /v1/jobs/:id/stream for SSE)
curl https://laserart-api.ameerbaker2.workers.dev/v1/jobs/JOB_ID \
-H "Authorization: Bearer lsr_live_YOUR_KEY"
# → { "state": "completed", "result": { ... base64 designs, SVG, readiness ... } }Endpoints
| Endpoint | Scope | Description |
|---|---|---|
| POST /v1/generate | generate | Start an AI generation job (same payload as the web builder). Returns { jobId }. Costs 1 credit. |
| GET /v1/jobs/:id | generate | Poll a job for state and the full result payload once completed. |
| GET /v1/jobs/:id/stream | generate | Server-sent events stream of job progress (queued → processing → completed). |
| POST /v1/analyze-image | analyze | Detect subjects in an uploaded photo (person, pet, …) with bounding boxes. |
| POST /v1/remove-bg | generate | Remove the background from an uploaded image. |
| POST /v1/vectorize | vectorize | Trace a raster image into SVG. |
| POST /v1/vectorize-selection | vectorize | Vectorize a selected variant image (base64 PNG in, SVG job out). |
| POST /v1/export/dxf | export | Convert a design to DXF (R12/AC1009, mm-scaled). |
| POST /v1/keychain-outline | export | Generate an offset cut outline (optionally with a keychain ring) around a design. |
| POST /v1/history/save | history | Save a finished generation to the account's design history. |
| GET /v1/history | history | List the account's saved designs. |
| GET /v1/history/:id/load | history | Load one saved design with its variants. |
| GET /v1/health | — | Unauthenticated health check. Returns { ok: true }. |
History designs also support export-dxf, update-variant, select-variant, cache-svg, rename (PATCH/POST on /v1/history/:id/…) and DELETE /v1/history/:id.
Credits & failures
- 1 credit per AI generation job. SVG and DXF exports of finished designs are free.
- Credits are auto-refunded when a job fails with a server error.
- Generated designs are the same laser-ready output as the web builder: bridged, mm-sized SVG/DXF.
Questions or missing endpoints? [email protected]