Tham chiếu API

API Chat Completions tương thích OpenAI của OneNexus chỉ hoạt động khi base URL và giá trị model của request cùng thuộc một serving surface, và API key bạn dùng có quyền truy cập surface đó.

Nếu cần hướng dẫn từng bước cho request đầu tiên, hãy xem Bắt đầu nhanh với Platform model hoặc Gọi endpoint của self-hosted model.

Chọn đúng serving surface

Surface	Base URL	API key	Giá trị `model` trong request
Platform catalog dùng chung	`https://catalog.onenexus-do.cloud/v1`	Platform	Giá trị `model` chính xác trong Lệnh gọi cURL (`cURL request`) của dòng đã mở rộng
Self-hosted models của tenant	Sao chép tenant Endpoint hiển thị trên trang chi tiết model và thêm đuôi `/v1`	Inference (đã cấp quyền cho Served Model Name của model tương ứng)	Served Model Name chính xác được cấu hình cho model đó

Lưu ý: Không dùng lẫn lộn host và giá trị model từ các dòng khác nhau. Một API key hợp lệ vẫn có thể bị từ chối nếu gửi tới host mà key đó không có quyền truy cập.

Xác thực

Gửi API key dưới dạng bearer token trong header của mọi request:

Authorization: Bearer <your-api-key>

Tạo key tại Suy luận (Inference) → Khóa API (API Keys) → Tạo khóa API (Generate API key).

Loại key	Phạm vi hiệu lực (Scope)
Platform	Mọi model đã phát hành trong Platform catalog, kể cả model được thêm sau này. Key không gọi được self-hosted model của tenant và không thể thu hẹp phạm vi cho từng model riêng lẻ.
Inference	Áp dụng cho các Served Model Name của những model được chọn khi tạo key. Một bản replacement trong cùng tenant tiếp tục dùng một trong các Served Model Name đó sẽ dùng chung quyền truy cập. Các Served Model Name khác và catalog dùng chung đều bị từ chối.

Sử dụng Platform key cho catalog dùng chung và Inference key (được gán với đúng các Served Model Name cần thiết) cho self-hosted models. Xóa model không thu hồi (revoke) key; hãy chủ động thu hồi credential khi không còn muốn cấp quyền cho các Served Model Name đó.

Secret chỉ hiển thị một lần khi tạo key. Vì vậy, hãy dùng key riêng có thời hạn cho từng ứng dụng và môi trường, lưu key trong secret store phía server hoặc biến môi trường được bảo vệ, và tuyệt đối không gửi key cho bộ phận hỗ trợ.

Thao tác thu hồi key có hiệu lực ngay lập tức và không thể hoàn tác. Để rotate key: hãy tạo key thay thế trước → cập nhật cấu hình secret của ứng dụng → gửi thử request không chứa dữ liệu nhạy cảm để xác minh → sau đó thu hồi key cũ.

Tên model

Giao diện Console là nguồn chuẩn xác nhất để lấy chuỗi định danh gửi vào trường model:

Platform catalog: Mở Suy luận → Mô hình nền tảng (Platform Models), mở rộng dòng tương ứng và sao chép giá trị JSON model từ Lệnh gọi cURL của dòng đó. Không thay thế bằng giá trị ở cột ID mô hình công khai (Public model ID), vì cột đó là định danh dùng cho catalog và tính cước (billing identity), còn khi định tuyến, hệ thống dùng giá trị model trong lệnh cURL mẫu.
Self-hosted model: Mở trang chi tiết của model trong Suy luận → Mô hình tự lưu trữ (Self-hosted Models) rồi sao chép đúng Served Model Name. Tab Sao chép cURL (Copy as cURL) sẽ tự động ghép giá trị này với đúng endpoint và đường dẫn tương ứng.

Lưu ý: Catalog host hiện chưa mở endpoint GET /v1/models; đường dẫn này sẽ trả về lỗi 404. Hãy tìm danh sách Platform model trực tiếp trong mục Suy luận → Mô hình nền tảng trên Console.

Chat completions

Gửi POST /v1/chat/completions tới base URL đã chọn:

{
  "model": "<model-value-from-generated-curl>",
  "messages": [
    { "role": "user", "content": "Xin chào" }
  ],
  "max_tokens": 512,
  "temperature": 0.7,
  "stream": false
}

Response Chat Completions ở chế độ non-streaming chứa mảng choices; câu trả lời cuối (nếu có) nằm ở choices[0].message.content:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Xin chào!"
      }
    }
  ]
}

Response 2xx vẫn có thể không có câu trả lời cuối khi model chỉ trả về phần reasoning. Hãy tách bạch thành công ở tầng truyền tải/API với thành công ở tầng ứng dụng (đã có câu trả lời cuối), và kiểm tra toàn bộ response trước khi quyết định thử lại. Các trường khác trong response có thể thay đổi tùy thuộc vào model và engine phục vụ bên dưới; đừng để logic ứng dụng phụ thuộc vào các trường không có trong tài liệu.

Đặt stream thành true để nhận response dạng server-sent events. Nếu stream đã trả về dữ liệu rồi mới lỗi, đừng tự động gửi lại toàn bộ request, vì gửi lại có thể làm trùng tác vụ hoặc output.

Lỗi và thử lại

Mã trạng thái	Ý nghĩa	Hành động khuyến nghị
Validation `4xx`	Request body chứa dữ liệu không được hỗ trợ hoặc định dạng không hợp lệ	Sửa lại request; không thử lại nguyên trạng
`401`	Thiếu thông tin xác thực hoặc header `Authorization` sai định dạng	Gửi kèm header `Authorization: Bearer <key>`
`403`	Credential bị từ chối do sai loại key, sai tenant, hết hạn, key đã bị thu hồi, ngoài phạm vi Served Model Name, hoặc sai host/model	Kiểm tra lại cả bộ ba base URL + loại key + model; không thử lại nguyên trạng
`404`	Đường dẫn URL hoặc route không tồn tại trên hệ thống	Kiểm tra và sửa lại URL hoặc path; không xem đây là lỗi tạm thời của model
`429`	Request đã xác thực nhưng vượt giới hạn tần suất (rate limit)	Thử lại có giới hạn, kèm exponential backoff và jitter
`503`	Hệ thống phục vụ tạm thời không khả dụng	Thử lại có giới hạn; kiểm tra trạng thái sức khỏe (health) của model nếu lỗi kéo dài

GPU quota trong mục Hạn mức (Quotas) là giới hạn tiếp nhận (admission limit) ở control plane, áp dụng cho các tài nguyên dùng GPU. Còn lỗi 429 ở data plane là phản hồi riêng về tần suất request, không phải dấu hiệu cho thấy bạn cần thêm GPU quota.

Thông tin cần cung cấp khi yêu cầu hỗ trợ

Khi liên hệ hỗ trợ, hãy cung cấp: serving surface, endpoint, tên model, mốc thời gian UTC (timestamp), mã trạng thái HTTP và định danh request (request identifier) nếu response có trả về. Tuyệt đối không gửi kèm API key hoặc prompt chứa dữ liệu nhạy cảm.

Trước
Bắt đầu nhanh Tiếp
Tổng quan Self-hosted models