OpenAI Responses

Tạo phản hồi văn bản, hình ảnh, gọi công cụ và suy luận bằng API tương thích OpenAI Responses.

API Responses dùng Typed Items để biểu diễn thống nhất văn bản, hình ảnh, tệp, lệnh gọi công cụ và kết quả suy luận. API phù hợp với ứng dụng cần đầu vào đa phương thức, công cụ tích hợp, tương tác có trạng thái hoặc sự kiện dạng luồng có ngữ nghĩa. Các loại Item, công cụ và trường nâng cao khả dụng có thể khác nhau giữa các mô hình; căn cứ vào mô hình khả dụng cho tài khoản hiện tại và kết quả gọi thực tế.

POST/v1/responses

Tạo phản hồi của mô hình từ văn bản, hình ảnh, tệp hoặc Typed Input Items. API có thể trả về nhiều loại Output Items như tin nhắn, mục suy luận và lệnh gọi công cụ, đồng thời hỗ trợ truyền sự kiện ngữ nghĩa qua SSE.

Khả năng hỗ trợ hình ảnh, công cụ tích hợp, suy luận, liên kết trạng thái hoặc đầu ra có cấu trúc phụ thuộc vào mô hình khả dụng cho tài khoản hiện tại và kênh của nhà cung cấp. Nên hoàn thành yêu cầu văn bản tối thiểu trước, rồi bật từng trường nâng cao.

Xác thực

bearerAuth

Xác thựcBearer <token>

Sử dụng Bearer your-api-key trong Header Authorization.

Vị trí truyền: header

Nội dung yêu cầu

Responses biểu diễn đầu vào, công cụ và đầu ra bằng Typed Items. Chọn chế độ xem theo tác vụ; khả năng sử dụng trường phụ thuộc vào mô hình và kênh.

application/json

Đầu vào văn bản

Cách ngắn nhất là truyền chuỗi trực tiếp vào input; cũng có thể dùng Typed Items dạng tin nhắn.

model: ID mô hình hỗ trợ Responses và khả dụng với API Key hiện tại.
input: Chuỗi hoặc mảng Typed Input Items.
instructions: Chỉ dẫn cấp cao chỉ áp dụng cho phản hồi này.

application/json

{
  "model": "MODEL_ID",
  "input": "Hãy giới thiệu bản thân bằng ba câu."
}

Phản hồi văn bản cơ bản. input có thể là chuỗi trực tiếp hoặc Typed Input Items.

background?boolean|null

Có chạy phản hồi ở chế độ nền hay không. Khả năng sử dụng chế độ nền phụ thuộc vào mô hình, kênh và quyền của tài khoản.

Giá trị mặc địnhfalse

context_management?array<>|null

Cấu hình quản lý ngữ cảnh cho yêu cầu hiện tại, chẳng hạn nén ngữ cảnh khi đạt ngưỡng Token đã chỉ định.

conversation?string||null

Conversation chứa phản hồi này. Có thể truyền Conversation ID hoặc đối tượng chứa id; không sử dụng cùng previous_response_id.

model?string

ID mô hình văn bản Responses cần dùng. Chọn mô hình khả dụng với API Key hiện tại.

Độ dài1 <= length

input?text input|array<||||||||||||||||||||||||||||||>

Đầu vào văn bản. Có thể truyền chuỗi trực tiếp hoặc tin nhắn và Typed Items khác.

include?array<>|null

Chỉ định dữ liệu mở rộng cần đính kèm phản hồi.

instructions?string|array<||||||||||||||||||||||||||||||>|null

Tin nhắn hệ thống hoặc nhà phát triển dùng làm chỉ dẫn cấp cao cho phản hồi này. Khi dùng previous_response_id, instructions của phản hồi trước không tự động được kế thừa.

max_output_tokens?integer|null

Giới hạn Token mà phản hồi có thể tạo, bao gồm đầu ra hiển thị và Token suy luận.

max_tool_calls?integer|null

Giới hạn tổng số lần gọi công cụ tích hợp mà phản hồi này có thể xử lý, không phải giới hạn riêng cho từng loại công cụ.

Phạm vi0 <= value

metadata?|null

Thông tin khóa–giá trị đính kèm đối tượng phản hồi. Khóa tối đa 64 ký tự, giá trị tối đa 512 ký tự.

Số thuộc tínhproperties <= 16

parallel_tool_calls?boolean|null

Có cho phép mô hình thực hiện các lệnh gọi công cụ song song hay không.

Giá trị mặc địnhtrue

moderation?|null

Cấu hình kiểm duyệt đầu vào và đầu ra của phản hồi.

previous_response_id?string|null

ID duy nhất của Response trước, dùng để tiếp tục tương tác có trạng thái. Không sử dụng cùng conversation; instructions của phản hồi trước không tự động được kế thừa.

prompt?|null

Tham chiếu mẫu Prompt đã lưu và các biến của mẫu.

prompt_cache_key?string|null

Dùng để tăng tỷ lệ trúng bộ nhớ đệm prompt cho các yêu cầu tương tự và thay thế mục đích lưu đệm của user.

prompt_cache_options?|null

Cấu hình bộ nhớ đệm prompt ở cấp yêu cầu. Khối nội dung có thể dùng prompt_cache_breakpoint để đánh dấu ranh giới lưu đệm rõ ràng.

prompt_cache_retention?string|null

Đã ngừng khuyến nghị

Đã ngừng khuyến nghị; dùng prompt_cache_options.ttl. Trường này được giữ lại để tương thích với chính sách lưu bộ nhớ đệm cũ.

Giá trị được phép

"in_memory"
"24h"
null

reasoning?|null

Cấu hình mô hình suy luận. Chỉ áp dụng cho mô hình hỗ trợ khả năng này.

service_tier?string|null

Cấp dịch vụ sử dụng cho yêu cầu. Giá trị yêu cầu có thể khác giá trị thực tế trong phản hồi, chẳng hạn yêu cầu fast nhưng phản hồi trả về priority.

Giá trị mặc định"auto"

Giá trị được phép

"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
null

safety_identifier?string|null

Định danh người dùng cuối ổn định để giám sát an toàn và hành vi lạm dụng. Nên băm trước khi gửi để tránh truyền thông tin có thể nhận dạng cá nhân.

Độ dàilength <= 64

store?boolean|null

Có lưu phản hồi được tạo hay không. Việc lưu, đọc và thời gian lưu thực tế phụ thuộc vào khả năng của nền tảng.

Giá trị mặc địnhtrue

stream?boolean|null

Khi là true, trả về các sự kiện ngữ nghĩa của Responses qua Server-Sent Events.

Giá trị mặc địnhfalse

stream_options?|null

Cấu hình phản hồi dạng luồng. Chỉ sử dụng khi stream là true.

temperature?number|null

Nhiệt độ lấy mẫu. Thông thường chỉ điều chỉnh một trong hai tham số temperature hoặc top_p.

Phạm vi0 <= value <= 2

Giá trị mặc định1

text?

tool_choice?||||||||

Điều khiển việc mô hình có chọn công cụ hay không và cách chọn.

tools?array<|||||||||||||>

Công cụ tích hợp hoặc hàm tùy chỉnh mà mô hình có thể sử dụng. Phạm vi hỗ trợ thực tế phụ thuộc vào mô hình và kênh.

top_logprobs?integer|null

Số Token ứng viên có xác suất cao nhất được trả về tại mỗi vị trí Token đầu ra, từ 0 đến 20.

Phạm vi0 <= value <= 20

top_p?number|null

Khối xác suất cho lấy mẫu nucleus. Thông thường chỉ điều chỉnh một trong hai tham số top_p hoặc temperature.

Phạm vi0 <= value <= 1

Giá trị mặc định1

truncation?string|null

Đã ngừng khuyến nghị

Chính sách cắt ngắn khi ngữ cảnh vượt cửa sổ. disabled khiến yêu cầu vượt giới hạn thất bại.

Giá trị mặc định"disabled"

Giá trị được phép

"auto"
"disabled"
null

user?string

Đã ngừng khuyến nghị

Đã ngừng khuyến nghị. Dùng safety_identifier cho định danh an toàn và prompt_cache_key để nhóm bộ nhớ đệm.

Khả năng hỗ trợ công cụ, trạng thái, suy luận và đa phương thức trong Responses có thể khác nhau theo mô hình và kênh của nhà cung cấp. Nên hoàn thành yêu cầu văn bản tối thiểu trước, rồi bật từng trường nâng cao.

Nội dung phản hồi

`application/json`

curl -X POST "https://example.com/v1/responses" \  -H "Content-Type: application/json" \  -d '{    "model": "MODEL_ID",    "input": "Hãy kể một câu chuyện trước giờ ngủ về kỳ lân bằng ba câu."  }'

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "MODEL_ID",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Dưới ánh trăng, một chú kỳ lân phát hiện lối đi bí mật dẫn đến bầu trời sao.",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 22,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 40
  },
  "user": null,
  "metadata": {}
}

Tài liệu chính thức OpenAI ResponsesXem định nghĩa giao thức phía nhà cung cấp và các thay đổi trường mới nhất.

Xác thực

Nội dung yêu cầu

Nội dung phản hồi

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

502application/json

503application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`