Tài liệu của OpenAI rất toàn diện. Nhưng cũng bị phân tán trên sáu tài liệu tham chiếu API khác nhau, ba hướng dẫn di chuyển và một changelog cập nhật hàng tháng.
Các bài hướng dẫn từ năm 2024 tham chiếu các model đã ngừng hoạt động và các tham số đã bị gỡ bỏ. Bạn tìm “OpenAI streaming example” và thấy bốn cách triển khai khác nhau —trong đó chỉ hai cách còn hoạt động.
Hướng dẫn này bao quát mọi tính năng chính của OpenAI API tính đến tháng 7 năm 2026, theo đúng thứ tự bạn nên học, kèm code chạy được.
Không tham số lỗi thời. Không có kiểu trốn tránh “kiểm tra tài liệu mới nhất”. Mọi ví dụ đều được kiểm thử trên API hiện tại.
Bức tranh OpenAI API năm 2026
OpenAI hiện duy trì ba API đang hoạt động, và biết nên dùng cái nào giúp tránh rất nhiều rối rắm.
Chat Completions API (/v1/chat/completions): bản cổ điển. Không trạng thái, request-response. Gửi tin nhắn, nhận completion. Hỗ trợ streaming, function calling, JSON mode và structured outputs. Đây là thứ 90% ứng dụng sử dụng. Nếu bạn không chắc dùng API nào, hãy dùng cái này.
Responses API (/v1/responses): mới hơn, có trạng thái. Duy trì trạng thái hội thoại phía máy chủ thay vì bắt bạn tự quản lý mảng tin nhắn. Hỗ trợ web search, file search và computer use như các công cụ tích hợp. Tốt hơn cho các quy trình agent phức tạp, nơi model cần điều phối nhiều công cụ qua nhiều lượt. Sự đánh đổi: kiểm soát lịch sử tin nhắn ít hơn, và API vẫn đang phát triển.
Agents SDK: bổ sung mới nhất. Một framework để xây dựng AI agent bền bỉ với guardrails tích hợp, bàn giao giữa các agent chuyên biệt và tracing. Ràng buộc hơn các API thô —bạn đánh đổi sự linh hoạt để phát triển các mẫu agent phổ biến nhanh hơn. Không trình bày chi tiết ở đây; hướng dẫn xây dựng AI agent bao quát vấn đề này một cách sâu sắc.
Đội hình model hiện tại (tháng 7 năm 2026):
| Mô hình | Input $/M | Output $/M | Context | Tốt nhất cho |
|---|---|---|---|---|
| GPT-5.5 | $5.00 | $30.00 | 1M | Năng lực tối đa, suy luận phức tạp |
| GPT-5.4 | $2.50 | $15.00 | 1M | Năng lực mạnh, giá trị tốt hơn |
| GPT-5.4 Mini | $0.75 | $4.50 | 400K | Tác vụ hằng ngày, cân bằng chi phí/chất lượng tốt |
| GPT-5.4 Nano | $0.20 | $1.25 | 128K | Tác vụ đơn giản khối lượng lớn |
| o4-mini | $1.10 | $4.40 | 200K | Toán, logic, câu đố code (chuyên suy luận) |
Xác thực. Đặt API key của bạn làm biến môi trường OPENAI_API_KEY —không bao giờ hardcode. Về quản lý key trong sản xuất, xoay vòng, phạm vi quyền và kiến trúc key ảo, xem hướng dẫn quản lý API key của chúng tôi.
Chat Completions API: nền tảng
Mọi tích hợp OpenAI đều bắt đầu từ đây.
Lệnh gọi chat cơ bản —Python:
from openai import OpenAI
client = OpenAI(
base_url="https://api.tokspan.com/v1",
api_key="ts-your-key-here"
)
response = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "system", "content": "You are a software engineer. Answer with code when appropriate."},
{"role": "user", "content": "Write a Python function to check if a string is a palindrome."}
],
temperature=0.3, # Low = deterministic, good for code
max_tokens=500, # Cap output length
top_p=0.95 # Nucleus sampling —usually leave at default
)
print(response.choices[0].message.content)Mọi tham số quan trọng:
model—dùng model nào. Trong sản xuất hãy dùng ID gắn ngày (gpt-5.5-2025-06-15), không dùng bí danh (gpt-5.5). Bí danh âm thầm nâng cấp lên snapshot mới có thể thay đổi hành vi prompt của bạn.messages—mảng các đối tượng tin nhắn vớirole(“system”, “user”, “assistant”) vàcontent. Tin nhắn system đặt hành vi. Tin nhắn user là yêu cầu. Tin nhắn assistant là phản hồi model trước đó —bao gồm chúng để duy trì ngữ cảnh hội thoại.temperature—từ 0 đến 2. Dùng 0–0.3 cho code và tác vụ thực tế. 0.7–1.0 cho chat và viết sáng tạo. 1.0 trở lên cho động não.max_tokens—giới hạn cứng cho độ dài đầu ra. Model dừng khi chạm giới hạn này, kể cả giữa câu. Đặt rộng rãi (500–4,000) cho hầu hết tác vụ.top_p—thay thế cho temperature. Thường để mặc định (1.0) và kiểm soát tính ngẫu nhiên chỉ bằng temperature.
Viết tin nhắn system cho đúng. Một tin nhắn system tốt cụ thể, không triết lý. Tệ: “Bạn là trợ lý AI hữu ích.” Tốt: “Bạn là người đánh giá code Python. Với mỗi đoạn code, hãy xác định: (1) bug tiềm ẩn, (2) vấn đề hiệu suất, (3) vi phạm phong cách. Định dạng phản hồi dạng danh sách gạch đầu dòng. Giữ mỗi gạch đầu dòng dưới 30 từ.”
Hội thoại nhiều lượt. API không trạng thái. Nó không nhớ các lệnh gọi trước của bạn.
Để có một cuộc hội thoại, bạn gửi toàn bộ lịch sử tin nhắn mỗi lần —tin nhắn system + mọi tin nhắn user và assistant trước đó + tin nhắn user mới. Khi lịch sử tiến gần giới hạn ngữ cảnh của model, hãy cắt bớt các tin nhắn cũ nhất hoặc tóm tắt chúng. Cắt bớt tốt hơn một lỗi; tóm tắt tốt hơn cắt bớt.
Streaming: phản hồi theo thời gian thực
Chế độ không streaming: người dùng chờ 3–8 giây, rồi thấy toàn bộ phản hồi một lúc. Chế độ streaming: người dùng thấy từ ngữ xuất hiện theo thời gian thực bắt đầu từ ~0.4 giây. Khác biệt về UI là khác biệt giữa “cảm giác chậm” và “cảm giác tức thì”.
Triển khai streaming trong Python:
stream = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "Explain recursion."}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)Triển khai streaming trong Node.js:
const stream = await client.chat.completions.create({
model: "gpt-5.5",
messages: [{ role: "user", content: "Explain recursion." }],
stream: true
});
for await (const chunk of stream) {
if (chunk.choices[0]?.delta?.content) {
process.stdout.write(chunk.choices[0].delta.content);
}
}Các trường hợp ngoại lệ cần xử lý: Chunk rỗng (vài chunk đầu trong stream thường không có nội dung —API vẫn đang xử lý). Mất kết nối (bọc stream trong try/except, retry với cùng tin nhắn nếu thất bại giữa chừng). Theo dõi finish reason (chunk cuối chứa finish_reason —kiểm tra nó để biết model dừng tự nhiên hay chạm giới hạn).
Function Calling: trao công cụ cho LLM của bạn
Model không thực thi code. Nó tạo JSON mô tả hàm nào cần gọi và với tham số nào. Code của bạn thực thi hàm đó.
Bạn gửi kết quả trở lại. Model dùng kết quả để tạo phản hồi cuối cùng. Đây là kiến trúc đằng sau mọi AI agent.
Ví dụ hoàn chỉnh về agent thời tiết:
import json
# Step 1: Define the tool
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city. Returns temperature in Celsius and conditions.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name, e.g. 'Tokyo'"}
},
"required": ["city"]
}
}
}]
# Step 2: User asks a question that needs the tool
response = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
tools=tools,
tool_choice="auto" # Model decides whether to use a tool
)
# Step 3: Check if model wants to call a tool
msg = response.choices[0].message
if msg.tool_calls:
tool_call = msg.tool_calls[0]
args = json.loads(tool_call.function.arguments)
# Step 4: Execute the function (in reality, call a weather API)
weather_result = get_actual_weather(args["city"])
# Step 5: Send the result back
messages = [
{"role": "user", "content": "What's the weather in Tokyo?"},
msg, # The assistant's tool_call message
{"role": "tool", "tool_call_id": tool_call.id, "content": str(weather_result)}
]
final_response = client.chat.completions.create(
model="gpt-5.5",
messages=messages
)
print(final_response.choices[0].message.content)Function calling song song. Định nghĩa nhiều công cụ. Model có thể yêu cầu vài công cụ cùng lúc nếu chúng độc lập —“lấy thời tiết ở Tokyo VÀ Osaka.” Code của bạn cần xử lý nhiều tool_calls trong phản hồi, thực thi chúng song song (asyncio.gather) và gửi tất cả kết quả về cùng nhau.
Thực hành tốt với function calling. Mô tả công cụ chính là prompt —viết rõ ràng và kèm ví dụ về thời điểm dùng từng công cụ. Ràng buộc tham số chặt chẽ —dùng enum thay vì chuỗi văn bản tự do. Hướng dẫn function calling của OpenAI trình bày chi tiết các trường hợp ngoại lệ như tool call streaming và thực thi song song.
Hãy làm cho công cụ có tính idempotent. Khi thực thi công cụ thất bại, hãy gửi thông báo lỗi trở lại cho model —nó thường có thể phục hồi bằng cách thử các tham số khác nhau.
Để so sánh function calling giữa các nhà cung cấp OpenAI, Anthropic, Google và DeepSeek —bao gồm tính năng nào sống sót qua quá trình chuyển đổi tương thích OpenAI —bài so sánh tool calling có bảng phân tích đầy đủ giữa các nhà cung cấp.
Structured Outputs: JSON được đảm bảo
JSON mode (response_format={"type": "json_object"}) gợi ý rằng bạn muốn JSON. Model thường tuân theo. Structured Outputs (response_format={"type": "json_schema", ...}) đảm bảo điều đó —việc lấy mẫu token của model bị giới hạn để chỉ tạo ra JSON hợp lệ khớp với schema của bạn.
Khi nào dùng cái nào. JSON mode: tạo prototype nhanh, công cụ nội bộ, các trường hợp bạn có thể chấp nhận JSON sai cấu trúc thỉnh thoảng. Structured Outputs: API sản xuất, tính năng hướng tới khách hàng, mọi trường hợp JSON không hợp lệ gây ra lỗi dây chuyền. Tài liệu Structured Outputs của OpenAI trình bày đầy đủ cú pháp định nghĩa schema và các model được hỗ trợ.
Định nghĩa schema —ví dụ trình phân tích CV:
response = client.chat.completions.create(
model="gpt-5.4", # Structured Outputs supported on GPT-5.4+
messages=[{"role": "user", "content": f"Extract information from this resume:\n\n{resume_text}"}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "resume_extraction",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"skills": {"type": "array", "items": {"type": "string"}},
"years_experience": {"type": "integer"},
"current_role": {"type": "string"}
},
"required": ["name", "skills", "years_experience"]
}
}
}
)
resume_data = json.loads(response.choices[0].message.content)
# Guaranteed to match your schema. No try/except json.loads needed.Checklist triển khai sản xuất
Quản lý môi trường. API key trong kho bí mật (AWS Secrets Manager, HashiCorp Vault, Doppler), không phải trong file .env. Xoay vòng key mỗi 90 ngày. Dùng key riêng cho phát triển, staging và sản xuất với giới hạn ngân sách và danh sách model cho phép khác nhau.
Xử lý lỗi cho sản xuất. Bọc mọi lệnh gọi API trong retry với backoff lũy thừa và jitter. Bật circuit breaker cho các nhà cung cấp lỗi liên tục —dừng định tuyến đến họ trong 30 giây, kiểm tra, tiếp tục nếu khỏe mạnh. Không bao giờ trả lỗi API thô cho người dùng —ánh xạ chúng thành thông báo thân thiện và ghi log chi tiết nội bộ.
Giám sát chi phí. Theo dõi chi phí theo người dùng, theo tính năng, theo model. Đặt cảnh báo bất thường ở mức 2x chi tiêu hàng ngày bình thường.
Hóa đơn $500 bất ngờ xảy ra khi không ai theo dõi. Bản tóm tắt chi phí hàng ngày chỉ mất 10 giây để đọc.
Quản lý giới hạn tốc độ. Nắm rõ giới hạn RPM và TPM của gói của bạn. Đọc header x-ratelimit-remaining-* trong mọi phản hồi. Giảm tốc độ khi còn 30%. Dừng lại ở 10%.
Để có kiến trúc giới hạn tốc độ hoàn chỉnh —từ backoff phản ứng đến điều tiết dự đoán —xem hướng dẫn xử lý giới hạn tốc độ trong sản xuất của chúng tôi.
Con đường thay thế. Một nền tảng tổng hợp xử lý xác thực, phục hồi lỗi, ghi log chi phí và quản lý giới hạn tốc độ ở cấp hạ tầng. Bạn chỉ tập trung vào logic ứng dụng.
Sự đánh đổi là ít kiểm soát hơn đối với đường đi của request. Với hầu hết đội nhóm, thời gian tiết kiệm được lớn hơn phần kiểm soát phải nhường.
Câu hỏi thường gặp
Sự khác biệt giữa GPT-5.5 và o4-mini là gì?
GPT-5.5 là model đa dụng cho chat, code, phân tích và sinh nội dung. o4-mini là model chuyên về suy luận —nó suy nghĩ lâu hơn trước khi trả lời, khiến nó mạnh hơn ở toán học, bài toán logic và suy luận hình thức, nhưng chậm hơn và đắt hơn mỗi token.
Dùng GPT-5.5 cho các tác vụ hàng ngày. Dùng o4-mini cho các tác vụ mà bình thường bạn sẽ với tay lấy máy tính hoặc một chứng minh hình thức.
Tôi có cần dùng Responses API thay vì Chat Completions không?
Chưa cần. Chat Completions ổn định, được hỗ trợ rộng rãi và xử lý 90% trường hợp sử dụng. Responses API thêm quản lý trạng thái và công cụ tích hợp (web search, file search) nhưng mới hơn và đang phát triển.
Bắt đầu với Chat Completions. Di chuyển sang Responses API khi bạn cần các tính năng cụ thể của nó.
Làm thế nào để giảm chi phí OpenAI API?
Dùng GPT-5.4 Mini ($0.75/$4.50) thay vì GPT-5.5 ($5/$30) cho các tác vụ đơn giản. Bật prompt caching —giảm 50% cho đầu vào được cache. Dùng batch API cho công việc không khẩn cấp —giảm 50% cho vòng xử lý 24 giờ.
Hoặc dùng nền tảng tổng hợp nơi giá gộp theo khối lượng và định tuyến model tự động giảm chi phí mà không cần chuyển model thủ công. Hướng dẫn chiến thuật cắt giảm hóa đơn trình bày từng chiến lược.
Tôi có thể dùng SDK OpenAI với các model không phải của OpenAI không?
Có. Hầu hết nhà cung cấp đều cung cấp endpoint tương thích OpenAI.
Đổi base_url và api_key. Code của bạn vẫn nguyên vẹn. Đây là lợi thế lớn nhất của tiêu chuẩn tương thích OpenAI —bạn không bị khóa vào một nhà cung cấp duy nhất.
Điều gì xảy ra khi OpenAI ngừng hỗ trợ một model tôi đang dùng?
OpenAI thường thông báo trước 1–3 tháng. Cố định vào ID model gắn ngày (gpt-5.5-2025-06-15), không phải bí danh (gpt-5.5), để kiểm soát thời điểm di chuyển.
Kiểm thử model thay thế bằng prompt của bạn trước ngày ngừng hỗ trợ. Cấu hình sẵn model dự phòng không phải của OpenAI để bạn không bị buộc phải di chuyển theo tiến độ của OpenAI.
OpenAI API là tiêu chuẩn ngành vì một lý do: SDK chín muồi, tài liệu toàn diện và hệ sinh thái hỗ trợ nó trước tiên. Nhưng 2026 là năm đầu tiên tiêu chuẩn đó bộc lộ sức căng —giao thức gốc của Anthropic, function calling tự động của Google và áp lực giá từ DeepSeek đều đang kéo các nhà phát triển về phía những tính năng không sống sót khi chuyển qua /v1/chat/completions. Câu hỏi đáng theo dõi: Agents SDK của OpenAI sẽ trở thành tiêu chuẩn ngành tiếp theo tái hợp nhất hệ sinh thái, hay sẽ thúc đẩy sự phân mảnh bằng cách giới thiệu các khả năng chỉ có trên hạ tầng riêng của OpenAI?
Bắt đầu viết code —làm chủ OpenAI API theo cách của bạn. Sau đó thêm Claude, Gemini và DeepSeek qua cùng một SDK khi bạn sẵn sàng —vì ván cược an toàn duy nhất trong 2026 là code chạy được trên mọi nhà cung cấp.