Schnittstelle für Entwickler
Schick ein Bild an einen Endpunkt und bekomm dieselbe laserfertige Datei zurück, die du auch im Foto Studio erhalten würdest. Gedacht für Shops, Automationen und Produktionssysteme, die ohne Bildschirm arbeiten.
Die Schnittstelle ist in Studio Pro und Business enthalten.
Anmeldung
Lege im Konto unter "API Keys & Webhooks" einen Schlüssel an. Er wird nur einmal angezeigt. Schick ihn als Kopfzeile: Authorization: Bearer DEIN_SCHLUESSEL
Anfrage
| Feld | Pflicht | Bedeutung |
|---|---|---|
| image | ja | Die Bilddatei, bis zu 20 MB. JPEG, PNG oder WebP. |
| materialId | – | Das Material. Voreinstellung: das erste in der Liste. birch · walnut · slate · glass · glass-frosted · acrylic · acrylic-dark · plastic-light · plastic-dark · anodized · stainless · leather |
| laserId | – | Der Lasertyp. co2 · fiber · diode |
| imageTypeId | – | Die Art des Motivs. photo · line-art |
| goalId | – | Das Ziel der Gravur. balanced · deep-black · fine-trace-deep · micro-detail · soft-photo · hard-marking · vector-graphic |
| widthMm | – | Die Breite auf dem Material, 5–1200 mm. Voreinstellung 100. |
| dpi | – | Punkte je Zoll, 50–2000. Ohne Angabe die Vorgabe des Lasertyps. |
Beispiel
Als "multipart/form-data" — das Bild im Feld "image", alles andere als Textfelder daneben.
curl -X POST https://vextrify.com/v1/prepare \ -H "Authorization: Bearer DEIN_SCHLUESSEL" \ -F "image=@foto.jpg" \ -F "materialId=birch" \ -F "laserId=co2" \ -F "imageTypeId=photo" \ -F "goalId=balanced" \ -F "widthMm=100"
Antwort
Das Bild kommt als PNG in "base64". Unter "applied" stehen die tatsächlich verwendeten Werte — damit lässt sich ein Ergebnis im Foto Studio wiederherstellen. Steht dort "resolutionReduced": true, wurde die Zielauflösung nicht ganz erreicht; das ändert das Punktmuster der Gravur.
{
"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
}
}Fehler
| 401 | unauthorized | Der Schlüssel fehlt, ist widerrufen oder abgelaufen. |
| 402 | plan-required | Die Schnittstelle ist in Studio Pro und Business enthalten. |
| 403 | scope-required | Diesem Schlüssel fehlt die Berechtigung "prepare:create". |
| 400 | missing-image | Es fehlt eine Bilddatei im Feld "image". |
| 400 | invalid-request | Ein Feld fehlt oder hat einen unbekannten Wert. Das betroffene Feld steht in "field". |
| 413 | image-too-large | Die Bilddatei ist größer als 20 MB. |
| 413 | job-too-large | Breite und Auflösung ergeben zusammen ein zu großes Ergebnis. Die Meldung nennt die mögliche Breite. |
| 422 | image-unreadable | Das Bildformat konnte nicht gelesen werden. |
| 429 | rate-limited | Kontingent aufgebraucht oder gerade alle Rechenplätze belegt. "Retry-After" nennt die Wartezeit in Sekunden. |
Webhooks
Trag im Konto eine Adresse ein, an die wir Ereignisse schicken. Jede Zustellung trägt die Kopfzeilen "vextrify-event" und "vextrify-signature". Antwortet deine Adresse nicht, versuchen wir es bis zu dreimal; bei einer ausdrücklichen Ablehnung (4xx) nur einmal.
- job.completed
- job.failed
Signatur prüfen
Die Kopfzeile "vextrify-signature" hat die Form t=ZEITSTEMPEL,v1=SIGNATUR. Bilde einen HMAC mit SHA-256 über "ZEITSTEMPEL.KÖRPER" mit deinem Signatur-Secret und vergleiche ihn mit v1.
// Node.js
const erwartet = createHmac("sha256", DEIN_SIGNATUR_SECRET)
.update(`${t}.${rohkoerper}`)
.digest("hex");
// vergleiche "erwartet" mit v1 aus der Kopfzeile vextrify-signature: t=…,v1=…
// WICHTIG: den ROHEN Text des Koerpers verwenden, nicht neu zusammengesetztes JSON.