Dokumentacja API · v1JSON + multipart

Dodaj haft do swojego produktu.

Praktyczne REST API do prywatnej digitalizacji obrazów i rzeczywistej konwersji plików maszynowych. Ta strona zawiera kompletny przewodnik szybkiego startu, opis punktów końcowych i obsługę błędów.

Pobierz klucz API OpenAPI 3.1

Bazowy adres URL

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

Autoryzacja

Klucz Bearer

Limit

60/min

Zadania

Asynchronicznie

Klucze mają określony zakres, wygasać, można je natychmiast unieważnić i są pokazywane tylko raz. Przechowuj je na serwerze — nigdy nie umieszczaj w kodzie przeglądarki ani aplikacji mobilnej.

Przegląd Szybki start Uwierzytelnianie Utwórz zadanie Cykl życia zadania Opis punktów końcowych Błędy i limity

Szybki start

Twoje pierwsze zadanie w trzech krokach.

Utwórz klucz

Wybierz tylko te uprawnienia, których potrzebuje Twoja usługa, i przechowuj sekret w menedżerze haseł po stronie serwera.

Wyślij źródło

Wyślij dane formularza multipart z procesem, formatem wyjściowym i jednym prywatnym plikiem źródłowym.

Odpytaj zadanie

Używaj zwróconego procesu i identyfikatora zadania, aż status zmieni się na ukończone lub niepowodzenie.

Utwórz zadanie konwersji · 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]"

Uwierzytelnianie

Klucze Bearer z określonym zakresem.

Wysyłaj klucz w nagłówku Authorization przy każdym żądaniu. Klucz ma dostęp tylko do zadań właściciela i tylko do uprawnień wybranych podczas tworzenia.

formats:read

usage:read

jobs:read

jobs:write

Nagłówek Authorization

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

Tylko po stronie serwera

Nie osadzaj klucza deweloperskiego na stronie WWW, w dystrybuowanym pliku binarnym pulpitu ani w aplikacji mobilnej. Przekierowuj żądania przez backend.

Potrzebujesz delegowanego dostępu użytkownika?

Klienci AI powinni korzystać z MCP z OAuth i PKCE zamiast otrzymywać klucz API dewelopera.

POST /jobs

Wybierz proces pasujący do źródła.

workflow=conversion

Istniejący plik maszynowy

Prześlij plik PES, DST, JEF lub inny czytelny format haftu maszynowego i wybierz inny zapisywalny format wyjściowy.

Wymagane: workflow, format, file
Maksymalny plik: 50 MB

workflow=digitising

Grafika JPG, PNG, SVG lub WebP

Wygeneruj podgląd ściegów z grafiki. Wymagana jest szerokość gotowego haftu i maksymalna liczba kolorów nici.

Dodatkowe pola: width_mm, colour_count
Prawidłowe zakresy: 10–300 mm · 1–24 kolory
Maksymalny plik: 20 MB

Pojedyncze pliki i partie

Użyj file dla jednego źródła lub files[] dla maksymalnie 10 źródeł. Ograniczona darmowa obróbka może akceptować jeden plik na żądanie. Każda partia używa jednego wspólnego procesu i formatu wyjściowego.

202 Accepted

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

Tworzenie jest asynchroniczne

HTTP 202 oznacza, że prywatne zadanie zostało przyjęte, a nie że plik maszynowy jest gotowy. Zachowaj zarówno job.id i job.workflow; proces wybiera trasę statusu.

queuedOczekiwanie na pracownika

processingSilnik działa

completedSprawdź wyniki i ostrzeżenia

failedOdczytaj failureCode i failureReason

Odpytywanie i pliki

Odczytaj wynik, nie tylko status.

Ukończona odpowiedź zawiera przetworzone metryki, ostrzeżenia, zdarzenia, artefakty podglądu i pliki wyjściowe. Podpisane adresy URL są krótkotrwałe; pobierz zadanie ponownie po wygaśnięciu adresu URL.

Pobierz zadanie przetwarzania · Shell

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

Metryki

Liczba ściegów, wymiary i pomiary specyficzne dla silnika.

Ostrzeżenia

Uwagi dotyczące zgodności lub produkcji, które powinien wyświetlać interfejs użytkownika.

Prywatne pliki

Podpisane adresy URL są ważne przez 10 minut i nadal wymuszają własność oraz stan odblokowania.

Odblokowanie może zużyć uprawnienie

Najpierw sprawdź job.unlock lub GET /usage. Wywołanie punktu końcowego odblokowania może zużyć limit subskrypcji lub istniejące kredyty przetwarzania. Konta wewnętrzne mogą odblokować bez opłaty. Nie otwiera to kasy ani zakupu kredytów.

Opis punktów końcowych

Pełny interfejs v1.

OpenAPI JSON

GET/formats

Źródła do odczytu, wyjścia do zapisu i ostrzeżenia zgodności.

formats:read

GET/usage

Limit podglądów, kredyty, koszty przepływów pracy i daty resetu.

usage:read

GET/jobs

50 najnowszych prywatnych zadań przetwarzania konta.

jobs:read

POST/jobs

Utwórz zadanie podglądu konwersji lub digitalizacji obrazu.

jobs:write

GET/jobs/conversion/{id}

Sprawdź jedno należące zadanie konwersji i jego dane wyjściowe.

jobs:read

GET/jobs/digitising/{id}

Sprawdź jedno należące zadanie digitalizacji i jego dane wyjściowe.

jobs:read

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

Ponownie kolejkuj nieudane zadanie, dopóki jego prywatne źródło nadal istnieje.

jobs:write

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

Odblokuj ukończone zadanie za pomocą limitu lub istniejących kredytów.

jobs:write

Odpowiedzi listy

GET /formats zwraca data[] i artworkInputs[]. GET /jobs zwraca data[] plus freeUsage i jest ograniczona do 50 najnowszych zadań.

Odpowiedzi ponowienia

Ponowienie akceptuje tylko failed zadanie, którego źródło nie wygasło. Pomyślne ponowienie zwraca HTTP 202 z zadaniem zresetowanym do queued.

Błędy i limity szybkości

Błędy jasno. Ponawiaj świadomie.

401

Brakujący, nieprawidłowy, wygasły lub unieważniony klucz

403

Brakujące uprawnienie lub zasób należy do innego użytkownika

404

Nie znaleziono zadania lub pliku prywatnego

409

Stan zadania nie pozwala na tę czynność

410

Przesyłanie źródła wygasło

422

Nieprawidłowe pola, plik, format lub niewystarczający limit

429

Przekroczono limit szybkości

Błąd walidacji 422

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

60 żądań na minutę

Ogólny limit dotyczy każdego klucza API, z osobnym limitem sieciowym. Trasy przesyłania, przetwarzania i odblokowywania mają surowsze zabezpieczenia przed nadużyciami.

Obsługuj HTTP 429

Szanuj Retry-After i używaj wykładniczego wycofywania z jitterem. Nie odpytaj ciągle ukończonych lub nieudanych zadań.

Tworzysz dla agenta AI?

Używaj OAuth + MCP, nie klucza API.

Przewodnik agenta zawiera konfigurację połączenia, adresy URL wykrywania, OAuth PKCE, schematy wszystkich narzędzi i gotowe przykłady JSON-RPC.

Otwórz dokumentację MCP

Potrzebujesz pomocy? Skontaktuj się z pomocą techniczną deweloperów

Pobierz opis OpenAPI