OpenAI 创建 ChatKit 会话

2026-11-19 09:55 更新

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 会话 以停止使用该会话已签发的客户端密钥发起新请求。

以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号