Tham chiếu API

Chat-completions API 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, đồng thời API key có quyền truy cập surface đó.

Để gửi request đầu tiên theo từng bước, hãy dùng Platform quickstart 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 được host sẵn	https://catalog.onenexus-do.cloud/v1	Platform	Giá trị model chính xác trong Lệnh gọi cURL của dòng đã mở rộng
Self-hosted models của tenant	Copy tenant Endpoint hiển thị trên detail page của model rồi nối /v1	Inference authorize Served Model Name của model đã chọn	Served Model Name chính xác đã cấu hình trên model đó

Không trộn host và model value từ hai dòng khác nhau; key hợp lệ vẫn có thể bị từ chối nếu không có quyền truy cập host đó.

Authentication

Gửi key dưới dạng bearer token trong mọi request:

Authorization: Bearer <your-api-key>

Tạo key trong Khóa API → Tạo khóa API.

Loại key	Scope
Platform	Mọi model đã publish 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 scope.
Inference	Served Model Name của các model được chọn khi tạo key. Replacement trong cùng tenant tiếp tục dùng một trong các Served Model Name đó sẽ dùng chung access. Các Served Model Name khác và shared catalog đều bị từ chối.

Dùng Platform key cho shared catalog và Inference key scoped tới các Served Model Name cần thiết cho self-hosted model. Xóa model không revoke key; hãy revoke credential trực tiếp khi các Served Model Name đó không còn được authorize.

Secret chỉ hiển thị một lần, nên dùng key có thời hạn riêng cho từng application và environment, lưu trong server-side secret store hoặc environment variable được bảo vệ, và không bao giờ gửi key cho support.

Revocation có hiệu lực ngay và không thể hoàn tác. Rotate theo thứ tự: tạo key thay thế → update secret configuration của application → xác minh một request không chứa sensitive data → revoke key cũ.

Model name

Console là nguồn tin chuẩn cho string gửi trong model:

• Platform catalog: mở Mô hình nền tảng, mở rộng một dòng rồi copy JSON model value trong Lệnh gọi cURL. Không thay bằng cột ID mô hình công khai (Public model ID); đó là catalog/billing identity, còn routing dùng model value trong generated request.
• Self-hosted model: mở model rồi copy Served Model Name. Tab Sao chép cURL ghép sẵn giá trị này với endpoint và path chính xác.

Catalog host hiện chưa cung cấp GET /v1/models; path này trả về 404. Hãy tìm Platform model trong Console.

Chat completions

Gửi POST /v1/chat/completions tương đối vớ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
}

Chat Completions response không streaming có choices array; đọc final text (nếu có) tại choices[0].message.content:

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

Response 2xx có thể không có final text khi model trả reasoning nhưng không trả final answer; hãy tách transport/API success khỏi final-answer success ở application layer và kiểm tra full response trước khi quyết định retry. Các response field khác có thể thay đổi theo model và serving engine; không viết application logic phụ thuộc vào field chưa được document.

Đặt stream thành true để nhận server-sent event stream. Nếu stream đã phát data rồi mới lỗi, không tự động replay toàn bộ request; replay có thể tạo work hoặc output trùng lặp.

Error và retry

Status	Ý nghĩa	Cách xử lý
Validation 4xx	Request body chứa data không được hỗ trợ hoặc sai format	Sửa request; không retry nguyên trạng
401	Không có credential hoặc Authorization header sai format	Gửi Authorization: Bearer <key>
403	Credential bị từ chối vì loại key, tenant, thời hạn, trạng thái revoke, Served Model Name scope, host hoặc model name	Kiểm tra lại toàn bộ tuple base URL + loại key + model; không retry nguyên trạng
404	URL hoặc route không tồn tại	Sửa URL hoặc path; không coi đây là transient model error
429	Đã chạm request-rate ceiling sau authentication	Retry số lần hữu hạn với exponential backoff và jitter
503	Serving path tạm thời không khả dụng	Retry số lần hữu hạn; kiểm tra health của model nếu lỗi kéo dài

GPU quota trong Hạn mức (Quotas) là control-plane admission limit cho tài nguyên dùng GPU. Data-plane 429 là response về request rate riêng; nó không chứng minh rằng bạn cần thêm GPU quota.

Thông tin cần gửi khi support

Khi escalate, hãy gửi serving surface, endpoint, model name, UTC timestamp, HTTP status và request identifier nếu response có cung cấp. Không bao giờ gửi API key hoặc prompt có nội dung nhạy cảm.

• Khắc phục sự cố self-hosted model
• Pilot & bảo mật
• Trao đổi với kỹ sư