OpenAI 列出 ChatKit 线程条目

2026-11-19 09:55 更新

get /chatkit/threads/{thread_id}/items

列出指定 ChatKit 线程的条目。

路径参数

  • thread_id: string

要查询其条目的 ChatKit 线程标识符。

查询参数

  • after: optional string

列出此 ID 之后创建的记录。请求第一页时默认为 null。

  • before: optional string

列出此 ID 之前创建的记录。获取最新结果时默认为 null。

  • limit: optional integer

每页最多返回的线程条目数,默认为 20。

minimum: 0, maximum: 100

  • order: optional "asc" or "desc"

按创建时间排序,默认为 desc(降序)。asc 表示升序。

  • "asc"

  • "desc"

返回值

  • ChatKitThreadItemList object { data, first_id, has_more, 2 more }

ChatKit API 返回的线程条目分页列表。

  • data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more

线程列表。

  • ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }

用户在线程中发出的消息。

  • id: string

线程条目的标识符。

  • attachments: array of ChatKitAttachment

用户消息中的附件,默认为空列表。

  • id: string

附件标识符。

  • mime_type: string

附件的 MIME 类型。

  • name: string

附件的原始显示名称。

  • preview_url: string or null

用于在当前视图内预览附件的 URL。

format: uri

  • type: "image" or "file"

附件类型。

  • "image"

  • "file"

  • content: array of InputText { text, type } or QuotedText { text, type }

用户提供的内容元素,按顺序排列。

  • InputText object { text, type }

用户在线程中输入的文本块。

  • text: string

用户提供的纯文本。

  • type: "input_text" (default: "input_text")

内容类型,固定为 input_text。

  • "input_text"

  • QuotedText object { text, type }

用户在消息中引用的片段。

  • text: string

引用的文本内容。

  • type: "quoted_text" (default: "quoted_text")

内容类型,固定为 quoted_text。

  • "quoted_text"

  • created_at: integer

条目创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • inference_options: object { model, tool_choice } or null

此消息使用的推理设置覆盖值。未设置时默认为 null。

  • model: string or null

生成响应的模型名称。使用会话默认模型时,该值默认为 null。

  • tool_choice: object { id } or null

优先调用的工具。由 ChatKit 自动选择时默认为 null。

  • id: string

请求调用的工具标识符。

  • object: "chatkit.thread_item" (default: "chatkit.thread_item")

对象类型,固定为 chatkit.thread_item。

  • "chatkit.thread_item"

  • thread_id: string

所属线程的标识符。

  • type: "chatkit.user_message" (default: "chatkit.user_message")

  • "chatkit.user_message"

  • ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }

助手在线程中发出的消息。

  • id: string

线程条目的标识符。

  • content: array of ChatKitResponseOutputText

助手响应的各个片段,按顺序排列。

  • annotations: array of File { source, type } or URL { source, type }

响应文本附带的注解,按顺序排列。

  • File object { source, type }

引用已上传文件的注解。

  • source: object { filename, type }

注解引用的文件附件。

  • filename: string

注解引用的文件名。

  • type: "file" (default: "file")

类型标记固定为 file。

  • "file"

  • type: "file" (default: "file")

此注解的类型固定为 file。

  • "file"

  • URL object { source, type }

引用 URL 的注解。

  • source: object { type, url }

注解引用的 URL。

  • type: "url" (default: "url")

类型标记固定为 url。

  • "url"

  • url: string

注解引用的 URL。

format: uri

  • type: "url" (default: "url")

此注解的类型固定为 url。

  • "url"

  • text: string

助手生成的文本。

  • type: "output_text" (default: "output_text")

内容类型,固定为 output_text。

  • "output_text"

  • created_at: integer

条目创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • object: "chatkit.thread_item" (default: "chatkit.thread_item")

对象类型,固定为 chatkit.thread_item。

  • "chatkit.thread_item"

  • thread_id: string

所属线程的标识符。

  • type: "chatkit.assistant_message" (default: "chatkit.assistant_message")

条目类型,固定为 chatkit.assistant_message。

  • "chatkit.assistant_message"

  • ChatKitWidgetItem object { id, created_at, object, 3 more }

用于呈现界面组件数据的线程条目。

  • id: string

线程条目的标识符。

  • created_at: integer

条目创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • object: "chatkit.thread_item" (default: "chatkit.thread_item")

对象类型,固定为 chatkit.thread_item。

  • "chatkit.thread_item"

  • thread_id: string

所属线程的标识符。

  • type: "chatkit.widget" (default: "chatkit.widget")

条目类型,固定为 chatkit.widget。

  • "chatkit.widget"

  • widget: string

在用户界面中呈现的序列化组件数据。

  • ChatKitClientToolCall object { id, arguments, call_id, 7 more }

助手发起的客户端工具调用记录。

  • id: string

线程条目的标识符。

  • arguments: string

传给工具的参数,采用 JSON 编码。

  • call_id: string

客户端工具调用的标识符。

  • created_at: integer

条目创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • name: string

被调用的工具名称。

  • object: "chatkit.thread_item" (default: "chatkit.thread_item")

对象类型,固定为 chatkit.thread_item。

  • "chatkit.thread_item"

  • output: string or null

记录的工具输出,采用 JSON 编码。执行期间默认为 null。

  • status: "in_progress" or "completed"

工具调用的执行状态。

  • "in_progress"

  • "completed"

  • thread_id: string

所属线程的标识符。

  • type: "chatkit.client_tool_call" (default: "chatkit.client_tool_call")

条目类型,固定为 chatkit.client_tool_call。

  • "chatkit.client_tool_call"

  • ChatKitTask object { id, created_at, heading, 5 more }

工作流发出的任务,用于显示进度和状态更新。

  • id: string

线程条目的标识符。

  • created_at: integer

条目创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • heading: string or null

可选的任务标题,未提供时默认为 null。

  • object: "chatkit.thread_item" (default: "chatkit.thread_item")

对象类型,固定为 chatkit.thread_item。

  • "chatkit.thread_item"

  • summary: string or null

可选的任务摘要,省略时默认为 null。

  • task_type: "custom" or "thought"

任务的子类型。

  • "custom"

  • "thought"

  • thread_id: string

所属线程的标识符。

  • type: "chatkit.task" (default: "chatkit.task")

条目类型,固定为 chatkit.task。

  • "chatkit.task"

  • ChatKitTaskGroup object { id, created_at, object, 3 more }

在线程中归为一组的工作流任务。

  • id: string

线程条目的标识符。

  • created_at: integer

条目创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • object: "chatkit.thread_item" (default: "chatkit.thread_item")

对象类型,固定为 chatkit.thread_item。

  • "chatkit.thread_item"

  • tasks: array of object { heading, summary, type }

该组包含的任务。

  • heading: string or null

可选的任务组标题,未提供时默认为 null。

  • summary: string or null

可选的任务组摘要,省略时默认为 null。

  • type: "custom" or "thought"

组内任务的子类型。

  • "custom"

  • "thought"

  • thread_id: string

所属线程的标识符。

  • type: "chatkit.task_group" (default: "chatkit.task_group")

条目类型,固定为 chatkit.task_group。

  • "chatkit.task_group"

  • first_id: string or null

列表中第一条记录的 ID。

  • has_more: boolean

是否还有更多记录。

  • last_id: string or null

列表中最后一条记录的 ID。

  • object: "list" (default: "list")

返回对象的类型,固定为 list。

  • "list"

请求示例

## 在服务端设置 OPENAI_API_KEY 环境变量。
## 将线程 ID 替换为目标线程 ID。可用 limit 指定每页返回的条目数。
curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID/items \
    -H 'OpenAI-Beta: chatkit_beta=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

200 响应示例

{
  "data": [
    {
      "id": "id",
      "attachments": [
        {
          "id": "id",
          "mime_type": "mime_type",
          "name": "name",
          "preview_url": "https://example.com",
          "type": "image"
        }
      ],
      "content": [
        {
          "text": "示例消息",
          "type": "input_text"
        }
      ],
      "created_at": 0,
      "inference_options": {
        "model": "model",
        "tool_choice": {
          "id": "id"
        }
      },
      "object": "chatkit.thread_item",
      "thread_id": "thread_id",
      "type": "chatkit.user_message"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}

请求示例

## 在服务端设置 OPENAI_API_KEY 环境变量。
## 将线程 ID 替换为目标线程 ID。可用 limit 指定每页返回的条目数。
curl "https://api.openai.com/v1/chatkit/threads/cthr_abc123/items?limit=3" \
  -H "OpenAI-Beta: chatkit_beta=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

响应示例

{
  "data": [
    {
      "id": "cthi_user_001",
      "object": "chatkit.thread_item",
      "type": "chatkit.user_message",
      "content": [
        {
          "type": "input_text",
          "text": "我需要排查一个使用引导中的问题。"
        }
      ],
      "attachments": [],
      "created_at": 1712345600,
      "thread_id": "cthr_abc123",
      "inference_options": null
    },
    {
      "id": "cthi_assistant_002",
      "object": "chatkit.thread_item",
      "type": "chatkit.assistant_message",
      "content": [
        {
          "type": "output_text",
          "text": "先确认你部署的工作流版本。",
          "annotations": []
        }
      ],
      "created_at": 1712345601,
      "thread_id": "cthr_abc123"
    }
  ],
  "has_more": false,
  "object": "list",
  "first_id": "cthi_user_001",
  "last_id": "cthi_assistant_002"
}
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号