> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigmodel.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# Response API 兼容
智谱提供独立的 Response API 协议。您可以使用现有的 OpenAI SDK `responses` 接口，或直接发 HTTP 请求，只需修改 API Key、基础 URL 和模型编码，即可调用智谱模型。这套协议让您能够：
* 用同一套 `input` / `output` 对象描述文本、图片、文件和工具调用
* 通过 `store` 与 `previous_response_id` 做服务端多轮，不必自己拼接历史
* 接入兼容 Responses 协议的客户端与 Agent 工具链
* 与现有 [对话补全](/api-reference/模型-api/对话补全) 并存，已有 Chat Completions 代码不必迁移
智谱 Response API 与 OpenAI Responses 在部分字段上仍有差异：默认 `store=false`、流式结束不发送 `data: [DONE]`、当前未提供 cancel。完整字段以 [创建 Response](/api-reference/response/创建-response) 为准。
### 核心优势
}>
与对话补全分开的端点、对象模型和流式事件，互不影响
}>
使用 OpenAI SDK `responses.create`，只需改 base\_url 和模型编码
}>
`store` + `previous_response_id` 由服务端拼接上下文，响应 id 有效期 7 天
}>
支持文本、图片、文件输入，以及函数、命名空间、自定义工具和联网搜索
## 环境要求
}>
Python 3.7.1 或更高版本
}>
OpenAI SDK 版本不低于 1.0.0（需支持 `responses`）
请确保使用较新的 OpenAI SDK。旧版本可能没有 `client.responses`。
## 安装 OpenAI SDK
### 使用 pip 安装
```bash theme={null}
# 安装或升级到最新版本
pip install --upgrade 'openai>=1.0'
# 验证安装
python -c "import openai; print(openai.__version__)"
```
### 使用 poetry 安装
```bash theme={null}
poetry add "openai>=1.0"
```
## 快速开始
### 获取 API Key
1. 访问 [智谱开放平台](https://bigmodel.cn)
2. 注册并登录您的账户
3. 在 [API Keys](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) 管理页面创建 API Key
4. 复制您的 API Key 以供使用
建议将 API Key 设置为环境变量：`export ZAI_API_KEY=YOUR_API_KEY`，不要硬编码到代码中。
### 创建客户端
Response API 的基址是 `https://open.bigmodel.cn/api/v1`，不是对话补全使用的 `https://open.bigmodel.cn/api/paas/v4`。请求超时为 7200 秒。
```python theme={null}
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://open.bigmodel.cn/api/v1",
timeout=7200
)
```
```python theme={null}
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("ZAI_API_KEY"),
base_url="https://open.bigmodel.cn/api/v1",
timeout=7200
)
```
```python theme={null}
from openai import OpenAI
from dataclasses import dataclass
@dataclass
class ZhipuResponseConfig:
api_key: str
base_url: str = "https://open.bigmodel.cn/api/v1"
timeout: int = 7200
max_retries: int = 3
config = ZhipuResponseConfig(api_key="YOUR_API_KEY")
client = OpenAI(
api_key=config.api_key,
base_url=config.base_url,
timeout=config.timeout,
max_retries=config.max_retries
)
```
## 基础使用示例
### 简单调用
`input` 传字符串，等价于一条用户文本。
```bash theme={null}
curl https://open.bigmodel.cn/api/v1/responses \
--header "Authorization: Bearer YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "glm-5.3",
"input": "用一句话介绍智谱 GLM。"
}'
```
```python theme={null}
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://open.bigmodel.cn/api/v1",
timeout=7200
)
response = client.responses.create(
model="glm-5.3",
input="用一句话介绍智谱 GLM。"
)
print(response.id, response.status)
print(response.output_text)
```
```typescript theme={null}
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://open.bigmodel.cn/api/v1",
timeout: 7200 * 1000
});
const response = await client.responses.create({
model: "glm-5.3",
input: "用一句话介绍智谱 GLM。"
});
console.log(response.id, response.status);
console.log(response.output_text);
```
同步返回一个 Response 对象。先看 `id`、`status`、`output`、`usage`、`error`。文本在 `output` 里 `type=message` 的项中。
### 流式响应
`stream=true` 时按 SSE 推送事件。结束以 `response.completed` / `failed` / `incomplete` / `error` 为准，**不发送** `data: [DONE]`。
```python theme={null}
stream = client.responses.create(
model="glm-5.3",
input="写一首关于人工智能的诗",
stream=True
)
for event in stream:
if getattr(event, "type", None) == "response.output_text.delta":
print(event.delta, end="", flush=True)
print()
```
事件与字段见 [创建 Response](/api-reference/response/创建-response)。
### 多轮对话
默认 `store=false`，响应不会落库。需要查询或续写时，创建时设置 `store=true`，下一轮传入 `previous_response_id`。当前没有 cancel 接口。
```python theme={null}
first = client.responses.create(
model="glm-5.3",
input="我的名字是李雷。",
store=True
)
second = client.responses.create(
model="glm-5.3",
input="我叫什么名字？",
previous_response_id=first.id,
store=True
)
print(second.output_text)
```
## 高级功能
### 推理（reasoning）
```python theme={null}
response = client.responses.create(
model="glm-5.3",
input="证明勾股定理，并给出一个数值例子。",
extra_body={
"reasoning": {
"effort": "max"
}
}
)
print(response.output_text)
```
`effort` 默认 `max`。传入 `none` / `minimal` 会放弃思考；`low` / `medium` 映射为 `high`；`xhigh` 映射为 `max`。
### 函数调用
```python theme={null}
import json
def get_weather(city: str) -> str:
return json.dumps({"city": city, "weather": "晴", "temperature": 26}, ensure_ascii=False)
tools = [
{
"type": "function",
"name": "get_weather",
"description": "获取指定城市的天气",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称"}
},
"required": ["city"]
}
}
]
first = client.responses.create(
model="glm-5.3",
input="北京今天天气怎么样？",
tools=tools,
tool_choice="auto",
store=True
)
calls = [item for item in first.output if getattr(item, "type", None) == "function_call"]
if calls:
call = calls[0]
result = get_weather(**json.loads(call.arguments))
second = client.responses.create(
model="glm-5.3",
previous_response_id=first.id,
store=True,
input=[
{
"type": "function_call_output",
"call_id": call.call_id,
"output": result
}
]
)
print(second.output_text)
```
`tool_choice` 为 `none` 或 `auto`。另支持 `namespace`、`custom` 和由服务端执行的 `web_search`。
### 图像理解
```python theme={null}
response = client.responses.create(
model="glm-5.3",
input=[
{
"type": "message",
"role": "user",
"content": [
{"type": "input_text", "text": "请描述这张图片的内容"},
{
"type": "input_image",
"image_url": "https://cdn.bigmodel.cn/static/logo/register.png"
}
]
}
]
)
print(response.output_text)
```
## 参数配置
### 常用参数说明
| 参数 | 类型 | 默认值 | 说明 |
| ---------------------- | -------------- | ----- | -------------------------------------------------- |
| model | string | 必填 | 模型编码，例如 `glm-5.3` |
| input | string / array | 必填 | 用户文本，或输入项列表 |
| instructions | string | - | 系统指令 |
| stream | boolean | false | 是否 SSE 流式输出 |
| temperature | float | 1.0 | 采样温度 `[0.0, 1.0]`，不要与 `top_p` 同时调节 |
| top\_p | float | 0.95 | 核采样 `[0.01, 1.0]` |
| max\_output\_tokens | integer | 65536 | 最大输出 tokens（含思维链），上限 131072 |
| store | boolean | false | 是否保存，供查询和多轮使用 |
| previous\_response\_id | string | - | 上一轮 `id`，有效期 7 天 |
| tools | array | - | `function` / `namespace` / `custom` / `web_search` |
| reasoning.effort | string | max | 思考工作量 |
| text.format.type | string | text | `text` 或 `json_object` |
不要同时调节 `temperature` 和 `top_p`。查询、列举输入项和删除都要求创建时 `store=true`。
## 实践建议
* 客户端超时设为 7200 秒
* 长文本优先使用流式输出
* 多轮只传本轮 `input`，历史交给 `previous_response_id`
* 默认 `store=false`，仅在需要查询或续写时再保存
* 用 `max_output_tokens` 限制输出长度
* 按任务选择合适的 `reasoning.effort`
* 使用环境变量存储 API 密钥
* 不要把密钥写入仓库或前端
* 定期轮换 API 密钥
* 流式结束看 `response.completed`，不要等待 `data: [DONE]`
* 检查 `status` 与 `error`
* 响应 id 有效期 7 天，过期后无法续写
## 迁移指南
### 从 OpenAI Responses 迁移
如果您已经在使用 OpenAI Responses API，迁移到智谱非常简单：
```python theme={null}
from openai import OpenAI
# 原来的 OpenAI 代码
client = OpenAI(
api_key="sk-...", # OpenAI API Key
# base_url 使用默认值
)
# 迁移到智谱，只需要修改两处
client = OpenAI(
api_key="YOUR_API_KEY", # 替换为智谱 API Key
base_url="https://open.bigmodel.cn/api/v1", # 智谱 Response API 基址
timeout=7200
)
# 其他代码保持不变
response = client.responses.create(
model="glm-5.3", # 使用智谱模型
input="Hello!"
)
```
注意默认 `store=false`；若依赖服务端保存或 `previous_response_id`，创建时需显式 `store=true`。
## 接口一览
Base URL：`https://open.bigmodel.cn/api/v1`
| 方法 | 路径 | 说明 |
| :----- | :------------------------------------- | :------------------------------------------------- |
| POST | `/responses` | [创建 Response](/api-reference/response/创建-response) |
| GET | `/responses/{response_id}` | [查询 Response](/api-reference/response/查询-response) |
| GET | `/responses/{response_id}/input_items` | [查询输入项列表](/api-reference/response/查询输入项列表) |
| DELETE | `/responses/{response_id}` | [删除 Response](/api-reference/response/删除-response) |
## 更多资源
} href="/api-reference/response/创建-response">
查看完整请求、响应字段与流式事件
} href="https://platform.openai.com/docs/api-reference/responses">
参考 OpenAI 官方文档了解协议形态