Hướng dẫn kết nối API trung gian cho Cursor: Cấu hình Base URL tùy chỉnh

1. Cursor là gì?

Cursor là trình soạn thảo mã nguồn được xây dựng dựa trên VS Code với nền tảng AI tích hợp sâu, hỗ trợ trò chuyện (Chat), tạo mã (Composer/Chat) và tự động hoàn thiện thông minh. Nó hỗ trợ BYOK (Bring Your Own Key), cho phép bạn sử dụng API Key riêng để kết nối với các endpoint mô hình của mình. Điều này rất phù hợp cho những người dùng không muốn mua gói đăng ký chính thức hoặc muốn tập trung sử dụng một mô hình cụ thể.

Sau khi kết nối với trung gian, bạn có thể sử dụng các mô hình Claude / GPT / Gemini theo hình thức trả phí theo token thông qua khóa sk- của hệ thống mà không cần mua gói đăng ký chính thức của Cursor.

2. Chuẩn bị

1. Đăng nhập vào bảng điều khiển API, tạo khóa sk-xxxxxx dành riêng cho bạn trong phần "API Keys".
2. Xác nhận slug mô hình muốn sử dụng (ví dụ: claude-sonnet-5, gpt-5.5, gemini-3.7-flash) trong phần "Model Pricing".
3. Xác nhận địa chỉ gateway: https://www.relay-api.com.

3. Cấu hình trong Cursor

Mở Cursor → Settings → Models → API Keys (hoặc tìm kiếm Models trực tiếp trong phần cài đặt):

1. Chọn nhà cung cấp mô hình muốn kết nối (OpenAI chọn mục Open AI, Claude chọn Anthropic, Gemini chọn Google Gemini).
2. Nhập API Key: sk-khóa_của_bạn.
3. Nhập Override Base URL: Điền đường dẫn gateway tương ứng với nhà cung cấp đã chọn.
   • Claude / Anthropic: https://www.relay-api.com
   • GPT / OpenAI: https://www.relay-api.com/v1
   • Gemini: https://www.relay-api.com/v1beta
4. Thêm ID mô hình chính xác muốn sử dụng vào danh sách Models (sao chép slug từ bảng điều khiển, không nhập tên hiển thị).
5. Nhấn Verify để xác thực kết nối; sau đó dùng Chat bình thường để gửi một đoạn văn bản ngắn nhằm xác nhận phản hồi hoạt động bình thường.

4. Nghiệm thu và xử lý lỗi

Hiện tượng	Cách xử lý
401 / 403	Khóa không hợp lệ, chưa được kích hoạt hoặc không đủ số dư; xác nhận sk- chính xác và nạp thêm tiền.
404 / Mô hình không khả dụng	Slug mô hình không khớp với nền tảng hoặc mô hình chưa được kích hoạt; kiểm tra lại ID mô hình.
Verify thành công nhưng Agent thất bại	Phân biệt sự khác biệt giao thức /chat/completions, hãy sử dụng Chat cơ bản để kiểm tra kết nối nền tảng.
Tab completion không hoạt động	Các tính năng chuyên dụng như Tab Completion vẫn sử dụng mô hình tích hợp sẵn của Cursor, đây là giới hạn sản phẩm, không liên quan đến cấu hình Base URL.

Khuyến nghị bảo mật: Không đăng tải khóa lên các kho lưu trữ công khai. Bạn nên tạo mỗi dự án một khóa riêng biệt và chú ý theo dõi số dư cùng chi tiết sử dụng.

Giải thích về Base URL: Hệ thống chấp nhận cả /v1beta/models/... và /v1beta/v1beta/models/... (cũng như /v1/... và /v1/v1/...), vì vậy việc ứng dụng khách có tự động thêm /v1 hoặc /v1beta hay không đều không ảnh hưởng đến việc gọi API: Base URL điền địa chỉ tên miền gốc hoặc địa chỉ có kèm /v1beta đều hoạt động. Vui lòng tra cứu và sao chép ID mô hình trong phần "Model ID" ở góc trên bên phải trang "Token" trong bảng điều khiển.