비동기 작업 | everyais

Responses background · 비디오 생성 폴링 · 웹훅 대안을 한 흐름으로.

오래 걸리는 작업은 요청을 제출하고 결과를 나중에 받는 비동기 작업 모델을 씁니다. 게이트웨이에는 두 종류가 있고, 폴링 경로가 서로 다릅니다.

1. Responses background 잡

POST /v1/responses 에 background: true 를 주면 즉시 status: "queued" 로 응답합니다.

{
  "model": "everyais/claude-opus-5",
  "input": "긴 리서치 작업...",
  "background": true
}

폴링: GET /v1/responses/{id}
상태 전이: queued → in_progress → completed / incomplete / failed / cancelled
취소: POST /v1/responses/{id}/cancel (queued·in_progress 만 취소되고 예약 크레딧이 환불됩니다)

2. 비디오 생성 잡

POST /v1/videos/generations 는 항상 비동기입니다. 응답의 id 로 폴링합니다.

폴링: GET /v1/videos/generations/{id}
진행 중이면 Retry-After: 5 — 5초 간격 폴링을 권장합니다.
상태: processing / completed / failed / cancelled

⚠️ 비디오 잡을 GET /v1/outputs/{requestId} 로 조회하면 404 입니다. 두 id 는 서로 다른 공간이며, /v1/outputs 는 완료된 요청 이력 조회용입니다.

3. 폴링 대신 웹훅

폴링 없이 완료 통보를 받으려면 대시보드에서 웹훅 엔드포인트를 등록하고 video.completed · video.failed 이벤트를 구독하세요.

video.completed 페이로드에는 jobId · model · status · durationSeconds · cost · data 가 담깁니다.

그 밖에 구독 가능한 이벤트는 credit.low · credit.depleted · credit.recharged · credit.recharge_failed · cost.threshold · cost.limit_hit · payment.succeeded · payment.failed · anomaly.detected · key.expiring 입니다.