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

Messages (v1)
Legacy

Create messages within threadssource

Related guide: Assistants source

Create message (v1)
Legacy

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

Create a message.source

Path parameters

thread_id

stringsource

Required

The ID of the thread to create a message for.source

Request body

role

stringsource

Required

The role of the entity that is creating the message. Allowed values include:source

user: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages.
assistant: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation.

content

stringsource

Required

The content of the message.source

file_ids

arraysource

Optional

Defaults to []

A list of File IDs that the message should use. There can be a maximum of 10 files attached to a message. Useful for tools like retrieval and code_interpreter that can access and use files.source

metadata

mapsource

Optional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.source

Returns

A message object.source

Example request

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();

Response

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": {}
}

List messages (v1)
Legacy

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

Returns a list of messages for a given thread.source

Path parameters

thread_id

stringsource

Required

The ID of the thread the messages belong to.source

Query parameters

limit

integersource

Optional

Defaults to 20

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.source

order

stringsource

Optional

Defaults to desc

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.source

after

stringsource

Optional

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.source

before

stringsource

Optional

A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.source

run_id

stringsource

Optional

Filter messages by the run ID that generated them.source

Returns

A list of message objects.source

Example request

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();

Response

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
}

List message files (v1)
Legacy

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

Returns a list of message files.source

Path parameters

thread_id

stringsource

Required

The ID of the thread that the message and files belong to.source

message_id

stringsource

Required

The ID of the message that the files belongs to.source

Query parameters

limit

integersource

Optional

Defaults to 20

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.source

order

stringsource

Optional

Defaults to desc

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.source

after

stringsource

Optional

before

stringsource

Optional

Returns

A list of message file objects.source

Example request

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();

Response

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
}

Retrieve message (v1)
Legacy

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

Retrieve a message.source

Path parameters

thread_id

stringsource

Required

The ID of the thread to which this message belongs.source

message_id

stringsource

Required

The ID of the message to retrieve.source

Returns

The message object matching the specified ID.source

Example request

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();

Response

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": {}
}

Retrieve message file (v1)
Legacy

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

Retrieves a message file.source

Path parameters

thread_id

stringsource

Required

The ID of the thread to which the message and File belong.source

message_id

stringsource

Required

The ID of the message the file belongs to.source

file_id

stringsource

Required

The ID of the file being retrieved.source

Returns

The message file object.source

Example request

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();

Response

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

Modify message (v1)
Legacy

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

Modifies a message.source

Path parameters

thread_id

stringsource

Required

The ID of the thread to which this message belongs.source

message_id

stringsource

Required

The ID of the message to modify.source

Request body

metadata

mapsource

Optional

Returns

The modified message object.source

Example request

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",
      },
    }
  }'

Response

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"
  }
}

The message object (v1)
Legacy

Represents a message within a thread.source

stringsource

The identifier, which can be referenced in API endpoints.source

object

stringsource

The object type, which is always thread.message.source

created_at

integersource

The Unix timestamp (in seconds) for when the message was created.source

thread_id

stringsource

The thread ID that this message belongs to.source

status

stringsource

The status of the message, which can be either in_progress, incomplete, or completed.source

incomplete_details

object or nullsource

On an incomplete message, details about why the message is incomplete.source

completed_at

integer or nullsource

The Unix timestamp (in seconds) for when the message was completed.source

incomplete_at

integer or nullsource

The Unix timestamp (in seconds) for when the message was marked as incomplete.source

role

stringsource

The entity that produced the message. One of user or assistant.source

content

arraysource

The content of the message in array of text and/or images.source

assistant_id

string or nullsource

If applicable, the ID of the assistant that authored this message.source

run_id

string or nullsource

The ID of the run associated with the creation of this message. Value is null when messages are created manually using the create message or create thread endpoints.source

file_ids

arraysource

A list of file IDs that the assistant should use. Useful for tools like retrieval and code_interpreter that can access files. A maximum of 10 files can be attached to a message.source

metadata

mapsource

OBJECT The message 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": {}
}

The message file object (v1)
Legacy

A list of files attached to a message.source

stringsource

The identifier, which can be referenced in API endpoints.source

object

stringsource

The object type, which is always thread.message.file.source

created_at

integersource

The Unix timestamp (in seconds) for when the message file was created.source

message_id

stringsource

The ID of the message that the File is attached to.source

OBJECT The message file 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"
}

Messages (v1)Legacy

Create message (v1)Legacy

Path parameters

Request body

Returns

List messages (v1)Legacy

Path parameters

Query parameters

Returns

List message files (v1)Legacy

Path parameters

Query parameters

Returns

Retrieve message (v1)Legacy

Path parameters

Returns

Retrieve message file (v1)Legacy

Path parameters

Returns

Modify message (v1)Legacy

Path parameters

Request body

Returns

The message object (v1)Legacy

The message file object (v1)Legacy

Messages (v1)
Legacy

Create message (v1)
Legacy

List messages (v1)
Legacy

List message files (v1)
Legacy

Retrieve message (v1)
Legacy

Retrieve message file (v1)
Legacy

Modify message (v1)
Legacy

The message object (v1)
Legacy

The message file object (v1)
Legacy