Create a message.

POST /threads/{thread_id}/messages

Api key auth

Path parameters

thread_id string Required

The ID of the thread to create a message for.

application/json

Body Required

role string Required
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.
Values are user or assistant.
content string | array[object] Required
One of:
Text content string Array of content parts array[object]

The text contents of the message.
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.

At least 1 element.
One of:
MessageContentImageFileObject object MessageContentImageUrlObject object MessageRequestContentTextObject object

References an image File in the content of a message.

Hide attributes Show attributes

type string Required

Always image_file.

Value is image_file.

image_file object Required

Hide image_file attributes Show image_file attributes object

file_id string Required

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 string

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.

Values are auto, low, or high. Default value is auto.

References an image URL in the content of a message.

Hide attributes Show attributes

type string Required

The type of the content part.

Value is image_url.

image_url object Required

Hide image_url attributes Show image_url attributes object

url string(uri) Required

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

detail string

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

Values are auto, low, or high. Default value is auto.
attachments array[object] | null

A list of files attached to the message, and the tools they should be added to.
Hide attachments attributes Show attachments attributes object
- file_id string
  
  The ID of the file to attach to the message.
- tools array[object]
  
  The tools to add this file to.
  One of:
  AssistantToolsCode object AssistantToolsFileSearchTypeOnly object
metadata object | null

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.
Hide metadata attribute Show metadata attribute object | null
- * string Additional properties

Responses

200 application/json

OK
Hide response attributes Show response attributes object
- id string Required
  
  The identifier, which can be referenced in API endpoints.
- object string Required
  
  The object type, which is always thread.message.
  
  Value is thread.message.
- created_at integer Required
  
  The Unix timestamp (in seconds) for when the message was created.
- thread_id string Required
  
  The thread ID that this message belongs to.
- status string Required
  
  The status of the message, which can be either in_progress, incomplete, or completed.
  
  Values are in_progress, incomplete, or completed.
- incomplete_details object | null Required
  
  On an incomplete message, details about why the message is incomplete.
  
  Hide incomplete_details attribute Show incomplete_details attribute object | null
  
  reason string Required
  
  The reason the message is incomplete.
  
  Values are content_filter, max_tokens, run_cancelled, run_expired, or run_failed.
- completed_at integer | null Required
  
  The Unix timestamp (in seconds) for when the message was completed.
- incomplete_at integer | null Required
  
  The Unix timestamp (in seconds) for when the message was marked as incomplete.
- role string Required
  
  The entity that produced the message. One of user or assistant.
  
  Values are user or assistant.
- content array[object] Required
  
  The content of the message in array of text and/or images.
  
  One of:
  MessageContentImageFileObject object MessageContentImageUrlObject object MessageContentTextObject object MessageContentRefusalObject object
  
  References an image File in the content of a message.
  
  Hide attributes Show attributes
  
  type string Required
  
  Always image_file.
  
  Value is image_file.
  
  image_file object Required
  
  Hide image_file attributes Show image_file attributes object
  
  file_id string Required
  
  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 string
  
  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.
  
  Values are auto, low, or high. Default value is auto.
  
  References an image URL in the content of a message.
  
  Hide attributes Show attributes
  
  type string Required
  
  The type of the content part.
  
  Value is image_url.
  
  image_url object Required
  
  Hide image_url attributes Show image_url attributes object
  
  url string(uri) Required
  
  The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp.
  
  detail string
  
  Specifies the detail level of the image. low uses fewer tokens, you can opt in to high resolution using high. Default value is auto
  
  Values are auto, low, or high. Default value is auto.
  
  The text content that is part of a message.
  
  Hide attributes Show attributes
  
  type string Required
  
  Always text.
  
  Value is text.
  
  text object Required
  
  Hide text attributes Show text attributes object
  
  value string Required
  
  The data that makes up the text.
  
  annotations array[object] Required
  
  One of:
  MessageContentTextAnnotationsFileCitationObject object MessageContentTextAnnotationsFilePathObject object
  
  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.
  
  Hide attributes Show attributes
  
  type string Required
  
  Always file_citation.
  
  Value is file_citation.
  
  text string Required
  
  The text in the message content that needs to be replaced.
  
  file_citation object Required
  
  Hide file_citation attribute Show file_citation attribute object
  
  file_id string Required
  
  The ID of the specific File the citation is from.
  
  start_index integer Required
  
  Minimum value is 0.
  
  end_index integer Required
  
  Minimum value is 0.
  
  A URL for the file that's generated when the assistant used the code_interpreter tool to generate a file.
  
  Hide attributes Show attributes
  
  type string Required
  
  Always file_path.
  
  Value is file_path.
  
  text string Required
  
  The text in the message content that needs to be replaced.
  
  file_path object Required
  
  Hide file_path attribute Show file_path attribute object
  
  file_id string Required
  
  The ID of the file that was generated.
  
  start_index integer Required
  
  Minimum value is 0.
  
  end_index integer Required
  
  Minimum value is 0.
- assistant_id string | null Required
  
  If applicable, the ID of the assistant that authored this message.
- run_id string | null Required
  
  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.
- attachments array[object] | null Required
  
  A list of files attached to the message, and the tools they were added to.
  
  Hide attachments attributes Show attachments attributes object
  
  file_id string
  
  The ID of the file to attach to the message.
  
  tools array[object]
  
  The tools to add this file to.
  
  One of:
  AssistantToolsCode object AssistantToolsFileSearchTypeOnly object
- metadata object | null Required
  
  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.
  
  Hide metadata attribute Show metadata attribute object | null
  
  * string Additional properties

POST /threads/{thread_id}/messages

curl \
 --request POST 'https://api.openai.com/v1/threads/{thread_id}/messages' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"role":"user","content":"string","attachments":[{"file_id":"string","tools":[{"type":"code_interpreter"}]}],"metadata":{"additionalProperty1":"string","additionalProperty2":"string"}}'

Request examples

{
  "role": "user",
  "content": "string",
  "attachments": [
    {
      "file_id": "string",
      "tools": [
        {
          "type": "code_interpreter"
        }
      ]
    }
  ],
  "metadata": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  }
}

Response examples (200)

{
  "id": "string",
  "object": "thread.message",
  "created_at": 42,
  "thread_id": "string",
  "status": "in_progress",
  "incomplete_details": {
    "reason": "content_filter"
  },
  "completed_at": 42,
  "incomplete_at": 42,
  "role": "user",
  "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "string",
        "detail": "auto"
      }
    }
  ],
  "assistant_id": "string",
  "run_id": "string",
  "attachments": [
    {
      "file_id": "string",
      "tools": [
        {
          "type": "code_interpreter"
        }
      ]
    }
  ],
  "metadata": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  }
}

Create a message.

Path parameters

Body Required

content string | array[object] Required

Responses