Tra cứu và xuất hóa đơn

Chọn khoảng thời gian, xem thống kê tiêu thụ và xuất hóa đơn Excel.

Thống kê hóa đơn tổng hợp mức dùng, số lần gọi và số tiền theo thời gian. Excel dùng để lưu và đối chiếu ngoại tuyến.

Chuẩn bị token truy cập

Tạo token truy cập trong mục “Bảo mật” của hồ sơ, nhập vào Try It của Tra cứu thống kê hóa đơn hoặc Xuất hóa đơn.

Chọn thời gian và bộ lọc

Chọn đơn vị thống kê, ví dụ “Ngày” để xem tổng hợp mỗi ngày.
Nhập mốc Unix theo giây cho bắt đầu/kết thúc, hoặc dùng bộ chọn ngày bên phải. Ngày được chuyển theo múi giờ trình duyệt; kiểm tra giờ cuối khi muốn lấy trọn ngày.
Chỉ nhập tên khi cần lọc API Key hoặc mô hình cụ thể; để cả hai trống nếu muốn mọi bản ghi phù hợp.

Bộ lọc	Bắt buộc	Cách dùng
Đơn vị `type`	Có	1=phút, 2=giờ, 3=ngày, 4=tuần, 5=tháng
Bắt đầu, kết thúc	Có	`startTime`, `endTime` theo giây; kết thúc không trước bắt đầu
Tên API Key `tokenName`	Không	Tên, không phải khóa bí mật/token truy cập; bỏ qua để không lọc tên
Tên mô hình `modelName`	Không	Tên mô hình thực tế; bỏ qua để không lọc mô hình

Tra cứu và xem thống kê

Gửi điều kiện bằng Try It của Tra cứu thống kê hóa đơn. code=200 trong thân là thành công nghiệp vụ; data là mảng tổng hợp, không phải nhật ký từng lần gọi.

time, timeGroup: thời gian bản ghi và mốc nhóm theo giây.
callCount, totalUseTime: số lần gọi và tổng thời lượng.
totalPromptTokens, totalCompletionTokens và trường cache: mức dùng đầu vào, đầu ra và cache.
totalAmount: số tiền tiêu thụ. Xem Reference để biết trường và ví dụ đầy đủ; không coi số Token là tiền.

code: 200, data: [] nghĩa là truy vấn thành công nhưng không có bản ghi khớp thời gian và bộ lọc.

Một số trường tùy chọn có thể là null; không coi là 0.

Xuất hóa đơn Excel

Gửi cùng điều kiện bằng Try It của Xuất hóa đơn. Khi lấy tệp thành công:

Kiểm tra khoảng thời gian xuất hiển thị trong kết quả.
Giữ tên tệp chứa thời gian hoặc sửa “Tên tệp”; phần mở rộng .xlsx được giữ tự động.
Nhấn “Tải hóa đơn Excel” để lưu cục bộ.

Thời gian trong tên tệp dùng múi giờ trình duyệt. Nội dung và cột Excel do nền tảng tạo; đổi tên không đổi dữ liệu. Khi so sánh thống kê và xuất, giữ nguyên thời gian, đơn vị và bộ lọc tên.

HTTP 200 không bảo đảm xuất thành công: xử lý lỗi JSON trước, không lưu thành .xlsx.

Câu hỏi thường gặp

Hiện tượng	Cách xử lý
Thành công nhưng không có dữ liệu	Kiểm tra đơn vị thời gian và khoảng ngày, rồi xóa bộ lọc tên
`code: 401` nghiệp vụ, xác thực thất bại	Kiểm tra token truy cập; nếu hợp lệ vẫn lỗi, liên hệ hỗ trợ
Xuất trả `code: 400`, lỗi kiểm tra tham số	Kiểm tra đơn vị cùng giờ bắt đầu và kết thúc
Xuất trả `code: 500`, `ERROR`	Kiểm tra JSON và kiểu tham số; nếu đúng vẫn lỗi, liên hệ quản trị viên
Không mở tệp bằng Excel được	Kiểm tra Content-Type, tránh lưu JSON lỗi thành Excel

Các lỗi xuất này có thể dùng HTTP 200; không chỉ nhìn mã HTTP. Xem ví dụ đầy đủ trong Reference tương ứng.

Xem giá mô hình hiện hành tại chợ mô hình.

Gọi từ chương trình

Ví dụ Bash cần curl và jq, gồm lấy xác thực, tra cứu thống kê và lưu Excel.

Ghép ba khối sau theo thứ tự vào một tệp .sh, thay token và thời gian, rồi chạy bằng bash; không dán từng phần vào terminal tương tác.

Ví dụ từ 2026-10-10 00:00:00 đến 2026-10-20 23:59:59, giờ Bắc Kinh, theo ngày, không lọc tên. Thay bằng thời gian cần tra cứu.

1. Lấy xác thực hóa đơn

Gọi GET /api/user/self bằng token truy cập, phân tích token trong data.remark, dùng cho hóa đơn cùng trang. Token truy cập dùng Bearer ở bước đầu, không trực tiếp thay Header token của hóa đơn.

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. Tra cứu thống kê

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
  }'

Đọc JSON code để biết thành công nghiệp vụ, không chỉ trạng thái thoát cURL. timestamp gốc là mili giây, còn thời gian truy vấn là giây.

3. Kiểm tra và lưu Excel

Thành công phải trả luồng application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, không phải JSON lỗi.

Ghi tệp tạm trước; chỉ lưu thành bill_export.xlsx khi HTTP 200, kiểu Excel và tệp không rỗng. Không ghi đè tệp đã có.

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'