Hướng dẫn API tương thích OpenAI: đổi Base URL
Tìm hiểu phạm vi tương thích OpenAI, cách chuyển ứng dụng khách hiện có sang Modelflare và những ranh giới cần xác minh trước khi đưa lưu lượng production vào.

API tương thích OpenAI cho phép ứng dụng khách hiện có giữ nguyên header xác thực, cấu trúc yêu cầu JSON và cách xử lý streaming quen thuộc trong khi gửi lưu lượng đến một gateway khác. Thay đổi có thể chỉ gồm việc đổi Base URL và khóa API, nhưng tương thích vẫn là một hợp đồng giao thức—không phải cam kết rằng mọi mô hình đều hỗ trợ mọi endpoint hoặc mọi trường riêng của nhà cung cấp.
Hướng dẫn này trình bày lộ trình chuyển đổi an toàn cho ứng dụng, script và công cụ AI vốn đã dùng API theo kiểu OpenAI.
Tương thích OpenAI thực sự bao gồm những gì
Những phần dễ tái sử dụng nhất của hợp đồng gồm:
- Xác thực bằng Bearer token qua header Authorization.
- Yêu cầu và phản hồi JSON trên các endpoint có phiên bản /v1.
- Các endpoint phổ biến như /v1/models, /v1/chat/completions và /v1/responses.
- Server-Sent Events cho các yêu cầu streaming được hỗ trợ.
- Các trường yêu cầu quen thuộc như model, messages, input, stream và định nghĩa công cụ khi giao thức đã chọn hỗ trợ.
Tương thích không có nghĩa là một mô hình có thể chuyển tự do giữa Chat Completions và Responses. Một mô hình có thể chỉ được cung cấp qua một giao thức đã xác minh. Các trường suy luận, tìm kiếm hoặc đa phương thức riêng của nhà cung cấp cũng có thể cần được chuyển tiếp nguyên trạng thay vì để gateway chuyển đổi.
Hãy coi danh mục trực tiếp Mô hình & bảng giá là nguồn thông tin chuẩn cho mô hình, nhóm và định dạng API bạn định sử dụng.
Chuẩn bị chuyển đổi
Trước khi sửa mã ứng dụng:
- Tạo một khóa riêng trong Khóa API thay vì dùng lại khóa cá nhân hoặc khóa của một tích hợp không liên quan.
- Chọn nhóm mô hình chính có quyền truy cập mô hình cần dùng.
- Chỉ thêm các nhóm dự phòng theo thứ tự khi chúng cũng hỗ trợ mô hình đó và phù hợp với cùng chính sách chi phí và độ ổn định.
- Ghi lại endpoint hiện tại, ID mô hình, cài đặt streaming và cách dùng công cụ để so sánh hành vi trước và sau khi chuyển.
Base URL chuẩn tương thích OpenAI của Modelflare là:
https://modelflare.dev/v1
Phần lớn SDK yêu cầu Base URL kết thúc ở /v1 rồi tự nối thêm /chat/completions hoặc /responses. Hãy kiểm tra tài liệu của ứng dụng khách trước khi thêm một hậu tố endpoint thứ hai.
Xác minh xác thực và quyền truy cập mô hình trước
Lưu khóa trong biến môi trường thay vì trong mã nguồn:
export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'
Sau đó, xác nhận rằng khóa có thể liệt kê các mô hình khả dụng:
curl -sS https://modelflare.dev/v1/models \
-H "Authorization: Bearer $MODELFLARE_API_KEY"
Phản hồi thành công chứng minh tên máy chủ, đường kết nối TLS và khóa đều hợp lệ. Điều này chưa chứng minh một định dạng yêu cầu cụ thể hợp lệ với mọi mô hình được trả về, vì vậy bước kiểm tra tiếp theo phải dùng đúng endpoint dự định.
Gửi một yêu cầu bằng giao thức dự định
Với mô hình Chat Completions được ghi là tương thích với định dạng đó:
curl -sS https://modelflare.dev/v1/chat/completions \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_CHAT_MODEL",
"messages": [
{"role": "user", "content": "Reply with the active model name."}
],
"stream": false
}'
Với mô hình lập trình tương thích Responses:
curl -sS https://modelflare.dev/v1/responses \
-H "Authorization: Bearer $MODELFLARE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-sol",
"input": "Reply with the active model name.",
"stream": false
}'
Hãy dùng chính xác ID mô hình hiển thị trong danh mục trực tiếp. Kết quả model_not_found thường có nghĩa là khóa hoặc nhóm đã chọn không thể truy cập mô hình đó, chứ đổi chữ hoa, chữ thường sẽ không khắc phục được yêu cầu.
Kiểm tra streaming riêng
Yêu cầu không streaming thành công vẫn chưa đủ với ứng dụng phụ thuộc vào streaming. Hãy lặp lại yêu cầu với "stream": true, xác nhận các event đến dần dần và bảo đảm ứng dụng khách không buffer toàn bộ phản hồi rồi mới hiển thị.
Khi chẩn đoán một stream chậm, hãy tách riêng:
- thời gian xác thực và chọn tuyến;
- thời gian đến khi nhận header phản hồi từ nhà cung cấp dịch vụ;
- thời gian đến nội dung hoặc delta công cụ hữu ích đầu tiên;
- tốc độ tạo nội dung sau khi đầu ra hiển thị bắt đầu.
Nhật ký sử dụng của Modelflare lưu metadata thời gian theo từng yêu cầu cho mục đích này mà không lưu prompt, nội dung phản hồi, nội dung yêu cầu thô, khóa API, email hay địa chỉ IP dạng văn bản thuần.
Danh sách kiểm tra khi chuyển sang production
- Lưu khóa API trong kho bí mật hoặc biến môi trường.
- Cố định Base URL là https://modelflare.dev/v1.
- Dùng mô hình hỗ trợ rõ ràng endpoint đã chọn.
- Kiểm tra độc lập chế độ không streaming và streaming.
- Kiểm tra công cụ, đầu ra có cấu trúc, tùy chọn suy luận và đầu vào đa phương thức nếu ứng dụng sử dụng chúng.
- Giữ nguyên các giá trị 0 hoặc false được đặt rõ ràng khi chúng mang ý nghĩa trong yêu cầu của ứng dụng khách.
- Đặt thời gian chờ của ứng dụng khách theo tác vụ thực tế thay vì theo một prompt kiểm tra tình trạng ngắn.
- Sau khi chuyển, xem lại trạng thái, độ trễ, lượng token, nhóm đã chọn và chi phí trong nhật ký sử dụng.
Khi ranh giới giao thức đã được xác minh, ứng dụng khách thường có thể giữ nguyên vòng đời yêu cầu hiện có, còn Modelflare cung cấp quyền truy cập mô hình, chính sách định tuyến và khả năng quan sát từng yêu cầu phía sau endpoint tương thích.
Để hiểu lớp vận hành phía sau endpoint đó, hãy đọc API gateway cho AI là gì?. Nếu ứng dụng khách có thể dùng nhiều hơn một định dạng OpenAI, hãy so sánh Responses API hay Chat Completions trước khi đổi đường dẫn.