OpenAI 列出 ChatKit 线程条目
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"
}
TRAE-AI编程


更多建议: