Responses API và Chat Completions khác nhau ra sao: hướng dẫn chuyển đổi (2026)

OpenAI khuyến nghị mọi dự án mới dùng Responses API, đồng thời khẳng định Chat Completions vẫn được hỗ trợ. Hai endpoint sẽ cùng tồn tại lâu dài, nhưng cấu trúc trường, quản lý state và hệ thống tool đều khác nhau. Bài viết tách khác biệt thành 4 chiều, chỉ ra code cần thay khi chuyển đổi, và kết thúc bằng bảng ra quyết định — mọi ví dụ chạy được trực tiếp trên endpoint của EXAIV

Định nghĩa: Responses API là giao diện hợp nhất của OpenAI ra đời sau Chat Completions: input là mảng input, output là danh sách các mục output có kiểu rõ ràng, trạng thái hội thoại được lưu phía server theo mặc định (store), và có sẵn hosted tools như web search, file search, code interpreter. Chat Completions là giao thức không trạng thái: mỗi request mang toàn bộ lịch sử messages và client tự quản lý context.

Một bảng thấy hết khác biệt cốt lõi

So sánh code: cùng một việc, hai hình dạng

Chat Completions (endpoint EXAIV /api/ai/v1/chat/completions):

curl https://exaiv.com/api/ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "user", "content": "Giải thích AI gateway là gì trong một câu." }
    ]
  }'

Responses API (endpoint EXAIV /api/ai/v1/responses):

curl https://exaiv.com/api/ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-6-sol",
    "input": "Giải thích AI gateway là gì trong một câu."
  }'

Ở tầng SDK: client.chat.completions.create(...) thành client.responses.create(...); đọc kết quả từ completion.choices[0].message.content thành response.output_text. Tài liệu đầy đủ: Chat Completions và Responses

Chuyển đổi trong bốn bước

1. messages → input: request thuần văn bản truyền chuỗi; request có lịch sử đổi tên mảng messages thành input, giữ nguyên role/content
2. Đổi đường đọc kết quả: choices[0].message.content → duyệt output lọc type === "message", hoặc dùng trường tiện ích output_text
3. Chuyển system prompt sang instructions: tin nhắn role: "system" của Chat có tham số riêng cấp cao nhất trong Responses
4. Viết lại định nghĩa tool: hai phiên bản giống nhưng không identical — soát từng trường. Hosted tools của Responses (web_search…) bật bằng tên, không cần tự viết vòng orchestration

Chọn bên nào, theo tình huống

EXAIV cung cấp cả hai endpoint chung một API key, nên không phải chọn bên vĩnh viễn: traffic hiện có giữ Chat Completions, tính năng mới dùng Responses, và đổi mô hình nền từ trang mô hình

Tại sao có hai interface

Bối cảnh tiến hóa giúp ra quyết định dễ hơn. Chat Completions là interface thời kỳ đầu của OpenAI; nhờ cấu trúc đơn giản và dùng được xuyên nhà cung cấp, nó trở thành chuẩn de facto mà cả ngành học theo — gần như mọi nhà cung cấp mô hình hôm nay đều có endpoint kiểu messages. Responses API là thiết kế lại của OpenAI cho kỷ nguyên agent: việc "mô hình có thể phải làm nhiều việc" (gọi tool, tra cứu, chạy code) trở thành công dân hạng nhất ngay trong tầng interface, đưa quản lý state và thực thi tool về phía server. Hai interface nhắm hai tình huống khác nhau — đó chính là lý do chúng cùng tồn tại.

Bảng ánh xạ tham số tra nhanh

Những tương ứng bạn dùng nhiều nhất khi chuyển đổi:

Trường chính xác nằm ở tài liệu tham khảo; khi chuyển đổi hãy soát từng trường một.

Chuyên sâu về state: store và previous_response_id

Đây là khác biệt triết học sâu nhất giữa hai thế hệ. Chat Completions giả định "server không nhớ gì": mỗi lượt bạn gửi lại toàn bộ lịch sử, việc quản lý context window và chi phí nằm ở client. Responses API lưu hội thoại phía server theo mặc định (store: true); lượt sau chỉ cần tham chiếu previous_response_id, server tiếp tục với đầy đủ hội thoại và tool context.

Hệ quả thực tế cho lập trình viên:

• Ít code hơn: các module tự giữ mảng messages, cắt lịch sử, nén context có thể xóa đi
• Ít token hơn: server tái sử dụng context sẵn có, chi phí gửi lại biến mất
• Lưu ý tuân thủ: dữ liệu hội thoại nằm phía server; nhóm có yêu cầu data-residency có thể đặt store: false, đổi lại quay về chế độ gửi đầy đủ mỗi lượt

Năm bẫy hay gặp khi chuyển đổi

1. Kết quả rỗng: chưa đổi đường đọc — nội dung giờ nằm trong output chứ không phải choices[0].message.content
2. Tool gọi âm thầm thất bại: định nghĩa tools hai thế hệ khác nhau; sao chép nguyên xi sẽ fail lặng lẽ — phải soát từng trường
3. Parser SSE gãy: loại event hoàn toàn khác; logic delta không áp được lên response.output_text.delta
4. Lỗi nhiều ứng viên: tham số n đã bị bỏ; logic phụ thuộc phải viết lại hoặc ở lại Chat
5. State lộ dữ liệu: store mặc định bật, dữ liệu test sẽ được lưu — tình huống nhạy cảm dữ liệu hãy tắt rõ ràng

FAQ

Chuyển streaming, từng event một

Tên event là nơi tốn nhiều thời gian chuyển đổi nhất. Bản đồ nhanh:

Hai khác biệt cấu trúc cần thấm: delta phía Chat là các mảnh vô danh do bạn tự ghép, trong khi event Responses gọi tên thứ nó mang; và trong Responses, một lượt nhiều tool là một vòng đời request chứ không phải nhiều lượt request/response. Parser SSE, logic retry và xử lý timeout đều phải viết lại theo tên event mới — đây là phầnmigration luôn tốn hơn dự tính.

Dùng Responses qua gateway

Ba điều đáng biết khi endpoint bị proxy:

• Hosted tools chạy thượng nguồn: web search, code interpreter chạy phía OpenAI; gateway chuyển tiếp request và stream kết quả về nguyên vẹn
• State phía server vẫn ở thượng nguồn: previous_response_id tham chiếu state lưu phía OpenAI; gateway chuyển tiếp trong suốt
• Key và thanh toán là của gateway: một key EXAIV dùng cho cả hai endpoint, tính tiền theo model và token bất kể endpoint — giá live tại trang giá

Checklist trước khi chuyển

Năm câu hỏi theo thứ tự — dừng ở câu đầu tiên trả lời "chưa" và sửa tầng đó trước:

1. Request văn bản thuần chạy được trên endpoint mới chưa (không tool, không streaming)?
2. Đường đọc kết quả trả về text thật (không phải undefined)?
3. Định nghĩa tool parse không lỗi schema?
4. Một vòng tool đầy đủ hoàn tất chưa (gọi → chạy → tiếp)?
5. Streaming render trọn vẹn đầu-cuối với tên event mới chưa?

Hai loại system prompt cần biết thêm

Bổ sung cho checklist chuyển đổi, hai tình huống hay bị bỏ sót:

Reasoning tokens. Phía Responses, các reasoning item là output hạng nhất có thể nối tiếp qua các lượt. Nếu chuyển đổi mà không tính đến điều này, tác vụ nhiều bước sẽ có vẻ "quên cách suy luận" — vì ở Chat Completions, reasoning bị vứt bỏ giữa các lần gọi. Nếu ứng dụng của bạn làm việc nhiều bước phức tạp, đây là chỗ cảm nhận rõ nhất sự khác biệt.

Cách xử lý kết quả hosted tool. Ở Chat Completions, bạn là người viết vòng lặp: gọi, thực thi, gửi lại. Ở Responses, một lượt nhiều tool là một vòng đời — kết quả đến như các item trong output. Những UI giả định một câu trả lời mỗi request cần được cập nhật để render nhiều output item.

FAQ

FAQ

Đọc thêm

• Chat Completions API reference
• Responses API reference
• Anthropic Messages API reference