OpenAI CTO

消息 (v1)

Legacy

在线程中创建消息。

相关指南：助手概述

创建消息 (v1)

POST https://api.openai.com/v1/threads/{thread_id}/messages

功能说明

创建一条消息。

路径参数

参数名称类型是否必需描述
thread_idstring必需要为其创建消息的 线程 的 ID。

请求体

参数名称类型是否必需描述
rolestring必需创建消息的实体的角色。允许的值包括:
  • user: 表示消息由实际用户发送,应该用于大多数情况下表示用户生成的消息。
  • assistant: 表示消息由助手生成。使用此值将消息从助手插入到对话中。
contentstring必需消息的内容。
file_idsarray可选消息应使用的 文件 ID 列表。每条消息最多可以附加 10 个文件。对于像 retrieval 和 code_interpreter 这样可以访问和使用文件的工具很有用。
metadatamap可选一组最多 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=v1" \
  -d '{
      "role": "user",
      "content": "How does AI work? Explain it in simple terms."
    }'

示例响应

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

列出消息 (v1)

GET https://api.openai.com/v1/threads/{thread_id}/messages

功能说明

返回一个指定线程的消息列表。

路径参数

参数名称类型是否必需描述
thread_idstring必需消息所属的 线程 的 ID。

查询参数

参数名称类型是否必需默认值描述
limitinteger可选20要返回的对象数量限制。限制范围是 1 到 100,默认值为 20。
orderstring可选desc按 created_at 时间戳对对象进行排序。可选值为 asc（升序）和 desc（降序）。
afterstring可选-用于分页的游标。after 是一个对象 ID,定义了您在列表中的位置。例如,如果您发出一个列表请求并收到 100 个对象,以 obj_foo 结尾,则后续调用可以包含 after=obj_foo 以获取列表的下一页。
beforestring可选-用于分页的游标。before 是一个对象 ID,定义了您在列表中的位置。例如,如果您发出一个列表请求并收到 100 个对象,以 obj_foo 结尾,则后续调用可以包含 before=obj_foo 以获取列表的上一页。
run_idstring可选-按生成它们的运行 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=v1"

示例响应

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

列出消息文件 (v1)

GET https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files

功能说明

返回一个消息文件列表。

路径参数

参数名称类型是否必需描述
thread_idstring必需消息和文件所属的线程的 ID。
message_idstring必需文件所属的消息的 ID。

查询参数

参数名称类型是否必需默认值描述
limitinteger可选20要返回的对象数量限制。限制范围是 1 到 100,默认值为 20。
orderstring可选desc按 created_at 时间戳对对象进行排序。可选值为 asc（升序）和 desc（降序）。
afterstring可选-用于分页的游标。after 是一个对象 ID,定义了您在列表中的位置。例如,如果您发出一个列表请求并收到 100 个对象,以 obj_foo 结尾,则后续调用可以包含 after=obj_foo 以获取列表的下一页。
beforestring可选-用于分页的游标。before 是一个对象 ID,定义了您在列表中的位置。例如,如果您发出一个列表请求并收到 100 个对象,以 obj_foo 结尾,则后续调用可以包含 before=obj_foo 以获取列表的上一页。

返回值

一个 消息文件 对象列表。

示例请求

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

示例响应

{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "thread.message.file",
      "created_at": 1699061776,
      "message_id": "msg_abc123"
    },
    {
      "id": "file-abc123",
      "object": "thread.message.file",
      "created_at": 1699061776,
      "message_id": "msg_abc123"
    }
  ],
  "first_id": "file-abc123",
  "last_id": "file-abc123",
  "has_more": false
}

获取消息 (v1)

GET https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}

功能说明

获取一个指定 ID 的消息。

路径参数

参数名称类型是否必需描述
thread_idstring必需此消息所属的 线程 的 ID。
message_idstring必需要获取的消息的 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=v1"

示例响应

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

获取消息文件 (v1)

GET https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}/files/{file_id}

功能说明

获取一个指定 ID 的消息文件。

路径参数

参数名称类型是否必需描述
thread_idstring必需消息和文件所属的线程的 ID。
message_idstring必需文件所属的消息的 ID。
file_idstring必需要获取的文件的 ID。

返回值

与指定 ID 匹配的 消息文件 对象。

示例请求

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

示例响应

{
  "id": "file-abc123",
  "object": "thread.message.file",
  "created_at": 1699061776,
  "message_id": "msg_abc123"
}

修改消息 (v1)

POST https://api.openai.com/v1/threads/{thread_id}/messages/{message_id}

功能说明

修改一条消息。

路径参数

参数名称类型是否必需描述
thread_idstring必需此消息所属的线程的 ID。
message_idstring必需要修改的消息的 ID。

请求体

参数名称类型是否必需描述
metadatamap可选一组最多 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=v1" \
  -d '{
      "metadata": {
        "modified": "true",
        "user": "abc123"
      }
    }'

示例响应

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

消息对象 (v1)

表示 线程中的一条消息。

参数名称类型描述
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与此消息的创建关联的 run ID。当使用创建消息或创建线程端点手动创建消息时,该值为 null。
file_idsarray助手应使用的 文件 ID 列表。每条消息最多可以附加 10 个文件。
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": []
      }
    }
  ],
  "file_ids": [],
  "assistant_id": "asst_abc123",
  "run_id": "run_abc123",
  "metadata": {}
}

消息文件对象 (v1)

附加到 message 的文件列表。

参数名称类型描述
idstring可在 API 端点中引用的标识符。
objectstring对象类型,始终为 thread.message.file。
created_atinteger创建消息文件的 Unix 时间戳(秒)。
message_idstring此 文件 附加到的 消息 的 ID。

示例:

{
  "id": "file-abc123",
  "object": "thread.message.file",
  "created_at": 1698107661,
  "message_id": "message_QLoItBbqwyAJEzlTy4y9kOMM"
}

Was this page helpful?