과금

프로모션 지원금과 후불 한도

GET /api/v1/chat/credit의 선택 항목 funding은 선불 자금, 프로모션 지원금, 승인된 후불 한도를 구분합니다. 이전 응답에 funding이 없다고 0으로 해석하지 마세요. SDK는 client.getBalance(), CLI는 spicyapi balance --json을 사용합니다. 금액은 정확한 USD 십진 문자열이고 날짜는 RFC3339입니다.

prepaidAvailableUsd는 선불 가용 자금, grantAvailableUsd는 현재 유효한 지원금 합계입니다. grants에는 각 지급 건의 availableUsd, heldUsd, spentUsd, status, startsAt, expiresAt, modelSlugs가 있습니다. 모델 목록이 비어 있으면 모든 모델에 적용됩니다. 유효 기간과 모델 범위를 벗어나면 사용할 수 없으며 출금할 수도 없습니다. 잔액이나 예약 금액이 남은 지급 건을 우선하며, 각 그룹은 최신순으로 최대 100건까지 표시합니다. grantsHasMore가 true이면 반환되지 않은 기록이 더 있습니다. 표시된 목록의 소계를 전체 합계로 사용하지 마세요.

credit.limitUsd는 승인 한도이며 현금 잔액이 아닙니다. credit.availableUsd는 남은 한도, usedUsd는 정산된 미상환 금액, heldUsd는 작업이 예약한 한도입니다. 만료·중지·초과는 새 호출을 제한하지만 부채를 없애지 않습니다. available이 음수여도 승인된 한도를 사용할 수 있으므로 부호만으로 요청을 차단하지 마세요. cashShortfallUsd가 양수이면 외부 결제 회수에 따른 부족액을 보충해야 하며 지원금이나 후불 한도로 대체할 수 없습니다. 최종 허용 여부는 서버가 판단합니다.

할인은 요청 가격을, 지원금과 후불 한도는 결제 재원을 결정합니다. 실패하거나 덜 사용한 예약액은 원래 재원으로 해제되지만 만료·취소된 지원금이 다시 유효해지지는 않습니다. 변경은 관리자의 수동 승인 후 적용됩니다. 지원금이나 후불 한도는 지원팀에 문의하세요. 직접 잔액을 늘리는 공개 API는 없습니다. 원장의 grant_expire는 지원금 만료, grant_revoke는 회수입니다.

현재 API 키의 사용량

GET /api/v1/usage는 인증에 사용한 현재 API 키의 작업만 집계합니다. from과 to는 YYYY-MM-DD 형식의 UTC 날짜이며 범위는 [from,to), 즉 시작일 포함·종료일 제외입니다. 최대 92일까지 조회할 수 있습니다. 기본 to는 UTC 기준 내일이고 from은 to의 7일 전입니다. totalSpend와 각 spend는 정산된 실제 청구액만 합한 USD 십진 문자열이며 미정산 hold는 제외합니다. 작업 생성일을 기준으로 집계하므로 늦게 정산되면 이전 날짜의 금액이 바뀔 수 있습니다. 잔액이나 키의 남은 예산을 보여 주는 API는 아닙니다.

고객 할인과 프로모션

전체 사용자 또는 특정 계정에 전체 모델·선택 모델 할인을 적용할 수 있습니다. 상시 할인은 중지할 때까지, 기간 한정 할인은 실제 시작 시각부터 종료 시각까지 유효합니다. 계정 전용 가격은 해당 계정으로 로그인하거나 해당 API 키로 견적을 받을 때만 적용됩니다.

할인은 중복 적용되지 않으며 이용 가능한 최저가가 자동 선택됩니다. 기본 요금 $10에 공개 할인 10%와 계정 할인 20%가 있으면 $8입니다. 행사가 끝난 뒤 새 견적은 남은 유효 할인 또는 기본 가격을 사용합니다.

카운트다운은 가격을 보장하지 않습니다. 인증 정보와 전체 입력으로 jobs/quote를 호출하고 할인·가격·입력이 바뀌면 다시 견적을 받으세요. 접수된 작업은 당시 확정된 가격으로 정산하므로 실행 중 행사가 끝나도 가격이 오르지 않으며 최종 청구는 예약 금액을 넘지 않습니다.

할인은 API 사용 요금에 자동 적용되며 충전 금액 할인이나 충전 캐시백이 아닙니다. 일별·월별 예산 예시는 현재 가격을 기준으로 계산하므로 예산 기간 도중에 할인이 끝날 수 있습니다. 종료 시각도 확인하세요.

과금 단위

모델의 pricing[].unit은 per_image, per_second, per_request, per_1k_tokens 중 하나입니다. quantityField와 pricing[].variant를 카탈로그에서 읽고 입력 필드를 추측하지 마세요.

hold, settle, release

createTask에서 estimatedCost를 hold하고 succeeded는 실제 사용량으로 settle합니다. failed·expired와 과거 canceled 기록은 전액 release되지만, 새로 수락된 task는 취소할 수 없습니다. task와 hold는 한 데이터베이스 트랜잭션에서 생성되며 정산은 task마다 정확히 한 번 완료됩니다.

잔액과 한도

GET /api/v1/chat/credit는 available, held, total을 반환합니다. 잔액 부족은 40201, 키의 일일·월간·누적 한도와 플랫폼 일일 한도는 40202입니다. 일일 한도는 UTC 자정에, 월간 한도는 UTC 기준 매월 1일 자정에 새로 시작하며 누적 한도는 초기화되지 않습니다. 명시적인 0은 무제한입니다.

원장

원장은 append-only이며 topup, bonus, hold, settle, refund, adjust, chargeback을 별도 항목으로 기록합니다. 이러한 잔액 변동은 task input/output 정리 대상이 아니며 결제 내역에서 확인할 수 있습니다.