Hướng dẫn tích hợp OpenAI API: Khả năng tương thích Chat Completions và cấu hình khóa

I. Tổng quan

Trang web này cung cấp khả năng tích hợp tương thích với định dạng OpenAI Chat Completions (/v1/chat/completions). Đối với các mã đã chạy ổn định trong SDK chính thức của OpenAI hoặc các ứng dụng khách tương thích với OpenAI, bạn chỉ cần trỏ địa chỉ yêu cầu tới cổng OpenAI của trang web này, thay thế api_key bằng khóa sk- của hệ thống, các phương thức gọi khác vẫn giữ nguyên.

Các dòng mô hình GPT hiện có tùy thuộc vào danh sách tại trung tâm mô hình (ví dụ: gpt-5.4, gpt-5.5, gpt-5.4-mini, gpt-4o, v.v.), bạn có thể truy vấn danh sách đầy đủ và đơn giá qua GET /v1/models.

II. Địa chỉ giao diện (API)

Phương thức	Đường dẫn	Mô tả
POST	/v1/chat/completions	Hoàn thiện hội thoại (không truyền phát / truyền phát), phần thân yêu cầu tuân theo payload của OpenAI
GET	/v1/models	Danh sách mô hình và đơn giá (không cần xác thực)

Địa chỉ Gateway: https://www.relay-api.com. Để gọi các lệnh tương thích với OpenAI, vui lòng gửi yêu cầu tới POST https://www.relay-api.com/v1 và giữ nguyên đường dẫn.

III. Phương thức xác thực

Authorization: Bearer sk-khóa_của_bạn

Tạo khóa bắt đầu bằng sk- trong mục "Trung tâm người dùng → Khóa API". Sử dụng tiêu đề xác thực giống hệt với OpenAI chính thức, SDK sẽ tự động thêm tiêu đề Authorization.

IV. Bắt đầu nhanh

4.1 curl (không truyền phát)

curl -X POST https://www.relay-api.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-khóa_của_bạn" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "system", "content": "Bạn là một trợ lý hữu ích."},
      {"role": "user", "content": "Hãy giới thiệu về bản thân trong ba câu."}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

4.2 OpenAI SDK (Python)

from openai import OpenAI

client = OpenAI(
    base_url="https://www.relay-api.com/v1",
    api_key="sk-khóa_của_bạn",
)

resp = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Xin chào"}],
)
print(resp.choices[0].message.content)

Sau khi đặt base_url thành cổng OpenAI nêu trên và thay thế api_key, các phương thức gọi còn lại hoàn toàn giống với SDK chính thức.

V. Tham số yêu cầu

Trường	Loại	Bắt buộc	Mô tả
model	string	Có	Slug mô hình, ví dụ: gpt-5.4
messages	array	Có	Danh sách tin nhắn, phần tử là {role, content}; giá trị role gồm system / user / assistant
temperature	number	Không	Nhiệt độ lấy mẫu, mặc định 1.0
top_p	number	Không	Lấy mẫu hạt nhân (Nucleus sampling), mặc định 1.0
max_tokens	int	Không	Số token đầu ra tối đa
stream	bool	Không	Có truyền phát kết quả hay không, mặc định false
stop	string / array	Không	Chuỗi dừng
presence_penalty / frequency_penalty	number	Không	Hình phạt lặp lại, phạm vi -2~2

VI. Cấu trúc phản hồi

{
  "id": "chatcmpl-123456",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Xin chào! Rất vui được gặp bạn."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 12,
    "total_tokens": 30
  }
}

Trường	Mô tả
id	ID duy nhất của lần hoàn thiện này
choices[].message	Phản hồi từ trợ lý, content là nội dung văn bản
choices[].finish_reason	Lý do kết thúc: stop / length / content_filter
usage.prompt_tokens	Số token đầu vào (căn cứ tính phí)
usage.completion_tokens	Số token đầu ra (căn cứ tính phí)
usage.total_tokens	Tổng số token

VII. Đầu ra truyền phát (Streaming)

Sau khi thêm "stream": true vào phần thân yêu cầu, hệ thống sẽ trả về luồng SSE, mỗi dòng data: là một chunk:

data: {"id": "chatcmpl-123456", "object": "chat.completion.chunk", "choices": [{"index": 0, "delta": {"role": "assistant"}, "finish_reason": null}]}

data: {"id": "chatcmpl-123456", "object": "chat.completion.chunk", "choices": [{"index": 0, "delta": {"content": "Xin chào"}, "finish_reason": null}]}

data: {"id": "chatcmpl-123456", "object": "chat.completion.chunk", "choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}]}

data: [DONE]

Ứng dụng khách chỉ cần nối các choices[0].delta.content của mỗi chunk để nhận được phản hồi hoàn chỉnh; nhận [DONE] nghĩa là luồng kết thúc. Nếu đặt stream=True trong SDK OpenAI, các sự kiện này sẽ được tự động xử lý.

VIII. Mã lỗi thường gặp

Mã trạng thái HTTP	Ý nghĩa	Đề xuất xử lý
400	Tham số yêu cầu không hợp lệ (mô hình không tồn tại, messages trống...)	Kiểm tra các trường trong phần thân yêu cầu
401	Khóa API không hợp lệ hoặc bị thiếu	Kiểm tra tiêu đề Authorization và định dạng khóa
403	Khóa đã bị hủy, hết số dư, hoặc không được cấp quyền truy cập mô hình/tuyến đường này	Nạp tiền hoặc kiểm tra quyền hạn của khóa
404	Đường dẫn hoặc mô hình không tồn tại	Xác nhận lại base_url và tên mô hình
429	Kích hoạt giới hạn tốc độ (Rate limit)	Thử lại sau khi đợi theo cơ số lũy thừa
500	Lỗi nội bộ hệ thống	Thử lại sau, nếu lỗi kéo dài hãy liên hệ hỗ trợ

Phần thân phản hồi lỗi có cấu trúc thống nhất: {"code": Mã trạng thái, "message": "Mô tả lỗi", "data": null}.

IX. Ghi chú về khả năng tương thích

• Hỗ trợ SDK OpenAI (Python / Node.js, v.v.) kết nối thông qua base_url tùy chỉnh.
• Hỗ trợ các ứng dụng khách tương thích với OpenAI (LobeChat, ChatBox, NextChat, One API, v.v.) cấu hình địa chỉ API tùy chỉnh.
• Tên mô hình lấy theo slug trả về từ GET /v1/models.