OpenAI 创建 ChatKit 会话
post /chatkit/sessions
创建一个 ChatKit 会话。
请求体参数
内容类型为 application/json。
user: string
标识应用终端用户的字符串。会话可访问归属同一 user 的其他对象。
minLength: 1
workflow: ChatSessionWorkflowParam
驱动会话的工作流。
id: string
会话所调用工作流的标识符。
state_variables: optional map[string or number or boolean or number]
传给工作流的状态变量。键最多 64 个字符,值须为基本类型。该映射默认为空对象。
string
maxLength: 10485760
number
boolean
number
tracing: optional object { enabled }
可选。覆盖工作流调用的追踪设置。省略时默认启用追踪。
enabled: optional boolean
是否在会话中启用追踪,默认为 true。
version: optional string
要执行的工作流版本,默认使用最新部署版本。
chatkit_configuration: optional ChatSessionChatKitConfigurationParam
可选。覆盖 ChatKit 运行时功能设置。
automatic_thread_titling: optional object { enabled }
自动生成线程标题的设置。省略时默认启用。
enabled: optional boolean
是否自动生成线程标题,默认为 true。
file_upload: optional object { enabled, max_file_size, max_files }
配置是否允许上传及上传限额。省略时默认禁用上传,max_files 默认为 10,max_file_size 默认为 512 MB。
enabled: optional boolean
是否允许在本次会话中上传文件,默认为 false。
max_file_size: optional integer
单个上传文件的大小上限,单位为 MB。默认值和允许的最大值均为 512 MB。
minimum: 1, maximum: 512
max_files: optional integer
本次会话允许上传的文件数量上限,默认为 10。
minimum: 1
history: optional object { enabled, recent_threads }
聊天记录保留设置。省略时默认开启历史记录,recent_threads 为 null,表示线程数不限。
enabled: optional boolean
允许用户访问此前的 ChatKit 线程,默认为 true。
recent_threads: optional integer
用户可以访问的最近 ChatKit 线程数,省略时不限。
minimum: 1
expires_after: optional ChatSessionExpiresAfterParam
可选。设置会话创建后的有效期,单位为秒。默认为 10 分钟。
anchor: "created_at" (default: "created_at")
计算到期时间的基准,当前固定为 created_at。
"created_at"
seconds: integer
从基准时间到会话到期的秒数。
format: int64, minimum: 1, maximum: 600
rate_limits: optional ChatSessionRateLimitsParam
可选。覆盖每分钟请求上限,省略时默认为 10。
max_requests_per_1_minute: optional integer
会话每分钟允许的最大请求数,默认为 10。
minimum: 1
返回值
ChatSession object { id, chatkit_configuration, client_secret, 7 more }
ChatKit 会话及其生效配置。
id: string
ChatKit 会话的标识符。
chatkit_configuration: ChatSessionChatKitConfiguration
本次会话生效的 ChatKit 功能配置。
automatic_thread_titling: ChatSessionAutomaticThreadTitling
自动生成线程标题的设置。
enabled: boolean
是否启用自动生成线程标题。
file_upload: ChatSessionFileUpload
会话的上传设置。
enabled: boolean
是否允许在本次会话中上传文件。
max_file_size: integer or null
单个上传文件的大小上限,单位为 MB。
max_files: integer or null
本次会话允许上传的文件数量上限。
history: ChatSessionHistory
聊天记录保留设置。
enabled: boolean
本次会话是否持久保留聊天记录。
recent_threads: integer or null
历史记录视图中可显示的既往线程数。保留全部历史时默认为 null。
client_secret: string
用于验证会话请求的临时客户端密钥。
expires_at: integer
会话到期的 Unix 时间戳,单位为秒。
format: unixtime
max_requests_per_1_minute: integer
每分钟请求上限的副本,便于直接读取。
object: "chatkit.session" (default: "chatkit.session")
对象类型,固定为 chatkit.session。
"chatkit.session"
rate_limits: ChatSessionRateLimits
实际生效的速率限制。
max_requests_per_1_minute: integer
每个一分钟时间窗口内允许的最大请求数。
status: ChatSessionStatus
会话当前的生命周期状态。
"active"
"expired"
"cancelled"
user: string
与会话关联的用户标识符。
workflow: ChatKitWorkflow
会话所用工作流的元数据。
id: string
为该会话提供支持的工作流标识符。
state_variables: map[string or number or boolean or number] or null
调用工作流时应用的状态变量键值对。未提供覆盖值时默认为 null。
string
number
boolean
number
tracing: object { enabled }
应用于工作流的追踪设置。
enabled: boolean
是否启用追踪。
version: string or null
会话使用的具体工作流版本。使用最新部署版本时默认为 null。
请求示例
## 在服务端设置 OPENAI_API_KEY 环境变量。
## 将 user 和 workflow.id 替换为真实的用户标识符与已部署的工作流 ID。
curl https://api.openai.com/v1/chatkit/sessions \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: chatkit_beta=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"user": "x",
"workflow": {
"id": "id"
}
}'
200 响应示例
{
"id": "cksess_123",
"chatkit_configuration": {
"automatic_thread_titling": {
"enabled": true
},
"file_upload": {
"enabled": true,
"max_file_size": 16,
"max_files": 20
},
"history": {
"enabled": true,
"recent_threads": 10
}
},
"client_secret": "ek_token_123",
"expires_at": 1712349876,
"max_requests_per_1_minute": 60,
"object": "chatkit.session",
"rate_limits": {
"max_requests_per_1_minute": 60
},
"status": "active",
"user": "user_789",
"workflow": {
"id": "workflow_alpha",
"state_variables": {
"message": "你好"
},
"tracing": {
"enabled": true
},
"version": "2024-10-01"
}
}
请求示例
## 在服务端设置 OPENAI_API_KEY 环境变量。
## 将 user 和 workflow.id 替换为真实的用户标识符与已部署的工作流 ID。
curl https://api.openai.com/v1/chatkit/sessions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: chatkit_beta=v1" \
-d '{
"user": "user_123",
"workflow": {"id": "workflow_alpha"}
}'
响应示例
{
"id": "cksess_123",
"object": "chatkit.session",
"client_secret": "ek_example_00eyJleHBpcmVzX2F0IjogMTczNTY4OTYwMH0=",
"expires_at": 1735689600,
"workflow": {
"id": "workflow_alpha",
"version": null,
"state_variables": null,
"tracing": {
"enabled": true
}
},
"user": "user_123",
"rate_limits": {
"max_requests_per_1_minute": 10
},
"max_requests_per_1_minute": 10,
"status": "active",
"chatkit_configuration": {
"automatic_thread_titling": {
"enabled": true
},
"file_upload": {
"enabled": false,
"max_file_size": 512,
"max_files": 10
},
"history": {
"enabled": true,
"recent_threads": null
}
}
}
如需把会话接入网页组件,请参阅 ChatKit 指南。
可对活动会话调用取消 ChatKit 会话 以停止使用该会话已签发的客户端密钥发起新请求。

TRAE-AI编程


更多建议: