API tương thích với OpenAI trả về 401/403 — những điểm dễ sai ở base_url và header

Mục đích cốt lõi của API tương thích với OpenAI là SDK hoạt động ngay — vì vậy khi nhận 401, lỗi gần như luôn nằm ở hai dòng bạn đã thay đổi: base_url và api_key. Dưới đây là các dạng lỗi theo đúng thứ tự chúng thường xảy ra.

Lỗi

phản hồi (HTTP 401)

{
  "error": {
    "type": "invalid_api_key",
    "message": "Invalid or missing API key.",
    "code": "invalid_api_key"
  }
}

Tổng quan nguyên nhân và cách khắc phục

Nguyên nhân	Cách khắc phục
base_url thiếu hậu tố /v1 (hoặc bị lặp)	Hầu hết gateway yêu cầu chính xác https://host/v1 — SDK tự thêm /chat/completions.
Key từ host khác	Các key sk-… chỉ xác thực với dịch vụ đã cấp chúng; hãy kiểm tra tiền tố ↔ host.
Proxy doanh nghiệp / WAF loại bỏ Authorization header	Kiểm tra từ một mạng sạch; cấu hình proxy để chuyển tiếp Authorization.
Biến môi trường OPENAI_API_KEY ghi đè key bạn chỉ định	SDK mặc định đọc biến môi trường — trong một số thiết lập, biến cũ sẽ âm thầm được ưu tiên; hãy truyền api_key một cách rõ ràng.

Xác minh URL chính xác mà SDK đang gọi

In client.base_url và gọi GET /v1/models — endpoint đã xác thực rẻ nhất. Nếu /models hoạt động, xác thực là ổn và lỗi nằm ở nơi khác:

check.py

from openai import OpenAI

client = OpenAI(
    base_url="https://api.kunavo.com/v1",   # exactly one /v1
    api_key="sk-kn-...",                 # explicit beats env vars
)
print(client.base_url)
print([m.id for m in client.models.list().data][:5])

Dùng Curl với cùng host để loại trừ SDK

Nếu curl với Authorization: Bearer hoạt động còn SDK thì không, hãy so sánh request thực tế của SDK (đặt OPENAI_LOG=debug) — chín trên mười lần là proxy hoặc biến môi trường đã viết lại một giá trị nào đó.

Nếu bạn gọi qua Kunavo

Endpoint của Kunavo tuân thủ nghiêm ngặt hình dạng OpenAI tại https://api.kunavo.com/v1 với xác thực Bearer, và GET /v1/models hoạt động như phép kiểm tra xác thực. Nếu mã của bạn đang chạy với api.openai.com, đổi base_url sang Kunavo là thay đổi duy nhất — cùng SDK, cùng định dạng truyền tải, một key cho Claude, GPT và các model đa phương tiện.

Câu hỏi thường gặp

401 và 403 trên gateway — khác nhau thế nào?

401 = thông tin xác thực không được chấp nhận (thiếu key hoặc key không hợp lệ). 403 = key hợp lệ nhưng không được phép thực hiện thao tác đó (key bị vô hiệu hóa, tài khoản bị đình chỉ, model không được cấp quyền). Hãy đọc nội dung lỗi — API tương thích đặt lý do trong error.message.

Tại sao mã của tôi chạy cục bộ nhưng lại 401 trong CI?

CI là một môi trường khác: secret chưa được thiết lập, được thiết lập cho dịch vụ khác hoặc proxy loại bỏ header. Ghi log repr(key[:12]) và base_url bên trong CI để xem thực tế đang được gửi đi.

Hướng dẫn liên quan

Hướng dẫn API tương thích OpenAI — từ endpoint cục bộ của Ollama đến các mô hình frontier lưu trữ

Thông tin chi tiết hơn về ý nghĩa lỗi có trong tài liệu tham chiếu lỗi; bạn chỉ mất một phút để lấy khóa qua đăng ký và hướng dẫn xác thực.