diff --git a/en/python/resources/beta/subresources/threads/index.md b/en/python/resources/beta/subresources/threads/index.md index bba6cb39..5dd1719a 100644 --- a/en/python/resources/beta/subresources/threads/index.md +++ b/en/python/resources/beta/subresources/threads/index.md @@ -6,7 +6,7 @@ **post** `/threads` -Create thread +Create a thread. ### Parameters @@ -30,7 +30,7 @@ Create thread References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `image_file: ImageFileParam` + - `image_file: ImageFile` - `file_id: str` @@ -56,7 +56,7 @@ Create thread References an image URL in the content of a message. - - `image_url: ImageURLParam` + - `image_url: ImageURL` - `url: str` @@ -361,7 +361,7 @@ print(message_thread) **post** `/threads/runs` -Create thread and run +Create a thread and run it in one request. ### Parameters @@ -676,7 +676,7 @@ Create thread and run References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `image_file: ImageFileParam` + - `image_file: ImageFile` - `file_id: str` @@ -702,7 +702,7 @@ Create thread and run References an image URL in the content of a message. - - `image_url: ImageURLParam` + - `image_url: ImageURL` - `url: str` @@ -916,10 +916,76 @@ Create thread and run The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. -- `tools: Optional[Iterable[object]]` +- `tools: Optional[Iterable[AssistantToolParam]]` Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + - `class CodeInterpreterTool: …` + + - `class FileSearchTool: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `file_search: Optional[FileSearch]` + + Overrides for the file search tool. + + - `max_num_results: Optional[int]` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `class FunctionTool: …` + + - `function: FunctionDefinition` + + - `name: str` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: Optional[str]` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: Optional[FunctionParameters]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: Optional[bool]` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: Literal["function"]` + + The type of tool being defined: `function` + + - `"function"` + - `top_p: Optional[float]` An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. @@ -1162,7 +1228,27 @@ Create thread and run The Unix timestamp (in seconds) for when the run was started. - - `status: object` + - `status: RunStatus` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: str` @@ -1206,10 +1292,82 @@ Create thread and run The name of the function to call. - - `tools: List[object]` + - `tools: List[AssistantTool]` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class FileSearchTool: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `file_search: Optional[FileSearch]` + + Overrides for the file search tool. + + - `max_num_results: Optional[int]` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `class FunctionTool: …` + + - `function: FunctionDefinition` + + - `name: str` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: Optional[str]` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: Optional[FunctionParameters]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: Optional[bool]` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: Literal["function"]` + + The type of tool being defined: `function` + + - `"function"` + - `truncation_strategy: Optional[TruncationStrategy]` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -1309,11 +1467,13 @@ for thread in client.beta.threads.create_and_run( }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -1549,7 +1709,7 @@ data: [DONE] **get** `/threads/{thread_id}` -Retrieve thread +Retrieves a thread. ### Parameters @@ -1672,7 +1832,7 @@ print(my_thread) **post** `/threads/{thread_id}` -Modify thread +Modifies a thread. ### Parameters @@ -1825,7 +1985,7 @@ print(my_updated_thread) **delete** `/threads/{thread_id}` -Delete thread +Delete a thread. ### Parameters @@ -2104,7 +2264,7 @@ print(response) **get** `/threads/{thread_id}/runs` -List runs +Returns a list of runs belonging to a thread. ### Parameters @@ -2350,7 +2510,27 @@ List runs The Unix timestamp (in seconds) for when the run was started. - - `status: object` + - `status: RunStatus` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: str` @@ -2394,10 +2574,82 @@ List runs The name of the function to call. - - `tools: List[object]` + - `tools: List[AssistantTool]` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class FileSearchTool: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `file_search: Optional[FileSearch]` + + Overrides for the file search tool. + + - `max_num_results: Optional[int]` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `class FunctionTool: …` + + - `function: FunctionDefinition` + + - `name: str` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: Optional[str]` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: Optional[FunctionParameters]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: Optional[bool]` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: Literal["function"]` + + The type of tool being defined: `function` + + - `"function"` + - `truncation_strategy: Optional[TruncationStrategy]` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -2500,11 +2752,13 @@ print(page.id) }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -2652,7 +2906,7 @@ print(runs) **post** `/threads/{thread_id}/runs` -Create run +Create a run. ### Parameters @@ -2694,7 +2948,7 @@ Create run References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `image_file: ImageFileParam` + - `image_file: ImageFile` - `file_id: str` @@ -2720,7 +2974,7 @@ Create run References an image URL in the content of a message. - - `image_url: ImageURLParam` + - `image_url: ImageURL` - `url: str` @@ -3148,10 +3402,76 @@ Create run The name of the function to call. -- `tools: Optional[Iterable[object]]` +- `tools: Optional[Iterable[AssistantToolParam]]` Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + - `class CodeInterpreterTool: …` + + - `class FileSearchTool: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `file_search: Optional[FileSearch]` + + Overrides for the file search tool. + + - `max_num_results: Optional[int]` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `class FunctionTool: …` + + - `function: FunctionDefinition` + + - `name: str` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: Optional[str]` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: Optional[FunctionParameters]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: Optional[bool]` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: Literal["function"]` + + The type of tool being defined: `function` + + - `"function"` + - `top_p: Optional[float]` An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. @@ -3394,18 +3714,38 @@ Create run The Unix timestamp (in seconds) for when the run was started. - - `status: object` + - `status: RunStatus` - - `thread_id: str` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + - `"queued"` - - `tool_choice: Optional[AssistantToolChoiceOption]` + - `"in_progress"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` + + - `thread_id: str` + + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. + + - `tool_choice: Optional[AssistantToolChoiceOption]` + + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - `Literal["none", "auto", "required"]` @@ -3438,10 +3778,82 @@ Create run The name of the function to call. - - `tools: List[object]` + - `tools: List[AssistantTool]` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class FileSearchTool: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `file_search: Optional[FileSearch]` + + Overrides for the file search tool. + + - `max_num_results: Optional[int]` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `class FunctionTool: …` + + - `function: FunctionDefinition` + + - `name: str` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: Optional[str]` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: Optional[FunctionParameters]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: Optional[bool]` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: Literal["function"]` + + The type of tool being defined: `function` + + - `"function"` + - `truncation_strategy: Optional[TruncationStrategy]` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -3542,11 +3954,13 @@ for run in client.beta.threads.runs.create( }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -3772,7 +4186,7 @@ data: [DONE] **get** `/threads/{thread_id}/runs/{run_id}` -Retrieve run +Retrieves a run. ### Parameters @@ -4000,7 +4414,27 @@ Retrieve run The Unix timestamp (in seconds) for when the run was started. - - `status: object` + - `status: RunStatus` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: str` @@ -4044,10 +4478,82 @@ Retrieve run The name of the function to call. - - `tools: List[object]` + - `tools: List[AssistantTool]` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class FileSearchTool: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `file_search: Optional[FileSearch]` + + Overrides for the file search tool. + + - `max_num_results: Optional[int]` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `class FunctionTool: …` + + - `function: FunctionDefinition` + + - `name: str` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: Optional[str]` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: Optional[FunctionParameters]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: Optional[bool]` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: Literal["function"]` + + The type of tool being defined: `function` + + - `"function"` + - `truncation_strategy: Optional[TruncationStrategy]` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -4148,11 +4654,13 @@ print(run.id) }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -4232,7 +4740,7 @@ print(run) **post** `/threads/{thread_id}/runs/{run_id}` -Modify run +Modifies a run. ### Parameters @@ -4469,7 +4977,27 @@ Modify run The Unix timestamp (in seconds) for when the run was started. - - `status: object` + - `status: RunStatus` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: str` @@ -4513,10 +5041,82 @@ Modify run The name of the function to call. - - `tools: List[object]` + - `tools: List[AssistantTool]` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class FileSearchTool: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `file_search: Optional[FileSearch]` + + Overrides for the file search tool. + + - `max_num_results: Optional[int]` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `class FunctionTool: …` + + - `function: FunctionDefinition` + + - `name: str` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: Optional[str]` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: Optional[FunctionParameters]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: Optional[bool]` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: Literal["function"]` + + The type of tool being defined: `function` + + - `"function"` + - `truncation_strategy: Optional[TruncationStrategy]` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -4617,11 +5217,13 @@ print(run.id) }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -4712,7 +5314,7 @@ print(run) **post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` -Submit tool outputs to run +When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request. ### Parameters @@ -4958,7 +5560,27 @@ Submit tool outputs to run The Unix timestamp (in seconds) for when the run was started. - - `status: object` + - `status: RunStatus` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: str` @@ -5002,19 +5624,91 @@ Submit tool outputs to run The name of the function to call. - - `tools: List[object]` + - `tools: List[AssistantTool]` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. - - `truncation_strategy: Optional[TruncationStrategy]` + - `class CodeInterpreterTool: …` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `type: Literal["code_interpreter"]` - - `type: Literal["auto", "last_messages"]` + The type of tool being defined: `code_interpreter` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `"code_interpreter"` - - `"auto"` + - `class FileSearchTool: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `file_search: Optional[FileSearch]` + + Overrides for the file search tool. + + - `max_num_results: Optional[int]` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `class FunctionTool: …` + + - `function: FunctionDefinition` + + - `name: str` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: Optional[str]` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: Optional[FunctionParameters]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: Optional[bool]` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: Literal["function"]` + + The type of tool being defined: `function` + + - `"function"` + + - `truncation_strategy: Optional[TruncationStrategy]` + + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + + - `type: Literal["auto", "last_messages"]` + + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + + - `"auto"` - `"last_messages"` @@ -5107,11 +5801,13 @@ for run in client.beta.threads.runs.submit_tool_outputs( }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -5286,7 +5982,7 @@ data: [DONE] **post** `/threads/{thread_id}/runs/{run_id}/cancel` -Cancel a run +Cancels a run that is `in_progress`. ### Parameters @@ -5514,7 +6210,27 @@ Cancel a run The Unix timestamp (in seconds) for when the run was started. - - `status: object` + - `status: RunStatus` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: str` @@ -5558,10 +6274,82 @@ Cancel a run The name of the function to call. - - `tools: List[object]` + - `tools: List[AssistantTool]` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class FileSearchTool: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `file_search: Optional[FileSearch]` + + Overrides for the file search tool. + + - `max_num_results: Optional[int]` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `class FunctionTool: …` + + - `function: FunctionDefinition` + + - `name: str` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: Optional[str]` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: Optional[FunctionParameters]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: Optional[bool]` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: Literal["function"]` + + The type of tool being defined: `function` + + - `"function"` + - `truncation_strategy: Optional[TruncationStrategy]` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -5662,11 +6450,13 @@ print(run.id) }, "response_format": "auto", "started_at": 0, - "status": {}, + "status": "queued", "thread_id": "thread_id", "tool_choice": "none", "tools": [ - {} + { + "type": "code_interpreter" + } ], "truncation_strategy": { "type": "auto", @@ -5984,7 +6774,27 @@ print(run) The Unix timestamp (in seconds) for when the run was started. - - `status: object` + - `status: RunStatus` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` - `thread_id: str` @@ -6028,10 +6838,82 @@ print(run) The name of the function to call. - - `tools: List[object]` + - `tools: List[AssistantTool]` The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class FileSearchTool: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `file_search: Optional[FileSearch]` + + Overrides for the file search tool. + + - `max_num_results: Optional[int]` + + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: Optional[Literal["auto", "default_2024_08_21"]]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `class FunctionTool: …` + + - `function: FunctionDefinition` + + - `name: str` + + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + + - `description: Optional[str]` + + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: Optional[FunctionParameters]` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: Optional[bool]` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](https://platform.openai.com/docs/guides/function-calling). + + - `type: Literal["function"]` + + The type of tool being defined: `function` + + - `"function"` + - `truncation_strategy: Optional[TruncationStrategy]` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -6074,7 +6956,27 @@ print(run) ### Run Status -- `object` +- `Literal["queued", "in_progress", "requires_action", 6 more]` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` # Steps @@ -6084,7 +6986,7 @@ print(run) **get** `/threads/{thread_id}/runs/{run_id}/steps` -List run steps +Returns a list of run steps belonging to a run. ### Parameters @@ -6227,45 +7129,189 @@ List run steps Details of the tool call. - - `tool_calls: List[object]` + - `tool_calls: List[ToolCall]` An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `type: Literal["tool_calls"]` + - `class CodeInterpreterToolCall: …` - Always `tool_calls`. + Details of the Code Interpreter tool call the run step was involved in. - - `"tool_calls"` + - `id: str` - - `thread_id: str` + The ID of the tool call. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `code_interpreter: CodeInterpreter` - - `type: Literal["message_creation", "tool_calls"]` + The Code Interpreter tool call definition. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `input: str` - - `"message_creation"` + The input to the Code Interpreter tool call. - - `"tool_calls"` + - `outputs: List[CodeInterpreterOutput]` - - `usage: Optional[Usage]` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `class CodeInterpreterOutputLogs: …` - - `completion_tokens: int` + Text output from the Code Interpreter tool call as part of a run step. - Number of completion tokens used over the course of the run step. + - `logs: str` - - `prompt_tokens: int` + The text output from the Code Interpreter tool call. - Number of prompt tokens used over the course of the run step. + - `type: Literal["logs"]` - - `total_tokens: int` + Always `logs`. - Total number of tokens used (prompt + completion). + - `"logs"` -### Example + - `class CodeInterpreterOutputImage: …` + + - `image: CodeInterpreterOutputImageImage` + + - `file_id: str` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `type: Literal["image"]` + + Always `image`. + + - `"image"` + + - `type: Literal["code_interpreter"]` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `"code_interpreter"` + + - `class FileSearchToolCall: …` + + - `id: str` + + The ID of the tool call object. + + - `file_search: FileSearch` + + For now, this is always going to be an empty object. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. + + - `ranker: Literal["auto", "default_2024_08_21"]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `results: Optional[List[FileSearchResult]]` + + The results of the file search. + + - `file_id: str` + + The ID of the file that result was found in. + + - `file_name: str` + + The name of the file that result was found in. + + - `score: float` + + The score of the result. All values must be a floating point number between 0 and 1. + + - `content: Optional[List[FileSearchResultContent]]` + + The content of the result that was found. The content is only included if requested via the include query parameter. + + - `text: Optional[str]` + + The text content of the file. + + - `type: Optional[Literal["text"]]` + + The type of the content. + + - `"text"` + + - `type: Literal["file_search"]` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `"file_search"` + + - `class FunctionToolCall: …` + + - `id: str` + + The ID of the tool call object. + + - `function: Function` + + The definition of the function that was called. + + - `arguments: str` + + The arguments passed to the function. + + - `name: str` + + The name of the function. + + - `output: Optional[str]` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + + - `type: Literal["function"]` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `"function"` + + - `type: Literal["tool_calls"]` + + Always `tool_calls`. + + - `"tool_calls"` + + - `thread_id: str` + + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + + - `type: Literal["message_creation", "tool_calls"]` + + The type of run step, which can be either `message_creation` or `tool_calls`. + + - `"message_creation"` + + - `"tool_calls"` + + - `usage: Optional[Usage]` + + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + + - `completion_tokens: int` + + Number of completion tokens used over the course of the run step. + + - `prompt_tokens: int` + + Number of prompt tokens used over the course of the run step. + + - `total_tokens: int` + + Total number of tokens used (prompt + completion). + +### Example ```python import os @@ -6386,7 +7432,7 @@ print(run_steps) **get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` -Retrieve run step +Retrieves a run step. ### Parameters @@ -6511,124 +7557,268 @@ Retrieve run step Details of the tool call. - - `tool_calls: List[object]` + - `tool_calls: List[ToolCall]` An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `type: Literal["tool_calls"]` + - `class CodeInterpreterToolCall: …` - Always `tool_calls`. + Details of the Code Interpreter tool call the run step was involved in. - - `"tool_calls"` + - `id: str` - - `thread_id: str` + The ID of the tool call. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `code_interpreter: CodeInterpreter` - - `type: Literal["message_creation", "tool_calls"]` + The Code Interpreter tool call definition. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `input: str` - - `"message_creation"` + The input to the Code Interpreter tool call. - - `"tool_calls"` + - `outputs: List[CodeInterpreterOutput]` - - `usage: Optional[Usage]` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `class CodeInterpreterOutputLogs: …` - - `completion_tokens: int` + Text output from the Code Interpreter tool call as part of a run step. - Number of completion tokens used over the course of the run step. + - `logs: str` - - `prompt_tokens: int` + The text output from the Code Interpreter tool call. - Number of prompt tokens used over the course of the run step. + - `type: Literal["logs"]` - - `total_tokens: int` + Always `logs`. - Total number of tokens used (prompt + completion). + - `"logs"` -### Example + - `class CodeInterpreterOutputImage: …` -```python -import os -from openai import OpenAI + - `image: CodeInterpreterOutputImageImage` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -run_step = client.beta.threads.runs.steps.retrieve( - step_id="step_id", - thread_id="thread_id", - run_id="run_id", -) -print(run_step.id) -``` + - `file_id: str` -#### Response + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expired_at": 0, - "failed_at": 0, - "last_error": { - "code": "server_error", - "message": "message" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" - }, - "type": "message_creation" - }, - "thread_id": "thread_id", - "type": "message_creation", - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - } -} -``` + - `type: Literal["image"]` -### Example + Always `image`. -```python -from openai import OpenAI -client = OpenAI() + - `"image"` -run_step = client.beta.threads.runs.steps.retrieve( - thread_id="thread_abc123", - run_id="run_abc123", - step_id="step_abc123" -) + - `type: Literal["code_interpreter"]` -print(run_step) -``` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. -#### Response + - `"code_interpreter"` -```json -{ - "id": "step_abc123", - "object": "thread.run.step", - "created_at": 1699063291, - "run_id": "run_abc123", - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "type": "message_creation", + - `class FileSearchToolCall: …` + + - `id: str` + + The ID of the tool call object. + + - `file_search: FileSearch` + + For now, this is always going to be an empty object. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. + + - `ranker: Literal["auto", "default_2024_08_21"]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `results: Optional[List[FileSearchResult]]` + + The results of the file search. + + - `file_id: str` + + The ID of the file that result was found in. + + - `file_name: str` + + The name of the file that result was found in. + + - `score: float` + + The score of the result. All values must be a floating point number between 0 and 1. + + - `content: Optional[List[FileSearchResultContent]]` + + The content of the result that was found. The content is only included if requested via the include query parameter. + + - `text: Optional[str]` + + The text content of the file. + + - `type: Optional[Literal["text"]]` + + The type of the content. + + - `"text"` + + - `type: Literal["file_search"]` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `"file_search"` + + - `class FunctionToolCall: …` + + - `id: str` + + The ID of the tool call object. + + - `function: Function` + + The definition of the function that was called. + + - `arguments: str` + + The arguments passed to the function. + + - `name: str` + + The name of the function. + + - `output: Optional[str]` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + + - `type: Literal["function"]` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `"function"` + + - `type: Literal["tool_calls"]` + + Always `tool_calls`. + + - `"tool_calls"` + + - `thread_id: str` + + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + + - `type: Literal["message_creation", "tool_calls"]` + + The type of run step, which can be either `message_creation` or `tool_calls`. + + - `"message_creation"` + + - `"tool_calls"` + + - `usage: Optional[Usage]` + + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + + - `completion_tokens: int` + + Number of completion tokens used over the course of the run step. + + - `prompt_tokens: int` + + Number of prompt tokens used over the course of the run step. + + - `total_tokens: int` + + Total number of tokens used (prompt + completion). + +### Example + +```python +import os +from openai import OpenAI + +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +run_step = client.beta.threads.runs.steps.retrieve( + step_id="step_id", + thread_id="thread_id", + run_id="run_id", +) +print(run_step.id) +``` + +#### Response + +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.run.step", + "run_id": "run_id", + "status": "in_progress", + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } +} +``` + +### Example + +```python +from openai import OpenAI +client = OpenAI() + +run_step = client.beta.threads.runs.steps.retrieve( + thread_id="thread_abc123", + run_id="run_abc123", + step_id="step_abc123" +) + +print(run_step) +``` + +#### Response + +```json +{ + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", "status": "completed", "cancelled_at": null, "completed_at": 1699063291, @@ -7090,123 +8280,153 @@ print(run_step) Details of the tool call. - - `tool_calls: List[object]` + - `tool_calls: List[ToolCall]` An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `type: Literal["tool_calls"]` + - `class CodeInterpreterToolCall: …` - Always `tool_calls`. + Details of the Code Interpreter tool call the run step was involved in. - - `"tool_calls"` + - `id: str` - - `thread_id: str` + The ID of the tool call. - The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. + - `code_interpreter: CodeInterpreter` - - `type: Literal["message_creation", "tool_calls"]` + The Code Interpreter tool call definition. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `input: str` - - `"message_creation"` + The input to the Code Interpreter tool call. - - `"tool_calls"` + - `outputs: List[CodeInterpreterOutput]` - - `usage: Optional[Usage]` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `class CodeInterpreterOutputLogs: …` - - `completion_tokens: int` + Text output from the Code Interpreter tool call as part of a run step. - Number of completion tokens used over the course of the run step. + - `logs: str` - - `prompt_tokens: int` + The text output from the Code Interpreter tool call. - Number of prompt tokens used over the course of the run step. + - `type: Literal["logs"]` - - `total_tokens: int` + Always `logs`. - Total number of tokens used (prompt + completion). + - `"logs"` -### Run Step Delta + - `class CodeInterpreterOutputImage: …` -- `object` + - `image: CodeInterpreterOutputImageImage` -### Run Step Delta Event + - `file_id: str` -- `class RunStepDeltaEvent: …` + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `type: Literal["image"]` - - `id: str` + Always `image`. - The identifier of the run step, which can be referenced in API endpoints. + - `"image"` - - `delta: object` + - `type: Literal["code_interpreter"]` - - `object: Literal["thread.run.step.delta"]` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The object type, which is always `thread.run.step.delta`. + - `"code_interpreter"` - - `"thread.run.step.delta"` + - `class FileSearchToolCall: …` -### Run Step Delta Message Delta + - `id: str` -- `class RunStepDeltaMessageDelta: …` + The ID of the tool call object. - Details of the message creation by the run step. + - `file_search: FileSearch` - - `type: Literal["message_creation"]` + For now, this is always going to be an empty object. - Always `message_creation`. + - `ranking_options: Optional[FileSearchRankingOptions]` - - `"message_creation"` + The ranking options for the file search. - - `message_creation: Optional[MessageCreation]` + - `ranker: Literal["auto", "default_2024_08_21"]` - - `message_id: Optional[str]` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The ID of the message that was created by this run step. + - `"auto"` -### Run Step Include + - `"default_2024_08_21"` -- `Literal["step_details.tool_calls[*].file_search.results[*].content"]` + - `score_threshold: float` - - `"step_details.tool_calls[*].file_search.results[*].content"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. -### Tool Call + - `results: Optional[List[FileSearchResult]]` -- `object` + The results of the file search. -### Tool Call Delta + - `file_id: str` -- `object` + The ID of the file that result was found in. -### Tool Call Delta Object + - `file_name: str` -- `class ToolCallDeltaObject: …` + The name of the file that result was found in. - Details of the tool call. + - `score: float` - - `type: Literal["tool_calls"]` + The score of the result. All values must be a floating point number between 0 and 1. - Always `tool_calls`. + - `content: Optional[List[FileSearchResultContent]]` - - `"tool_calls"` + The content of the result that was found. The content is only included if requested via the include query parameter. - - `tool_calls: Optional[List[object]]` + - `text: Optional[str]` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The text content of the file. -### Tool Calls Step Details + - `type: Optional[Literal["text"]]` -- `class ToolCallsStepDetails: …` + The type of the content. - Details of the tool call. + - `"text"` - - `tool_calls: List[object]` + - `type: Literal["file_search"]` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `"file_search"` + + - `class FunctionToolCall: …` + + - `id: str` + + The ID of the tool call object. + + - `function: Function` + + The definition of the function that was called. + + - `arguments: str` + + The arguments passed to the function. + + - `name: str` + + The name of the function. + + - `output: Optional[str]` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + + - `type: Literal["function"]` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `"function"` - `type: Literal["tool_calls"]` @@ -7214,186 +8434,2510 @@ print(run_step) - `"tool_calls"` -# Messages + - `thread_id: str` -## List messages + The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. -`beta.threads.messages.list(strthread_id, MessageListParams**kwargs) -> SyncCursorPage[Message]` + - `type: Literal["message_creation", "tool_calls"]` -**get** `/threads/{thread_id}/messages` + The type of run step, which can be either `message_creation` or `tool_calls`. -List messages + - `"message_creation"` -### Parameters + - `"tool_calls"` -- `thread_id: str` + - `usage: Optional[Usage]` -- `after: Optional[str]` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - 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. + - `completion_tokens: int` -- `before: Optional[str]` + Number of completion tokens used over the course of the run step. - 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, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `prompt_tokens: int` -- `limit: Optional[int]` + Number of prompt tokens used over the course of the run step. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `total_tokens: int` -- `order: Optional[Literal["asc", "desc"]]` + Total number of tokens used (prompt + completion). - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. +### Run Step Delta - - `"asc"` +- `class RunStepDelta: …` - - `"desc"` + The delta containing the fields that have changed on the run step. -- `run_id: Optional[str]` + - `step_details: Optional[StepDetails]` - Filter messages by the run ID that generated them. + The details of the run step. -### Returns + - `class RunStepDeltaMessageDelta: …` -- `class Message: …` + Details of the message creation by the run step. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `type: Literal["message_creation"]` - - `id: str` + Always `message_creation`. - The identifier, which can be referenced in API endpoints. + - `"message_creation"` - - `assistant_id: Optional[str]` + - `message_creation: Optional[MessageCreation]` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `message_id: Optional[str]` - - `attachments: Optional[List[Attachment]]` + The ID of the message that was created by this run step. - A list of files attached to the message, and the tools they were added to. + - `class ToolCallDeltaObject: …` - - `file_id: Optional[str]` + Details of the tool call. - The ID of the file to attach to the message. + - `type: Literal["tool_calls"]` - - `tools: Optional[List[AttachmentTool]]` + Always `tool_calls`. - The tools to add this file to. + - `"tool_calls"` - - `class CodeInterpreterTool: …` + - `tool_calls: Optional[List[ToolCallDelta]]` + + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + + - `class CodeInterpreterToolCallDelta: …` + + Details of the Code Interpreter tool call the run step was involved in. + + - `index: int` + + The index of the tool call in the tool calls array. - `type: Literal["code_interpreter"]` - The type of tool being defined: `code_interpreter` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - `"code_interpreter"` - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + - `id: Optional[str]` - - `type: Literal["file_search"]` + The ID of the tool call. - The type of tool being defined: `file_search` + - `code_interpreter: Optional[CodeInterpreter]` - - `"file_search"` + The Code Interpreter tool call definition. - - `completed_at: Optional[int]` + - `input: Optional[str]` - The Unix timestamp (in seconds) for when the message was completed. + The input to the Code Interpreter tool call. - - `content: List[object]` + - `outputs: Optional[List[CodeInterpreterOutput]]` - The content of the message in array of text and/or images. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `created_at: int` + - `class CodeInterpreterLogs: …` - The Unix timestamp (in seconds) for when the message was created. + Text output from the Code Interpreter tool call as part of a run step. - - `incomplete_at: Optional[int]` + - `index: int` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The index of the output in the outputs array. - - `incomplete_details: Optional[IncompleteDetails]` + - `type: Literal["logs"]` - On an incomplete message, details about why the message is incomplete. + Always `logs`. - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` + - `"logs"` - The reason the message is incomplete. + - `logs: Optional[str]` - - `"content_filter"` + The text output from the Code Interpreter tool call. - - `"max_tokens"` + - `class CodeInterpreterOutputImage: …` - - `"run_cancelled"` + - `index: int` - - `"run_expired"` + The index of the output in the outputs array. - - `"run_failed"` + - `type: Literal["image"]` - - `metadata: Optional[Metadata]` + Always `image`. - 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. + - `"image"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `image: Optional[Image]` - - `object: Literal["thread.message"]` + - `file_id: Optional[str]` - The object type, which is always `thread.message`. + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. - - `"thread.message"` + - `class FileSearchToolCallDelta: …` - - `role: Literal["user", "assistant"]` + - `file_search: object` - The entity that produced the message. One of `user` or `assistant`. + For now, this is always going to be an empty object. - - `"user"` + - `index: int` - - `"assistant"` + The index of the tool call in the tool calls array. - - `run_id: Optional[str]` + - `type: Literal["file_search"]` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `status: Literal["in_progress", "incomplete", "completed"]` + - `"file_search"` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `id: Optional[str]` - - `"in_progress"` + The ID of the tool call object. - - `"incomplete"` + - `class FunctionToolCallDelta: …` - - `"completed"` + - `index: int` - - `thread_id: str` + The index of the tool call in the tool calls array. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `type: Literal["function"]` -### Example + The type of tool call. This is always going to be `function` for this type of tool call. -```python -import os -from openai import OpenAI + - `"function"` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -page = client.beta.threads.messages.list( - thread_id="thread_id", -) -page = page.data[0] -print(page.id) -``` + - `id: Optional[str]` -#### Response + The ID of the tool call object. -```json -{ - "data": [ - { - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ + - `function: Optional[Function]` + + The definition of the function that was called. + + - `arguments: Optional[str]` + + The arguments passed to the function. + + - `name: Optional[str]` + + The name of the function. + + - `output: Optional[str]` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + +### Run Step Delta Event + +- `class RunStepDeltaEvent: …` + + Represents a run step delta i.e. any changed fields on a run step during streaming. + + - `id: str` + + The identifier of the run step, which can be referenced in API endpoints. + + - `delta: RunStepDelta` + + The delta containing the fields that have changed on the run step. + + - `step_details: Optional[StepDetails]` + + The details of the run step. + + - `class RunStepDeltaMessageDelta: …` + + Details of the message creation by the run step. + + - `type: Literal["message_creation"]` + + Always `message_creation`. + + - `"message_creation"` + + - `message_creation: Optional[MessageCreation]` + + - `message_id: Optional[str]` + + The ID of the message that was created by this run step. + + - `class ToolCallDeltaObject: …` + + Details of the tool call. + + - `type: Literal["tool_calls"]` + + Always `tool_calls`. + + - `"tool_calls"` + + - `tool_calls: Optional[List[ToolCallDelta]]` + + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + + - `class CodeInterpreterToolCallDelta: …` + + Details of the Code Interpreter tool call the run step was involved in. + + - `index: int` + + The index of the tool call in the tool calls array. + + - `type: Literal["code_interpreter"]` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `"code_interpreter"` + + - `id: Optional[str]` + + The ID of the tool call. + + - `code_interpreter: Optional[CodeInterpreter]` + + The Code Interpreter tool call definition. + + - `input: Optional[str]` + + The input to the Code Interpreter tool call. + + - `outputs: Optional[List[CodeInterpreterOutput]]` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `class CodeInterpreterLogs: …` + + Text output from the Code Interpreter tool call as part of a run step. + + - `index: int` + + The index of the output in the outputs array. + + - `type: Literal["logs"]` + + Always `logs`. + + - `"logs"` + + - `logs: Optional[str]` + + The text output from the Code Interpreter tool call. + + - `class CodeInterpreterOutputImage: …` + + - `index: int` + + The index of the output in the outputs array. + + - `type: Literal["image"]` + + Always `image`. + + - `"image"` + + - `image: Optional[Image]` + + - `file_id: Optional[str]` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `class FileSearchToolCallDelta: …` + + - `file_search: object` + + For now, this is always going to be an empty object. + + - `index: int` + + The index of the tool call in the tool calls array. + + - `type: Literal["file_search"]` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `"file_search"` + + - `id: Optional[str]` + + The ID of the tool call object. + + - `class FunctionToolCallDelta: …` + + - `index: int` + + The index of the tool call in the tool calls array. + + - `type: Literal["function"]` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `"function"` + + - `id: Optional[str]` + + The ID of the tool call object. + + - `function: Optional[Function]` + + The definition of the function that was called. + + - `arguments: Optional[str]` + + The arguments passed to the function. + + - `name: Optional[str]` + + The name of the function. + + - `output: Optional[str]` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + + - `object: Literal["thread.run.step.delta"]` + + The object type, which is always `thread.run.step.delta`. + + - `"thread.run.step.delta"` + +### Run Step Delta Message Delta + +- `class RunStepDeltaMessageDelta: …` + + Details of the message creation by the run step. + + - `type: Literal["message_creation"]` + + Always `message_creation`. + + - `"message_creation"` + + - `message_creation: Optional[MessageCreation]` + + - `message_id: Optional[str]` + + The ID of the message that was created by this run step. + +### Run Step Include + +- `Literal["step_details.tool_calls[*].file_search.results[*].content"]` + + - `"step_details.tool_calls[*].file_search.results[*].content"` + +### Tool Call + +- `ToolCall` + + Details of the Code Interpreter tool call the run step was involved in. + + - `class CodeInterpreterToolCall: …` + + Details of the Code Interpreter tool call the run step was involved in. + + - `id: str` + + The ID of the tool call. + + - `code_interpreter: CodeInterpreter` + + The Code Interpreter tool call definition. + + - `input: str` + + The input to the Code Interpreter tool call. + + - `outputs: List[CodeInterpreterOutput]` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `class CodeInterpreterOutputLogs: …` + + Text output from the Code Interpreter tool call as part of a run step. + + - `logs: str` + + The text output from the Code Interpreter tool call. + + - `type: Literal["logs"]` + + Always `logs`. + + - `"logs"` + + - `class CodeInterpreterOutputImage: …` + + - `image: CodeInterpreterOutputImageImage` + + - `file_id: str` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `type: Literal["image"]` + + Always `image`. + + - `"image"` + + - `type: Literal["code_interpreter"]` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `"code_interpreter"` + + - `class FileSearchToolCall: …` + + - `id: str` + + The ID of the tool call object. + + - `file_search: FileSearch` + + For now, this is always going to be an empty object. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. + + - `ranker: Literal["auto", "default_2024_08_21"]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `results: Optional[List[FileSearchResult]]` + + The results of the file search. + + - `file_id: str` + + The ID of the file that result was found in. + + - `file_name: str` + + The name of the file that result was found in. + + - `score: float` + + The score of the result. All values must be a floating point number between 0 and 1. + + - `content: Optional[List[FileSearchResultContent]]` + + The content of the result that was found. The content is only included if requested via the include query parameter. + + - `text: Optional[str]` + + The text content of the file. + + - `type: Optional[Literal["text"]]` + + The type of the content. + + - `"text"` + + - `type: Literal["file_search"]` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `"file_search"` + + - `class FunctionToolCall: …` + + - `id: str` + + The ID of the tool call object. + + - `function: Function` + + The definition of the function that was called. + + - `arguments: str` + + The arguments passed to the function. + + - `name: str` + + The name of the function. + + - `output: Optional[str]` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + + - `type: Literal["function"]` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `"function"` + +### Tool Call Delta + +- `ToolCallDelta` + + Details of the Code Interpreter tool call the run step was involved in. + + - `class CodeInterpreterToolCallDelta: …` + + Details of the Code Interpreter tool call the run step was involved in. + + - `index: int` + + The index of the tool call in the tool calls array. + + - `type: Literal["code_interpreter"]` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `"code_interpreter"` + + - `id: Optional[str]` + + The ID of the tool call. + + - `code_interpreter: Optional[CodeInterpreter]` + + The Code Interpreter tool call definition. + + - `input: Optional[str]` + + The input to the Code Interpreter tool call. + + - `outputs: Optional[List[CodeInterpreterOutput]]` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `class CodeInterpreterLogs: …` + + Text output from the Code Interpreter tool call as part of a run step. + + - `index: int` + + The index of the output in the outputs array. + + - `type: Literal["logs"]` + + Always `logs`. + + - `"logs"` + + - `logs: Optional[str]` + + The text output from the Code Interpreter tool call. + + - `class CodeInterpreterOutputImage: …` + + - `index: int` + + The index of the output in the outputs array. + + - `type: Literal["image"]` + + Always `image`. + + - `"image"` + + - `image: Optional[Image]` + + - `file_id: Optional[str]` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `class FileSearchToolCallDelta: …` + + - `file_search: object` + + For now, this is always going to be an empty object. + + - `index: int` + + The index of the tool call in the tool calls array. + + - `type: Literal["file_search"]` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `"file_search"` + + - `id: Optional[str]` + + The ID of the tool call object. + + - `class FunctionToolCallDelta: …` + + - `index: int` + + The index of the tool call in the tool calls array. + + - `type: Literal["function"]` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `"function"` + + - `id: Optional[str]` + + The ID of the tool call object. + + - `function: Optional[Function]` + + The definition of the function that was called. + + - `arguments: Optional[str]` + + The arguments passed to the function. + + - `name: Optional[str]` + + The name of the function. + + - `output: Optional[str]` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + +### Tool Call Delta Object + +- `class ToolCallDeltaObject: …` + + Details of the tool call. + + - `type: Literal["tool_calls"]` + + Always `tool_calls`. + + - `"tool_calls"` + + - `tool_calls: Optional[List[ToolCallDelta]]` + + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + + - `class CodeInterpreterToolCallDelta: …` + + Details of the Code Interpreter tool call the run step was involved in. + + - `index: int` + + The index of the tool call in the tool calls array. + + - `type: Literal["code_interpreter"]` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `"code_interpreter"` + + - `id: Optional[str]` + + The ID of the tool call. + + - `code_interpreter: Optional[CodeInterpreter]` + + The Code Interpreter tool call definition. + + - `input: Optional[str]` + + The input to the Code Interpreter tool call. + + - `outputs: Optional[List[CodeInterpreterOutput]]` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `class CodeInterpreterLogs: …` + + Text output from the Code Interpreter tool call as part of a run step. + + - `index: int` + + The index of the output in the outputs array. + + - `type: Literal["logs"]` + + Always `logs`. + + - `"logs"` + + - `logs: Optional[str]` + + The text output from the Code Interpreter tool call. + + - `class CodeInterpreterOutputImage: …` + + - `index: int` + + The index of the output in the outputs array. + + - `type: Literal["image"]` + + Always `image`. + + - `"image"` + + - `image: Optional[Image]` + + - `file_id: Optional[str]` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `class FileSearchToolCallDelta: …` + + - `file_search: object` + + For now, this is always going to be an empty object. + + - `index: int` + + The index of the tool call in the tool calls array. + + - `type: Literal["file_search"]` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `"file_search"` + + - `id: Optional[str]` + + The ID of the tool call object. + + - `class FunctionToolCallDelta: …` + + - `index: int` + + The index of the tool call in the tool calls array. + + - `type: Literal["function"]` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `"function"` + + - `id: Optional[str]` + + The ID of the tool call object. + + - `function: Optional[Function]` + + The definition of the function that was called. + + - `arguments: Optional[str]` + + The arguments passed to the function. + + - `name: Optional[str]` + + The name of the function. + + - `output: Optional[str]` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + +### Tool Calls Step Details + +- `class ToolCallsStepDetails: …` + + Details of the tool call. + + - `tool_calls: List[ToolCall]` + + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + + - `class CodeInterpreterToolCall: …` + + Details of the Code Interpreter tool call the run step was involved in. + + - `id: str` + + The ID of the tool call. + + - `code_interpreter: CodeInterpreter` + + The Code Interpreter tool call definition. + + - `input: str` + + The input to the Code Interpreter tool call. + + - `outputs: List[CodeInterpreterOutput]` + + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + + - `class CodeInterpreterOutputLogs: …` + + Text output from the Code Interpreter tool call as part of a run step. + + - `logs: str` + + The text output from the Code Interpreter tool call. + + - `type: Literal["logs"]` + + Always `logs`. + + - `"logs"` + + - `class CodeInterpreterOutputImage: …` + + - `image: CodeInterpreterOutputImageImage` + + - `file_id: str` + + The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. + + - `type: Literal["image"]` + + Always `image`. + + - `"image"` + + - `type: Literal["code_interpreter"]` + + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + + - `"code_interpreter"` + + - `class FileSearchToolCall: …` + + - `id: str` + + The ID of the tool call object. + + - `file_search: FileSearch` + + For now, this is always going to be an empty object. + + - `ranking_options: Optional[FileSearchRankingOptions]` + + The ranking options for the file search. + + - `ranker: Literal["auto", "default_2024_08_21"]` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `score_threshold: float` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `results: Optional[List[FileSearchResult]]` + + The results of the file search. + + - `file_id: str` + + The ID of the file that result was found in. + + - `file_name: str` + + The name of the file that result was found in. + + - `score: float` + + The score of the result. All values must be a floating point number between 0 and 1. + + - `content: Optional[List[FileSearchResultContent]]` + + The content of the result that was found. The content is only included if requested via the include query parameter. + + - `text: Optional[str]` + + The text content of the file. + + - `type: Optional[Literal["text"]]` + + The type of the content. + + - `"text"` + + - `type: Literal["file_search"]` + + The type of tool call. This is always going to be `file_search` for this type of tool call. + + - `"file_search"` + + - `class FunctionToolCall: …` + + - `id: str` + + The ID of the tool call object. + + - `function: Function` + + The definition of the function that was called. + + - `arguments: str` + + The arguments passed to the function. + + - `name: str` + + The name of the function. + + - `output: Optional[str]` + + The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. + + - `type: Literal["function"]` + + The type of tool call. This is always going to be `function` for this type of tool call. + + - `"function"` + + - `type: Literal["tool_calls"]` + + Always `tool_calls`. + + - `"tool_calls"` + +# Messages + +## List messages + +`beta.threads.messages.list(strthread_id, MessageListParams**kwargs) -> SyncCursorPage[Message]` + +**get** `/threads/{thread_id}/messages` + +Returns a list of messages for a given thread. + +### Parameters + +- `thread_id: str` + +- `after: Optional[str]` + + 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. + +- `before: Optional[str]` + + 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, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + +- `limit: Optional[int]` + + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + +- `order: Optional[Literal["asc", "desc"]]` + + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + + - `"asc"` + + - `"desc"` + +- `run_id: Optional[str]` + + Filter messages by the run ID that generated them. + +### Returns + +- `class Message: …` + + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + + - `id: str` + + The identifier, which can be referenced in API endpoints. + + - `assistant_id: Optional[str]` + + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) 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. + + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"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. + + - `class ImageFileContentBlock: …` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: ImageFile` + + - `file_id: str` + + The [File](https://platform.openai.com/docs/api-reference/files) 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`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_file"]` + + Always `image_file`. + + - `"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. + + - `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` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_url"]` + + The type of the content part. + + - `"image_url"` + + - `class TextContentBlock: …` + + The text content that is part of a message. + + - `text: Text` + + - `annotations: List[Annotation]` + + - `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` + + - `file_citation: FileCitation` + + - `file_id: str` + + The ID of the specific File the citation is from. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_citation"]` + + Always `file_citation`. + + - `"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` + + - `file_path: FilePath` + + - `file_id: str` + + The ID of the file that was generated. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_path"]` + + Always `file_path`. + + - `"file_path"` + + - `value: str` + + The data that makes up the text. + + - `type: Literal["text"]` + + Always `text`. + + - `"text"` + + - `class RefusalContentBlock: …` + + The refusal content generated by the assistant. + + - `refusal: str` + + - `type: Literal["refusal"]` + + Always `refusal`. + + - `"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. + + - `"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`. + + - `"thread.message"` + + - `role: Literal["user", "assistant"]` + + The entity that produced the message. One of `user` or `assistant`. + + - `"user"` + + - `"assistant"` + + - `run_id: Optional[str]` + + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) 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`. + + - `"in_progress"` + + - `"incomplete"` + + - `"completed"` + + - `thread_id: str` + + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + +### Example + +```python +import os +from openai import OpenAI + +client = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted +) +page = client.beta.threads.messages.list( + thread_id="thread_id", +) +page = page.data[0] +print(page.id) +``` + +#### Response + +```json +{ + "data": [ + { + "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" + } + ], + "first_id": "msg_abc123", + "has_more": false, + "last_id": "msg_abc123", + "object": "list" +} +``` + +### Example + +```python +from openai import OpenAI +client = OpenAI() + +thread_messages = client.beta.threads.messages.list("thread_abc123") +print(thread_messages.data) +``` + +#### Response + +```json +{ + "object": "list", + "data": [ + { + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + }, + { + "id": "msg_abc456", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "Hello, what is AI?", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc456", + "has_more": false +} +``` + +## Create message + +`beta.threads.messages.create(strthread_id, MessageCreateParams**kwargs) -> Message` + +**post** `/threads/{thread_id}/messages` + +Create a message. + +### Parameters + +- `thread_id: str` + +- `content: Union[str, Iterable[MessageContentPartParam]]` + + The text contents of the message. + + - `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](https://platform.openai.com/docs/models). + + - `class ImageFileContentBlock: …` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: ImageFile` + + - `file_id: str` + + The [File](https://platform.openai.com/docs/api-reference/files) 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`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_file"]` + + Always `image_file`. + + - `"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. + + - `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` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_url"]` + + The type of the content part. + + - `"image_url"` + + - `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`. + + - `"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. + + - `"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. + + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class AttachmentToolFileSearch: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"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. + +### Returns + +- `class Message: …` + + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + + - `id: str` + + The identifier, which can be referenced in API endpoints. + + - `assistant_id: Optional[str]` + + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) 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. + + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"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. + + - `class ImageFileContentBlock: …` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: ImageFile` + + - `file_id: str` + + The [File](https://platform.openai.com/docs/api-reference/files) 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`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_file"]` + + Always `image_file`. + + - `"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. + + - `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` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_url"]` + + The type of the content part. + + - `"image_url"` + + - `class TextContentBlock: …` + + The text content that is part of a message. + + - `text: Text` + + - `annotations: List[Annotation]` + + - `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` + + - `file_citation: FileCitation` + + - `file_id: str` + + The ID of the specific File the citation is from. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_citation"]` + + Always `file_citation`. + + - `"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` + + - `file_path: FilePath` + + - `file_id: str` + + The ID of the file that was generated. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_path"]` + + Always `file_path`. + + - `"file_path"` + + - `value: str` + + The data that makes up the text. + + - `type: Literal["text"]` + + Always `text`. + + - `"text"` + + - `class RefusalContentBlock: …` + + The refusal content generated by the assistant. + + - `refusal: str` + + - `type: Literal["refusal"]` + + Always `refusal`. + + - `"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. + + - `"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`. + + - `"thread.message"` + + - `role: Literal["user", "assistant"]` + + The entity that produced the message. One of `user` or `assistant`. + + - `"user"` + + - `"assistant"` + + - `run_id: Optional[str]` + + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) 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`. + + - `"in_progress"` + + - `"incomplete"` + + - `"completed"` + + - `thread_id: str` + + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + +### Example + +```python +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) +``` + +#### Response + +```json +{ + "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" +} +``` + +### Example + +```python +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) +``` + +#### Response + +```json +{ + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1713226573, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} +} +``` + +## Modify message + +`beta.threads.messages.update(strmessage_id, MessageUpdateParams**kwargs) -> Message` + +**post** `/threads/{thread_id}/messages/{message_id}` + +Modifies a message. + +### Parameters + +- `thread_id: str` + +- `message_id: str` + +- `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. + +### Returns + +- `class Message: …` + + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + + - `id: str` + + The identifier, which can be referenced in API endpoints. + + - `assistant_id: Optional[str]` + + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) 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. + + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"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. + + - `class ImageFileContentBlock: …` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: ImageFile` + + - `file_id: str` + + The [File](https://platform.openai.com/docs/api-reference/files) 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`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_file"]` + + Always `image_file`. + + - `"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. + + - `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` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_url"]` + + The type of the content part. + + - `"image_url"` + + - `class TextContentBlock: …` + + The text content that is part of a message. + + - `text: Text` + + - `annotations: List[Annotation]` + + - `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` + + - `file_citation: FileCitation` + + - `file_id: str` + + The ID of the specific File the citation is from. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_citation"]` + + Always `file_citation`. + + - `"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` + + - `file_path: FilePath` + + - `file_id: str` + + The ID of the file that was generated. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_path"]` + + Always `file_path`. + + - `"file_path"` + + - `value: str` + + The data that makes up the text. + + - `type: Literal["text"]` + + Always `text`. + + - `"text"` + + - `class RefusalContentBlock: …` + + The refusal content generated by the assistant. + + - `refusal: str` + + - `type: Literal["refusal"]` + + Always `refusal`. + + - `"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. + + - `"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`. + + - `"thread.message"` + + - `role: Literal["user", "assistant"]` + + The entity that produced the message. One of `user` or `assistant`. + + - `"user"` + + - `"assistant"` + + - `run_id: Optional[str]` + + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) 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`. + + - `"in_progress"` + + - `"incomplete"` + + - `"completed"` + + - `thread_id: str` + + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + +### Example + +```python +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.update( + message_id="message_id", + thread_id="thread_id", +) +print(message.id) +``` + +#### Response + +```json +{ + "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" +} +``` + +### Example + +```python +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) +``` + +#### Response + +```json +{ + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "file_ids": [], + "metadata": { + "modified": "true", + "user": "abc123" + } +} +``` + +## Retrieve message + +`beta.threads.messages.retrieve(strmessage_id, MessageRetrieveParams**kwargs) -> Message` + +**get** `/threads/{thread_id}/messages/{message_id}` + +Retrieve a message. + +### Parameters + +- `thread_id: str` + +- `message_id: str` + +### Returns + +- `class Message: …` + + Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + + - `id: str` + + The identifier, which can be referenced in API endpoints. + + - `assistant_id: Optional[str]` + + If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) 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. + + - `class CodeInterpreterTool: …` + + - `type: Literal["code_interpreter"]` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + + - `type: Literal["file_search"]` + + The type of tool being defined: `file_search` + + - `"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. + + - `class ImageFileContentBlock: …` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `image_file: ImageFile` + + - `file_id: str` + + The [File](https://platform.openai.com/docs/api-reference/files) 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`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_file"]` + + Always `image_file`. + + - `"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. + + - `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` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_url"]` + + The type of the content part. + + - `"image_url"` + + - `class TextContentBlock: …` + + The text content that is part of a message. + + - `text: Text` + + - `annotations: List[Annotation]` + + - `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` + + - `file_citation: FileCitation` + + - `file_id: str` + + The ID of the specific File the citation is from. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_citation"]` + + Always `file_citation`. + + - `"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` + + - `file_path: FilePath` + + - `file_id: str` + + The ID of the file that was generated. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_path"]` + + Always `file_path`. + + - `"file_path"` + + - `value: str` + + The data that makes up the text. + + - `type: Literal["text"]` + + Always `text`. + + - `"text"` + + - `class RefusalContentBlock: …` + + The refusal content generated by the assistant. + + - `refusal: str` + + - `type: Literal["refusal"]` + + Always `refusal`. + + - `"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. + + - `"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`. + + - `"thread.message"` + + - `role: Literal["user", "assistant"]` + + The entity that produced the message. One of `user` or `assistant`. + + - `"user"` + + - `"assistant"` + + - `run_id: Optional[str]` + + The ID of the [run](https://platform.openai.com/docs/api-reference/runs) 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`. + + - `"in_progress"` + + - `"incomplete"` + + - `"completed"` + + - `thread_id: str` + + The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + +### Example + +```python +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.retrieve( + message_id="message_id", + thread_id="thread_id", +) +print(message.id) +``` + +#### Response + +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ { "file_id": "file_id", "tools": [ @@ -7405,7 +10949,13 @@ print(page.id) ], "completed_at": 0, "content": [ - {} + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } ], "created_at": 0, "incomplete_at": 0, @@ -7420,12 +10970,6 @@ print(page.id) "run_id": "run_id", "status": "in_progress", "thread_id": "thread_id" - } - ], - "first_id": "msg_abc123", - "has_more": false, - "last_id": "msg_abc123", - "object": "list" } ``` @@ -7435,20 +10979,20 @@ print(page.id) from openai import OpenAI client = OpenAI() -thread_messages = client.beta.threads.messages.list("thread_abc123") -print(thread_messages.data) +message = client.beta.threads.messages.retrieve( + message_id="msg_abc123", + thread_id="thread_abc123", +) +print(message) ``` #### Response ```json { - "object": "list", - "data": [ - { "id": "msg_abc123", "object": "thread.message", - "created_at": 1699016383, + "created_at": 1699017614, "assistant_id": null, "thread_id": "thread_abc123", "run_id": null, @@ -7464,405 +11008,515 @@ print(thread_messages.data) ], "attachments": [], "metadata": {} - }, - { - "id": "msg_abc456", - "object": "thread.message", - "created_at": 1699016383, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "Hello, what is AI?", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} - } - ], - "first_id": "msg_abc123", - "last_id": "msg_abc456", - "has_more": false } ``` -## Create message +## Delete message + +`beta.threads.messages.delete(strmessage_id, MessageDeleteParams**kwargs) -> MessageDeleted` + +**delete** `/threads/{thread_id}/messages/{message_id}` + +Deletes a message. + +### Parameters + +- `thread_id: str` + +- `message_id: str` + +### Returns + +- `class MessageDeleted: …` + + - `id: str` + + - `deleted: bool` + + - `object: Literal["thread.message.deleted"]` + + - `"thread.message.deleted"` + +### Example + +```python +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_deleted = client.beta.threads.messages.delete( + message_id="message_id", + thread_id="thread_id", +) +print(message_deleted.id) +``` + +#### Response + +```json +{ + "id": "id", + "deleted": true, + "object": "thread.message.deleted" +} +``` + +### Example + +```python +from openai import OpenAI +client = OpenAI() + +deleted_message = client.beta.threads.messages.delete( + message_id="msg_abc12", + thread_id="thread_abc123", +) +print(deleted_message) +``` + +#### Response + +```json +{ + "id": "msg_abc123", + "object": "thread.message.deleted", + "deleted": true +} +``` + +## Domain Types + +### Annotation + +- `Annotation` + + 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. + + - `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` + + - `file_citation: FileCitation` + + - `file_id: str` + + The ID of the specific File the citation is from. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_citation"]` + + Always `file_citation`. + + - `"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` + + - `file_path: FilePath` + + - `file_id: str` + + The ID of the file that was generated. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_path"]` + + Always `file_path`. + + - `"file_path"` + +### Annotation Delta + +- `AnnotationDelta` + + 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. + + - `class FileCitationDeltaAnnotation: …` + + 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. + + - `index: int` + + The index of the annotation in the text content part. + + - `type: Literal["file_citation"]` + + Always `file_citation`. + + - `"file_citation"` + + - `end_index: Optional[int]` + + - `file_citation: Optional[FileCitation]` + + - `file_id: Optional[str]` + + The ID of the specific File the citation is from. + + - `quote: Optional[str]` + + The specific quote in the file. + + - `start_index: Optional[int]` + + - `text: Optional[str]` + + The text in the message content that needs to be replaced. + + - `class FilePathDeltaAnnotation: …` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `index: int` + + The index of the annotation in the text content part. + + - `type: Literal["file_path"]` + + Always `file_path`. + + - `"file_path"` + + - `end_index: Optional[int]` + + - `file_path: Optional[FilePath]` + + - `file_id: Optional[str]` + + The ID of the file that was generated. + + - `start_index: Optional[int]` + + - `text: Optional[str]` + + The text in the message content that needs to be replaced. + +### File Citation Annotation + +- `class FileCitationAnnotation: …` -`beta.threads.messages.create(strthread_id, MessageCreateParams**kwargs) -> Message` + 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. -**post** `/threads/{thread_id}/messages` + - `end_index: int` -Create message + - `file_citation: FileCitation` -### Parameters + - `file_id: str` -- `thread_id: str` + The ID of the specific File the citation is from. -- `content: Union[str, Iterable[MessageContentPartParam]]` + - `start_index: int` - The text contents of the message. + - `text: str` - - `str` + The text in the message content that needs to be replaced. - The text contents of the message. + - `type: Literal["file_citation"]` - - `Iterable[MessageContentPartParam]` + Always `file_citation`. - 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](https://platform.openai.com/docs/models). + - `"file_citation"` - - `class ImageFileContentBlock: …` +### File Citation Delta Annotation - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. +- `class FileCitationDeltaAnnotation: …` - - `image_file: ImageFileParam` + 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. - - `file_id: str` + - `index: int` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + The index of the annotation in the text content part. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `type: Literal["file_citation"]` - 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`. + Always `file_citation`. - - `"auto"` + - `"file_citation"` - - `"low"` + - `end_index: Optional[int]` - - `"high"` + - `file_citation: Optional[FileCitation]` - - `type: Literal["image_file"]` + - `file_id: Optional[str]` - Always `image_file`. + The ID of the specific File the citation is from. - - `"image_file"` + - `quote: Optional[str]` - - `class ImageURLContentBlock: …` + The specific quote in the file. - References an image URL in the content of a message. + - `start_index: Optional[int]` - - `image_url: ImageURLParam` + - `text: Optional[str]` - - `url: str` + The text in the message content that needs to be replaced. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. +### File Path Annotation - - `detail: Optional[Literal["auto", "low", "high"]]` +- `class FilePathAnnotation: …` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"auto"` + - `end_index: int` - - `"low"` + - `file_path: FilePath` - - `"high"` + - `file_id: str` - - `type: Literal["image_url"]` + The ID of the file that was generated. - The type of the content part. + - `start_index: int` - - `"image_url"` + - `text: str` - - `class TextContentBlockParam: …` + The text in the message content that needs to be replaced. - The text content that is part of a message. + - `type: Literal["file_path"]` - - `text: str` + Always `file_path`. - Text content to be sent to the model + - `"file_path"` - - `type: Literal["text"]` +### File Path Delta Annotation - Always `text`. +- `class FilePathDeltaAnnotation: …` - - `"text"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. -- `role: Literal["user", "assistant"]` + - `index: int` - The role of the entity that is creating the message. Allowed values include: + The index of the annotation in the text content part. - - `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. + - `type: Literal["file_path"]` - - `"user"` + Always `file_path`. - - `"assistant"` + - `"file_path"` -- `attachments: Optional[Iterable[Attachment]]` + - `end_index: Optional[int]` - A list of files attached to the message, and the tools they should be added to. + - `file_path: Optional[FilePath]` - `file_id: Optional[str]` - The ID of the file to attach to the message. + The ID of the file that was generated. - - `tools: Optional[Iterable[AttachmentTool]]` + - `start_index: Optional[int]` - The tools to add this file to. + - `text: Optional[str]` - - `class CodeInterpreterTool: …` + The text in the message content that needs to be replaced. - - `type: Literal["code_interpreter"]` +### Image File - The type of tool being defined: `code_interpreter` +- `class ImageFile: …` - - `"code_interpreter"` + - `file_id: str` - - `class AttachmentToolFileSearch: …` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `type: Literal["file_search"]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The type of tool being defined: `file_search` + 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`. - - `"file_search"` + - `"auto"` -- `metadata: Optional[Metadata]` + - `"low"` - 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. + - `"high"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. +### Image File Content Block -### Returns +- `class ImageFileContentBlock: …` -- `class Message: …` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `image_file: ImageFile` - - `id: str` + - `file_id: str` - The identifier, which can be referenced in API endpoints. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `assistant_id: Optional[str]` + - `detail: Optional[Literal["auto", "low", "high"]]` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + 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`. - - `attachments: Optional[List[Attachment]]` + - `"auto"` - A list of files attached to the message, and the tools they were added to. + - `"low"` - - `file_id: Optional[str]` + - `"high"` - The ID of the file to attach to the message. + - `type: Literal["image_file"]` - - `tools: Optional[List[AttachmentTool]]` + Always `image_file`. - The tools to add this file to. + - `"image_file"` - - `class CodeInterpreterTool: …` +### Image File Delta - - `type: Literal["code_interpreter"]` +- `class ImageFileDelta: …` - The type of tool being defined: `code_interpreter` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"code_interpreter"` + 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`. - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + - `"auto"` - - `type: Literal["file_search"]` + - `"low"` - The type of tool being defined: `file_search` + - `"high"` - - `"file_search"` + - `file_id: Optional[str]` - - `completed_at: Optional[int]` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The Unix timestamp (in seconds) for when the message was completed. +### Image File Delta Block - - `content: List[object]` +- `class ImageFileDeltaBlock: …` - The content of the message in array of text and/or images. + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `created_at: int` + - `index: int` - The Unix timestamp (in seconds) for when the message was created. + The index of the content part in the message. - - `incomplete_at: Optional[int]` + - `type: Literal["image_file"]` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + Always `image_file`. - - `incomplete_details: Optional[IncompleteDetails]` + - `"image_file"` - On an incomplete message, details about why the message is incomplete. + - `image_file: Optional[ImageFileDelta]` - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The reason the message is incomplete. + 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`. - - `"content_filter"` + - `"auto"` - - `"max_tokens"` + - `"low"` - - `"run_cancelled"` + - `"high"` - - `"run_expired"` + - `file_id: Optional[str]` - - `"run_failed"` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `metadata: Optional[Metadata]` +### Image URL - 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. +- `class ImageURL: …` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `url: str` - - `object: Literal["thread.message"]` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The object type, which is always `thread.message`. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"thread.message"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `role: Literal["user", "assistant"]` + - `"auto"` - The entity that produced the message. One of `user` or `assistant`. + - `"low"` - - `"user"` + - `"high"` - - `"assistant"` +### Image URL Content Block - - `run_id: Optional[str]` +- `class ImageURLContentBlock: …` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + References an image URL in the content of a message. - - `status: Literal["in_progress", "incomplete", "completed"]` + - `image_url: ImageURL` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `url: str` - - `"in_progress"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + + - `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` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_url"]` + + The type of the content part. + + - `"image_url"` + +### Image URL Delta - - `"incomplete"` +- `class ImageURLDelta: …` - - `"completed"` + - `detail: Optional[Literal["auto", "low", "high"]]` - - `thread_id: str` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `"auto"` -### Example + - `"low"` -```python -import os -from openai import OpenAI + - `"high"` -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) -``` + - `url: Optional[str]` -#### Response + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "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" -} -``` +### Image URL Delta Block -### Example +- `class ImageURLDeltaBlock: …` -```python -from openai import OpenAI -client = OpenAI() + References an image URL in the content of a message. -thread_message = client.beta.threads.messages.create( - "thread_abc123", - role="user", - content="How does AI work? Explain it in simple terms.", -) -print(thread_message) -``` + - `index: int` -#### Response + The index of the content part in the message. -```json -{ - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1713226573, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} -} -``` + - `type: Literal["image_url"]` -## Modify message + Always `image_url`. -`beta.threads.messages.update(strmessage_id, MessageUpdateParams**kwargs) -> Message` + - `"image_url"` -**post** `/threads/{thread_id}/messages/{message_id}` + - `image_url: Optional[ImageURLDelta]` -Modify message + - `detail: Optional[Literal["auto", "low", "high"]]` -### Parameters + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. -- `thread_id: str` + - `"auto"` -- `message_id: str` + - `"low"` -- `metadata: Optional[Metadata]` + - `"high"` - 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. + - `url: Optional[str]` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. -### Returns +### Message - `class Message: …` @@ -7908,237 +11562,139 @@ Modify message The Unix timestamp (in seconds) for when the message was completed. - - `content: List[object]` + - `content: List[MessageContent]` The content of the message in array of text and/or images. - - `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. - - - `"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. + - `class ImageFileContentBlock: …` - - `object: Literal["thread.message"]` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - The object type, which is always `thread.message`. + - `image_file: ImageFile` - - `"thread.message"` + - `file_id: str` - - `role: Literal["user", "assistant"]` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The entity that produced the message. One of `user` or `assistant`. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `"user"` + 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`. - - `"assistant"` + - `"auto"` - - `run_id: Optional[str]` + - `"low"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `"high"` - - `status: Literal["in_progress", "incomplete", "completed"]` + - `type: Literal["image_file"]` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + Always `image_file`. - - `"in_progress"` + - `"image_file"` - - `"incomplete"` + - `class ImageURLContentBlock: …` - - `"completed"` + References an image URL in the content of a message. - - `thread_id: str` + - `image_url: ImageURL` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + - `url: str` -### Example + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. -```python -import os -from openai import OpenAI + - `detail: Optional[Literal["auto", "low", "high"]]` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -message = client.beta.threads.messages.update( - message_id="message_id", - thread_id="thread_id", -) -print(message.id) -``` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` -#### Response + - `"auto"` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "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" -} -``` + - `"low"` -### Example + - `"high"` -```python -from openai import OpenAI -client = OpenAI() + - `type: Literal["image_url"]` -message = client.beta.threads.messages.update( - message_id="msg_abc12", - thread_id="thread_abc123", - metadata={ - "modified": "true", - "user": "abc123", - }, -) -print(message) -``` + The type of the content part. -#### Response + - `"image_url"` -```json -{ - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "file_ids": [], - "metadata": { - "modified": "true", - "user": "abc123" - } -} -``` + - `class TextContentBlock: …` -## Retrieve message + The text content that is part of a message. -`beta.threads.messages.retrieve(strmessage_id, MessageRetrieveParams**kwargs) -> Message` + - `text: Text` -**get** `/threads/{thread_id}/messages/{message_id}` + - `annotations: List[Annotation]` -Retrieve message + - `class FileCitationAnnotation: …` -### Parameters + 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. -- `thread_id: str` + - `end_index: int` -- `message_id: str` + - `file_citation: FileCitation` -### Returns + - `file_id: str` -- `class Message: …` + The ID of the specific File the citation is from. - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `start_index: int` - - `id: str` + - `text: str` - The identifier, which can be referenced in API endpoints. + The text in the message content that needs to be replaced. - - `assistant_id: Optional[str]` + - `type: Literal["file_citation"]` - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + Always `file_citation`. - - `attachments: Optional[List[Attachment]]` + - `"file_citation"` - A list of files attached to the message, and the tools they were added to. + - `class FilePathAnnotation: …` - - `file_id: Optional[str]` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The ID of the file to attach to the message. + - `end_index: int` - - `tools: Optional[List[AttachmentTool]]` + - `file_path: FilePath` - The tools to add this file to. + - `file_id: str` - - `class CodeInterpreterTool: …` + The ID of the file that was generated. - - `type: Literal["code_interpreter"]` + - `start_index: int` - The type of tool being defined: `code_interpreter` + - `text: str` - - `"code_interpreter"` + The text in the message content that needs to be replaced. - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + - `type: Literal["file_path"]` - - `type: Literal["file_search"]` + Always `file_path`. - The type of tool being defined: `file_search` + - `"file_path"` - - `"file_search"` + - `value: str` - - `completed_at: Optional[int]` + The data that makes up the text. - The Unix timestamp (in seconds) for when the message was completed. + - `type: Literal["text"]` + + Always `text`. + + - `"text"` - - `content: List[object]` + - `class RefusalContentBlock: …` - The content of the message in array of text and/or images. + The refusal content generated by the assistant. + + - `refusal: str` + + - `type: Literal["refusal"]` + + Always `refusal`. + + - `"refusal"` - `created_at: int` @@ -8207,210 +11763,197 @@ Retrieve message The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. -### Example +### Message Content -```python -import os -from openai import OpenAI +- `MessageContent` -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -message = client.beta.threads.messages.retrieve( - message_id="message_id", - thread_id="thread_id", -) -print(message.id) -``` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. -#### Response + - `class ImageFileContentBlock: …` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - {} - ], - "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" -} -``` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. -### Example + - `image_file: ImageFile` -```python -from openai import OpenAI -client = OpenAI() + - `file_id: str` -message = client.beta.threads.messages.retrieve( - message_id="msg_abc123", - thread_id="thread_abc123", -) -print(message) -``` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. -#### Response + - `detail: Optional[Literal["auto", "low", "high"]]` -```json -{ - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} -} -``` + 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`. + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_file"]` + + Always `image_file`. + + - `"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. + + - `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` + + - `"auto"` + + - `"low"` + + - `"high"` + + - `type: Literal["image_url"]` + + The type of the content part. + + - `"image_url"` + + - `class TextContentBlock: …` + + The text content that is part of a message. + + - `text: Text` + + - `annotations: List[Annotation]` + + - `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` + + - `file_citation: FileCitation` + + - `file_id: str` + + The ID of the specific File the citation is from. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_citation"]` + + Always `file_citation`. + + - `"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` + + - `file_path: FilePath` -## Delete message + - `file_id: str` -`beta.threads.messages.delete(strmessage_id, MessageDeleteParams**kwargs) -> MessageDeleted` + The ID of the file that was generated. -**delete** `/threads/{thread_id}/messages/{message_id}` + - `start_index: int` -Delete message + - `text: str` -### Parameters + The text in the message content that needs to be replaced. -- `thread_id: str` + - `type: Literal["file_path"]` -- `message_id: str` + Always `file_path`. -### Returns + - `"file_path"` -- `class MessageDeleted: …` + - `value: str` - - `id: str` + The data that makes up the text. - - `deleted: bool` + - `type: Literal["text"]` - - `object: Literal["thread.message.deleted"]` + Always `text`. - - `"thread.message.deleted"` + - `"text"` -### Example + - `class RefusalContentBlock: …` -```python -import os -from openai import OpenAI + The refusal content generated by the assistant. -client = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted -) -message_deleted = client.beta.threads.messages.delete( - message_id="message_id", - thread_id="thread_id", -) -print(message_deleted.id) -``` + - `refusal: str` -#### Response + - `type: Literal["refusal"]` -```json -{ - "id": "id", - "deleted": true, - "object": "thread.message.deleted" -} -``` + Always `refusal`. -### Example + - `"refusal"` -```python -from openai import OpenAI -client = OpenAI() +### Message Content Delta -deleted_message = client.beta.threads.messages.delete( - message_id="msg_abc12", - thread_id="thread_abc123", -) -print(deleted_message) -``` +- `MessageContentDelta` -#### Response + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. -```json -{ - "id": "msg_abc123", - "object": "thread.message.deleted", - "deleted": true -} -``` + - `class ImageFileDeltaBlock: …` -## Domain Types + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. -### Annotation + - `index: int` -- `object` + The index of the content part in the message. -### Annotation Delta + - `type: Literal["image_file"]` -- `object` + Always `image_file`. -### File Citation Annotation + - `"image_file"` -- `class FileCitationAnnotation: …` + - `image_file: Optional[ImageFileDelta]` - 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. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `end_index: int` + 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`. - - `file_citation: FileCitation` + - `"auto"` - - `file_id: str` + - `"low"` - The ID of the specific File the citation is from. + - `"high"` - - `start_index: int` + - `file_id: Optional[str]` - - `text: str` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - The text in the message content that needs to be replaced. + - `class TextDeltaBlock: …` - - `type: Literal["file_citation"]` + The text content that is part of a message. - Always `file_citation`. + - `index: int` - - `"file_citation"` + The index of the content part in the message. -### File Citation Delta Annotation + - `type: Literal["text"]` -- `class FileCitationDeltaAnnotation: …` + Always `text`. + + - `"text"` + + - `text: Optional[TextDelta]` + + - `annotations: Optional[List[AnnotationDelta]]` + + - `class FileCitationDeltaAnnotation: …` 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. @@ -8442,73 +11985,73 @@ print(deleted_message) The text in the message content that needs to be replaced. -### File Path Annotation - -- `class FilePathAnnotation: …` + - `class FilePathDeltaAnnotation: …` A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `end_index: int` + - `index: int` - - `file_path: FilePath` + The index of the annotation in the text content part. - - `file_id: str` + - `type: Literal["file_path"]` - The ID of the file that was generated. + Always `file_path`. - - `start_index: int` + - `"file_path"` - - `text: str` + - `end_index: Optional[int]` - The text in the message content that needs to be replaced. + - `file_path: Optional[FilePath]` - - `type: Literal["file_path"]` + - `file_id: Optional[str]` - Always `file_path`. + The ID of the file that was generated. - - `"file_path"` + - `start_index: Optional[int]` -### File Path Delta Annotation + - `text: Optional[str]` -- `class FilePathDeltaAnnotation: …` + The text in the message content that needs to be replaced. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `value: Optional[str]` - - `index: int` + The data that makes up the text. - The index of the annotation in the text content part. + - `class RefusalDeltaBlock: …` - - `type: Literal["file_path"]` + The refusal content that is part of a message. - Always `file_path`. + - `index: int` - - `"file_path"` + The index of the refusal part in the message. - - `end_index: Optional[int]` + - `type: Literal["refusal"]` - - `file_path: Optional[FilePath]` + Always `refusal`. - - `file_id: Optional[str]` + - `"refusal"` - The ID of the file that was generated. + - `refusal: Optional[str]` - - `start_index: Optional[int]` + - `class ImageURLDeltaBlock: …` - - `text: Optional[str]` + References an image URL in the content of a message. - The text in the message content that needs to be replaced. + - `index: int` -### Image File + The index of the content part in the message. -- `class ImageFile: …` + - `type: Literal["image_url"]` - - `file_id: str` + Always `image_url`. - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `"image_url"` + + - `image_url: Optional[ImageURLDelta]` - `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`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - `"auto"` @@ -8516,13 +12059,21 @@ print(deleted_message) - `"high"` -### Image File Content Block + - `url: Optional[str]` -- `class ImageFileContentBlock: …` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + +### Message Content Part Param + +- `MessageContentPartParam` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `class ImageFileContentBlock: …` References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `image_file: ImageFileParam` + - `image_file: ImageFile` - `file_id: str` @@ -8544,13 +12095,19 @@ print(deleted_message) - `"image_file"` -### Image File Delta + - `class ImageURLContentBlock: …` -- `class ImageFileDelta: …` + 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. - `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`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - `"auto"` @@ -8558,53 +12115,67 @@ print(deleted_message) - `"high"` - - `file_id: Optional[str]` + - `type: Literal["image_url"]` - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + The type of the content part. -### Image File Delta Block + - `"image_url"` -- `class ImageFileDeltaBlock: …` + - `class TextContentBlockParam: …` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + The text content that is part of a message. - - `index: int` + - `text: str` - The index of the content part in the message. + Text content to be sent to the model - - `type: Literal["image_file"]` + - `type: Literal["text"]` - Always `image_file`. + Always `text`. - - `"image_file"` + - `"text"` - - `image_file: Optional[ImageFileDelta]` +### Message Deleted - - `detail: Optional[Literal["auto", "low", "high"]]` +- `class MessageDeleted: …` - 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`. + - `id: str` - - `"auto"` + - `deleted: bool` - - `"low"` + - `object: Literal["thread.message.deleted"]` - - `"high"` + - `"thread.message.deleted"` - - `file_id: Optional[str]` +### Message Delta - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. +- `class MessageDelta: …` -### Image URL + The delta containing the fields that have changed on the Message. -- `class ImageURL: …` + - `content: Optional[List[MessageContentDelta]]` - - `url: str` + The content of the message in array of text and/or images. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `class ImageFileDeltaBlock: …` + + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + + - `index: int` + + The index of the content part in the message. + + - `type: Literal["image_file"]` + + Always `image_file`. + + - `"image_file"` + + - `image_file: Optional[ImageFileDelta]` - `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` + 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`. - `"auto"` @@ -8612,328 +12183,321 @@ print(deleted_message) - `"high"` -### Image URL Content Block - -- `class ImageURLContentBlock: …` - - References an image URL in the content of a message. + - `file_id: Optional[str]` - - `image_url: ImageURLParam` + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `url: str` + - `class TextDeltaBlock: …` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The text content that is part of a message. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `index: int` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + The index of the content part in the message. - - `"auto"` + - `type: Literal["text"]` - - `"low"` + Always `text`. - - `"high"` + - `"text"` - - `type: Literal["image_url"]` + - `text: Optional[TextDelta]` - The type of the content part. + - `annotations: Optional[List[AnnotationDelta]]` - - `"image_url"` + - `class FileCitationDeltaAnnotation: …` -### Image URL Delta + 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. -- `class ImageURLDelta: …` + - `index: int` - - `detail: Optional[Literal["auto", "low", "high"]]` + The index of the annotation in the text content part. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `type: Literal["file_citation"]` - - `"auto"` + Always `file_citation`. - - `"low"` + - `"file_citation"` - - `"high"` + - `end_index: Optional[int]` - - `url: Optional[str]` + - `file_citation: Optional[FileCitation]` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `file_id: Optional[str]` -### Image URL Delta Block + The ID of the specific File the citation is from. -- `class ImageURLDeltaBlock: …` + - `quote: Optional[str]` - References an image URL in the content of a message. + The specific quote in the file. - - `index: int` + - `start_index: Optional[int]` - The index of the content part in the message. + - `text: Optional[str]` - - `type: Literal["image_url"]` + The text in the message content that needs to be replaced. - Always `image_url`. + - `class FilePathDeltaAnnotation: …` - - `"image_url"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `image_url: Optional[ImageURLDelta]` + - `index: int` - - `detail: Optional[Literal["auto", "low", "high"]]` + The index of the annotation in the text content part. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `type: Literal["file_path"]` - - `"auto"` + Always `file_path`. - - `"low"` + - `"file_path"` - - `"high"` + - `end_index: Optional[int]` - - `url: Optional[str]` + - `file_path: Optional[FilePath]` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `file_id: Optional[str]` -### Message + The ID of the file that was generated. -- `class Message: …` + - `start_index: Optional[int]` - Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). + - `text: Optional[str]` - - `id: str` + The text in the message content that needs to be replaced. - The identifier, which can be referenced in API endpoints. + - `value: Optional[str]` - - `assistant_id: Optional[str]` + The data that makes up the text. - If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. + - `class RefusalDeltaBlock: …` - - `attachments: Optional[List[Attachment]]` + The refusal content that is part of a message. - A list of files attached to the message, and the tools they were added to. + - `index: int` - - `file_id: Optional[str]` + The index of the refusal part in the message. - The ID of the file to attach to the message. + - `type: Literal["refusal"]` - - `tools: Optional[List[AttachmentTool]]` + Always `refusal`. - The tools to add this file to. + - `"refusal"` - - `class CodeInterpreterTool: …` + - `refusal: Optional[str]` - - `type: Literal["code_interpreter"]` + - `class ImageURLDeltaBlock: …` - The type of tool being defined: `code_interpreter` + References an image URL in the content of a message. - - `"code_interpreter"` + - `index: int` - - `class AttachmentToolAssistantToolsFileSearchTypeOnly: …` + The index of the content part in the message. - - `type: Literal["file_search"]` + - `type: Literal["image_url"]` - The type of tool being defined: `file_search` + Always `image_url`. - - `"file_search"` + - `"image_url"` - - `completed_at: Optional[int]` + - `image_url: Optional[ImageURLDelta]` - The Unix timestamp (in seconds) for when the message was completed. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `content: List[object]` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The content of the message in array of text and/or images. + - `"auto"` - - `created_at: int` + - `"low"` - The Unix timestamp (in seconds) for when the message was created. + - `"high"` - - `incomplete_at: Optional[int]` + - `url: Optional[str]` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `incomplete_details: Optional[IncompleteDetails]` + - `role: Optional[Literal["user", "assistant"]]` - On an incomplete message, details about why the message is incomplete. + The entity that produced the message. One of `user` or `assistant`. - - `reason: Literal["content_filter", "max_tokens", "run_cancelled", 2 more]` + - `"user"` - The reason the message is incomplete. + - `"assistant"` - - `"content_filter"` +### Message Delta Event - - `"max_tokens"` +- `class MessageDeltaEvent: …` - - `"run_cancelled"` + Represents a message delta i.e. any changed fields on a message during streaming. - - `"run_expired"` + - `id: str` - - `"run_failed"` + The identifier of the message, which can be referenced in API endpoints. - - `metadata: Optional[Metadata]` + - `delta: MessageDelta` - 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. + The delta containing the fields that have changed on the Message. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `content: Optional[List[MessageContentDelta]]` - - `object: Literal["thread.message"]` + The content of the message in array of text and/or images. - The object type, which is always `thread.message`. + - `class ImageFileDeltaBlock: …` - - `"thread.message"` + References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. - - `role: Literal["user", "assistant"]` + - `index: int` - The entity that produced the message. One of `user` or `assistant`. + The index of the content part in the message. - - `"user"` + - `type: Literal["image_file"]` - - `"assistant"` + Always `image_file`. - - `run_id: Optional[str]` + - `"image_file"` - The ID of the [run](https://platform.openai.com/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `image_file: Optional[ImageFileDelta]` - - `status: Literal["in_progress", "incomplete", "completed"]` + - `detail: Optional[Literal["auto", "low", "high"]]` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + 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`. - - `"in_progress"` + - `"auto"` - - `"incomplete"` + - `"low"` - - `"completed"` + - `"high"` - - `thread_id: str` + - `file_id: Optional[str]` - The [thread](https://platform.openai.com/docs/api-reference/threads) ID that this message belongs to. + The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. -### Message Content + - `class TextDeltaBlock: …` -- `object` + The text content that is part of a message. -### Message Content Delta + - `index: int` -- `object` + The index of the content part in the message. -### Message Content Part Param + - `type: Literal["text"]` -- `MessageContentPartParam` + Always `text`. - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `"text"` - - `class ImageFileContentBlock: …` + - `text: Optional[TextDelta]` - References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. + - `annotations: Optional[List[AnnotationDelta]]` - - `image_file: ImageFileParam` + - `class FileCitationDeltaAnnotation: …` - - `file_id: str` + 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. - The [File](https://platform.openai.com/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `index: int` - - `detail: Optional[Literal["auto", "low", "high"]]` + The index of the annotation in the text content part. - 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`. + - `type: Literal["file_citation"]` - - `"auto"` + Always `file_citation`. - - `"low"` + - `"file_citation"` - - `"high"` + - `end_index: Optional[int]` - - `type: Literal["image_file"]` + - `file_citation: Optional[FileCitation]` - Always `image_file`. + - `file_id: Optional[str]` - - `"image_file"` + The ID of the specific File the citation is from. - - `class ImageURLContentBlock: …` + - `quote: Optional[str]` - References an image URL in the content of a message. + The specific quote in the file. - - `image_url: ImageURLParam` + - `start_index: Optional[int]` - - `url: str` + - `text: Optional[str]` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The text in the message content that needs to be replaced. - - `detail: Optional[Literal["auto", "low", "high"]]` + - `class FilePathDeltaAnnotation: …` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"auto"` + - `index: int` - - `"low"` + The index of the annotation in the text content part. - - `"high"` + - `type: Literal["file_path"]` - - `type: Literal["image_url"]` + Always `file_path`. - The type of the content part. + - `"file_path"` - - `"image_url"` + - `end_index: Optional[int]` - - `class TextContentBlockParam: …` + - `file_path: Optional[FilePath]` - The text content that is part of a message. + - `file_id: Optional[str]` - - `text: str` + The ID of the file that was generated. - Text content to be sent to the model + - `start_index: Optional[int]` - - `type: Literal["text"]` + - `text: Optional[str]` - Always `text`. + The text in the message content that needs to be replaced. - - `"text"` + - `value: Optional[str]` -### Message Deleted + The data that makes up the text. -- `class MessageDeleted: …` + - `class RefusalDeltaBlock: …` - - `id: str` + The refusal content that is part of a message. - - `deleted: bool` + - `index: int` - - `object: Literal["thread.message.deleted"]` + The index of the refusal part in the message. - - `"thread.message.deleted"` + - `type: Literal["refusal"]` -### Message Delta + Always `refusal`. -- `class MessageDelta: …` + - `"refusal"` - The delta containing the fields that have changed on the Message. + - `refusal: Optional[str]` - - `content: Optional[List[object]]` + - `class ImageURLDeltaBlock: …` - The content of the message in array of text and/or images. + References an image URL in the content of a message. - - `role: Optional[Literal["user", "assistant"]]` + - `index: int` - The entity that produced the message. One of `user` or `assistant`. + The index of the content part in the message. - - `"user"` + - `type: Literal["image_url"]` - - `"assistant"` + Always `image_url`. -### Message Delta Event + - `"image_url"` -- `class MessageDeltaEvent: …` + - `image_url: Optional[ImageURLDelta]` - Represents a message delta i.e. any changed fields on a message during streaming. + - `detail: Optional[Literal["auto", "low", "high"]]` - - `id: str` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The identifier of the message, which can be referenced in API endpoints. + - `"auto"` - - `delta: MessageDelta` + - `"low"` - The delta containing the fields that have changed on the Message. + - `"high"` - - `content: Optional[List[object]]` + - `url: Optional[str]` - The content of the message in array of text and/or images. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - `role: Optional[Literal["user", "assistant"]]` @@ -8985,7 +12549,55 @@ print(deleted_message) - `class Text: …` - - `annotations: List[object]` + - `annotations: List[Annotation]` + + - `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` + + - `file_citation: FileCitation` + + - `file_id: str` + + The ID of the specific File the citation is from. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_citation"]` + + Always `file_citation`. + + - `"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` + + - `file_path: FilePath` + + - `file_id: str` + + The ID of the file that was generated. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_path"]` + + Always `file_path`. + + - `"file_path"` - `value: str` @@ -8999,7 +12611,55 @@ print(deleted_message) - `text: Text` - - `annotations: List[object]` + - `annotations: List[Annotation]` + + - `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` + + - `file_citation: FileCitation` + + - `file_id: str` + + The ID of the specific File the citation is from. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_citation"]` + + Always `file_citation`. + + - `"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` + + - `file_path: FilePath` + + - `file_id: str` + + The ID of the file that was generated. + + - `start_index: int` + + - `text: str` + + The text in the message content that needs to be replaced. + + - `type: Literal["file_path"]` + + Always `file_path`. + + - `"file_path"` - `value: str` @@ -9031,7 +12691,67 @@ print(deleted_message) - `class TextDelta: …` - - `annotations: Optional[List[object]]` + - `annotations: Optional[List[AnnotationDelta]]` + + - `class FileCitationDeltaAnnotation: …` + + 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. + + - `index: int` + + The index of the annotation in the text content part. + + - `type: Literal["file_citation"]` + + Always `file_citation`. + + - `"file_citation"` + + - `end_index: Optional[int]` + + - `file_citation: Optional[FileCitation]` + + - `file_id: Optional[str]` + + The ID of the specific File the citation is from. + + - `quote: Optional[str]` + + The specific quote in the file. + + - `start_index: Optional[int]` + + - `text: Optional[str]` + + The text in the message content that needs to be replaced. + + - `class FilePathDeltaAnnotation: …` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `index: int` + + The index of the annotation in the text content part. + + - `type: Literal["file_path"]` + + Always `file_path`. + + - `"file_path"` + + - `end_index: Optional[int]` + + - `file_path: Optional[FilePath]` + + - `file_id: Optional[str]` + + The ID of the file that was generated. + + - `start_index: Optional[int]` + + - `text: Optional[str]` + + The text in the message content that needs to be replaced. - `value: Optional[str]` @@ -9055,7 +12775,67 @@ print(deleted_message) - `text: Optional[TextDelta]` - - `annotations: Optional[List[object]]` + - `annotations: Optional[List[AnnotationDelta]]` + + - `class FileCitationDeltaAnnotation: …` + + 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. + + - `index: int` + + The index of the annotation in the text content part. + + - `type: Literal["file_citation"]` + + Always `file_citation`. + + - `"file_citation"` + + - `end_index: Optional[int]` + + - `file_citation: Optional[FileCitation]` + + - `file_id: Optional[str]` + + The ID of the specific File the citation is from. + + - `quote: Optional[str]` + + The specific quote in the file. + + - `start_index: Optional[int]` + + - `text: Optional[str]` + + The text in the message content that needs to be replaced. + + - `class FilePathDeltaAnnotation: …` + + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + + - `index: int` + + The index of the annotation in the text content part. + + - `type: Literal["file_path"]` + + Always `file_path`. + + - `"file_path"` + + - `end_index: Optional[int]` + + - `file_path: Optional[FilePath]` + + - `file_id: Optional[str]` + + The ID of the file that was generated. + + - `start_index: Optional[int]` + + - `text: Optional[str]` + + The text in the message content that needs to be replaced. - `value: Optional[str]`