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-datawith one field namedfile.
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:
httpandhttpsURLs 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.
| Name | Values | Default | Meaning |
|---|---|---|---|
view | iso front back left right top bottom persp | iso | Camera. |
size | 16 to 2048 | 512 | Square output, in pixels. Or use width and height. |
width, height | 16 to 2048 | 512 | Output size in pixels. |
bg | RRGGBB | F4F5F7 | Background colour, six hex digits without #. |
transparent | 0 or 1 | 0 | Transparent background. |
edges | 0 or 1 | 1 | Feature lines. |
edge_width | 0 to 8 | 1 | Line width in pixels. |
up | y, z | format’s convention | Which axis points up. STL, STEP, IGES and 3MF are read Z-up; glTF, OBJ and PLY Y-up. |
shading | auto, smooth, flat | auto | Smooth curved surfaces; edges sharper than 30° stay hard. flat shows the individual triangles. |
color | RRGGBB | model colours | Override the model colour. |
sheet | 0 or 1 | 0 | 2×2 sheet: iso, front, right and top at a common scale. |
format | png apng gif | png | apng, 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). |
frames | 8 to 72 | 36 | Turntable frame count. Only with format=apng or gif. |
azimuth, elevation | degrees | the view’s | Custom camera: around the vertical axis (0 = front) and above the horizon (−90 to 90). |
margin | 0 to 0.45 | 0.06 | Empty border, as a fraction of the image. |
filename | text | none | POST only. Format hint, for example part.stl. Not stored. |
url | http(s) URL | none | GET 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:
| Header | Meaning |
|---|---|
Content-Type | image/png, also for animated PNG turntables. |
X-Request-Id | Identifier for this request. Quote it when you contact support. |
X-ZRender-Cache | hit or miss: whether the image came from the output cache. |
X-ZRender-Triangles | Number of triangles in the model. |
X-ZRender-Render-Ms | Render time in milliseconds. |
X-ZRender-Units | Units 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-Remaining | Units 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.
| HTTP | Code | When |
|---|---|---|
| 400 | bad_request | Bad or missing parameter, or an empty body. |
| 401 | unauthorized | Missing or invalid key. |
| 402 | quota_exceeded | Free tier used up (100 units per month). |
| 413 | too_large | Input over 100 MB, or over 5,000,000 triangles. |
| 415 | unsupported_format | Unknown format, or STEP or Draco on a build without them. |
| 422 | invalid_model | Corrupt or empty model. |
| 429 | rate_limited | Too many requests. The Retry-After header says how long to wait. |
| 502 | fetch_failed | url= could not be fetched or was refused. |
| 504 | timeout | The render took longer than 10 seconds. |
| 500 | internal | Anything 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
| Format | API | In-browser converter | Notes |
|---|---|---|---|
| STL | Yes | Yes | Binary and ASCII. |
| GLB / glTF | Yes | Yes | Embedded 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). |
| OBJ | Yes | Yes | Geometry and v x y z r g b vertex colours (materials in .mtl files are not read). |
| 3MF | Yes | Yes | |
| AMF | Yes | Yes | XML or zipped. Colours from materials, volumes or objects; units converted to millimetres. Constellations (placed copies) are not expanded. |
| OFF | Yes | Yes | OFF and COFF, face or vertex colours. Read Z-up. |
| VRML, Open Inventor | Yes | Yes | VRML 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. |
| DXF | Yes | Yes | 2D 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) | Yes | No | Every 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, VTU | Yes | Yes | Meshes (I-DEAS .unv) and results (VTK .vtu) as their outer surface; results coloured by displacement. |
OpenCascade BREP (.brep) | Yes | No | Server-side, three times the units. |
STEP (.step, .stp) | Yes | No | Server-side only: it needs a CAD kernel. Counts three times in units. |
IGES (.igs, .iges) | Yes | No | Like 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/rendergives 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=apngis 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.