OpenAI CTO

消息 Beta

创建线程中的消息。

相关指南：助手概览

创建消息 Beta

创建一个消息。

路径参数

  • thread_id（string，必需）：要为其创建消息的线程的 ID。

请求体

  • role（string，必需）：创建消息的实体的角色。允许的值包括：
    • user：表示消息由实际用户发送，大多数情况下应使用此值表示用户生成的消息。
    • assistant：表示消息由助手生成。使用此值将助手的消息插入到对话中。
  • content（string 或 array，必需）：消息的内容。
  • attachments（array 或 null，可选）：附加到消息的文件列表及其应添加到的工具。
  • metadata（map，可选）：可以附加到对象的 16 对键值对。这对于以结构化格式存储有关对象的额外信息很有用。键最长可以是 64 个字符，值最长可以是 512 个字符。

返回

返回一个消息对象。

示例请求

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
      "role": "user",
      "content": "How does AI work? Explain it in simple terms."
    }'

{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1713226573,
  "assistant_id": null,
  "thread_id": "thread_abc123",
  "run_id": null,
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "attachments": [],
  "metadata": {}
}

列出消息 Beta

返回给定线程的消息列表。

路径参数

  • thread_id（string，必需）：消息所属的线程的 ID。

查询参数

  • limit（integer，可选）：返回对象的数量限制。限制可以在 1 到 100 之间选择，默认为 20。
  • order（string，可选）：按对象的 created_at 时间戳排序。asc 代表升序，desc 代表降序，默认为 desc。
  • after（string，可选）：用于分页的游标。after 是一个对象 ID，定义了你在列表中的位置。例如，如果你发起一个列表请求并收到 100 个对象，以 obj_foo 结束，你的后续调用可以包括 after=obj_foo 以获取列表的下一页。
  • before（string，可选）：用于分页的游标。before 是一个对象 ID，定义了你在列表中的位置。例如，如果你发起一个列表请求并收到 100 个对象，以 obj_foo 结束，你的后续调用可以包括 before=obj_foo 以获取列表的前一页。
  • run_id（string，可选）：通过生成它们的 run ID 过滤消息。

返回

返回一个消息对象列表。

示例请求

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

响应

{
  "object": "list",
  "data": [
    {
      "id": "msg_abc123",
      "object": "thread.message",
      "created_at": 1699016383,
      "assistant_id": null,
      "thread_id": "thread_abc123",
      "run_id": null,
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": {
            "value": "How does AI work? Explain it in simple terms.",
            "annotations": []
          }
        }
      ],
      "attachments": [],
      "metadata": {}
    },
    {
      "id": "msg_abc456",
      "object": "thread.message",
      "created_at": 1699016383,
      "assistant_id": null,
      "thread_id": "thread_abc123",
      "run_id": null,
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": {
            "value": "Hello, what is AI?",
            "annotations": []
          }
        }
      ],
      "attachments": [],
      "metadata": {}
    }
  ],
  "first_id": "msg_abc123",
  "last_id": "msg_abc456",
  "has_more": false
}

检索消息 Beta

检索一条消息。

路径参数

  • thread_id（string，必需）：此消息所属的线程的 ID。
  • message_id（string，必需）：要检索的消息的 ID。

返回

返回与指定 ID 匹配的消息对象。

示例请求

curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

响应

{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699017614,
  "assistant_id": null,
  "thread_id": "thread_abc123",
  "run_id": null,
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "attachments": [],
  "metadata": {}
}

修改消息 Beta

修改一条消息。

路径参数

  • thread_id（string，必需）：此消息所属的线程的 ID。
  • message_id（string，必需）：要修改的消息的 ID。

请求体

  • metadata（map，可选）：可以附加到对象的 16 对键值对。这对于以结构化格式存储有关对象的额外信息很有用。键最长可以是 64 个字符，值最长可以是 512 个字符。

返回

返回修改后的消息对象。

示例请求

curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
      "metadata": {
        "modified": "true",
        "user": "abc123"
      }
    }'

响应

{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699017614,
  "assistant_id": null,
  "thread_id": "thread_abc123",
  "run_id": null,
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "file_ids": [],
  "metadata": {
    "modified": "true",
    "user": "abc123"
  }
}

删除消息 Beta

删除一条消息。

路径参数

  • thread_id（string，必需）：此消息所属的线程的 ID。
  • message_id（string，必需）：要删除的消息的 ID。

返回

返回删除状态。

示例请求

curl -X DELETE https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

响应

{
  "id": "msg_abc123",
  "object": "thread.message.deleted",
  "deleted": true
}

消息对象（Beta版）

表示线程中的消息。

名称类型描述
idstring可在API端点中引用的标识符。
objectstring对象类型，始终为“thread.message”。
created_atinteger创建消息的Unix时间戳（以秒为单位）。
thread_idstring此消息所属的线程ID。
statusstring消息的状态，可以是“in_progress”、“incomplete”或“completed”。
incomplete_detailsobject or null在不完整的消息上，有关消息不完整的详细信息。
completed_atinteger or null完成消息的Unix时间戳（以秒为单位）。
incomplete_atinteger or null将消息标记为不完整的Unix时间戳（以秒为单位）。
rolestring产生消息的实体。其中之一为“user”或“assistant”。
contentarray消息的内容，以文本和/或图像的数组形式。
assistant_idstring or null如果适用，则为助手作者此消息的ID。
run_idstring or null与此消息创建相关联的运行的ID。当使用创建消息或创建线程端点手动创建消息时，值为“null”。
attachmentsarray or null附加到消息的文件以及将其添加到的工具列表。
metadatamap可以附加到对象的最多16个键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键最多可以是64个字符，值最多可以是512个字符。

示例消息对象：

{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1698983503,
  "thread_id": "thread_abc123",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "Hi! How can I help you today?",
        "annotations": []
      }
    }
  ],
  "assistant_id": "asst_abc123",
  "run_id": "run_abc123",
  "attachments": [],
  "metadata": {}
}

Was this page helpful?