Wits Connect & API

Wits Connect gồm những gì

Wits Connect có năm mục: Tổng quan, Khoá API, Mô hình, Mức dùng và Hướng dẫn tích hợp. Một khoá dùng được cho mọi mô hình, bạn chọn mô hình bằng trường model trong mỗi lời gọi.

Mỗi lần gọi trừ Wits từ ví của bạn, không có phí cố định.

Muốn một bảng điều khiển đầy đủ hơn với nhật ký, giới hạn và thanh toán, dùng Cổng nhà phát triển (xem bài riêng). Khoá tạo ở đâu cũng nằm chung một danh sách của tài khoản bạn.

Tạo và thu hồi khoá API

Mỗi tài khoản có tối đa 20 khoá đang hoạt động cùng lúc. Hãy tạo một khoá riêng cho mỗi ứng dụng để thu hồi riêng khi cần.

Nếu tài khoản chưa được mở quyền tạo khoá, trang ghi “Việc tạo API key mới hiện chưa mở”. Khoá đã có vẫn hoạt động và bạn vẫn thu hồi được.

1. Mở mục Khoá API. Khung Tạo API key nằm ở đầu mục. Nút Tạo khoá ở đầu cột trái cũng đưa bạn tới đây.
2. Điền Tên API key (tối đa 60 ký tự). Đặt tên dễ nhớ để sau này biết khoá nào dùng cho ứng dụng nào.
3. Điền Hạn mức token/tháng. Nhập 0 nghĩa là không giới hạn. Xem mục Trần token mỗi tháng bên dưới.
4. Bấm Tạo API key rồi bấm Copy. Trang cảnh báo: khoá chỉ hiện 1 lần, rời trang là không xem lại được.
5. Bấm Thu hồi ở dòng khoá khi không dùng nữa. Trang hỏi xác nhận: ứng dụng đang dùng khoá này sẽ mất quyền gọi API ngay. Thu hồi xong không khôi phục được.

Trần token mỗi tháng cho từng khoá

Trần token tháng đặt riêng cho từng khoá lúc tạo. Khoá chạm trần thì dừng cho tới đầu tháng sau, các khoá khác vẫn chạy bình thường. Khi đó API trả mã quota_exceeded.

Mục Mức dùng hiện token đã dùng của từng khoá trong tháng so với trần bạn đặt, kèm dòng Tổng các khoá.

Trần của khoá khác với ví. Khoá hết trần thì nhờ chủ tài khoản nâng trần. Ví hết tiền thì nạp thêm Wits.

Gọi API

API theo chuẩn OpenAI, nên thư viện bạn đang dùng chỉ cần đổi hai thứ là base_url và khoá.

base_url là https://witsagi.com/api/v1. Header là Authorization: Bearer sk-wits-… Điểm cuối chat là POST /chat/completions.

Danh sách mô hình hiện hành lấy bằng GET /api/v1/models. Ví dụ curl, Python, Node và mã lỗi đầy đủ nằm ở trang Tài liệu API (/docs/api). Bài này không lặp lại.

1. Mở mục Hướng dẫn tích hợp. Trang nhắc base_url, header và có nút Mở tài liệu API.
2. Chép ví dụ ở mục Ví dụ gọi API. Thay khoá thật vào chỗ sk-wits-… rồi chạy từ máy chủ của bạn.
3. Kiểm tra phản hồi. Mỗi phản hồi cho biết số Wits đã trừ và số dư còn lại, bạn không cần gọi thêm để đối soát.

Mô hình gọi được qua API

Mục Mô hình liệt kê mô hình đang gọi được, chia theo nhóm, mỗi dòng có tên, vai trò, trạng thái Mở hoặc Sắp mở và giá.

Giá tính bằng USD cho mỗi 1 triệu token (vào và ra), ví trừ Wits tương ứng. Số cụ thể xem ngay ở mục này, không ghi cố định trong bài.

Wits 5 (miễn phí) và Wits Flat 5.5 (gói tháng) chỉ dùng trong ứng dụng Studio, không gọi qua API.

Ví bị trừ thế nào

Ví trừ theo token thật: token vào và token ra tính riêng theo bậc mô hình. Trước khi chạy, hệ thống giữ trước một khoản theo ước lượng, chạy xong hoàn lại phần thừa.

Yêu cầu bị từ chối vì hết ví hoặc hết trần khoá thì không bị trừ đồng nào.

Gói tháng Plus, Pro, Max cấp hạn mức dùng trong ứng dụng. Lời gọi API trừ ví Wits. Chi tiết xem bài Gói, hạn mức và ví Wits.

Các mã lỗi hay gặp

Lỗi trả về dạng JSON giống chuẩn OpenAI, có trường code. Bảng đầy đủ và cách xử lý ở trang Tài liệu API (/docs/api).

401 invalid_api_key: thiếu header, sai khoá hoặc khoá đã thu hồi. Tạo khoá mới nếu cần.

402 insufficient_wits: ví Wits hết tiền. Nạp thêm ở /billing.

429 rate_limited: gọi quá nhanh. Mỗi khoá được 120 yêu cầu mỗi phút và 20 yêu cầu mỗi 10 giây. Chờ đúng số giây trong header Retry-After rồi gọi lại.

429 quota_exceeded: khoá đã dùng hết trần token của tháng. Nâng trần hoặc chờ tới đầu tháng sau.

404 model_not_found: tên mô hình sai. Lấy danh sách bằng GET /api/v1/models.