Hướng dẫn sử dụng API phản hồi OpenAI

Hướng dẫn này giúp bạn tích hợp OpenAI Responses API từ đầu đến cuối: gửi request đến POST /v1/responses, đọc cấu trúc output lồng nhau, bật built-in tools, duy trì trạng thái hội thoại bằng previous_response_id, và kiểm thử hợp đồng API trong Apidog. Responses API là giao diện mới hơn của OpenAI để tạo đầu ra từ mô hình; hướng dẫn Responses chính thức giải thích vì sao OpenAI khuyến nghị dùng giao diện này cho dự án mới. Nếu bạn đã từng dùng endpoint cũ, bạn có thể tái sử dụng nhiều thiết lập tương tự như trong hướng dẫn kiểm thử ChatGPT API với Apidog.

Dùng thử Apidog ngay hôm nay

Chuẩn bị trước khi gọi Responses API

Bạn cần có:

• Một OpenAI API key có quyền truy cập vào mô hình bạn muốn dùng. Lưu key trong biến môi trường, không hard-code vào code hoặc file chia sẻ.
• Tên mô hình mà tài khoản của bạn có thể gọi. Hãy kiểm tra trong dashboard OpenAI thay vì giả định.
• Công cụ gửi HTTP request và đọc JSON response. Bạn có thể dùng curl cho lần gọi đầu tiên, sau đó dùng Apidog để kiểm thử, viết assertion và mock response.

Responses API dùng một endpoint chính:

POST /v1/responses

Bạn gửi model, input, tùy chọn instructions, tools, store, và nhận lại một object response. Object này có thể chứa văn bản, tool calls, kết quả từ hosted tools như web search hoặc file search.

Điểm khác biệt quan trọng:

1. Responses API có thể chạy built-in tools phía server.
2. Responses API có state theo mặc định. Mỗi response có id, và bạn có thể truyền id đó vào request tiếp theo bằng previous_response_id.

Responses API khác gì Chat Completions?

Nếu bạn từng dùng POST /v1/chat/completions, khác biệt lớn nhất là request/response shape và cách quản lý state.

Chat Completions nhận messages[] và trả về choices[]. Bạn phải tự gửi lại lịch sử hội thoại trong mỗi request.

Responses API nhận input và trả về output[]. Nó có thể lưu trạng thái hội thoại và chạy hosted tools.

Khía cạnh	Chat Completions	Responses API
Endpoint	POST /v1/chat/completions	POST /v1/responses
Request body	messages[]	input + instructions
Output shape	choices[].message	output[] gồm các item đã định kiểu
Conversation state	Bạn tự gửi lại lịch sử	store + previous_response_id
Built-in tools	Bạn tự triển khai	web_search, file_search, code_interpreter, v.v.
Trạng thái	Vẫn được hỗ trợ	Được khuyến nghị cho dự án mới

Chat Completions chưa bị loại bỏ. OpenAI vẫn hỗ trợ endpoint này, nên bạn có thể migrate từng flow. Assistants API mới là API đang có lộ trình ngừng hoạt động: OpenAI đã ngừng hỗ trợ vào ngày 26/08/2025 và dự kiến ngừng hoạt động vào ngày 26/08/2026.

Gửi request đầu tiên

Ví dụ tối thiểu bằng curl:

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
  }'

Trong request này:

• model: tên mô hình tài khoản của bạn có quyền truy cập.
• input: nội dung người dùng gửi.
• instructions: chỉ dẫn cấp hệ thống.
• store: cho phép OpenAI lưu response để dùng tiếp trong hội thoại sau.

Nếu mô hình trong ví dụ không khả dụng với tài khoản của bạn, hãy thay bằng mô hình bạn thấy trong dashboard OpenAI.

Đọc response trả về

Response rút gọn có dạng:

{
  "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
  }
}

Phần text không nằm ở field cấp cao nhất. Với HTTP response thô, bạn cần đọc:

output[0].content[0].text

Các field cần chú ý:

• id: dùng cho request tiếp theo qua previous_response_id.
• status: trạng thái xử lý, ví dụ completed.
• output[]: danh sách item đã định kiểu, có thể gồm message hoặc tool call.
• usage.total_tokens: tổng số token đã dùng.

Một số SDK có helper như output_text, nhưng đó là tiện ích của SDK, không phải field JSON thô bắt buộc khi gọi trực tiếp HTTP endpoint.

Bật built-in tools

Responses API có thể chạy một số công cụ phía OpenAI. Bạn khai báo trong mảng tools, mô hình sẽ quyết định khi nào cần gọi.

Các tool được xác minh bao gồm:

• web_search: tìm kiếm web và trả kết quả có trích dẫn.
• file_search: truy xuất dữ liệu từ file đã tải lên.
• code_interpreter: chạy và phân tích code trong sandbox.
• computer_use: điều khiển giao diện máy tính.
• image_generation: tạo hình ảnh.

Ví dụ bật web search:

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [{ "type": "web_search" }]
}

Khi tool được gọi, output[] sẽ có thêm item tương ứng, ví dụ web_search_call, ngoài message cuối cùng. Bạn có thể dùng field này để kiểm tra tool có thật sự được kích hoạt hay không.

Tiếp tục hội thoại bằng previous_response_id

State được quản lý qua hai tham số:

• store: kiểm soát việc OpenAI lưu response. Mặc định là true, response được giữ lại trong 30 ngày.
• previous_response_id: liên kết request mới với response đã lưu.

Ví dụ request tiếp theo:

{
  "model": "gpt-5.5",
  "input": "Now rewrite that for a non-technical audience.",
  "previous_response_id": "resp_abc123"
}

Bạn không cần gửi lại toàn bộ lịch sử hội thoại. OpenAI sẽ tiếp tục từ response trước đó.

Nếu muốn stateless hoàn toàn, đặt:

{
  "store": false
}

Khi đó bạn tự quản lý context ở phía ứng dụng.

Với voice/audio realtime độ trễ thấp, OpenAI dùng giao diện khác. Xem thêm hướng dẫn GPT realtime API. Nếu bạn đang điều phối agent nhiều bước, các pattern sẽ gần với OpenAI Agents SDK.

Kiểm thử Responses API trong Apidog

Apidog là nền tảng thiết kế, kiểm thử và mock API. Với Responses API, bạn không viết SDK code trong Apidog; bạn tạo HTTP request thô đến /v1/responses, gửi request, đọc JSON response và thêm assertion.

1. Lưu API key trong environment variable

Trong Apidog:

1. Tạo environment, ví dụ OpenAI Prod.
2. Thêm biến OPENAI_API_KEY.
3. Tạo request mới:
   • Method: POST
   • URL: https://api.openai.com/v1/responses
4. Thêm header:

Authorization: Bearer {{OPENAI_API_KEY}}
Content-Type: application/json

1. Dán JSON body:

{
  "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
}

1. Gửi request và kiểm tra response.

Cách này giúp API key không bị lưu trực tiếp trong request hoặc collection được chia sẻ.

2. Thêm assertion cho response

HTTP 200 chưa đủ để chứng minh response đúng shape mà ứng dụng cần. Hãy thêm assertion cho các field quan trọng:

• status bằng completed.
• output[0].content[0].text tồn tại và không rỗng.
• usage.total_tokens lớn hơn 0.
• Khi dùng tools, output[] có item với type là web_search_call.

Ví dụ các điều kiện nên kiểm tra:

status == "completed"
output[0].content[0].text is not empty
usage.total_tokens > 0
output contains item where type == "web_search_call"

Trình tạo assertion trực quan của Apidog cho phép nhắm vào JSON path mà không cần viết test script. Nếu bạn muốn tổ chức test case rõ ràng hơn, xem mẫu test case API.

Sau khi lưu request vào collection, bạn có thể chạy lại test nhiều lần hoặc đưa vào CI.

3. Mock response để phát triển offline

Gọi OpenAI API tốn chi phí và cần kết nối mạng. Khi frontend hoặc test pipeline chỉ cần response shape ổn định, bạn có thể mock response trong Apidog.

Quy trình:

1. Gửi request thật đến /v1/responses.
2. Lưu payload response đại diện làm mock.
3. Trỏ ứng dụng hoặc frontend sang mock URL của Apidog.
4. Dùng mock để phát triển UI, parser hoặc test pipeline mà không tốn token.

Khi response shape thay đổi, bạn cập nhật mock một lần thay vì sửa nhiều test rải rác.

Xem thêm giải thích về API mock.

Cách chia tách nên dùng:

• Test với endpoint thật để xác minh hợp đồng OpenAI.
• Dùng mock để phát triển nhanh, offline và xác định.

Cả hai có thể nằm trong cùng một project Apidog.

FAQ

Responses API có thay thế Chat Completions không?

Không bắt buộc ngay lập tức. OpenAI gọi Responses API là bước phát triển của Chat Completions và khuyến nghị cho dự án mới, nhưng Chat Completions vẫn được hỗ trợ và chưa có ngày ngừng hoạt động được công bố. Bạn có thể migrate từng flow.

Assistants API là API có lộ trình ngừng hoạt động, với mốc kết thúc vào năm 2026.

store khác gì previous_response_id?

store kiểm soát việc OpenAI có lưu response hay không. Mặc định là true, với thời gian lưu mặc định 30 ngày.

previous_response_id dùng để liên kết request mới với response đã lưu, giúp mô hình tiếp tục hội thoại ở phía server.

Dùng cả hai khi bạn muốn hội thoại có state. Tắt store khi bạn muốn stateless và tự quản lý context.

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 phụ thuộc vào tài khoản và mô hình bạn chọn.

Cách kiểm tra thực tế:

1. Xem danh sách model trong dashboard OpenAI.
2. Gửi request nhanh đến /v1/responses.
3. Đọc field model trong response.
4. Nếu lỗi quyền truy cập hoặc model không tồn tại, thay bằng model khả dụng với API key của bạn.

Có thể kiểm thử built-in tools mà không viết code không?

Có. Trong Apidog, thêm tools vào JSON body:

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [{ "type": "web_search" }]
}

Sau đó thêm assertion kiểm tra output[] có item như:

{
  "type": "web_search_call"
}

Bạn đang kiểm thử qua HTTP, nên không cần SDK. Với các bộ test lớn hơn, xem cách tạo bộ sưu tập kiểm thử API từ OpenAPI specs.

Tổng kết

Responses API gom nhiều luồng vào một endpoint: POST /v1/responses. Bạn có thể gửi input, đọc output[] lồng nhau, bật hosted tools và duy trì hội thoại bằng previous_response_id.

Khi triển khai, hãy tập trung vào bốn việc:

1. Gửi request HTTP đúng shape.
2. Parse text từ output[0].content[0].text.
3. Kiểm tra tool call trong output[] khi dùng tools.
4. Viết assertion cho response contract thay vì chỉ kiểm tra status code.

Apidog giúp bạn xây dựng request, lưu API key bằng environment variable, xác nhận các field JSON lồng nhau và mock response cho phát triển offline. Tải xuống Apidog và trỏ request vào /v1/responses để kiểm tra chính xác dữ liệu mà 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 test code.