VoxAI Public API

Authentication

All /api/v1/* endpoints require an API token in the Authorization header. Session JWTs are not accepted — requests with a JWT receive an error directing you to use an API token.

Authorization: Bearer vtx_<your_token>

Scopes

Poll routes (GET /assets/:assetId, GET /asset-groups/:assetGroupId) require a valid token but no specific scope.

Async workflow

Generation is asynchronous. A successful request returns 202 with asset IDs while processing continues in the background.

1. POST /api/v1/generate/* → receive assetId or assetGroupId
2. Poll GET /api/v1/assets/:assetId or wait for a webhook event
3. When complete, call POST /api/v1/assets/:assetId/download-url (native files) or download-convert (format conversion)

Credit pricing

Prompt enhancement and autoPrompt do not cost extra credits.

Endpoints

Example responses

Batch image generation

{
  "success": true,
  "data": {
    "assetGroupId": "6656c01ec43902bd48d4d100",
    "derivedPrompt": "blocky voxel warrior with ...",
    "assets": [
      { "assetId": "6656c01ec43902bd48d4d297", "status": "processing" },
      { "assetId": "6656c01ec43902bd48d4d298", "status": "processing" }
    ]
  }
}

derivedPrompt is present only when the prompt was auto-derived via autoPrompt=true.

Single 3D generation

{
  "success": true,
  "data": {
    "assetId": "6656c01ec43902bd48d4d297",
    "assetGroupId": null,
    "status": "processing"
  }
}

Download URL

{
  "success": true,
  "data": {
    "url": "https://d….cloudfront.net/3D_model/….vox?Expires=…&Signature=…",
    "expiresAt": "2026-07-15T06:15:00.000Z",
    "filename": "model.vox"
  }
}

Webhooks

Webhooks are optional. Configure an HTTPS URL in the API panel (account menu → API). If no URL is saved, no outbound events are sent and you must poll asset endpoints instead.

Event types

• image.completed / image.failed
• model.completed / model.failed
• tool.revoxelize.completed / tool.revoxelize.failed
• tool.rigging.completed / tool.rigging.failed

Completed events include a fresh CloudFront downloadUrl (reminted on every delivery attempt). Verify authenticity with the X-VoxAI-Signature header: sha256=HMAC(webhookSecret, rawBody).

Completed webhook payload

{
  "id": "evt_...",
  "type": "model.completed",
  "createdAt": "2026-07-15T06:00:00.000Z",
  "data": {
    "assetId": "...",
    "assetGroupId": null,
    "status": "completed",
    "source": "api",
    "format": "vox",
    "downloadUrl": "https://d….cloudfront.net/3D_model/….vox?Expires=…&Signature=…",
    "downloadExpiresAt": "2026-07-15T06:15:00.000Z",
    "filename": "model.vox"
  }
}

Error codes

cURL examples

Text-to-image with prompt enhancement

curl -s -X POST https://api.voxelai.ai/api/v1/generate/image \
  -H "Authorization: Bearer vtx_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a warrior robot","name":"robot","imageModel":"nanobanana","imageNumber":1,"promptEnhancement":true,"style":"Roblox style"}'

Image-to-image with autoPrompt

curl -s -X POST https://api.voxelai.ai/api/v1/generate/image \
  -H "Authorization: Bearer vtx_YOUR_TOKEN" \
  -F "autoPrompt=true" \
  -F "name=auto_i2i" \
  -F "imageModel=nanobanana" \
  -F "imageNumber=1" \
  -F "imageStyle=Roblox style" \
  -F "image=@/path/to/photo.jpg"

Direct image → 3D (skip image library)

curl -s -X POST https://api.voxelai.ai/api/v1/generate/3d \
  -H "Authorization: Bearer vtx_YOUR_TOKEN" \
  -F "name=my_model" \
  -F "format=voxai_v3" \
  -F "cubeSize=0.032" \
  -F "image=@photo.png"

Poll, download, and convert

# Check credits
curl -s https://api.voxelai.ai/api/v1/credits \
  -H "Authorization: Bearer vtx_YOUR_TOKEN"

# Poll asset status
curl -s https://api.voxelai.ai/api/v1/assets/6656c01ec43902bd48d4d297 \
  -H "Authorization: Bearer vtx_YOUR_TOKEN"

# Native download URL
curl -s -X POST https://api.voxelai.ai/api/v1/assets/6656c01ec43902bd48d4d297/download-url \
  -H "Authorization: Bearer vtx_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "format": "vox" }'

# Format conversion (binary response)
curl -X POST https://api.voxelai.ai/api/v1/assets/6656c01ec43902bd48d4d297/download-convert \
  -H "Authorization: Bearer vtx_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputFormat":"vox","outputFormat":"glb"}' \
  -o model_voxel.glb

Replace the base URL with your backend host if self-hosting.