文件搜索工具

POST  v1/responses

请求参数

Authorization

在 Header 添加参数 Authorization，其值为在 Bearer 之后拼接 Token。

Authorization: Bearer ******************

Body 参数

Content-Type: application/json

参数名	类型	必填	说明
model	string	必需	要使用的模型 ID。
tools	array[object]	必需	工具
input	array [object]	必需	输入消息列表。包含 role (可选), content (可选) 等字段。
include	array[string]	可选	指定要在模型响应中包含的附加输出数据。
instructions	string	可选	作为系统消息插入到模型上下文的最前面。注意：当使用 previous_response_id 时，之前的指令不会自动带入，方便切换指令。
max_output_tokens	integer	可选	响应生成的最大 token 数（包含可见输出和推理 token）。
metadata	object	可选	最多包含 16 个键值对的元数据对象，用于存储额外信息。键最长 64 字符，值最长 512 字符。
parallel_tool_calls	boolean	可选	是否在工具调用期间启用并行执行。
previous_response_id	string	可选	前一次响应的唯一 ID，用于创建多轮对话。
reasoning	object	可选	仅适用于 o 系列模型。配置模型的推理行为。
service_tier	string	可选	指定处理请求的延迟层级（如 auto, default, flex）。未设置时默认为 auto。
store	boolean	可选	是否将此请求的输出存储用于模型蒸馏或评估。
stream	boolean	可选	如果为 true，将通过服务器发送事件流式返回响应。
temperature	number	可选	采样温度 (0-2)。值越高输出越随机，值越低越确定。建议只调整此参数或 top_p 其中之一。
text	object	可选	文本响应的配置。可配置 { "type": "json_schema" } 以启用结构化输出。
tool_choice	array[string]	可选	模型可调用的工具列表（目前仅支持函数）。最多支持 128 个函数。
top_p	number	可选	核采样参数 (0-1)。例如 0.1 意味着只考虑概率质量前 10% 的 token。
truncation	string	可选	用于模型响应的截断策略。
user	string	可选	最终用户的唯一标识符，有助于 OpenAI 监控和检测滥用行为。

请求示例 (JSON)

{
    "model": "gpt-4.1",
    "tools": [
        {
            "type": "file_search",
            "vector_store_ids": [
                "vs_1234567890"
            ],
            "max_num_results": 20
        }
    ],
    "input": "古代棕龙有哪些特性和属性?"
}

返回响应

200 成功

Content-Type: application/json

响应参数

字段名	类型	必填	说明
id	string	必需	响应的唯一标识符。
object	string	必需	对象类型。
created_at	integer	必需	创建时间的 Unix 时间戳。
status	string	必需	响应的当前状态。
background	boolean	必需	是否在后台运行。
model	string	必需	使用的模型名称。
parallel_tool_calls	boolean	必需	是否启用了并行工具调用。
service_tier	string	必需	服务层级（如 default, flex 等）。
store	boolean	必需	是否存储了输出用于训练/评估。
temperature	integer	必需	采样温度。
tool_choice	string	必需	工具选择策略。
tools	array[string]	必需	可用的工具列表。
top_logprobs	integer	必需	返回的对数概率数量。
top_p	integer	必需	核采样概率阈值。
truncation	string	必需	截断策略。
user	null	必需	用户标识（此处显示为 null，通常用于审计）。
metadata	object	必需	用户自定义的元数据。
created	integer	必需	另一个时间戳字段（可能是兼容旧版字段）。

响应示例

{
    "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,
    "text": {
        "format": {
            "type": "text"
        }
    },
    "tool_choice": "auto",
    "tools": [
        {
            "type": "file_search",
            "filters": null,
            "max_num_results": 20,
            "ranking_options": {
                "ranker": "auto",
                "score_threshold": 0
            },
            "vector_store_ids": [
                "vs_1234567890"
            ]
        }
    ],
    "top_p": 1,
    "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": {}
}

示例代码

import http.client
import json

conn = http.client.HTTPSConnection("nxaiapp.com")
payload = json.dumps({
   "model": "gpt-4.1",
   "tools": [
      {
         "type": "file_search",
         "vector_store_ids": [
            "vs_1234567890"
         ],
         "max_num_results": 20
      }
   ],
   "input": "古代棕龙有哪些特性和属性?"
})
headers = {
   'Authorization': 'Bearer <token>',
   'Content-Type': 'application/json'
}
conn.request("POST", "/v1//responses", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))