Response API 兼容 - 智谱AI开放文档

智谱提供独立的 Response API 协议。您可以使用现有的 OpenAI SDK responses 接口，或直接发 HTTP 请求，只需修改 API Key、基础 URL 和模型编码，即可调用智谱模型。这套协议让您能够：

用同一套 input / output 对象描述文本、图片、文件和工具调用
通过 store 与 previous_response_id 做服务端多轮，不必自己拼接历史
接入兼容 Responses 协议的客户端与 Agent 工具链
与现有对话补全并存，已有 Chat Completions 代码不必迁移

智谱 Response API 与 OpenAI Responses 在部分字段上仍有差异：默认 store=false、流式结束不发送 data: [DONE]、当前未提供 cancel。完整字段以创建 Response 为准。

核心优势

独立协议

与对话补全分开的端点、对象模型和流式事件，互不影响

SDK 可复用

使用 OpenAI SDK responses.create，只需改 base_url 和模型编码

有状态多轮

store + previous_response_id 由服务端拼接上下文，响应 id 有效期 7 天

工具与多模态

支持文本、图片、文件输入，以及函数、命名空间、自定义工具和联网搜索

环境要求

Python 版本

Python 3.7.1 或更高版本

OpenAI SDK

OpenAI SDK 版本不低于 1.0.0（需支持 responses）

请确保使用较新的 OpenAI SDK。旧版本可能没有 client.responses。

安装 OpenAI SDK

使用 pip 安装

# 安装或升级到最新版本
pip install --upgrade 'openai>=1.0'

# 验证安装
python -c "import openai; print(openai.__version__)"

使用 poetry 安装

poetry add "openai>=1.0"

快速开始

获取 API Key

访问智谱开放平台
注册并登录您的账户
在 API Keys 管理页面创建 API Key
复制您的 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 秒。

基础配置
环境变量
配置类

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://open.bigmodel.cn/api/v1",
    timeout=7200
)

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
)

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 传字符串，等价于一条用户文本。

cURL
Python
TypeScript

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。"
  }'

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)

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]。

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。

多轮对话

默认 store=false，响应不会落库。需要查询或续写时，创建时设置 store=true，下一轮传入 previous_response_id。当前没有 cancel 接口。

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）

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。

函数调用

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。

图像理解

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，迁移到智谱非常简单：

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
GET	`/responses/{response_id}`	查询 Response
GET	`/responses/{response_id}/input_items`	查询输入项列表
DELETE	`/responses/{response_id}`	删除 Response

创建 Response

查看完整请求、响应字段与流式事件

OpenAI Responses 文档

参考 OpenAI 官方文档了解协议形态

​核心优势

独立协议

SDK 可复用

有状态多轮

工具与多模态

​环境要求

Python 版本

OpenAI SDK

​安装 OpenAI SDK

​使用 pip 安装

​使用 poetry 安装

​快速开始

​获取 API Key

​创建客户端

​基础使用示例

​简单调用

​流式响应

​多轮对话

​高级功能

​推理（reasoning）

​函数调用

​图像理解

​参数配置

​常用参数说明

​实践建议

性能优化

成本控制

安全性

可靠性

​迁移指南

​从 OpenAI Responses 迁移

​接口一览

​更多资源

创建 Response

OpenAI Responses 文档

核心优势

环境要求

安装 OpenAI SDK

使用 pip 安装

使用 poetry 安装

快速开始

获取 API Key

创建客户端

基础使用示例

简单调用

流式响应

多轮对话

高级功能

推理（reasoning）

函数调用

图像理解

参数配置

常用参数说明

实践建议

迁移指南

从 OpenAI Responses 迁移

接口一览

更多资源