PiAPI 작업 폴링과 Webhook: 완료 처리를 안정적으로 구현하기

이미지나 동영상 요청이 접수되어도 완료 처리 과정은 필요합니다. PiAPI 통합 API 작업에서는 작업 ID를 저장하고 최종 상태를 확인한 뒤 모델별 출력을 처리하세요. 처음 연동할 때는 폴링이 간편하며, Webhook을 사용하면 백엔드가 작업 완료에 반응할 수 있습니다.

1. 작업 ID를 저장하고 폴링에 제한 두기

작업 생성 후 data.task_id를 자체 작업 ID와 함께 저장하세요. 서버의 API 키로 같은 작업을 조회합니다. HTTP 응답 성공만으로 생성 완료를 판단하지 말고 data.status를 확인하세요.

curl --fail-with-body --silent --show-error \
  "https://api.piapi.ai/api/v1/task/${PIAPI_TASK_ID}" \
  --header "x-api-key: ${PIAPI_API_KEY}"

completed이면 모델에 맞는 data.output을 검증하고, failed이면 data.error를 기록합니다. 대기 중에는 재시도 횟수를 제한하고 간격을 점차 늘리며 무작위 지연을 추가하세요. 앱의 대기 기한은 자체 설정입니다. 기한 초과가 원격 작업의 실패나 취소를 뜻하지는 않으므로 나중에 대조할 ID를 보존하세요.

2. 인증된 콜백 추가하기

아래 설정을 유효한 작업 생성 요청 본문에 합치되 기존 설정 필드는 유지하세요. 공개 HTTPS 엔드포인트와 백엔드 비밀 저장소의 비밀값을 사용합니다. PiAPI 문서에 따르면 비밀값은 x-webhook-secret 헤더로 전달되므로 알림 수락 전에 검증하세요.

{
  "config": {
    "webhook_config": {
      "endpoint": "https://your-app.example/piapi/callback",
      "secret": "YOUR_WEBHOOK_SECRET"
    }
  }
}

Webhook JSON에는 timestamp와 data가 있습니다. 작업이 해당 앱의 것인지 확인한 뒤 이벤트를 영구 기록하거나 큐에 저장하고 신속히 2xx를 반환하세요. 다운로드 등 오래 걸리는 일은 HTTP 처리기 밖에서 수행합니다. 성공 응답을 받지 못하면 재전송한다는 문서 설명에 따라 중복 전달을 예상하세요.

3. 폴링과 콜백을 하나의 처리기로 통합하기

두 경로에서 같은 완료 처리기를 사용하세요. 작업 ID와 완료 동작에 영구적인 고유 제약을 두면 중복 알림이나 후속 작업의 이중 실행을 방지할 수 있습니다. 타임스탬프만으로는 서로 다른 작업을 식별할 수 없습니다. 최종 상태 이후의 오래된 업데이트는 무시하고, 워커가 중단 후에도 안전하게 재시도하도록 설계하세요.

콜백이 없거나 상태가 불명확하면 저장한 작업 ID를 다시 조회하세요. 조회 시간 초과를 이유로 다른 유료 작업을 무조건 만들지 마세요. 전송 오류와 확인된 작업 실패를 구분하고 대조한 뒤 재제출 여부를 결정합니다.

4. 실패 상황 점검하기

배포 전에 콜백 재전송, 잘못된 비밀값, 전달 지연, 워커 재시작을 시험하세요. 완료 작업마다 영구 결과가 하나만 남고 실패 작업에는 오류가 보존되는지 확인합니다. 다음으로 출력 저장 가이드에 따라 생성 파일을 보관하세요.

참고: 통합 API 스키마, 작업 조회 예제, Webhook 문서. 예제는 연동 구조를 설명하며 실제 생성 성능 측정이 아닙니다.