Billing

Gateway hoạt động trả trước: bạn nạp credit, mỗi request chốt sổ trừ vào đó theo từng token, và mọi con số soi lại được theo từng request. Trang này là chính sách tính tiền chính xác — đúng bộ quy tắc engine billing đang chạy.

Một request tốn bao nhiêu

Mỗi model có ba chiều giá theo token — input, cached_input và output — công bố theo USD trên một triệu token ở trang models và trong GET /v1/models. Chi phí một request là:

công thức chi phí

billable_input = prompt_tokens - cached_tokens

cost = billable_input   x input_price
     + cached_tokens    x cached_input_price   (falls back to input_price)
     + completion_tokens x output_price
     + request_fee                             (0 on all current models)

Prompt cache là tự động: phần input mà upstream nhận ra từ một prefix giống hệt gần đây trả về trong prompt_tokens_details.cached_tokens và được tính theo giá cached_input rẻ hơn.
Model không công bố giá cached_input (hiện là glm-4.7-flash) tính trọn prompt theo giá input — cached_tokens vẫn được báo cho minh bạch, chỉ là không kèm giảm giá, vì phía chúng tôi cũng không được upstream giảm.
Reasoning không bao giờ tính tiền riêng. reasoning_tokens là tập con của completion_tokens — phần đã tính đủ theo giá output; con số này hiện ra để bạn giải thích được câu trả lời dài, không phải để tính hai lần.

Khối usage của mọi response mang đủ đầu vào của công thức đó:

usage trong response

"usage": {
  "prompt_tokens": 12907,
  "completion_tokens": 300,
  "total_tokens": 13207,
  "prompt_tokens_details": {"cached_tokens": 12864},
  "completion_tokens_details": {"reasoning_tokens": 0}
}

Chi phí tính bằng số nguyên nano-USD (10⁻⁹ USD) — không float, không làm tròn từng request. Trúng cache exact toàn phần (request giống hệt, response phục vụ từ cache của gateway) chỉ tính 10% giá thường của response đó và mang x-gw-cache: hit.

Hold và lỗi 402

Trước khi gọi model, gateway tạm giữ trên số dư khả dụng một khoản: chi phí prompt ước tính cộng output tính tới min(max_tokens, 4096) token. Khoản giữ được nhả ngay khi request chốt sổ theo chi phí thật — hold chỉ sống vài giây, và có trần để model context lớn không bao giờ đóng băng cả đô-la mỗi request. Nếu số dư khả dụng không đủ cho khoản giữ:

402 insufficient_credits

HTTP/1.1 402 Payment Required
{
  "error": {
    "message": "Insufficient credits. Available: $0.0041. This request requires an estimated hold of $0.0269. Top up at https://app.clfaigateway.dev/billing/topup",
    "type": "insufficient_credits",
    "code": "insufficient_credits",
    "param": null,
    "metadata": {
      "available_nano": 4100000,
      "required_estimate_nano": 26927600,
      "topup_url": "https://app.clfaigateway.dev/billing/topup"
    }
  }
}

Số khả dụng và mức ước tính nằm trong message cho người đọc và trong metadata cho máy. SDK không tự retry 402 — nạp tiền rồi gửi lại.

Bảo hiểm zero-completion

Quy tắc nguyên văn

Request kết thúc với completion_tokens = 0 VÀ finish_reason là null hoặc "error" → giá $0 — kể cả phần prompt token mà upstream đã tính chúng tôi. Phần đó chúng tôi chịu.

Nói gọn: model hỏng mà không sinh ra gì thì bạn không mất gì, tính cả prompt.

Bảo hiểm KHÔNG áp dụng khi finish_reason là "stop" hoặc "length" với 0 completion token — ví dụ request gửi max_tokens: 0. Model đã chạy xong bình thường và tự dừng (hoặc bị bảo dừng), nên prompt tính tiền như thường. Không có ngoại lệ này thì max_tokens: 0 thành đường xử lý prompt miễn phí.

Ngắt kết nối và stream đứt

Trường hợp	Bạn trả
Bạn ngắt giữa stream	Phần token đã phát, đếm chính xác từ usage per-chunk — việc sinh chữ không dừng hồi tố. Request chốt sổ `success`.
Upstream hỏng giữa stream	Chỉ phần token đã phát trước lúc hỏng; bạn nhận `finish_reason: "error"` và request chốt sổ `partial`.
Hỏng trước khi có output	$0 theo bảo hiểm zero-completion (điều kiện phía trên).

Chặn trần xấu nhất bằng max_tokens

Ngắt kết nối không hủy phần đã sinh, nên max_tokens chính là trần chi tiêu mỗi request của bạn. Không gửi thì gateway áp mặc định 4096 token output.

Xem chi phí ở đâu

Response không stream (và cache hit) mang chi phí đã chốt trong header x-gw-cost-nano:

header response

x-request-id: req_01j9zx6d2fk8v3q7w1m4e5t8ha
x-gw-model: kimi-k2.6
x-gw-cache: miss
x-gw-cost-nano: 1979454
x-ratelimit-limit: 60
x-ratelimit-remaining: 57
x-ratelimit-reset: 1774694460

Stream không mang được header đó — header gửi đi trước khi chi phí tồn tại. Với mọi request, GET /v1/generation là hồ sơ chính thức per-request (token, chi phí, tầng cache, độ trễ, trạng thái), có sau khi chốt sổ vài giây:

tra chi phí một request

curl "https://api.clfaigateway.dev/v1/generation?id=req_01j9zx6d2fk8v3q7w1m4e5t8ha" \
  -H "Authorization: Bearer sk-gw-..."

Số tổng hợp nằm ở GET /v1/usage và trên dashboard. Ba bề mặt hiện cùng một bộ số đã chốt.

Hiển thị trễ không phải tính tiền trễ

Số trên dashboard và số tổng hợp thường xuất hiện trong vài giây sau khi chốt sổ, nhưng có thể trễ vài phút lúc tải nặng. Bản thân khoản tiền được chốt đúng một lần cho mỗi request trong sổ cái — con số bạn thấy cuối cùng luôn là số đã chốt, không bao giờ là ước lượng.

Nạp tiền và credit

Nạp từ dashboard: chuyển khoản VietQR (xác nhận tự động, thường trong vài giây) hoặc thẻ quốc tế. Credit tính bằng USD.
Credit khuyến mãi có hạn dùng được tiêu trước credit đã mua, nên không có chuyện khoản khuyến mãi hết hạn trong khi tiền mua bị tiêu trước.
Số dư, các khoản credit còn hiệu lực và hạn của chúng xem ở GET /v1/credits và trên dashboard.

Trang trướcStreaming Trang sauContext & cache