API-Referenz · v1JSON + Multipart

Stickerei in Ihr Produkt integrieren.

Eine praxisnahe REST-API für private Bild-Digitalisierung und echte Maschinen-Dateikonvertierung. Diese Seite enthält den vollständigen Schnellstart, die Endpunkt-Referenz und die Fehlerübersicht.

API-Schlüssel erstellen OpenAPI 3.1

Basis-URL

https://embroideryfileconverter.com/api/developer/v1

Authentifizierung

Bearer-Schlüssel

Limit

60/min

Jobs

Asynchron

Schlüssel sind bereichsbezogen, laufen ab, können sofort widerrufen werden und werden nur einmal angezeigt. Bewahren Sie sie auf Ihrem Server auf – geben Sie sie niemals in Browser- oder Mobilclient-Code aus.

Übersicht Schnellstart Authentifizierung Auftrag erstellen Auftragslebenszyklus Endpunkt-Referenz Fehler & Limits

Schnellstart

Ihr erster Job in drei Schritten.

Schlüssel erstellen

Wählen Sie nur die Fähigkeiten aus, die Ihr Dienst benötigt, und speichern Sie das Geheimnis in einem serverseitigen Secret Manager.

Quelle senden

POST-Multipart-Formulardaten mit Workflow, Ausgabeformat und einer privaten Quelldatei senden.

Job abfragen

Verwenden Sie den zurückgegebenen Workflow und die Job-ID, bis der Status „abgeschlossen“ oder „fehlgeschlagen“ lautet.

Konvertierungs-Job erstellen · Shell

curl -X POST https://embroideryfileconverter.com/api/developer/v1/jobs \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json" \
  -F "workflow=conversion" \
  -F "format=dst" \
  -F "[email protected]"

Authentifizierung

Bereichsbezogene Bearer-Schlüssel.

Senden Sie den Schlüssel bei jeder Anfrage im Authorization-Header. Ein Schlüssel kann nur auf die Jobs seines Besitzers und nur auf die bei der Erstellung ausgewählten Fähigkeiten zugreifen.

formats:read

usage:read

jobs:read

jobs:write

Authorization-Header

Authorization: Bearer efc_live_...
Accept: application/json

Nur serverseitig

Binden Sie keinen Entwickler-Schlüssel in eine Webseite, eine verteilte Desktop-Binärdatei oder eine Mobile App ein. Leiten Sie Anfragen über Ihr Backend weiter.

Delegierten Benutzerzugriff benötigt?

KI-Clients sollten MCP mit OAuth und PKCE verwenden, anstatt einen Entwickler-API-Schlüssel zu erhalten.

POST /jobs

Wählen Sie den Workflow, der zur Quelle passt.

workflow=conversion

Vorhandene Maschinendatei

Laden Sie PES, DST, JEF oder ein anderes lesbares Stickformat hoch und wählen Sie ein anderes beschreibbares Ausgabeformat.

Erforderlich: workflow, format, file
Maximale Dateigröße: 50 MB

workflow=digitising

JPG-, PNG-, SVG- oder WebP-Vorlage

Erzeugen Sie eine Stichvorschau aus der Vorlage. Fertigbreite und maximale Garnfarbanzahl sind erforderlich.

Zusätzliche Felder: width_mm, colour_count
Gültige Bereiche: 10–300 mm · 1–24 Farben
Maximale Dateigröße: 20 MB

Einzeldateien und Stapel

Verwenden Sie file für eine Quelle oder files[] für bis zu 10 Quellen. Die begrenzte kostenlose Verarbeitung akzeptiert ggf. nur eine Datei pro Anfrage. Jeder Stapel verwendet einen gemeinsamen Workflow und ein gemeinsames Ausgabeformat.

202 Accepted

{
  "message": "Processing started.",
  "job": {
    "id": "01JEXAMPLEJOBID000000000",
    "status": "queued",
    "workflow": "conversion"
  },
  "jobs": [
    {
      "id": "01JEXAMPLEJOBID000000000",
      "status": "queued",
      "workflow": "conversion"
    }
  ],
  "freeUsage": {
    "previewRemaining": 2,
    "creditBalance": 0
  }
}

Erstellung ist asynchron

HTTP 202 bedeutet, dass der private Job angenommen wurde, nicht dass die Maschinendatei bereit ist. Speichern Sie sowohl job.id als auch job.workflow; der Workflow wählt die Status-Route.

queuedWarten auf einen Worker

processingEngine läuft

completedAusgaben und Warnungen prüfen

failedfailureCode und failureReason lesen

Abfragen und Dateien

Lesen Sie das Ergebnis, nicht nur den Status.

Eine abgeschlossene Antwort enthält analysierte Metriken, Warnungen, Ereignisse, Vorschau-Artefakte und Ausgabedateien. Signierte URLs sind kurzlebig; fordern Sie den Job erneut an, wenn eine URL abläuft.

Verarbeitungs-Job abrufen · Shell

curl https://embroideryfileconverter.com/api/developer/v1/jobs/conversion/01JEXAMPLEJOBID000000000 \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json"

Metriken

Stichanzahl, Abmessungen und enginespezifische Messwerte.

Warnungen

Kompatibilitäts- oder Produktionshinweise, die Ihre Benutzeroberfläche anzeigen sollte.

Private Dateien

Signierte URLs sind 10 Minuten gültig und erzwingen weiterhin Eigentümerschaft und Entsperrstatus.

Entsperren kann eine Berechtigung verbrauchen

Zuerst prüfen job.unlock oder GET /usage. Der Aufruf des Freischalt-Endpunkts kann ein Abonnement-Kontingent oder vorhandene Verarbeitungs-Credits verbrauchen. Interne Konten können kostenlos freischalten. Es öffnet keinen Checkout und kauft keine Credits.

Endpunkt-Referenz

Die vollständige v1-Oberfläche.

OpenAPI JSON

GET/formats

Lesbare Quellen, schreibbare Ausgaben und Kompatibilitätswarnungen.

formats:read

GET/usage

Vorschau-Kontingent, Credits, Workflow-Kosten und Reset-Daten.

usage:read

GET/jobs

Die 50 neuesten privaten Verarbeitungsaufträge des Kontos.

jobs:read

POST/jobs

Einen Konvertierungs- oder Bild-Digitalisierungs-Vorschauauftrag erstellen.

jobs:write

GET/jobs/conversion/{id}

Einen eigenen Konvertierungsauftrag und seine Ausgaben prüfen.

jobs:read

GET/jobs/digitising/{id}

Einen eigenen Digitalisierungsauftrag und seine Ausgaben prüfen.

jobs:read

POST/jobs/{workflow}/{id}/retry

Einen fehlgeschlagenen Auftrag erneut in die Warteschlange stellen, solange seine private Quelle noch existiert.

jobs:write

POST/jobs/{workflow}/{id}/unlock

Einen abgeschlossenen Auftrag mit Kontingent oder vorhandenen Credits freischalten.

jobs:write

Listen-Antworten

GET /formats gibt zurück data[] als auch artworkInputs[]. GET /jobs gibt zurück data[] plus freeUsage und ist auf die 50 neuesten Jobs begrenzt.

Wiederholungs-Antworten

Wiederholung akzeptiert nur einen failed Job, dessen Quelle noch nicht abgelaufen ist. Eine erfolgreiche Wiederholung gibt HTTP 202 mit dem zurückgesetzten Job zurück auf queued.

Fehler und Ratenlimits

Fehler klar melden. Bewusst wiederholen.

401

Fehlender, ungültiger, abgelaufener oder widerrufener Schlüssel

403

Fehlende Fähigkeit oder Ressource gehört einem anderen Benutzer

404

Job oder private Datei nicht gefunden

409

Job-Status erlaubt diese Aktion nicht

410

Quell-Upload ist abgelaufen

422

Ungültige Felder, Datei, Format oder unzureichendes Kontingent

429

Ratenlimit überschritten

422 Validierungsfehler

{
  "message": "The format field is invalid.",
  "errors": {
    "format": [
      "Choose an output format different from every detected source format."
    ]
  }
}

60 Anfragen pro Minute

Das allgemeine Limit gilt pro API-Schlüssel mit einer separaten Netzwerkobergrenze. Upload-, Verarbeitungs- und Entsperr-Routen haben strengere Missbrauchskontrollen.

HTTP 429 behandeln

Respektieren Sie Retry-After und verwenden Sie exponentielles Backoff mit Jitter. Fragen Sie abgeschlossene oder fehlgeschlagene Jobs nicht kontinuierlich ab.

Für einen KI-Agenten entwickeln?

Verwenden Sie OAuth + MCP, keinen API-Schlüssel.

Die Agenten-Anleitung enthält Verbindungsaufbau, Discovery-URLs, OAuth PKCE, jedes Tool-Schema und kopierfertige JSON-RPC-Beispiele.

MCP-Dokumentation öffnen

Hilfe benötigt? Entwickler-Support kontaktieren

OpenAPI-Beschreibung herunterladen