Developer interface
Send an image to one endpoint and get back the same laser-ready file you would get in the Photo Studio. Made for shops, automations and production systems that work without a screen.
The API is included in Studio Pro and Business.
Authentication
Create a key in your account under "API Keys & Webhooks". It is shown only once. Send it as a header: Authorization: Bearer YOUR_KEY
Request
| Field | Required | Meaning |
|---|---|---|
| image | yes | The image file, up to 20 MB. JPEG, PNG or WebP. |
| materialId | – | The material. Default: the first in the list. birch · walnut · slate · glass · glass-frosted · acrylic · acrylic-dark · plastic-light · plastic-dark · anodized · stainless · leather |
| laserId | – | The laser type. co2 · fiber · diode |
| imageTypeId | – | The kind of subject. photo · line-art |
| goalId | – | The engraving goal. balanced · deep-black · fine-trace-deep · micro-detail · soft-photo · hard-marking · vector-graphic |
| widthMm | – | The width on the material, 5–1200 mm. Default 100. |
| dpi | – | Dots per inch, 50–2000. Without it, the laser type's default. |
Example
As "multipart/form-data" — the image in the "image" field, everything else as text fields alongside.
curl -X POST https://vextrify.com/v1/prepare \ -H "Authorization: Bearer YOUR_KEY" \ -F "image=@photo.jpg" \ -F "materialId=birch" \ -F "laserId=co2" \ -F "imageTypeId=photo" \ -F "goalId=balanced" \ -F "widthMm=100"
Response
The image comes as PNG in "base64". Under "applied" are the values actually used — with them a result can be reproduced in the Photo Studio. If "resolutionReduced" is true, the target resolution was not fully reached; that changes the dot pattern of the engraving.
{
"jobId": "5f2c…",
"image": { "format": "png", "base64": "iVBORw0…", "widthPx": 1000, "heightPx": 750 },
"applied": {
"materialId": "birch",
"laserId": "co2",
"imageTypeId": "photo",
"goalId": "balanced",
"widthMm": 100,
"dpi": 254,
"effectiveDpi": 254,
"resolutionReduced": false
}
}Errors
| 401 | unauthorized | The key is missing, revoked or expired. |
| 402 | plan-required | The API is included in Studio Pro and Business. |
| 403 | scope-required | This key lacks the "prepare:create" permission. |
| 400 | missing-image | An image file is missing in the "image" field. |
| 400 | invalid-request | A field is missing or has an unknown value. The affected field is in "field". |
| 413 | image-too-large | The image file is larger than 20 MB. |
| 413 | job-too-large | Width and resolution together produce too large a result. The message names the possible width. |
| 422 | image-unreadable | The image format could not be read. |
| 429 | rate-limited | Quota exhausted or all processing slots busy. "Retry-After" gives the wait in seconds. |
Webhooks
Register an address in your account for us to send events to. Every delivery carries the headers "vextrify-event" and "vextrify-signature". If your address does not answer we try up to three times; on an explicit rejection (4xx) only once.
- job.completed
- job.failed
Verifying the signature
The header "vextrify-signature" has the form t=TIMESTAMP,v1=SIGNATURE. Compute an HMAC with SHA-256 over "TIMESTAMP.BODY" using your signing secret and compare it with v1.
// Node.js
const expected = createHmac("sha256", YOUR_SIGNING_SECRET)
.update(`${t}.${rawBody}`)
.digest("hex");
// compare "expected" with v1 from the vextrify-signature header: t=…,v1=…
// IMPORTANT: use the RAW body text, not re-serialized JSON.