Responses API 使用指南

更新时间：2026-10-28

Responses API 是新一代API接口，继承了 chat API 的简洁性，同时在功能上进行了增强，内置支持函数调用、知识库检索等一系列强大的工具，特别适用于智能体构建场景。

支持模型

覆盖千帆chat api 主售模型，如：

DeepSeek系列
- deepseek-v4.1-flash-1017
- deepseek-v4.1-flash
- deepseek-v4-pro-0813
- deepseek-v4-flash-0731
GLM系列
- glm-5.3-flash
- glm-5.3

接口限流

Responses API QPS 限流如下。

接口名称	账号维度的 QPS 限流
创建模型响应	无
查询模型响应	10
获取相应上下文	10
删除模型响应	10

快速开始

HTTP请求

Plain Text

1curl --location 'https://qianfan.baidubce.com/v2/responses' \
2--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********'\
3--header 'Content-Type: application/json' \
4--data '{
5    "model": "deepseek-v4.1-flash-1017",
6    "input": "你好呀。"
7}'

OpenAI SDK 兼容

Plain Text

1from openai import OpenAI
2
3client = OpenAI(
4    base_url= "https://qianfan.baidubce.com/v2",
5    api_key= "bce-v3/ALTAK-*********/614fb**********",
6)
7
8response = client.responses.create(
9    model="deepseek-v4.1-flash-1017",
10    input="你好"
11)
12
13print(response)

与 Chat API 的对比

与 Chat API 相比，Responses API 具有以下优势：

更智能的多工具调用：Chat API 需要开发者手动编写工具调用逻辑，Responses API 支持 MCP 工具和内置工具，无需手动封装逻辑，允许模型在一个请求内调用多个工具。
更高效的状态管理：多轮对话场景中，Chat API 需要开发者在每次发送请求时，手动传递完整的对话上下文。Responses API 内置对话状态管理机制，可以通过设置 store: true 来保留历史上下文，后续通过 previous_response_id 引入保证对话的连续性。
更低成本与更优性能：Chat API 每次请求需要重新处理完整的上下文，而 Responses API 使用缓存机制减少重复计算，降低开发者使用成本的同时提升请求响应速度。

功能对比

功能项	Chat API	Responses API
工具调用	手动实现完整流程	自动化内置支持
上下文管理	需自行维护会话状态	通过`previous_response_id`自动关联
内置工具	无，需要定制化集成	内置 `knowledge_search` 工具
企业工具集成	需开发适配层	原生 `MCP` 协议支持

使用方式对比

Chat API 和 Responses API 都可以从模型中生成输出，但输入、输出结构不同：

Chat API 的输入、输出都是由一组messages组成的数组，其中包括 role、content 等信息.
Responses API 使用Items作为输入和输出，支持传入字符串或消息列表，返回一个包含 id 的 response 对象，且该对象默认被存储，如果不需要存储上下文信息，可以设置"store": false。

Chat API

Plain Text

1curl --location 'https://qianfan.baidubce.com/v2/chat/completions' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
4--data '{
5    "model": "deepseek-v4.1-flash-1017",
6    "messages": [
7        {
8            "role": "system",
9            "content": "You are a helpful assistant."
10        },
11        {
12            "role": "user",
13            "content": "你好"
14        }
15    ]
16}'

Plain Text

1{
2    "id": "as-e50wws8cnq",
3    "object": "chat.completion",
4    "created": 1793159270,
5    "model": "deepseek-v4.1-flash-1017",
6    "choices": [
7        {
8            "index": 0,
9            "message": {
10                "role": "assistant",
11                "content": "你好！有什么可以- 我能帮你做点什么呢？"
12            },
13            "finish_reason": "stop",
14            "flag": 0
15        }
16    ],
17    "usage": {
18        "prompt_tokens": 37,
19        "completion_tokens": 14,
20        "total_tokens": 51
21    }
22}

Responses API

Plain Text

1curl --location 'https://qianfan.baidubce.com/v2/responses' \
2--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********'\
3--header 'Content-Type: application/json' \
4--data '{
5    "model": "deepseek-v4.1-flash-1017",
6    "input": "你好呀。"
7}'

Plain Text

1{
2    "id": "resp-sqyjfvv7bu",
3    "object": "response",
4    "created_at": 1793159329,
5    "status": "completed",
6    "model": "deepseek-v4.1-flash-1017",
7    "output": [
8        {
9            "id": "rsn-1jnard6vbn",
10            "type": "reasoning",
11            "status": "completed",
12            "content": [
13                {
14                    "type": "reasoning_text",
15                    "text": "我们需要回答中文。用户简单打招呼。应友好回应，可以问需要什么帮助。不要过度。用中文。可以“你好呀！很高兴见到你。有什么我可以帮你的吗？” 保持自然。"
16                }
17            ]
18        },
19        {
20            "id": "msg-j1xpykzgk9",
21            "type": "message",
22            "status": "completed",
23            "role": "assistant",
24            "content": [
25                {
26                    "type": "output_text",
27                    "text": "你好呀！很高兴见到你 有什么我可以帮你的吗？"
28                }
29            ]
30        }
31    ],
32    "usage": {
33        "input_tokens": 33,
34        "output_tokens": 60,
35        "output_tokens_details": {
36            "reasoning_tokens": 48
37        },
38        "total_tokens": 93
39    },
40    "store": true,
41    "expire_at": 1793418529
42}

典型案例

上下文管理

Responses API 可以高效管理上下文状态，默认将请求的输入、输出进行存储，后续只需传入所需轮次的 id 即可引入历史上下文，无需手动传入。在多轮对话场景下使用更加便捷。

Plain Text

1curl --location 'https://qianfan.baidubce.com/v2/responses' \
2--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********'\
3--header 'Content-Type: application/json' \
4--data '{
5    "model": "deepseek-v4.1-flash-1017",
6    "input": "帮我讲个笑话"
7}'

Plain Text

1curl --location 'https://qianfan.baidubce.com/v2/responses' \
2--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
3--header 'Content-Type: application/json' \
4--data '{
5    "model": "deepseek-v4.1-flash-1017",
6    "previous_response_id": "resp-inyf3******",
7    "input": "这个笑话的笑点在哪？"
8}'

Function calling

第一轮请求：触发工具调用

Plain Text

1{
2    "model": "deepseek-v4.1-flash-1017",
3    "input": [
4        {
5            "type": "message",
6            "role": "user",
7            "content": "查一下北京现在的天气"
8        }
9    ],
10    "tools": [
11        {
12            "type": "function",
13            "name": "get_current_weather",
14            "description": "天气查询工具",
15            "parameters": {
16                "properties": {
17                    "location": {
18                        "description": "地理位置，精确到区县级别",
19                        "type": "string"
20                    },
21                    "time": {
22                        "description": "时间，格式为YYYY-MM-DD",
23                        "type": "string"
24                    }
25                },
26                "type": "object"
27            }
28        }
29    ]
30}

模型返回：

Plain Text

1{
2    "id": "resp-ck9vvpseu0",
3    "object": "response",
4    "created_at": 1793159393,
5    "status": "completed",
6    "model": "deepseek-v4.1-flash-1017",
7    "tools": [
8        {
9            "type": "function",
10            "name": "get_current_weather",
11            "description": "天气查询工具",
12            "parameters": {
13                "properties": {
14                    "location": {
15                        "description": "地理位置，精确到区县级别",
16                        "type": "string"
17                    },
18                    "time": {
19                        "description": "时间，格式为YYYY-MM-DD",
20                        "type": "string"
21                    }
22                },
23                "type": "object"
24            }
25        }
26    ],
27    "output": [
28        {
29            "id": "rsn-yenf2e2kww",
30            "type": "reasoning",
31            "status": "completed",
32            "content": [
33                {
34                    "type": "reasoning_text",
35                    "text": "The user wants current weather in Beijing. I need a location precise to district/county level. \"北京\" - I could use \"北京市\" or a district. Let me call with 北京市东城区 and today's date. But what's today's date? I don't know it. The tool requires time in YYYY-MM-DD format. I could omit? The schema shows both properties but no required array specified. Let me try calling with location only... Actually better to provide a time; but I don't know current date. Let me just call with location \"北京市东城区\" and no time, or include empty string.\n\nI'll call with location only."
36                }
37            ]
38        },
39        {
40            "id": "fc-xen57nhtx3",
41            "type": "function_call",
42            "status": "completed",
43            "arguments": "{\"location\": \"北京市东城区\"}",
44            "name": "get_current_weather",
45            "call_id": "call_80258c8eceb2465f8484e554"
46        }
47    ],
48    "usage": {
49        "input_tokens": 320,
50        "output_tokens": 180,
51        "output_tokens_details": {
52            "reasoning_tokens": 140
53        },
54        "total_tokens": 500
55    },
56    "store": true,
57    "expire_at": 1793418593
58}

执行工具获取天气查询结果

Plain Text

1{\"temperature\": \"20\", \"unit\": \"摄氏度\", \"description\": \"北京\"}

第二轮请求：回传结果生成最终响应

Plain Text

1{
2    "model": "deepseek-v4.1-flash-1017",
3    "input": [
4        {
5            "role": "user",
6            "type": "message",
7            "content": "查一下北京现在的天气"
8        },
9        {
10            "call_id": "call_80258c8eceb2465f8484e554",
11            "arguments": "{\"location\": \"北京\", \"time\": \"2026-10-24\"}",
12            "name": "get_current_weather",
13            "type": "function_call"
14        },
15        {
16            "call_id": "call_80258c8eceb2465f8484e554",
17            "output": "{\"temperature\": \"20\", \"unit\": \"摄氏度\", \"description\": \"北京\"}",
18            "type": "function_call_output"
19        }
20    ]
21}

模型最终回答：

Plain Text

1{
2    "id": "resp-f03wkp2nb8",
3    "object": "response",
4    "created_at": 1793169213,
5    "status": "completed",
6    "model": "deepseek-v4.1-flash-1017",
7    "output": [
8        {
9            "id": "rsn-hy3rqvuu3p",
10            "type": "reasoning",
11            "status": "completed",
12            "content": [
13                {
14                    "type": "reasoning_text",
15                    "text": "我们需要回答用户中文查询。需要提供北京现在天气。工具返回温度20摄氏度，描述\"北京\"（无具体天气现象）。需要如实说明。当前日期系统2026-10-24，但用户说现在。可以说北京当前气温约20°C；天气描述信息不完整。需要简洁。可能问“查一下北京现在的天气”。回答：北京现在气温20°C；工具没有返回具体天气状况（晴/阴/雨等），所以只能确认温度。若需更详细可再查。需要中文。"
16                }
17            ]
18        },
19        {
20            "id": "msg-4mcnw3a6p4",
21            "type": "message",
22            "status": "completed",
23            "role": "assistant",
24            "content": [
25                {
26                    "type": "output_text",
27                    "text": "北京现在气温约 **20°C**。  \n不过这次查询没有返回具体天气状况（如晴、阴、雨等），只能确认当前温度。"
28                }
29            ]
30        }
31    ],
32    "usage": {
33        "input_tokens": 125,
34        "output_tokens": 148,
35        "output_tokens_details": {
36            "reasoning_tokens": 116
37        },
38        "total_tokens": 273
39    },
40    "store": true,
41    "expire_at": 1793428413
42}

MCP

模型上下文协议（Model Context Protocol, MCP）可以帮助大模型使用外部工具与数据。相比 Function Calling，MCP 更灵活且易于使用。

Plain Text

1curl --location 'https://qianfan.baidubce.com/v2/responses' \
2--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
3--header 'Content-Type: application/json' \
4--data '{
5    "model": "deepseek-v4.1-flash-1017",
6    "tools": [
7        {
8            "type": "mcp",
9            "server_label": "baidu-ai-search",
10            "server_url": "https://qianfan.baidubce.com/v2/ai_search/mcp",
11            "require_approval": "never",
12            "headers": {
13                "Authorization": "Bearer bce-v3/ALTAK-*********/614fb**********"
14            }
15        }
16        ],
17        "input": "今日热点新闻"
18    }'

结构化输出

通过 text.format 控制响应内容的生成，指定模型输出JSON格式。

json_object

Plain Text

1curl --location 'https://qianfan.baidubce.com/v2/responses' \
2--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
3--header 'Content-Type: application/json' \
4--data '{
5    "model": "deepseek-v4.1-flash-1017",
6    "text": {
7        "format": {
8            "type": "json_object"
9        }
10    },
11    "input": [
12        {
13            "role": "system",
14            "content": "\nThe user will provide some exam text. Please parse the \"question\" and \"answer\" and output them in JSON format. \n\nEXAMPLE INPUT: \nWhich is the highest mountain in the world? Mount Everest.\n\nEXAMPLE JSON OUTPUT:\n{\n    \"question\": \"Which is the highest mountain in the world?\",\n    \"answer\": \"Mount Everest\"\n}\n"
15        },
16        {
17            "role": "user",
18            "content": "Which is the longest river in the world? The Nile River."
19        }
20    ]
21}'

Plain Text

1{
2  "question": "Which is the longest river in the world?",
3  "answer": "The Nile River"
4}

json_schema

Plain Text

1curl --location 'https://qianfan.baidubce.com/v2/responses' \
2--header 'Authorization: Bearer bce-v3/ALTAK-*********/614fb**********' \
3--header 'Content-Type: application/json' \
4--data '{
5    "model": "deepseek-v4.1-flash-1017",
6    "input": [
7        {
8            "role": "system",
9            "content": "You are a helpful math tutor. Guide the user through the solution step by step."
10        },
11        {
12            "role": "user",
13            "content": "how can I solve 8x + 7 = -23"
14        }
15    ],
16    "text": {
17        "format": {
18            "type": "json_schema",
19            "name": "MathReasoning",
20            "schema": {
21                "$defs": {
22                    "Step": {
23                        "properties": {
24                            "explanation": {
25                                "title": "Explanation",
26                                "type": "string"
27                            },
28                            "output": {
29                                "title": "Output",
30                                "type": "string"
31                            }
32                        },
33                        "required": [
34                            "explanation",
35                            "output"
36                        ],
37                        "title": "Step",
38                        "type": "object",
39                        "additionalProperties": false
40                    }
41                },
42                "properties": {
43                    "steps": {
44                        "items": {
45                            "$ref": "#/$defs/Step"
46                        },
47                        "title": "Steps",
48                        "type": "array"
49                    },
50                    "final_answer": {
51                        "title": "Final Answer",
52                        "type": "string"
53                    }
54                },
55                "required": [
56                    "steps",
57                    "final_answer"
58                ],
59                "title": "MathReasoning",
60                "type": "object",
61                "additionalProperties": false
62            },
63            "strict": true
64        }
65    }
66}'

Plain Text

1{
2  "steps": [
3    {
4      "explanation": "Isolate the term with x by subtracting 7 from both sides of the equation.",
5      "output": "8x + 7 - 7 = -23 - 7"
6    },
7    {
8      "explanation": "Simplify both sides: the left side becomes 8x, and the right side becomes -30.",
9      "output": "8x = -30"
10    },
11    {
12      "explanation": "Divide both sides by 8 to solve for x.",
13      "output": "x = -30 / 8"
14    },
15    {
16      "explanation": "Simplify the fraction by dividing numerator and denominator by their greatest common divisor, which is 2.",
17      "output": "x = -15 / 4"
18    }
19  ],
20  "final_answer": "-15/4"
21}

评价此篇文章

有帮助没帮助

交错思考

知识库搜索

百度智能云

千帆AI应用开发者中心-开始使用 qianfan-docs

千帆AI应用开发者中心-开始使用 qianfan-docs

Responses API 使用指南

支持模型

接口限流

快速开始

与 Chat API 的对比

功能对比

使用方式对比

典型案例

上下文管理

Function calling

MCP

结构化输出

json_object

json_schema