Endpoints

The pipeline is asynchronous. Generation runs on serverless GPU workers that scale to zero when idle, so a request may wait for a cold start and a textured voxelize can take several minutes. Rather than holding one long HTTP request open, each generation endpoint submits a job and returns a jobId immediately. You then poll /api/generate/status every couple of seconds until the job reaches a terminal state.

The typical flow is:

1. POST /api/generate/images → { jobId }, then poll status until the 3 candidate images come back.
2. POST /api/generate/voxelize with a chosen image → { jobId }, then poll status until the .vox comes back.

All endpoints require authentication.

---

Step 1: Generate Candidate Images

Submits a job that generates 3 candidate images from a text prompt. This endpoint is rate-limited (1 request per 15 seconds per user) to prevent abuse, but it costs 0 tokens to use.

POST /api/generate/images

Request Parameters

Parameter	Type	Required	Description
prompt	string	Yes	The text description of the asset you want to generate. Max 500 characters.
seed	integer	No	A specific seed value for reproducible image generation.

Request Body Example

{
  "prompt": "a magical floating island with a crystal tree",
  "seed": 12345
}

Response

Returns the id of the submitted job. Poll /api/generate/status with this id to retrieve the generated images.

{
  "jobId": "abc123-def456-..."
}

---

Step 2: Voxelize Image

Submits a job that converts a chosen base64 image into a 3D .vox file. This endpoint costs 1 token, deducted up front when the job is submitted. The token is automatically refunded if the submission fails, or if the job later fails on the worker (handled by the status endpoint, so a dropped client never orphans a spent token).

POST /api/generate/voxelize

Request Parameters

Parameter	Type	Required	Description
image_base64	string	Yes	The Base64-encoded image string you wish to voxelize (a data: URI prefix is accepted).
voxel_size	integer	No	The resolution of the longest axis (range: 8 to 128). Default: 32.
texturing	string	No	The style of texture generation: "textured" (full PBR color) or "gray" (faster, monochrome). Default: "textured".
fill	boolean	No	Whether to fill the interior volume of the generated voxel model. Default: false.
color	string	No	Color mapping mode: "surface" or "vertex". Default: "surface".
palette_size	integer	No	Caps the number of distinct colors in the voxel-art palette (range: 2 to 256). Default: 32.

Request Body Example

{
  "image_base64": "data:image/png;base64,...",
  "voxel_size": 32,
  "texturing": "textured",
  "fill": false,
  "color": "surface",
  "palette_size": 32
}

Response

Returns the id of the submitted job along with the post-deduction token balance. Poll /api/generate/status with this id to retrieve the finished .vox file.

{
  "jobId": "abc123-def456-...",
  "balance": 4,          // User's remaining token balance after the 1-token deduction
  "charged": true        // Whether the 1-token deduction succeeded
}

---

Step 3: Poll Job Status

Polls the state of a previously submitted job. This endpoint is short, idempotent, and safe to call repeatedly (every couple of seconds is typical). You may only poll your own jobs.

GET /api/generate/status?jobId={jobId}

Query Parameters

Parameter	Type	Required	Description
jobId	string	Yes	The job id returned by /api/generate/images or /api/generate/voxelize.

Response

The state field drives what you do next. Keep polling while it is queued or running; stop on completed or failed.

State	Meaning
queued	The job is waiting for a worker (e.g. a cold start / scale-up).
running	The job is executing on a GPU worker.
completed	The job finished successfully; the result is in output.
failed	The job failed. For a paid voxelize job, the token is refunded here once.

While queued or running, the response surfaces RunPod’s real timings so you can render an honest progress bar:

{
  "state": "running",
  "delayTime": 1820,       // ms spent waiting in queue (cold-start indicator)
  "executionTime": 45000   // ms spent executing so far
}

When completed, the result is in output. For an images job:

{
  "state": "completed",
  "executionTime": 38000,
  "output": {
    "seed": 12345,
    "images": [
      { "index": 0, "image_base64": "..." },
      { "index": 1, "image_base64": "..." },
      { "index": 2, "image_base64": "..." }
    ]
  }
}

For a voxelize job, the response also echoes the post-spend token balance:

{
  "state": "completed",
  "executionTime": 210000,
  "output": {
    "filename": "voxel_00000.vox",
    "vox_base64": "..."
  },
  "balance": 4,
  "charged": true
}

When failed:

{
  "state": "failed",
  "error": "A human-readable description of what went wrong."
}

---

Common Errors

• 400 Bad Request: Invalid request body, an empty/oversized prompt, a missing image, or a missing jobId on the status endpoint.
• 401 Unauthorized: Missing, expired, or invalid authentication token.
• 402 Payment Required: Returned by /voxelize if the user is out of tokens (code: "INSUFFICIENT_TOKENS").
• 403 Forbidden: No token balance found for the account (code: "NO_BALANCE"), or polling a job you do not own.
• 404 Not Found: The polled jobId does not exist.
• 429 Too Many Requests: Returned on /images when the 15-second rate limit is exceeded.
• 502 Bad Gateway: A transient backend hiccup while checking status (the response includes "transient": true). The job is still running — keep polling.

A voxelize job that fails — whether at submission or later on the worker — has its token automatically refunded exactly once, so a failed or abandoned generation never costs a token.