본문으로 건너뛰기

요청별 비용

호출과 작업별 비용을 고객 시스템에 기록하는 방법

동기 호출, 영상 작업과 Batch의 비용 필드와 확인 시점, 호출 비용과 USD 및 KRW 금액의 차이를 구분하고 각 식별자에 비용을 연결해 중복 없이 기록하는 방법을 설명합니다.

페이지 목차

호출 방식별 비용 기록

호출별 비용을 추적하려면 고객 시스템에서 요청이나 작업 식별자에 비용을 연결해 저장하세요. 게이트웨이 비용은 선택한 모델과 실제 사용량에 따라 달라집니다. 현재 모델의 unit 단가는 에셋에서 확인합니다.

호출 방식비용을 확인할 때기록할 값과 식별자
estimated_cost를 반환하는 동기 호출HTTP 200 JSON 응답에서(Responses의 incomplete 응답 포함)최상위 estimated_cost.amount와 currency, 고객 요청 식별자와 시각
비동기 영상접수 후 같은 작업 ID의 조회에서data.job.usage.amount와 currency, 작업 ID와 시각
작업 ID를 반환하는 이미지 모델(예시 모델: Seedream 5.5)동기 호출과 비동기 호출 모두 작업 조회에서data.job.usage와 작업 ID
Batch처리 상태와 별도로 정산을 확인한 뒤settlement_status: "settled"와 settled_units, Batch ID

위 표의 값은 호출이나 작업 한 건을 추적하는 데 씁니다. 관리 API의 USD 비용이나 결제 화면의 KRW 금액과는 단위가 다릅니다. 서로 대조하기 전에 맞춰 볼 기간, 대상과 단위를 요금 및 사용량 안내에서 확인하세요.

동기 응답에서 비용 확인하기

Chat Completions, Responses, Messages, Embeddings, Image Generations와 Image Edits의 HTTP 200 JSON 응답에는 usage.estimated_cost가 아니라 최상위 estimated_cost 객체가 포함됩니다. 비용을 계산할 수 없는 응답에서는 값이 null일 수 있습니다. 응답에 따라 estimated_cost의 값과 비용을 확인하는 곳이 다릅니다.

응답estimated_cost비용을 확인하는 곳
위 엔드포인트의 HTTP 200 JSON 응답최상위 객체로 포함같은 응답의 estimated_cost
영상 생성의 접수 응답null작업 조회의 data.job.usage
작업 ID를 반환하는 이미지 모델로 보낸 Image Generations 응답null작업 조회의 data.job.usage

estimated_cost 객체에는 다음 필드가 포함됩니다.

필드타입설명
estimated_cost.amountstring해당 호출의 비용을 소수 문자열로 반환
estimated_cost.currencystring현재 unit을 반환
estimated_cost.disclaimerstring공개 단가를 바탕으로 한 값이며 실제 청구액과 다를 수 있음을 알리는 문구를 반환

estimated_cost.amount는 해당 호출의 비용을 추적할 때 사용하는 값입니다. 응답의 disclaimer가 안내하듯 실제 청구액과 다를 수 있으며, VAT 또는 계약상 정산 조정이 반영된 최종 납부 금액은 아닙니다.

응답에 따라 비용을 다음과 같이 기록합니다.

응답기록하는 방법
HTTP 200이고 estimated_cost가 있음amount와 currency를 고객 시스템의 요청 식별자, 요청 시각, API 키 이름과 연결합니다. 응답에 호출 ID가 있으면 함께 보관합니다.
Responses의 status: "incomplete"출력이 완전하지 않아도 비용 기록에서 빼지 않고, estimated_cost가 있으면 그 값을 해당 호출의 비용으로 기록합니다. 출력 조건을 바꿔 다시 보낸 요청은 별도 호출이므로 추가 비용이 발생할 수 있습니다. 다시 요청하기 전에 응답 상태에 따른 다음 행동을 확인하세요.
estimated_cost가 null이거나 없음, 또는 usage 이벤트를 받지 못함비용을 0으로 저장하지 않습니다. 사용량 분석의 누적값에서 사용량 반영 여부를 따로 확인할 수 있지만, 누적값이 특정 호출의 비용을 대신하지는 않습니다.
스트리밍 응답스트리밍 비용의 제공 여부와 이벤트 위치는 Chat Completions, Responses 및 Messages 명세를 따릅니다. 누적 usage와 비용 값이 제공되면 고객 요청과 연결해 기록합니다. Responses에서는 종료 이벤트의 response.usage를 확인하되, estimated_cost가 항상 제공된다고 가정하지 않습니다.

비동기 영상 작업 비용 확인하기

영상 작업의 비용은 파일 다운로드와 별도로 확인합니다.

  1. 생성 접수 응답의 작업 ID를 저장합니다.
  2. 같은 ID로 Jobs에서 작업을 조회합니다.
  3. 응답에 data.job.usage.amount와 currency 필드가 있으면 두 값을 작업 ID, 요청 시각과 모델 코드에 연결해 기록합니다.

items 필드에는 수량과 단위가 들어 있고, unit_price 필드는 빠질 수 있습니다. 필드 구조는 Jobs의 사용량과 작업 비용에서 확인합니다.

해상도, 길이와 입력 조건에 따라 사용량과 단가가 달라집니다. 보관한 결과를 다음 생성 요청의 입력으로 사용해도 그 요청은 새 작업으로 접수됩니다. 새 작업의 ID와 비용은 앞 작업과 구분해 기록합니다.

usage 필드가 없어도 작업이 무료였다고 판단하지 말고, 먼저 data.job.status를 확인합니다.

상태다음 행동
queued, running작업이 아직 실행 중이므로 간격을 두고 같은 작업을 조회합니다. 비용을 0으로 기록하지 않습니다.
succeeded비용을 확인하지 못한 상태로 기록하고 같은 작업을 다시 조회합니다. 계속 확인되지 않으면 작업 ID로 문의합니다.
failed비용을 기다리며 반복 조회하지 말고 실패 원인을 확인합니다.

작업 비용을 해석할 때는 다음 상황을 구분합니다.

상황판단과 다음 행동
실패한 작업에서 비용 값이 반환됐거나 차감이 의심됨작업 ID와 반환된 비용 값을 남겨 문의합니다.
영상 파일을 받지 못함파일을 받지 못한 상황은 생성 작업이 failed로 끝난 상태와 다릅니다. 영상 파일을 받지 못했다는 이유만으로 자동 환불되지는 않습니다.
data.job.usage 값을 받음이 값만으로 스페이스에서 최종 차감이 완료됐다고 확정하지 않습니다. 스페이스에 반영된 사용량은 사용량 분석의 누적값과 유닛의 잔액 및 초과 사용량에서 확인합니다. 누적값과 잔액에는 여러 호출이 함께 반영되므로 영상 한 건의 비용과 같아야 한다고 판단하지 않습니다.
작업별 차감을 대조해야 함플랫폼 내 문의 기능에 작업 ID, 요청 시각과 반환된 usage 값을 남깁니다. API 키 값은 보내지 않습니다.

Batch의 확정 비용 확인하기

제출할 때 받은 Batch ID로 Batches에서 Batch를 조회합니다. status: "completed"는 모든 행의 성공이나 비용 확정을 뜻하지 않습니다. 결과 파일을 받았더라도 확정 비용은 settlement_status와 settled_units로 별도로 확인합니다. 정산 결과에 따라 비용을 기록하세요.

정산 결과기록하거나 확인할 내용
settlement_status가 settled이고 settled_units가 null이 아님settled_units의 유닛 금액 문자열을 확정 비용으로 기록합니다. 문자열 "0"도 확정된 금액입니다.
정산 중(pending, queued, processing, settling)이며 settled_units가 null무료로 기록하지 않고 같은 Batch ID로 다시 조회합니다. 정산 중의 null은 정산 완료 뒤 반환되는 문자열 "0"과 다릅니다.
settlement_status가 settled인데 settled_units가 null금액을 확인할 수 없는 상태입니다. null을 0으로 바꾸지 말고 Batch ID로 문의합니다.
settlement_status가 quarantined정산 보류 상태이며 무료나 정산 완료를 뜻하지 않습니다. 자동 조회를 멈추고 Batch ID로 문의합니다.
settlement_status가 settling 또는 settled인데 billing_usage가 null과금 근거를 확인할 수 없는 상태입니다. Batch ID로 문의합니다.

Batch의 과금 근거는 Batch 객체의 billing_usage 필드입니다. Batch 객체에는 표준 usage 필드가 없습니다. billing_usage 필드와 결과 행마다 있는 response.body.usage 필드는 서로 다른 값으로 다룹니다.

다음 경우에는 비용이 남거나 0으로 확정될 수 있습니다.

  • 일부 요청이 실패하거나 Batch를 취소해도 이미 처리된 요청의 결과와 비용은 남을 수 있습니다. 취소를 요청했다면 상태가 cancelling인 동안 기다린 뒤 상태와 정산을 다시 확인합니다.
  • 파라미터 오류로 모든 행이 거부돼 토큰 사용량이 0이었다면 정산 완료 뒤 확정 비용도 0인지 확인합니다.

Batch별 확정 비용은 스페이스의 누적값과 다릅니다. 누적 사용량은 사용량 분석에서, 남은 잔액은 유닛에서 각각 확인합니다. 아직 정산되지 않은 작업의 비용은 API 키와 구성원의 사용 한도에 미리 반영되지 않으므로, 한도만으로 전체 지출 상한을 보장할 수 없습니다. 자세한 내용은 월 사용 한도에서 확인합니다.

Batch 결과 파일과 정산을 확인하는 순서를 따라 확인한 비용은 작업별 기록에 연결합니다.

작업별 비용 기록과 중복 합산 방지

고객 작업 하나가 여러 요청 또는 작업으로 이뤄지면 각 식별자와 비용을 고객 시스템의 작업 식별자에 연결해 합산합니다. 같은 영상 작업 ID 또는 Batch ID로 여러 번 조회했더라도 응답에 포함된 비용을 새로 발생한 비용으로 더하지 않습니다.

아래 예시는 조회할 때마다 비용을 더하지 않고 같은 기록을 갱신하는 방법을 보여줍니다. ID와 금액은 기록 방법을 설명하기 위한 가상 값입니다. video-J1과 batch-B1은 서로 다른 작업입니다. 표의 각 행은 새 작업을 만들지 않고 기존 작업을 다시 조회해 받은 결과입니다.

조회한 작업응답에서 확인한 상태와 비용고객 시스템의 기록
video-J1 첫 조회running, usage 없음비용 미확인으로 저장합니다. 0으로 채우지 않습니다.
같은 video-J1 후속 조회succeeded, usage.amount: "0.4200", currency: "unit"기존 video-J1 기록에 받은 금액과 조회 시각을 반영합니다. 같은 금액이 다시 반환되어도 중복 합산하지 않습니다.
batch-B1 정산 전 조회settlement_status가 settled가 아님, settled_units: null정산 미완료로 저장합니다. 작업 처리 상태와 구분합니다.
같은 batch-B1 정산 후 조회settlement_status: "settled", settled_units: "0"기존 기록을 확정된 0 unit으로 갱신합니다. 앞선 null과 구분합니다.

비용 미확인이나 정산 미완료 같은 기록 상태는 고객 시스템에서 관리하는 구분이며 새로운 API 응답 필드가 아닙니다. 요청 또는 작업 식별자, 요청 시각, 조회 시각, 모델 코드와 반환된 비용 필드의 값을 함께 보관하세요. API 키 값은 기록에 포함하지 않습니다.

기록이 없거나 값이 다를 때

증상다음 행동
호출 응답의 비용과 사용량 분석의 누적값이 다름두 값은 범위와 반영 시점이 다릅니다. 요청 시각, API 키와 조회 기간을 대조하세요.
과거 호출의 비용이 에셋에 표시된 단가로 계산한 값과 다름에셋에 표시된 단가는 현재 값입니다. 과거 호출의 비용을 현재 단가로 다시 계산해 같아야 한다고 판단하지 마세요.
Messages 호출의 비용이 요청한 모델의 단가로 계산한 값보다 큼응답의 usage에 단계별 사용량(iterations)이 있으면 단계마다 그 단계에 쓰인 모델의 단가로 계산해 합산합니다. 응답 usage의 speed나 inference_geo 값에 따라 적용 단가가 달라질 수도 있습니다.
비용이 계속 없거나 예상과 크게 다름렛서 플랫폼에 로그인한 뒤 플랫폼 내 문의 기능에 요청 시각, 작업 또는 Batch ID, API 키 이름을 남깁니다. API 키 값은 보내지 않습니다.