Số dư và quota

RouteAPI hoạt động theo mô hình trả trước: bạn nạp tiền vào tài khoản trước, khi gọi API sẽ bị trừ phí từ số dư theo mức sử dụng thực tế. Bạn có thể đặt quota riêng cho từng API key, hoặc bật tự động nạp tiền để tránh dịch vụ bị gián đoạn khi số dư cạn.

Tính bằng đô la Mỹ

Số dư tài khoản, giá mô hình, quota API key và số tiền nạp đều tính bằng đô la Mỹ (USD). Console có thể quy đổi số tiền sang đơn vị tiền tệ khác theo cấu hình của site để hiển thị; đây chỉ là quy đổi ở lớp hiển thị, việc trừ phí và ghi sổ luôn tính bằng USD.

Số dư tài khoản

Số dư tài khoản là quỹ chung cho tất cả API key của bạn; xem số dư hiện tại và mức sử dụng trong quá khứ tại trang Ví.

• Mỗi yêu cầu đều bị trừ phí từ số dư tài khoản, và số dư không bao giờ bị trừ âm.
• Nếu số dư không đủ để trả chi phí ước tính của một yêu cầu, yêu cầu sẽ bị từ chối với 403 và mã lỗi insufficient_user_quota. Cách ước tính xem tại Usage và tính phí.
• Nếu tài khoản của bạn có chiết khấu riêng, thị trường mô hình sẽ hiển thị giá sau chiết khấu, nhật ký usage sẽ ghi chú “Hệ số riêng”, và phí được tính theo giá sau chiết khấu.

Quota API key

Khi tạo hoặc chỉnh sửa key tại trang API Key, bạn có thể đặt riêng cho từng key:

Cài đặt	Mô tả
Quota (USD)	Số tiền tối đa key này được tiêu; có thể đặt quota không giới hạn
Thời gian hết hạn	Key hết hiệu lực khi đến hạn; mặc định không bao giờ hết hạn
Giới hạn mô hình	Chỉ cho phép key này gọi các mô hình được chỉ định
Danh sách IP cho phép	Chỉ chấp nhận yêu cầu từ các IP được chỉ định

Quota của key là một mức trần, không phải một ví riêng. Mỗi yêu cầu trừ đồng thời vào quota của key và số dư tài khoản; nếu một trong hai không đủ, yêu cầu sẽ bị từ chối. Kể cả khi đặt quota không giới hạn, số tiền thực tế có thể dùng vẫn bị giới hạn bởi số dư tài khoản.

Cách dùng phổ biến là tạo key riêng cho từng dự án, môi trường hoặc thành viên và đặt quota cho từng key, để một ứng dụng đơn lẻ không thể tiêu hết số dư của cả tài khoản. Danh sách API key hiển thị quota đã dùng và tổng quota của từng key.

Tình huống	Phản hồi
Quota của key đã hết	401, thông báo quota của key đã cạn
Quota còn lại của key không đủ trả chi phí ước tính của lần này	403, mã lỗi pre_consume_token_quota_failed
Key đã hết hạn hoặc đã bị vô hiệu hóa	401
Yêu cầu gọi mô hình mà key không được phép, hoặc IP nguồn không nằm trong danh sách cho phép	403

Nạp tiền

Tại trang Ví, chọn số tiền và phương thức thanh toán để nạp; tối thiểu 1 USD. Các phương thức thanh toán khả dụng theo hiển thị trên trang ví.

• Số dư được ghi nhận theo đúng số tiền USD bạn nhập.
• Khi thanh toán bằng thẻ ngân hàng qua Stripe, số tiền thực bị trừ bao gồm 4% phí xử lý trên số tiền nạp, để bù đắp phí xử lý thanh toán và thuế. Trang sẽ hiển thị số tiền thực bị trừ trước khi bạn thanh toán.

Tự động nạp tiền

Sau khi bật tự động nạp tiền, khi số dư xuống dưới ngưỡng bạn đặt, hệ thống sẽ tự động nạp một số tiền cố định bằng thẻ ngân hàng đã lưu; phù hợp với môi trường production cần vận hành ổn định lâu dài. Cấu hình tại mục “Tự động nạp tiền” trong trang ví.

Cài đặt	Mô tả	Phạm vi
Ngưỡng kích hoạt	Kích hoạt nạp tiền khi số dư xuống dưới mức này	Không quá 1,000 USD, mặc định 20 USD
Số tiền mỗi lần nạp	Số tiền nạp tự động mỗi lần	10–5,000 USD, mặc định 100 USD
Hạn mức mỗi tháng	Tổng hạn mức nạp tự động trong một tháng dương lịch; 0 nghĩa là không giới hạn	Không quá 50,000 USD và không thấp hơn số tiền mỗi lần nạp
Phương thức thanh toán	Thẻ ngân hàng dùng để trừ tiền	Lưu tối đa 3 thẻ, dùng theo thứ tự đã đặt

Cách hoạt động:

• Sau mỗi lần quyết toán yêu cầu, hệ thống kiểm tra số dư và kích hoạt một lần nạp nếu xuống dưới ngưỡng. Giữa hai lần nạp tự động cách nhau ít nhất 10 phút.
• Nếu lúc lưu cài đặt số dư đã dưới ngưỡng, hệ thống sẽ kích hoạt nạp tiền ngay.
• Khi thẻ mặc định bị từ chối rõ ràng (ví dụ thẻ hết hạn, bị ngân hàng phát hành từ chối), hệ thống sẽ thử lần lượt các thẻ đã lưu tiếp theo. Khi kết quả không rõ ràng (ví dụ cần xác thực 3D), hệ thống không đổi thẻ để tránh bị trừ tiền hai lần.
• Nếu tất cả các thẻ đều thất bại, hệ thống tự động thử lại sau 15 phút, 1 giờ, 3 giờ và 6 giờ. Nếu vẫn thất bại, hệ thống dừng thử lại và gửi email thông báo cho bạn. Trang ví cũng hiển thị nhắc nhở; sau khi đổi phương thức thanh toán, bạn có thể bấm “Nạp tiền ngay”.
• Khi đạt hạn mức tháng, tháng đó sẽ không tự động nạp tiền nữa.
• Tự động nạp tiền cũng chịu phí 4%.

Mẹo

Nên đặt ngưỡng kích hoạt thấp hơn số tiền mỗi lần nạp, và để dư theo tốc độ tiêu thụ đỉnh của bạn. Nếu trong 10 phút bạn có thể tiêu hết phần tiền trong ngưỡng, hãy tăng ngưỡng hoặc số tiền mỗi lần nạp.

Nhắc nhở số dư

Trong cài đặt thông báo tại Cài đặt cá nhân, bạn có thể đặt ngưỡng nhắc nhở số dư; khi số dư xuống dưới ngưỡng, bạn sẽ được thông báo qua email, Webhook, Bark hoặc Gotify. Khi số dư cạn khiến yêu cầu bị từ chối, hệ thống cũng gửi email nhắc nhở, tối đa một lần mỗi ngày.

Khi số dư không đủ thì làm gì

1. Nạp tiền tại trang ví, hoặc bật tự động nạp tiền.
2. Nếu mã lỗi là pre_consume_token_quota_failed, hoặc thông báo quota của key đã cạn, bạn cần tăng quota của key này; nạp tiền vào tài khoản không giải quyết được.
3. Nếu số dư có vẻ đủ nhưng yêu cầu vẫn bị từ chối, hãy kiểm tra max_tokens trong yêu cầu có đặt quá lớn không. Chi phí ước tính có tính cả max_tokens; xem chi tiết tại Usage và tính phí.
4. Đối chiếu mức tiêu thụ gần đây trong nhật ký usage.