대기열과 제한

대기열Copy Anchor Link

• 계정마다 최대 10개 작업이 동시에 처리됩니다.
• 그 뒤로 최대 30개 작업이 대기열에서 기다립니다. 작업이 기다리는 동안 GET /edits/{id}는 queue_position (앞에서 기다리는 작업 수. 실행 중인 작업은 세지 않으므로 0은 다음에 시작한다는 뜻)과 estimated_seconds (완료 예상 시간)를 반환합니다.
• 이미 30개가 기다리고 있으면 POST /edits는 Retry-After 헤더와 함께 **503 queue_full**을 반환합니다. 차감되지 않습니다.
• 작업은 대기열을 떠난 뒤 최대 10분 동안 실행될 수 있습니다. 기다린 시간은 포함되지 않으므로 대기열이 가득 차 있으면 마지막 작업은 최악의 경우 약 30분이 걸릴 수 있습니다. 대부분의 작업은 1~2분, 10개 중 9개는 3분 안에 끝납니다.

요청 한도Copy Anchor Link

각 계정(모든 키가 공유)은 임의의 최근 60초 동안 다음만큼 요청할 수 있습니다:

유효한 키가 있는 모든 요청이 계산되며, 오류로 거절된 요청도 포함됩니다. 키가 없거나 잘못된 요청은 어떤 계정에도 계산되지 않습니다.

한도를 넘으면 Retry-After와 함께 429 rate_limited가 반환됩니다. 값은 항상 정수 초이며, 구간 안에서 가장 오래된 요청이 만료될 때까지의 시간입니다. GET /account는 현재 한도를 limits에 담아 반환합니다. 엔터프라이즈 계정은 더 높은 한도를 가질 수 있습니다.

폴링Copy Anchor Link

• 작업이 **processing**이거나 queued이면서 queue_position이 0인 동안에는 GET /edits/{id}를 5초마다 폴링합니다.
• 대기열에서 더 뒤에 있는 동안에는 30초마다 확인합니다. estimated_seconds는 작업이 끝날 예상 시간이지 확인 간격이 아닙니다.

10개 처리 중, 30개 대기 중일 때 조회는 분당 최대 190회로 한도 240회 안에 듭니다. 폴링을 아예 하지 않으려면 callback_url을 넘겨 웹훅을 받으세요.

이미지Copy Anchor Link

• JPEG, PNG 또는 WebP, 최대 20 MB, 긴 변은 최대 8000 px.
• image_url, image_base64, 멀티파트 image 파일, 또는 이전 OCR 호출의 image_id로 보냅니다. 요청마다 이 중 정확히 하나만 씁니다.
• 편집당 최대 20개 교체.

업로드 방식별 인코딩, EXIF, 투명도, 결과 파일은 이미지를 보세요.

안전한 재시도Copy Anchor Link

모든 POST /edits에 Idempotency-Key 헤더를 보내면 타임아웃이나 네트워크 오류 뒤에도 안전하게 재시도할 수 있습니다. 24시간 안에 같은 키를 다시 쓰면 새 작업을 만들고 차감하는 대신, 원래 작업의 id와 현재 상태 (이미 processing이거나 끝났을 수도 있음)와 함께 202를 반환합니다. 본문이 달라도 마찬가지입니다. 키는 계정 단위이며 그 계정의 모든 API 키가 공유합니다. 거절된 요청(모든 4xx 또는 5xx)은 키를 소모하지 않으므로 고친 뒤 같은 키로 다시 보낼 수 있습니다.