Tích hợp OpenAI API chỉ cần bốn thứ: một tài khoản đăng nhập được, một API Key còn dùng được, một dự án đã bật thanh toán, cùng Base URL chính xác và một lần gọi thành công. Nghe đơn giản, nhưng thứ thường làm các đội mới bị kẹt không phải là mã nguồn, mà là cấu trúc tài khoản, phương thức thanh toán và cách ghép địa chỉ.

Bài viết đi theo đúng thứ tự thao tác: tài khoản và dự án, tạo khóa, nạp tiền, cài SDK, gọi Responses API lần đầu, xem mức sử dụng, xử lý lỗi 401 và 429, cuối cùng là chuyển Base URL sang cổng tương thích OpenAI. Ví dụ trong bài chủ yếu dùng Responses API; với công cụ cũ chỉ hỗ trợ Chat Completions, có thể thay giao diện theo cùng cách.

Lưu ý: OpenAI, ChatGPT và GPT là nhãn hiệu của OpenAI. Bài viết dựa trên hành vi giao diện công khai tính đến tháng 10 năm 2026; tên mô hình, hạn mức và giá có thể thay đổi, vui lòng đối chiếu bảng giá mô hình và tài liệu chính thức.

1. Tài khoản, tổ chức và dự án là gì

Nền tảng OpenAI có ít nhất ba lớp, và trộn lẫn chúng là nguồn lỗi phổ biến nhất:

  • Tài khoản: thông tin đăng nhập, quyết định ai có thể vào bảng điều khiển;
  • Tổ chức: đơn vị sở hữu hóa đơn và mức sử dụng, thường dùng để quản lý cộng tác trong đội;
  • Dự án: đơn vị tách biệt khóa, mức sử dụng và quyền hạn, nên chia theo môi trường hoặc mảng kinh doanh.

Một hiểu nhầm phổ biến là coi gói đăng ký ChatGPT là số dư API. Hai thứ này tách biệt: gói đăng ký cho quyền dùng sản phẩm trò chuyện, còn API tính phí theo lượt gọi thực tế. Trước khi tích hợp, đội ngũ nên xác định ai phụ trách tài khoản, ai phụ trách thanh toán, ai giữ quyền quản trị, để sau này thay người vẫn tìm được khóa thuộc về đâu.

2. Thứ tự tạo API Key

Làm theo các bước sau, không nhảy bước:

  1. Đăng nhập bảng điều khiển API bằng tài khoản quản trị, xác nhận đang ở đúng tổ chức.
  2. Tạo mới hoặc chọn một dự án trong tổ chức, tách theo "phát triển / kiểm thử / sản xuất".
  3. Vào trang API Keys của dự án, tạo khóa mới.
  4. Đặt tên khóa thể hiện rõ mục đích, ví dụ "san-xuat-bot-cham-soc".
  5. Sao chép ngay khóa đầy đủ, lưu vào trình quản lý mật khẩu hoặc kho bí mật của nền tảng triển khai.
  6. Thiết lập quyền, ngân sách hoặc hạn mức cho dự án nếu cần, rồi lưu.

Khóa đầy đủ thường chỉ hiển thị một lần khi tạo. Trang chỉ còn vài ký tự đầu và cuối là bình thường; đừng mong sao chép lại sau đó. Nếu mất, hãy tạo khóa mới và vô hiệu hóa khóa cũ, không cố khôi phục.

3. Nạp tiền, hóa đơn và hạn mức

API dùng trả trước hay trả sau tùy loại tài khoản và khu vực; căn cứ vào bảng điều khiển. Trước khi bật, chú ý ba điểm:

  1. Phương thức thanh toán có hỗ trợ thẻ hoặc kênh của bạn không;
  2. Chu kỳ hóa đơn và cách nhận hóa đơn;
  3. Có thể đặt nhắc nhở ngân sách và hạn mức cứng cho dự án không.

Thanh toán thất bại là vấn đề thường gặp khi tích hợp. Khi thẻ bị từ chối, trước hết kiểm tra địa chỉ thanh toán, tên chủ thẻ và phương thức xác minh, rồi liên hệ ngân hàng phát hành; đừng gửi lại nhiều lần trong thời gian ngắn vì một số hệ thống chống gian lận có thể khóa thẻ. Các đội dùng cổng thường có thể nạp bằng đồng nhân dân tệ; phí và quy tắc ghi có căn cứ theo trang giá, giá có thể điều chỉnh nên hãy xem trang trước khi đặt.

4. Cài SDK và gửi yêu cầu curl đầu tiên

Cài SDK Python chính thức:

python3 -m pip install --upgrade openai
export OPENAI_API_KEY="sk-khoa-cua-ban"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="ten-mo-hinh-copy-tu-trang-gia-hoac-tai-lieu"

Gọi Responses API bằng curl để xác nhận địa chỉ, khóa và mạng đều thông:

curl -sS "$OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "input": "Giải thích bằng một câu thế nào là cổng API."
  }'

Đừng viết tên mô hình theo trí nhớ; hãy sao chép tên đang dùng từ trang giá hoặc tài liệu chính thức và lưu vào biến OPENAI_MODEL. Trả về 200 và nội dung phản hồi có đầu ra nghĩa là đường kết nối đã thông; trả về 401 thì xem khóa trước, 404 thì xem Base URL và tên mô hình.

5. Lần gọi Python đầu tiên

Đoạn mã dưới gửi một yêu cầu tối thiểu qua Responses API và in kết quả văn bản:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)

resp = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="Giới thiệu giới hạn năng lực của bạn trong ba câu.",
)

print(resp.output_text)

Nếu framework chỉ hỗ trợ Chat Completions, đổi lời gọi thành client.chat.completions.create(...) và đặt tin nhắn trong messages. Hai giao diện có đường dẫn khác nhau; trộn lẫn là nguyên nhân phổ biến của lỗi 404.

6. Hiểu mức sử dụng và hóa đơn

Trang Usage trong bảng điều khiển thường hiển thị mức tiêu thụ theo ba chiều: dự án, mô hình và thời gian, đồng thời tách đầu vào với đầu ra. Giai đoạn đầu nên xem mỗi ngày, tập trung xác nhận:

  • Dự án nào đang tiêu thụ;
  • Đầu vào và đầu ra chiếm bao nhiêu;
  • Có lần thử lại thất bại bất thường không;
  • Nhắc nhở ngân sách có hiệu lực không.

ID yêu cầu trong phản hồi cần được lưu vào nhật ký. Khi có tranh chấp hóa đơn hoặc sự cố, ID yêu cầu là tư liệu đầu tiên để nhà cung cấp định vị vấn đề. Đội ngũ cũng nên ghi lại mối liên hệ giữa người dùng, mô-đun chức năng và ID yêu cầu ở phía ứng dụng; nếu không, hóa đơn chỉ cho thấy tổng số mà không quy được về đâu.

7. Xử lý lỗi 401 và 429

401 nghĩa là danh tính không được chấp nhận. Kiểm tra lần lượt: tiêu đề yêu cầu có Bearer không; khóa có thừa dấu cách hoặc xuống dòng không; khóa đã bị xóa hoặc dự án đã bị vô hiệu hóa chưa; có phải đang gửi khóa của cổng đến địa chỉ chính thức không. Trước khi đổi khóa, xác nhận yêu cầu thực sự đi đến đâu, nếu không có thể công vô ích.

429 có hai nghĩa: giới hạn tốc độ và hết số dư. Xem mã lỗi và tiêu đề phản hồi, đừng vội giảm tốc toàn bộ. insufficient_quota thường chỉ số dư hoặc hạn mức, cần nạp tiền hoặc điều chỉnh hạn mức dự án; lỗi tốc độ mới phù hợp với lùi theo cấp số nhân. Thử lại chỉ có ý nghĩa với 429, 5xx và lỗi mạng; thử lại 400, 401, 403, 404 chỉ làm mất hạn mức. Quy trình khắc phục đầy đủ hơn có trong tài liệu lỗi OpenAI API; giá và mô hình hiện có xem tại bảng giá mô hình.

8. Chọn kết nối trực tiếp hay cổng tương thích

Tiêu chí Kết nối trực tiếp chính thức Cổng tương thích OpenAI
Địa chỉ https://api.openai.com/v1 Base URL do cổng cung cấp, thường cũng kết thúc bằng /v1
Tài khoản và thanh toán Tài khoản chính thức, theo phương thức chính thức hỗ trợ Đăng ký tài khoản trên trang, hỗ trợ nạp bằng nhân dân tệ và hóa đơn
Mạng Phụ thuộc mạng cục bộ và tuyến xuyên biên giới Thường có điểm truy cập trong nước
Phạm vi mô hình Mô hình của OpenAI Có thể cung cấp thêm mô hình nhiều hãng, theo trang giá
Tính phí Hóa đơn chính thức Số dư và nhật ký sử dụng trên trang
Xử lý sự cố Kênh hỗ trợ chính thức Cổng kiểm tra phía thượng nguồn, người dùng giữ ID yêu cầu
Phù hợp Chỉ dùng OpenAI, đã có kênh thanh toán hợp lệ Đội trong nước, nhiều mô hình, muốn hóa đơn thống nhất

Khi chọn, đừng chỉ nhìn đơn giá. Thanh toán có thuận không, ai xử lý khi có sự cố, có chuyển mô hình bất cứ lúc nào không — đều ảnh hưởng chi phí dài hạn. Giá thay đổi, luôn lấy trang giá làm căn cứ.

9. Chuyển sang cổng tương thích: chỉ đổi Base URL

Chi phí chuyển đổi thường thấp hơn tưởng tượng vì cổng tương thích giữ nguyên định dạng yêu cầu. Thứ tự:

  1. Đăng ký tài khoản cổng và tạo khóa tại trang đăng ký.
  2. Đổi OPENAI_BASE_URL sang địa chỉ cổng, giữ /v1.
  3. Đổi khóa sang khóa của cổng, không trộn hai bộ khóa.
  4. Sao chép tên mô hình từ trang giá của cổng, đừng dùng tên chính thức rồi hy vọng trùng.
  5. Gọi /v1/models và một yêu cầu tối thiểu trước, rồi mới chuyển lưu lượng sản xuất.
  6. Giữ tuyến chính thức hoặc dự phòng làm phương án hạ cấp.

"Tương thích OpenAI" nghĩa là định dạng yêu cầu và phản hồi tương thích, không có nghĩa mọi tính năng mở rộng đều giống hệt. Tệp, xử lý hàng loạt, gọi công cụ và các giao diện nâng cao có được hỗ trợ hay không phải xem tài liệu cổng từng mục, đừng mặc định tất cả đều dùng được. Chi tiết phạm vi tương thích có thể tham khảo tài liệu về API tương thích OpenAI.

10. An toàn khóa và kiểm tra trước khi lên tuyến

Rò rỉ khóa dẫn đến chi phí trực tiếp. Yêu cầu tối thiểu:

  • Khóa chỉ đặt trong biến môi trường phía máy chủ hoặc dịch vụ quản lý bí mật, không viết vào mã giao diện, không đưa vào Git;
  • Tách khóa theo môi trường, kiểm thử và sản xuất không dùng chung;
  • Ghi rõ người phụ trách và mục đích cho từng khóa, vô hiệu hóa kịp thời khi nghỉ việc hoặc đổi dự án;
  • Không in khóa đầy đủ trong nhật ký, chỉ giữ bốn ký tự cuối;
  • Luân chuyển định kỳ, thu hồi ngay khi phát hiện gọi bất thường.

Kiểm tra từng mục trước khi lên tuyến:

  • [ ] Tài khoản, tổ chức, dự án rõ ràng;
  • [ ] Phương thức thanh toán dùng được, đã đặt nhắc nhở ngân sách;
  • [ ] Khóa lưu trong biến môi trường hoặc kho bí mật;
  • [ ] Base URL chỉ còn một /v1;
  • [ ] Yêu cầu tối thiểu trả về 200, nội dung bình thường;
  • [ ] Đã cấu hình lùi 429 và thử lại 5xx;
  • [ ] Nhật ký sử dụng có ID yêu cầu, mô hình và thời gian xử lý;
  • [ ] Đã diễn tập quy trình chuyển tuyến dự phòng và vô hiệu hóa khóa.

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

API Key và gói đăng ký ChatGPT có phải một thứ?

Không. Gói đăng ký và API tính phí riêng; API Key chỉ được tạo và quản lý trên nền tảng API. Khi hoàn ứng cho đội, cần phân biệt hai khoản chi.

Vì sao tạo xong không thấy khóa đầy đủ?

Khóa đầy đủ thường chỉ hiển thị một lần khi tạo; nền tảng chỉ giữ một phần ký tự để nhận diện. Nếu mất, hãy tạo khóa mới và vô hiệu hóa khóa cũ.

Base URL nên ghi đến đâu?

Ghi đến tên miền cộng /v1, không kèm /chat/completions hay /responses. Đường dẫn do SDK hoặc yêu cầu tự ghép; thêm một đoạn là lỗi 404.

Một khóa dùng cho nhiều dự án được không?

Về kỹ thuật là được, về quản lý thì không nên. Tách khóa theo dự án hoặc môi trường để kiểm soát quyền, định vị mức dùng và thu hẹp ảnh hưởng khi rò rỉ.

Đội trong nước có nhất thiết phải dùng cổng?

Không nhất thiết. Tùy kênh thanh toán, chất lượng mạng, yêu cầu tuân thủ và nhu cầu nhiều mô hình. Đội chỉ dùng OpenAI, đã có thanh toán và mạng ổn định có thể nối trực tiếp; đội cần thanh toán bằng nhân dân tệ và đầu mối thống nhất có thể cân nhắc chuyển sang cổng tương thích.

Bước tiếp theo

Hãy chạy thông yêu cầu tối thiểu trước, rồi mới tích hợp nghiệp vụ. Nếu cần nạp bằng nhân dân tệ và đầu mối đa mô hình thống nhất, có thể bắt đầu từ đăng ký ZSQH AI Gateway; mô hình và giá căn cứ theo bảng giá mô hình.

Đọc thêm: