OpenAI API参考文档 | OpenAI开发文档|OpenAI中文官方文档|ChatGPT中文版|ChatGPT教程

消息（v1）
Legacy

在话题中创建消息source

创建消息（v1）
Legacy

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

创建消息。source

路径参数

thread_id

字符串source

必填

要为其创建消息的线程的 ID。source

请求正文

角色

字符串source

必填

创建消息的实体的角色。允许的值包括：source

user：表示消息是由实际用户发送的，在大多数情况下应该用于表示用户生成的消息。
assistant：表示消息由助手生成。使用此值可将来自助手的消息插入到对话中。

内容

字符串source

必填

消息的内容。source

file_ids

数组source

可选

默认为 []

消息应使用的文件 ID 列表。一条消息最多可以附加 10 个文件。适用于以下工具retrieval和code_interpreter可以访问和使用文件。source

元数据

地图source

可选

一组 16 个可附加到对象的键值对。这对于以结构化格式存储有关对象的其他信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。source

消息对象。source

示例请求

1
2
3
4
5
6
7
8
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."
    }'

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

thread_message = client.beta.threads.messages.create(
  "thread_abc123",
  role="user",
  content="How does AI work? Explain it in simple terms.",
)
print(thread_message)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const threadMessages = await openai.beta.threads.messages.create(
    "thread_abc123",
    { role: "user", content: "How does AI work? Explain it in simple terms." }
  );

  console.log(threadMessages);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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）
Legacy

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

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

路径参数

thread_id

字符串source

必填

消息所属线程的 ID。source

查询参数

限制

整数source

可选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。source

次序

字符串source

可选

默认为 desc

按created_at对象的时间戳。asc对于升序和desc以降序排列。source

后

字符串source

可选

用于分页的游标。after是定义您在列表中的位置的对象 ID。例如，如果您发出列表请求并收到 100 个对象，以 obj_foo 结尾，则您的后续调用可以包含 after=obj_foo 以便获取列表的下一页。source

以前

字符串source

可选

用于分页的游标。before是定义您在列表中的位置的对象 ID。例如，如果您发出一个列表请求并收到 100 个对象，以 obj_foo 结尾，则您的后续调用可以包含 before=obj_foo 以便获取列表的上一页。source

run_id

字符串source

可选

按生成消息的运行 ID 筛选消息。source

消息对象列表。source

示例请求

1
2
3
4
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"

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

thread_messages = client.beta.threads.messages.list("thread_abc123")
print(thread_messages.data)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const threadMessages = await openai.beta.threads.messages.list(
    "thread_abc123"
  );

  console.log(threadMessages.data);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
  "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）
Legacy

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

返回消息文件列表。source

路径参数

thread_id

字符串source

必填

消息和文件所属的线程的 ID。source

message_id

字符串source

必填

文件所属消息的 ID。source

查询参数

限制

整数source

可选

默认为 20

要返回的对象数量限制。Limit 的范围可以介于 1 和 100 之间，默认值为 20。source

次序

字符串source

可选

默认为 desc

按created_at对象的时间戳。asc对于升序和desc以降序排列。source

后

字符串source

可选

以前

字符串source

可选

消息文件对象列表。source

示例请求

1
2
3
4
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"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

message_files = client.beta.threads.messages.files.list(
  thread_id="thread_abc123",
  message_id="msg_abc123"
)
print(message_files)

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const messageFiles = await openai.beta.threads.messages.files.list(
    "thread_abc123",
    "msg_abc123"
  );
  console.log(messageFiles);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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）
Legacy

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

检索消息。source

路径参数

thread_id

字符串source

必填

此消息所属的线程的 ID。source

message_id

字符串source

必填

要检索的消息的 ID。source

与指定 ID 匹配的 message 对象。source

示例请求

1
2
3
4
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"

1
2
3
4
5
6
7
8
from openai import OpenAI
client = OpenAI()

message = client.beta.threads.messages.retrieve(
  message_id="msg_abc123",
  thread_id="thread_abc123",
)
print(message)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const message = await openai.beta.threads.messages.retrieve(
    "thread_abc123",
    "msg_abc123"
  );

  console.log(message);
}

main();

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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）
Legacy

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

检索消息文件。source

路径参数

thread_id

字符串source

必填

消息和 File 所属的线程的 ID。source

message_id

字符串source

必填

文件所属消息的 ID。source

file_id

字符串source

必填

正在检索的文件的 ID。source

消息文件对象。source

示例请求

1
2
3
4
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"

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

message_files = client.beta.threads.messages.files.retrieve(
    thread_id="thread_abc123",
    message_id="msg_abc123",
    file_id="file-abc123"
)
print(message_files)

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";
const openai = new OpenAI();

async function main() {
  const messageFile = await openai.beta.threads.messages.files.retrieve(
    "thread_abc123",
    "msg_abc123",
    "file-abc123"
  );
  console.log(messageFile);
}

main();

响应

1
2
3
4
5
6
{
  "id": "file-abc123",
  "object": "thread.message.file",
  "created_at": 1699061776,
  "message_id": "msg_abc123"
}

修改消息（v1）
Legacy

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

修改消息。source

路径参数

thread_id

字符串source

必填

此消息所属的线程的 ID。source

message_id

字符串source

必填

要修改的消息的 ID。source

请求正文

元数据

地图source

可选

修改后的 message 对象。source

示例请求

1
2
3
4
5
6
7
8
9
10
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"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
from openai import OpenAI
client = OpenAI()

message = client.beta.threads.messages.update(
  message_id="msg_abc12",
  thread_id="thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123",
  },
)
print(message)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const message = await openai.beta.threads.messages.update(
    "thread_abc123",
    "msg_abc123",
    {
      metadata: {
        modified: "true",
        user: "abc123",
      },
    }
  }'

响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "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）
Legacy

表示线程中的消息。source

身份证

字符串source

标识符，可在 API 终端节点中引用。source

对象

字符串source

对象类型，始终为thread.message.source

created_at

整数source

创建消息时的 Unix 时间戳（以秒为单位）。source

thread_id

字符串source

此消息所属的线程 ID。source

地位

字符串source

消息的状态，可以是in_progress,incomplete或completed.source

incomplete_details

object 或 nullsource

在未完成的消息中，有关消息未完成原因的详细信息。source

completed_at

整数或 nullsource

消息完成时的 Unix 时间戳（以秒为单位）。source

incomplete_at

整数或 nullsource

消息标记为未完成时的 Unix 时间戳（以秒为单位）。source

角色

字符串source

生成消息的实体。其中之一user或assistant.source

内容

数组source

文本和/或图像数组中的消息内容。source

assistant_id

string 或 nullsource

如果适用，则为创作此消息的助手的 ID。source

run_id

string 或 nullsource

与创建此消息关联的运行的 ID。值为null使用 Create Message 或 Create Thread 端点手动创建消息时。source

file_ids

数组source

助理应使用的文件 ID 列表。对于检索和code_interpreter等可以访问文件的工具很有用。一条消息最多可以附加 10 个文件。source

元数据

地图source

OBJECT 消息对象（v1）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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）
Legacy

附加到message.source

身份证

字符串source

标识符，可在 API 终端节点中引用。source

对象

字符串source

对象类型，始终为thread.message.file.source

created_at

整数source

创建消息文件时的 Unix 时间戳（以秒为单位）。source

message_id

字符串source

File 附加到的消息的 ID。source

OBJECT 消息文件对象（v1）

1
2
3
4
5
6
7
{
  "id": "file-abc123",
  "object": "thread.message.file",
  "created_at": 1698107661,
  "message_id": "message_QLoItBbqwyAJEzlTy4y9kOMM",
  "file_id": "file-abc123"
}

消息 （v1）Legacy

创建消息 （v1）Legacy

路径参数

请求正文

返回

列出消息 （v1）Legacy

路径参数

查询参数

返回

列出消息文件 （v1）Legacy

路径参数

查询参数

返回

检索消息 （v1）Legacy

路径参数

返回

检索消息文件 （v1）Legacy

路径参数

返回

修改消息 （v1）Legacy

路径参数

请求正文

返回

消息对象 （v1）Legacy

消息文件对象 （v1）Legacy

消息（v1）
Legacy

创建消息（v1）
Legacy

列出消息（v1）
Legacy

列出消息文件（v1）
Legacy

检索消息（v1）
Legacy

检索消息文件（v1）
Legacy

修改消息（v1）
Legacy

消息对象（v1）
Legacy

消息文件对象（v1）
Legacy