개발자

Sume 생성 Job과 Format·Action·Agent 실행의 차이

Sume Job은 /v1/jobs에서 추적하는 생성 요청 하나이고, 실행은 Format, 스케줄, Agent Completion이 시작한 에이전트 턴 하나입니다. ID, 웹훅, 대기 방법이 다릅니다.

읽는 시간 5분Sume
전체 글

Sume API에서 Job은 POST /v1/videos나 Avatar 경로 같은 모델 엔드포인트에서 온 생성 요청 하나이며, /v1/jobs/{id}에서 추적됩니다. 실행은 Format, 스케줄(Actions API), Agent Completion이 시작한 에이전트 턴 하나이며, /v1/format-runs, /v1/action-runs, /v1/agent-runs 아래에서 추적됩니다. 둘은 ID, 상태, 웹훅, 대기 헬퍼가 모두 다르며, Job ID와 실행 ID는 서로 바꿔 쓸 수 없습니다.

아래 비교는 Sume 문서 Job과 결과 (영문), API 레퍼런스, Run 웹훅 (영문), 실행 기다리기 (영문)를 바탕으로 하며, 2026-09-26에 확인했습니다.

Job과 실행은 무엇이 다른가요?

가장 자주 하는 호출을 기준으로 나란히 비교했습니다. Format 실행 수명주기 자체는 Sume Format 실행 수명주기에서 다룹니다.

Job과 결과 (영문), API 레퍼런스, Run 웹훅 (영문) 기준, 2026-09-26 확인.
항목생성 JobFormat, Action, Agent 실행
생성하는 호출모델 엔드포인트: POST /v1/videos, Avatar 경로, /v1/models/sume/…/runs 별칭POST /v1/formats/{handle}/{slug}/runs, POST /v1/actions/{action_id}/runs, POST /v1/agent/completions
IDjob_…Format 실행과 API로 트리거한 Action 실행은 arun_…(스케줄 문서에는 스케줄로 실행된 경우 run_…로 나옴), Agent Completions는 agrun_…
조회 경로GET /v1/jobs/{id}, 그리고 /status, /result, /eventsGET /v1/format-runs/{run_id}, /v1/action-runs/{run_id}, /v1/agent-runs/{run_id}, 그리고 /status, /result
종료 상태completed, failed, canceled같음. Format과 Action 실행에는 skipped도 있음
결과 전달 방식mode: async, sync, subscribe, webhook 중 하나communication.mode: async 또는 webhook
웹훅 이벤트job.completed, job.failed, job.canceledformat.run.terminal, action.run.terminal, agent.run.terminal. 완료나 실패 때만 발생
취소생성이 시작되기 전에만 가능. 이후에는 409 job_generation_already_started멱등한 POST …/cancel. queued나 processing 상태인 실행을 멈춤
TypeScript 대기waitForJobfamily를 지정한 waitForRun, 또는 subscribeFormatRun

내가 만든 것이 어느 쪽인지 어떻게 구분하나요?

호출한 경로와 응답을 보세요. Job 제출 봉투에는 Job ID인 request_id가 담기고, POST /v1/videos는 Job ID인 id로 응답합니다. 실행 생성은 object가 format.run, action.run, agent.run 중 하나인 영수증을 반환하며, 여기에는 해당 계열 경로의 status_url이 담겨 있습니다. 각각 해당 경로에서 읽으세요.

# A job, from POST /v1/videos or an Avatar route
curl https://api.sume.com/v1/jobs/$JOB_ID/status \
  -H "Authorization: Bearer $SUME_API_KEY"

# A Format run: its own family route, not /v1/jobs
curl https://api.sume.com/v1/format-runs/$RUN_ID \
  -H "Authorization: Bearer $SUME_API_KEY"

실행과 Job은 어떤 관계인가요?

실행은 에이전트 턴 하나이므로, 그 턴이 클립이나 이미지를 몇 개 만들었든 종료 웹훅은 한 번만 발생합니다. 턴 내부의 진행 상황은 생성 Job 계층에 있으며, 이 계층의 웹훅은 Job이 하나씩 끝날 때마다 Job별로 발생합니다.

비용을 보려면 GET /v1/usage에 run_id를 넘겨 Format, Action, Agent 실행 하나의 비용을 에이전트 자체의 턴까지 포함해 합산하거나, job_id를 넘겨 생성 Job 하나의 비용을 합산하세요.

어떤 웹훅을 받게 되나요?

Job과 실행은 서로 다른 이벤트와 페이로드를 보내지만 서명 스킴은 같으므로, 검증기 하나로 둘 다 처리할 수 있습니다. event로 분기하세요. Job 전달은 job_id로, 실행 전달은 run_id와 같은 값인 봉투의 request_id로 중복을 제거하세요. 검증은 Sume 영상 실행용 서명된 웹훅에서 다룹니다.

자주 헷갈리는 차이가 하나 있습니다. canceled에 도달한 Job은 job.canceled를 보내지만, 취소되거나 건너뛴 실행은 웹훅을 전혀 보내지 않습니다. 취소는 취소 응답을, 건너뜀은 생성 응답을 신뢰하세요.

이 구분 때문에 어떤 실수가 생기나요?

여기서 생기는 버그는 대부분 둘을 하나의 리소스로 취급해서 생깁니다.

  • 실행 ID로 /v1/jobs 폴링하기: Action에는 자체 실행 리소스가 있어 /v1/jobs 아래에 나타나지 않으며, Action이나 Format 실행 ID는 /v1/agent-runs에서 해석되지 않습니다.
  • GET /v1/format-runs 찾기: 여러 Format에 걸친 실행 목록은 없습니다. Format별로 실행 목록을 조회하거나, 저장해 둔 실행 ID로 자체 인덱스를 관리하세요. Job에는 GET /v1/jobs라는 목록이 있습니다.
  • 실행에 mode: "subscribe" 보내기: communication.mode에는 subscribe 값이 없으며, 전달을 켜는 것은 webhook_url을 넣는 일입니다.
  • 생성 도중에 Job을 취소하려 하기: Job 취소는 생성 작업이 시작되기 전에만 성공하지만, 실행은 processing 동안에도 취소할 수 있습니다.
  • Job ID로 waitForRun 호출하기: Job에는 waitForJob을 쓰세요. 두 헬퍼는 Sume SDK에서 Job과 실행 기다리기에서 다룹니다.

출처

관련 글

작성자 Sume