이미지 벡터화 API로 일괄 처리하고 중단된 작업 이어가기
파일별 변환 ID와 진행 상태를 저장하는 큐로 이미지를 일괄 벡터화합니다. 실패한 파일을 기록하고 완료된 작업을 다시 제출하지 않고 재개하세요.
목차
API로 이미지를 일괄 벡터화하려면 원본을 하나씩 큐에 넣고 다음 파일로 넘어가기 전에 진행 상태를 저장하세요. PerfectVector API v1에서는 배치 전체를 작업 프로그램이 관리합니다. API는 요청당 이미지 한 장을 받으며, 기본 설정에서 계정당 실사용 변환을 한 번에 하나만 처리합니다. PerfectVector API 제한
이미지마다 큐에 레코드 만들기
각 원본 이미지의 고정 사본과 별도 출력 폴더를 준비하세요. 아래 예제는 작업 프로세스 하나, 로컬 SQLite 데이터베이스, 단일 프레임 PNG·JPEG·WebP 파일이 있는 폴더를 가정합니다. 큐에 파일을 넣기 전에 API 파일 제한을 확인하세요. 이름이 같은 logo.png 파일이 서로의 결과를 덮어쓰지 않도록 출력 경로를 고유하게 정합니다.
첫 업로드 전에 아래 필드를 한 레코드에 저장하세요.
| 필드 | 기록할 내용 |
|---|---|
| 원본 | 고정 경로나 객체 버전, 원본 바이트의 해시. |
| 요청 키 | 같은 작업의 재제출을 식별하는 멱등성 키. 최초 POST를 시도한 시각도 기록합니다. |
| 변환 ID | API의 vec_… ID. 응답을 받는 즉시 저장합니다. |
| 출력 | 고유한 로컬 경로와 마지막으로 확인한 큐 상태. |
| 실패 정보 | 확인할 수 있다면 API 문제 코드, 요청 ID 또는 변환 오류. |
POST를 보내기 전에 레코드를 커밋하세요. API가 업로드를 받았는데 ID를 받기 전에 연결이 끊겨도 저장된 키로 재요청할 수 있습니다. PerfectVector는 같은 계정과 모드에서 최초 요청 이후 24시간 동안 이 키를 인식합니다. 재요청할 때 이미지 바이트와 옵션은 그대로 유지하세요. PerfectVector 멱등성
한 번에 한 건씩 제출하고 상태를 확인한 뒤 저장하기
이미지를 image 필드에 담고 레코드의 Idempotency-Key를 헤더에 넣어 /v1/vectorizations로 멀티파트 POST를 보내세요. 제출 응답을 빨리 받으려면 Prefer: respond-async를 사용합니다. 제출 응답에서 받은 ID를 저장한 뒤 상태를 확인하세요. 202는 변환이 아직 끝나지 않았다는 뜻입니다. 201은 변환 성공과 실패를 모두 나타낼 수 있으므로 JSON 상태를 읽어야 합니다. PerfectVector 대기와 비동기 처리
아래는 작업 프로세스의 판단 순서입니다. 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 오류
작업 프로세스를 다시 시작해도 새 변환 없이 상태를 확인하거나 결과를 다시 받을 수 있습니다. 성공한 SVG를 다운로드해 저장한 뒤 다음 항목으로 넘어가세요. API 결과는 변환이 끝난 뒤 24시간 후에 만료됩니다. PerfectVector 결과와 다운로드
아래 의사 코드를 데이터베이스와 HTTP 클라이언트에 맞춰 구현하세요. 이어지는 실험은 작업 프로세스가 각 요청을 기록하고, 두 번째 변환 ID를 커밋한 직후에만 테스트용으로 일시 중지할 수 있다고 가정합니다.
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 테스트 모드
- 첫 파일이
saved상태가 될 때까지 실행합니다. 두 번째 정상 파일의 ID는 저장됐지만 출력은 저장되기 전에 작업을 멈춥니다. - 작업을 재시작합니다. 첫 파일을 건너뛰고 두 번째 파일의 기존 변환 ID로 다운로드하는지 확인합니다.
- 손상된 파일이 문제 코드와 함께 실패 보고서에 나타나고 해당 SVG는 생성되지 않았는지 확인합니다.
- 작업을 한 번 더 실행합니다. 저장된 두 파일이 그대로 있고 성공한 업로드를 다시 보내지 않는지 확인합니다.
API 테스트 키로 재시작을 확인했습니다. 샘플 SVG 두 개를 저장했고, 손상된 파일 하나는 거부로 기록했습니다. 두 번째 성공 파일은 기존 ID로 이어서 받았습니다. 마지막 실행에서는 요청이 한 건도 발생하지 않았습니다. 테스트 변환은 즉시 끝나므로 대기 상태는 별도 테스트 응답으로 확인하세요.
자주 묻는 질문
API 한 번 호출로 모든 파일을 제출할 수 있나요?
PerfectVector API v1은 POST 한 번에 이미지 한 장을 받습니다. 배치의 각 파일을 별도 요청으로 제출하세요. 실사용 모드에서는 계정의 동시 처리 한도를 지키고, 현재 변환이 끝난 뒤 다음 파일을 제출하세요. PerfectVector API 제한
SVG가 이미 만료됐다면 어떻게 하나요?
이전에 내려받았다면 저장된 SVG를 사용하세요. 없다면 변환 상태를 확인한 뒤 새 작업을 시작할지 결정하세요. 새로운 실사용 변환이 성공하면 크레딧이 다시 차감될 수 있습니다. PerfectVector 결과와 다운로드
출처
- PerfectVector — 제한 — 파일 검사와 계정당 기본 동시 처리 한도.
- PerfectVector — 멱등성 — 키 범위, 재요청 가능 시간, 입력 일치 조건.
- PerfectVector — 대기와 비동기 처리 — 비동기 제출과 상태 확인.
- PerfectVector — 결과 — 다운로드, 실패, 결과 만료.
- PerfectVector — 테스트 모드 — 테스트 키로 확인할 수 있는 업로드 검사와 출력.
- PerfectVector — 오류 — Retry-After 대기, 최종 실패, 새 키가 필요한 경우.
PerfectVector API 페이지에서 테스트 키를 발급받고 준비한 파일 세 개로 확인해 보세요. 성공한 항목마다 디스크에 SVG가 있고, 재시작할 때 완료된 항목이 다시 제출되지 않는지 확인하세요.
