Hướng dẫn này sẽ đưa bạn qua việc sử dụng API Phản hồi (Responses API) của OpenAI từ đầu đến cuối: khi hoàn thành, bạn sẽ có thể gửi yêu cầu đến POST /v1/responses, đọc kết quả đầu ra lồng nhau mà nó trả về, bật các công cụ tích hợp, duy trì trạng thái cuộc hội thoại qua các lần gọi và xác minh toàn bộ hợp đồng bên trong Apidog. Responses API là giao diện mới hơn của OpenAI để tạo ra đầu ra từ mô hình, và hướng dẫn Responses chính thức giải thích lý do OpenAI hiện hướng các dự án mới đến giao diện này. Nếu bạn đã từng thử nghiệm với endpoint cũ hơn, bạn có thể tái sử dụng hầu hết các thiết lập đó, tương tự như quy trình trong hướng dẫn kiểm thử ChatGPT API của chúng tôi.
Bạn cần chuẩn bị gì trước tiên
Trước khi gửi yêu cầu, hãy đảm bảo bạn có một vài thứ sau:
- Một khóa OpenAI API có quyền truy cập vào một mô hình đa năng hiện tại. Hãy giữ khóa này trong một biến môi trường, không dán vào một lệnh hoặc tệp chia sẻ.
- Một tên mô hình mà tài khoản của bạn thực sự có thể gọi. Thay vì mã hóa cứng một cái, hãy kiểm tra danh sách mô hình trong bảng điều khiển OpenAI của bạn và xác nhận nó với endpoint.
- Một cách để gửi các yêu cầu HTTP thô và kiểm tra JSON trả về. Một terminal với
curlsẽ hoạt động tốt cho lần gọi đầu tiên, và Apidog là công cụ bạn sẽ sử dụng để xác nhận và tạo mock cho phản hồi sau này.
Cũng hữu ích khi biết endpoint hoạt động như thế nào trước khi bạn gọi nó. Responses API chỉ cung cấp một endpoint duy nhất là POST /v1/responses. Bạn gửi một tên mô hình và một input, và bạn nhận lại một đối tượng phản hồi có thể chứa văn bản thuần túy, các lệnh gọi hàm và kết quả từ các công cụ được OpenAI lưu trữ như tìm kiếm web hoặc tìm kiếm tệp. Một lần gọi có thể chạy toàn bộ một lượt đa bước: mô hình quyết định tìm kiếm web, đọc kết quả, sau đó viết câu trả lời, và phản hồi ghi lại từng bước nó đã thực hiện.
Hai điều làm cho nó khác biệt so với một endpoint văn bản thuần túy. Thứ nhất, nó có thể chạy các công cụ tích hợp ở phía máy chủ, vì vậy bạn không cần phải tự mình kết nối công cụ tìm kiếm hoặc sandbox của riêng mình. Thứ hai, nó có trạng thái theo mặc định. Mỗi phản hồi đều có một id, và bạn có thể chuyển id đó cho yêu cầu tiếp theo để OpenAI giữ lịch sử cuộc trò chuyện cho bạn. OpenAI mô tả Responses API là sự phát triển của Chat Completions và khuyến nghị nó cho các dự án mới, tổng hợp các bài học từ phiên bản beta của Assistants API. Vì vậy, thay vì ba mô hình tư duy, bạn chỉ cần một.
Tìm hiểu sự khác biệt so với Chat Completions
Nếu bạn đã sử dụng POST /v1/chat/completions, sự thay đổi chủ yếu nằm ở hình dạng và trạng thái. Chat Completions nhận một mảng messages và trả về choices. Bạn tự quản lý toàn bộ bản ghi, gửi lại mọi lượt trước đó trong mỗi lần gọi. Các công cụ là thứ bạn tự triển khai ở phía mình.
Responses API nhận một input (một chuỗi hoặc một danh sách các mục đã được định kiểu) và trả về một output (một danh sách các mục đã được định kiểu). Nó có thể lưu trữ lượt cho bạn và chạy các công cụ được lưu trữ mà không cần thêm cấu hình.
Đây là so sánh thực tế:
| Khía cạnh | Chat Completions | Responses API |
|---|---|---|
| Endpoint | POST /v1/chat/completions |
POST /v1/responses |
| Nội dung yêu cầu (Request body) | Mảng messages |
input (chuỗi hoặc các mục) + instructions |
| Dạng đầu ra (Output shape) | choices[].message |
Danh sách output các mục đã được định kiểu |
| Trạng thái cuộc hội thoại (Conversation state) | Bạn gửi lại toàn bộ lịch sử | store + previous_response_id |
| Các công cụ tích hợp sẵn | Bạn tự xây dựng | web_search, file_search, code_interpreter, và nhiều hơn nữa |
| Trạng thái | Được hỗ trợ, chưa thông báo ngừng hỗ trợ | Được khuyến nghị cho các dự án mới |
Chat Completions sẽ không bị loại bỏ. OpenAI cho biết nó vẫn được hỗ trợ, và bạn có thể di chuyển từng luồng người dùng một thay vì viết lại mọi thứ cùng lúc. Assistants API là cái đang có thời hạn: OpenAI đã ngừng hỗ trợ nó vào ngày 26 tháng 8 năm 2025, với tuyên bố sẽ ngừng hoạt động vào ngày 26 tháng 8 năm 2026, vì vậy công việc tác nhân mới nên bắt đầu trên Responses.
Thực hiện yêu cầu đầu tiên của bạn
Đây là một cuộc gọi tối thiểu. Thay đổi tên mô hình thành bất kỳ mô hình nào tài khoản của bạn có quyền truy cập và giữ khóa của bạn khỏi chính lệnh.
curl https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": "Write one sentence describing what an API mock server does.",
"instructions": "You are a concise technical writer. No marketing language.",
"store": true
}'
Bạn truyền ba thứ quan trọng ở đây: model, input (lời nhắc của bạn), và instructions (hướng dẫn cấp hệ thống). Đặt store thành true cho OpenAI biết để lưu phản hồi để bạn có thể tiếp tục chuỗi sau này.
Đọc phản hồi
Một phản hồi được cắt bớt trông như thế này:
{
"id": "resp_abc123",
"object": "response",
"status": "completed",
"model": "gpt-5.5",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "A mock server returns predefined API responses so clients can be developed and tested before the real backend exists."
}
]
}
],
"usage": {
"input_tokens": 28,
"output_tokens": 24,
"total_tokens": 52
}
}
Lưu ý cấu trúc, vì đây là phần khiến mọi người bối rối. Văn bản bạn muốn nằm ở output[0].content[0].text, không phải ở một trường cấp cao nhất. Các SDK chính thức bổ sung một trình truy cập tiện lợi output_text tổng hợp tất cả các mục văn bản thành một chuỗi, nhưng thuộc tính đó là một trình trợ giúp SDK, không phải là một phần của JSON HTTP thô. Khi bạn gọi trực tiếp endpoint, bạn đọc đường dẫn lồng nhau. id cấp cao nhất là thứ bạn sẽ sử dụng lại cho trạng thái, và usage.total_tokens cho bạn biết chi phí của cuộc gọi.
Thêm các công cụ tích hợp sẵn
Tính năng nổi bật là OpenAI chạy một số công cụ cho bạn. Bạn liệt kê chúng trong một mảng tools và mô hình sẽ quyết định khi nào gọi chúng. Các loại tích hợp sẵn đã được xác minh bao gồm:
web_searchđể tra cứu internet trực tiếp với trích dẫn (web_search_previewcũ hơn vẫn hoạt động cho các tích hợp cũ nhưng thiếu các điều khiển mới hơn).file_searchđể truy xuất trên các tệp bạn đã tải lên.code_interpreterđể chạy và phân tích mã trong một sandbox.computer_useđể điều khiển giao diện máy tính.image_generationđể tạo hình ảnh ngay lập tức.
Bật một công cụ chỉ là một bổ sung nhỏ vào nội dung:
{
"model": "gpt-5.5",
"input": "What changed in the latest OpenAPI release? Cite sources.",
"tools": [{ "type": "web_search" }]
}
Khi mô hình sử dụng một công cụ, mảng output sẽ có thêm các mục ghi lại bước đó, chẳng hạn như một mục web_search_call cùng với message cuối cùng. Điều này hữu ích sau này: bạn có thể kiểm tra xem một công cụ có thực sự đã được kích hoạt hay không, chứ không chỉ là văn bản được trả về.
Tiếp tục cuộc hội thoại qua các lần gọi
Trạng thái hoạt động thông qua hai tham số. store mặc định là true, có nghĩa là OpenAI lưu đối tượng phản hồi (được giữ lại trong 30 ngày theo mặc định) và trả về một id. Truyền id đó làm previous_response_id trong lần gọi tiếp theo của bạn và mô hình sẽ tiếp tục chuỗi mà không cần bạn gửi lại bản ghi:
{
"model": "gpt-5.5",
"input": "Now rewrite that for a non-technical audience.",
"previous_response_id": "resp_abc123"
}
Nếu bạn muốn giữ mọi thứ không trạng thái, hoặc bạn có yêu cầu không lưu trữ dữ liệu, hãy đặt store thành false và tự quản lý ngữ cảnh. Đối với các luồng thoại và âm thanh thời gian thực, độ trễ thấp, OpenAI sử dụng một giao diện khác; hướng dẫn GPT realtime API của chúng tôi đề cập đến trường hợp đó. Và nếu bạn đang điều phối các tác nhân đa bước trên tất cả những điều này, các mẫu sẽ khớp với OpenAI Agents SDK.
Cách kiểm thử trong Apidog
Apidog là một nền tảng kiểm thử, thiết kế và mock API. Nó không phải là một OpenAI SDK hay một thư viện mã, vì vậy bạn sẽ không viết Python với nó. Thay vào đó, bạn sẽ: xây dựng yêu cầu HTTP thô đến /v1/responses, gửi nó và viết các xác nhận (assertions) trên JSON trả về. Đó chính xác là loại kiểm tra hợp đồng giúp phát hiện một tích hợp bị lỗi trước khi người dùng của bạn phát hiện ra.
Dưới đây là cách thiết lập, từng bước một.
Lưu khóa trong một biến môi trường
Trong Apidog, tạo một môi trường (ví dụ, “OpenAI Prod”) và thêm một biến như OPENAI_API_KEY. Giữ giá trị trong môi trường, không phải trong yêu cầu, để bí mật không bao giờ được đưa vào một bộ sưu tập được chia sẻ. Sau đó, xây dựng một yêu cầu POST mới đến https://api.openai.com/v1/responses và thêm tiêu đề Authorization: Bearer {{OPENAI_API_KEY}}. Apidog sẽ thay thế biến này tại thời điểm gửi.
Đặt nội dung là JSON và dán yêu cầu từ trước đó. Nhấn gửi. Bạn sẽ thấy đối tượng phản hồi đầy đủ, được định dạng, với mảng output lồng nhau.
Xác nhận các trường phản hồi
Một phản hồi 200 thành công không phải là bằng chứng cho thấy phản hồi có hình dạng mà ứng dụng của bạn mong đợi. Thêm các xác nhận để lỗi hồi quy được thông báo rõ ràng. Các kiểm tra hữu ích đối với phản hồi /v1/responses:
statusbằngcompleted.output[0].content[0].texttồn tại và không rỗng.usage.total_tokenslớn hơn 0.- Khi bạn gửi
tools, một mục trongoutputcótypebằngweb_search_call.
Trình tạo xác nhận trực quan của Apidog cho phép bạn nhắm mục tiêu các đường dẫn JSON đó mà không cần viết các tập lệnh kiểm thử, và mẫu test case API của chúng tôi cho thấy cách cấu trúc các kiểm tra như thế này. Lưu yêu cầu vào một bộ sưu tập và nó trở thành một bài kiểm thử lặp lại mà bạn có thể chạy trong CI.
Mock phản hồi để phát triển ngoại tuyến
Các cuộc gọi OpenAI tốn tiền và cần truy cập mạng, điều này gây khó khăn khi bạn đang xây dựng giao diện người dùng tiêu thụ phản hồi hoặc chạy các bài kiểm thử trong một pipeline không nên gọi một API trả phí. Tính năng mock của Apidog giải quyết vấn đề đó. Lưu một payload /v1/responses đại diện dưới dạng mock, trỏ ứng dụng của bạn đến URL mock của Apidog, và frontend của bạn sẽ nhận được hình dạng JSON chính xác mà không tốn token nào. Khi endpoint thực thay đổi, bạn cập nhật một mock thay vì phải khắc phục lỗi trên mọi bài kiểm thử. Giải thích về API mock của chúng tôi hướng dẫn cách tiếp cận chung.
Sự phân chia này rất quan trọng. Bạn kiểm thử chống lại endpoint trực tiếp để xác minh hợp đồng của OpenAI, và bạn mock nó để phát triển nhanh chóng, ngoại tuyến, xác định. Cả hai đều chạy từ cùng một dự án Apidog.
Các câu hỏi thường gặp
Responses API có thay thế Chat Completions không?
Không phải theo cách bắt buộc. OpenAI gọi Responses là sự phát triển của Chat Completions và khuyến nghị nó cho các dự án mới, nhưng Chat Completions vẫn được hỗ trợ mà chưa có thông báo ngày ngừng hoạt động. Bạn có thể di chuyển từng luồng một. Assistants API là cái đang được ngừng hoạt động, với ngày kết thúc vào năm 2026.
Sự khác biệt giữa store và previous_response_id là gì?
store kiểm soát xem OpenAI có lưu đối tượng phản hồi hay không (mặc định là true và giữ lại trong 30 ngày). previous_response_id là cách bạn liên kết một yêu cầu mới với một yêu cầu đã được lưu trữ để mô hình tiếp tục cuộc trò chuyện ở phía máy chủ. Bạn sử dụng chúng cùng nhau cho các chuỗi có trạng thái, và tắt store khi bạn muốn hành vi không trạng thái.
Những mô hình nào hỗ trợ Responses API?
Các mô hình đa năng hiện tại của OpenAI được thiết kế để hoạt động với Responses API, nhưng khả dụng tùy thuộc vào tài khoản của bạn và mô hình bạn chọn. Thay vì mã hóa cứng một tên mô hình, hãy kiểm tra danh sách mô hình trong bảng điều khiển OpenAI của bạn, sau đó xác nhận nó với endpoint. Gửi một yêu cầu nhanh qua Apidog và đọc trường model trong phản hồi là một cách nhanh chóng để xác minh những gì khóa của bạn thực sự có thể gọi.
Tôi có thể kiểm thử các công cụ tích hợp sẵn mà không cần viết mã không?
Có. Thêm một mảng tools vào nội dung JSON trong Apidog, gửi yêu cầu và xác nhận rằng mục gọi công cụ khớp (như web_search_call) xuất hiện trong mảng output. Bạn đang kiểm tra hành vi của OpenAI qua HTTP, vì vậy không cần SDK. Để kiểm thử các cuộc gọi công cụ tác nhân rộng hơn, hãy xem cách tạo bộ sưu tập kiểm thử API từ các thông số kỹ thuật OpenAPI.
Tổng kết
Giờ đây bạn đã nắm được toàn bộ quy trình: một endpoint duy nhất, POST /v1/responses, xử lý văn bản, các công cụ được lưu trữ, và trạng thái cuộc trò chuyện phía máy chủ. Gửi yêu cầu, đọc output lồng nhau, thêm mảng tools khi bạn cần tìm kiếm hoặc thực thi mã, và liên kết previous_response_id để duy trì một chuỗi hội thoại. Vì cấu trúc này khác với Chat Completions, bước an toàn nhất là tự mình xác minh hợp đồng thay vì tin tưởng vào ký ức của bạn về API cũ hơn.
Đó là nơi Apidog phát huy tác dụng. Xây dựng yêu cầu, lưu khóa của bạn dưới dạng biến môi trường, xác nhận các trường output lồng nhau, và mock phản hồi cho công việc ngoại tuyến, tất cả trong một dự án. Tải xuống Apidog và trỏ một bài kiểm thử vào /v1/responses để xem chính xác những gì tích hợp của bạn nhận được. Bạn có thể thực hiện toàn bộ thiết lập trong Apidog mà không cần viết một dòng mã kiểm thử nào.