聊天（Chat）
OpenAI 響應格式（Responses）
官方文件
📝 簡介
OpenAI 最先進的模型響應介面。支援文字和影象輸入，以及文字輸出。建立與模型的有狀態互動，將先前響應的輸出用作輸入。透過檔案搜尋、網路搜尋、計算機使用等內建工具擴充套件模型的能力。使用函式呼叫允許模型訪問外部系統和資料。
相關指南可參閱OpenAI官網：Responses
💡 請求示例
基礎文字響應 ✅
curl https://88api.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-4.1",
"input": "講一個三句話的關於獨角獸的睡前故事。"
}'響應示例:
{
"id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
"object": "response",
"created_at": 1741476542,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "message",
"id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "在一個寧靜的月夜下，一隻名叫璐米娜的獨角獸發現了一個倒映著星星的隱藏水池。當她將獨角浸入水中時，水池開始閃爍，顯現出通往一個有著無盡夜空的魔法世界的路徑。充滿好奇，璐米娜為所有做夢的人許下願望，希望他們能找到自己的隱藏魔法，當她回頭望去，她的蹄印像星塵一樣閃爍。",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 36,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 87,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 123
},
"user": null,
"metadata": {}
}影象分析響應 ✅
curl https://88api.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-4.1",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "描述這張圖片中的內容"},
{
"type": "input_image",
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
}
]
}
]
}'響應示例:
{
"id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
"object": "response",
"created_at": 1741476777,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "message",
"id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "這張圖片展示了一條木製棧道或小徑穿過茂密的綠色草地，上方是點綴著幾朵雲的藍天。場景呈現出一個寧靜的自然區域，可能是公園或自然保護區。背景中有樹木和灌木叢。整個景觀展現出和諧的自然環境，棧道為遊客提供了一條穿過溼地或草原而不影響周圍生態系統的路徑。",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 52,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 380
},
"user": null,
"metadata": {}
}網路搜尋工具 ✅
curl https://88api.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-4.1",
"tools": [{ "type": "web_search_preview" }],
"input": "今天有什麼積極正面的新聞?"
}'響應示例:
{
"id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c",
"object": "response",
"created_at": 1741484430,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "web_search_call",
"id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c",
"status": "completed"
},
{
"type": "message",
"id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "截至今天，2025年3月9日，一則值得關注的積極新聞是中國科學家在可再生能源領域取得重大突破，成功研發出一種新型高效太陽能電池，轉化率達到了創紀錄的35%，這可能會極大推動清潔能源的普及和應用。這項技術預計將使太陽能發電成本降低約40%，為全球減少碳排放提供了新的解決方案。",
"annotations": [
{
"type": "url_citation",
"start_index": 42,
"end_index": 100,
"url": "https://example.com/renewable-energy-breakthrough/?utm_source=chatgpt.com",
"title": "中國科學家在可再生能源領域取得重大突破"
},
{
"type": "url_citation",
"start_index": 101,
"end_index": 150,
"url": "https://example.com/solar-cell-efficiency-record/?utm_source=chatgpt.com",
"title": "新型高效太陽能電池轉化率創紀錄"
},
{
"type": "url_citation",
"start_index": 151,
"end_index": 200,
"url": "https://example.com/clean-energy-cost-reduction/?utm_source=chatgpt.com",
"title": "太陽能發電成本有望降低40%"
}
]
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "web_search_preview",
"domains": [],
"search_context_size": "medium",
"user_location": {
"type": "approximate",
"city": null,
"country": "US",
"region": null,
"timezone": null
}
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 356,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 684
},
"user": null,
"metadata": {}
}檔案搜尋工具 ✅
curl https://88api.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-4.1",
"tools": [{
"type": "file_search",
"vector_store_ids": ["vs_1234567890"],
"max_num_results": 20
}],
"input": "古代棕龍有哪些特性和屬性?"
}'響應示例:
{
"id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7",
"object": "response",
"created_at": 1741485253,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "file_search_call",
"id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7",
"status": "completed",
"queries": ["古代棕龍的特性和屬性"],
"results": null
},
{
"type": "message",
"id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "根據資料，古代棕龍具有以下特性和屬性：\n\n1. 物理特徵：古代棕龍體型龐大，體長可達25-30米，翼展約35米。它們的鱗片呈深棕色至銅色，隨著年齡增長會變得更加暗沉。頭部有特徵性的雙角和脊刺，下顎強壯，適合撕裂獵物。\n\n2. 能力：它們能噴吐強力的酸液，對目標造成嚴重腐蝕傷害。古代棕龍還擁有出色的掘地能力，常在沙漠或山地挖掘複雜的巢穴系統。\n\n3. 智力：被認為是龍族中最為狡猾和有耐心的品種，智力極高，精通多種語言，並具有複雜的戰術思維。\n\n4. 棲息地：主要棲息在乾旱的山地和沙漠地區，喜歡炎熱乾燥的環境。\n\n5. 寶藏：古代棕龍以其龐大的寶藏聞名，特別喜愛收集銅幣、紅寶石和火焰魔法物品。\n\n6. 壽命：是所有龍種中壽命最長的之一，可活2000-2500年，隨著年齡增長其力量和魔法能力也會增強。\n\n7. 性格：極度領地意識強，性格暴躁易怒，對侵入者毫不留情，但也以其罕見的耐心著稱，能為復仇等待幾個世紀。",
"annotations": [
{
"type": "file_citation",
"index": 80,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 233,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 345,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 420,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 520,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 580,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 655,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 781,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
}
]
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "file_search",
"filters": null,
"max_num_results": 20,
"ranking_options": {
"ranker": "auto",
"score_threshold": 0.0
},
"vector_store_ids": ["vs_1234567890"]
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 18307,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 348,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 18655
},
"user": null,
"metadata": {}
}流式響應 ✅
curl https://88api.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-4.1",
"instructions": "你是一個有幫助的助手。",
"input": "你好！",
"stream": true
}'流式響應示例:
event: response.created
data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"你是一個有幫助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}
event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"你是一個有幫助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}
event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}}
event: response.content_part.added
data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"你好"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"！"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":" 我"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"能"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"為"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"您"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"提供"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"什麼"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"幫助"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"嗎"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"？"}
event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"你好！ 我能為您提供什麼幫助嗎？"}
event: response.content_part.done
data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"你好！ 我能為您提供什麼幫助嗎？","annotations":[]}}
event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"你好！ 我能為您提供什麼幫助嗎？","annotations":[]}]}}
event: response.completed
data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"你是一個有幫助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"你好！ 我能為您提供什麼幫助嗎？","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}}函式呼叫 ✅
curl https://88api.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "gpt-4.1",
"input": "波士頓今天的天氣如何？",
"tools": [
{
"type": "function",
"name": "get_current_weather",
"description": "獲取指定位置的當前天氣",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location", "unit"]
}
}
],
"tool_choice": "auto"
}'響應示例:
{
"id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0",
"object": "response",
"created_at": 1741294021,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1-2025-04-14",
"output": [
{
"type": "function_call",
"id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0",
"call_id": "call_unLAR8MvFNptuiZK6K6HCy5k",
"name": "get_current_weather",
"arguments": "{\"location\":\"波士頓, MA\",\"unit\":\"celsius\"}",
"status": "completed"
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "function",
"description": "獲取指定位置的當前天氣",
"name": "get_current_weather",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location", "unit"]
},
"strict": true
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 291,
"output_tokens": 23,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 314
},
"user": null,
"metadata": {}
}推理能力 ✅
curl https://88api.ai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "o3-mini",
"input": "一隻啄木鳥能啄多少木頭?",
"reasoning": {
"effort": "high"
}
}'響應示例:
{
"id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808",
"object": "response",
"created_at": 1741477868,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "o1-2024-12-17",
"output": [
{
"type": "message",
"id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "這是一個源自英文繞口令"How much wood would a woodchuck chuck if a woodchuck could chuck wood"的問題。在現實中，啄木鳥(woodpecker)和土撥鼠(woodchuck)是不同的動物，而且土撥鼠實際上並不"啄(chuck)"木頭。\n\n從科學角度看，啄木鳥每天確實會啄樹木以尋找食物、建造巢穴或進行通訊。一隻啄木鳥平均每天可能啄樹約8000-12000次，視物種和具體目的而定。如果我們將這轉換為木材量，假設每次啄擊移除約0.1-0.2立方厘米的木材，那麼一隻啄木鳥理論上每天可能移除約800-2400立方厘米的木材。\n\n然而，啄木鳥主要是為了覓食和築巢而啄木，而不是單純地移除木材，所以這個計算只是一個有趣的理論估算。",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": "high",
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 81,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 1035,
"output_tokens_details": {
"reasoning_tokens": 832
},
"total_tokens": 1116
},
"user": null,
"metadata": {}
}📮 請求
端點
POST /v1/responses建立模型響應。提供文字或影象輸入以生成文字或JSON輸出。讓模型呼叫您自己的自定義程式碼或使用內建工具（如網路搜尋或檔案搜尋）將您自己的資料用作模型響應的輸入。
鑑權方法
在請求頭中包含以下內容進行 API 金鑰認證：
Authorization: Bearer $API_KEY其中 $API_KEY 是您的 API 金鑰。
請求體引數
input
型別: 字串或陣列
必需: 是
提供給模型的文字、影象或檔案輸入，用於生成響應。
可能的型別
| 型別 | 描述 |
|---|---|
| 字串 | 文字輸入，相當於具有使用者角色的文字輸入 |
| 輸入項陣列 | 包含不同內容型別的一個或多個輸入項列表 |
輸入訊息物件
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| content | 字串或陣列 | 是 | 提供給模型的文字、影象或音訊輸入，用於生成響應。也可以包含之前的助手響應 |
| role | 字串 | 是 | 輸入訊息的角色。可選值：user、assistant、system 或 developer |
| type | 字串 | 否 | 輸入訊息的型別，始終為 message |
內容項型別
文字輸入
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| text | 字串 | 是 | 提供給模型的文字輸入 |
| type | 字串 | 是 | 輸入項的型別，始終為 input_text |
影象輸入
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| detail | 字串 | 是 | 要傳送給模型的影象的詳細級別。可選值：high、low 或 auto。預設為 auto |
| type | 字串 | 是 | 輸入項的型別，始終為 input_image |
| file_id | 字串 | 否 | 要傳送給模型的檔案ID |
| image_url | 字串 | 否 | 要傳送給模型的影象URL。可以是完整的URL或資料URL中的base64編碼影象 |
檔案輸入
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| type | 字串 | 是 | 輸入項的型別，始終為 input_file |
| file_data | 字串 | 否 | 要傳送給模型的檔案內容 |
| file_id | 字串 | 否 | 要傳送給模型的檔案ID |
| filename | 字串 | 否 | 要傳送給模型的檔名 |
輸出項型別
輸出文字
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| text | 字串 | 是 | 模型生成的文字輸出 |
| type | 字串 | 是 | 輸出項的型別，始終為 output_text |
| annotations | 陣列 | 是 | 文字輸出的註釋 |
註釋型別
檔案引用:
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| file_id | 字串 | 是 | 檔案的ID |
| index | 整數 | 是 | 檔案在檔案列表中的索引 |
| type | 字串 | 是 | 檔案引用的型別，始終為 file_citation |
URL引用:
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| end_index | 整數 | 是 | URL引用在訊息中的最後一個字元的索引 |
| start_index | 整數 | 是 | URL引用在訊息中的第一個字元的索引 |
| title | 字串 | 是 | 網路資源的標題 |
| type | 字串 | 是 | URL引用的型別，始終為 url_citation |
| url | 字串 | 是 | 網路資源的URL |
檔案路徑:
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| file_id | 字串 | 是 | 檔案的ID |
| index | 整數 | 是 | 檔案在檔案列表中的索引 |
| type | 字串 | 是 | 檔案路徑的型別，始終為 file_path |
拒絕響應
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| refusal | 字串 | 是 | 模型的拒絕解釋 |
| type | 字串 | 是 | 拒絕的型別，始終為 refusal |
工具呼叫型別
檔案搜尋工具呼叫
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| id | 字串 | 是 | 檔案搜尋工具呼叫的唯一ID |
| queries | 陣列 | 是 | 用於搜尋檔案的查詢 |
| status | 字串 | 是 | 檔案搜尋工具呼叫的狀態。可能值包括：in_progress、searching、incomplete 或 failed |
| type | 字串 | 是 | 檔案搜尋工具呼叫的型別，始終為 file_search_call |
| results | 陣列或null | 否 | 檔案搜尋工具呼叫的結果 |
網路搜尋工具呼叫
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| id | 字串 | 是 | 網路搜尋工具呼叫的唯一ID |
| status | 字串 | 是 | 網路搜尋工具呼叫的狀態 |
| type | 字串 | 是 | 網路搜尋工具呼叫的型別，始終為 web_search_call |
函式工具呼叫
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| arguments | 字串 | 是 | 傳遞給函式的引數的JSON字串 |
| call_id | 字串 | 是 | 模型生成的函式工具呼叫的唯一ID |
| name | 字串 | 是 | 要執行的函式的名稱 |
| type | 字串 | 是 | 函式工具呼叫的型別，始終為 function_call |
| id | 字串 | 否 | 函式工具呼叫的唯一ID |
| status | 字串 | 否 | 專案的狀態。可能值：in_progress、completed或incomplete |
計算機工具呼叫
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| action | 物件 | 是 | 計算機互動的操作，如點選、拖拽等 |
| call_id | 字串 | 是 | 響應工具呼叫輸出時使用的識別符號 |
| id | 字串 | 是 | 計算機呼叫的唯一ID |
| pending_safety_checks | 陣列 | 是 | 計算機呼叫的待處理安全檢查 |
| status | 字串 | 是 | 專案的狀態。可能值：in_progress、completed或incomplete |
| type | 字串 | 是 | 計算機呼叫的型別，始終為 computer_call |
計算機操作型別:
| 操作型別 | 描述 |
|---|---|
| click | 滑鼠點選操作 |
| double_click | 滑鼠雙擊操作 |
| drag | 拖拽操作 |
| keypress | 按鍵操作 |
| move | 滑鼠移動操作 |
| screenshot | 螢幕截圖操作 |
| scroll | 滾動操作 |
| type | 文字輸入操作 |
| wait | 等待操作 |
計算機工具呼叫輸出
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| call_id | 字串 | 是 | 產生輸出的計算機工具呼叫的ID |
| output | 物件 | 是 | 用於計算機使用工具的計算機螢幕截圖影象 |
| type | 字串 | 是 | 計算機工具呼叫輸出的型別，始終為 computer_call_output |
| acknowledged_safety_checks | 陣列 | 否 | API報告的已被開發者確認的安全檢查 |
| id | 字串 | 否 | 計算機工具呼叫輸出的ID |
| status | 字串 | 否 | 輸入訊息的狀態。可能值：in_progress、completed或incomplete |
函式工具呼叫輸出
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| call_id | 字串 | 是 | 模型生成的函式工具呼叫的唯一ID |
| output | 字串 | 是 | 函式工具呼叫輸出的JSON字串 |
| type | 字串 | 是 | 函式工具呼叫輸出的型別，始終為 function_call_output |
| id | 字串 | 否 | 函式工具呼叫輸出的唯一ID |
| status | 字串 | 否 | 專案的狀態。可能值：in_progress、completed或incomplete |
推理相關項
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| id | 字串 | 是 | 推理內容的唯一識別符號 |
| summary | 陣列 | 是 | 推理文字內容 |
| type | 字串 | 是 | 物件的型別，始終為 reasoning |
| encrypted_content | 字串或null | 否 | 推理項的加密內容 - 當使用 reasoning.encrypted_content 包含引數生成響應時填充 |
| status | 字串 | 否 | 專案的狀態。可能值：in_progress、completed或incomplete |
推理摘要:
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| text | 字串 | 是 | 模型生成響應時使用的推理的簡短摘要 |
| type | 字串 | 是 | 物件的型別，始終為 summary_text |
專案引用
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| id | 字串 | 是 | 要引用的專案的ID |
| type | 字串 | 否 | 要引用的專案型別，始終為 item_reference |
model
型別: 字串
必需: 是
用於生成響應的模型ID，例如 gpt-4.1 或 o3。OpenAI 提供各種具有不同能力、效能特性和價格點的模型。請參閱模型指南以瀏覽和比較可用模型。
include
型別: 陣列或null
必需: 否
指定要在模型響應中包含的附加輸出資料。當前支援的值包括：
| 值 | 描述 |
|---|---|
file_search_call.results | 包含檔案搜尋工具呼叫的搜尋結果 |
message.input_image.image_url | 包含輸入訊息中的影象URL |
computer_call_output.output.image_url | 包含電腦呼叫輸出中的影象URL |
reasoning.encrypted_content | 在推理項輸出中包含推理標記的加密版本 |
instructions
型別: 字串或null
必需: 否
作為模型上下文中的第一項插入系統（或開發者）訊息。
當與 previous_response_id 一起使用時，前一個響應中的指令不會被帶到下一個響應。這使得在新響應中輕鬆切換系統（開發者）訊息變得簡單。
max_output_tokens
型別: 整數或null
必需: 否
可以為響應生成的令牌數量的上限，包括可見輸出令牌和推理令牌。
metadata
型別: 物件
必需: 否
可以附加到物件的16個鍵值對集合。這對於以結構化格式儲存物件的其他資訊很有用,並可以透過 API 或儀表板查詢物件。
鍵是最大長度為64個字元的字串。值是最大長度為512個字元的字串。
parallel_tool_calls
型別: 布林值或null
必需: 否
預設值: true
是否允許模型並行執行工具呼叫。
previous_response_id
型別: 字串或null
必需: 否
模型的前一個響應的唯一ID。使用此引數建立多輪對話。瞭解更多關於對話狀態。
reasoning
型別: 物件或null
必需: 否
僅適用於o系列模型
推理模型的配置選項。
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| effort | 字串或null | 否 | 推理的努力程度，可選值: low, medium, high。預設值為 medium。降低推理努力可以加快響應速度並減少響應中用於推理的令牌數 |
| summary | 字串或null | 否 | 模型執行的推理摘要。這對於除錯和理解模型的推理過程很有用。可選值: auto, concise, detailed |
| generate_summary | 字串或null | 否 | 已棄用: 請使用 summary 替代。模型執行的推理摘要。可選值: auto, concise, detailed |
service_tier
型別: 字串或null
必需: 否
預設值: auto
指定用於處理請求的延遲層級。此引數與訂閱了 scale tier 服務的客戶相關：
| 值 | 描述 |
|---|---|
auto | 如果專案啟用了 Scale tier，系統將使用 scale tier 信用直到用完；如果專案未啟用 Scale tier，請求將使用預設服務層級處理，具有較低的正常執行時間 SLA 且無延遲保證 |
default | 請求將使用預設服務層級處理，具有較低的正常執行時間 SLA 且無延遲保證 |
flex | 請求將使用 Flex Processing 服務層級處理。瞭解更多資訊請參閱官方文件 |
當未設定此引數時，預設行為為 auto。
當設定此引數時，響應體將包含已使用的 service_tier。
store
型別: 布林值或null
必需: 否
預設值: true
是否儲存生成的模型響應以供以後透過 API 檢索。
stream
型別: 布林值或null
必需: 否
預設值: false
如果設定為 true，模型響應資料將在生成時使用伺服器傳送的事件流式傳輸到客戶端。
temperature
型別: 數字或null
必需: 否
預設值: 1
要使用的取樣溫度，介於 0 和 2 之間。較高的值（如0.8）會使輸出更加隨機，而較低的值（如0.2）會使其更加集中和確定性。我們通常建議更改此值或 top_p，但不要同時更改。
text
型別: 物件
必需: 否
模型文字響應的配置選項。可以是純文字或結構化JSON資料。
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| format | 物件 | 否 | 指定模型必須輸出的格式 |
配置 { "type": "json_schema" } 啟用結構化輸出，確保模型將匹配您提供的JSON模式。更多資訊請參閱結構化輸出指南。
預設格式為 { "type": "text" }，沒有其他選項。
不推薦用於gpt-4o及更新的模型：
設定為 { "type": "json_object" } 啟用較舊的JSON模式，確保模型生成的訊息是有效的JSON。對於支援的模型，首選使用 json_schema。
文字格式型別
文字 (Text)
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| type | 字串 | 是 | 定義的響應格式型別。始終為 text |
JSON模式 (JSON Schema)
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| name | 字串 | 是 | 響應格式的名稱。必須包含a-z, A-Z, 0-9，或包含下劃線和破折號，最大長度為64 |
| schema | 物件 | 是 | 響應格式的模式，描述為JSON Schema物件 |
| type | 字串 | 是 | 定義的響應格式型別。始終為 json_schema |
| description | 字串 | 否 | 響應格式用途的描述，模型用它來確定如何以該格式響應 |
| strict | 布林值或null | 否 | 是否在生成輸出時啟用嚴格模式遵循。預設為 false。如果設定為 true，模型將始終遵循 schema 欄位中定義的確切模式。嚴格模式下只支援JSON Schema的子集 |
JSON物件 (JSON Object)
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| type | 字串 | 是 | 定義的響應格式型別。始終為 json_object |
注意：如果沒有指示模型這樣做的系統或使用者訊息，模型將不會生成JSON。對於支援的模型，建議使用 json_schema。
tool_choice
型別: 字串或物件
必需: 否
模型如何選擇生成響應時使用的工具（或多個工具）。請參閱 tools 引數瞭解如何指定模型可以呼叫的工具。
可能的型別
工具選擇模式 (Tool choice mode)
型別: 字串
控制模型是否呼叫工具以及呼叫哪種工具。
| 值 | 描述 |
|---|---|
none | 模型不會呼叫任何工具，而是生成一條訊息 |
auto | 模型可以在生成訊息或呼叫一個或多個工具之間選擇 |
required | 模型必須呼叫一個或多個工具 |
託管工具 (Hosted tool)
型別: 物件
指示模型應使用內建工具生成響應。
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| type | 字串 | 是 | 模型應使用的託管工具型別。允許的值有：file_search、web_search_preview、computer_use_preview |
函式工具 (Function tool)
型別: 物件
使用此選項強制模型呼叫特定函式。
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| name | 字串 | 是 | 要呼叫的函式名稱 |
| type | 字串 | 是 | 對於函式呼叫，型別始終為 function |
tools
型別: 陣列
必需: 否
模型在生成響應時可能呼叫的工具陣列。你可以透過設定 tool_choice 引數來指定使用哪個工具。
你可以提供給模型的兩類工具是：
- 內建工具：由OpenAI提供的擴充套件模型能力的工具，如網路搜尋或檔案搜尋。
- 函式呼叫（自定義工具）：由您定義的函式，使模型能夠呼叫您自己的程式碼。
檔案搜尋工具 (File search)
型別: 物件
一個搜尋已上傳檔案中相關內容的工具。
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| type | 字串 | 是 | 檔案搜尋工具的型別，始終為 file_search |
| vector_store_ids | 陣列 | 是 | 要搜尋的向量儲存ID列表 |
| filters | 物件 | 否 | 要應用的過濾器 |
| max_num_results | 整數 | 否 | 返回的最大結果數。此數字應介於1到50之間（含） |
| ranking_options | 物件 | 否 | 搜尋排名選項 |
過濾器型別
比較過濾器 (Comparison Filter)
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| key | 字串 | 是 | 要與值進行比較的鍵 |
| type | 字串 | 是 | 指定比較運算子: eq, ne, gt, gte, lt, lte- eq: 等於 <br />- ne: 不等於<br />- gt: 大於<br />- gte: 大於等於<br />- lt: 小於<br />- lte: 小於等於 |
| value | 字串/數字/布林值 | 是 | 要與屬性鍵比較的值；支援字串、數字或布林型別 |
複合過濾器 (Compound Filter)
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| filters | 陣列 | 是 | 要組合的過濾器陣列。專案可以是比較過濾器或複合過濾器 |
| type | 字串 | 是 | 操作型別: and 或 or |
排名選項
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| ranker | 字串 | 否 | 檔案搜尋使用的排名器 |
| score_threshold | 數字 | 否 | 檔案搜尋的分數閾值，介於0和1之間的數字。接近1的數字將嘗試僅返回最相關的結果，但可能返回更少的結果 |
函式工具 (Function)
型別: 物件
定義模型可以選擇呼叫的您自己程式碼中的函式。
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| type | 字串 | 是 | 函式工具的型別，始終為 function |
| name | 字串 | 是 | 要呼叫的函式名稱 |
| parameters | 物件 | 是 | 描述函式引數的JSON模式物件 |
| strict | 布林值 | 是 | 是否強制嚴格引數驗證。預設為 true |
| description | 字串 | 否 | 函式的描述。模型用它來確定是否呼叫函式 |
網路搜尋工具 (Web search preview)
型別: 物件
此工具搜尋網路上的相關結果，用於響應。
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| type | 字串 | 是 | 網路搜尋工具的型別。可選值: web_search_preview 或 web_search_preview_2025_03_11 |
| search_context_size | 字串 | 否 | 對用於搜尋的上下文視窗空間量的高階指導。可選值: low, medium, high。預設為 medium |
| user_location | 物件 | 否 | 使用者的位置 |
| domains | 陣列 | 否 | 限制搜尋的域名列表 |
使用者位置
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| type | 字串 | 是 | 位置近似型別。始終為 approximate |
| city | 字串 | 否 | 使用者所在城市的自由文字輸入，例如 "San Francisco" |
| country | 字串 | 否 | 使用者的兩字母ISO國家程式碼，例如 "US" |
| region | 字串 | 否 | 使用者所在區域的自由文字輸入，例如 "California" |
| timezone | 字串 | 否 | 使用者的IANA時區，例如 "America/Los_Angeles" |
計算機使用工具 (Computer use preview)
型別: 物件
控制虛擬計算機的工具。
| 屬性 | 型別 | 必需 | 描述 |
|---|---|---|---|
| type | 字串 | 是 | 計算機使用工具的型別。始終為 computer_use_preview |
| display_height | 整數 | 是 | 計算機顯示器的高度 |
| display_width | 整數 | 是 | 計算機顯示器的寬度 |
| environment | 字串 | 是 | 要控制的計算機環境型別 |
top_p
型別: 數字或null
必需: 否
預設值: 1
一種替代取樣溫度的方法，稱為核取樣，其中模型考慮具有 top_p 機率質量的標記結果。因此，0.1 意味著只考慮包含前 10% 機率質量的標記。
我們通常建議更改此值或 temperature，但不要同時更改。
truncation
型別: 字串或null
必需: 否
預設值: disabled
用於模型響應的截斷策略：
| 值 | 描述 |
|---|---|
auto | 如果此響應和前一個響應的上下文超過模型的上下文視窗大小，模型將透過刪除對話中間的輸入項來截斷響應以適應上下文視窗 |
disabled | 如果模型響應將超過模型的上下文視窗大小，請求將失敗並顯示400錯誤 |
user
型別: 字串
必需: 否
表示終端使用者的唯一識別符號，可以幫助OpenAI監控和檢測濫用行為。
📥 響應
返回一個響應物件。
成功響應
返回一個響應物件，如果請求被流式傳輸，則返回響應物件的流式序列。
id
- 型別：字串
- 說明：響應的唯一識別符號
object
- 型別：字串
- 說明：物件型別,值為 "response"
created_at
- 型別：整數
- 說明：響應建立時間戳
status
- 型別：字串
- 說明：響應狀態，如 "completed"、"in_progress" 等
error
- 型別：物件或null
- 說明：如果發生錯誤，包含錯誤資訊
incomplete_details
- 型別：物件或null
- 說明：如果響應不完整，包含詳細資訊
instructions
- 型別：字串或null
- 說明：提供給模型的系統指令
max_output_tokens
- 型別：整數或null
- 說明：最大輸出標記數
model
- 型別：字串
- 說明：使用的模型名稱
output
- 型別：陣列
- 說明：包含生成的回覆和工具呼叫
- 可能包含:
- 訊息物件（
type: "message"） - 工具使用物件（
type: "tool_use"）
- 訊息物件（
parallel_tool_calls
- 型別：布林值
- 說明：是否啟用並行工具呼叫
previous_response_id
- 型別：字串或null
- 說明：前一個響應的ID（用於多輪對話）
reasoning
- 型別：物件
- 說明：推理相關資訊
store
- 型別：布林值
- 說明：是否儲存此響應
temperature
- 型別：數字
- 說明：使用的取樣溫度
text
- 型別：物件
- 說明：文字輸出格式配置
tool_choice
- 型別：字串
- 說明：工具選擇策略
tools
- 型別：陣列
- 說明：可用工具列表
top_p
- 型別：數字
- 說明：核取樣閾值
truncation
- 型別：字串
- 說明：截斷策略
usage
- 型別：物件
- 說明：token 使用統計
- 屬性:
input_tokens: 輸入使用的 token 數input_tokens_details: 輸入token詳細資訊output_tokens: 輸出使用的 token 數output_tokens_details: 輸出token詳細資訊total_tokens: 總 token 數
user
- 型別：字串或null
- 說明：使用者識別符號
metadata
- 型別：物件
- 說明：附加的後設資料資訊