Sume API로 AI 영상 생성 Job이나 실행을 취소하는 방법

Sume 생성 Job을 취소하려면 POST /v1/jobs/{id}/cancel을 보내세요. 취소는 생성 작업이 시작되기 전에만 성공하며, 그 뒤에는 409 job_generation_already_started가 반환되고 Job은 정상적으로 끝납니다. Format, Action, Agent 실행에는 각자 멱등한 취소 경로가 있으며, Format 실행이 취소 전에 끝낸 생성은 그대로 과금됩니다.

아래 규칙은 Sume 문서 Job과 결과 (영문), API 레퍼런스, 실행과 결과 (영문), Run 웹훅 (영문)과 라이브 OpenAPI 레퍼런스에서 가져왔으며, 모두 2026-09-26에 확인했습니다.

어떤 취소 엔드포인트를 호출하나요?

Job과 실행은 서로 다른 리소스이며, 각각 자체 경로가 있습니다. 경로를 직접 만들지 말고 상태 페이로드나 영수증의 cancel_url을 따르세요.

생성 Job은 언제 취소할 수 있나요?

생성 작업이 시작되기 전에만 가능합니다. 문서화된 취소 경로는 queued -> canceled입니다. 외부 생성 작업이 하나라도 시작되면, 이미 생성에 제출된 작업을 사용량 정산이 환불하는 일이 없도록 Sume가 취소를 거부하며, Job은 정상적으로 완료되거나 실패합니다.

• 호출하기 전에 확인하세요. 상태 페이로드의 cancelable은 외부 생성 작업이 시작되기 전에만 true이고, 그 뒤에는 cancel_url이 null이 됩니다.
• 늦은 취소에는 details.cancelable: false와 함께 409 job_generation_already_started가 돌아옵니다.
• 이미 완료되거나 실패한 Job도 취소할 수 없으며, 이 경로는 409로 응답합니다.
• 이미 canceled인 Job을 취소하면 같은 Job이 idempotency_hit: true와 함께 돌아옵니다.

curl -X POST https://api.sume.com/v1/jobs/job_123/cancel \
  -H "Authorization: Bearer $SUME_API_KEY"

실행 취소는 어떻게 동작하나요?

POST /v1/format-runs/{run_id}/cancel은 formats:write가 필요하고 멱등이며, 어느 쪽이든 현재 영수증이 돌아옵니다. cancel_effect가 무슨 일이 있었는지 알려 줍니다. canceled는 이 호출이 진행 중인 실행을 멈췄다는 뜻이고, no_op은 실행이 이미 끝나 있었다는 뜻입니다. cancelable은 실행이 queued나 processing인 동안 true입니다.

Action 실행에서도 cancelable은 queued나 processing인 동안 true이며, 이미 종료된 실행을 취소하면 그 종료 영수증이 200으로 돌아옵니다. Agent Completions의 경우, 문서는 진행 중인 실행을 멈추는 방법으로 같은 POST …/cancel 호출을 보여 줍니다.

대량 실행 큐에는 큐 취소 엔드포인트가 없습니다. 대신 자식 실행을 하나씩 취소하세요. 그러면 해당 큐 항목이 canceled가 되고, 그 슬롯이 큐에서 기다리는 다음 항목에 돌아갑니다. Format 대량 실행을 참고하세요.

취소한 뒤에도 과금되는 것은 무엇인가요?

Sume는 유료 Job을 접수할 때 예상 금액을 예약하고, 확정 전에 취소되면 그 예약을 환불합니다. 취소가 거부된 Job은 계속 실행됩니다. 성공적으로 완료되면 예약이 확정되고, 실패하면 해당하는 경우 예약이 해제되거나 환불됩니다.

Format 실행에서는 실행이 취소 전에 완료한 생성이 과금되며, usage에 그 금액이 나옵니다. 나중에 Job이나 실행 하나를 확인하려면 job_id나 run_id를 붙여 GET /v1/usage를 호출하세요. 정확히 얼마가 들었는지 합산해 줍니다. 그 원장을 읽는 방법은 실패한 AI 영상 Job에도 비용이 드나요?에서 보여 줍니다.

취소하면 웹훅이 오나요?

Job은 웹훅을 보내지만 실행은 보내지 않습니다. webhook_url과 함께 제출한 Job은 status: "ERROR"와 error 객체가 담긴 종료 이벤트 job.canceled를 받습니다.

취소된 Format, Action, Agent 실행은 웹훅을 절대 보내지 않습니다. 취소 응답을 신뢰하고, 상태가 canceled가 될 때까지 status_url을 폴링하세요. POST를 기다리지 마세요. 웹훅에만 의존하는 연동은 이 경로를 취소 응답 자체에서 처리해야 합니다.

타임아웃이나 중단된 폴링 루프가 무언가를 취소하나요?

아닙니다. 클라이언트 쪽 타임아웃은 Job을 취소하지 않습니다. Job은 계속 실행되고 계속 과금됩니다. 폴링 루프를 그만둬도 Format 실행이나 그 지출은 멈추지 않습니다. 타임아웃된 SDK 대기도 아무것도 취소하지 않습니다. 작업을 멈추려면 Job에는 cancelApiJob을, Format 실행에는 cancelFormatRun을 호출하세요. CLI에는 sume jobs cancel <job_id> --confirm-submit이 있고, 호스팅 MCP에서 jobs_cancel은 idempotency_key를 받는 쓰기 도구입니다.

제출이 429 queue_full로 실패했을 때, 더 이상 필요 없는 대기 중인 Job을 취소하는 것은 문서에 나온 대응 단계 중 하나입니다. 나머지는 Sume 영상 Job 동시성과 큐에서 다룹니다.