# 자수 파일 변환기 개발자 API

정규 페이지: https://embroideryfileconverter.com/ko/developers

이미지 디지타이징, 파일 변환, 작업 상태, 검증된 출력 및 서명된 다운로드를 위한 비공개 REST API로 자수 워크플로를 구축합니다.

## 올바른 통합 선택

- 백엔드, SaaS 제품, 전자상거래 워크플로, 자동화 또는 서버 측 애플리케이션에는 이 페이지의 REST API를 사용하세요.
- 어시스턴트가 OAuth를 통해 사용자를 대신해 작업해야 할 때는 [AI 에이전트 및 MCP 문서](https://embroideryfileconverter.com/ko/ai-agents)를 사용하세요.

개발자 API 키를 브라우저 JavaScript, 모바일 애플리케이션 또는 배포된 데스크톱 바이너리에 넣지 마세요.

## 기본 URL 및 인증

- 기본 URL: `https://embroideryfileconverter.com/api/developer/v1`
- 인증: `Authorization: Bearer efc_live_...`
- 작업 콘텐츠 유형: `multipart/form-data`
- 일반 기본 속도 제한: 키당 분당 60 요청, 별도의 네트워크 상한 적용
- 서명된 파일 URL 수명: 10분
- [OpenAPI 3.1 설명](https://embroideryfileconverter.com/developers/openapi.json)
- [API 키 생성 또는 취소](https://embroideryfileconverter.com/developers/keys)

API 키는 한 번만 표시되며 SHA-256 해시로만 저장되고 만료되며 즉시 취소할 수 있습니다. 사용 가능한 기능은 `formats:read`, `usage:read`, `jobs:read`, `jobs:write`입니다.

## 빠른 시작: 변환 작업 만들기

```bash
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 "file=@design.pes"
```

처리가 비동기이므로 API는 HTTP 202를 반환합니다:

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

`job.id`와 `job.workflow`를 모두 유지하세요. 상태가 `completed` 또는 `failed`가 될 때까지 워크플로별 작업 엔드포인트를 폴링하세요.

## 작업 생성 필드

### 변환

기존 자수 기계 파일에는 `workflow=conversion`을 사용하세요.

- 필수: `workflow`, `format`, `file` 또는 `files[]` 중 하나
- 최대 소스 크기: 파일당 50MB
- 출력 `format`은 쓰기 가능해야 하며 감지된 소스 형식과 달라야 합니다.

### 디지타이징

JPG, JPEG, PNG, SVG 또는 WebP 아트워크에는 `workflow=digitising`을 사용하세요.

- 필수: `workflow`, `format`, `file` 또는 `files[]` 중 하나, `width_mm`, `colour_count`
- `width_mm`: 10에서 300 사이의 숫자
- `colour_count`: 1부터 24까지의 정수
- 최대 소스 크기: 파일당 20MB

`files[]`는 한 배치에서 최대 10개의 소스를 허용합니다. 제한된 무료 처리 계정은 요청당 하나의 소스로 제한될 수 있습니다. 배치의 모든 파일은 동일한 워크플로와 출력 형식을 사용합니다.

## 작업 폴링

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

가능한 상태는 `queued`, `processing`, `completed`, `failed`입니다. 상세 작업 응답에는 지표, 경고, 실패 정보, 이벤트, 미리보기 산출물, 출력물, 잠금 해제 상태, 임시 서명 파일 URL이 포함됩니다. 서명 URL이 만료되면 작업을 다시 요청하세요.

## 전체 엔드포인트 참조

- `GET /formats`는 `formats:read` 권한이 필요하며 `data[]`와 `artworkInputs[]`를 반환합니다.
- `GET /usage`는 `usage:read` 권한이 필요하며 allowance, credits, workflow costs, reset dates를 포함한 `freeUsage`를 반환합니다.
- `GET /jobs`는 `jobs:read` 권한이 필요하며 최대 50개의 최근 소유 작업에 대한 `data[]`와 `freeUsage`를 반환합니다.
- `POST /jobs`는 `jobs:write` 권한이 필요하며 하나 이상의 비공개 비동기 미리보기 작업을 생성합니다.
- `GET /jobs/conversion/{id}`는 `jobs:read` 권한이 필요하며 소유한 파일 변환 작업 하나를 반환합니다.
- `GET /jobs/digitising/{id}`는 `jobs:read` 권한이 필요하며 소유한 디지타이징 작업 하나를 반환합니다.
- `POST /jobs/conversion/{id}/retry`와 `POST /jobs/digitising/{id}/retry`는 `jobs:write` 권한이 필요합니다. 만료되지 않은 소스가 있는 실패한 작업만 재시도할 수 있습니다.
- `POST /jobs/conversion/{id}/unlock`과 `POST /jobs/digitising/{id}/unlock`은 `jobs:write` 권한이 필요합니다. 작업이 완료된 상태여야 합니다.
- 서명된 `GET /uploads/{id}/download`과 `GET /uploads/{id}/preview` URL은 `jobs:read` 권한이 필요합니다. 직접 구성하지 말고 작업 응답에 반환된 전체 URL을 사용하세요.

## 잠금 해제 동작

잠금 해제 전에 `job.unlock` 또는 `GET /usage`를 확인하세요. 잠금 해제 요청은 계정의 사용 가능한 구독 권한 또는 처리 크레딧을 소모할 수 있습니다. 내부 계정은 무료로 잠금 해제할 수 있습니다. 결제 또는 크레딧 구매가 열리지 않습니다. 할당량 또는 크레딧이 부족하면 유효성 검사 오류가 반환됩니다.

## 오류 및 재시도 동작

- `401`: 개발자 키가 없거나, 형식이 잘못되었거나, 만료되었거나, 취소됨
- `403`: 키 권한이 없거나 리소스가 다른 계정에 속함
- `404`: 작업 또는 비공개 파일을 찾을 수 없음
- `409`: 현재 작업 상태에서 재시도 또는 잠금 해제가 허용되지 않음
- `410`: 비공개 소스 업로드가 만료됨
- `422`: 잘못된 필드, 소스 파일, 출력 형식 또는 할당량 부족
- `429`: 속도 제한 초과; `Retry-After`를 준수하고 지터가 있는 지수 백오프 사용

작업 생성은 업로드 및 처리 제한으로 보호되며, 잠금 해제 경로는 더 엄격한 결제 작업 제한이 적용됩니다. 과도한 폴링을 피하고 종료 상태 후에는 중단하세요.

## 보안 모델

고객 파일은 비공개로 유지됩니다. 모든 작업 쿼리는 API 키 소유자로 제한되며, 서명 URL은 만료되고, 다운로드 가능한 기계 파일은 권한 확인이 통과될 때까지 잠겨 있으며, 요청된 작업 실행 전에 키 권한이 강제 적용됩니다.

## 관련 페이지

- [AI 에이전트 및 MCP](https://embroideryfileconverter.com/ko/ai-agents)
- [지원하는 자수 형식](https://embroideryfileconverter.com/ko/formats)
- [개인정보 및 파일 보관](https://embroideryfileconverter.com/ko/privacy)