Ricamo Convertitore file
AccediRegistrati gratis
Riferimento API · v1JSON + multipart

Integra il ricamo in il tuo prodotto.

Un’API REST pratica per la digitalizzazione privata delle immagini e la vera conversione di file macchina. Questa pagina è la guida rapida completa, il riferimento degli endpoint e la guida agli errori.

Ottieni una chiave APIOpenAPI 3.1

URL di base

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

Autenticazione

Chiave Bearer

Limite

60/min

Lavori

Asincrono

Le chiavi sono limitate per ambito, scadono, possono essere revocate immediatamente e vengono mostrate una sola volta. Conservale sul tuo server: non inserirle mai nel codice di browser o app mobile.

PanoramicaGuida rapidaAutenticazioneCrea un lavoroCiclo di vita del lavoroRiferimento endpointErrori e limiti
Guida rapida

Il tuo primo lavoro in tre passaggi.

01

Crea una chiave

Seleziona solo le funzioni necessarie al tuo servizio e conserva il segreto in un gestore di segreti lato server.

02

Invia l’origine

Invia dati multipart form con il flusso di lavoro, il formato di output e un solo file origine privato.

03

Interroga il lavoro

Usa il flusso di lavoro e l’ID del lavoro restituiti finché lo stato non è completato o non riuscito.

Crea un lavoro di conversione · 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]"

Autenticazione

Chiavi Bearer con ambito.

Invia la chiave nell’intestazione Authorization a ogni richiesta. Una chiave può accedere solo ai lavori del suo proprietario e solo alle funzioni selezionate al momento della creazione.

formats:read
usage:read
jobs:read
jobs:write
Intestazione Authorization
Authorization: Bearer efc_live_...
Accept: application/json

Solo lato server

Non incorporare una chiave sviluppatore in una pagina web, un eseguibile desktop distribuito o un’app mobile. Instrada le richieste tramite il tuo backend.

Ti serve l’accesso delegato dell’utente?

I client AI devono usare MCP con OAuth e PKCE invece di ricevere una chiave API sviluppatore.

POST /jobs

Scegli il flusso di lavoro corrispondente all’origine.

workflow=conversion

File macchina esistente

Carica PES, DST, JEF o un altro formato di ricamo leggibile e scegli un output scrivibile diverso.

Necessari
workflow, format, file
File massimo
50 MB
workflow=digitising

Grafica JPG, PNG, SVG o WebP

Genera un’anteprima di punti dalla grafica. Sono obbligatori la larghezza finita e il numero massimo di colori del filo.

Campi aggiuntivi
width_mm, colour_count
Intervalli validi
10–300 mm · 1–24 colori
File massimo
20 MB

File singoli e batch

Usa file per una sola origine o files[] per un massimo di 10 origini. L’elaborazione gratuita limitata può accettare un solo file per richiesta. Ogni batch usa un unico flusso di lavoro e formato di output condivisi.
202 Accepted
{
  "message": "Processing started.",
  "job": {
    "id": "01JEXAMPLEJOBID000000000",
    "status": "queued",
    "workflow": "conversion"
  },
  "jobs": [
    {
      "id": "01JEXAMPLEJOBID000000000",
      "status": "queued",
      "workflow": "conversion"
    }
  ],
  "freeUsage": {
    "previewRemaining": 2,
    "creditBalance": 0
  }
}

La creazione è asincrona

HTTP 202 indica che il lavoro privato è stato accettato, non che il file macchina è pronto. Conserva sia job.id sia job.workflow; il flusso di lavoro seleziona la rotta di stato.

queuedIn attesa di un worker
processingMotore in esecuzione
completedIspeziona output e avvisi
failedLeggi failureCode e failureReason

Polling e file

Leggi il risultato, non solo lo stato.

Una risposta completata include metriche analizzate, avvisi, eventi, anteprime e file di output. Gli URL firmati hanno vita breve; richiedi di nuovo il lavoro quando un URL scade.

Ottieni un lavoro di elaborazione · Shell
curl https://embroideryfileconverter.com/api/developer/v1/jobs/conversion/01JEXAMPLEJOBID000000000 \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json"

Metriche

Conteggio punti, dimensioni e misure specifiche del motore.

Avvisi

Note di compatibilità o di produzione che la tua UI deve mostrare.

File privati

Gli URL firmati durano 10 minuti e continuano a far rispettare il proprietario e lo stato di sblocco.

Lo sblocco può consumare un diritto

Ispeziona prima job.unlock o GET /usage. La chiamata all'endpoint di sblocco può consumare un abbonamento o crediti di elaborazione esistenti. Gli account interni possono sbloccare senza costi. Non apre un checkout né l'acquisto di crediti.

Riferimento endpoint

La superficie completa v1.

OpenAPI JSON
GET/formats

Sorgenti leggibili, output scrivibili e avvisi di compatibilità.

formats:read
GET/usage

Credito anteprima, crediti, costi dei flussi di lavoro e date di reset.

usage:read
GET/jobs

I 50 lavori di elaborazione privati più recenti dell’account.

jobs:read
POST/jobs

Crea un lavoro di anteprima di conversione o digitalizzazione da immagine.

jobs:write
GET/jobs/conversion/{id}

Ispeziona un lavoro di conversione dell’account e i suoi output.

jobs:read
GET/jobs/digitising/{id}

Ispeziona un lavoro di digitalizzazione dell’account e i suoi output.

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

Rimetti in coda un lavoro non riuscito mentre la sorgente privata esiste ancora.

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

Sblocca un lavoro completato usando il credito disponibile o crediti esistenti.

jobs:write

Risposte elenco

GET /formats restituisce data[] sia artworkInputs[]. GET /jobs restituisce data[] più freeUsage ed è limitato ai 50 lavori più recenti.

Risposte di nuovo tentativo

Il nuovo tentativo accetta solo un failed lavoro la cui origine non è scaduta. Un nuovo tentativo riuscito restituisce HTTP 202 con il lavoro reimpostato su queued.

Errori e limiti di frequenza

Fallisci in modo chiaro. Ritenta deliberatamente.

401

Chiave mancante, non valida, scaduta o revocata

403

Funzione mancante o risorsa di un altro utente

404

Lavoro o file privato non trovato

409

Lo stato del lavoro non consente questa azione

410

Il caricamento dell’origine è scaduto

422

Campi, file, formato non validi o quota insufficiente

429

Limite di frequenza superato

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

60 richieste al minuto

Il limite generale si applica per chiave API, con un tetto di rete separato. Le rotte di caricamento, elaborazione e sblocco hanno controlli anti-abuso più severi.

Gestisci HTTP 429

Rispetta Retry-After e usa backoff esponenziale con jitter. Non interrogare continuamente i lavori completati o non riusciti.

Stai sviluppando per un agente AI?

Usa OAuth + MCP, non una chiave API.

La guida dell’agente include la configurazione della connessione, gli URL di discovery, OAuth PKCE, ogni schema di tool ed esempi JSON-RPC pronti da copiare.

Apri la documentazione MCP

Serve aiuto? Contatta il supporto sviluppatori

Scarica la descrizione OpenAPI