청구 조회 및 내보내기

청구 통계는 모델 사용량, 호출 수, 금액을 시간 단위로 집계합니다. Excel은 저장과 오프라인 대조용입니다.

액세스 토큰 준비

프로필의 ‘보안’에서 액세스 토큰을 만들고 청구 통계 조회 또는 청구서 내보내기의 Try It에 입력하세요.

기간과 필터 선택

집계 단위를 선택합니다. 예를 들어 ‘일’은 일별 합계입니다.
시작·종료를 초 단위 Unix 타임스탬프로 입력하거나 오른쪽 날짜 선택기를 쓰세요. 브라우저 현지 시간대로 변환되므로 하루 전체 조회 시 종료 시각을 확인하세요.
특정 Key나 모델만 볼 때 이름을 입력하고 전체 기록은 두 이름을 비워두세요.

필터	필수	사용법
집계 단위 `type`	예	1=분, 2=시간, 3=일, 4=주, 5=월
시작·종료	예	`startTime`, `endTime`은 초 단위. 종료는 시작보다 빠를 수 없음
API Key 이름 `tokenName`	아니요	비밀 키나 토큰이 아닌 이름. 생략하면 이름 필터 없음
모델 이름 `modelName`	아니요	실제 모델 이름. 생략하면 모델 필터 없음

통계 조회 및 확인

청구 통계 조회의 Try It에서 조건을 보내세요. 본문 code=200은 업무 성공이며 data는 호출별 로그가 아닌 집계 배열입니다.

time, timeGroup: 기록 시각과 초 단위 그룹 시각.
callCount, totalUseTime: 호출 수와 총 소요 시간.
totalPromptTokens, totalCompletionTokens, 캐시 필드: 입력·출력·캐시 사용량.
totalAmount: 소비 금액. 필드와 예제는 Reference를 참조하며 Token 사용량을 금액으로 취급하지 마세요.

code: 200, data: []는 조회 성공이지만 기간·필터에 맞는 기록이 없다는 뜻입니다.

선택 필드는 null일 수 있으며 0으로 취급하지 마세요.

Excel 청구서 내보내기

청구서 내보내기의 Try It에 같은 조건을 보내세요. 파일을 받으면:

결과의 내보내기 기간을 확인하세요.
자동 기간 파일명을 유지하거나 ‘파일 이름’을 바꾸세요. .xlsx 확장자는 자동 유지됩니다.
‘Excel 청구서 다운로드’를 눌러 로컬에 저장하세요.

파일명 시각은 브라우저 현지 시간대입니다. 내용과 열은 플랫폼이 생성하며 이름 변경은 내용에 영향을 주지 않습니다. 통계와 대조할 때 기간·집계 단위·이름 필터를 같게 하세요.

HTTP 200만으로 내보내기 성공이 아닙니다. JSON 업무 오류를 먼저 처리하고 .xlsx로 저장하지 마세요.

문제 해결

현상	조치
성공했지만 기록 없음	시간 단위·기간을 확인하고 이름 필터를 비우세요
업무 `code: 401`, 인증 실패	토큰을 확인하고 유효한데 계속 실패하면 지원팀에 문의
내보내기 `code: 400`, 매개변수 검증 실패	집계 단위와 시작·종료를 확인
내보내기 `code: 500`, `ERROR`	JSON·타입을 확인하고 올바른 입력도 실패하면 관리자 문의
Excel에서 열 수 없음	Content-Type을 확인하여 JSON 오류를 Excel로 저장하지 않았는지 확인

이 업무 오류는 HTTP 200으로 올 수 있습니다. HTTP 상태만 보지 말고 해당 Reference의 전체 예제를 확인하세요.

현재 가격은 모델 마켓플레이스에서 확인하세요.

프로그램에서 호출

Bash 예제는 curl, jq가 필요하며 인증 획득, 통계 조회, Excel 저장을 포함합니다.

아래 세 블록을 순서대로 하나의 .sh로 합치고 토큰·기간을 바꾼 뒤 bash로 실행하세요. 대화형 터미널에 나눠 붙이지 마세요.

예제는 베이징 시간 2026-10-10 00:00:00부터 2026-10-20 23:59:59까지 일별 집계이며 이름 필터는 없습니다. 필요한 기간으로 바꾸세요.

1. 청구 인증 얻기

액세스 토큰으로 GET /api/user/self를 호출하고 data.remark의 token을 읽어 같은 사이트 청구 요청에 사용하세요. 액세스 토큰은 첫 Bearer 단계용으로 청구 token Header를 직접 대체하지 못합니다.

set -euo pipefail

ACCESS_TOKEN='your-user-token'

BILLING_TOKEN=$(curl --fail --silent --show-error "https://api.agtcloud.cn/api/user/self" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | \
  jq -er '
    select(.success == true)
    | .data.remark | fromjson | .token
    | select(type == "string" or type == "number")
    | tostring | select(length > 0)
  ')

2. 통계 조회

curl --fail-with-body "https://api.agtcloud.cn/bill/stats" \
  -X POST \
  -H "token: ${BILLING_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": 3,
    "startTime": 1791561600,
    "endTime": 1792511999
  }'

cURL 종료 코드뿐 아니라 JSON code로 업무 성공을 판단하세요. 루트 timestamp는 밀리초이며 조회 시간은 초입니다.

3. Excel 확인 및 저장

성공은 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet 스트림이어야 하며 JSON 업무 오류가 아닙니다.

먼저 임시 파일에 쓰고 HTTP 200·Excel 타입·비어 있지 않음일 때만 bill_export.xlsx로 저장합니다. 기존 파일은 덮어쓰지 않습니다.

response_file=$(mktemp './.bill_export.XXXXXX')
[[ "$response_file" == ./.bill_export.* && -f "$response_file" && ! -L "$response_file" ]] || exit 1
trap 'if [[ "$response_file" == ./.bill_export.* && -f "$response_file" && ! -L "$response_file" ]]; then rm -f -- "$response_file"; fi' EXIT

response_meta=$(curl --silent --show-error "https://api.agtcloud.cn/bill/excel" \
  -X POST \
  -H "token: ${BILLING_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": 3,
  "startTime": 1791561600,
  "endTime": 1792511999
}' \
  --output "$response_file" \
  --write-out '%{http_code}\n%{content_type}')

http_status=${response_meta%%$'\n'*}
content_type=${response_meta#*$'\n'}
if [[ "$http_status" != 200 || "${content_type%%;*}" != application/vnd.openxmlformats-officedocument.spreadsheetml.sheet || ! -s "$response_file" ]]; then
  printf 'Export failed: HTTP %s (%s)\n' "$http_status" "$content_type" >&2
  if [[ "${content_type%%;*}" == application/json ]]; then
    jq '{code, message}' "$response_file" >&2
  fi
  exit 1
fi

if [[ -e bill_export.xlsx || -L bill_export.xlsx ]]; then
  printf 'bill_export.xlsx already exists; choose another filename.\n' >&2
  exit 1
fi
mv -n -- "$response_file" bill_export.xlsx
if [[ -e "$response_file" ]]; then
  printf 'bill_export.xlsx already exists; choose another filename.\n' >&2
  exit 1
fi
printf 'Saved bill_export.xlsx\n'