Docs HTTP API v1

API documentation

Send a 3D file, get a PNG. One endpoint does the work; everything else on this page is detail. A machine-readable version is in openapi.yaml.

The hosted API opens soon; until then you can read the docs, try the free in-browser tools and ask for early access.

Quickstart

The base URL in these examples is https://api.example.com. Replace zr_live_YOUR_KEY with a key from the dashboard.

curl

Upload a file as the raw request body:

curl -X POST "https://api.example.com/v1/render?view=iso&size=512&filename=gear.stl" \
  -H "Authorization: Bearer zr_live_YOUR_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @gear.stl \
  -o gear.png

Or let the server fetch the file from a URL:

curl -G "https://api.example.com/v1/render" \
  -H "Authorization: Bearer zr_live_YOUR_KEY" \
  --data-urlencode "url=https://example.com/models/gear.stl" \
  -d view=iso -d size=512 \
  -o gear.png

Multipart uploads work too, with one field named file:

curl -X POST "https://api.example.com/v1/render?sheet=1&size=1024" \
  -H "Authorization: Bearer zr_live_YOUR_KEY" \
  -F "file=@bracket.step" \
  -o bracket-sheet.png

JavaScript (fetch)

Node.js 18 or later, saved as an ES module (render.mjs). Upload a file:

import { readFile, writeFile } from 'node:fs/promises';

const BASE = 'https://api.example.com';
const KEY = process.env.ZRENDER_KEY; // zr_live_...

const params = new URLSearchParams({ view: 'iso', size: '512', filename: 'gear.stl' });

const res = await fetch(`${BASE}/v1/render?${params}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${KEY}`,
    'Content-Type': 'application/octet-stream',
  },
  body: await readFile('gear.stl'),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${res.status} ${error.code}: ${error.message} (request ${error.request_id})`);
}

await writeFile('gear.png', Buffer.from(await res.arrayBuffer()));
console.log('triangles:', res.headers.get('x-zrender-triangles'));
console.log('render ms:', res.headers.get('x-zrender-render-ms'));

Render from a URL:

import { writeFile } from 'node:fs/promises';

const BASE = 'https://api.example.com';
const KEY = process.env.ZRENDER_KEY;

const params = new URLSearchParams({
  url: 'https://example.com/models/gear.stl',
  view: 'top',
  size: '256',
});

const res = await fetch(`${BASE}/v1/render?${params}`, {
  headers: { Authorization: `Bearer ${KEY}` },
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${res.status} ${error.code}: ${error.message}`);
}

await writeFile('gear-top.png', Buffer.from(await res.arrayBuffer()));

Python (requests)

Upload a file:

import os
import requests

BASE = "https://api.example.com"
KEY = os.environ["ZRENDER_KEY"]  # zr_live_...

with open("gear.stl", "rb") as f:
    data = f.read()

r = requests.post(
    f"{BASE}/v1/render",
    params={"view": "iso", "size": 512, "filename": "gear.stl"},
    headers={
        "Authorization": f"Bearer {KEY}",
        "Content-Type": "application/octet-stream",
    },
    data=data,
    timeout=30,
)

if r.status_code != 200:
    err = r.json()["error"]
    raise SystemExit(f"{r.status_code} {err['code']}: {err['message']} (request {err['request_id']})")

with open("gear.png", "wb") as out:
    out.write(r.content)

print("triangles:", r.headers.get("X-ZRender-Triangles"))
print("render ms:", r.headers.get("X-ZRender-Render-Ms"))

Render from a URL:

import os
import requests

BASE = "https://api.example.com"
KEY = os.environ["ZRENDER_KEY"]

r = requests.get(
    f"{BASE}/v1/render",
    params={"url": "https://example.com/models/gear.stl", "view": "top", "size": 256},
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=30,
)

if r.status_code != 200:
    err = r.json()["error"]
    raise SystemExit(f"{r.status_code} {err['code']}: {err['message']}")

with open("gear-top.png", "wb") as out:
    out.write(r.content)

Authentication

Send your API key as a bearer token on every request to /v1/render and /v1/usage:

Authorization: Bearer zr_live_YOUR_KEY

Keys start with zr_live_. Create and revoke them in the dashboard, which you sign in to with an email link. A key is shown only once, when it is created, so store it somewhere safe. A missing or invalid key gets a 401 unauthorized response.

Keep keys on your server. Do not put them in browser code or mobile apps, where anyone can read them.

Render endpoints

Upload a file

POST /v1/render

The body is the file. Two encodings are accepted:

  • the raw file bytes, with Content-Type: application/octet-stream, or
  • multipart/form-data with one field named file.

Render parameters go in the query string. The optional filename= query parameter (or the multipart filename) is used only as a hint for format detection.

Fetch from a URL

GET /v1/render?url=https://…

The server downloads the file from url and renders it. All other parameters and the response are the same as for POST. Restrictions on the fetch:

  • http and https URLs only;
  • private, loopback and link-local addresses are refused;
  • the download is capped at 100 MB and times out after 10 seconds.

If the file cannot be fetched or the address is refused, the response is 502 fetch_failed.

Success response

200 OK with Content-Type: image/png and the image as the body. Turntables (format=apng) are animated PNGs and use the same content type. See response headers for the metadata that comes with it.

Parameters

All parameters are optional query-string parameters. The same names are used by the demo endpoint.

NameValuesDefaultMeaning
viewiso front back left right top bottom perspisoCamera.
size16 to 2048512Square output, in pixels. Or use width and height.
width, height16 to 2048512Output size in pixels.
bgRRGGBBF4F5F7Background colour, six hex digits without #.
transparent0 or 10Transparent background.
edges0 or 11Feature lines.
edge_width0 to 81Line width in pixels.
upy, zformat’s conventionWhich axis points up. STL, STEP, IGES and 3MF are read Z-up; glTF, OBJ and PLY Y-up.
shadingauto, smooth, flatautoSmooth curved surfaces; edges sharper than 30° stay hard. flat shows the individual triangles.
colorRRGGBBmodel coloursOverride the model colour.
sheet0 or 102×2 sheet: iso, front, right and top at a common scale.
formatpng apng gifpngapng, gif and webm render a turntable animation: animated PNG, GIF (plays everywhere, including e-mail) or WebM video (VP9, the smallest file, for a <video> tag).
frames8 to 7236Turntable frame count. Only with format=apng or gif.
azimuth, elevationdegreesthe view’sCustom camera: around the vertical axis (0 = front) and above the horizon (−90 to 90).
margin0 to 0.450.06Empty border, as a fraction of the image.
filenametextnonePOST only. Format hint, for example part.stl. Not stored.
urlhttp(s) URLnoneGET only, required. The file to fetch and render.

A bad or missing parameter, or an empty body, gets a 400 bad_request response whose message names the problem.

Response headers

Every successful render carries these headers:

HeaderMeaning
Content-Typeimage/png, also for animated PNG turntables.
X-Request-IdIdentifier for this request. Quote it when you contact support.
X-ZRender-Cachehit or miss: whether the image came from the output cache.
X-ZRender-TrianglesNumber of triangles in the model.
X-ZRender-Render-MsRender time in milliseconds.
X-ZRender-UnitsUnits charged for this request: still 1, sheet 1, turntable 4; STEP input multiplies by 3. A cached repeat costs 0, and failed renders are not charged.
X-ZRender-Quota-RemainingUnits left in the current period.

Errors

Errors are JSON with an HTTP status that matches the code:

{
  "error": {
    "code": "invalid_model",
    "message": "…",
    "request_id": "…"
  }
}

message is written for people and may change; branch on code.

HTTPCodeWhen
400bad_requestBad or missing parameter, or an empty body.
401unauthorizedMissing or invalid key.
402quota_exceededFree tier used up (100 units per month).
413too_largeInput over 100 MB, or over 5,000,000 triangles.
415unsupported_formatUnknown format, or STEP or Draco on a build without them.
422invalid_modelCorrupt or empty model.
429rate_limitedToo many requests. The Retry-After header says how long to wait.
502fetch_failedurl= could not be fetched or was refused.
504timeoutThe render took longer than 10 seconds.
500internalAnything else.

Limits

Input size
100 MB per file
Triangles
5,000,000 per model
Output
2048 px per side
Render time
10 s per render
URL fetch
100 MB cap, 10 s timeout

Going over the size or triangle limit returns 413 too_large; going over the time limit returns 504 timeout.

Formats

FormatAPIIn-browser converterNotes
STLYesYesBinary and ASCII.
GLB / glTFYesYesEmbedded buffers. Base-colour textures (PNG, JPEG), vertex colours, quantized meshes and texture transforms. Meshopt compression (EXT_ and KHR_meshopt_compression) and Draco are read (Draco on the server only).
OBJYesYesGeometry and v x y z r g b vertex colours (materials in .mtl files are not read).
3MFYesYes
AMFYesYesXML or zipped. Colours from materials, volumes or objects; units converted to millimetres. Constellations (placed copies) are not expanded.
OFFYesYesOFF and COFF, face or vertex colours. Read Z-up.
VRML, Open InventorYesYesVRML 2.0 / VRML97 (.wrl) and Inventor 2.1 ASCII (.iv): face and line sets, boxes, spheres, cylinders and cones, material colours, transforms, DEF/USE. Textures, text and Inline files are not read.
DXFYesYes2D flat parts (ASCII DXF): lines, arcs, circles, polylines with bulges, ellipses, splines and blocks, in the drawing’s units. Drawn as a plate (thickness= in mm); /v1/analyze adds cut length, pierces, parts, holes and net area. Text, dimensions and hatches are ignored.
FreeCAD (.FCStd)YesNoEvery visible shape, in FreeCAD’s colours (per face too), with assembly links, group placements and link arrays; FEM meshes and results as FreeCAD shows them; embedded VRML and Inventor scenes too. Server-side, three times the units.
FEM: UNV, VTUYesYesMeshes (I-DEAS .unv) and results (VTK .vtu) as their outer surface; results coloured by displacement.
OpenCascade BREP (.brep)YesNoServer-side, three times the units.
STEP (.step, .stp)YesNoServer-side only: it needs a CAD kernel. Counts three times in units.
IGES (.igs, .iges)YesNoLike STEP: server-side, exact CAD edges and normals, three times the units.

On uploads, the optional filename= parameter (or the multipart filename) is used only as a format hint.

Usage

GET /v1/usage

Returns the plan and unit counts for the key’s account in the current period.

curl "https://api.example.com/v1/usage" \
  -H "Authorization: Bearer zr_live_YOUR_KEY"
{
  "plan": "free",
  "period": "2026-11",
  "units_used": 12,
  "units_included": 100,
  "hard_limit": true
}

When hard_limit is true, requests are refused with 402 quota_exceeded once units_used reaches units_included. What a unit is, and the draft plans, are on the pricing page.

Convert, draw, measure

Three more endpoints take the same body (upload, multipart or url=) and cost 1 unit each (STEP and IGES input three):

POST /v1/convert?to=glb|stl|obj|ply|3mf

Writes the model in another format: STEP to GLB for a web viewer, any mesh to STL or 3MF for printing. quantize=1 makes a GLB about half the size, simplify=N keeps at most N triangles (sharp edges and outlines are preserved), repair=1 welds and fixes orientation first. GLB is written in metres and Y-up, as glTF expects; STL and 3MF in millimetres, Z-up.

curl -s -X POST "$BASE/v1/convert?to=glb&quantize=1" \
  -H "Authorization: Bearer $ZR_KEY" --data-binary @bracket.step -o bracket.glb

POST /v1/drawing?format=svg|dxf

A line drawing with hidden lines dashed, true to scale. sheet=1 lays out front, top, right and isometric views (third-angle projection); view, azimuth/elevation pick a single view; hidden=0 leaves hidden lines out. STEP and IGES use the exact CAD edges. DXF puts lines on the layers VISIBLE and HIDDEN.

POST /v1/analyze

Measurements as JSON: bounding box, surface area, volume and centre of mass (for watertight models), whether the mesh is watertight and why not, separate parts, overhang area. Add density= (g/cm³) for the mass and printer=256x256x256 to know whether it fits. For STEP and IGES the answer also lists every part with its name, quantity and exact CAD volume, and the assembly tree; csv=1 returns that bill of materials as CSV.

Each CAD part also gets its manufacturing features: holes (diameter, depth, through or blind, counterbore, countersink, drill point, positions), the smallest internal corner radius, stock size and removal volume, and for sheet metal the thickness, bends and flat area.

print=1 adds an FDM print estimate: print time, filament length and weight with the infill counted, support volume and the underside that needs support. Change the settings with print_settings=layer_height=0.28,infill=0.2,supports=true and the filament with material=petg. 3MF projects from Bambu Studio, OrcaSlicer and PrusaSlicer bring their own profile, and sliced Bambu/Orca projects their own print time. With the same settings the estimate came within about 5 % of PrusaSlicer on most test parts.

DXF files return cut: cut length, pierces, parts, holes, net area; with thickness= and density= the mass, with cut_speed= (mm/min) the cut time.

curl -s -X POST "$BASE/v1/analyze?density=7.85" \
  -H "Authorization: Bearer $ZR_KEY" --data-binary @assembly.step
# {"bbox":{"size":[80,60,50]},"volume":61517.8,"mass_g":482.9,"watertight":true,
#  "cad":{"parts":[{"name":"post","quantity":2,"volume":2748.89,...}],...}, ...}

Large files: asynchronous jobs

POST /v1/jobs

Use this for files that need more than the 10 seconds and 2 GB of memory a /v1/render call gets, mainly large STEP assemblies. It takes the same body (upload or url=) and parameters, costs the same units, and is charged only when the job succeeds. A job may run for up to 120 seconds with 8 GB of memory.

The answer is 202 Accepted with the job, at once. Poll its status_url until status is done (or failed, with an error object using the usual codes), then download the PNG from result_url:

curl -s -X POST "$BASE/v1/jobs?size=1024&sheet=1" \
  -H "Authorization: Bearer $ZR_KEY" --data-binary @assembly.step
# {"id":"job_…","status":"queued","status_url":"…/v1/jobs/job_…", …}

curl -s "$BASE/v1/jobs/job_…" -H "Authorization: Bearer $ZR_KEY"
# {"status":"done","result_url":"…/v1/jobs/job_…/result","triangles":587200, …}

curl -s "$BASE/v1/jobs/job_…/result" -H "Authorization: Bearer $ZR_KEY" -o assembly.png
  • At most 3 jobs per account can be queued or running at once (429).
  • Asking for the result too early gives 409 job_not_finished; results expire after 30 days (410 gone).
  • The input file is deleted as soon as its job finishes. If the service restarts, unfinished jobs fail and must be sent again.
  • When /v1/render gives up on a file because of its size, the error message says so and points here.

Batches and webhooks

POST /v1/batch?op=render|convert|drawing|analyze

Send a ZIP of up to 100 models; every file goes through the same operation and parameters, as one job. The result is a ZIP with one output per input and a manifest.json with each file’s status and units. Files that fail are listed there and not charged.

zip parts.zip *.step
curl -s -X POST "$BASE/v1/batch?op=render&size=512&sheet=1" \
  -H "Authorization: Bearer $ZR_KEY" --data-binary @parts.zip
# {"id":"job_…","status":"queued","files":24, …}

Instead of polling, add callback_url=https://… to /v1/jobs or /v1/batch. When the job finishes, its status JSON is POSTed there with a signature header:

X-ZRender-Event: job.done
X-ZRender-Signature: t=1795003812,v1=5f2c…

v1 is the HMAC-SHA256 of <t>.<raw body> with your webhook secret from the dashboard. Check it, and reject old timestamps. A call that does not get a 2xx answer is retried after 30 seconds, 2 and 10 minutes, 1 and 6 hours.

POST /v1/watches

Or let the service watch your bucket. Give it an S3-compatible endpoint (AWS S3, Cloudflare R2, Hetzner, MinIO), credentials that can read the input prefix and write the output prefix, and an operation. Every few minutes it processes new or changed models and writes the results next to them under the output prefix (or a .error.json explaining a failure). The secret key is stored encrypted and never shown again.

curl -s -X POST "$BASE/v1/watches" -H "Authorization: Bearer $ZR_KEY" \
  -H "Content-Type: application/json" -d '{
    "endpoint": "https://ACCOUNT.r2.cloudflarestorage.com", "bucket": "parts",
    "access_key_id": "…", "secret_access_key": "…",
    "input_prefix": "uploads/", "output_prefix": "previews/",
    "op": "render", "params": { "size": 512, "sheet": 1 } }'

Demo endpoint

POST /v1/demo/render

The endpoint behind the STEP to PNG page. It needs no key and takes the same body and parameters as POST /v1/render, with tighter limits:

  • input up to 20 MB;
  • output at most 512 pixels;
  • no turntable (format=apng is refused);
  • 10 renders per hour per IP address.

It exists for the website. Do not build on it: use a key and /v1/render.

Data retention

  • Input files are held only for the duration of the render and then deleted.
  • Rendered outputs are cached for at most 30 days, keyed by a hash of the file and the parameters.
  • Logs are kept at most 30 days and never contain file contents.

The hosted API runs in the EU. If your files may not leave your network at all, see the self-hosted licence.

OpenAPI

The API is described in OpenAPI 3.0: /docs/openapi.yaml. Load it into your HTTP client or code generator of choice.