Sume API 상태 값 정리: Job, 실행, 큐, 웹훅

Sume API의 생성 Job은 queued, processing, completed, failed, canceled 상태를 거치고, Format과 Action 실행에는 skipped가 더해지며, POST /v1/videos는 같은 수명주기를 pending, in_progress, completed, failed, cancelled로 표기합니다. 대량 실행 큐, 웹훅 전달, 사용량 행, 공유 권한, 잔액에는 각각 고유한 값이 있으며, 아래에 정리했습니다.

모든 값은 Job과 결과 (영문), 실행과 결과 (영문), 오류와 요청 한도 (영문) 같은 Sume 문서나 라이브 OpenAPI 레퍼런스에서 가져왔으며, 2026-09-27에 확인했습니다. 각 표의 캡션에 출처 페이지를 적었습니다. Job과 실행이 어떻게 다른지는 Sume Job과 실행의 차이를 참고하세요.

Job과 실행은 어떤 상태 값을 쓰나요?

각 행에는 해당 객체를 자세히 설명하는 글을 링크했습니다.

큐, 웹훅, 과금은 어떤 상태 값을 쓰나요?

다음 객체들은 Job과 실행 안에 있지 않고, 그 주변에 있습니다.

canceled인가요, cancelled인가요?

POST /v1/videos를 제외하면 모두 l이 하나입니다. Job, 실행, 대량 실행 항목, 리소스는 canceled로 쓰고, OpenRouter 형태의 영상 경로는 cancelled로 답하며, queued 대신 pending을, processing 대신 in_progress를 씁니다. 하나의 enum을 공유하지 말고 표면별로 문자열을 비교하세요.

Scheduled 실행을 보면 그 이유를 알 수 있습니다. 이 실행의 상태는 내부 상태를 다시 매핑한 값입니다. done은 completed로, error는 failed로, cancelled는 canceled로 노출되며, 문서는 Job 쪽 상태 문자열이 그대로 통한다고 가정하지 말라고 경고합니다.

어떤 값이 종료 상태이고, 어떤 값에서 웹훅이 가나요?

Job은 completed, failed, canceled에서, 실행은 이 세 값이나 skipped에서 폴링을 멈추세요. 다만 종료 상태라고 해서 웹훅이 전달되는 것은 아닙니다.

• Job 웹훅은 세 가지 종료 상태 모두에서 job.completed, job.failed, job.canceled로 전송됩니다.
• 실행 웹훅은 completed나 failed일 때 한 번 전송됩니다. canceled나 skipped 실행은 웹훅을 보내지 않으므로, 대신 취소 응답이나 생성 응답을 읽으세요.
• 건너뛴 Scheduled 실행에는 skip_reason: previous_run_active가 담깁니다. 언제 이렇게 되는지는 중복 실행 막기에서 다룹니다.
• 대량 실행 큐가 completed여도 counts.failed와 counts.canceled는 따로 확인해야 합니다.

outcome은 웹훅의 status에 무엇을 더하나요?

실행 웹훅의 status는 값이 두 가지뿐입니다. outcome은 쓸 수 있는 출력을 받았는지에 답합니다. ok는 출력과 함께 완료된 실행, error는 완료되지 못한 실행, degraded는 완료되고 과금됐지만 영수증에 여전히 output_error가 담긴 실행입니다. 예를 들어 output_extraction_failed가 details.reason: harvest_unavailable을 보고하면 완료된 영수증에도 output_error가 담깁니다. 이때 투영은 실행되지 못했고, status는 completed로 남으며, 다음 읽기에서 영수증이 채워집니다.

API에서는 결과가 output_schema에 맞지 않으면 실행이 실패합니다. status는 failed가 되고, error에는 output_error와 같은 사유가 담깁니다. 이 실행은 status: "ERROR", outcome: "error"로 도착합니다. 쓸 수 있는 출력을 받았는지가 궁금하다면 outcome으로 분기하세요.