API tương thích OpenAI: đổi Base URL

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 JSON và cách xử lý streaming quen thuộc, dù lưu lượng được chuyển qua một gateway khác. Trong nhiều trường hợp, bạn chỉ cần đổi Base URL và khóa API. Tuy vậy, “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 trường riêng của nhà cung cấp.

Hướng dẫn này trình bày cách chuyển đổi an toàn cho ứng dụng, script và công cụ AI vốn đã sử dụng API theo kiểu OpenAI.

Tương thích OpenAI thực sự bao gồm những gì

Các phần thường có thể tái sử dụng gồm:

• xác thực 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 dưới /v1;
• những endpoint phổ biến như /v1/models, /v1/chat/completions và /v1/responses;
• Server-Sent Events cho yêu cầu streaming được hỗ trợ;
• các trường 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 một mô hình có thể chuyển tự do giữa Chat Completions và Responses. Mô hình có thể chỉ được cung cấp qua một giao thức đã xác minh. Những trường suy luận, tìm kiếm hoặc đầu vào đ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 dùng danh mục trực tiếp Mô hình & Giá làm nguồn tham chiếu cho mô hình, nhóm và định dạng API dự định sử dụng.

Chuẩn bị trước khi chuyển đổi

Trước khi sửa mã ứng dụng:

1. Tạo một khóa riêng trong Khóa API, không dùng lại khóa cá nhân hoặc khóa của tích hợp khác.
2. Chọn nhóm chính thực sự có quyền truy cập mô hình cần dùng.
3. Chỉ thêm các nhóm dự phòng theo thứ tự rõ ràng khi chúng hỗ trợ cùng mô hình và phù hợp với chính sách chi phí, độ ổn định.
4. Ghi lại endpoint hiện tại, ID mô hình chính xác, chế độ streaming và cách dùng công cụ để so sánh trước và sau khi chuyển.

Base URL chuẩn của API Modelflare tương thích OpenAI là:

https://modelflare.dev/v1

Phần lớn SDK mong Base URL kết thúc tại /v1, rồi tự nối /chat/completions hoặc /responses. Hãy kiểm tra tài liệu của ứng dụng khách để tránh lặp đường dẫn endpoint.

Xác minh khóa và quyền truy cập mô hình trước

Lưu khóa trong biến môi trường hoặc kho bí mật, không ghi vào mã nguồn:

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

Sau đó, kiểm tra xem khóa có thể liệt kê các mô hình khả dụng hay không:

curl -sS https://modelflare.dev/v1/models \
  -H "Authorization: Bearer $MODELFLARE_API_KEY"

Phản hồi thành công xác nhận tên miền, kết nối TLS và khóa hợp lệ. Điều đó chưa chứng minh mọi mô hình trả về đều chấp nhận mọi định dạng yêu cầu; bước tiếp theo phải gọi đúng endpoint sẽ dùng trong thực tế.

Gửi một yêu cầu bằng giao thức dự kiến

Với mô hình được ghi là hỗ trợ Chat Completions:

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": "Hãy trả lời bằng tên mô hình đang hoạt động."}
    ],
    "stream": false
  }'

Với mô hình lập trình hỗ trợ 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": "Hãy trả lời bằng tên mô hình đang hoạt động.",
    "stream": false
  }'

Hãy dùng đúng ID mô hình hiển thị trong danh mục. Lỗi model_not_found thường cho biết khóa hoặc nhóm không có quyền truy cập; đổi chữ hoa, chữ thường hiếm khi giải quyết được vấn đề.

Kiểm tra streaming riêng biệt

Yêu cầu không streaming thành công vẫn chưa đủ nếu ứng dụng phụ thuộc vào đầu ra tăng dần. Hãy thử lại với "stream": true, xác nhận các event đến lần lượt và bảo đảm ứng dụng khách không đợi toàn bộ phản hồi rồi mới hiển thị.

Khi chẩn đoán streaming chậm, hãy tách riêng:

• thời gian xác thực và chọn tuyến;
• thời gian chờ header phản hồi từ upstream;
• thời gian đến văn bản, suy luận hoặc event công cụ hữu ích đầu tiên;
• tốc độ sinh sau khi đầu ra bắt đầu hiển thị.

Nhật ký sử dụng Modelflare lưu các số đo này theo từng yêu cầu nhưng không lưu prompt, nội dung phản hồi, body thô, khóa API, địa chỉ email hoặc IP dạng rõ.

Danh sách kiểm tra trước khi đưa vào 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 được xác nhận hỗ trợ endpoint đã chọn.
• Kiểm tra riêng chế độ streaming và không streaming.
• Nếu ứng dụng sử dụng công cụ, đầu ra có cấu trúc, tùy chọn suy luận hoặc đầu vào đa phương thức, hãy kiểm tra từng phần.
• Giữ nguyên giá trị 0 và false khi chúng mang ý nghĩa rõ ràng.
• Đặt timeout theo khối lượng công việc thực, không dựa trên một prompt kiểm tra rất ngắn.
• Sau khi chuyển, xem lại trạng thái, độ trễ, token, nhóm thực tế 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. Phía sau cùng endpoint, Modelflare quản lý 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.