Dùng khoá provider riêng của bạn

BYOK không phải lúc nào cũng có lợi. Nó hợp lý khi:

• Bạn đã có hợp đồng hoặc mức giá riêng với nhà cung cấp, rẻ hơn giá bán lẻ.
• Công ty bạn yêu cầu mọi lệnh gọi model phải nằm dưới tài khoản doanh nghiệp để kiểm toán hoặc tuân thủ.
• Bạn muốn dùng một model mà chúng tôi chưa bật sẵn, nhưng provider thì đã hỗ trợ.
• Bạn đang tự vận hành model trên máy chủ của mình và chỉ cần phần điều phối, kênh, kho kiến thức.

Ngược lại, nếu bạn chỉ muốn mọi thứ chạy và không muốn quản thêm một hoá đơn nữa, cứ dùng credits của chúng tôi — nạp trước, hết thì dừng, có báo cáo chi phí từng tin nhắn.

Rất đơn giản: lần gọi nào dùng khoá của bạn thì không trừ credits. Chúng tôi vẫn ghi lại số token vào/ra để bạn có thống kê trong dashboard, nhưng số tiền ghi nhận là 0 và ví không đổi số dư.

Trong phản hồi của /v1/chat/completions, khối chatly nói rõ lần gọi đó thuộc loại nào:

"chatly": { "charged_micros": "0", "byok": true }

Mỗi provider có thể có nhiều khoá với nhãn khác nhau, nhưng nhãn không được trùng nhau trong cùng một provider — gửi trùng sẽ nhận 409 conflict.

Cách dễ nhất là vào dashboard: Cài đặt → Khoá riêng của bạn (BYOK) (/dashboard/cai-dat), chọn provider, đặt nhãn dễ nhớ và dán khoá. Thao tác này yêu cầu vai trò quản trị trở lên, vì nó đụng tới bí mật và hoá đơn của cả tổ chức.

Nếu muốn làm bằng API:

curl https://api.chattudong.com/provider-keys \
  -H "Authorization: Bearer $CHATLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "label": "Khoá OpenAI của công ty",
    "key": "sk-..."
  }'

{
  "id": "pk_…",
  "provider": "openai",
  "label": "Khoá OpenAI của công ty",
  "lastFour": "a1b2",
  "enabled": true
}

Liệt kê bằng GET /provider-keys — chỉ trả về nhãn, provider, bốn ký tự cuối và thời điểm dùng gần nhất. Xoá bằng DELETE /provider-keys/{id}.

Có khoá rồi vẫn chưa đủ — bạn phải nói rõ lần gọi này muốn dùng khoá riêng, bằng header x-chatly-use-byok: true. Thiết kế như vậy để bạn chủ động: cùng một tổ chức có thể vừa chạy tác vụ nền bằng khoá riêng, vừa để bot chăm sóc khách hàng chạy bằng credits.

curl https://api.chattudong.com/v1/chat/completions \
  -H "Authorization: Bearer $CHATLY_API_KEY" \
  -H "x-chatly-use-byok: true" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1-mini",
    "messages": [{"role": "user", "content": "Tóm tắt đoạn này giúp tôi"}]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.chattudong.com/v1",
  apiKey: process.env.CHATLY_API_KEY,
  defaultHeaders: { "x-chatly-use-byok": "true" },
});

Nếu tổ chức chưa có khoá đang bật cho provider của model bạn chọn, hệ thống tự quay về khoá nền tảng và tính tiền như bình thường. Muốn biết chắc lần gọi đó chạy bằng gì thì đọc chatly.byok trong phản hồi.

Đây là phần chúng tôi nghiêm túc nhất, nên nói thẳng cách làm thay vì hứa chung chung.

• Mã hoá envelope AES-256-GCM. Mỗi khoá được mã hoá bằng một data key riêng, data key đó lại được bọc bằng khoá gốc của hệ thống. Lộ một bản ghi không kéo theo bản ghi khác, và xoay khoá gốc chỉ cần bọc lại data key chứ không phải mã hoá lại toàn bộ dữ liệu.
• Buộc vào đúng bản ghi. Dữ liệu phụ trợ xác thực (AAD) gắn ciphertext với chính bản ghi của nó. Ai đó copy khối đã mã hoá từ tổ chức này sang tổ chức khác thì giải mã sẽ thất bại, chứ không âm thầm hoạt động.
• Không bao giờ hiển thị lại. Sau khi lưu, chúng tôi chỉ trả về bốn ký tự cuối để bạn nhận ra đó là khoá nào. Không có màn hình nào, không có endpoint nào cho xem lại khoá đầy đủ. Mất khoá thì xoá và dán khoá mới.
• Không rời tiến trình xử lý. Khoá chỉ được giải mã ngay tại thời điểm gọi nhà cung cấp, không ghi vào log, không đi kèm phản hồi trả về cho client.
• Có nhật ký kiểm toán. Thêm và xoá khoá đều ghi lại ai làm, lúc nào.

Chi tiết từng mã lỗi xem ở API Reference.