출시 전 점검표

데모는 요청 하나면 되지만, 제품은 타임아웃, 중복 웹훅, 만료된 링크, 유출된 키를 견뎌야 합니다. 출시 전에 이 목록을 확인하세요.

키

• 키는 서버의 시크릿 저장소에 있고, 브라우저나 앱 번들에는 절대 없습니다.
• 환경별·서비스별로 키를 따로 써서 하나만 폐기할 수 있습니다.
• 운영 키는 실제로 쓰는 모델만 허용하고 일일 지출 한도가 있습니다.
• 중단 없이 키를 교체하는 방법을 압니다(인증).

작업 만들기

• 모든 createTask에 내 작업 ID에서 만든 Idempotency-Key를 보내며, 한 번 만들어 재시도마다 다시 씁니다.
• 429, 500, 503, 50301만 재시도하고, 백오프와 Retry-After를 지킵니다(오류).
• 400, 40004처럼 "요청을 고쳐야 하는" 오류는 재시도하지 않고 표시하거나 로그로 남깁니다.
• 가격을 보여 준다면 먼저 견적을 받아 quoteId와 expectedCredits를 넘기고, 40901을 처리합니다.
• 잔액 부족(40201)이 사용자보다 먼저 담당자에게 알려집니다. 알림, 이메일, 배너 무엇이든 좋습니다.

결과 받기

• 작업에 callBackUrl을 붙이고, 엔드포인트가 서명을 검증하며 오래된 타임스탬프를 거부합니다.
• 웹훅 핸들러가 2xx를 빨리 돌려주고 실제 작업은 백그라운드에서 합니다.
• 중복 전송은 request_id로 무시합니다.
• 웹훅이 오지 않은 작업을 주기적으로 다시 읽습니다.
• succeeded, failed, expired, canceled가 아닌 상태는 모두 "아직 실행 중"으로 다룹니다.

파일

• 완성된 파일은 약 20분 뒤 만료되는 서명 URL을 링크하지 않고, 내 저장소(또는 에셋 라이브러리)로 복사합니다.
• 저장하는 것은 서명 링크가 아니라 taskId입니다.
• 다운로드 코드가 서명 URL에 API 키를 보내지 않습니다.
• 참조 파일은 파일 자체를 가리키는 공개 HTTPS 링크, 업로드, 에셋 중 하나이며 공유 페이지가 아닙니다.

비용

• 모델마다 과금 단위(장당, 초당, 요청당)와 가격을 올리는 설정을 압니다.
• 미리보기와 테스트는 가장 싼 해상도와 가장 짧은 길이로 합니다.
• 폭주하는 루프가 잔액을 다 쓰기 전에 지출 한도가 막아 줍니다.
• 예상 금액이 그대로 청구됐다고 가정하지 않고 credits와 settled를 확인합니다.

모니터링

• 실패할 때마다 request_id, taskId, code, errorCode를 로그로 남깁니다.
• 모델별 failed 비율을 지켜봅니다. 갑자기 오르면 대개 프롬프트, 입력, 모델 중 무언가가 바뀐 것입니다.
• 모델별로 createTask부터 웹훅까지의 시간을 추적하고 이상값에 알림을 겁니다.
• 팀의 누군가는 API 콘솔의 로그와 사용량 페이지가 어디 있는지 압니다.

콘텐츠

PopNow는 일반 사용자를 위한 서비스입니다. 모델마다 콘텐츠 규칙이 있으며, 거절된 요청은 content_rejected로 실패합니다. 사용자가 프롬프트를 쓴다면 원래 오류를 그대로 보여 주지 말고, 왜 거절됐는지 내 화면에서 알려 주고 고칠 수 있게 하세요.