API-referentie · v1JSON + multipart

Bouw borduurwerk in uw product.

Een praktische REST API voor privé afbeeldingsdigitalisering en echte machinebestandsconversie. Deze pagina is de volledige quickstart, endpointreferentie en foutengids.

Een API-sleutel ophalen OpenAPI 3.1

Basis-URL

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

Authenticatie

Bearer-sleutel

Limiet

60/min

Taken

Asynchroon

Sleutels zijn beperkt, verlopen, kunnen direct worden ingetrokken en worden slechts één keer getoond. Bewaar ze op uw server—verstuur ze nooit in browser- of mobiele clientcode.

Overzicht Quickstart Authenticatie Taak maken Taaklevenscyclus Endpointreferentie Fouten en limieten

Quickstart

Uw eerste taak in drie stappen.

Een sleutel maken

Selecteer alleen de mogelijkheden die uw service nodig heeft en bewaar het geheim in een server-side secret manager.

De bron versturen

POST multipart form data met de workflow, uitvoerindeling en één privé bronbestand.

De taak bevragen

Gebruik de teruggegeven workflow en taak-ID tot de status voltooid of mislukt is.

Een conversietaak maken · 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]"

Authenticatie

Beperkte Bearer-sleutels.

Verstuur de sleutel in de Authorization-header bij elk verzoek. Een sleutel heeft alleen toegang tot de taken van de eigenaar en alleen tot de mogelijkheden die bij het maken zijn geselecteerd.

formats:read

usage:read

jobs:read

jobs:write

Authorization-header

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

Alleen server-side

Plaats geen ontwikkelaarsleutel in een webpagina, gedistribueerde desktop-binary of mobiele app. Proxy verzoeken via uw backend.

Gedelegeerde gebruikers toegang nodig?

AI-clients moeten MCP met OAuth en PKCE gebruiken in plaats van een ontwikkelaars-API-sleutel te ontvangen.

POST /jobs

Kies de workflow die bij de bron past.

workflow=conversion

Bestaand machinebestand

Upload PES, DST, JEF of een andere leesbare borduurindeling en kies een andere schrijfbare uitvoer.

Vereist: workflow, format, file
Maximum bestand: 50 MB

workflow=digitising

JPG, PNG, SVG of WebP artwork

Genereer een steekvoorbeeld uit artwork. Voltooide breedte en maximum aantal draadkleuren zijn vereist.

Extra velden: width_mm, colour_count
Geldige bereiken: 10–300 mm · 1–24 kleuren
Maximum bestand: 20 MB

Enkele bestanden en batches

Gebruik file voor één bron of files[] voor maximaal 10 bronnen. Beperkte gratis verwerking kan één bestand per verzoek accepteren. Elke batch gebruikt één gedeelde workflow en uitvoerindeling.

202 Accepted

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

Aanmaken is asynchroon

HTTP 202 betekent dat de privétaak is geaccepteerd, niet dat het machinebestand klaar is. Bewaar zowel job.id en job.workflow; de workflow kiest de statusroute.

queuedWachten op een worker

processingEngine draait

completedControleer uitvoer en waarschuwingen

failedLees failureCode en failureReason

Bevragen en bestanden

Lees het resultaat, niet alleen de status.

Een voltooide respons bevat geparste metrics, waarschuwingen, gebeurtenissen, voorbeeldartefacten en uitvoerbestanden. Ondertekende URL’s zijn kortstondig; vraag de taak opnieuw op wanneer een URL verloopt.

Een verwerkingstaak ophalen · Shell

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

Metrics

Steekaantal, afmetingen en engine-specifieke metingen.

Waarschuwingen

Compatibiliteits- of productieopmerkingen die uw UI moet tonen.

Privébestanden

Ondertekende URL’s zijn 10 minuten geldig en handhaven nog steeds eigendom en ontgrendelstatus.

Ontgrendelen kan een recht verbruiken

Eerst inspecteren job.unlock of GET /usage. Het aanroepen van het ontgrendelingseindpunt kan een abonnementsquotum of bestaande verwerkingscredits verbruiken. Interne accounts kunnen mogelijk gratis ontgrendelen. Het opent geen afrekenpagina of aankoop van credits.

Endpointreferentie

Het volledige v1-oppervlak.

OpenAPI JSON

GET/formats

Leesbare bronnen, schrijfbare uitvoer en compatibiliteitswaarschuwingen.

formats:read

GET/usage

Preview-tegoed, credits, workflowkosten en resetdatums.

usage:read

GET/jobs

De 50 meest recente privé-verwerkingstaken van het account.

jobs:read

POST/jobs

Maak een conversie- of afbeelding-digitaliseer-previewtaak.

jobs:write

GET/jobs/conversion/{id}

Inspecteer één eigen conversietaak en de bijbehorende uitvoer.

jobs:read

GET/jobs/digitising/{id}

Inspecteer één eigen digitaliseertaak en de bijbehorende uitvoer.

jobs:read

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

Plaats een mislukte taak opnieuw in de wachtrij zolang de privé-bron nog bestaat.

jobs:write

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

Ontgrendel een voltooide taak met tegoed of bestaande credits.

jobs:write

Lijstreacties

GET /formats retourneert data[] en artworkInputs[]. GET /jobs retourneert data[] plus freeUsage en is beperkt tot de 50 meest recente taken.

Opnieuw proberen reacties

Opnieuw proberen accepteert alleen een failed taak waarvan de bron niet is verlopen. Een succesvolle poging retourneert HTTP 202 met de taak teruggezet naar queued.

Fouten en limieten

Faal duidelijk. Probeer bewust opnieuw.

401

Ontbrekende, ongeldige, verlopen of ingetrokken sleutel

403

Ontbrekende mogelijkheid of resource behoort toe aan een andere gebruiker

404

Taak of privébestand is niet gevonden

409

Taakstatus staat deze actie niet toe

410

Bronupload is verlopen

422

Ongeldige velden, bestand, indeling of onvoldoende quota

429

Limiet overschreden

422 validatiefout

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

60 verzoeken per minuut

De algemene limiet geldt per API-sleutel, met een afzonderlijk netwerkplafond. Upload-, verwerkings- en ontgrendelroutes hebben strengere misbruikcontroles.

HTTP 429 afhandelen

Respecteer Retry-After en gebruik exponentiële backoff met jitter. Poll niet continu voltooide of mislukte taken.

Bouwen voor een AI-agent?

Gebruik OAuth + MCP, geen API-sleutel.

De agentgids bevat verbindingsinstellingen, discovery-URL’s, OAuth PKCE, elk toolschema en kant-en-klare JSON-RPC-voorbeelden.

MCP-documentatie openen

Hulp nodig? Contacteer ontwikkelaarsondersteuning

Download de OpenAPI-beschrijving