> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.

# 이미지 벡터화 API로 일괄 처리하고 중단된 작업 이어가기

> 파일별 변환 ID와 진행 상태를 저장하는 큐로 이미지를 일괄 벡터화합니다. 실패한 파일을 기록하고 완료된 작업을 다시 제출하지 않고 재개하세요.

Source: https://perfectvector.com/ko/blog/batch-vectorize-images-api

Language: ko
Author: Jay
Published: 2026-11-10T08:00:00+09:00

API로 이미지를 일괄 벡터화하려면 원본을 하나씩 큐에 넣고 다음 파일로 넘어가기 전에 진행 상태를 저장하세요. PerfectVector API v1에서는 배치 전체를 작업 프로그램이 관리합니다. API는 요청당 이미지 한 장을 받으며, 기본 설정에서 계정당 실사용 변환을 한 번에 하나만 처리합니다. [PerfectVector API 제한](https://perfectvector.com/docs/api/limits)

## 이미지마다 큐에 레코드 만들기

각 원본 이미지의 고정 사본과 별도 출력 폴더를 준비하세요. 아래 예제는 작업 프로세스 하나, 로컬 SQLite 데이터베이스, 단일 프레임 PNG·JPEG·WebP 파일이 있는 폴더를 가정합니다. 큐에 파일을 넣기 전에 [API 파일 제한](https://perfectvector.com/docs/api/limits)을 확인하세요. 이름이 같은 `logo.png` 파일이 서로의 결과를 덮어쓰지 않도록 출력 경로를 고유하게 정합니다.

첫 업로드 전에 아래 필드를 한 레코드에 저장하세요.

| 필드    | 기록할 내용                                          |
| ----- | ----------------------------------------------- |
| 원본    | 고정 경로나 객체 버전, 원본 바이트의 해시.                       |
| 요청 키  | 같은 작업의 재제출을 식별하는 멱등성 키. 최초 POST를 시도한 시각도 기록합니다. |
| 변환 ID | API의 `vec_…` ID. 응답을 받는 즉시 저장합니다.               |
| 출력    | 고유한 로컬 경로와 마지막으로 확인한 큐 상태.                      |
| 실패 정보 | 확인할 수 있다면 API 문제 코드, 요청 ID 또는 변환 오류.            |

POST를 보내기 전에 레코드를 커밋하세요. API가 업로드를 받았는데 ID를 받기 전에 연결이 끊겨도 저장된 키로 재요청할 수 있습니다. PerfectVector는 같은 계정과 모드에서 최초 요청 이후 24시간 동안 이 키를 인식합니다. 재요청할 때 이미지 바이트와 옵션은 그대로 유지하세요. [PerfectVector 멱등성](https://perfectvector.com/docs/api/idempotency)

**작업 흐름**

![키가 붙은 래스터 이미지 묶음에서 변환 기록을 거쳐 SVG로 이어집니다. 재시작 화살표는 저장된 변환 기록으로 돌아갑니다.](https://perfectvector.com/blog/batch-vectorize-images-api/workflow.webp)

*다운로드 전에 변환 ID를 저장하세요. 중단됐다면 그 ID부터 다시 이어가면 됩니다.*

## 한 번에 한 건씩 제출하고 상태를 확인한 뒤 저장하기

이미지를 `image` 필드에 담고 레코드의 `Idempotency-Key`를 헤더에 넣어 `/v1/vectorizations`로 멀티파트 POST를 보내세요. 제출 응답을 빨리 받으려면 `Prefer: respond-async`를 사용합니다. 제출 응답에서 받은 ID를 저장한 뒤 상태를 확인하세요. `202`는 변환이 아직 끝나지 않았다는 뜻입니다. `201`은 변환 성공과 실패를 모두 나타낼 수 있으므로 JSON 상태를 읽어야 합니다. [PerfectVector 대기와 비동기 처리](https://perfectvector.com/docs/api/waiting-and-async)

아래는 작업 프로세스의 판단 순서입니다. `saved` 같은 큐 상태는 직접 정하는 이름입니다. API는 `processing`, `succeeded` 같은 상태를 반환합니다.

| 디스크에 저장된 큐 레코드   | 다음 작업                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------- |
| 새 레코드, 키 저장됨     | 원본 바이트를 업로드하고 반환된 변환 ID를 기록합니다.                                                          |
| 제출 여부 불확실, ID 없음 | 재요청 가능 시간 안이라면 저장된 키로 동일한 업로드를 다시 보냅니다. 시간이 지났다면 과금될 수 있는 새 변환을 시도하기 전에 검토가 필요하다고 표시합니다. |
| 변환 ID 저장됨        | 기존 ID로 상태를 확인합니다. 요청 사이에 약 2초 기다리고 요청 한도에 따른 대기 시간도 지킵니다.                                |
| 변환 성공, 파일 없음     | 결과를 받아 `image/svg+xml`인지 확인합니다. 임시 파일에 쓴 뒤 최종 경로로 옮기고 나서 저장 완료를 기록합니다.                   |
| 저장 완료            | POST를 건너뜁니다. 출력 파일이 없어졌다면 링크가 유효할 때 기존 결과를 다시 받습니다.                                      |
| 거부 또는 실패         | HTTP 문제 정보나 변환의 최종 오류를 기록합니다. 입력이 잘못됐다면 수정한 뒤 새 작업으로 시도합니다.                              |

POST가 `429` 또는 `503`을 반환하면 `Retry-After`를 지키고, 최초 요청 이후 24시간 안에 원래 키와 같은 이미지, 옵션으로 다시 시도하세요. `too_many_in_flight`라면 진행 중인 실사용 변환도 끝날 때까지 기다립니다. 변환 ID가 있으면 다시 제출하기 전에 확인하세요. 최종 상태가 `failed`이고 오류가 `timeout` 또는 `provider_unavailable`이라면 재시도할 때 새 키가 필요합니다. 후자의 경우 서비스가 복구된 뒤 시도하세요. 클라이언트에서 시간 초과가 나면 원래 변환의 상태를 알 수 없으므로 기존 ID를 확인하거나 유효 시간 안에 원래 키로 재요청하세요. [PerfectVector API 오류](https://perfectvector.com/docs/api/errors)

작업 프로세스를 다시 시작해도 새 변환 없이 상태를 확인하거나 결과를 다시 받을 수 있습니다. 성공한 SVG를 다운로드해 저장한 뒤 다음 항목으로 넘어가세요. API 결과는 변환이 끝난 뒤 24시간 후에 만료됩니다. [PerfectVector 결과와 다운로드](https://perfectvector.com/docs/api/results)

아래 의사 코드를 데이터베이스와 HTTP 클라이언트에 맞춰 구현하세요. 이어지는 실험은 작업 프로세스가 각 요청을 기록하고, 두 번째 변환 ID를 커밋한 직후에만 테스트용으로 일시 중지할 수 있다고 가정합니다.

```text
for each queue row in a stable order:
    if the row is rejected or its saved SVG is still on disk:
        continue
    if the row has no conversion ID:
        verify source bytes match the stored digest
        if an earlier POST is uncertain and the replay window expired:
            flag the row for review and continue
        POST with the stored key and original bytes and options
        if the response is a permanent input rejection:
            commit the error and continue
        if the POST times out or the service requests a retry:
            keep the same key, record the retry time and stop this run
        commit the returned conversion ID
        pause here when testing recovery after a commit
    GET status by conversion ID, waiting between pending responses
    if conversion failed:
        commit its error and continue
    download the existing result and check the SVG media type
    write to a temporary file and rename it to the output path
    commit the saved state
```

## 파일 세 개로 재시작 확인하기

작은 PNG 로고 두 개와 손상된 PNG 하나를 사용하세요. 손상된 파일도 일부러 큐에 넣어 요청이 거부된 뒤에도 처리가 이어지는지 확인합니다. 테스트 키로 정상 파일 두 개를 보내면 각각 샘플 SVG가 반환됩니다. 손상된 파일은 검증에서 거부되고 출력 폴더에 SVG가 생기지 않아야 합니다. 테스트 모드는 정상 파일 두 개에 동일한 샘플 SVG를 반환합니다. [PerfectVector 테스트 모드](https://perfectvector.com/docs/api/test-mode)

1. 첫 파일이 `saved` 상태가 될 때까지 실행합니다. 두 번째 정상 파일의 ID는 저장됐지만 출력은 저장되기 전에 작업을 멈춥니다.
2. 작업을 재시작합니다. 첫 파일을 건너뛰고 두 번째 파일의 기존 변환 ID로 다운로드하는지 확인합니다.
3. 손상된 파일이 문제 코드와 함께 실패 보고서에 나타나고 해당 SVG는 생성되지 않았는지 확인합니다.
4. 작업을 한 번 더 실행합니다. 저장된 두 파일이 그대로 있고 성공한 업로드를 다시 보내지 않는지 확인합니다.

API 테스트 키로 재시작을 확인했습니다. 샘플 SVG 두 개를 저장했고, 손상된 파일 하나는 거부로 기록했습니다. 두 번째 성공 파일은 기존 ID로 이어서 받았습니다. 마지막 실행에서는 요청이 한 건도 발생하지 않았습니다. 테스트 변환은 즉시 끝나므로 대기 상태는 별도 테스트 응답으로 확인하세요.

## 자주 묻는 질문

### API 한 번 호출로 모든 파일을 제출할 수 있나요?

PerfectVector API v1은 POST 한 번에 이미지 한 장을 받습니다. 배치의 각 파일을 별도 요청으로 제출하세요. 실사용 모드에서는 계정의 동시 처리 한도를 지키고, 현재 변환이 끝난 뒤 다음 파일을 제출하세요. [PerfectVector API 제한](https://perfectvector.com/docs/api/limits)

### SVG가 이미 만료됐다면 어떻게 하나요?

이전에 내려받았다면 저장된 SVG를 사용하세요. 없다면 변환 상태를 확인한 뒤 새 작업을 시작할지 결정하세요. 새로운 실사용 변환이 성공하면 크레딧이 다시 차감될 수 있습니다. [PerfectVector 결과와 다운로드](https://perfectvector.com/docs/api/results)

## 출처

1. [PerfectVector — 제한](https://perfectvector.com/docs/api/limits) — 파일 검사와 계정당 기본 동시 처리 한도.
2. [PerfectVector — 멱등성](https://perfectvector.com/docs/api/idempotency) — 키 범위, 재요청 가능 시간, 입력 일치 조건.
3. [PerfectVector — 대기와 비동기 처리](https://perfectvector.com/docs/api/waiting-and-async) — 비동기 제출과 상태 확인.
4. [PerfectVector — 결과](https://perfectvector.com/docs/api/results) — 다운로드, 실패, 결과 만료.
5. [PerfectVector — 테스트 모드](https://perfectvector.com/docs/api/test-mode) — 테스트 키로 확인할 수 있는 업로드 검사와 출력.
6. [PerfectVector — 오류](https://perfectvector.com/docs/api/errors) — Retry-After 대기, 최종 실패, 새 키가 필요한 경우.

***

[PerfectVector API 페이지에서 테스트 키를 발급받고](https://perfectvector.com/ko/api) 준비한 파일 세 개로 확인해 보세요. 성공한 항목마다 디스크에 SVG가 있고, 재시작할 때 완료된 항목이 다시 제출되지 않는지 확인하세요.

## Explore

- [Read the HTML article](https://perfectvector.com/ko/blog/batch-vectorize-images-api)
- [PNG2SVG 일괄 변환: 다운로드한 ZIP 파일 확인하기](https://perfectvector.com/ko/blog/png2svg-batch-convert.md)
- [Claude Code와 MCP로 폴더의 이미지를 SVG로 일괄 변환하기](https://perfectvector.com/ko/blog/batch-vectorize-images-claude-code-mcp.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)