2026-09-26개발자

Sume request_id·job_id·run_id: 저장하고 문의할 ID

Job이나 실행 ID를 저장하고, 웹훅은 job_id나 실행 봉투의 request_id로 중복을 제거하고, Sume 지원팀에는 req_ 요청 ID를 Job이나 실행 ID와 함께 알려 주세요.

읽는 시간 5분Sume

Sume API에서 job_id와 run_id는 시작한 작업을 가리키고, req_… 요청 ID는 HTTP 응답 하나를 가리키며 모든 응답에 x-sume-request-id 헤더로 실려 옵니다. Job이나 실행 ID를 저장하고, 웹훅 중복 제거는 Job이면 job_id로, 실행이면 봉투의 request_id(run_id와 같은 값)로 하세요. 지원팀에 문의할 때는 req_… ID를 Job이나 실행 ID와 함께 알려 주세요.

함정은 request_id라는 필드 이름입니다. 이 필드가 나오는 위치에 따라 값이 달라집니다. 아래 의미는 Sume 문서 오류와 요청 한도 (영문), Job과 결과 (영문), Run 웹훅 (영문)과 Sume API 레퍼런스에서 가져왔으며, 2026-09-26에 확인했습니다.

request_id는 위치마다 무엇을 뜻하나요?

나타나는 위치에 따라 읽으세요. req_ 접두사가 붙은 값은 HTTP 상관관계 ID이며, 절대 Job ID가 아닙니다.

오류와 요청 한도 (영문), Run 웹훅 (영문), Sume API 레퍼런스 기준, 2026-09-26 확인.
위치	값	용도
`error.request_id`, `x-sume-request-id` 헤더	`req_…`. 생성 Job ID가 아닌 HTTP 상관관계 ID	지원 문의와 로그
Job 제출 응답의 `request_id`	해당 Job의 ID	저장하고 `/v1/jobs/{id}` 폴링
Job 웹훅의 `request_id`와 `job_id`	둘 다 Job ID(`job_…`)	`job_id`로 중복 제거
실행 웹훅 봉투의 `request_id`	`run_id`와 같음. 재시도해도 유지됨	이 값으로 중복 제거
실행 영수증의 `request_id`	상관관계 ID. `GET`으로 읽으면 `req_…`, 웹훅 `payload` 안에서는 실행 ID	로그에 남기되 중복 제거에는 쓰지 않음
사용량 행의 `request_id`	행이 Job에 연결된 경우 Job ID 또는 요청 ID	사용량과 Job 조인

어떤 ID를 저장해야 하나요?

작업의 ID입니다. 모든 Job 제출 모드는 첫 응답에서 Job ID를 돌려줍니다. 제출 봉투에서는 request_id로, POST /v1/videos에서는 id로 옵니다. Format 실행의 ID는 생성 영수증의 data.id이며 arun_… 형태의 값입니다. 임베드 쿡북 (영문)은 브라우저에 응답하기 전에 이 ID를 자체 레코드에 연결해 저장하라고 안내합니다.

프로세스 연결이 끊기거나 타임아웃되더라도 그 ID를 유지하고, 유료 작업을 중복 제출하는 대신 Job이나 실행 경로로 복구하세요.

웹훅 중복 제거에는 어떤 ID를 써야 하나요?

재시도해도 중복 제거 ID는 그대로 반복되므로, insert-or-ignore 처리의 키로 이 ID를 쓰세요.

Job 웹훅: job_id. 문서는 이 값을 수신 측의 멱등성 키로 지정하며, 다시 보내기(Redeliver)는 실제 이벤트를 반복해서 보냅니다.
실행 웹훅: run_id와 같은 값인 봉투의 request_id. 중첩된 payload.request_id는 무시하고, request_id는 재시도마다 반복되므로 전달 순서는 created_at으로 정하세요.
테스트 전송: webhook.test 이벤트에는 req_wh_test_… 요청 ID가 있고 job_id나 실행 ID는 없습니다. 실제 이벤트가 아닙니다.

{
  "event": "job.completed",
  "request_id": "job_…",
  "job_id": "job_…",
  "status": "OK",
  "payload": {
    "artifacts": [
      { "id": "artf_…", "url": "https://media.sume.com/artifacts/…", "type": "image" }
    ]
  }
}

Sume 지원팀에는 어떤 ID를 보내야 하나요?

Sume API 오류와 요청 한도에 정리된 대로, 요청 ID를 Job이나 실행 ID, error.code와 함께 알려 주고 키와 시크릿은 빼세요. 각 ID를 찾는 위치는 다음과 같습니다.

실패한 HTTP 호출: x-sume-request-id 헤더나 error.request_id. req_… 값입니다.
TypeScript SDK: SumeApiError와 SumeRunRequestError의 requestId. waitForJob이 throw하는 SumeJobRequestError에는 그 대신 jobId가 있습니다.
Format 실행: arun_… ID와 함께, 영수증 자체의 request_id. 문서는 지원팀이 요청하는 값이 이것이라고 설명합니다.
검증되지 않는 웹훅: x-sume-webhook-secret-fingerprint 값. 티켓에 붙여넣어도 안전한 유일한 부분입니다. 다른 점검 사항은 Sume 웹훅 전달 디버깅에서 다룹니다.

사용량 행을 Job이나 실행과 어떻게 연결하나요?

GET /v1/usage를 job_id나 run_id로 필터링하면 생성 Job 하나, 또는 Format, Action, Agent 실행 하나의 비용을 합산할 수 있습니다. 각 원장 행의 request_id는 행이 Job에 연결된 경우 Sume Job ID나 요청 ID이며, 행에는 run_id와, 그 Job을 만든 에이전트 턴인 turn_job_id도 담깁니다. 실행과 Job의 관계는 Sume Job과 실행의 차이에서 설명합니다.

출처

작성자 Sume