프로덕션 연동 가이드

모델과 프로토콜 선택

인증된 실시간 카탈로그에서 inputSchema와 예제를 읽고 enabled와 available이 모두 true인 모델을 선택하세요. 공개 모델 페이지가 계정의 현재 호출 가능 여부를 보장하지는 않습니다. 기본 작업은 /api/v1, 호환 클라이언트는 /v1을 사용합니다. Console 쿠키를 API 인증에 쓰지 마세요.

API 키는 백엔드 환경에만 보관하고 브라우저나 배포 앱에 넣지 마세요. 최신 Schema의 타입, 열거형, 조건부 필수 필드를 따릅니다. 공개 HTTPS 미디어 URL은 모델이 지원하는 입력 필드에 직접 지정할 수 있습니다. 로컬 파일은 업로드 주소 발급 → PUT → commit 순서로 처리하고 반환된 spicy:// URI를 해당 입력 필드에 넣습니다. 모델을 바꾸면 입력을 다시 검증하세요.

견적 확인 후 제출

model, input, callBackUrl 전체로 jobs/quote를 호출합니다. estimatedCost, maxCharge, currency, expiresAt을 사용자에게 보여 주세요. 견적은 5분 동안 유효하며 잔액을 동결하지 않습니다. 확인 후 동일 요청에 quoteId와 expectedCost를 추가합니다. 입력 변경이나 40901이 발생하면 다시 견적을 받고, 인상된 비용을 자동 승인하지 마세요. 금액은 십진 문자열로 보관합니다.

작업 기록 저장

전송 전에 업무 ID, 안전한 요청 지문, Idempotency-Key를 저장하고 접수 후 taskId와 request_id를 기록합니다. 같은 계정·API 키·논리 요청은 24시간 안에 기존 키를 재사용합니다. 타임아웃이 접수 실패를 의미하지는 않습니다. 실패로 종료된 작업을 재시도하면 현재 조건으로 새 작업이 생성됩니다.

콜백과 결과 처리

원본 바이트로 서명과 타임스탬프를 확인한 뒤 중복을 제거하고 저장합니다. 빠르게 응답하고 긴 작업은 별도 큐에서 처리하세요. 지연·중복 이벤트는 작업 상태를 기준으로 처리합니다. 폴링은 recordInfo에 상한이 있는 지수 백오프를 적용합니다. 202는 접수, succeeded는 생성 성공, settled=true는 정산 완료입니다.

동시 실행과 보관 기간

계정별 진행 중 작업 수와 요청 시간을 제한합니다. 429에서는 Retry-After를 따르고 모든 작업을 매초 동시에 조회하지 마세요. 카탈로그는 계정별로 짧은 시간 동안 캐시합니다. 다운로드 URL은 20분, 생성 파일은 14일, 업로드는 1일 유지되므로 필요한 결과는 따로 보관하세요. 연결 종료는 작업 취소가 아닙니다.

출시 전 검증

카탈로그, 잔액, 견적부터 확인한 뒤 비용 승인 절차를 거쳐 최소 생성을 테스트합니다. 성공, 입력 오류, 잔액 부족, 같은 키로 복구, 중복 콜백, 만료 URL, 예산 제한을 확인하세요. 로그에는 request_id, taskId, 시간, 상태, 금액만 남기고 키와 전체 프롬프트를 기록하지 마세요.