Tài liệu

Đăng nhập Desktop, gọi API và hiểu cách FuJue Platform tính chi phí.

Bắt đầu nhanh

FuJue Platform cấp một tài khoản dùng chung cho bảng điều khiển web, FuJue Harness Desktop và API. Ba bước dưới đây là toàn bộ luồng thiết lập:

1

Tạo tài khoản

Đăng ký bằng email. Mỗi tài khoản mới nhận 1.00 USD tín dụng thưởng dùng cho mọi mô hình.

2

Tạo khoá API nếu gọi từ code

Khoá chỉ hiển thị một lần. Đặt tên theo môi trường, ví dụ Production hoặc CI.

3

Kết nối Desktop hoặc gọi mô hình

Desktop dùng đăng nhập trình duyệt, không cần dán khoá. Ứng dụng khác dùng khoá API với cổng OpenAI hoặc Anthropic bên dưới.

Mọi tài khoản đều tạo khoá API riêng ở trang API key; khoá chỉ hiển thị một lần ngay sau khi tạo.

Tải FuJue Harness

Bộ cài chính thức cho Windows, macOS và Linux nằm ở trang tải ứng dụng. Trang đó hiển thị phiên bản hiện hành, liên kết tải trực tiếp và ghi chú cho từng nền tảng.

  • Windows 10/11 x64 — bản chưa ký, Windows SmartScreen có thể hỏi thêm ở lần mở đầu tiên.
  • macOS 13 trở lên — bản riêng cho Apple Silicon và Intel.
  • Linux x64 — AppImage, cần chmod +x trước khi chạy.

Sau khi cài, mở ứng dụng và chọn “Đăng nhập bằng trình duyệt”. Không cần dán khoá API: Desktop nhận phiên, số dư và danh sách mô hình từ tài khoản của bạn.

Kết nối FuJue Harness Desktop

Desktop dùng uỷ quyền PKCE: ứng dụng tạo một thử thách, mở trình duyệt tới trang đồng ý, nhận mã một lần rồi đổi mã đó thành token riêng cho thiết bị. Không có khoá nào bị dán thủ công và token có thể thu hồi từ web.

1. Trỏ hồ sơ Desktop về Platform

# cordis.yml - id: deepseek-account config: platformOrigin: 'https://platform.fujue.ai' harnessOrigin: 'https://platform.fujue.ai' inferenceOrigin: 'https://platform.fujue.ai' - id: llm-deepseek-account config: baseURL: 'https://platform.fujue.ai/anthropic'

Dùng http://localhost:3000 khi chạy Platform cục bộ; đặt thêm allowLoopbackHttp: true để cho phép HTTP trên loopback trong lúc phát triển.

2. Đăng nhập

Chọn “Đăng nhập bằng trình duyệt” trong menu tài khoản của ứng dụng. Trình duyệt mở trang uỷ quyền; sau khi bạn đồng ý, tab hoàn tất hiện ra và Desktop tự nhận token, danh sách mô hình, số dư và thông báo.

3. Quản lý thiết bị

Mỗi lần đăng nhập tạo một token riêng. Xem và thu hồi tại Cài đặt → Thiết bị đã kết nối. Thu hồi xong, ứng dụng trên thiết bị đó nhận lỗi 401 và phải đăng nhập lại.

Các endpoint Desktop dùng (đều yêu cầu header x-dsh-auth-token):

  • POST /auth-api/v0/dsh/auth_init — tạo yêu cầu PKCE
  • POST /auth-api/v0/dsh/auth_exchange — đổi mã lấy token thiết bị
  • GET /auth-api/v0/users/current — hồ sơ tài khoản
  • GET /api/v0/users/get_user_summary — số dư ví
  • GET /api/v0/users/notifications/list — thông báo chưa đọc
  • GET /models — danh mục mô hình kèm huy hiệu và năng lực

Tham chiếu API

Cổng OpenAI tương thích nhận cùng một khoá API ở header Authorization: Bearer, hoặc x-api-key nếu ứng dụng của bạn dùng kiểu đó.

Liệt kê mô hình

curl https://platform.fujue.ai/v1/models \ -H "Authorization: Bearer $FJ_API_KEY"

Chat completions

curl https://platform.fujue.ai/v1/chat/completions \ -H "Authorization: Bearer $FJ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-flash", "messages": [ { "role": "system", "content": "Trả lời ngắn gọn bằng tiếng Việt." }, { "role": "user", "content": "Tóm tắt thay đổi trong PR này." } ], "temperature": 0.7, "max_tokens": 1024, "stream": true }'

Đặt base_url của SDK thành https://platform.fujue.ai/v1 và dùng khoá FuJue. Trường stream được chuyển nguyên trạng; chi phí vẫn được ghi khi stream kết thúc.

Ví dụ Python

from openai import OpenAI client = OpenAI( api_key="fjk_sk_...", base_url="https://platform.fujue.ai/v1", ) reply = client.chat.completions.create( model="deepseek-v4-pro", messages=[{"role": "user", "content": "Giải thích đoạn code này"}], ) print(reply.choices[0].message.content)

Cổng Anthropic

Desktop gọi mô hình qua giao thức Anthropic tại /anthropic/v1/messages. Cổng này nhận cùng token thiết bị hoặc khoá API và ghi chi phí theo đúng mô hình trong thân yêu cầu.

Nhà cung cấp chỉ có endpoint OpenAI thì cổng tự chuyển yêu cầu sang /chat/completions — nội dung, lời gọi công cụ và luồng sự kiện đều được dịch, nên trong trang quản trị chỉ cần điền một URL và một khoá. Ô URL Anthropic chỉ dùng khi nhà cung cấp có sẵn giao thức này.

curl https://platform.fujue.ai/anthropic/messages \ -H "x-api-key: $FJ_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-flash", "max_tokens": 1024, "messages": [{ "role": "user", "content": "Xin chào" }] }'

Không có yêu cầu mô hình (ví dụ tải tệp) thì cổng chuyển tiếp nguyên vẹn và không tính phí.

Khoá và bảo mật

  • Khoá API có dạng fjk_sk_… và chỉ được lưu dưới dạng băm SHA-256.
  • Token thiết bị có dạng fjk_at_…, gắn với một lần uỷ quyền và thu hồi được độc lập.
  • Phiên trình duyệt dùng cookie HttpOnly, SameSite=Lax; không lưu token trong localStorage.
  • Mã uỷ quyền chỉ dùng một lần, hết hạn sau 10 phút và bị từ chối nếu redirect không nằm trong danh sách cho phép.
  • Mật khẩu lưu bằng scrypt với salt riêng cho từng tài khoản.

Nếu nghi ngờ khoá bị lộ, thu hồi tại Khoá API rồi tạo khoá mới. Ứng dụng đang dùng khoá cũ nhận lỗi 401 ngay lập tức.

Đo lường và số dư

Mỗi yêu cầu hoàn tất ghi một dòng vào bảng sử dụng với model, token vào, token ra và chi phí. Chi phí tính theo giá niêm yết của mô hình, làm tròn 8 chữ số thập phân.

  • Ví thưởng được trừ trước, sau đó tới số dư đã nạp.
  • Số dư không bao giờ âm; yêu cầu mới bị từ chối với mã 402 khi tổng số dư bằng 0.
  • Bảng Sử dụng lọc theo 7, 14, 30 hoặc 90 ngày và tách theo mô hình, khoá và nguồn gọi.
  • Stream được đo khi nhà cung cấp gửi frame usage; nếu không có frame, yêu cầu không bị tính phí.

Mã lỗi

Cổng OpenAI trả lỗi theo cấu trúc chuẩn, mã nằm ở trường `error.code`:

  • 401 invalid_api_key — thiếu khoá, khoá bị thu hồi, hoặc token thiết bị hết hiệu lực.
  • 402 insufficient_quota — số dư bằng 0; nạp thêm để tiếp tục.
  • 404 model_not_found — Platform không phục vụ model đã yêu cầu.
  • 503 upstream_not_configured — máy chủ thiếu DEEPSEEK_API_KEY.
  • 502 upstream_unreachable — không kết nối được nhà cung cấp mô hình.

Cổng Anthropic trả lỗi dạng {"type":"error","error":{...}} với cùng ngữ nghĩa HTTP.