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

FeldPflichtBedeutung
imagejaDie 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

401unauthorizedDer Schlüssel fehlt, ist widerrufen oder abgelaufen.
402plan-requiredDie Schnittstelle ist in Studio Pro und Business enthalten.
403scope-requiredDiesem Schlüssel fehlt die Berechtigung "prepare:create".
400missing-imageEs fehlt eine Bilddatei im Feld "image".
400invalid-requestEin Feld fehlt oder hat einen unbekannten Wert. Das betroffene Feld steht in "field".
413image-too-largeDie Bilddatei ist größer als 20 MB.
413job-too-largeBreite und Auflösung ergeben zusammen ein zu großes Ergebnis. Die Meldung nennt die mögliche Breite.
422image-unreadableDas Bildformat konnte nicht gelesen werden.
429rate-limitedKontingent 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.