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

FieldRequiredMeaning
imageyesThe 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

401unauthorizedThe key is missing, revoked or expired.
402plan-requiredThe API is included in Studio Pro and Business.
403scope-requiredThis key lacks the "prepare:create" permission.
400missing-imageAn image file is missing in the "image" field.
400invalid-requestA field is missing or has an unknown value. The affected field is in "field".
413image-too-largeThe image file is larger than 20 MB.
413job-too-largeWidth and resolution together produce too large a result. The message names the possible width.
422image-unreadableThe image format could not be read.
429rate-limitedQuota 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.