Mobidoo

실행과 Job 기다리기

생성 job은 SDK가 기다려 줍니다. Format·Action·Agent 실행은 이 페이지의 HTTP 루프로 기다립니다. 프로덕션에서는 웹훅을 권장합니다.

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

Sume의 비동기 작업은 두 종류이고, URL도 두 갈래입니다.

종류만드는 곳읽는 곳기다리는 방법
JobImage Router, Video Router 등 생성 경로/v1/jobs/{id}@sume-com/client 또는 sume-client의 subscribe
실행(run)Format, Action, Agent Completion/v1/format-runs/{id}, /v1/action-runs/{id}, /v1/agent-runs/{id}아래 HTTP 루프 또는 run 웹훅

job id는 run id가 아니고, run id도 job id가 아닙니다. 지금은 SSE 이벤트 스트림이 없습니다. 기다린다는 것은 상태가 종료될 때까지 다시 읽는다는 뜻입니다.

subscribe

subscribe는 job을 제출하고 기다립니다.

  • 둘 다 2초마다 /v1/jobs/{id}/status를 폴링하고, job이 완료되면 /v1/jobs/{id}/result를 읽습니다.
  • TypeScript 클라이언트는 maxPollTime(지정하지 않으면 5분)이 지나면 멈추고 TimeoutError를 던집니다. 그 requestId가 job id이며, job은 계속 실행되고 과금도 됩니다. 예상하는 가장 긴 job에 맞춰 maxPollTime을 정하세요. 비디오는 보통 몇 분 걸립니다.
  • Python 클라이언트는 job이 끝날 때까지 기다립니다.

이미 job id가 있을 때

result()는 subscribe처럼 job이 끝날 때까지 기다립니다. TypeScript에서는 HTTP로 읽으세요. terminal이 true가 될 때까지 GET /v1/jobs/{id}/status, 그다음 GET /v1/jobs/{id}/result입니다. 필드와 루프는 Job과 결과에 있습니다.

실패하거나 취소된 job의 /result는 409 job_not_completed를 답합니다. 그럴 때는 /v1/jobs/{id}에서 status와 error를 읽으세요.

Format·Action·Agent 실행

SDK에는 실행 호출이 없습니다. POST 한 번으로 실행을 만들고, 상태가 종료될 때까지 영수증을 다시 읽으세요.

Action과 Agent Completion 실행도 /v1/action-runs/{id}, /v1/agent-runs/{id}에서 같은 루프를 씁니다. 영수증의 각 필드는 실행과 결과에 있습니다.

루프를 올바르게 유지하는 규칙입니다.

  • 생성 요청에 Idempotency-Key를 보내세요. 같은 키로 다시 보낸 생성은 같은 실행을 돌려줍니다. 키가 없으면 재시도가 두 번째 실행을 시작하고 과금합니다.
  • 간격을 늘리세요. 긴 비디오는 15~30분 걸립니다. 간격을 1분까지 두 배씩 늘리세요.
  • 읽기에서 받은 429나 5xx는 실행이 아니라 읽기가 실패한 것입니다. 실행은 계속 진행되고 과금됩니다. 기다렸다가 다시 읽으세요.
  • expires_at을 상한으로 쓰세요. 종료되지 않은 영수증에는 Sume가 실행을 failed로 마감하는 시각이 있습니다.
  • 루프를 멈춰도 실행은 취소되지 않습니다. run id를 저장해 두고 나중에 읽거나, POST /v1/format-runs/{id}/cancel로 취소하세요.

기다리는 동안 단계 보기

status는 Format 실행이 processing이라는 것만 알려 줍니다. 단계 타임라인은 무엇을 하고 있는지 알려 줍니다. preparing, running, finalizing이 각각 시각과 상태와 함께 옵니다. 영수증의 events_url을 읽으세요.

로그 스트림이 아니라 단계 타임라인입니다. Sume는 에이전트 출력, 도구 호출, 샌드박스 내부를 공개하지 않습니다. Run receipt의 events_url을 참고하세요. Action과 Agent 실행은 events_url: null을 보고합니다.

종료가 곧 성공은 아닙니다

실행은 completed, failed, canceled, skipped에서 종료됩니다. 실패한 실행은 예외가 아니라 요청한 결과입니다. 웹훅 핸들러처럼 영수증의 status와 error를 읽으세요.

skipped는 다른 실행이 진행 중이었고 on_active_run: "skip"을 보냈다는 뜻입니다. Format 실행은 기본적으로 동시 실행을 허용합니다.

가능하면 웹훅을

폴링 루프는 진행 중인 실행마다 타이머 하나와 열린 요청 하나를 붙잡고, 실행은 보통 몇 분 걸립니다. run 웹훅은 같은 영수증을 그 비용 없이 전달하고, 웹훅 검증이 받는 쪽의 절반입니다. 루프는 대비책으로 남겨 두세요.

다음