API 참조 · v1JSON + multipart

자수 기능 추가 제품에.

비공개 이미지 디지타이징과 실제 기계 파일 변환을 위한 실용적인 REST API입니다. 이 페이지는 빠른 시작, 엔드포인트 참조 및 오류 안내서입니다.

API 키 발급 OpenAPI 3.1

기본 URL

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

인증

Bearer 키

요청 제한

60/min

작업

비동기

키는 범위가 지정되며 만료되고 즉시 취소할 수 있으며 한 번만 표시됩니다. 서버에 보관하세요. 브라우저나 모바일 클라이언트 코드에 포함하지 마세요.

개요 빠른 시작 인증 작업 생성 작업 수명 주기 엔드포인트 참조 오류 및 한도

빠른 시작

세 단계로 첫 작업 시작하기.

키 생성

서비스에 필요한 기능만 선택하고 비밀 키는 서버 측 비밀 관리자에 저장하세요.

원본 전송

워크플로, 출력 형식, 비공개 원본 파일을 포함한 multipart form data를 POST하세요.

작업 폴링

반환된 워크플로와 작업 ID를 사용하여 상태가 완료 또는 실패가 될 때까지 폴링하세요.

변환 작업 생성 · 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]"

인증

범위가 지정된 Bearer 키.

모든 요청의 Authorization 헤더에 키를 전송하세요. 키는 소유자의 작업과 생성 시 선택한 기능에만 접근할 수 있습니다.

formats:read

usage:read

jobs:read

jobs:write

Authorization 헤더

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

서버 측 전용

개발자 키를 웹 페이지, 배포용 데스크톱 바이너리 또는 모바일 앱에 포함하지 마세요. 백엔드를 통해 요청을 프록시하세요.

위임된 사용자 접근이 필요하신가요?

AI 클라이언트는 개발자 API 키 대신 OAuth와 PKCE가 포함된 MCP를 사용해야 합니다.

POST /jobs

원본에 맞는 워크플로를 선택하세요.

workflow=conversion

기존 기계 파일

PES, DST, JEF 또는 다른 읽을 수 있는 자수 형식을 업로드하고 다른 쓰기 가능한 출력 형식을 선택하세요.

필요: workflow, format, file
최대 파일: 50 MB

workflow=digitising

JPG, PNG, SVG 또는 WebP 아트워크

아트워크에서 스티치 미리보기를 생성합니다. 완성 폭과 최대 실 색상 수가 필요합니다.

추가 필드: width_mm, colour_count
유효 범위: 10–300 mm · 1–24 색상
최대 파일: 20 MB

단일 파일 및 배치

사용 file 단일 원본용 또는 files[] 최대 10개 원본용입니다. 무료 처리 제한은 요청당 한 파일만 허용할 수 있습니다. 모든 배치는 하나의 공유 워크플로와 출력 형식을 사용합니다.

202 Accepted

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

생성은 비동기입니다

HTTP 202는 비공개 작업이 접수되었음을 의미하며, 기계 파일이 준비되었음을 의미하지 않습니다. 다음을 모두 유지하세요 job.id 및 job.workflow; 워크플로가 상태 경로를 선택합니다.

queued작업자 대기 중

processing엔진 실행 중

completed출력 및 경고 확인

failedfailureCode와 failureReason 확인

폴링 및 파일

상태뿐만 아니라 결과도 확인하세요.

완료된 응답에는 파싱된 지표, 경고, 이벤트, 미리보기 아티팩트 및 출력 파일이 포함됩니다. 서명된 URL은 수명이 짧습니다. URL이 만료되면 작업을 다시 요청하세요.

처리 작업 가져오기 · Shell

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

지표

스티치 수, 치수 및 엔진별 측정값.

경고

UI에 표시해야 하는 호환성 또는 생산 관련 참고 사항.

비공개 파일

서명된 URL은 10분 동안 유효하며 소유권과 잠금 해제 상태를 계속 적용합니다.

잠금 해제 시 권한이 소모될 수 있음

먼저 확인 job.unlock 또는 GET /usage. 잠금 해제 엔드포인트 호출 시 구독 허용량 또는 기존 처리 크레딧이 소모될 수 있습니다. 내부 계정은 무료로 잠금 해제할 수 있습니다. 결제 또는 크레딧 구매가 열리지 않습니다.

엔드포인트 참조

전체 v1 인터페이스.

OpenAPI JSON

GET/formats

읽기 가능 원본, 쓰기 가능 출력 및 호환성 경고.

formats:read

GET/usage

미리보기 허용량, 크레딧, 워크플로 비용, 초기화 날짜.

usage:read

GET/jobs

계정의 최근 비공개 처리 작업 50개.

jobs:read

POST/jobs

변환 또는 이미지 디지타이징 미리보기 작업을 생성합니다.

jobs:write

GET/jobs/conversion/{id}

소유한 변환 작업 하나와 그 출력을 검사합니다.

jobs:read

GET/jobs/digitising/{id}

소유한 디지타이징 작업 하나와 그 출력을 검사합니다.

jobs:read

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

비공개 원본이 아직 존재하는 동안 실패한 작업을 다시 대기열에 넣습니다.

jobs:write

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

허용량 또는 기존 크레딧으로 완료된 작업을 잠금 해제합니다.

jobs:write

목록 응답

GET /formats 반환 data[] 및 artworkInputs[]. GET /jobs 반환 data[] 추가 freeUsage 최근 50개 작업으로 제한됩니다.

재시도 응답

재시도는 다음 작업만 허용합니다 failed 원본이 있는 작업 만료되지 않은 작업입니다. 재시도 성공 시 작업이 다음 상태로 초기화된 HTTP 202를 반환합니다 queued.

오류 및 요청 제한

명확하게 실패하고 의도적으로 재시도하세요.

401

키가 없거나 유효하지 않거나 만료되었거나 취소됨

403

필요한 기능이 없거나 리소스가 다른 사용자 소유임

404

작업 또는 비공개 파일을 찾을 수 없음

409

작업 상태가 이 작업을 허용하지 않음

410

원본 업로드가 만료됨

422

잘못된 필드, 파일, 형식 또는 할당량 부족

429

요청 제한 초과

422 유효성 검사 오류

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

분당 60회 요청

일반 제한은 API 키당 적용되며 별도의 네트워크 상한이 있습니다. 업로드, 처리 및 잠금 해제 경로는 더 엄격한 남용 방지 제어가 적용됩니다.

HTTP 429 처리

준수 Retry-After 을 준수하고 지터가 포함된 지수 백오프를 사용하세요. 완료 또는 실패한 작업을 계속 폴링하지 마세요.

AI 에이전트를 위한 개발 중이신가요?

API 키 대신 OAuth + MCP를 사용하세요.

에이전트 가이드에는 연결 설정, 검색 URL, OAuth PKCE, 모든 도구 스키마 및 복사 가능한 JSON-RPC 예제가 포함되어 있습니다.

MCP 문서 열기

도움이 필요하신가요? 개발자 지원 문의

OpenAPI 설명 다운로드