Endpoints

VoxelAI Studio generates models with an agentic LLM pipeline: the model reasons about your prompt and drives the editor’s own tools — creating layers, defining materials, and placing voxels with primitives and boolean operations — then returns a clean, layered, fully-editable result. There are two endpoints for it, differing only in how the result is delivered:

• POST /api/generate/model — streaming (Server-Sent Events). Used by the web app to render the build live.
• POST /api/generate/roblox — buffered (one JSON response). Used by the Roblox plugin and recommended for any non-streaming client or agent.

Both cost 3 tokens, charged up front and refunded if the build errors, is aborted, or comes back empty. All endpoints require authentication.

For agents: this is the whole generation API

Model generation is synchronous — you send a prompt and get the finished model back (streamed or buffered). There is no job to submit and poll. If you are looking for an image-to-3D / “generate then voxelize” flow, that pipeline is deprecated — see the note at the bottom of this page. Don’t build against it.

---

Agentic Model Generation (SSE)

Builds a clean, layered, fully-editable voxel model from a text prompt. The request holds open for the few seconds the build takes, and each applied operation is pushed to you over Server-Sent Events so you can render the model assembling live. Costs 3 tokens (charged up front, refunded on error / abort / empty).

POST /api/generate/model

Request Parameters

Parameter	Type	Required	Description
prompt	string	Yes	What to build. Max 500 characters.
startMaterialId	integer	No	First material id to assign. Default: 1.
bounds	[w,h,d]	No	Soft size hint per axis; each value is clamped to 256.
symmetry	boolean	No	Hint the agent to build symmetrically. Default: false.
pro	boolean	No	Opt into the stronger model. Paid plans only — ignored on free plans.
priorOps	Op[]	No	Operations from an earlier build, replayed server-side to seed a modification (the “modify” flow). Capped at 2000.

Response — text/event-stream

The response is a stream of named SSE events:

event: op
data: {"op":{...},"result":{...}}        // one per applied build operation

event: done
data: {"summary":"...","title":"Crystal Tree","description":"...","tags":["voxel","tree"],"totalVoxels":1840,"balance":1}

event: error
data: {"error":"...","refunded":true}

• op — emitted for every operation the agent applies. Accumulate these to drive a live preview and to keep as the priorOps for a later modification.
• done — terminal success. Carries the finished voxel count, the post-spend balance, and the finish-tool metadata.
• error — terminal failure (including an empty build, EMPTY_MODEL). The refunded flag confirms the tokens were returned.

If the client disconnects mid-build, the server aborts the loop and refunds.

---

Buffered Generation — /api/generate/roblox

The non-streaming sibling of /api/generate/model. It runs the exact same agentic build to completion, then returns the resolved result as a single JSON document instead of an SSE stream — for clients that can’t read a streaming response body (notably Roblox Studio’s HttpService, but also any simple request/response agent). It costs 3 tokens with the same charge-up-front / refund-on-failure behavior, and always uses the base model (the pro toggle is web-only).

This is the recommended endpoint for non-streaming agents and the one the Roblox Studio plugin calls with its vxlrbx_ token. Despite the name, nothing about it is Roblox-specific — the response is plain voxels and materials.

POST /api/generate/roblox

Request Parameters

Parameter	Type	Required	Description
prompt	string	Yes	What to build. Max 500 characters.
mode	string	No	Reserved client hint (e.g. target output kind).
startMaterialId	integer	No	First material id to assign. Default: 1.
bounds	[w,h,d]	No	Soft size hint per axis; each clamped to 256.
symmetry	boolean	No	Build symmetrically. Default: false.
priorOps	Op[]	No	Replayed ops to seed a modification. Capped at 2000.

Response

A flat voxel list plus the material palette, ready to instantiate directly. All models share origin [0,0,0], so coordinates are consistent across the list.

{
  "summary": "A small crystal tree",
  "totalVoxels": 1840,
  "balance": 1,
  "voxels": [
    { "x": 0, "y": 0, "z": 0, "materialId": 1 }
  ],
  "materials": [
    {
      "id": 1,
      "name": "Bark",
      "hex": "#6b4f2a",
      "roughness": 0.8,
      "metallic": 0.0,
      "emissive": 0,
      "emissiveIntensity": 0
    }
  ],
  "ops": [ /* the build ops, for an optional client-side replay */ ]
}

An empty build returns 422 with { "refunded": true } (code: EMPTY_MODEL); if model generation isn’t configured server-side you get 503.

---

Finish-tool metadata

The agentic build ends when the AI calls its finish tool, which emits gallery and SEO metadata alongside the model. These fields appear in the done SSE event (for /model) and are consumed by /api/generate/save:

Field	Description
summary	A short natural-language summary of what was built.
title	A concise gallery title (≤ 6 words).
description	A 1–2 sentence description mentioning voxel art.
tags	4–8 lowercase discovery keywords.

---

Common Errors

• 400 Bad Request: Invalid request body or an empty/oversized prompt.
• 401 Unauthorized: Missing, expired, or invalid authentication token.
• 402 Payment Required: Out of tokens (code: "INSUFFICIENT_TOKENS"), or an adult/violent prompt on a free plan (code: "ADULT_CONTENT_PAID_ONLY").
• 403 Forbidden: No token balance found for the account (code: "NO_BALANCE").
• 422 Unprocessable Entity: The build produced no voxels (code: "EMPTY_MODEL"); the charge is refunded.
• 429 Too Many Requests: A per-endpoint rate limit was exceeded.
• 503 Service Unavailable: Agentic model generation isn’t configured on the server.

Generation uses charge-up-front, refund-on-failure billing. A build that fails or comes back empty has its tokens refunded exactly once, so a failed or abandoned generation never costs you anything.

---

Deprecated: image-to-3D (RunPod) pipeline

Deprecated — do not use

The endpoints in this section (/api/generate/images, /api/generate/voxelize, /api/generate/status) were the old two-step image→mesh pipeline that ran on RunPod GPU workers. It is deprecated and no longer part of the product. All generation now goes through the agentic endpoints above.

If you are an agent or building an integration, stop here — use /api/generate/model or /api/generate/roblox. This section is retained only as a historical/migration reference and may be removed.

The old flow was asynchronous: POST /api/generate/images returned a jobId for three candidate images; you polled GET /api/generate/status?jobId=... until they were ready, chose one, submitted it to POST /api/generate/voxelize for a jobId, and polled again for the finished .vox. The agentic pipeline replaces all of this with a single synchronous request that returns an editable, layered model — there are no jobs to poll. Do not build new clients against the deprecated routes.