영상 생성 Job 상태 API 폴링하기: Sume의 /v1/jobs

Sume에서 영상 생성 Job을 폴링하려면 제출 호출이 돌려준 Job ID로 GET /v1/jobs/{id}/status를 읽고, 읽기 사이에 최소 next_poll_after_seconds만큼 기다리고, terminal이 true가 되면 멈춘 뒤, result_ready가 true일 때 GET /v1/jobs/{id}/result를 가져오세요. 실패하거나 취소된 Job에는 결과가 없습니다. 오류는 GET /v1/jobs/{id}의 Job 레코드에서 읽으세요.

아래 경로와 규칙은 Sume 문서 Job과 결과 (영문)와 API 레퍼런스에서, 필드 정의는 라이브 OpenAPI 레퍼런스에서 가져왔으며, 모두 2026-09-26에 확인했습니다. Format 실행에는 별도의 영수증이 있습니다. Sume Format 실행 수명주기를 참고하세요.

어떤 Job 엔드포인트를 폴링하나요?

Sume 생성 엔드포인트는 내구성 있는 Job을 만듭니다. Sume의 Job 봉투로 응답하는 제출은 첫 응답에 Job ID를 request_id로 담고, status_url과 result_url도 함께 담습니다. queued와 processing은 비종료 상태이고, completed, failed, canceled는 종료 상태입니다.

반면 POST /v1/videos는 봉투 없이 자체 형식의 객체로 응답합니다. 여기에는 Job id와 polling_url(GET /v1/videos/{id})이 담기며, 이 폴링 경로는 상태를 pending, in_progress, cancelled로 표기합니다. 같은 Job을 GET /v1/jobs/{id}/status와 GET /v1/jobs/{id}/result에서도 볼 수 있습니다.

상태 페이로드에서 무엇을 알 수 있나요?

폴링은 불리언(terminal, result_ready)이나 sume_status를 기준으로 하세요. 페이로드에는 다른 큐 API에서 넘어온 클라이언트를 위한 큐 형태의 status(IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELED)도 있습니다. 이 값은 sume_status와 일대일로 대응하며, 문서는 둘을 섞어 쓰지 말라고 안내합니다.

폴링 루프는 어떻게 동작해야 하나요?

문서는 클라이언트 쪽에서 Job을 기다리는 방법으로 이 루프를 제시합니다. 대기가 여러분의 클라이언트 안에서 일어나므로, HTTP 요청을 열어 두지 않고도 몇 분 동안 이어질 수 있습니다.

• next_poll_after_seconds가 있으면 그 값을 따르고, 없으면 지수 백오프하세요. 많은 Job에 걸친 촘촘한 루프는 피하세요.
• terminal이 true가 되거나 여러분이 정한 마감 시간이 지날 때까지 폴링하세요. 유료 생성에서 queued는 정상적인 접수 상태입니다.
• 상태 읽기는 쓰기 예산과 분리된 읽기 예산에서 차감되므로, 폴링 루프가 자신을 만든 제출을 429로 막을 수는 없습니다. Sume API 오류와 요청 한도를 참고하세요.
• TypeScript에서는 @sume-com/sdk의 waitForJob이 바로 이 루프입니다. 기본 타임아웃은 20분이고, 2초인 pollInterval은 하한입니다. next_poll_after_seconds가 더 길면 그 값이 우선합니다.

job = POST /v1/{product}/generate { mode: "async", ... } with Idempotency-Key
loop:
  s = GET /v1/jobs/{job.id}/status
  onStatus(s)                     # optional progress callback
  if s.terminal: break
  sleep(s.next_poll_after_seconds or exponential backoff)
if s.sume_status == "completed":
  return GET /v1/jobs/{job.id}/result
else:                             # failed or canceled
  raise from (GET /v1/jobs/{job.id}).job.error

완료된 결과에는 무엇이 들어 있나요?

GET /v1/jobs/{id}/result는 완료된 Job에만 응답합니다. 대기 중, 처리 중, 실패, 취소 상태의 Job에는 details에 현재 상태를 담은 409 job_not_completed가 돌아옵니다.

완료된 결과에는 artifacts가 들어 있을 수 있습니다. 각 항목에는 불투명한 id, media.sume.com의 url, type(image, video, audio, model, file 중 하나), content_type이 있고, size_bytes, width, height, duration_ms, checksum_sha256이 담길 수도 있습니다. artifact URL은 파싱하지 마세요. 경로는 불투명한 값입니다. 원본 프로바이더 URL은 공개 API 출력이 아닙니다.

Job이 왜 아직 대기 중인가요?

워크스페이스 동시성은 API가 Job을 접수할 때가 아니라 워커가 Job을 processing으로 옮길 때 적용되므로, 접수된 Job도 기다릴 수 있습니다. 상태 페이로드의 queue 객체가 그 이유를 알려 줍니다. state(waiting, deferred, runtime_unavailable, …), 프로바이더 중립적인 reason, 그리고 Job이 워커에 픽업되거나 재시도될 수 있는 가장 이른 시각인 available_at이 담깁니다. queue.position은 Sume가 실제 순위를 계산하기 전까지 null이며, API는 가짜 큐 위치를 반환하지 않습니다. Sume 영상 Job 동시성과 큐를 참고하세요.

단계별 기록이 필요하면 GET /v1/jobs/{id}/events를 읽으세요. job.created, job.queued, job.started, generation.submitted, job.completed, job.failed, job.canceled, webhook.delivery가 나열됩니다. 이 엔드포인트는 스트림이 아니라 pull 스냅샷이며, 원본 프로바이더 task ID와 URL은 숨깁니다.

폴러가 타임아웃되거나 비정상 종료되면 어떻게 되나요?

Job은 그대로 진행됩니다. 클라이언트 쪽 타임아웃은 Job을 취소하지 않으며, Job은 계속 실행되고 계속 과금됩니다. 제출할 때 Job ID를 저장해 두고, 다시 제출하는 대신 status_url에서 이어 가세요. 안전한 재시도는 AI 영상 API 멱등성 키에서, 잃어버린 ID를 찾는 방법은 영상 Job 목록 조회와 복구에서 다룹니다.

루프를 건너뛰려면 종료 웹훅을 요청하세요. mode를 받는 경로에서는 공개 HTTPS webhook_url과 함께 mode: "webhook"을, POST /v1/videos에서는 callback_url을 보내면 됩니다. Job 웹훅은 종료 이벤트(job.completed, job.failed, job.canceled)만 보냅니다. 누락된 전달에 대비해 status_url 폴링은 계속 쓸 수 있게 두세요. 호스팅 MCP에서는 jobs_wait가 대기를 맡습니다. 긴 영상 Job을 위한 MCP jobs_wait를 참고하세요.