AWS Step Functions 콜백 대기로 AI 영상 실행 기다리기

AWS Step Functions가 콜백을 기다리게 하려면 Task 상태의 Resource 끝에 .waitForTaskToken을 붙이고, 태스크 토큰 $$.Task.Token을 실제 작업을 맡는 쪽에 넘기세요. 상태 머신 실행은 누군가 그 토큰으로 SendTaskSuccess나 SendTaskFailure를 호출하거나 상태가 타임아웃될 때까지 멈춥니다. AI 영상 작업이라면 태스크 하나가 작업을 시작하고, 작업의 웹훅이 토큰을 돌려줍니다.

AWS 관련 내용은 Step Functions 개발자 안내서의 서비스 통합 패턴, Lambda, Task 상태, 할당량, 오류 처리 페이지와 SendTaskSuccess, SendTaskFailure API 레퍼런스에서, Sume 관련 내용은 Format 호출하기 (영문), 실행과 결과 (영문), Run 웹훅 (영문)에서 가져왔습니다. 모두 2026-09-27에 확인했습니다. Sume에는 Step Functions 전용 연동이 없으며, Lambda 함수가 Sume의 HTTPS API를 직접 호출합니다.

콜백 패턴을 Sume 영상 실행에는 어떻게 적용하나요?

대기가 시작되기 전에 실행 ID가 상태 머신 실행의 데이터에 들어 있도록, 상태를 두 개로 나누세요.

• 일반 Lambda 태스크인 StartRun은 communication.webhook_url이 여러분의 수신기를 가리키는 Sume Format 실행을 만들고, 실행 ID를 반환합니다. Idempotency-Key는 상태 머신 실행 이름에서 만들므로, 재시도된 태스크는 원래 실행을 돌려받습니다. 같은 키와 같은 본문이면 원래 영수증과 함께 200이 반환되며, 두 번째 실행도 두 번째 청구도 없습니다.
• .waitForTaskToken을 붙인 Lambda 태스크인 WaitForVideo는 작은 함수에 실행 ID와 토큰을 넘깁니다. 이 함수는 여러분이 관리하는 테이블에 실행 ID를 키로 토큰을 저장하고 반환하며, 상태 머신 실행은 대기합니다.
• 웹훅 수신기는 Sume의 서명된 POST를 검증하고, run_id로 토큰을 찾아 SendTaskSuccess나 SendTaskFailure를 호출합니다.
• SUME_API_KEY는 서버 쪽에 두세요. AWS는 API 키에는 Lambda 환경 변수 대신 Secrets Manager를 쓰라고 권장합니다.

"StartRun": {
  "Type": "Task",
  "Resource": "arn:aws:states:::lambda:invoke",
  "Parameters": {
    "FunctionName": "arn:aws:lambda:region:account-id:function:start-sume-run",
    "Payload": { "order.$": "$.order", "execution.$": "$$.Execution.Name" }
  },
  "ResultPath": "$.run",
  "Next": "WaitForVideo"
},
"WaitForVideo": {
  "Type": "Task",
  "Resource": "arn:aws:states:::lambda:invoke.waitForTaskToken",
  "Parameters": {
    "FunctionName": "arn:aws:lambda:region:account-id:function:park-task-token",
    "Payload": { "run_id.$": "$.run.Payload.run_id", "token.$": "$$.Task.Token" }
  },
  "TimeoutSeconds": 6000,
  "ResultPath": "$.video",
  "Catch": [{ "ErrorEquals": ["States.Timeout"], "ResultPath": "$.timeout", "Next": "ReadRun" }],
  "Next": "Publish"
}

영상 실행에는 어떤 Step Functions 설정이 필요한가요?

기본값은 대부분 짧은 태스크를 전제로 합니다. 바꾸거나 확인해야 할 설정은 다음과 같습니다.

태스크 토큰을 웹훅 URL에 넣으면 왜 안 되나요?

수신기에 테이블이 필요 없으니 더 간단해 보입니다. 하지만 두 가지 때문에 이 방법은 통하지 않습니다. 먼저 토큰이 들어가지 않을 수 있습니다. 토큰은 최대 2,048자인데, Sume는 호스트와 경로를 포함한 webhook_url을 2,048자로 제한합니다. 또 안전한 재시도가 불가능해집니다. URL은 요청 본문의 일부이고, Sume는 같은 키에 다른 본문이 오면 409 idempotency_conflict로 응답합니다. 타임아웃된 콜백 태스크는 새로운 무작위 토큰을 받으므로, 새 토큰을 URL에 담은 재시도가 바로 그런 요청이 됩니다.

웹훅 수신기는 무엇을 돌려보내야 하나요?

수신기는 평범한 웹훅 엔드포인트입니다. 함수 URL과 서명 확인은 AWS Lambda로 Sume 웹훅 받기에서 다룹니다. 서명을 확인한 다음에는 이렇게 하세요.

• 봉투의 run_id로 토큰을 찾으세요. 아직 저장되지 않았다면 503으로 응답하세요. Sume는 실패한 시도를 다시 보내며(시도는 최대 10회), 여러분이 보낸 Retry-After를 따릅니다.
• status: "OK": 토큰과 짧은 output(예: 실행 ID와 payload.primary_output_url)으로 SendTaskSuccess를 호출하세요. 1 MiB를 넘는 영수증은 payload: null로 도착하지만, status는 여전히 결과를 알려 줍니다.
• status: "ERROR": error에는 Sume의 error.code(최대 256자)를, cause에는 그 메시지를 넣어 SendTaskFailure를 호출하세요.
• Step Functions가 TaskTimedOut으로 응답하면 토큰이 만료되었거나 그 태스크가 이미 닫힌 것입니다. 예를 들어 앞선 전달이 이미 성공한 경우입니다. 그래도 2xx로 응답하세요. 그러지 않으면 Sume가 계속 재시도합니다.
• Sume가 시도마다 주는 시간인 10초 안에 응답하고, 재시도마다 같은 값이 오는 request_id로 중복을 제거하세요.

웹훅이 오지 않으면 상태는 얼마나 기다려야 하나요?

타임아웃이 없으면 토큰을 기다리는 태스크는 상태 머신 실행이 일 년 할당량에 도달할 때까지 기다립니다. TimeoutSeconds는 Sume 자체의 기한을 넘기도록 설정하세요. 진행 중인 실행은 created_at으로부터 90분 뒤에 failed로 강제 종료되며, 25분이 넘었고 10분 동안 아무 신호가 없으면 그보다 일찍 종료됩니다. 롱폼 영상은 15분에서 30분이 걸리는 작업입니다.

TimeoutSeconds가 다 지나면 상태는 States.Timeout으로 실패합니다. 이 오류는 States.TaskFailed 와일드카드에 걸리지 않으므로, 위 예시처럼 이름으로 잡아 GET /v1/format-runs/{run_id}를 한 번 읽는 ReadRun 상태로 보내세요. POST를 보내지 않는 실행은 상태 머신 실행이 이 읽기로 알게 됩니다. 취소된 실행은 웹훅을 보내지 않고, 엔드포인트가 10회 시도를 모두 거부하면 아무것도 전달되지 않은 채 실행은 그대로 남습니다. 여러분의 타임아웃은 실행도, 그 지출도 멈추지 않습니다.