Skip to content
API Reference
Beta
Threads
Messages

Create message

Deprecated
beta.threads.messages.create(strthread_id, MessageCreateParams**kwargs) -> Message
POST/threads/{thread_id}/messages

Create a message.

ParametersExpand Collapse
thread_id: str
content: Union[str, Iterable[MessageContentPartParam]]

The text contents of the message.

Accepts one of the following:
str

The text contents of the message.

Iterable[MessageContentPartParam]

An array of content parts with a defined type, each can be of type text or images can be passed with image_url or image_file. Image types are only supported on Vision-compatible models.

Accepts one of the following:
class ImageFileContentBlock: …

References an image File in the content of a message.

image_file: ImageFile
file_id: str

The File ID of the image in the message content. Set purpose="vision" when uploading the File if you need to later display the file content.

detail: Optional[Literal["auto", "low", "high"]]

Specifies the detail level of the image if specified by the user. low uses fewer tokens, you can opt in to high resolution using high.

Accepts one of the following:
"auto"
"low"
"high"
type: Literal["image_file"]

Always image_file.

class ImageURLContentBlock: …

References an image URL in the content of a message.

image_url: ImageURL
url: str

The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp.

formaturi
detail: Optional[Literal["auto", "low", "high"]]

Specifies the detail level of the image. low uses fewer tokens, you can opt in to high resolution using high. Default value is auto

Accepts one of the following:
"auto"
"low"
"high"
type: Literal["image_url"]

The type of the content part.

class TextContentBlockParam: …

The text content that is part of a message.

text: str

Text content to be sent to the model

type: Literal["text"]

Always text.

role: Literal["user", "assistant"]

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

  • 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.
Accepts one of the following:
"user"
"assistant"
attachments: Optional[Iterable[Attachment]]

A list of files attached to the message, and the tools they should be added to.

file_id: Optional[str]

The ID of the file to attach to the message.

tools: Optional[Iterable[AttachmentTool]]

The tools to add this file to.

Accepts one of the following:
class CodeInterpreterTool: …
type: Literal["code_interpreter"]

The type of tool being defined: code_interpreter

class AttachmentToolFileSearch: …
type: Literal["file_search"]

The type of tool being defined: file_search

metadata: Optional[Metadata]

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, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

ReturnsExpand Collapse
class Message: …

Represents a message within a thread.

id: str

The identifier, which can be referenced in API endpoints.

assistant_id: Optional[str]

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

attachments: Optional[List[Attachment]]

A list of files attached to the message, and the tools they were added to.

file_id: Optional[str]

The ID of the file to attach to the message.

tools: Optional[List[AttachmentTool]]

The tools to add this file to.

Accepts one of the following:
class CodeInterpreterTool: …
type: Literal["code_interpreter"]

The type of tool being defined: code_interpreter

class AttachmentToolAssistantToolsFileSearchTypeOnly: …
type: Literal["file_search"]

The type of tool being defined: file_search

completed_at: Optional[int]

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

content: List[MessageContent]

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

Accepts one of the following:
class ImageFileContentBlock: …

References an image File in the content of a message.

image_file: ImageFile
file_id: str

The File ID of the image in the message content. Set purpose="vision" when uploading the File if you need to later display the file content.

detail: Optional[Literal["auto", "low", "high"]]

Specifies the detail level of the image if specified by the user. low uses fewer tokens, you can opt in to high resolution using high.

Accepts one of the following:
"auto"
"low"
"high"
type: Literal["image_file"]

Always image_file.

class ImageURLContentBlock: …

References an image URL in the content of a message.

image_url: ImageURL
url: str

The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp.

formaturi
detail: Optional[Literal["auto", "low", "high"]]

Specifies the detail level of the image. low uses fewer tokens, you can opt in to high resolution using high. Default value is auto

Accepts one of the following:
"auto"
"low"
"high"
type: Literal["image_url"]

The type of the content part.

class TextContentBlock: …

The text content that is part of a message.

text: Text
annotations: List[Annotation]
Accepts one of the following:
class FileCitationAnnotation: …

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files.

end_index: int
minimum0
file_citation: FileCitation
file_id: str

The ID of the specific File the citation is from.

start_index: int
minimum0
text: str

The text in the message content that needs to be replaced.

type: Literal["file_citation"]

Always file_citation.

class FilePathAnnotation: …

A URL for the file that's generated when the assistant used the code_interpreter tool to generate a file.

end_index: int
minimum0
file_path: FilePath
file_id: str

The ID of the file that was generated.

start_index: int
minimum0
text: str

The text in the message content that needs to be replaced.

type: Literal["file_path"]

Always file_path.

value: str

The data that makes up the text.

type: Literal["text"]

Always text.

class RefusalContentBlock: …

The refusal content generated by the assistant.

refusal: str
type: Literal["refusal"]

Always refusal.

created_at: int

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

incomplete_at: Optional[int]

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

incomplete_details: Optional[IncompleteDetails]

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

reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]

The reason the message is incomplete.

Accepts one of the following:
"content_filter"
"max_tokens"
"run_cancelled"
"run_expired"
"run_failed"
metadata: Optional[Metadata]

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, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

object: Literal["thread.message"]

The object type, which is always thread.message.

role: Literal["user", "assistant"]

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

Accepts one of the following:
"user"
"assistant"
run_id: Optional[str]

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.

status: Literal["in_progress", "incomplete", "completed"]

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

Accepts one of the following:
"in_progress"
"incomplete"
"completed"
thread_id: str

The thread ID that this message belongs to.

Create message

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
message = client.beta.threads.messages.create(
    thread_id="thread_id",
    content="string",
    role="user",
)
print(message.id)
{
  "id": "id",
  "assistant_id": "assistant_id",
  "attachments": [
    {
      "file_id": "file_id",
      "tools": [
        {
          "type": "code_interpreter"
        }
      ]
    }
  ],
  "completed_at": 0,
  "content": [
    {
      "image_file": {
        "file_id": "file_id",
        "detail": "auto"
      },
      "type": "image_file"
    }
  ],
  "created_at": 0,
  "incomplete_at": 0,
  "incomplete_details": {
    "reason": "content_filter"
  },
  "metadata": {
    "foo": "string"
  },
  "object": "thread.message",
  "role": "user",
  "run_id": "run_id",
  "status": "in_progress",
  "thread_id": "thread_id"
}
Returns Examples
{
  "id": "id",
  "assistant_id": "assistant_id",
  "attachments": [
    {
      "file_id": "file_id",
      "tools": [
        {
          "type": "code_interpreter"
        }
      ]
    }
  ],
  "completed_at": 0,
  "content": [
    {
      "image_file": {
        "file_id": "file_id",
        "detail": "auto"
      },
      "type": "image_file"
    }
  ],
  "created_at": 0,
  "incomplete_at": 0,
  "incomplete_details": {
    "reason": "content_filter"
  },
  "metadata": {
    "foo": "string"
  },
  "object": "thread.message",
  "role": "user",
  "run_id": "run_id",
  "status": "in_progress",
  "thread_id": "thread_id"
}