URL cơ sở API OpenAI (2026): Endpoint trực tiếp và tương thích

URL cơ sở API OpenAI (2026): Endpoint trực tiếp và tương thích

Trả lời nhanh: URL cơ sở API OpenAI chính thức là https://api.openai.com/v1. Dùng URL này làm base_url hoặc baseURL của SDK, sau đó để SDK tự thêm đường dẫn tài nguyên. Các endpoint đầy đủ phổ biến là https://api.openai.com/v1/responses và https://api.openai.com/v1/chat/completions.

Đối với cổng tương thích OpenAI của Flatkey, hãy dùng https://router.flatkey.ai/v1 làm URL cơ sở. Endpoint chat-completions tương ứng là https://router.flatkey.ai/v1/chat/completions. Không dán toàn bộ đường dẫn /chat/completions vào trường SDK chỉ mong đợi URL cơ sở.

Bảng URL cơ sở API OpenAI

URL cơ sở và endpoint: điểm khác biệt

Một URL cơ sở là tiền tố dùng chung được cấu hình một lần trong SDK. Một endpoint là đường dẫn hoàn chỉnh cho một thao tác API. Việc nhầm lẫn giữa chúng gây ra các lỗi tích hợp phổ biến nhất:

• 404 Not Found: bạn đã cung cấp sai đường dẫn hoặc lặp lại /v1.
• 401 Unauthorized: khóa không thuộc về URL cơ sở mà bạn đang gọi.
• /v1/v1/...: cả URL cơ sở đã cấu hình và mã máy khách đều thêm /v1.
• .../chat/completions/chat/completions: một endpoint đầy đủ được truyền vào vị trí SDK chỉ mong đợi URL cơ sở.

Dùng một nguồn duy nhất làm chuẩn cho URL cơ sở, lưu khóa trong biến môi trường, và chạy một yêu cầu nhỏ tới /models hoặc chat trước khi chuyển lưu lượng production.

Cổng API tương thích OpenAI thay đổi điều gì

Thay đổi cốt lõi nằm ở vận hành, không phải ở khái niệm.

Đó là lý do ngay từ đầu các nhóm tìm kiếm một openai compatible api gateway. Họ không yêu cầu một định dạng prompt mới. Họ muốn giảm rủi ro phải viết lại.

Dùng danh sách kiểm tra di chuyển này trước khi thay đổi production

Cách an toàn nhất để áp dụng một openai compatible api gateway là xem nó như một thay đổi tích hợp có kiểm soát, không phải một dự án trừu tượng hóa bao trùm.

1. Liệt kê chính xác các endpoint OpenAI bạn đang dùng hiện nay. Hầu hết nhóm nghĩ rằng họ dùng “API OpenAI”, trong khi thực tế chỉ dùng một tập con nhỏ hơn như chat completions, responses, embeddings hoặc tạo ảnh.
2. Xác nhận các lệnh gọi nào phải giữ nguyên trong mã ứng dụng. Điều này giúp phạm vi luôn thực tế và bảo vệ tuyên bố “di chuyển tối thiểu”.
3. Kiểm tra xem SDK hiện tại của bạn đã hỗ trợ URL cơ sở tùy chỉnh chưa. Các máy khách OpenAI Python và Node chính thức hiện tại đều có hỗ trợ.
4. Trước tiên chọn một quy trình staging. Bắt đầu với tuyến đã phù hợp với hình dạng yêu cầu OpenAI tiêu chuẩn.
5. Xác minh trực tiếp các mô hình đích trước khi triển khai. Đừng dựa vào ảnh chụp màn hình cũ hoặc các giả định về danh mục đã lỗi thời.
6. Ghi lại quy tắc dự phòng. Người rà soát cần biết liệu tuyến có thể chuyển mô hình, thất bại an toàn hay xếp hàng hay không.
7. Phê duyệt lưu ý về khả năng tương thích. Câu chữ đã công bố nên ghi “OpenAI-compatible” cho bề mặt yêu cầu được hỗ trợ, không phải “hoàn toàn giống OpenAI.”

Danh sách kiểm tra này là điều khiến một openai compatible api gateway trở nên đáng tin cậy khi rà soát cho production.

Ví dụ mã thay đổi tối thiểu

Các SDK OpenAI chính thức hiện tại đã có tài liệu về hỗ trợ URL cơ sở tùy chỉnh. Đây là lý do về mặt cơ chế khiến một openai compatible api gateway có thể là một lần di chuyển ít trở ngại khi cổng duy trì hình dạng yêu cầu theo kiểu OpenAI mà bạn đang dùng.

Ví dụ Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-fk-your-flatkey-key",
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Return a one-line health check."},
    ],
)

print(response.choices[0].message.content)

Ví dụ Node

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-5.4-mini",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Return a one-line health check." },
  ],
});

console.log(response.choices[0].message.content);

Ví dụ cURL

curl -X POST "https://router.flatkey.ai/v1/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      { "role": "user", "content": "Return a one-line health check." }
    ]
  }'

Đối với nhiều nhóm, đây là bằng chứng đầu tiên cho thấy một cổng API tương thích OpenAI không nhất thiết đồng nghĩa với việc phải viết lại client. Ràng buộc quan trọng là quy trình làm việc bạn chọn phải phù hợp với bề mặt yêu cầu được hỗ trợ.

Cần xác minh gì trước khi nói quá trình di chuyển là “thay thế trực tiếp”

Đây là điểm mà hầu hết các trang về cổng API tương thích OpenAI trở nên thiếu chặt chẽ. “Thay thế trực tiếp” là khái niệm quá rộng nếu bạn không xác định ranh giới.

Hãy sử dụng bảng này khi rà soát:

Một cổng API tương thích OpenAI có giá trị khi các kiểm tra này được thông qua với ít trở ngại hơn so với các đợt di chuyển nhà cung cấp riêng lẻ.

Trình tự triển khai thực tế

Đây là lộ trình triển khai gọn gàng nhất cho một cổng API tương thích OpenAI khi bạn muốn thay đổi mã ở mức tối thiểu:

1. Kiểm kê đường dẫn gọi hiện tại. Ghi lại phiên bản SDK hiện tại, nhóm endpoint, ID mô hình, cài đặt streaming và các giả định về thử lại.
2. Thay đổi một base URL trong môi trường staging. Trước tiên hãy giữ nguyên mẫu client. Đừng gộp việc này với các thay đổi không liên quan về prompt hoặc mô hình.
3. Giữ một mô hình đã được phê duyệt cho lần kiểm thử đầu tiên. Tiêu chí thành công đầu tiên là khả năng tương thích truyền tải, không phải phạm vi bao phủ mô hình rộng.
4. Thực hiện kiểm tra hình dạng phản hồi và lỗi. So sánh đầu ra, mã trạng thái, kỳ vọng về độ trễ và hành vi ghi log.
5. Rà soát chính sách định tuyến mô hình. Quyết định xem tuyến được cố định vào một mô hình, có thể chuyển dự phòng sang một lớp tương đương, hay phải đóng khi có lỗi.
6. Chỉ mở rộng sau khi xác nhận catalog đang hoạt động. Vào ngày 15 tháng 7 năm 2026, nguồn cấp dữ liệu giá công khai của Flatkey hiển thị tổng cộng 170 dòng và 95 dòng khả dụng, nhưng việc triển khai production vẫn cần xác thực chính xác mô hình vào ngày bạn phát hành.

Trình tự đó biến một cổng API tương thích OpenAI thành một lớp kiểm soát di chuyển thay vì một điểm chưa rõ khác trong tích hợp.

Điểm khác biệt so với di chuyển trực tiếp sang nhà cung cấp

Tài liệu của các nhà cung cấp đã cho thấy khả năng tương thích theo kiểu OpenAI đang trở nên phổ biến. Google ghi nhận quyền truy cập Gemini thông qua các thư viện OpenAI. DeepSeek ghi nhận khả năng tương thích với OpenAI và Anthropic. Nhưng mỗi nhà cung cấp vẫn có khóa, base URL và ranh giới vận hành riêng.

Đó là khoảng trống mà một cổng API tương thích OpenAI giải quyết. Thay vì hướng dẫn từng nhóm thiết lập riêng theo từng nhà cung cấp mới, bạn có thể tập trung hóa bề mặt di chuyển và chuyển công việc rà soát sang phê duyệt mô hình, khả năng quan sát và chính sách định tuyến mô hình.

Điều này cũng giải thích vì sao thông điệp hiện tại của Flatkey mạnh hơn câu “nó hoạt động với OpenAI SDK.” Lợi ích quan trọng hơn là một cổng API tương thích OpenAI có thể hợp nhất quyền truy cập và quy trình rà soát mà không buộc phải viết lại ứng dụng ngay lập tức.

Cách diễn đạt về tuân thủ mà người rà soát có thể phê duyệt

Hãy sử dụng cách diễn đạt như sau trong lần rà soát cuối trước khi xuất bản:

Tránh cách diễn đạt như sau trừ khi người đánh giá có thể chứng minh điều đó:

Những lưu ý này khiến câu chuyện về cổng API tương thích OpenAI đáng tin cậy hơn, chứ không yếu đi.

Khi nào cổng API tương thích OpenAI là lựa chọn phù hợp

Một cổng API tương thích OpenAI thường là lựa chọn phù hợp khi:

• nhóm của bạn đã dựa vào các luồng client theo kiểu OpenAI và muốn có lộ trình di chuyển ít gây gián đoạn nhất
• đã có nhiều hơn một dòng model trong phạm vi triển khai
• bạn cần một nơi duy nhất để xem xét quyền truy cập, mức sử dụng và các tuyến đã được phê duyệt
• các thay đổi model diễn ra đủ thường xuyên để biện minh cho một chính sách định tuyến model dùng chung
• bạn muốn di chuyển có kiểm soát trước khi cân nhắc các tính năng cổng chuyên sâu hơn

Nếu các điều kiện đó không đúng, thiết lập trực tiếp với nhà cung cấp vẫn có thể đơn giản hơn. Bài viết này cần trung thực về sự đánh đổi đó.

Các nhóm AWS: URL cơ sở tương thích OpenAI của Bedrock

Nếu các model của bạn chạy trên AWS, Amazon Bedrock cung cấp URL cơ sở tương thích OpenAI riêng, https://bedrock-runtime.{region}.amazonaws.com/openai/v1, được xác thực bằng khóa API Bedrock. Hướng dẫn API tương thích OpenAI của Amazon Bedrock của chúng tôi đề cập đến endpoint, khóa, ID model và hạn chế của /models.

Kết luận

Giá trị của một cổng API tương thích OpenAI không phải là tạo ra một mẫu API mới. Giá trị nằm ở việc cho phép các nhóm duy trì một tích hợp quen thuộc theo kiểu OpenAI, đồng thời đưa quyền truy cập, phê duyệt model và kiểm soát triển khai vào sau một lớp duy nhất có thể xem xét.

Đối với Flatkey, tuyên bố mạnh nhất có thể đánh giá rất đơn giản: giữ nguyên mẫu client bạn đang sử dụng, thay đổi URL cơ sở thành https://router.flatkey.ai/v1, xác thực chính xác quy trình được hỗ trợ và phê duyệt chính sách định tuyến model trước khi mở rộng lưu lượng. Đó là danh sách kiểm tra di chuyển mà các nhà phát triển thực sự cần.