Skip to content

aiollm_openai

aiollm_openai

OpenAI provider: its client, API and error resolver.

Modules:

Name Description
adapters

OpenAI's adapters between shared types and its methods.

api

URLs of the OpenAI API.

client

Client of the OpenAI API.

methods

OpenAI's methods of the Responses and Files APIs and of containers.

resolver

Error mapping of the OpenAI API.

tools

OpenAI's built-in tools, as the shared request takes them.

types

OpenAI's own types and the options of a generation call.

Classes:

Name Description
OpenAIAPI

Builds OpenAI request URLs.

OpenAIClient

Client of the OpenAI API.

OpenAIErrorResolver

Error resolver with OpenAI's specifics.

Attributes:

Name Type Description
OPENAI_API Final[OpenAIAPI]

The OpenAI API, version 1.

OPENAI_API module-attribute

OPENAI_API: Final[OpenAIAPI] = OpenAIAPI(
    base_url="https://api.openai.com/", version="v1"
)

The OpenAI API, version 1.

OpenAIAPI

OpenAIAPI(base_url: str | URL, version: str)

Bases: BaseAPI

Builds OpenAI request URLs.

OpenAIClient

OpenAIClient(
    token: str | None = None,
    *,
    session: ISession | None = None,
    **session_kwargs: Unpack[AiohttpSessionOptions],
)

Bases: BaseProviderClient

Client of the OpenAI API.

A given session that does not fit OpenAI (the generic BaseErrorResolver, a key outside Authorization) gets a warning from warn_about_session.

Attributes:

Name Type Description
generation

Shared text generation over the Responses API.

files

Shared file storage over the Files API; an upload is a user_data file unless provider_options sets another purpose.

Example

async with OpenAIClient("sk-...") as client: ... response = await client.generation.create( ... GenerationRequest(model="gpt-5", input="Hi") ... )

Create the client from a token or a ready session.

Parameters:

Name Type Description Default
token str | None

API key; an AiohttpSession with OpenAI's URL, error resolver and BearerAuth is created from it. Without a token and a session, OPENAI_API_KEY is used.

None
session ISession | None

A ready session, for custom settings; it is checked with warn_about_session.

None
**session_kwargs Unpack[AiohttpSessionOptions]

Further arguments of the AiohttpSession built from the token, such as timeout or max_body_size.

{}

Raises:

Type Description
ValueError

If both token and session are given, or neither is and OPENAI_API_KEY is unset or empty, or session_kwargs are given with a session.

OpenAIErrorResolver

Bases: BaseErrorResolver

Error resolver with OpenAI's specifics.

A 429 whose code or type is in QUOTA_CODES (no credit left, a spend or usage limit reached) is a QuotaExceededError and is not retried, also when a stream reports it. The error event of a response stream is flat ({"type": "error", "code", "message", "param"}) and is read like an error object; a response.failed event and a Response with status failed are read by their response.error. They come with a 200 status, so their class is picked by their code or type through ERROR_STATUSES; a code it does not list, such as invalid_prompt, gives APIStatusError itself. As for every resolver, such an in-band failure is never transient.

Methods:

Name Description
resolve

Build the error, reading OpenAI's in-band failures too.

classify_status

Pick the error class and transience, quota errors first.

resolve

resolve(
    *, status: int, body: Any, headers: Mapping[str, str]
) -> APIStatusError

Build the error, reading OpenAI's in-band failures too.

Parameters:

Name Type Description Default
status int

HTTP status code of the response.

required
body Any

Decoded JSON body or event data, or None.

required
headers Mapping[str, str]

Response headers.

required

Returns:

Type Description
APIStatusError

The error to raise.

classify_status

classify_status(
    *,
    status: int,
    code: str | None,
    error_type: str | None,
    message: str | None,
    retry_after: float | None,
) -> tuple[type[APIStatusError], bool]

Pick the error class and transience, quota errors first.

Parameters:

Name Type Description Default
status int

HTTP status the error is classified by.

required
code str | None

Provider error code, if any.

required
error_type str | None

Provider error type, if any.

required
message str | None

Error message, if any.

required
retry_after float | None

Seconds from Retry-After, if any.

required

Returns:

Type Description
type[APIStatusError]

QuotaExceededError (never transient) for a 429 with a

bool

quota code or type, else the default classification.

methods

OpenAI's methods of the Responses and Files APIs and of containers.

Their request fields are the generated mixins of methods.params.

Modules:

Name Description
files

Methods of OpenAI's Files API, and the download of a container's file.

params

Generated provider component types.

responses

Methods of OpenAI's Responses API.

Type Aliases:

Name Description
Metadata

OpenAI metadata: up to 16 pairs, keys up to 64 and values up to 512

Classes:

Name Description
CreateFile

Upload a file, to refer to it by its id in later requests.

DeleteFile

Delete a file.

DownloadFile

Stream the content of a file, never holding it whole in memory.

ListFiles

List the files of the project, one page at a time.

RetrieveContainerFileContent

Stream the content of a file in a code interpreter's container.

RetrieveFile

Get the metadata of a file.

CreateResponse

Create a response and wait for the whole of it.

StreamResponse

Create a response and stream its events.

Metadata

Metadata = Annotated[
    dict[
        Annotated[str, StringConstraints(max_length=64)],
        Annotated[str, StringConstraints(max_length=512)],
    ],
    MaxLen(16),
]

OpenAI metadata: up to 16 pairs, keys up to 64 and values up to 512 characters, checked before the request is sent.

The limits are only written in the schema's description, so the generated methods.params type does not check them; both methods narrow their metadata field to this type.

CreateFile

Bases: CreateFileParams, BaseAPIMethod[OpenAIFile]

Upload a file, to refer to it by its id in later requests.

The upload is never retried: POST /files is not idempotent, and a retry after a lost answer would store the file twice. A timeout or a lost connection may therefore leave a file at OpenAI whose id you never got; give the file an expires_after where that matters. expires_after is sent as expires_after[anchor] and expires_after[seconds], the form fields OpenAI reads.

A file id refers to data in the project: treat it as a server-side reference and never take one from an end user.

Example

file = await client.send_request( ... CreateFile(file=Path("report.pdf"), purpose="user_data") ... ) file.id

DeleteFile

Bases: DeleteFileParams, BaseAPIMethod[DeleteFileResponse]

Delete a file.

It is retried on a transient failure, as the official SDKs do; a retry after a deletion whose answer was lost raises NotFoundError, since the file is already gone.

Example

await client.send_request(DeleteFile(file_id="file-1"))

DownloadFile

Bases: DownloadFileParams, BaseStreamMethod[bytes]

Stream the content of a file, never holding it whole in memory.

Only opening the download is retried. Stream.save(path) writes it to a file.

Example

method = DownloadFile(file_id="file-1") async with client.stream(method) as content: ... await content.save(Path("output.jsonl"))

ListFiles

Bases: ListFilesParams, BaseAPIMethod[ListFilesResponse]

List the files of the project, one page at a time.

Pass the page's last_id as after while has_more is true.

Example

page = await client.send_request(ListFiles(limit=100)) while page.has_more: ... page = await client.send_request( ... ListFiles(limit=100, after=page.last_id) ... )

RetrieveContainerFileContent

Bases: RetrieveContainerFileContentParams, BaseStreamMethod[bytes]

Stream the content of a file in a code interpreter's container.

The files the code writes stay in its container, not in the Files API, until the container expires; client.files.download sends this method for a ProducedFile with a container_id. Only opening the download is retried. OpenAI answers 404 once the container has expired.

Example

method = RetrieveContainerFileContent( ... container_id="cntr_123", file_id="cfile_456" ... ) async with client.stream(method) as content: ... await content.save(Path("chart.png"))

RetrieveFile

Bases: RetrieveFileParams, BaseAPIMethod[OpenAIFile]

Get the metadata of a file.

Example

file = await client.send_request(RetrieveFile(file_id="file-1"))

CreateResponse

Bases: CreateResponseParams, BaseAPIMethod[Response]

Create a response and wait for the whole of it.

A response with status failed is raised as the APIStatusError that OpenAIErrorResolver picks from its error.code (such as a transient InternalServerError for server_error), with the Response as the error's raw. This is stricter than the official SDK, which returns it as data, and matches its get_final_response() and Anthropic, where a failure is always an error. A transient failure (a lost connection, a timeout, a 5xx, a 429 with Retry-After) is retried, as the official SDKs do. A timeout or a lost connection may hide a generation that ran on the server, a risk the SDKs accept too.

Example

response = await client.send_request( ... CreateResponse(model="gpt-5", input="Hi") ... ) response.output

StreamResponse

Bases: StreamResponseParams, BaseStreamMethod[ResponseStreamEvent]

Create a response and stream its events.

Only opening the stream is retried, on a transient failure; once events arrive, a failure reaches the caller. The stream ends with response.completed or response.incomplete; a body that ends before one of them raises APIStreamInterruptedError. An error event and response.failed are raised as the APIStatusError that OpenAIErrorResolver picks from their code; for response.failed the event is the error's raw.

Its stream field is always True: it asks for server-sent events.

Example

method = StreamResponse(model="gpt-5", input="Hi") async with client.stream(method) as events: ... async for event in events: ... if isinstance(event, OutputTextDeltaEvent): ... print(event.delta, end="")

params

Generated provider component types.

Modules:

Name Description
containers

Provider containers types generated from OpenAPI.

files

Provider files types generated from OpenAPI.

images

Provider images types generated from OpenAPI.

messages

Provider messages types generated from OpenAPI.

responses

Provider responses types generated from OpenAPI.

shared

Provider shared types generated from OpenAPI.

tools

Provider tools types generated from OpenAPI.

usage

Provider usage types generated from OpenAPI.

Classes:

Name Description
RetrieveContainerFileContentParams

RetrieveContainerFileContentParams from the OpenAI API.

ApplyPatchCreateFileOperationParam

Instruction for creating a new file via the apply_patch tool.

ApplyPatchDeleteFileOperationParam

ApplyPatchDeleteFileOperationParam from the OpenAI API.

ApplyPatchUpdateFileOperationParam

ApplyPatchUpdateFileOperationParam from the OpenAI API.

ContainerFileCitationBody

ContainerFileCitationBody from the OpenAI API.

CreateFileParams

CreateFileParams from the OpenAI API.

CreateFileRequest

CreateFileRequest from the OpenAI API.

DeleteFileParams

DeleteFileParams from the OpenAI API.

DownloadFileParams

DownloadFileParams from the OpenAI API.

FileCitationBody

A citation to a file.

FileExpirationAfter

The expiration policy for a file.

FilePath

A path to a file.

ListFilesParams

ListFilesParams from the OpenAI API.

RetrieveFileParams

RetrieveFileParams from the OpenAI API.

CodeInterpreterOutputImage

The image output from the code interpreter.

ComputerScreenshotImage

A computer screenshot image used with the computer use tool.

ImageOptionsParam

Request level image options.

EasyInputMessage

EasyInputMessage from the OpenAI API.

FunctionShellCallOutputContentParam

FunctionShellCallOutputContentParam from the OpenAI API.

FunctionShellCallOutputExitOutcomeParam

FunctionShellCallOutputExitOutcomeParam from the OpenAI API.

FunctionShellCallOutputTimeoutOutcomeParam

Indicates that the shell call exceeded its configured time limit.

InputFileContent

A file input to the model.

InputFileContentParam

A file input to the model.

InputImageContent

An image input to the model.

InputImageContentParamAutoParam

An image input to the model.

InputMessage

InputMessage from the OpenAI API (upstream: InputMessage).

InputTextContent

A text input to the model.

InputTextContentParam

A text input to the model.

LogProb

The log probability of a token.

OutputMessage

An output message from the model.

OutputTextContent

A text output from the model.

PromptCacheBreakpointConfig

Marks the exact end of a reusable prompt prefix.

PromptCacheBreakpointParam

Marks the exact end of a reusable prompt prefix.

ReasoningTextContent

Reasoning text from the model.

RefusalContent

A refusal from the model.

SummaryTextContent

A summary text from the model.

TopLogProb

The top log probability of a token.

UrlCitationBody

A citation for a web resource used to generate a model response.

AccessProgramsParam

Domain-specific access programs to use for this request.

BackgroundOptionsParam

Options for background execution.

CompactionTriggerItemParam

Compacts the current context.

ContextManagementParam

ContextManagementParam from the OpenAI API.

ConversationParam2

The conversation that this response belongs to.

CreateModelResponseProperties

CreateModelResponseProperties from the OpenAI API.

CreateResponse

CreateResponse from the OpenAI API.

CreateResponseParams

CreateResponseParams from the OpenAI API.

ItemReferenceParam

An internal identifier for an item to reference.

ModelResponseProperties

ModelResponseProperties from the OpenAI API.

ModerationConfigParam

The moderation policy for the response input.

ModerationParam

ModerationParam from the OpenAI API.

ModerationPolicyParam

The policy to apply to moderated response input and output.

ProgramItemParam

ProgramItemParam from the OpenAI API.

ProgramOutputItemParam

ProgramOutputItemParam from the OpenAI API.

Reasoning

Reasoning from the OpenAI API (upstream: Reasoning).

ResponseConfigurationUpdateItemParam

An update to the conversation's response configuration.

ResponseFormatJsonObject

JSON object response format.

ResponseFormatText

Default response format.

ResponsePromptCacheOptionsParam

Options for prompt caching.

ResponseProperties

ResponseProperties from the OpenAI API.

ResponseTextParam

Configuration options for a text response from the model.

StreamResponseParams

StreamResponseParams from the OpenAI API.

TextResponseFormatJsonSchema

JSON Schema response format.

AdditionalToolsItemParam

AdditionalToolsItemParam from the OpenAI API.

CompactionSummaryItemParam

CompactionSummaryItemParam from the OpenAI API.

ComputerCallOutputItemParam

The output of a computer tool call.

ComputerCallSafetyCheckParam

A pending safety check for the computer call.

ComputerToolCall

A tool call to a computer use tool.

ContainerReferenceParam

ContainerReferenceParam from the OpenAI API.

FunctionCallOutputItemParam

The output of a function tool call.

FunctionShellCallItemParam

FunctionShellCallItemParam from the OpenAI API.

FunctionShellCallOutputItemParam

The streamed output items emitted by a shell tool call.

FunctionShellToolParam

A tool that allows the model to execute shell commands.

LocalEnvironmentParam

LocalEnvironmentParam from the OpenAI API.

LocalSkillParam

LocalSkillParam from the OpenAI API.

ReasoningItem

ReasoningItem from the OpenAI API (upstream: ReasoningItem).

ToolSearchCallItemParam

ToolSearchCallItemParam from the OpenAI API.

ToolSearchOutputItemParam

ToolSearchOutputItemParam from the OpenAI API.

ApplyPatchToolCallItemParam

ApplyPatchToolCallItemParam from the OpenAI API.

ApplyPatchToolCallOutputItemParam

The streamed output emitted by an apply patch tool call.

ApplyPatchToolParam

ApplyPatchToolParam from the OpenAI API.

ApproximateLocation

ApproximateLocation from the OpenAI API.

AutoCodeInterpreterToolParam

Configuration for a code interpreter container.

ClickParam

A click action.

CodeInterpreterOutputLogs

The logs output from the code interpreter.

CodeInterpreterTool

CodeInterpreterTool from the OpenAI API.

CodeInterpreterToolCall

A tool call to run code.

ComparisonFilter

ComparisonFilter from the OpenAI API.

CompoundFilter

Combine multiple filters using and or or.

ComputerTool

A tool that controls a virtual computer.

ComputerUsePreviewTool

A tool that controls a virtual computer.

ContainerAutoParam

ContainerAutoParam from the OpenAI API.

ContainerNetworkPolicyAllowlistParam

ContainerNetworkPolicyAllowlistParam from the OpenAI API.

ContainerNetworkPolicyDisabledParam

ContainerNetworkPolicyDisabledParam from the OpenAI API.

ContainerNetworkPolicyDomainSecretParam

ContainerNetworkPolicyDomainSecretParam from the OpenAI API.

CoordParam

An x/y coordinate pair, e.g.

CustomGrammarFormatParam

A grammar defined by the user.

CustomTextFormatParam

Unconstrained free-form text.

CustomToolCall

A call to a custom tool created by the model.

CustomToolCallOutput

CustomToolCallOutput from the OpenAI API.

CustomToolParam

A custom tool that processes input using a specified format.

DirectToolCallCaller

DirectToolCallCaller from the OpenAI API.

DirectToolCallCallerParam

DirectToolCallCallerParam from the OpenAI API.

DoubleClickAction

A double click action.

DragParam

A drag action.

EmptyModelParam

EmptyModelParam from the OpenAI API.

FileSearchTool

A tool that searches for relevant content from uploaded files.

FileSearchToolCall

The results of a file search tool call.

FunctionShellActionParam

Commands and limits describing how to run the shell tool call.

FunctionTool

Defines a function in your own code the model can choose to call.

FunctionToolCall

A tool call to run a function.

FunctionToolParam

FunctionToolParam from the OpenAI API.

HTTPError

HTTPError from the OpenAI API (upstream: HTTPError).

HybridSearchOptions

HybridSearchOptions from the OpenAI API.

ImageGenTool

A tool that generates images using the GPT image models.

ImageGenToolCall

An image generation request made by the model.

ImageGenToolCallError

ImageGenToolCallError from the OpenAI API.

ImageGenToolCallModerationDetails

ImageGenToolCallModerationDetails from the OpenAI API.

InlineSkillParam

InlineSkillParam from the OpenAI API.

InlineSkillSourceParam

Inline skill payload.

KeyPressAction

A collection of keypresses the model would like to perform.

LocalShellExecAction

Execute a shell command on the server.

LocalShellToolCall

A tool call to run a command on the local shell.

LocalShellToolCallOutput

The output of a local shell tool call.

LocalShellToolParam

LocalShellToolParam from the OpenAI API.

MCPApprovalRequest

A request for human approval of a tool invocation.

MCPApprovalResponse

A response to an MCP approval request.

MCPListTools

A list of tools available on an MCP server.

MCPListToolsTool

A tool available on an MCP server.

MCPProtocolError

MCPProtocolError from the OpenAI API.

MCPTool

MCPTool from the OpenAI API (upstream: MCPTool).

MCPToolCall

An invocation of a tool on an MCP server.

MCPToolExecutionError

MCPToolExecutionError from the OpenAI API.

MCPToolFilter

A filter object to specify which tools are allowed.

MoveParam

A mouse move action.

NamespaceToolParam

Groups function/custom tools under a shared namespace.

ProgrammaticToolCallingParam

ProgrammaticToolCallingParam from the OpenAI API.

ProgramToolCallCaller

ProgramToolCallCaller from the OpenAI API.

ProgramToolCallCallerParam

ProgramToolCallCallerParam from the OpenAI API.

RankingOptions

RankingOptions from the OpenAI API.

ScreenshotParam

A screenshot action.

ScrollParam

A scroll action.

SkillReferenceParam

SkillReferenceParam from the OpenAI API.

SpecificApplyPatchParam

SpecificApplyPatchParam from the OpenAI API.

SpecificFunctionShellParam

SpecificFunctionShellParam from the OpenAI API.

SpecificProgrammaticToolCallingParam

SpecificProgrammaticToolCallingParam from the OpenAI API.

SvgParam

SvgParam from the OpenAI API (upstream: SvgParam).

SvgReasoningParam

Reasoning effort for SVG authoring.

ToolChoiceAllowed

Constrains the tools available to the model to a pre-defined set.

ToolChoiceCustom

ToolChoiceCustom from the OpenAI API.

ToolChoiceFunction

Use this option to force the model to call a specific function.

ToolChoiceMCP

ToolChoiceMCP from the OpenAI API (upstream: ToolChoiceMCP).

ToolChoiceTypes

ToolChoiceTypes from the OpenAI API.

ToolSearchOutputFunctionToolParam

ToolSearchOutputFunctionToolParam from the OpenAI API.

ToolSearchOutputNamespaceToolParam

Groups function/custom tools under a shared namespace.

ToolSearchToolParam

Hosted or BYOT tool search configuration for deferred tools.

TypeParam

An action to type in text.

WaitParam

A wait action.

WebSearchActionFind

WebSearchActionFind from the OpenAI API.

WebSearchActionOpenPage

WebSearchActionOpenPage from the OpenAI API.

WebSearchActionSearch

Action type "search" - Performs a web search query.

WebSearchPreviewTool

WebSearchPreviewTool from the OpenAI API.

WebSearchTool

Search the Internet for sources related to the prompt.

WebSearchToolCall

The results of a web search tool call.

SvgUsage

SvgUsage from the OpenAI API (upstream: SvgUsage).

RetrieveContainerFileContentParams

Bases: BaseAPIType

RetrieveContainerFileContentParams from the OpenAI API.

ApplyPatchCreateFileOperationParam

Bases: BaseAPIType

Instruction for creating a new file via the apply_patch tool.

Attributes:

Name Type Description
type Annotated[Literal['create_file'], Field(description='The operation type. Always `create_file`.')]

The operation type. Always create_file.

path Annotated[str, Field(description='Path of the file to create relative to the workspace root.', min_length=1)]

Path of the file to create relative to the workspace root.

diff Annotated[str, Field(description='Unified diff content to apply when creating the file.', max_length=10485760)]

Unified diff content to apply when creating the file.

ApplyPatchDeleteFileOperationParam

Bases: BaseAPIType

ApplyPatchDeleteFileOperationParam from the OpenAI API.

Instruction for deleting an existing file via the apply_patch tool.

Attributes:

Name Type Description
type Annotated[Literal['delete_file'], Field(description='The operation type. Always `delete_file`.')]

The operation type. Always delete_file.

path Annotated[str, Field(description='Path of the file to delete relative to the workspace root.', min_length=1)]

Path of the file to delete relative to the workspace root.

ApplyPatchUpdateFileOperationParam

Bases: BaseAPIType

ApplyPatchUpdateFileOperationParam from the OpenAI API.

Instruction for updating an existing file via the apply_patch tool.

Attributes:

Name Type Description
type Annotated[Literal['update_file'], Field(description='The operation type. Always `update_file`.')]

The operation type. Always update_file.

path Annotated[str, Field(description='Path of the file to update relative to the workspace root.', min_length=1)]

Path of the file to update relative to the workspace root.

diff Annotated[str, Field(description='Unified diff content to apply to the existing file.', max_length=10485760)]

Unified diff content to apply to the existing file.

ContainerFileCitationBody

Bases: BaseAPIType

ContainerFileCitationBody from the OpenAI API.

A citation for a container file used to generate a model response.

Attributes:

Name Type Description
type Annotated[Literal['container_file_citation'], Field(description='The type of the container file citation. Always `container_file_citation`.')]

The type of the container file citation. Always container_file_citation.

container_id Annotated[str, Field(description='The ID of the container file.')]

The ID of the container file.

file_id Annotated[str, Field(description='The ID of the file.')]

The ID of the file.

start_index Annotated[int, Field(description='The index of the first character of the container file citation in the message.')]

The index of the first character of the container file citation in the message.

end_index Annotated[int, Field(description='The index of the last character of the container file citation in the message.')]

The index of the last character of the container file citation in the message.

filename Annotated[str, Field(description='The filename of the container file cited.')]

The filename of the container file cited.

CreateFileParams

Bases: BaseAPIType

CreateFileParams from the OpenAI API.

Attributes:

Name Type Description
file Annotated[InputFile, Field(description='The File object (not file name) to be uploaded.')]

The File object (not file name) to be uploaded.

purpose Annotated[Literal['assistants', 'batch', 'fine-tune', 'vision', 'user_data', 'evals'], Field(description='The intended purpose of the uploaded file. One of:\n- `assistants`: Used in the Assistants API\n- `batch`: Used in the Batch API\n- `fine-tune`: Used for fine-tuning\n- `vision`: Images used for vision fine-tuning\n- `user_data`: Flexible file type for any purpose\n- `evals`: Used for eval data sets')]

The intended purpose of the uploaded file. One of: - assistants: Used in the Assistants API - batch: Used in the Batch API - fine-tune: Used for fine-tuning - vision: Images used for vision fine-tuning - user_data: Flexible file type for any purpose - evals: Used for eval data sets

expires_after FileExpirationAfter | MISSING

The expiration policy for a file. By default, files with purpose=batch expire after 30 days and all other files are persisted until they are manually deleted.

CreateFileRequest

Bases: BaseAPIType

CreateFileRequest from the OpenAI API.

Attributes:

Name Type Description
file Annotated[InputFile, Field(description='The File object (not file name) to be uploaded.')]

The File object (not file name) to be uploaded.

purpose Annotated[Literal['assistants', 'batch', 'fine-tune', 'vision', 'user_data', 'evals'], Field(description='The intended purpose of the uploaded file. One of:\n- `assistants`: Used in the Assistants API\n- `batch`: Used in the Batch API\n- `fine-tune`: Used for fine-tuning\n- `vision`: Images used for vision fine-tuning\n- `user_data`: Flexible file type for any purpose\n- `evals`: Used for eval data sets')]

The intended purpose of the uploaded file. One of: - assistants: Used in the Assistants API - batch: Used in the Batch API - fine-tune: Used for fine-tuning - vision: Images used for vision fine-tuning - user_data: Flexible file type for any purpose - evals: Used for eval data sets

expires_after FileExpirationAfter | MISSING

The expiration policy for a file. By default, files with purpose=batch expire after 30 days and all other files are persisted until they are manually deleted.

DeleteFileParams

Bases: BaseAPIType

DeleteFileParams from the OpenAI API.

DownloadFileParams

Bases: BaseAPIType

DownloadFileParams from the OpenAI API.

FileCitationBody

Bases: BaseAPIType

A citation to a file.

Attributes:

Name Type Description
type Annotated[Literal['file_citation'], Field(description='The type of the file citation. Always `file_citation`.')]

The type of the file citation. Always file_citation.

file_id Annotated[str, Field(description='The ID of the file.')]

The ID of the file.

index Annotated[int, Field(description='The index in the output text at which to insert the file citation.')]

The index in the output text at which to insert the file citation.

filename Annotated[str, Field(description='The filename of the file cited.')]

The filename of the file cited.

FileExpirationAfter

Bases: BaseAPIType

The expiration policy for a file.

By default, files with purpose=batch expire after 30 days and all other files are persisted until they are manually deleted.

Attributes:

Name Type Description
anchor Annotated[Literal['created_at'], Field(description='Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`.')]

Anchor timestamp after which the expiration policy applies. Supported anchors: created_at.

seconds Annotated[int, Field(description='The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).', ge=3600, le=2592000)]

The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

FilePath

Bases: BaseAPIType

A path to a file.

Attributes:

Name Type Description
type Annotated[Literal['file_path'], Field(description='The type of the file path. Always `file_path`.')]

The type of the file path. Always file_path.

file_id Annotated[str, Field(description='The ID of the file.')]

The ID of the file.

index Annotated[int, Field(description='The index of the file in the list of files.')]

The index of the file in the list of files.

ListFilesParams

Bases: BaseAPIType

ListFilesParams from the OpenAI API.

RetrieveFileParams

Bases: BaseAPIType

RetrieveFileParams from the OpenAI API.

CodeInterpreterOutputImage

Bases: BaseAPIType

The image output from the code interpreter.

Attributes:

Name Type Description
type Annotated[Literal['image'], Field(description='The type of the output. Always `image`.')]

The type of the output. Always image.

url Annotated[AnyUrl, Field(description='The URL of the image output from the code interpreter.')]

The URL of the image output from the code interpreter.

ComputerScreenshotImage

Bases: BaseAPIType

A computer screenshot image used with the computer use tool.

Attributes:

Name Type Description
type Annotated[Literal['computer_screenshot'], Field(description='Specifies the event type. For a computer screenshot, this property is \nalways set to `computer_screenshot`.')]

Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot.

image_url Annotated[AnyUrl | MISSING, Field(description='The URL of the screenshot image.')]

The URL of the screenshot image.

file_id Annotated[str | MISSING, Field(description='The identifier of an uploaded file that contains the screenshot.')]

The identifier of an uploaded file that contains the screenshot.

ImageOptionsParam

Bases: BaseAPIType

Request level image options.

Attributes:

Name Type Description
context_compression Annotated[ImageContextCompression | MISSING, Field(description='Controls image context optimization. Defaults to `auto`, which uses the model, transport, and input to select a policy. Use `enabled` to require compression support or `disabled` to turn it off.')]

Controls image context optimization. Defaults to auto, which uses the model, transport, and input to select a policy. Use enabled to require compression support or disabled to turn it off.

EasyInputMessage

Bases: BaseAPIType

EasyInputMessage from the OpenAI API.

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

Attributes:

Name Type Description
role Annotated[Literal['user', 'assistant', 'system', 'developer'], Field(description='The role of the message input. One of `user`, `assistant`, `system`, or\n`developer`.')]

The role of the message input. One of user, assistant, system, or developer.

content Annotated[str | InputMessageContentList, Field(description='Text, image, or audio input to the model, used to generate a response.\nCan also contain previous assistant responses.')]

Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses.

phase MessagePhase | None | MISSING

Labels an assistant message as intermediate commentary (commentary) or the final answer (final_answer). For models like gpt-5.3-codex and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages.

type Annotated[Literal['message'] | MISSING, Field(description='The type of the message input. Always `message`.')]

The type of the message input. Always message.

FunctionShellCallOutputContentParam

Bases: BaseAPIType

FunctionShellCallOutputContentParam from the OpenAI API.

Captured stdout and stderr for a portion of a shell tool call output.

Attributes:

Name Type Description
stdout Annotated[str, Field(description='Captured stdout output for the shell call.', max_length=10485760)]

Captured stdout output for the shell call.

stderr Annotated[str, Field(description='Captured stderr output for the shell call.', max_length=10485760)]

Captured stderr output for the shell call.

outcome Annotated[FunctionShellCallOutputOutcomeParam, Field(description='The exit or timeout outcome associated with this shell call.')]

The exit or timeout outcome associated with this shell call.

FunctionShellCallOutputExitOutcomeParam

Bases: BaseAPIType

FunctionShellCallOutputExitOutcomeParam from the OpenAI API.

Indicates that the shell commands finished and returned an exit code.

Attributes:

Name Type Description
type Annotated[Literal['exit'], Field(description='The outcome type. Always `exit`.')]

The outcome type. Always exit.

exit_code Annotated[int, Field(description='The exit code returned by the shell process.')]

The exit code returned by the shell process.

FunctionShellCallOutputTimeoutOutcomeParam

Bases: BaseAPIType

Indicates that the shell call exceeded its configured time limit.

Attributes:

Name Type Description
type Annotated[Literal['timeout'], Field(description='The outcome type. Always `timeout`.')]

The outcome type. Always timeout.

InputFileContent

Bases: BaseAPIType

A file input to the model.

Attributes:

Name Type Description
type Annotated[Literal['input_file'], Field(description='The type of the input item. Always `input_file`.')]

The type of the input item. Always input_file.

filename Annotated[str | MISSING, Field(description='The name of the file to be sent to the model.')]

The name of the file to be sent to the model.

file_data Annotated[str | MISSING, Field(description='The content of the file to be sent to the model.')]

The content of the file to be sent to the model.

prompt_cache_breakpoint PromptCacheBreakpointConfig | MISSING

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

file_url Annotated[AnyUrl | MISSING, Field(description='The URL of the file to be sent to the model.')]

The URL of the file to be sent to the model.

detail Annotated[FileInputDetail | MISSING, Field(description='The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`.')]

The detail level of the file to be sent to the model. Use auto to let the system select the detail level; for GPT-5.6 and later models, auto uses high-quality rendering, which may increase input token usage. Use low for lower-cost rendering, or high to render the file at higher quality. Defaults to auto.

InputFileContentParam

Bases: BaseAPIType

A file input to the model.

Attributes:

Name Type Description
type Annotated[Literal['input_file'], Field(description='The type of the input item. Always `input_file`.')]

The type of the input item. Always input_file.

file_data InputFileContentParamFileData | None | MISSING

The base64-encoded data of the file to be sent to the model.

detail Annotated[FileDetailEnum | MISSING, Field(description='The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`.')]

The detail level of the file to be sent to the model. Use auto to let the system select the detail level; for GPT-5.6 and later models, auto uses high-quality rendering, which may increase input token usage. Use low for lower-cost rendering, or high to render the file at higher quality. Defaults to auto.

prompt_cache_breakpoint PromptCacheBreakpointParam | None | MISSING

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

InputImageContent

Bases: BaseAPIType

An image input to the model.

Learn about image inputs.

Attributes:

Name Type Description
type Annotated[Literal['input_image'], Field(description='The type of the input item. Always `input_image`.')]

The type of the input item. Always input_image.

detail Annotated[ImageDetail, Field(description='The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.')]

The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

prompt_cache_breakpoint PromptCacheBreakpointConfig | MISSING

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

InputImageContentParamAutoParam

Bases: BaseAPIType

An image input to the model.

Learn about image inputs

Attributes:

Name Type Description
type Annotated[Literal['input_image'], Field(description='The type of the input item. Always `input_image`.')]

The type of the input item. Always input_image.

image_url InputImageContentParamAutoParamImageUrl | None | MISSING

The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.

prompt_cache_breakpoint PromptCacheBreakpointParam | None | MISSING

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

InputMessage

Bases: BaseAPIType

InputMessage from the OpenAI API (upstream: InputMessage).

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

Attributes:

Name Type Description
type Annotated[Literal['message'] | MISSING, Field(description='The type of the message input. Always set to `message`.')]

The type of the message input. Always set to message.

role Annotated[Literal['user', 'system', 'developer'], Field(description='The role of the message input. One of `user`, `system`, or `developer`.')]

The role of the message input. One of user, system, or developer.

status Annotated[Literal['in_progress', 'completed', 'incomplete'] | MISSING, Field(description='The status of item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.')]

The status of item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

content InputMessageContentList

A list of one or many input items to the model, containing different content types.

InputTextContent

Bases: BaseAPIType

A text input to the model.

Attributes:

Name Type Description
type Annotated[Literal['input_text'], Field(description='The type of the input item. Always `input_text`.')]

The type of the input item. Always input_text.

text Annotated[str, Field(description='The text input to the model.')]

The text input to the model.

prompt_cache_breakpoint PromptCacheBreakpointConfig | MISSING

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

InputTextContentParam

Bases: BaseAPIType

A text input to the model.

Attributes:

Name Type Description
type Annotated[Literal['input_text'], Field(description='The type of the input item. Always `input_text`.')]

The type of the input item. Always input_text.

text Annotated[str, Field(description='The text input to the model.', max_length=10485760)]

The text input to the model.

prompt_cache_breakpoint PromptCacheBreakpointParam | None | MISSING

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

LogProb

Bases: BaseAPIType

The log probability of a token.

Attributes:

Name Type Description
top_logprobs list[TopLogProb]

The top log probability of a token.

OutputMessage

Bases: BaseAPIType

An output message from the model.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of the output message.')]

The unique ID of the output message.

type Annotated[Literal['message'], Field(description='The type of the output message. Always `message`.')]

The type of the output message. Always message.

role Annotated[Literal['assistant'], Field(description='The role of the output message. Always `assistant`.')]

The role of the output message. Always assistant.

content Annotated[list[OutputMessageContent], Field(description='The content of the output message.')]

The content of the output message.

phase MessagePhase | None | MISSING

Labels an assistant message as intermediate commentary (commentary) or the final answer (final_answer). For models like gpt-5.3-codex and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages.

status Annotated[Literal['in_progress', 'completed', 'incomplete'], Field(description='The status of the message input. One of `in_progress`, `completed`, or\n`incomplete`. Populated when input items are returned via API.')]

The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.

OutputTextContent

Bases: BaseAPIType

A text output from the model.

Attributes:

Name Type Description
type Annotated[Literal['output_text'], Field(description='The type of the output text. Always `output_text`.')]

The type of the output text. Always output_text.

text Annotated[str, Field(description='The text output from the model.')]

The text output from the model.

annotations Annotated[list[Annotation], Field(description='The annotations of the text output.')]

The annotations of the text output.

logprobs list[LogProb]

The log probability of a token.

PromptCacheBreakpointConfig

Bases: BaseAPIType

Marks the exact end of a reusable prompt prefix.

When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

Attributes:

Name Type Description
mode Annotated[Literal['explicit'], Field(description='The breakpoint mode. Always `explicit`.')]

The breakpoint mode. Always explicit.

ttl Annotated[Literal['30m', '12h'] | MISSING, Field(description='The minimum lifetime of this cache breakpoint. Defaults to the request TTL.')]

The minimum lifetime of this cache breakpoint. Defaults to the request TTL.

PromptCacheBreakpointParam

Bases: BaseAPIType

Marks the exact end of a reusable prompt prefix.

When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

Attributes:

Name Type Description
mode Annotated[Literal['explicit'], Field(description='The breakpoint mode. Always `explicit`.')]

The breakpoint mode. Always explicit.

ttl Annotated[Literal['30m', '12h'] | MISSING, Field(description='The minimum lifetime of this cache breakpoint. Defaults to the request TTL.')]

The minimum lifetime of this cache breakpoint. Defaults to the request TTL.

ReasoningTextContent

Bases: BaseAPIType

Reasoning text from the model.

Attributes:

Name Type Description
type Annotated[Literal['reasoning_text'], Field(description='The type of the reasoning text. Always `reasoning_text`.')]

The type of the reasoning text. Always reasoning_text.

text Annotated[str, Field(description='The reasoning text from the model.')]

The reasoning text from the model.

RefusalContent

Bases: BaseAPIType

A refusal from the model.

Attributes:

Name Type Description
type Annotated[Literal['refusal'], Field(description='The type of the refusal. Always `refusal`.')]

The type of the refusal. Always refusal.

refusal Annotated[str, Field(description='The refusal explanation from the model.')]

The refusal explanation from the model.

SummaryTextContent

Bases: BaseAPIType

A summary text from the model.

Attributes:

Name Type Description
type Annotated[Literal['summary_text'], Field(description='The type of the object. Always `summary_text`.')]

The type of the object. Always summary_text.

text Annotated[str, Field(description='A summary of the reasoning output from the model so far.')]

A summary of the reasoning output from the model so far.

TopLogProb

Bases: BaseAPIType

The top log probability of a token.

UrlCitationBody

Bases: BaseAPIType

A citation for a web resource used to generate a model response.

Attributes:

Name Type Description
type Annotated[Literal['url_citation'], Field(description='The type of the URL citation. Always `url_citation`.')]

The type of the URL citation. Always url_citation.

url Annotated[AnyUrl, Field(description='The URL of the web resource.')]

The URL of the web resource.

start_index Annotated[int, Field(description='The index of the first character of the URL citation in the message.')]

The index of the first character of the URL citation in the message.

end_index Annotated[int, Field(description='The index of the last character of the URL citation in the message.')]

The index of the last character of the URL citation in the message.

title Annotated[str, Field(description='The title of the web resource.')]

The title of the web resource.

AccessProgramsParam

Bases: BaseAPIType

Domain-specific access programs to use for this request.

Attributes:

Name Type Description
cyber Annotated[CyberAccessProgramEnum | MISSING, Field(description="The Cyber access program to use for this request. Supported values are `standard`, `daybreak_blue`, and `daybreak_red`. If omitted, the API resolves the program from the model's Cyber tier and your organization and project access, subject to model-specific eligibility restrictions. By default, models without a Cyber tier use Standard. Blue-tier models use Daybreak Blue when authorized; otherwise they fall back to Standard unless the model requires Daybreak access. Red-tier models use Daybreak Red and require authorization. Requests that require unavailable Daybreak access return 403. An implicit Standard fallback is represented by null in the response's access_programs field, rather than an explicit Standard selection.")]

The Cyber access program to use for this request. Supported values are standard, daybreak_blue, and daybreak_red. If omitted, the API resolves the program from the model's Cyber tier and your organization and project access, subject to model-specific eligibility restrictions. By default, models without a Cyber tier use Standard. Blue-tier models use Daybreak Blue when authorized; otherwise they fall back to Standard unless the model requires Daybreak access. Red-tier models use Daybreak Red and require authorization. Requests that require unavailable Daybreak access return 403. An implicit Standard fallback is represented by null in the response's access_programs field, rather than an explicit Standard selection.

BackgroundOptionsParam

Bases: BaseAPIType

Options for background execution.

Attributes:

Name Type Description
completion_window Annotated[BackgroundCompletionWindowEnum | MISSING, Field(description='The completion window for background execution. Defaults to `soonest`; `2h` and `8h` select discounted background execution.')]

The completion window for background execution. Defaults to soonest; 2h and 8h select discounted background execution.

continuation_id Annotated[str | MISSING, Field(description='A customer-provided opaque identifier used to prioritize related background requests. It does not add prior history to the input.')]

A customer-provided opaque identifier used to prioritize related background requests. It does not add prior history to the input.

CompactionTriggerItemParam

Bases: BaseAPIType

Compacts the current context.

Must be the final input item.

Attributes:

Name Type Description
type Annotated[Literal['compaction_trigger'], Field(description='The type of the item. Always `compaction_trigger`.')]

The type of the item. Always compaction_trigger.

ContextManagementParam

Bases: BaseAPIType

ContextManagementParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[str, Field(description="The context management entry type. Currently only 'compaction' is supported.")]

The context management entry type. Currently only 'compaction' is supported.

compact_threshold ContextManagementParamCompactThreshold | None | MISSING

Token threshold at which compaction should be triggered for this entry.

ConversationParam2

Bases: BaseAPIType

The conversation that this response belongs to.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of the conversation.', examples=['conv_123'])]

The unique ID of the conversation.

CreateModelResponseProperties

Bases: BaseAPIType

CreateModelResponseProperties from the OpenAI API.

Attributes:

Name Type Description
temperature CreateModelResponsePropertiesTemperature | None | MISSING

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

top_p CreateModelResponsePropertiesTopP | None | MISSING

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.

user Annotated[str | None | MISSING, Field(deprecated=True, description='This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations.\nA stable identifier for your end-users.\nUsed to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).', examples=['user-1234'])]

This field is being replaced by safety_identifier and prompt_cache_key. Use prompt_cache_key instead to maintain caching optimizations. A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn

more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). safety_identifier: A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user, with a maximum length of 128 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. Learn more.

CreateResponse

Bases: BaseAPIType

CreateResponse from the OpenAI API.

Attributes:

Name Type Description
temperature CreateResponseTemperature | None | MISSING

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

top_p CreateResponseTopP | None | MISSING

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.

user Annotated[str | None | MISSING, Field(deprecated=True, description='This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations.\nA stable identifier for your end-users.\nUsed to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).', examples=['user-1234'])]

This field is being replaced by safety_identifier and prompt_cache_key. Use prompt_cache_key instead to maintain caching optimizations. A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn

more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). safety_identifier: A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user, with a maximum length of 128 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. Learn more. model: Model ID used to generate the response, like gpt-6.2-astra. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models. text: Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - Text inputs and outputs - Structured Outputs tools: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call. access_programs: Domain-specific access programs to use for this request. image: Request level image options. prompt_cache_options: Options for prompt caching. Supported for gpt-5.6 and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with prompt_cache_breakpoint. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set mode to explicit to disable the implicit breakpoint. The ttl defaults to 30m. Supported lifetimes depend on the API. See the prompt caching guide for current details. reasoning: Configuration options for reasoning models. input: Text, image, or file inputs to the model, used to generate a response. include: Specify additional output data to include in the model response. Currently supported values are: - web_search_call.results: Include the search results of the web search tool call. - web_search_call.action.sources: Include the sources of the web search tool call. - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.input_image.image_url: Include image urls from the input message. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). moderation: Configuration for running moderation on the input and output of this response. background_options: Options for background execution on HTTP requests. The 2h and 8h completion windows require background: true, Standard processing, and stream: false or omitted. conversation: The conversation that this response belongs to. Items from this conversation are prepended to input_items for this response request. Input items and output items from this response are automatically added to this conversation after this response completes. context_management: Context management configuration for this request. max_output_tokens: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.

CreateResponseParams

Bases: BaseAPIType

CreateResponseParams from the OpenAI API.

Attributes:

Name Type Description
temperature CreateResponseParamsTemperature | None | MISSING

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

top_p CreateResponseParamsTopP | None | MISSING

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.

user Annotated[str | None | MISSING, Field(deprecated=True, description='This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations.\nA stable identifier for your end-users.\nUsed to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).', examples=['user-1234'])]

This field is being replaced by safety_identifier and prompt_cache_key. Use prompt_cache_key instead to maintain caching optimizations. A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn

more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). safety_identifier: A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user, with a maximum length of 128 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. Learn more. model: Model ID used to generate the response, like gpt-6.2-astra. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models. text: Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - Text inputs and outputs - Structured Outputs tools: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call. access_programs: Domain-specific access programs to use for this request. image: Request level image options. prompt_cache_options: Options for prompt caching. Supported for gpt-5.6 and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with prompt_cache_breakpoint. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set mode to explicit to disable the implicit breakpoint. The ttl defaults to 30m. Supported lifetimes depend on the API. See the prompt caching guide for current details. reasoning: Configuration options for reasoning models. input: Text, image, or file inputs to the model, used to generate a response. include: Specify additional output data to include in the model response. Currently supported values are: - web_search_call.results: Include the search results of the web search tool call. - web_search_call.action.sources: Include the sources of the web search tool call. - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.input_image.image_url: Include image urls from the input message. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). moderation: Configuration for running moderation on the input and output of this response. background_options: Options for background execution on HTTP requests. The 2h and 8h completion windows require background: true, Standard processing, and stream: false or omitted. conversation: The conversation that this response belongs to. Items from this conversation are prepended to input_items for this response request. Input items and output items from this response are automatically added to this conversation after this response completes. context_management: Context management configuration for this request. max_output_tokens: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.

ItemReferenceParam

Bases: BaseAPIType

An internal identifier for an item to reference.

Attributes:

Name Type Description
id Annotated[str, Field(description='The ID of the item to reference.')]

The ID of the item to reference.

ModelResponseProperties

Bases: BaseAPIType

ModelResponseProperties from the OpenAI API.

Attributes:

Name Type Description
top_logprobs ModelResponsePropertiesTopLogprobs | None | MISSING

An integer between 0 and 20 specifying the maximum number of most likely tokens to return at each token position, each with an associated log probability. In some cases, the number of returned tokens may be fewer than requested.

temperature ModelResponsePropertiesTemperature | None | MISSING

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

top_p ModelResponsePropertiesTopP | None | MISSING

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.

user Annotated[str | None | MISSING, Field(deprecated=True, description='This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations.\nA stable identifier for your end-users.\nUsed to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).', examples=['user-1234'])]

This field is being replaced by safety_identifier and prompt_cache_key. Use prompt_cache_key instead to maintain caching optimizations. A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn

more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). safety_identifier: A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user, with a maximum length of 128 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. Learn more.

ModerationConfigParam

Bases: BaseAPIType

The moderation policy for the response input.

ModerationParam

Bases: BaseAPIType

ModerationParam from the OpenAI API.

Configuration for running moderation on the input and output of this response.

Attributes:

Name Type Description
model Annotated[str, Field(description="The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'.")]

The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'.

policy ModerationPolicyParam | None | MISSING

The policy to apply to moderated response input and output.

ModerationPolicyParam

Bases: BaseAPIType

The policy to apply to moderated response input and output.

Attributes:

Name Type Description
input ModerationConfigParam | None | MISSING

The moderation policy for the response input.

output ModerationConfigParam | None | MISSING

The moderation policy for the response input.

ProgramItemParam

Bases: BaseAPIType

ProgramItemParam from the OpenAI API.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of this program item.', examples=['cm_123'])]

The unique ID of this program item.

type Annotated[Literal['program'], Field(description='The item type. Always `program`.')]

The item type. Always program.

call_id Annotated[str, Field(description='The stable call ID of the program item.', max_length=64, min_length=1)]

The stable call ID of the program item.

code Annotated[str, Field(description='The JavaScript source executed by programmatic tool calling.', max_length=10485760)]

The JavaScript source executed by programmatic tool calling.

fingerprint Annotated[str, Field(description='Opaque program replay fingerprint that must be round-tripped.', max_length=10485760)]

Opaque program replay fingerprint that must be round-tripped.

ProgramOutputItemParam

Bases: BaseAPIType

ProgramOutputItemParam from the OpenAI API.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of this program output item.', examples=['cmo_123'])]

The unique ID of this program output item.

type Annotated[Literal['program_output'], Field(description='The item type. Always `program_output`.')]

The item type. Always program_output.

call_id Annotated[str, Field(description='The call ID of the program item.', max_length=64, min_length=1)]

The call ID of the program item.

result Annotated[str, Field(description='The result produced by the program item.', max_length=10485760)]

The result produced by the program item.

status Annotated[ProgramOutputItemStatus, Field(description='The terminal status of the program output.')]

The terminal status of the program output.

Reasoning

Bases: BaseAPIType

Reasoning from the OpenAI API (upstream: Reasoning).

Configuration options for reasoning models.

Attributes:

Name Type Description
mode Annotated[ReasoningModeEnum | MISSING, Field(description='Controls the reasoning execution mode for the request.\n\nWhen returned on a response, this is the effective execution mode.')]

Controls the reasoning execution mode for the request. When returned on a response, this is the effective execution mode.

ResponseConfigurationUpdateItemParam

Bases: BaseAPIType

An update to the conversation's response configuration.

Supply reasoning, text, or both. Each setting stays in effect until a later update replaces it.

Attributes:

Name Type Description
type Annotated[Literal['configuration_update'], Field(description='The item type. Always `configuration_update`.')]

The item type. Always configuration_update.

reasoning Annotated[ResponseConfigurationUpdateItemParamReasoning | MISSING, Field(description='Updates to reasoning configuration. Only effort is supported.')]

Updates to reasoning configuration. Only effort is supported.

text Annotated[ResponseConfigurationUpdateItemParamText | MISSING, Field(description='The text output configuration for subsequent responses.')]

The text output configuration for subsequent responses.

ResponseFormatJsonObject

Bases: BaseAPIType

JSON object response format.

An older method of generating JSON responses. Using json_schema is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.

Attributes:

Name Type Description
type Annotated[Literal['json_object'], Field(description='The type of response format being defined. Always `json_object`.')]

The type of response format being defined. Always json_object.

ResponseFormatText

Bases: BaseAPIType

Default response format.

Used to generate text responses.

Attributes:

Name Type Description
type Annotated[Literal['text'], Field(description='The type of response format being defined. Always `text`.')]

The type of response format being defined. Always text.

ResponsePromptCacheOptionsParam

Bases: BaseAPIType

Options for prompt caching.

Supported for gpt-5.6 and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with prompt_cache_breakpoint. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set mode to explicit to disable the implicit breakpoint. The ttl defaults to 30m. Supported lifetimes depend on the API. See the prompt caching guide for current details.

Attributes:

Name Type Description
ttl Annotated[Literal['30m', '12h'] | MISSING, Field(description='The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Supported values are `30m` (the default) and `12h`. The backend may retain cache entries for longer.')]

The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Supported values are 30m (the default) and 12h. The backend may retain cache entries for longer.

mode Annotated[PromptCacheModeEnum | MISSING, Field(description='Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching.')]

Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to implicit. With implicit, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With explicit, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching.

prewarm Annotated[bool | MISSING, Field(description='Prepares the prompt cache without generating output. Defaults to `false`. When set to `true`, overrides the `generate` field to `false`.')]

Prepares the prompt cache without generating output. Defaults to false. When set to true, overrides the generate field to false.

ResponseProperties

Bases: BaseAPIType

ResponseProperties from the OpenAI API.

Attributes:

Name Type Description
model Annotated[ModelIdsResponses | MISSING, Field(description='Model ID used to generate the response, like `gpt-6.2-astra`. OpenAI\noffers a wide range of models with different capabilities, performance\ncharacteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models)\nto browse and compare available models.')]

Model ID used to generate the response, like gpt-6.2-astra. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.

text ResponseTextParam | MISSING

Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and

outputs](https://developers.openai.com/api/docs/guides/text) - Structured Outputs tools: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call.

ResponseTextParam

Bases: BaseAPIType

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more: - Text inputs and outputs - Structured Outputs

Attributes:

Name Type Description
format TextResponseFormatConfiguration | MISSING

An object specifying the format that the model must output.

StreamResponseParams

Bases: BaseAPIType

StreamResponseParams from the OpenAI API.

Attributes:

Name Type Description
temperature StreamResponseParamsTemperature | None | MISSING

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

top_p StreamResponseParamsTopP | None | MISSING

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.

user Annotated[str | None | MISSING, Field(deprecated=True, description='This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations.\nA stable identifier for your end-users.\nUsed to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).', examples=['user-1234'])]

This field is being replaced by safety_identifier and prompt_cache_key. Use prompt_cache_key instead to maintain caching optimizations. A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn

more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). safety_identifier: A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user, with a maximum length of 128 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. Learn more. model: Model ID used to generate the response, like gpt-6.2-astra. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models. text: Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - Text inputs and outputs - Structured Outputs tools: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call. access_programs: Domain-specific access programs to use for this request. image: Request level image options. prompt_cache_options: Options for prompt caching. Supported for gpt-5.6 and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with prompt_cache_breakpoint. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set mode to explicit to disable the implicit breakpoint. The ttl defaults to 30m. Supported lifetimes depend on the API. See the prompt caching guide for current details. reasoning: Configuration options for reasoning models. input: Text, image, or file inputs to the model, used to generate a response. include: Specify additional output data to include in the model response. Currently supported values are: - web_search_call.results: Include the search results of the web search tool call. - web_search_call.action.sources: Include the sources of the web search tool call. - code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items. - computer_call_output.output.image_url: Include image urls from the computer call output. - file_search_call.results: Include the search results of the file search tool call. - message.input_image.image_url: Include image urls from the input message. - message.output_text.logprobs: Include logprobs with assistant messages. - reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program). moderation: Configuration for running moderation on the input and output of this response. background_options: Options for background execution on HTTP requests. The 2h and 8h completion windows require background: true, Standard processing, and stream: false or omitted. conversation: The conversation that this response belongs to. Items from this conversation are prepended to input_items for this response request. Input items and output items from this response are automatically added to this conversation after this response completes. context_management: Context management configuration for this request. max_output_tokens: An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.

TextResponseFormatJsonSchema

Bases: BaseAPIType

JSON Schema response format.

Used to generate structured JSON responses. Learn more about Structured Outputs.

Attributes:

Name Type Description
type Annotated[Literal['json_schema'], Field(description='The type of response format being defined. Always `json_schema`.')]

The type of response format being defined. Always json_schema.

description Annotated[str | MISSING, Field(description='A description of what the response format is for, used by the model to\ndetermine how to respond in the format.')]

A description of what the response format is for, used by the model to determine how to respond in the format.

name Annotated[str, Field(description='The name of the response format. Must be a-z, A-Z, 0-9, or contain\nunderscores and dashes, with a maximum length of 64.')]

The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

AdditionalToolsItemParam

Bases: BaseAPIType

AdditionalToolsItemParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['additional_tools'], Field(description='The item type. Always `additional_tools`.')]

The item type. Always additional_tools.

role Annotated[Literal['developer'], Field(description='The role that provided the additional tools. Only `developer` is supported.')]

The role that provided the additional tools. Only developer is supported.

tools Annotated[list[Tool], Field(description='A list of additional tools made available at this item.')]

A list of additional tools made available at this item.

CompactionSummaryItemParam

Bases: BaseAPIType

CompactionSummaryItemParam from the OpenAI API.

A compaction item generated by the v1/responses/compact API.

Attributes:

Name Type Description
type Annotated[Literal['compaction'], Field(description='The type of the item. Always `compaction`.')]

The type of the item. Always compaction.

encrypted_content Annotated[str, Field(description='The encrypted content of the compaction summary.', max_length=104857600)]

The encrypted content of the compaction summary.

ComputerCallOutputItemParam

Bases: BaseAPIType

The output of a computer tool call.

Attributes:

Name Type Description
call_id Annotated[str, Field(description='The ID of the computer tool call that produced the output.', max_length=64, min_length=1)]

The ID of the computer tool call that produced the output.

type Annotated[Literal['computer_call_output'], Field(description='The type of the computer tool call output. Always `computer_call_output`.')]

The type of the computer tool call output. Always computer_call_output.

output ComputerScreenshotImage

A computer screenshot image used with the computer use tool.

acknowledged_safety_checks list[ComputerCallSafetyCheckParam] | None | MISSING

A pending safety check for the computer call.

ComputerCallSafetyCheckParam

Bases: BaseAPIType

A pending safety check for the computer call.

Attributes:

Name Type Description
id Annotated[str, Field(description='The ID of the pending safety check.')]

The ID of the pending safety check.

ComputerToolCall

Bases: BaseAPIType

A tool call to a computer use tool.

See the computer use guide for more information.

Attributes:

Name Type Description
type Annotated[Literal['computer_call'], Field(description='The type of the computer call. Always `computer_call`.')]

The type of the computer call. Always computer_call.

id Annotated[str, Field(description='The unique ID of the computer call.')]

The unique ID of the computer call.

call_id Annotated[str, Field(description='An identifier used when responding to the tool call with output.')]

An identifier used when responding to the tool call with output.

actions ComputerActionList | MISSING

Flattened batched actions for computer_use. Each action includes an type discriminator and action-specific fields.

pending_safety_checks Annotated[list[ComputerCallSafetyCheckParam], Field(description='The pending safety checks for the computer call.')]

The pending safety checks for the computer call.

status Annotated[Literal['in_progress', 'completed', 'incomplete'], Field(description='The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.')]

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

ContainerReferenceParam

Bases: BaseAPIType

ContainerReferenceParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['container_reference'], Field(description='References a container created with the /v1/containers endpoint')]

References a container created with the /v1/containers endpoint

container_id Annotated[str, Field(description='The ID of the referenced container.', examples=['cntr_123'])]

The ID of the referenced container.

FunctionCallOutputItemParam

Bases: BaseAPIType

The output of a function tool call.

Attributes:

Name Type Description
call_id FunctionCallOutputItemParamCallId | None | MISSING

The unique ID of the function tool call generated by the model.

type Annotated[Literal['function_call_output'], Field(description='The type of the function tool call output. Always `function_call_output`.')]

The type of the function tool call output. Always function_call_output.

output Annotated[FunctionCallOutputItemParamOutput | list[FunctionCallOutputItemParamOutput1], Field(description='Text, image, or file output of the function tool call.')]

Text, image, or file output of the function tool call.

name FunctionCallOutputItemParamName | None | MISSING

The name of the tool that produced the output.

namespace FunctionCallOutputItemParamNamespace | None | MISSING

The namespace of the tool that produced the output.

caller ToolCallCallerParam | None | MISSING

The execution context that produced this tool call.

FunctionShellCallItemParam

Bases: BaseAPIType

FunctionShellCallItemParam from the OpenAI API.

A tool representing a request to execute one or more shell commands.

Attributes:

Name Type Description
call_id Annotated[str, Field(description='The unique ID of the shell tool call generated by the model.', max_length=64, min_length=1)]

The unique ID of the shell tool call generated by the model.

caller ToolCallCallerParam | None | MISSING

The execution context that produced this tool call.

type Annotated[Literal['shell_call'], Field(description='The type of the item. Always `shell_call`.')]

The type of the item. Always shell_call.

action Annotated[FunctionShellActionParam, Field(description='The shell commands and limits that describe how to run the tool call.')]

The shell commands and limits that describe how to run the tool call.

status FunctionShellCallItemStatus | None | MISSING

Status values reported for shell tool calls.

FunctionShellCallOutputItemParam

Bases: BaseAPIType

The streamed output items emitted by a shell tool call.

Attributes:

Name Type Description
call_id Annotated[str, Field(description='The unique ID of the shell tool call generated by the model.', max_length=64, min_length=1)]

The unique ID of the shell tool call generated by the model.

caller ToolCallCallerParam | None | MISSING

The execution context that produced this tool call.

type Annotated[Literal['shell_call_output'], Field(description='The type of the item. Always `shell_call_output`.')]

The type of the item. Always shell_call_output.

output Annotated[list[FunctionShellCallOutputContentParam], Field(description='Captured chunks of stdout and stderr output, along with their associated outcomes.')]

Captured chunks of stdout and stderr output, along with their associated outcomes.

status FunctionShellCallItemStatus | None | MISSING

Status values reported for shell tool calls.

FunctionShellToolParam

Bases: BaseAPIType

A tool that allows the model to execute shell commands.

Attributes:

Name Type Description
type Annotated[Literal['shell'], Field(description='The type of the shell tool. Always `shell`.')]

The type of the shell tool. Always shell.

allowed_callers FunctionShellToolParamAllowedCallers | None | MISSING

The tool invocation context(s).

LocalEnvironmentParam

Bases: BaseAPIType

LocalEnvironmentParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['local'], Field(description='Use a local computer environment.')]

Use a local computer environment.

skills Annotated[list[LocalSkillParam] | MISSING, Field(description='An optional list of skills.', max_length=200)]

An optional list of skills.

LocalSkillParam

Bases: BaseAPIType

LocalSkillParam from the OpenAI API.

Attributes:

Name Type Description
name Annotated[str, Field(description='The name of the skill.')]

The name of the skill.

description Annotated[str, Field(description='The description of the skill.')]

The description of the skill.

path Annotated[str, Field(description='The path to the directory containing the skill.')]

The path to the directory containing the skill.

ReasoningItem

Bases: BaseAPIType

ReasoningItem from the OpenAI API (upstream: ReasoningItem).

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

Attributes:

Name Type Description
type Annotated[Literal['reasoning'], Field(description='The type of the object. Always `reasoning`.')]

The type of the object. Always reasoning.

id Annotated[str, Field(description='The unique identifier of the reasoning content.')]

The unique identifier of the reasoning content.

summary Annotated[list[SummaryTextContent], Field(description='Reasoning summary content.')]

Reasoning summary content.

content Annotated[list[ReasoningTextContent] | MISSING, Field(description='Reasoning text content.')]

Reasoning text content.

status Annotated[Literal['in_progress', 'completed', 'incomplete'] | MISSING, Field(description='The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.')]

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

ToolSearchCallItemParam

Bases: BaseAPIType

ToolSearchCallItemParam from the OpenAI API.

Attributes:

Name Type Description
call_id ToolSearchCallItemParamCallId | None | MISSING

The unique ID of the tool search call generated by the model.

type Annotated[Literal['tool_search_call'], Field(description='The item type. Always `tool_search_call`.')]

The item type. Always tool_search_call.

execution Annotated[ToolSearchExecutionType | MISSING, Field(description='Whether tool search was executed by the server or by the client.')]

Whether tool search was executed by the server or by the client.

arguments Annotated[EmptyModelParam, Field(description='The arguments supplied to the tool search call.')]

The arguments supplied to the tool search call.

ToolSearchOutputItemParam

Bases: BaseAPIType

ToolSearchOutputItemParam from the OpenAI API.

Attributes:

Name Type Description
call_id ToolSearchOutputItemParamCallId | None | MISSING

The unique ID of the tool search call generated by the model.

type Annotated[Literal['tool_search_output'], Field(description='The item type. Always `tool_search_output`.')]

The item type. Always tool_search_output.

execution Annotated[ToolSearchExecutionType | MISSING, Field(description='Whether tool search was executed by the server or by the client.')]

Whether tool search was executed by the server or by the client.

tools Annotated[list[ToolSearchOutputTool], Field(description='The loaded tool definitions returned by the tool search output.')]

The loaded tool definitions returned by the tool search output.

ApplyPatchToolCallItemParam

Bases: BaseAPIType

ApplyPatchToolCallItemParam from the OpenAI API.

A tool call representing a request to create, delete, or update files using diff patches.

Attributes:

Name Type Description
type Annotated[Literal['apply_patch_call'], Field(description='The type of the item. Always `apply_patch_call`.')]

The type of the item. Always apply_patch_call.

call_id Annotated[str, Field(description='The unique ID of the apply patch tool call generated by the model.', max_length=64, min_length=1)]

The unique ID of the apply patch tool call generated by the model.

caller ToolCallCallerParam | None | MISSING

The execution context that produced this tool call.

status Annotated[ApplyPatchCallStatusParam, Field(description='The status of the apply patch tool call. One of `in_progress` or `completed`.')]

The status of the apply patch tool call. One of in_progress or completed.

operation Annotated[ApplyPatchOperationParam, Field(description='The specific create, delete, or update instruction for the apply_patch tool call.')]

The specific create, delete, or update instruction for the apply_patch tool call.

ApplyPatchToolCallOutputItemParam

Bases: BaseAPIType

The streamed output emitted by an apply patch tool call.

Attributes:

Name Type Description
type Annotated[Literal['apply_patch_call_output'], Field(description='The type of the item. Always `apply_patch_call_output`.')]

The type of the item. Always apply_patch_call_output.

call_id Annotated[str, Field(description='The unique ID of the apply patch tool call generated by the model.', max_length=64, min_length=1)]

The unique ID of the apply patch tool call generated by the model.

caller ToolCallCallerParam | None | MISSING

The execution context that produced this tool call.

status Annotated[ApplyPatchCallOutputStatusParam, Field(description='The status of the apply patch tool call output. One of `completed` or `failed`.')]

The status of the apply patch tool call output. One of completed or failed.

output ApplyPatchToolCallOutputItemParamOutput | None | MISSING

Optional human-readable log text from the apply patch tool (e.g., patch results or errors).

ApplyPatchToolParam

Bases: BaseAPIType

ApplyPatchToolParam from the OpenAI API.

Allows the assistant to create, delete, or update files using unified diffs.

Attributes:

Name Type Description
type Annotated[Literal['apply_patch'], Field(description='The type of the tool. Always `apply_patch`.')]

The type of the tool. Always apply_patch.

allowed_callers ApplyPatchToolParamAllowedCallers | None | MISSING

The tool invocation context(s).

ApproximateLocation

Bases: BaseAPIType

ApproximateLocation from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['approximate'], Field(description='The type of location approximation. Always `approximate`.')]

The type of location approximation. Always approximate.

AutoCodeInterpreterToolParam

Bases: BaseAPIType

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

Attributes:

Name Type Description
type Annotated[Literal['auto'], Field(description='Always `auto`.')]

Always auto.

file_ids Annotated[list[str] | MISSING, Field(description='An optional list of uploaded files to make available to your code.', max_length=50)]

An optional list of uploaded files to make available to your code.

network_policy Annotated[ContainerNetworkPolicyDisabledParam | ContainerNetworkPolicyAllowlistParam | MISSING, Field(description='Network access policy for the container.', discriminator='type')]

Network access policy for the container.

ClickParam

Bases: BaseAPIType

A click action.

Attributes:

Name Type Description
type Annotated[Literal['click'], Field(description='Specifies the event type. For a click action, this property is always `click`.')]

Specifies the event type. For a click action, this property is always click.

button Annotated[ClickButtonType, Field(description='Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.')]

Indicates which mouse button was pressed during the click. One of left, right, wheel, back, or forward.

x Annotated[int, Field(description='The x-coordinate where the click occurred.')]

The x-coordinate where the click occurred.

y Annotated[int, Field(description='The y-coordinate where the click occurred.')]

The y-coordinate where the click occurred.

CodeInterpreterOutputLogs

Bases: BaseAPIType

The logs output from the code interpreter.

Attributes:

Name Type Description
type Annotated[Literal['logs'], Field(description='The type of the output. Always `logs`.')]

The type of the output. Always logs.

logs Annotated[str, Field(description='The logs output from the code interpreter.')]

The logs output from the code interpreter.

CodeInterpreterTool

Bases: BaseAPIType

CodeInterpreterTool from the OpenAI API.

A tool that runs Python code to help generate a response to a prompt.

Attributes:

Name Type Description
type Annotated[Literal['code_interpreter'], Field(description='The type of the code interpreter tool. Always `code_interpreter`.')]

The type of the code interpreter tool. Always code_interpreter.

container Annotated[str | AutoCodeInterpreterToolParam, Field(description='The code interpreter container. Can be a container ID or an object that\nspecifies uploaded file IDs to make available to your code, along with an\noptional `memory_limit` setting.')]

The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code, along with an optional memory_limit setting.

allowed_callers CodeInterpreterToolAllowedCallers | None | MISSING

The tool invocation context(s).

CodeInterpreterToolCall

Bases: BaseAPIType

A tool call to run code.

Attributes:

Name Type Description
type Annotated[Literal['code_interpreter_call'], Field(description='The type of the code interpreter tool call. Always `code_interpreter_call`.')]

The type of the code interpreter tool call. Always code_interpreter_call.

id Annotated[str, Field(description='The unique ID of the code interpreter tool call.')]

The unique ID of the code interpreter tool call.

status Annotated[Literal['in_progress', 'completed', 'incomplete', 'interpreting', 'failed'], Field(description='The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`.')]

The status of the code interpreter tool call. Valid values are in_progress, completed, incomplete, interpreting, and failed.

container_id Annotated[str, Field(description='The ID of the container used to run the code.')]

The ID of the container used to run the code.

ComparisonFilter

Bases: BaseAPIType

ComparisonFilter from the OpenAI API.

A filter used to compare a specified attribute key to a given value using a defined comparison operation.

Attributes:

Name Type Description
type Annotated[Literal['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin'], Field(description='Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`.\n- `eq`: equals\n- `ne`: not equal\n- `gt`: greater than\n- `gte`: greater than or equal\n- `lt`: less than\n- `lte`: less than or equal\n- `in`: in\n- `nin`: not in')]

Specifies the comparison operator: eq, ne, gt, gte, lt, lte, in, nin. - eq: equals - ne: not equal - gt: greater than - gte: greater than or equal - lt: less than - lte: less than or equal - in: in - nin: not in

key Annotated[str, Field(description='The key to compare against the value.')]

The key to compare against the value.

value Annotated[str | float | bool | list[str | float], Field(description='The value to compare against the attribute key; supports string, number, or boolean types.')]

The value to compare against the attribute key; supports string, number, or boolean types.

CompoundFilter

Bases: BaseAPIType

Combine multiple filters using and or or.

Attributes:

Name Type Description
type Annotated[Literal['and', 'or'], Field(description='Type of operation: `and` or `or`.')]

Type of operation: and or or.

filters Annotated[list[ComparisonFilter | CompoundFilter], Field(description='Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.')]

Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.

ComputerTool

Bases: BaseAPIType

A tool that controls a virtual computer.

Learn more about the computer tool.

Attributes:

Name Type Description
type Annotated[Literal['computer'], Field(description='The type of the computer tool. Always `computer`.')]

The type of the computer tool. Always computer.

ComputerUsePreviewTool

Bases: BaseAPIType

A tool that controls a virtual computer.

Learn more about the computer tool.

Attributes:

Name Type Description
type Annotated[Literal['computer_use_preview'], Field(description='The type of the computer use tool. Always `computer_use_preview`.')]

The type of the computer use tool. Always computer_use_preview.

environment Annotated[ComputerEnvironment, Field(description='The type of computer environment to control.')]

The type of computer environment to control.

display_width Annotated[int, Field(description='The width of the computer display.')]

The width of the computer display.

display_height Annotated[int, Field(description='The height of the computer display.')]

The height of the computer display.

ContainerAutoParam

Bases: BaseAPIType

ContainerAutoParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['container_auto'], Field(description='Automatically creates a container for this request')]

Automatically creates a container for this request

file_ids Annotated[list[str] | MISSING, Field(description='An optional list of uploaded files to make available to your code.', max_length=50)]

An optional list of uploaded files to make available to your code.

network_policy Annotated[ContainerNetworkPolicyDisabledParam | ContainerNetworkPolicyAllowlistParam | MISSING, Field(description='Network access policy for the container.', discriminator='type')]

Network access policy for the container.

skills Annotated[list[ContainerAutoParamSkills] | MISSING, Field(description='An optional list of skills referenced by id or inline data. Across all inline skills in this list, decoded ZIP data must total at most 50 MiB and Base64 text must total at most 70,254,592 characters, including line breaks. Skill references do not count toward these limits.', max_length=200)]

An optional list of skills referenced by id or inline data. Across all inline skills in this list, decoded ZIP data must total at most 50 MiB and Base64 text must total at most 70,254,592 characters, including line breaks. Skill references do not count toward these limits.

ContainerNetworkPolicyAllowlistParam

Bases: BaseAPIType

ContainerNetworkPolicyAllowlistParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['allowlist'], Field(description='Allow outbound network access only to specified domains. Always `allowlist`.')]

Allow outbound network access only to specified domains. Always allowlist.

allowed_domains Annotated[list[str], Field(description='A list of allowed domains when type is `allowlist`.', min_length=1)]

A list of allowed domains when type is allowlist.

domain_secrets Annotated[list[ContainerNetworkPolicyDomainSecretParam] | MISSING, Field(description='Optional domain-scoped secrets for allowlisted domains.', min_length=1)]

Optional domain-scoped secrets for allowlisted domains.

ContainerNetworkPolicyDisabledParam

Bases: BaseAPIType

ContainerNetworkPolicyDisabledParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['disabled'], Field(description='Disable outbound network access. Always `disabled`.')]

Disable outbound network access. Always disabled.

ContainerNetworkPolicyDomainSecretParam

Bases: BaseAPIType

ContainerNetworkPolicyDomainSecretParam from the OpenAI API.

Attributes:

Name Type Description
domain Annotated[str, Field(description='The domain associated with the secret.', min_length=1)]

The domain associated with the secret.

name Annotated[str, Field(description='The name of the secret to inject for the domain.', min_length=1)]

The name of the secret to inject for the domain.

value Annotated[str, Field(description='The secret value to inject for the domain.', max_length=10485760, min_length=1)]

The secret value to inject for the domain.

CoordParam

Bases: BaseAPIType

An x/y coordinate pair, e.g.

{ x: 100, y: 200 }.

Attributes:

Name Type Description
x Annotated[int, Field(description='The x-coordinate.')]

The x-coordinate.

y Annotated[int, Field(description='The y-coordinate.')]

The y-coordinate.

CustomGrammarFormatParam

Bases: BaseAPIType

A grammar defined by the user.

Attributes:

Name Type Description
type Annotated[Literal['grammar'], Field(description='Grammar format. Always `grammar`.')]

Grammar format. Always grammar.

syntax Annotated[GrammarSyntax1, Field(description='The syntax of the grammar definition. One of `lark` or `regex`.')]

The syntax of the grammar definition. One of lark or regex.

definition Annotated[str, Field(description='The grammar definition.')]

The grammar definition.

CustomTextFormatParam

Bases: BaseAPIType

Unconstrained free-form text.

Attributes:

Name Type Description
type Annotated[Literal['text'], Field(description='Unconstrained text format. Always `text`.')]

Unconstrained text format. Always text.

CustomToolCall

Bases: BaseAPIType

A call to a custom tool created by the model.

Attributes:

Name Type Description
type Annotated[Literal['custom_tool_call'], Field(description='The type of the custom tool call. Always `custom_tool_call`.')]

The type of the custom tool call. Always custom_tool_call.

id Annotated[str | MISSING, Field(description='The unique ID of the custom tool call in the OpenAI platform.')]

The unique ID of the custom tool call in the OpenAI platform.

call_id Annotated[str, Field(description='An identifier used to map this custom tool call to a tool call output.')]

An identifier used to map this custom tool call to a tool call output.

caller ToolCallCaller | None | MISSING

The execution context that produced this tool call.

namespace Annotated[str | MISSING, Field(description='The namespace of the custom tool being called.')]

The namespace of the custom tool being called.

name Annotated[str, Field(description='The name of the custom tool being called.')]

The name of the custom tool being called.

input Annotated[str, Field(description='The input for the custom tool call generated by the model.')]

The input for the custom tool call generated by the model.

async_ Annotated[bool | MISSING, Field(validation_alias='async', description='Whether the custom tool call runs asynchronously.', serialization_alias='async')]

Whether the custom tool call runs asynchronously.

CustomToolCallOutput

Bases: BaseAPIType

CustomToolCallOutput from the OpenAI API.

The output of a custom tool call from your code, being sent back to the model.

Attributes:

Name Type Description
type Annotated[Literal['custom_tool_call_output'], Field(description='The type of the custom tool call output. Always `custom_tool_call_output`.')]

The type of the custom tool call output. Always custom_tool_call_output.

id Annotated[str | MISSING, Field(description='The unique ID of the custom tool call output in the OpenAI platform.')]

The unique ID of the custom tool call output in the OpenAI platform.

call_id Annotated[str, Field(description='The call ID, used to map this custom tool call output to a custom tool call.')]

The call ID, used to map this custom tool call output to a custom tool call.

caller ToolCallCallerParam | None | MISSING

The execution context that produced this tool call.

output Annotated[str | list[FunctionAndCustomToolCallOutput], Field(description='The output from the custom tool call generated by your code.\nCan be a string or an list of output content.')]

The output from the custom tool call generated by your code. Can be a string or an list of output content.

CustomToolParam

Bases: BaseAPIType

A custom tool that processes input using a specified format.

Learn more about custom tools

Attributes:

Name Type Description
type Annotated[Literal['custom'], Field(description='The type of the custom tool. Always `custom`.')]

The type of the custom tool. Always custom.

name Annotated[str, Field(description='The name of the custom tool, used to identify it in tool calls.')]

The name of the custom tool, used to identify it in tool calls.

async_ Annotated[bool | MISSING, Field(validation_alias='async', description='Whether the tool response can be returned asynchronously versus immediately returned on next response creation.', serialization_alias='async')]

Whether the tool response can be returned asynchronously versus immediately returned on next response creation.

description Annotated[str | MISSING, Field(description='Optional description of the custom tool, used to provide more context.')]

Optional description of the custom tool, used to provide more context.

format Annotated[CustomTextFormatParam | CustomGrammarFormatParam | MISSING, Field(description='The input format for the custom tool. Default is unconstrained text.', discriminator='type')]

The input format for the custom tool. Default is unconstrained text.

defer_loading Annotated[bool | MISSING, Field(description='Whether this tool should be deferred and discovered via tool search.')]

Whether this tool should be deferred and discovered via tool search.

allowed_callers CustomToolParamAllowedCallers | None | MISSING

The tool invocation context(s).

DirectToolCallCaller

Bases: BaseAPIType

DirectToolCallCaller from the OpenAI API.

DirectToolCallCallerParam

Bases: BaseAPIType

DirectToolCallCallerParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['direct'], Field(description='The caller type. Always `direct`.')]

The caller type. Always direct.

DoubleClickAction

Bases: BaseAPIType

A double click action.

Attributes:

Name Type Description
type Annotated[Literal['double_click'], Field(description='Specifies the event type. For a double click action, this property is always set to `double_click`.')]

Specifies the event type. For a double click action, this property is always set to double_click.

x Annotated[int, Field(description='The x-coordinate where the double click occurred.')]

The x-coordinate where the double click occurred.

y Annotated[int, Field(description='The y-coordinate where the double click occurred.')]

The y-coordinate where the double click occurred.

DragParam

Bases: BaseAPIType

A drag action.

Attributes:

Name Type Description
type Annotated[Literal['drag'], Field(description='Specifies the event type. For a drag action, this property is always set to `drag`.')]

Specifies the event type. For a drag action, this property is always set to drag.

path Annotated[list[CoordParam], Field(description='An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg\n```\n[\n { x: 100, y: 200 },\n { x: 200, y: 300 }\n]\n```')]

An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg [ { x: 100, y: 200 }, { x: 200, y: 300 } ]

EmptyModelParam

Bases: BaseAPIType

EmptyModelParam from the OpenAI API.

FileSearchTool

Bases: BaseAPIType

A tool that searches for relevant content from uploaded files.

Learn more about the file search tool.

Attributes:

Name Type Description
type Annotated[Literal['file_search'], Field(description='The type of the file search tool. Always `file_search`.')]

The type of the file search tool. Always file_search.

vector_store_ids Annotated[list[str], Field(description='The IDs of the vector stores to search.')]

The IDs of the vector stores to search.

max_num_results Annotated[int | MISSING, Field(description='The maximum number of results to return. This number should be between 1 and 50 inclusive.')]

The maximum number of results to return. This number should be between 1 and 50 inclusive.

ranking_options Annotated[RankingOptions | MISSING, Field(description='Ranking options for search.')]

Ranking options for search.

FileSearchToolCall

Bases: BaseAPIType

The results of a file search tool call.

See the file search guide for more information.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of the file search tool call.')]

The unique ID of the file search tool call.

type Annotated[Literal['file_search_call'], Field(description='The type of the file search tool call. Always `file_search_call`.')]

The type of the file search tool call. Always file_search_call.

status Annotated[Literal['in_progress', 'searching', 'completed', 'incomplete', 'failed'], Field(description='The status of the file search tool call. One of `in_progress`,\n`searching`, `incomplete` or `failed`,')]

The status of the file search tool call. One of in_progress, searching, incomplete or failed,

queries Annotated[list[str], Field(description='The queries used to search for files.')]

The queries used to search for files.

FunctionShellActionParam

Bases: BaseAPIType

Commands and limits describing how to run the shell tool call.

Attributes:

Name Type Description
commands Annotated[list[str], Field(description='Ordered shell commands for the execution environment to run.')]

Ordered shell commands for the execution environment to run.

FunctionTool

Bases: BaseAPIType

Defines a function in your own code the model can choose to call.

Learn more about function calling.

Attributes:

Name Type Description
type Annotated[Literal['function'], Field(description='The type of the function tool. Always `function`.')]

The type of the function tool. Always function.

name Annotated[str, Field(description='The name of the function to call.')]

The name of the function to call.

defer_loading Annotated[bool | MISSING, Field(description='Whether this function is deferred and loaded via tool search.')]

Whether this function is deferred and loaded via tool search.

FunctionToolCall

Bases: BaseAPIType

A tool call to run a function.

See the function calling guide for more information.

Attributes:

Name Type Description
id Annotated[str | MISSING, Field(description='The unique ID of the function tool call.')]

The unique ID of the function tool call.

type Annotated[Literal['function_call'], Field(description='The type of the function tool call. Always `function_call`.')]

The type of the function tool call. Always function_call.

call_id Annotated[str, Field(description='The unique ID of the function tool call generated by the model.')]

The unique ID of the function tool call generated by the model.

caller ToolCallCaller | None | MISSING

The execution context that produced this tool call.

namespace Annotated[str | MISSING, Field(description='The namespace of the function to run.')]

The namespace of the function to run.

name Annotated[str, Field(description='The name of the function to run.')]

The name of the function to run.

arguments Annotated[str, Field(description='A JSON string of the arguments to pass to the function.')]

A JSON string of the arguments to pass to the function.

status Annotated[Literal['in_progress', 'completed', 'incomplete'] | MISSING, Field(description='The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.')]

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

async_ Annotated[bool | MISSING, Field(validation_alias='async', description='Whether the function tool call runs asynchronously.', serialization_alias='async')]

Whether the function tool call runs asynchronously.

FunctionToolParam

Bases: BaseAPIType

FunctionToolParam from the OpenAI API.

Attributes:

Name Type Description
async_ Annotated[bool | MISSING, Field(validation_alias='async', description='Whether the tool response can be returned asynchronously versus immediately returned on next response creation.', serialization_alias='async')]

Whether the tool response can be returned asynchronously versus immediately returned on next response creation.

defer_loading Annotated[bool | MISSING, Field(description='Whether this function should be deferred and discovered via tool search.')]

Whether this function should be deferred and discovered via tool search.

allowed_callers FunctionToolParamAllowedCallers | None | MISSING

The tool invocation context(s).

HTTPError

Bases: BaseAPIType

HTTPError from the OpenAI API (upstream: HTTPError).

HybridSearchOptions

Bases: BaseAPIType

HybridSearchOptions from the OpenAI API.

Attributes:

Name Type Description
embedding_weight Annotated[float, Field(description='The weight of the embedding in the reciprocal ranking fusion.')]

The weight of the embedding in the reciprocal ranking fusion.

text_weight Annotated[float, Field(description='The weight of the text in the reciprocal ranking fusion.')]

The weight of the text in the reciprocal ranking fusion.

ImageGenTool

Bases: BaseAPIType

A tool that generates images using the GPT image models.

Attributes:

Name Type Description
type Annotated[Literal['image_generation'], Field(description='The type of the image generation tool. Always `image_generation`.')]

The type of the image generation tool. Always image_generation.

complexity Annotated[Literal['low', 'medium', 'high'] | MISSING, Field(description="Computation spent planning the image, independently of rendering quality.\nOverrides the outer response's `reasoning.effort` for image generation.\nWhen omitted, inherits a supported outer reasoning effort or uses the\nimage model's configured default.\nFor SVG output, controls the reference image, not the SVG author's\nreasoning.")]

Computation spent planning the image, independently of rendering quality. Overrides the outer response's reasoning.effort for image generation. When omitted, inherits a supported outer reasoning effort or uses the image model's configured default. For SVG output, controls the reference image, not the SVG author's reasoning.

quality Annotated[Literal['low', 'medium', 'high', 'xhigh', 'max', 'auto'] | MISSING, Field(description='The quality of the generated image. The GPT image models support `low`,\n`medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`,\nincluding their `2026-09-08` snapshots, also support `xhigh` and `max`.\nDefault: `auto`.')]

The quality of the generated image. The GPT image models support low, medium, and high. gpt-image-2.5-sunburst and gpt-image-2.5-flare, including their 2026-09-08 snapshots, also support xhigh and max. Default: auto.

size Annotated[str | Literal['1024x1024', '1024x1536', '1536x1024', 'auto'] | MISSING, Field(description="The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing.")]

The size of the generated images. For gpt-image-2, gpt-image-2-2026-04-21, gpt-image-2.5-sunburst, gpt-image-2.5-sunburst-2026-09-08, gpt-image-2.5-flare, and gpt-image-2.5-flare-2026-09-08, arbitrary resolutions are supported as WIDTHxHEIGHT strings, for example 1536x864. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above 2560x1440 are experimental, and the maximum supported resolution is 3840x2160. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes 1024x1024, 1536x1024, and 1024x1536 are supported by the GPT image models; auto is supported for models that allow automatic sizing.

output_format Annotated[Literal['png', 'webp', 'jpeg', 'gif', 'svg'] | MISSING, Field(description='The output format of the generated image. One of `png`, `webp`, `jpeg`,\n`gif`, or `svg`. Default: `png`. GIF and SVG output require a model\nthat supports the selected format. GIF output does not support\npartial image streaming (`partial_images` greater than `0`),\n`input_image_mask`, or custom `output_compression`.\nResponses lifecycle events can still be streamed for GIF output.')]

The output format of the generated image. One of png, webp, jpeg, gif, or svg. Default: png. GIF and SVG output require a model that supports the selected format. GIF output does not support partial image streaming (partial_images greater than 0), input_image_mask, or custom output_compression. Responses lifecycle events can still be streamed for GIF output.

frame_count Annotated[int | MISSING, Field(description='Number of GIF frames. Requires `output_format` to be `gif`. Default: 9.', ge=2, le=16)]

Number of GIF frames. Requires output_format to be gif. Default: 9.

frame_duration_ms Annotated[int | MISSING, Field(description='Duration of each GIF frame in milliseconds, rounded to 10 ms.\nRequires `output_format` to be `gif`. Default: 200.', ge=20, le=2000)]

Duration of each GIF frame in milliseconds, rounded to 10 ms. Requires output_format to be gif. Default: 200.

svg Annotated[SvgParam | MISSING, Field(description='SVG author model settings. Requires `output_format` to be `svg`.\nWhen SVG model selection is enabled, omitting this object uses the\nouter response model. Otherwise, the default SVG author is used and\nexplicit model overrides are unavailable.')]

SVG author model settings. Requires output_format to be svg. When SVG model selection is enabled, omitting this object uses the outer response model. Otherwise, the default SVG author is used and explicit model overrides are unavailable.

output_compression Annotated[int | MISSING, Field(description='Compression level for the output image. Default: 100.', ge=0, le=100)]

Compression level for the output image. Default: 100.

moderation Annotated[Literal['auto', 'low'] | MISSING, Field(description='Moderation level for the generated image. Default: `auto`.')]

Moderation level for the generated image. Default: auto.

background Annotated[Literal['transparent', 'opaque', 'auto'] | MISSING, Field(description='Set the background of the generated image. One of `transparent`, `opaque`,\nor `auto`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including\ntheir `2026-09-08` snapshots, support `opaque` and `transparent`\nbackgrounds. Transparent backgrounds are available for supported GPT Image\nmodels. For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in\npreview. When using `transparent`, set the output format to `png` or `webp`.\nDefault: `auto`.')]

Set the background of the generated image. One of transparent, opaque, or auto. gpt-image-2.5-sunburst and gpt-image-2.5-flare, including their 2026-09-08 snapshots, support opaque and transparent backgrounds. Transparent backgrounds are available for supported GPT Image models. For gpt-image-2 and gpt-image-2-2026-04-21, this support is in preview. When using transparent, set the output format to png or webp. Default: auto.

input_fidelity InputFidelity | None | MISSING

Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports high and low on gpt-image-1.5; gpt-image-1-mini supports only low. For gpt-image-2, omit this parameter. Defaults to low on supported models.

input_image_mask Annotated[ImageGenToolInputImageMask | MISSING, Field(description='Optional mask for inpainting. Contains `image_url`\n(string, optional) and `file_id` (string, optional).')]

Optional mask for inpainting. Contains image_url (string, optional) and file_id (string, optional).

partial_images Annotated[int | MISSING, Field(description='Number of partial images to generate in streaming mode, from 0 (default value) to 3.', ge=0, le=3)]

Number of partial images to generate in streaming mode, from 0 (default value) to 3.

action Annotated[ImageGenActionEnum | MISSING, Field(description='Whether to generate a new image or edit an existing image. Default: `auto`.')]

Whether to generate a new image or edit an existing image. Default: auto.

ImageGenToolCall

Bases: BaseAPIType

An image generation request made by the model.

Attributes:

Name Type Description
type Annotated[Literal['image_generation_call'], Field(description='The type of the image generation call. Always `image_generation_call`.')]

The type of the image generation call. Always image_generation_call.

id Annotated[str, Field(description='The unique ID of the image generation call.')]

The unique ID of the image generation call.

status Annotated[Literal['in_progress', 'completed', 'generating', 'failed'], Field(description='The status of the image generation call.')]

The status of the image generation call.

error Annotated[ImageGenToolCallError | MISSING, Field(description='Details of a moderation failure, when available.')]

Details of a moderation failure, when available.

ImageGenToolCallError

Bases: BaseAPIType

ImageGenToolCallError from the OpenAI API.

Attributes:

Name Type Description
type Annotated[str, Field(description='The error type.')]

The error type.

message Annotated[str, Field(description='A description of the error.')]

A description of the error.

moderation_details Annotated[ImageGenToolCallModerationDetails | MISSING, Field(description='Public details for a `moderation_blocked` error, when available.')]

Public details for a moderation_blocked error, when available.

ImageGenToolCallModerationDetails

Bases: BaseAPIType

ImageGenToolCallModerationDetails from the OpenAI API.

Attributes:

Name Type Description
moderation_stage Annotated[Literal['input', 'output', 'unknown'], Field(description='The stage where moderation blocked the image generation call.')]

The stage where moderation blocked the image generation call.

categories Annotated[list[str], Field(description='Public moderation categories. New category values may be added over time.')]

Public moderation categories. New category values may be added over time.

InlineSkillParam

Bases: BaseAPIType

InlineSkillParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['inline'], Field(description='Defines an inline skill for this request.')]

Defines an inline skill for this request.

name Annotated[str, Field(description='The name of the skill.')]

The name of the skill.

description Annotated[str, Field(description='The description of the skill.')]

The description of the skill.

source Annotated[InlineSkillSourceParam, Field(description='Inline skill payload')]

Inline skill payload

InlineSkillSourceParam

Bases: BaseAPIType

Inline skill payload.

Attributes:

Name Type Description
type Annotated[Literal['base64'], Field(description='The type of the inline skill source. Must be `base64`.')]

The type of the inline skill source. Must be base64.

media_type Annotated[Literal['application/zip'], Field(description='The media type of the inline skill payload. Must be `application/zip`.')]

The media type of the inline skill payload. Must be application/zip.

data Annotated[str, Field(description='Base64-encoded skill zip bundle.', max_length=70254592, min_length=1)]

Base64-encoded skill zip bundle.

KeyPressAction

Bases: BaseAPIType

A collection of keypresses the model would like to perform.

Attributes:

Name Type Description
type Annotated[Literal['keypress'], Field(description='Specifies the event type. For a keypress action, this property is always set to `keypress`.')]

Specifies the event type. For a keypress action, this property is always set to keypress.

keys Annotated[list[str], Field(description='The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.')]

The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

LocalShellExecAction

Bases: BaseAPIType

Execute a shell command on the server.

Attributes:

Name Type Description
type Annotated[Literal['exec'], Field(description='The type of the local shell action. Always `exec`.')]

The type of the local shell action. Always exec.

command Annotated[list[str], Field(description='The command to run.')]

The command to run.

env Annotated[dict[str, str], Field(description='Environment variables to set for the command.')]

Environment variables to set for the command.

LocalShellToolCall

Bases: BaseAPIType

A tool call to run a command on the local shell.

Attributes:

Name Type Description
type Annotated[Literal['local_shell_call'], Field(description='The type of the local shell call. Always `local_shell_call`.')]

The type of the local shell call. Always local_shell_call.

id Annotated[str, Field(description='The unique ID of the local shell call.')]

The unique ID of the local shell call.

call_id Annotated[str, Field(description='The unique ID of the local shell tool call generated by the model.')]

The unique ID of the local shell tool call generated by the model.

action LocalShellExecAction

Execute a shell command on the server.

status Annotated[Literal['in_progress', 'completed', 'incomplete'], Field(description='The status of the local shell call.')]

The status of the local shell call.

LocalShellToolCallOutput

Bases: BaseAPIType

The output of a local shell tool call.

Attributes:

Name Type Description
type Annotated[Literal['local_shell_call_output'], Field(description='The type of the local shell tool call output. Always `local_shell_call_output`.')]

The type of the local shell tool call output. Always local_shell_call_output.

id Annotated[str, Field(description='The unique ID of the local shell tool call generated by the model.')]

The unique ID of the local shell tool call generated by the model.

output Annotated[str, Field(description='A JSON string of the output of the local shell tool call.')]

A JSON string of the output of the local shell tool call.

LocalShellToolParam

Bases: BaseAPIType

LocalShellToolParam from the OpenAI API.

A tool that allows the model to execute shell commands in a local environment.

Attributes:

Name Type Description
type Annotated[Literal['local_shell'], Field(description='The type of the local shell tool. Always `local_shell`.')]

The type of the local shell tool. Always local_shell.

MCPApprovalRequest

Bases: BaseAPIType

A request for human approval of a tool invocation.

Attributes:

Name Type Description
type Annotated[Literal['mcp_approval_request'], Field(description='The type of the item. Always `mcp_approval_request`.')]

The type of the item. Always mcp_approval_request.

id Annotated[str, Field(description='The unique ID of the approval request.')]

The unique ID of the approval request.

server_label Annotated[str, Field(description='The label of the MCP server making the request.')]

The label of the MCP server making the request.

name Annotated[str, Field(description='The name of the tool to run.')]

The name of the tool to run.

arguments Annotated[str, Field(description='A JSON string of arguments for the tool.')]

A JSON string of arguments for the tool.

MCPApprovalResponse

Bases: BaseAPIType

A response to an MCP approval request.

Attributes:

Name Type Description
type Annotated[Literal['mcp_approval_response'], Field(description='The type of the item. Always `mcp_approval_response`.')]

The type of the item. Always mcp_approval_response.

approval_request_id Annotated[str, Field(description='The ID of the approval request being answered.')]

The ID of the approval request being answered.

approve Annotated[bool, Field(description='Whether the request was approved.')]

Whether the request was approved.

MCPListTools

Bases: BaseAPIType

A list of tools available on an MCP server.

Attributes:

Name Type Description
type Annotated[Literal['mcp_list_tools'], Field(description='The type of the item. Always `mcp_list_tools`.')]

The type of the item. Always mcp_list_tools.

id Annotated[str, Field(description='The unique ID of the list.')]

The unique ID of the list.

server_label Annotated[str, Field(description='The label of the MCP server.')]

The label of the MCP server.

tools Annotated[list[MCPListToolsTool], Field(description='The tools available on the server.')]

The tools available on the server.

MCPListToolsTool

Bases: BaseAPIType

A tool available on an MCP server.

Attributes:

Name Type Description
name Annotated[str, Field(description='The name of the tool.')]

The name of the tool.

input_schema Annotated[dict[str, Any], Field(description="The JSON schema describing the tool's input.")]

The JSON schema describing the tool's input.

MCPProtocolError

Bases: BaseAPIType

MCPProtocolError from the OpenAI API.

MCPTool

Bases: BaseAPIType

MCPTool from the OpenAI API (upstream: MCPTool).

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

Attributes:

Name Type Description
type Annotated[Literal['mcp'], Field(description='The type of the MCP tool. Always `mcp`.')]

The type of the MCP tool. Always mcp.

server_label Annotated[str, Field(description='A label for this MCP server, used to identify it in tool calls.')]

A label for this MCP server, used to identify it in tool calls.

server_url Annotated[AnyUrl | MISSING, Field(description='The URL for the MCP server. One of `server_url`, `connector_id`, or\n`tunnel_id` must be provided.')]

The URL for the MCP server. One of server_url, connector_id, or tunnel_id must be provided.

connector_id Annotated[Literal['connector_dropbox', 'connector_gmail', 'connector_googlecalendar', 'connector_googledrive', 'connector_microsoftteams', 'connector_outlookcalendar', 'connector_outlookemail', 'connector_sharepoint'] | MISSING, Field(deprecated=True, description='Identifier for service connectors, like those available in ChatGPT. One of\n`server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more\nabout service connectors [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors).\n\nThis field is deprecated for models released after September 1, 2026.\nUse `server_url` to connect to a remote MCP server, or `tunnel_id` to\nconnect through a Secure MCP Tunnel.\n\nCurrently supported `connector_id` values are:\n\n- Dropbox: `connector_dropbox`\n- Gmail: `connector_gmail`\n- Google Calendar: `connector_googlecalendar`\n- Google Drive: `connector_googledrive`\n- Microsoft Teams: `connector_microsoftteams`\n- Outlook Calendar: `connector_outlookcalendar`\n- Outlook Email: `connector_outlookemail`\n- SharePoint: `connector_sharepoint`')]

Identifier for service connectors, like those available in ChatGPT. One of server_url, connector_id, or tunnel_id must be provided. Learn more about service connectors

here. This field is deprecated for models released after September 1, 2026. Use server_url to connect to a remote MCP server, or tunnel_id to connect through a Secure MCP Tunnel. Currently supported connector_id values are: - Dropbox: connector_dropbox - Gmail: connector_gmail - Google Calendar: connector_googlecalendar - Google Drive: connector_googledrive - Microsoft Teams: connector_microsoftteams - Outlook Calendar: connector_outlookcalendar - Outlook Email: connector_outlookemail - SharePoint: connector_sharepoint tunnel_id: The Secure MCP Tunnel ID to use instead of a direct server URL. One of server_url, connector_id, or tunnel_id must be provided. authorization: An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here. server_description: Optional description of the MCP server, used to provide more context. allowed_tools: A filter object to specify which tools are allowed. allowed_callers: The tool invocation context(s). require_approval: Specify which of the MCP server's tools require approval. Can be always, never, or a filter object associated with tools that require approval. defer_loading: Whether this MCP tool is deferred and discovered via tool search.

MCPToolCall

Bases: BaseAPIType

An invocation of a tool on an MCP server.

Attributes:

Name Type Description
type Annotated[Literal['mcp_call'], Field(description='The type of the item. Always `mcp_call`.')]

The type of the item. Always mcp_call.

id Annotated[str, Field(description='The unique ID of the tool call.')]

The unique ID of the tool call.

server_label Annotated[str, Field(description='The label of the MCP server running the tool.')]

The label of the MCP server running the tool.

name Annotated[str, Field(description='The name of the tool that was run.')]

The name of the tool that was run.

arguments Annotated[str, Field(description='A JSON string of the arguments passed to the tool.')]

A JSON string of the arguments passed to the tool.

error Annotated[MCPToolCallError | None | MISSING, Field(description='The error from the tool call, if any.')]

The error from the tool call, if any.

status Annotated[MCPToolCallStatus | MISSING, Field(description='The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`.')]

The status of the tool call. One of in_progress, completed, incomplete, calling, or failed.

MCPToolExecutionError

Bases: BaseAPIType

MCPToolExecutionError from the OpenAI API.

MCPToolFilter

Bases: BaseAPIType

A filter object to specify which tools are allowed.

Attributes:

Name Type Description
tool_names Annotated[list[str] | MISSING, Field(description='List of allowed tool names.', title='MCP allowed tools')]

List of allowed tool names.

read_only Annotated[bool | MISSING, Field(description='Indicates whether or not a tool modifies data or is read-only. If an\nMCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),\nit will match this filter.')]

Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with

readOnlyHint](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter.

MoveParam

Bases: BaseAPIType

A mouse move action.

Attributes:

Name Type Description
type Annotated[Literal['move'], Field(description='Specifies the event type. For a move action, this property is always set to `move`.')]

Specifies the event type. For a move action, this property is always set to move.

x Annotated[int, Field(description='The x-coordinate to move to.')]

The x-coordinate to move to.

y Annotated[int, Field(description='The y-coordinate to move to.')]

The y-coordinate to move to.

NamespaceToolParam

Bases: BaseAPIType

Groups function/custom tools under a shared namespace.

Attributes:

Name Type Description
type Annotated[Literal['namespace'], Field(description='The type of the tool. Always `namespace`.')]

The type of the tool. Always namespace.

name Annotated[str, Field(description='The namespace name used in tool calls (for example, `crm`).', min_length=1)]

The namespace name used in tool calls (for example, crm).

description Annotated[str, Field(description='A description of the namespace shown to the model.')]

A description of the namespace shown to the model.

tools Annotated[list[NamespaceToolParamTools], Field(description='The function/custom tools available inside this namespace.', min_length=1)]

The function/custom tools available inside this namespace.

ProgrammaticToolCallingParam

Bases: BaseAPIType

ProgrammaticToolCallingParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['programmatic_tool_calling'], Field(description='The type of the tool. Always `programmatic_tool_calling`.')]

The type of the tool. Always programmatic_tool_calling.

ProgramToolCallCaller

Bases: BaseAPIType

ProgramToolCallCaller from the OpenAI API.

Attributes:

Name Type Description
caller_id Annotated[str, Field(description='The call ID of the program item that produced this tool call.')]

The call ID of the program item that produced this tool call.

ProgramToolCallCallerParam

Bases: BaseAPIType

ProgramToolCallCallerParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['program'], Field(description='The caller type. Always `program`.')]

The caller type. Always program.

caller_id Annotated[str, Field(description='The call ID of the program item that produced this tool call.', max_length=64, min_length=1)]

The call ID of the program item that produced this tool call.

RankingOptions

Bases: BaseAPIType

RankingOptions from the OpenAI API.

Attributes:

Name Type Description
ranker Annotated[RankerVersionType | MISSING, Field(description='The ranker to use for the file search.')]

The ranker to use for the file search.

score_threshold Annotated[float | MISSING, Field(description='The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.')]

The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.

hybrid_search Annotated[HybridSearchOptions | MISSING, Field(description='Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.')]

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

ScreenshotParam

Bases: BaseAPIType

A screenshot action.

Attributes:

Name Type Description
type Annotated[Literal['screenshot'], Field(description='Specifies the event type. For a screenshot action, this property is always set to `screenshot`.')]

Specifies the event type. For a screenshot action, this property is always set to screenshot.

ScrollParam

Bases: BaseAPIType

A scroll action.

Attributes:

Name Type Description
type Annotated[Literal['scroll'], Field(description='Specifies the event type. For a scroll action, this property is always set to `scroll`.')]

Specifies the event type. For a scroll action, this property is always set to scroll.

x Annotated[int, Field(description='The x-coordinate where the scroll occurred.')]

The x-coordinate where the scroll occurred.

y Annotated[int, Field(description='The y-coordinate where the scroll occurred.')]

The y-coordinate where the scroll occurred.

scroll_x Annotated[int, Field(description='The horizontal scroll distance.')]

The horizontal scroll distance.

scroll_y Annotated[int, Field(description='The vertical scroll distance.')]

The vertical scroll distance.

SkillReferenceParam

Bases: BaseAPIType

SkillReferenceParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['skill_reference'], Field(description='References a skill created with the /v1/skills endpoint.')]

References a skill created with the /v1/skills endpoint.

skill_id Annotated[str, Field(description='The ID of the referenced skill.', max_length=64, min_length=1)]

The ID of the referenced skill.

version Annotated[str | MISSING, Field(description="Optional skill version. Use a positive integer or 'latest'. Omit for default.")]

Optional skill version. Use a positive integer or 'latest'. Omit for default.

SpecificApplyPatchParam

Bases: BaseAPIType

SpecificApplyPatchParam from the OpenAI API.

Forces the model to call the apply_patch tool when executing a tool call.

Attributes:

Name Type Description
type Annotated[Literal['apply_patch'], Field(description='The tool to call. Always `apply_patch`.')]

The tool to call. Always apply_patch.

SpecificFunctionShellParam

Bases: BaseAPIType

SpecificFunctionShellParam from the OpenAI API.

Forces the model to call the shell tool when a tool call is required.

Attributes:

Name Type Description
type Annotated[Literal['shell'], Field(description='The tool to call. Always `shell`.')]

The tool to call. Always shell.

SpecificProgrammaticToolCallingParam

Bases: BaseAPIType

SpecificProgrammaticToolCallingParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['programmatic_tool_calling'], Field(description='The tool to call. Always `programmatic_tool_calling`.')]

The tool to call. Always programmatic_tool_calling.

SvgParam

Bases: BaseAPIType

SvgParam from the OpenAI API (upstream: SvgParam).

Attributes:

Name Type Description
reasoning SvgReasoningParam | None | MISSING

Reasoning effort for SVG authoring. When omitted, uses the author model's default in both Images and Responses.

SvgReasoningParam

Bases: BaseAPIType

Reasoning effort for SVG authoring.

When omitted, uses the author model's default in both Images and Responses.

ToolChoiceAllowed

Bases: BaseAPIType

Constrains the tools available to the model to a pre-defined set.

Attributes:

Name Type Description
type Annotated[Literal['allowed_tools'], Field(description='Allowed tool configuration type. Always `allowed_tools`.')]

Allowed tool configuration type. Always allowed_tools.

mode Annotated[Literal['auto', 'required'], Field(description='Constrains the tools available to the model to a pre-defined set.\n\n`auto` allows the model to pick from among the allowed tools and generate a\nmessage.\n\n`required` requires the model to call one or more of the allowed tools.')]

Constrains the tools available to the model to a pre-defined set. auto allows the model to pick from among the allowed tools and generate a message. required requires the model to call one or more of the allowed tools.

tools Annotated[list[dict[str, Any]], Field(description='A list of tool definitions that the model should be allowed to call.\n\nFor the Responses API, the list of tool definitions might look like:\n```json\n[\n { "type": "function", "name": "get_weather" },\n { "type": "mcp", "server_label": "deepwiki" },\n { "type": "image_generation" }\n]\n```')]

A list of tool definitions that the model should be allowed to call. For the Responses API, the list of tool definitions might look like: json [ { "type": "function", "name": "get_weather" }, { "type": "mcp", "server_label": "deepwiki" }, { "type": "image_generation" } ]

ToolChoiceCustom

Bases: BaseAPIType

ToolChoiceCustom from the OpenAI API.

Use this option to force the model to call a specific custom tool.

Attributes:

Name Type Description
type Annotated[Literal['custom'], Field(description='For custom tool calling, the type is always `custom`.')]

For custom tool calling, the type is always custom.

name Annotated[str, Field(description='The name of the custom tool to call.')]

The name of the custom tool to call.

ToolChoiceFunction

Bases: BaseAPIType

Use this option to force the model to call a specific function.

Attributes:

Name Type Description
type Annotated[Literal['function'], Field(description='For function calling, the type is always `function`.')]

For function calling, the type is always function.

name Annotated[str, Field(description='The name of the function to call.')]

The name of the function to call.

ToolChoiceMCP

Bases: BaseAPIType

ToolChoiceMCP from the OpenAI API (upstream: ToolChoiceMCP).

Use this option to force the model to call a specific tool on a remote MCP server.

Attributes:

Name Type Description
type Annotated[Literal['mcp'], Field(description='For MCP tools, the type is always `mcp`.')]

For MCP tools, the type is always mcp.

server_label Annotated[str, Field(description='The label of the MCP server to use.')]

The label of the MCP server to use.

ToolChoiceTypes

Bases: BaseAPIType

ToolChoiceTypes from the OpenAI API.

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

Attributes:

Name Type Description
type Annotated[Literal['file_search', 'web_search_preview', 'computer', 'computer_use_preview', 'computer_use', 'web_search_preview_2025_03_11', 'image_generation', 'code_interpreter'], Field(description='The type of hosted tool the model should to use. Learn more about\n[built-in tools](https://developers.openai.com/api/docs/guides/tools).\n\nAllowed values are:\n- `file_search`\n- `web_search_preview`\n- `computer`\n- `computer_use_preview`\n- `computer_use`\n- `code_interpreter`\n- `image_generation`')]

The type of hosted tool the model should to use. Learn more about [built-in

tools](https://developers.openai.com/api/docs/guides/tools). Allowed values are: - file_search - web_search_preview - computer - computer_use_preview - computer_use - code_interpreter - image_generation

ToolSearchOutputFunctionToolParam

Bases: BaseAPIType

ToolSearchOutputFunctionToolParam from the OpenAI API.

Attributes:

Name Type Description
name Annotated[str, Field(description='The name of the loaded function tool.', max_length=128, min_length=1, pattern='^(?![\\s\\S]*[\\r\\n])[a-zA-Z0-9_.-]+$')]

The name of the loaded function tool.

async_ Annotated[bool | MISSING, Field(validation_alias='async', description='Whether the tool response can be returned asynchronously versus immediately returned on next response creation.', serialization_alias='async')]

Whether the tool response can be returned asynchronously versus immediately returned on next response creation.

defer_loading Annotated[bool | MISSING, Field(description='Whether this function should be deferred and discovered via tool search.')]

Whether this function should be deferred and discovered via tool search.

allowed_callers ToolSearchOutputFunctionToolParamAllowedCallers | None | MISSING

The tool invocation context(s).

ToolSearchOutputNamespaceToolParam

Bases: BaseAPIType

Groups function/custom tools under a shared namespace.

Attributes:

Name Type Description
type Annotated[Literal['namespace'], Field(description='The type of the tool. Always `namespace`.')]

The type of the tool. Always namespace.

name Annotated[str, Field(description='The namespace name used in tool calls (for example, `crm`).', min_length=1)]

The namespace name used in tool calls (for example, crm).

description Annotated[str, Field(description='A description of the namespace shown to the model.')]

A description of the namespace shown to the model.

tools Annotated[list[ToolSearchOutputNamespaceToolParamTools], Field(description='The function/custom tools loaded inside this namespace.', min_length=1)]

The function/custom tools loaded inside this namespace.

ToolSearchToolParam

Bases: BaseAPIType

Hosted or BYOT tool search configuration for deferred tools.

Attributes:

Name Type Description
type Annotated[Literal['tool_search'], Field(description='The type of the tool. Always `tool_search`.')]

The type of the tool. Always tool_search.

execution Annotated[ToolSearchExecutionType | MISSING, Field(description='Whether tool search is executed by the server or by the client.')]

Whether tool search is executed by the server or by the client.

TypeParam

Bases: BaseAPIType

An action to type in text.

Attributes:

Name Type Description
type Annotated[Literal['type'], Field(description='Specifies the event type. For a type action, this property is always set to `type`.')]

Specifies the event type. For a type action, this property is always set to type.

text Annotated[str, Field(description='The text to type.')]

The text to type.

WaitParam

Bases: BaseAPIType

A wait action.

Attributes:

Name Type Description
type Annotated[Literal['wait'], Field(description='Specifies the event type. For a wait action, this property is always set to `wait`.')]

Specifies the event type. For a wait action, this property is always set to wait.

WebSearchActionFind

Bases: BaseAPIType

WebSearchActionFind from the OpenAI API.

Action type "find_in_page": Searches for a pattern within a loaded page.

Attributes:

Name Type Description
type Annotated[Literal['find_in_page'], Field(description='The action type.')]

The action type.

url Annotated[AnyUrl | None | MISSING, Field(description='The URL of the page searched for the pattern, when available.')]

The URL of the page searched for the pattern, when available.

pattern Annotated[str, Field(description='The pattern or text to search for within the page.')]

The pattern or text to search for within the page.

WebSearchActionOpenPage

Bases: BaseAPIType

WebSearchActionOpenPage from the OpenAI API.

Action type "open_page" - Opens a specific URL from search results.

Attributes:

Name Type Description
type Annotated[Literal['open_page'], Field(description='The action type.')]

The action type.

url Annotated[AnyUrl | None | MISSING, Field(description='The URL opened by the model.')]

The URL opened by the model.

WebSearchActionSearch

Bases: BaseAPIType

Action type "search" - Performs a web search query.

Attributes:

Name Type Description
type Annotated[Literal['search'], Field(description='The action type.')]

The action type.

query Annotated[str | MISSING, Field(deprecated=True, description='The search query.')]

The search query.

queries Annotated[list[str] | MISSING, Field(description='The search queries.', title='Search queries')]

The search queries.

sources Annotated[list[WebSearchActionSearchSource] | MISSING, Field(description='The sources used in the search.', title='Web search sources')]

The sources used in the search.

WebSearchPreviewTool

Bases: BaseAPIType

WebSearchPreviewTool from the OpenAI API.

This tool searches the web for relevant results to use in a response. Learn more about the web search tool.

Attributes:

Name Type Description
type Annotated[Literal['web_search_preview', 'web_search_preview_2025_03_11'], Field(description='The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.')]

The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11.

search_context_size Annotated[SearchContextSize | MISSING, Field(description='High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.')]

High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.

WebSearchTool

Bases: BaseAPIType

Search the Internet for sources related to the prompt.

Learn more about the web search tool.

Attributes:

Name Type Description
type Annotated[Literal['web_search', 'web_search_2025_08_26'], Field(description='The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.')]

The type of the web search tool. One of web_search or web_search_2025_08_26.

external_web_access Annotated[bool | MISSING, Field(description='Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content.')]

Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content.

filters WebSearchToolFilters | None | MISSING

Filters for the search.

user_location Annotated[WebSearchApproximateLocation | None | MISSING, Field(description='The approximate location of the user. If omitted or null, defaults to the\nUnited States. To avoid this fallback, pass `{"type": "approximate"}` without\nlocation fields. To localize results, provide the relevant location fields.')]

The approximate location of the user. If omitted or null, defaults to the United States. To avoid this fallback, pass {"type": "approximate"} without location fields. To localize results, provide the relevant location fields.

search_context_size Annotated[Literal['low', 'medium', 'high'] | MISSING, Field(description='High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.')]

High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.

WebSearchToolCall

Bases: BaseAPIType

The results of a web search tool call.

See the web search guide for more information.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of the web search tool call.')]

The unique ID of the web search tool call.

type Annotated[Literal['web_search_call'], Field(description='The type of the web search tool call. Always `web_search_call`.')]

The type of the web search tool call. Always web_search_call.

status Annotated[WebSearchCallStatus, Field(description='The status of the web search tool call.')]

The status of the web search tool call.

action Annotated[WebSearchActionSearch | WebSearchActionOpenPage | WebSearchActionFind | MISSING, Field(description='An object describing the specific action taken in this web search call.\nIncludes details on how the model used the web (search, open_page, find_in_page).', discriminator='type')]

An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page).

SvgUsage

Bases: BaseAPIType

SvgUsage from the OpenAI API (upstream: SvgUsage).

adapters

OpenAI's adapters between shared types and its methods.

Modules:

Name Description
conversions

Conversions of OpenAI's Responses types into shared types.

files

Adapter of shared files to OpenAI's Files API.

generation

Adapter of shared generation to OpenAI's Responses API.

Classes:

Name Description
OpenAIFilesAdapter

Stores files with OpenAI's /files.

OpenAIGenerationAdapter

Generates text with POST /responses.

Functions:

Name Description
output_text

Join the text of all output messages.

reasoning_summary

Join the summaries of all reasoning items.

tool_calls

Collect the function calls of a response.

OpenAIFilesAdapter

OpenAIFilesAdapter(*, page_size: int = DEFAULT_PAGE_SIZE)

Bases: BaseFilesAdapter[OpenAIFile, ListFilesResponse]

Stores files with OpenAI's /files.

An upload is a user_data file unless provider_options sets another purpose; expires_in_seconds becomes expires_after from the file's creation. The list goes newest first, page_size files a request, by after the last id.

Attributes:

Name Type Description
page_size

Files asked for in one page of the list.

Example

files = FilesResource(session, OpenAIFilesAdapter()) stored = await files.upload(Path("report.pdf"))

Store the page size.

Parameters:

Name Type Description Default
page_size int

Files asked for in one page of the list.

DEFAULT_PAGE_SIZE

Methods:

Name Description
with_options

Return a copy that sends the options with every upload.

to_upload_method

Build the method that stores a file.

to_retrieve_method

Build the method that reads a file's metadata.

to_list_method

Build the method that reads one page of the stored files.

to_page

Take the files of a page and where the next one starts.

to_delete_method

Build the method that deletes a file.

to_download_method

Build the method that streams a file's content.

to_stored_file

Convert OpenAI's file into the shared metadata.

with_options

with_options(options: OpenAIFileOptions) -> Self

Return a copy that sends the options with every upload.

Parameters:

Name Type Description Default
options OpenAIFileOptions

Fields of CreateFile that the shared upload does not hold, such as {"purpose": "vision"}.

required

Returns:

Type Description
Self

A copy of the adapter; this one is left as it is.

Raises:

Type Description
RequestValidationError

A key is not one of the options.

to_upload_method

to_upload_method(request: FileUpload) -> CreateFile

Build the method that stores a file.

Parameters:

Name Type Description Default
request FileUpload

The shared upload.

required

Returns:

Type Description
CreateFile

CreateFile with the file, its purpose and its expiry.

Raises:

Type Description
RequestValidationError

OpenAI cannot take the upload, such as an expiry outside 3600 to 2 592 000 seconds or an unknown purpose.

to_retrieve_method

to_retrieve_method(file_id: str) -> RetrieveFile

Build the method that reads a file's metadata.

Parameters:

Name Type Description Default
file_id str

OpenAI's id of the file.

required

Returns:

Type Description
RetrieveFile

RetrieveFile.

to_list_method

to_list_method(cursor: str | None) -> ListFiles

Build the method that reads one page of the stored files.

Parameters:

Name Type Description Default
cursor str | None

The id of the last file of the page before, or None for the first page.

required

Returns:

Type Description
ListFiles

ListFiles of page_size files, newest first.

to_page

to_page(
    raw: ListFilesResponse,
) -> tuple[Sequence[OpenAIFile], str | None]

Take the files of a page and where the next one starts.

Parameters:

Name Type Description Default
raw ListFilesResponse

The page.

required

Returns:

Type Description
tuple[Sequence[OpenAIFile], str | None]

Its files, and last_id while has_more is true.

to_delete_method

to_delete_method(file_id: str) -> DeleteFile

Build the method that deletes a file.

Parameters:

Name Type Description Default
file_id str

OpenAI's id of the file.

required

Returns:

Type Description
DeleteFile

DeleteFile.

to_download_method

to_download_method(
    file: ProviderFile,
) -> DownloadFile | RetrieveContainerFileContent

Build the method that streams a file's content.

Parameters:

Name Type Description Default
file ProviderFile

The file: a stored one, or a ProducedFile of a code interpreter's container.

required

Returns:

Type Description
DownloadFile | RetrieveContainerFileContent

RetrieveContainerFileContent for a file of a container, else

DownloadFile | RetrieveContainerFileContent

DownloadFile; OpenAI refuses a user_data file.

to_stored_file

to_stored_file(raw: OpenAIFile) -> StoredFile[OpenAIFile]

Convert OpenAI's file into the shared metadata.

Parameters:

Name Type Description Default
raw OpenAIFile

OpenAI's file.

required

Returns:

Type Description
StoredFile[OpenAIFile]

Its id, name, bytes as size and its Unix times in

StoredFile[OpenAIFile]

UTC.

OpenAIGenerationAdapter

OpenAIGenerationAdapter(
    *,
    input_conversion: IConversion[
        str | Sequence[InputItem],
        str | list[dict[str, Any]],
    ] = INPUT_CONVERSION,
    usage_conversion: IConversion[
        ResponseUsage, TokenUsage
    ] = USAGE_CONVERSION,
    stop_conversion: IConversion[
        Response, Stop
    ] = STOP_CONVERSION,
    schema_name: str = DEFAULT_SCHEMA_NAME,
)

Bases: BaseCompositeAdapter[GenerationRequest, Response, GenerationResponse[Response], ResponseStreamEvent, GenerationEvent[ResponseStreamEvent]]

Generates text with POST /responses.

Request fields map one to one; a list of turns becomes a list of EasyInputMessage items. OpenAI's own limits are checked when the method is built, so a request that OpenAI would reject, such as max_output_tokens below 16, more than 16 metadata pairs or a conversation that does not end with a user turn, raises RequestValidationError before anything is sent.

The conversions of the input, the token counts and the stop are keyword arguments, so any of them can be swapped without a subclass; a stream's terminal event goes through the same ones as a response.

Attributes:

Name Type Description
input_conversion

Turns the shared input into OpenAI's.

usage_conversion

Turns OpenAI's ResponseUsage into shared counts.

stop_conversion

Tells how a finished response stopped.

Example

generation = GenerationResource(session, OpenAIGenerationAdapter()) response = await generation.create( ... GenerationRequest(model="gpt-5", input="Hi") ... )

Store the conversions and the name of an output schema.

Parameters:

Name Type Description Default
input_conversion IConversion[str | Sequence[InputItem], str | list[dict[str, Any]]]

Turns the shared input into OpenAI's.

INPUT_CONVERSION
usage_conversion IConversion[ResponseUsage, TokenUsage]

Turns OpenAI's ResponseUsage into shared counts.

USAGE_CONVERSION
stop_conversion IConversion[Response, Stop]

Tells how a finished response stopped.

STOP_CONVERSION
schema_name str

The name OpenAI requires with a JSON Schema format; the shared output_schema has none.

DEFAULT_SCHEMA_NAME

Methods:

Name Description
with_options

Return a copy that sends the options with every method.

to_method

Build the method that creates a response at once.

to_response

Convert a finished response.

to_stream_method

Build the method that streams a response.

to_events

Convert the events of a Responses stream.

with_options

with_options(options: OpenAIGenerationOptions) -> Self

Return a copy that sends the options with every method.

Parameters:

Name Type Description Default
options OpenAIGenerationOptions

Fields of CreateResponse that the shared request does not hold, such as {"store": False}.

required

Returns:

Type Description
Self

A copy of the adapter; this one is left as it is.

Raises:

Type Description
RequestValidationError

A key is not one of the options.

to_method

to_method(request: GenerationRequest) -> CreateResponse

Build the method that creates a response at once.

Parameters:

Name Type Description Default
request GenerationRequest

The shared request.

required

Returns:

Type Description
CreateResponse

CreateResponse with the request's fields.

Raises:

Type Description
RequestValidationError

OpenAI cannot take the request.

to_response

to_response(
    raw: Response, request: GenerationRequest
) -> GenerationResponse[Response]

Convert a finished response.

Parameters:

Name Type Description Default
raw Response

OpenAI's response.

required
request GenerationRequest

The request it answers.

required

Returns:

Type Description
GenerationResponse[Response]

The generated text with its token counts, the calls of the

GenerationResponse[Response]

built-in tools OpenAI ran (server_tool_calls), the

GenerationResponse[Response]

sources its text cites (citations) and the files of a

GenerationResponse[Response]

container it names (files); an incomplete

GenerationResponse[Response]

response keeps its text and gets incomplete_reason, and

GenerationResponse[Response]

a refusal gets IncompleteReason.REFUSAL and refusal.

Raises:

Type Description
APIResponseError

The response did not finish. A failed one is raised by CreateResponse before it gets here.

to_stream_method

to_stream_method(
    request: GenerationRequest,
) -> StreamResponse

Build the method that streams a response.

Parameters:

Name Type Description Default
request GenerationRequest

The shared request.

required

Returns:

Type Description
StreamResponse

StreamResponse with the request's fields.

Raises:

Type Description
RequestValidationError

OpenAI cannot take the request.

to_events async

to_events(
    items: AsyncIterator[ResponseStreamEvent],
    request: GenerationRequest,
) -> AsyncGenerator[GenerationEvent[ResponseStreamEvent]]

Convert the events of a Responses stream.

Parameters:

Name Type Description Default
items AsyncIterator[ResponseStreamEvent]

The events OpenAI sent.

required
request GenerationRequest

The request the stream answers.

required

Yields:

Type Description
AsyncGenerator[GenerationEvent[ResponseStreamEvent]]

One shared event per OpenAI event; an item of a built-in

AsyncGenerator[GenerationEvent[ResponseStreamEvent]]

tool call is a ServerToolCallEvent when it is added and

AsyncGenerator[GenerationEvent[ResponseStreamEvent]]

when it is done. The stream's end is

AsyncGenerator[GenerationEvent[ResponseStreamEvent]]

checked by StreamResponse and by the use case.

Raises:

Type Description
APIResponseError

Arguments came for an item that no response.output_item.added opened as a function call.

output_text

output_text(response: Response) -> str | None

Join the text of all output messages.

The Responses API sends no such field: its schema names output_text as a property the SDKs compute, so Response reads it as None. It is collected here the way the SDKs do, from the output_text parts of the message items.

Parameters:

Name Type Description Default
response Response

A response.

required

Returns:

Type Description
str | None

The joined text, or None if the output has no text part.

reasoning_summary

reasoning_summary(response: Response) -> str | None

Join the summaries of all reasoning items.

Parameters:

Name Type Description Default
response Response

A response.

required

Returns:

Type Description
str | None

The joined summaries, or None if there are none (the

str | None

request did not ask for them).

tool_calls

tool_calls(response: Response) -> list[ToolCall]

Collect the function calls of a response.

Parameters:

Name Type Description Default
response Response

A response.

required

Returns:

Type Description
list[ToolCall]

A shared call per function_call item, in output order, with

list[ToolCall]

its call_id; empty without calls.

types

OpenAI's own types and the options of a generation call.

Every module but options is written by aiollm-codegen through scripts/generate_types.py; do not edit them by hand.

Modules:

Name Description
events

Provider events types generated from OpenAPI.

files

Provider files types generated from OpenAPI.

images

Provider images types generated from OpenAPI.

messages

Provider messages types generated from OpenAPI.

options

OpenAI's own options of a generation call.

responses

Provider responses types generated from OpenAPI.

shared

Provider shared types generated from OpenAPI.

tools

Provider tools types generated from OpenAPI.

usage

Provider usage types generated from OpenAPI.

Classes:

Name Description
OpenAIFileOptions

Fields of POST /files that the shared upload does not hold.

OpenAIGenerationOptions

Fields of POST /responses that the shared request does not hold.

OpenAIReasoningOptions

The parts of reasoning that the shared request does not set.

ResponseAudioDeltaEvent

Emitted when there is a partial audio response.

ResponseAudioDoneEvent

Emitted when the audio response is complete.

ResponseAudioTranscriptDeltaEvent

Emitted when there is a partial transcript of audio.

ResponseAudioTranscriptDoneEvent

Emitted when the full audio transcript is completed.

ResponseCodeInterpreterCallCodeDeltaEvent

ResponseCodeInterpreterCallCodeDeltaEvent from the OpenAI API.

ResponseCodeInterpreterCallCodeDoneEvent

ResponseCodeInterpreterCallCodeDoneEvent from the OpenAI API.

ResponseCodeInterpreterCallCompletedEvent

Emitted when the code interpreter call is completed.

ResponseCodeInterpreterCallInProgressEvent

Emitted when a code interpreter call is in progress.

ResponseCodeInterpreterCallInterpretingEvent

ResponseCodeInterpreterCallInterpretingEvent.

ResponseCompactionCompactingStreamingEvent

ResponseCompactionCompactingStreamingEvent from the OpenAI API.

ResponseCompletedEvent

Emitted when the model response is complete.

ResponseContentPartAddedEvent

Emitted when a new content part is added.

ResponseContentPartDoneEvent

Emitted when a content part is done.

ResponseCreatedEvent

An event that is emitted when a response is created.

ResponseCustomToolCallInputDeltaEvent

ResponseCustomToolCallInputDeltaEvent from the OpenAI API.

ResponseCustomToolCallInputDoneEvent

Event indicating that input for a custom tool call is complete.

ResponseErrorEvent

Emitted when an error occurs.

ResponseFailedEvent

An event that is emitted when a response fails.

ResponseFileSearchCallCompletedEvent

Emitted when a file search call is completed (results found).

ResponseFileSearchCallInProgressEvent

Emitted when a file search call is initiated.

ResponseFileSearchCallSearchingEvent

Emitted when a file search is currently searching.

ResponseFunctionCallArgumentsDeltaEvent

Emitted when there is a partial function-call arguments delta.

ResponseFunctionCallArgumentsDoneEvent

Emitted when function-call arguments are finalized.

ResponseImageGenCallCompletedEvent

ResponseImageGenCallCompletedEvent from the OpenAI API.

ResponseImageGenCallGeneratingEvent

ResponseImageGenCallGeneratingEvent from the OpenAI API.

ResponseImageGenCallInProgressEvent

Emitted when an image generation tool call is in progress.

ResponseImageGenCallPartialImageEvent

ResponseImageGenCallPartialImageEvent from the OpenAI API.

ResponseIncompleteEvent

An event that is emitted when a response finishes as incomplete.

ResponseInProgressEvent

Emitted when the response is in progress.

ResponseMCPCallArgumentsDeltaEvent

ResponseMCPCallArgumentsDeltaEvent from the OpenAI API.

ResponseMCPCallArgumentsDoneEvent

Emitted when the arguments for an MCP tool call are finalized.

ResponseMCPCallCompletedEvent

Emitted when an MCP tool call has completed successfully.

ResponseMCPCallFailedEvent

Emitted when an MCP tool call has failed.

ResponseMCPCallInProgressEvent

Emitted when an MCP tool call is in progress.

ResponseMCPListToolsCompletedEvent

ResponseMCPListToolsCompletedEvent from the OpenAI API.

ResponseMCPListToolsFailedEvent

Emitted when the attempt to list available MCP tools has failed.

ResponseMCPListToolsInProgressEvent

ResponseMCPListToolsInProgressEvent from the OpenAI API.

ResponseOutputItemAddedEvent

Emitted when a new output item is added.

ResponseOutputItemDoneEvent

Emitted when an output item is marked done.

ResponseOutputTextAnnotationAddedEvent

Emitted when an annotation is added to output text content.

ResponseQueuedEvent

Emitted when a response is queued and waiting to be processed.

ResponseReasoningSummaryPartAddedEvent

Emitted when a new reasoning summary part is added.

ResponseReasoningSummaryPartDoneEvent

Emitted when a reasoning summary part is completed.

ResponseReasoningSummaryTextDeltaEvent

Emitted when a delta is added to a reasoning summary text.

ResponseReasoningSummaryTextDoneEvent

Emitted when a reasoning summary text is completed.

ResponseReasoningTextDeltaEvent

Emitted when a delta is added to a reasoning text.

ResponseReasoningTextDoneEvent

Emitted when a reasoning text is completed.

ResponseRefusalDeltaEvent

Emitted when there is a partial refusal text.

ResponseRefusalDoneEvent

Emitted when refusal text is finalized.

ResponseShellCallCommandAddedStreamingEvent

ResponseShellCallCommandAddedStreamingEvent.

ResponseShellCallCommandDeltaStreamingEvent

ResponseShellCallCommandDeltaStreamingEvent.

ResponseShellCallCommandDoneStreamingEvent

A streaming event that indicated a shell command was completed.

ResponseShellCallOutputContentDeltaStreamingEvent

ResponseShellCallOutputContentDeltaStreamingEvent.

ResponseShellCallOutputContentDoneStreamingEvent

A streaming event that indicated shell call output was completed.

ResponseTextDeltaEvent

Emitted when there is an additional text delta.

ResponseTextDoneEvent

Emitted when text content is finalized.

ResponseWebSearchCallCompletedEvent

Emitted when a web search call is completed.

ResponseWebSearchCallInProgressEvent

Emitted when a web search call is initiated.

ResponseWebSearchCallSearchingEvent

Emitted when a web search call is executing.

ShellCallOutputDelta

A delta of stdout/stderr emitted while a shell call was running.

ApplyPatchCreateFileOperation

ApplyPatchCreateFileOperation from the OpenAI API.

ApplyPatchCreateFileOperationParam

Instruction for creating a new file via the apply_patch tool.

ApplyPatchDeleteFileOperation

ApplyPatchDeleteFileOperation from the OpenAI API.

ApplyPatchDeleteFileOperationParam

ApplyPatchDeleteFileOperationParam from the OpenAI API.

ApplyPatchUpdateFileOperation

ApplyPatchUpdateFileOperation from the OpenAI API.

ApplyPatchUpdateFileOperationParam

ApplyPatchUpdateFileOperationParam from the OpenAI API.

ContainerFileCitationBody

ContainerFileCitationBody from the OpenAI API.

DeleteFileResponse

DeleteFileResponse from the OpenAI API.

FileCitationBody

A citation to a file.

FilePath

A path to a file.

ListFilesResponse

ListFilesResponse from the OpenAI API.

OpenAIFile

OpenAIFile from the OpenAI API (upstream: OpenAIFile).

CodeInterpreterOutputImage

The image output from the code interpreter.

ComputerScreenshotImage

A computer screenshot image used with the computer use tool.

ImageGenOutputTokensDetails

The output token details for the image generation.

ResolvedImageOptions

ResolvedImageOptions from the OpenAI API.

FunctionShellCallOutputExitOutcome

FunctionShellCallOutputExitOutcome from the OpenAI API.

FunctionShellCallOutputExitOutcomeParam

FunctionShellCallOutputExitOutcomeParam from the OpenAI API.

FunctionShellCallOutputTimeoutOutcome

Indicates that the shell call exceeded its configured time limit.

FunctionShellCallOutputTimeoutOutcomeParam

Indicates that the shell call exceeded its configured time limit.

InputFileContent

A file input to the model.

InputFileContentParam

A file input to the model.

InputImageContent

An image input to the model.

InputImageContentParamAutoParam

An image input to the model.

InputTextContent

A text input to the model.

InputTextContentParam

A text input to the model.

LogProb

The log probability of a token.

PromptCacheBreakpointConfig

Marks the exact end of a reusable prompt prefix.

PromptCacheBreakpointParam

Marks the exact end of a reusable prompt prefix.

ReasoningTextContent

Reasoning text from the model.

RefusalContent

A refusal from the model.

SummaryTextContent

A summary text from the model.

TopLogProb

The top log probability of a token.

AccessProgramsBody

AccessProgramsBody from the OpenAI API.

CompactionTriggerItemParam

Compacts the current context.

FieldMisalignmentSteer

FieldMisalignmentSteer from the OpenAI API.

ItemReferenceParam

An internal identifier for an item to reference.

MisalignmentErrorDetailsResource

MisalignmentErrorDetailsResource from the OpenAI API.

ModelResponseProperties

ModelResponseProperties from the OpenAI API.

Moderation

Moderation results or errors for the response input and output.

ModerationErrorBody

ModerationErrorBody from the OpenAI API.

ModerationResultBody

A moderation result produced for the response input or output.

ProgramItemParam

ProgramItemParam from the OpenAI API.

ProgramOutputItemParam

ProgramOutputItemParam from the OpenAI API.

PromptCacheComparisonResponseNotFoundDiagnosticsBody

PromptCacheComparisonResponseNotFoundDiagnosticsBody.

PromptCacheHitDiagnosticsBody

PromptCacheHitDiagnosticsBody from the OpenAI API.

PromptCacheMissDiagnosticsBody

PromptCacheMissDiagnosticsBody from the OpenAI API.

PromptCacheOptions

The prompt-caching options that were applied to the response.

PromptCacheUnavailableDiagnosticsBody

PromptCacheUnavailableDiagnosticsBody from the OpenAI API.

Reasoning

Reasoning from the OpenAI API (upstream: Reasoning).

ReasoningInputTransformation

ReasoningInputTransformation from the OpenAI API.

Response

Response from the OpenAI API (upstream: Response).

ResponseConfigurationUpdateItemParam

An update to the conversation's response configuration.

ResponseConversation

The conversation that this response belonged to.

ResponseFormatJsonObject

JSON object response format.

ResponseFormatJsonSchemaSchema

ResponseFormatJsonSchemaSchema from the OpenAI API.

ResponseFormatText

Default response format.

ResponseLogProb

ResponseLogProb from the OpenAI API.

ResponseProperties

ResponseProperties from the OpenAI API.

ResponseTextParam

Configuration options for a text response from the model.

TextResponseFormatJsonSchema

JSON Schema response format.

AdditionalTools

AdditionalTools from the OpenAI API.

AdditionalToolsItemParam

AdditionalToolsItemParam from the OpenAI API.

ApplyPatchToolCall

ApplyPatchToolCall from the OpenAI API.

ApplyPatchToolCallItemParam

ApplyPatchToolCallItemParam from the OpenAI API.

ApplyPatchToolCallOutput

The output emitted by an apply patch tool call.

ApplyPatchToolCallOutputItemParam

The streamed output emitted by an apply patch tool call.

AutoCodeInterpreterToolParam

Configuration for a code interpreter container.

CodeInterpreterTool

CodeInterpreterTool from the OpenAI API.

CodeInterpreterToolCall

A tool call to run code.

CompactionBody

CompactionBody from the OpenAI API.

CompactionSummaryItemParam

CompactionSummaryItemParam from the OpenAI API.

ComputerCallOutputItemParam

The output of a computer tool call.

ComputerCallSafetyCheckParam

A pending safety check for the computer call.

ComputerToolCall

A tool call to a computer use tool.

ComputerToolCallOutput

The output of a computer tool call.

ComputerToolCallOutputResource

The output of a computer tool call.

ContainerAutoParam

ContainerAutoParam from the OpenAI API.

ContainerReferenceParam

ContainerReferenceParam from the OpenAI API.

ContainerReferenceResource

Represents a container created with /v1/containers.

CustomToolCall

A call to a custom tool created by the model.

CustomToolCallOutput

CustomToolCallOutput from the OpenAI API.

CustomToolCallOutputResource

CustomToolCallOutputResource from the OpenAI API.

CustomToolParam

A custom tool that processes input using a specified format.

EasyInputMessage

EasyInputMessage from the OpenAI API.

FunctionCallOutputItemParam

The output of a function tool call.

FunctionShellCall

FunctionShellCall from the OpenAI API.

FunctionShellCallItemParam

FunctionShellCallItemParam from the OpenAI API.

FunctionShellCallOutput

The output of a shell tool call that was emitted.

FunctionShellCallOutputContent

The content of a shell tool call output that was emitted.

FunctionShellCallOutputContentParam

FunctionShellCallOutputContentParam from the OpenAI API.

FunctionShellCallOutputItemParam

The streamed output items emitted by a shell tool call.

FunctionShellToolParam

A tool that allows the model to execute shell commands.

FunctionToolCall

A tool call to run a function.

FunctionToolCallOutput

The output of a function tool call.

FunctionToolCallOutputResource

The output of a function tool call.

InputMessage

InputMessage from the OpenAI API (upstream: InputMessage).

LocalEnvironmentParam

LocalEnvironmentParam from the OpenAI API.

LocalEnvironmentResource

LocalEnvironmentResource from the OpenAI API.

LocalSkillParam

LocalSkillParam from the OpenAI API.

MCPToolCall

An invocation of a tool on an MCP server.

NamespaceToolParam

Groups function/custom tools under a shared namespace.

OutputMessage

An output message from the model.

OutputTextContent

A text output from the model.

Program

Program from the OpenAI API (upstream: Program).

ProgramOutput

ProgramOutput from the OpenAI API (upstream: ProgramOutput).

ReasoningItem

ReasoningItem from the OpenAI API (upstream: ReasoningItem).

ToolSearchCallItemParam

ToolSearchCallItemParam from the OpenAI API.

ToolSearchOutput

ToolSearchOutput from the OpenAI API.

ToolSearchOutputItemParam

ToolSearchOutputItemParam from the OpenAI API.

ToolSearchOutputNamespaceToolParam

Groups function/custom tools under a shared namespace.

UrlCitationBody

A citation for a web resource used to generate a model response.

WebSearchToolCall

The results of a web search tool call.

ApplyPatchToolParam

ApplyPatchToolParam from the OpenAI API.

ApproximateLocation

ApproximateLocation from the OpenAI API.

ClickParam

A click action.

CodeInterpreterOutputLogs

The logs output from the code interpreter.

ComparisonFilter

ComparisonFilter from the OpenAI API.

CompoundFilter

Combine multiple filters using and or or.

ComputerTool

A tool that controls a virtual computer.

ComputerUsePreviewTool

A tool that controls a virtual computer.

ContainerNetworkPolicyAllowlistParam

ContainerNetworkPolicyAllowlistParam from the OpenAI API.

ContainerNetworkPolicyDisabledParam

ContainerNetworkPolicyDisabledParam from the OpenAI API.

ContainerNetworkPolicyDomainSecretParam

ContainerNetworkPolicyDomainSecretParam from the OpenAI API.

CoordParam

An x/y coordinate pair, e.g.

CustomGrammarFormatParam

A grammar defined by the user.

CustomTextFormatParam

Unconstrained free-form text.

DirectToolCallCaller

DirectToolCallCaller from the OpenAI API.

DirectToolCallCallerParam

DirectToolCallCallerParam from the OpenAI API.

DoubleClickAction

A double click action.

DragParam

A drag action.

EmptyModelParam

EmptyModelParam from the OpenAI API.

FileSearchTool

A tool that searches for relevant content from uploaded files.

FileSearchToolCall

The results of a file search tool call.

FunctionShellAction

Execute a shell command.

FunctionShellActionParam

Commands and limits describing how to run the shell tool call.

FunctionTool

Defines a function in your own code the model can choose to call.

FunctionToolParam

FunctionToolParam from the OpenAI API.

HTTPError

HTTPError from the OpenAI API (upstream: HTTPError).

HybridSearchOptions

HybridSearchOptions from the OpenAI API.

ImageGenTool

A tool that generates images using the GPT image models.

ImageGenToolCall

An image generation request made by the model.

ImageGenToolCallError

ImageGenToolCallError from the OpenAI API.

ImageGenToolCallModerationDetails

ImageGenToolCallModerationDetails from the OpenAI API.

InlineSkillParam

InlineSkillParam from the OpenAI API.

InlineSkillSourceParam

Inline skill payload.

KeyPressAction

A collection of keypresses the model would like to perform.

LocalShellExecAction

Execute a shell command on the server.

LocalShellToolCall

A tool call to run a command on the local shell.

LocalShellToolCallOutput

The output of a local shell tool call.

LocalShellToolParam

LocalShellToolParam from the OpenAI API.

MCPApprovalRequest

A request for human approval of a tool invocation.

MCPApprovalResponse

A response to an MCP approval request.

MCPApprovalResponseResource

A response to an MCP approval request.

MCPListTools

A list of tools available on an MCP server.

MCPListToolsTool

A tool available on an MCP server.

MCPProtocolError

MCPProtocolError from the OpenAI API.

MCPTool

MCPTool from the OpenAI API (upstream: MCPTool).

MCPToolExecutionError

MCPToolExecutionError from the OpenAI API.

MCPToolFilter

A filter object to specify which tools are allowed.

MoveParam

A mouse move action.

ProgrammaticToolCallingParam

ProgrammaticToolCallingParam from the OpenAI API.

ProgramToolCallCaller

ProgramToolCallCaller from the OpenAI API.

ProgramToolCallCallerParam

ProgramToolCallCallerParam from the OpenAI API.

RankingOptions

RankingOptions from the OpenAI API.

ScreenshotParam

A screenshot action.

ScrollParam

A scroll action.

SkillReferenceParam

SkillReferenceParam from the OpenAI API.

SpecificApplyPatchParam

SpecificApplyPatchParam from the OpenAI API.

SpecificFunctionShellParam

SpecificFunctionShellParam from the OpenAI API.

SpecificProgrammaticToolCallingParam

SpecificProgrammaticToolCallingParam from the OpenAI API.

SvgParam

SvgParam from the OpenAI API (upstream: SvgParam).

SvgReasoningParam

Reasoning effort for SVG authoring.

ToolChoiceAllowed

Constrains the tools available to the model to a pre-defined set.

ToolChoiceCustom

ToolChoiceCustom from the OpenAI API.

ToolChoiceFunction

Use this option to force the model to call a specific function.

ToolChoiceMCP

ToolChoiceMCP from the OpenAI API (upstream: ToolChoiceMCP).

ToolChoiceTypes

ToolChoiceTypes from the OpenAI API.

ToolSearchCall

ToolSearchCall from the OpenAI API.

ToolSearchOutputFunctionToolParam

ToolSearchOutputFunctionToolParam from the OpenAI API.

ToolSearchToolParam

Hosted or BYOT tool search configuration for deferred tools.

TypeParam

An action to type in text.

WaitParam

A wait action.

WebSearchActionFind

WebSearchActionFind from the OpenAI API.

WebSearchActionOpenPage

WebSearchActionOpenPage from the OpenAI API.

WebSearchActionSearch

Action type "search" - Performs a web search query.

WebSearchPreviewTool

WebSearchPreviewTool from the OpenAI API.

WebSearchTool

Search the Internet for sources related to the prompt.

CachedUsageDetails

CachedUsageDetails from the OpenAI API.

CacheWriteTokensDetails

CacheWriteTokensDetails from the OpenAI API.

ImageGenInputUsageDetails

The input tokens detailed information for the image generation.

ImageGenToolUsage

Token usage for image generation tool calls in a response.

ResponseToolUsage

ResponseToolUsage from the OpenAI API.

ResponseUsage

ResponseUsage from the OpenAI API (upstream: ResponseUsage).

SvgUsage

SvgUsage from the OpenAI API (upstream: SvgUsage).

WebSearchUsage

WebSearchUsage from the OpenAI API.

OpenAIFileOptions

Bases: TypedDict

Fields of POST /files that the shared upload does not hold.

Given to client.files.upload() as provider_options. Each key is a field of CreateFile with its type.

Attributes:

Name Type Description
purpose Literal['assistants', 'batch', 'fine-tune', 'vision', 'user_data', 'evals']

What the file is for; user_data, the purpose of files given to a model as input, when left out.

Example

await client.files.upload( ... Path("cat.png"), provider_options={"purpose": "vision"} ... )

OpenAIGenerationOptions

Bases: TypedDict

Fields of POST /responses that the shared request does not hold.

Given to client.generation.create() or stream() as provider_options; a key left out is not sent. Each key is a field of CreateResponse with its type, and the method checks the value.

Attributes:

Name Type Description
metadata Metadata | None

Up to 16 key-value pairs stored with the response.

reasoning OpenAIReasoningOptions

Reasoning settings besides the shared effort, such as {"summary": "auto"}.

store bool | None

Whether OpenAI keeps the response; None sends null.

previous_response_id str | None

The response this one continues.

temperature CreateResponseParamsTemperature | None

Sampling temperature, 0 to 2.

top_p CreateResponseParamsTopP | None

Nucleus sampling mass, 0 to 1.

include list[IncludeEnum] | None

Extra data to return, such as "reasoning.encrypted_content", which a stateless tool loop (store: False) needs to pass reasoning back.

max_tool_calls int | None

Most built-in tool calls in one response.

Example

await client.generation.create( ... model="gpt-5", input="Hi", provider_options={"store": False} ... )

OpenAIReasoningOptions

Bases: TypedDict

The parts of reasoning that the shared request does not set.

effort is the shared GenerationRequest.effort, so it is not here: the adapter merges these keys with it into one reasoning.

Attributes:

Name Type Description
summary Literal['auto', 'concise', 'detailed'] | None

Ask for a summary of the reasoning, which comes back as GenerationResponse.reasoning and ReasoningDeltaEvent.

context Literal['auto', 'current_turn', 'all_turns'] | None

Which earlier reasoning the model sees.

mode ReasoningModeEnum

The reasoning mode, such as standard or pro.

ResponseAudioDeltaEvent

Bases: BaseAPITypeExtra

Emitted when there is a partial audio response.

Attributes:

Name Type Description
type Annotated[Literal['response.audio.delta'], Field(description='The type of the event. Always `response.audio.delta`.')]

The type of the event. Always response.audio.delta.

sequence_number Annotated[int, Field(description='A sequence number for this chunk of the stream response.')]

A sequence number for this chunk of the stream response.

delta Annotated[str, Field(description='A chunk of Base64 encoded response audio bytes.')]

A chunk of Base64 encoded response audio bytes.

ResponseAudioDoneEvent

Bases: BaseAPITypeExtra

Emitted when the audio response is complete.

Attributes:

Name Type Description
type Annotated[Literal['response.audio.done'], Field(description='The type of the event. Always `response.audio.done`.')]

The type of the event. Always response.audio.done.

sequence_number Annotated[int, Field(description='The sequence number of the delta.')]

The sequence number of the delta.

ResponseAudioTranscriptDeltaEvent

Bases: BaseAPITypeExtra

Emitted when there is a partial transcript of audio.

Attributes:

Name Type Description
type Annotated[Literal['response.audio.transcript.delta'], Field(description='The type of the event. Always `response.audio.transcript.delta`.')]

The type of the event. Always response.audio.transcript.delta.

delta Annotated[str, Field(description='The partial transcript of the audio response.')]

The partial transcript of the audio response.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseAudioTranscriptDoneEvent

Bases: BaseAPITypeExtra

Emitted when the full audio transcript is completed.

Attributes:

Name Type Description
type Annotated[Literal['response.audio.transcript.done'], Field(description='The type of the event. Always `response.audio.transcript.done`.')]

The type of the event. Always response.audio.transcript.done.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseCodeInterpreterCallCodeDeltaEvent

Bases: BaseAPITypeExtra

ResponseCodeInterpreterCallCodeDeltaEvent from the OpenAI API.

Emitted when a partial code snippet is streamed by the code interpreter.

Attributes:

Name Type Description
type Annotated[Literal['response.code_interpreter_call_code.delta'], Field(description='The type of the event. Always `response.code_interpreter_call_code.delta`.')]

The type of the event. Always response.code_interpreter_call_code.delta.

output_index Annotated[int, Field(description='The index of the output item in the response for which the code is being streamed.')]

The index of the output item in the response for which the code is being streamed.

item_id Annotated[str, Field(description='The unique identifier of the code interpreter tool call item.')]

The unique identifier of the code interpreter tool call item.

delta Annotated[str, Field(description='The partial code snippet being streamed by the code interpreter.')]

The partial code snippet being streamed by the code interpreter.

sequence_number Annotated[int, Field(description='The sequence number of this event, used to order streaming events.')]

The sequence number of this event, used to order streaming events.

ResponseCodeInterpreterCallCodeDoneEvent

Bases: BaseAPITypeExtra

ResponseCodeInterpreterCallCodeDoneEvent from the OpenAI API.

Emitted when the code snippet is finalized by the code interpreter.

Attributes:

Name Type Description
type Annotated[Literal['response.code_interpreter_call_code.done'], Field(description='The type of the event. Always `response.code_interpreter_call_code.done`.')]

The type of the event. Always response.code_interpreter_call_code.done.

output_index Annotated[int, Field(description='The index of the output item in the response for which the code is finalized.')]

The index of the output item in the response for which the code is finalized.

item_id Annotated[str, Field(description='The unique identifier of the code interpreter tool call item.')]

The unique identifier of the code interpreter tool call item.

code Annotated[str, Field(description='The final code snippet output by the code interpreter.')]

The final code snippet output by the code interpreter.

sequence_number Annotated[int, Field(description='The sequence number of this event, used to order streaming events.')]

The sequence number of this event, used to order streaming events.

ResponseCodeInterpreterCallCompletedEvent

Bases: BaseAPITypeExtra

Emitted when the code interpreter call is completed.

Attributes:

Name Type Description
type Annotated[Literal['response.code_interpreter_call.completed'], Field(description='The type of the event. Always `response.code_interpreter_call.completed`.')]

The type of the event. Always response.code_interpreter_call.completed.

output_index Annotated[int, Field(description='The index of the output item in the response for which the code interpreter call is completed.')]

The index of the output item in the response for which the code interpreter call is completed.

item_id Annotated[str, Field(description='The unique identifier of the code interpreter tool call item.')]

The unique identifier of the code interpreter tool call item.

sequence_number Annotated[int, Field(description='The sequence number of this event, used to order streaming events.')]

The sequence number of this event, used to order streaming events.

ResponseCodeInterpreterCallInProgressEvent

Bases: BaseAPITypeExtra

Emitted when a code interpreter call is in progress.

Attributes:

Name Type Description
type Annotated[Literal['response.code_interpreter_call.in_progress'], Field(description='The type of the event. Always `response.code_interpreter_call.in_progress`.')]

The type of the event. Always response.code_interpreter_call.in_progress.

output_index Annotated[int, Field(description='The index of the output item in the response for which the code interpreter call is in progress.')]

The index of the output item in the response for which the code interpreter call is in progress.

item_id Annotated[str, Field(description='The unique identifier of the code interpreter tool call item.')]

The unique identifier of the code interpreter tool call item.

sequence_number Annotated[int, Field(description='The sequence number of this event, used to order streaming events.')]

The sequence number of this event, used to order streaming events.

ResponseCodeInterpreterCallInterpretingEvent

Bases: BaseAPITypeExtra

ResponseCodeInterpreterCallInterpretingEvent.

Emitted when the code interpreter is actively interpreting the code snippet.

Attributes:

Name Type Description
type Annotated[Literal['response.code_interpreter_call.interpreting'], Field(description='The type of the event. Always `response.code_interpreter_call.interpreting`.')]

The type of the event. Always response.code_interpreter_call.interpreting.

output_index Annotated[int, Field(description='The index of the output item in the response for which the code interpreter is interpreting code.')]

The index of the output item in the response for which the code interpreter is interpreting code.

item_id Annotated[str, Field(description='The unique identifier of the code interpreter tool call item.')]

The unique identifier of the code interpreter tool call item.

sequence_number Annotated[int, Field(description='The sequence number of this event, used to order streaming events.')]

The sequence number of this event, used to order streaming events.

ResponseCompactionCompactingStreamingEvent

Bases: BaseAPITypeExtra

ResponseCompactionCompactingStreamingEvent from the OpenAI API.

Emitted when new summary content is sampled for a compaction trigger. Contains no summary content.

Attributes:

Name Type Description
type Annotated[Literal['response.compaction.compacting'], Field(description='The type of the event, always `response.compaction.compacting`.')]

The type of the event, always response.compaction.compacting.

sequence_number Annotated[int, Field(description='The sequence number of the event that was emitted.')]

The sequence number of the event that was emitted.

output_index Annotated[int, Field(description='The index of the compaction output item.')]

The index of the compaction output item.

item_id Annotated[str, Field(description='The ID of the compaction output item.')]

The ID of the compaction output item.

ResponseCompletedEvent

Bases: BaseAPITypeExtra

Emitted when the model response is complete.

Attributes:

Name Type Description
type Annotated[Literal['response.completed'], Field(description='The type of the event. Always `response.completed`.')]

The type of the event. Always response.completed.

response Annotated[Response, Field(description='Properties of the completed response.')]

Properties of the completed response.

sequence_number Annotated[int, Field(description='The sequence number for this event.')]

The sequence number for this event.

ResponseContentPartAddedEvent

Bases: BaseAPITypeExtra

Emitted when a new content part is added.

Attributes:

Name Type Description
type Annotated[Literal['response.content_part.added'], Field(description='The type of the event. Always `response.content_part.added`.')]

The type of the event. Always response.content_part.added.

item_id Annotated[str, Field(description='The ID of the output item that the content part was added to.')]

The ID of the output item that the content part was added to.

output_index Annotated[int, Field(description='The index of the output item that the content part was added to.')]

The index of the output item that the content part was added to.

content_index Annotated[int, Field(description='The index of the content part that was added.')]

The index of the content part that was added.

part Annotated[OutputContent, Field(description='The content part that was added.')]

The content part that was added.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseContentPartDoneEvent

Bases: BaseAPITypeExtra

Emitted when a content part is done.

Attributes:

Name Type Description
type Annotated[Literal['response.content_part.done'], Field(description='The type of the event. Always `response.content_part.done`.')]

The type of the event. Always response.content_part.done.

item_id Annotated[str, Field(description='The ID of the output item that the content part was added to.')]

The ID of the output item that the content part was added to.

output_index Annotated[int, Field(description='The index of the output item that the content part was added to.')]

The index of the output item that the content part was added to.

content_index Annotated[int, Field(description='The index of the content part that is done.')]

The index of the content part that is done.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

part Annotated[OutputContent, Field(description='The content part that is done.')]

The content part that is done.

ResponseCreatedEvent

Bases: BaseAPITypeExtra

An event that is emitted when a response is created.

Attributes:

Name Type Description
type Annotated[Literal['response.created'], Field(description='The type of the event. Always `response.created`.')]

The type of the event. Always response.created.

response Annotated[Response, Field(description='The response that was created.')]

The response that was created.

sequence_number Annotated[int, Field(description='The sequence number for this event.')]

The sequence number for this event.

ResponseCustomToolCallInputDeltaEvent

Bases: BaseAPITypeExtra

ResponseCustomToolCallInputDeltaEvent from the OpenAI API.

Event representing a delta (partial update) to the input of a custom tool call.

Attributes:

Name Type Description
type Annotated[Literal['response.custom_tool_call_input.delta'], Field(description='The event type identifier.')]

The event type identifier.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

output_index Annotated[int, Field(description='The index of the output this delta applies to.')]

The index of the output this delta applies to.

item_id Annotated[str, Field(description='Unique identifier for the API item associated with this event.')]

Unique identifier for the API item associated with this event.

delta Annotated[str, Field(description='The incremental input data (delta) for the custom tool call.')]

The incremental input data (delta) for the custom tool call.

ResponseCustomToolCallInputDoneEvent

Bases: BaseAPITypeExtra

Event indicating that input for a custom tool call is complete.

Attributes:

Name Type Description
type Annotated[Literal['response.custom_tool_call_input.done'], Field(description='The event type identifier.')]

The event type identifier.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

output_index Annotated[int, Field(description='The index of the output this event applies to.')]

The index of the output this event applies to.

item_id Annotated[str, Field(description='Unique identifier for the API item associated with this event.')]

Unique identifier for the API item associated with this event.

input Annotated[str, Field(description='The complete input data for the custom tool call.')]

The complete input data for the custom tool call.

ResponseErrorEvent

Bases: BaseAPITypeExtra

Emitted when an error occurs.

Attributes:

Name Type Description
type Annotated[Literal['error'], Field(description='The type of the event. Always `error`.')]

The type of the event. Always error.

message Annotated[str, Field(description='The error message.')]

The error message.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseFailedEvent

Bases: BaseAPITypeExtra

An event that is emitted when a response fails.

Attributes:

Name Type Description
type Annotated[Literal['response.failed'], Field(description='The type of the event. Always `response.failed`.')]

The type of the event. Always response.failed.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

response Annotated[Response, Field(description='The response that failed.')]

The response that failed.

ResponseFileSearchCallCompletedEvent

Bases: BaseAPITypeExtra

Emitted when a file search call is completed (results found).

Attributes:

Name Type Description
type Annotated[Literal['response.file_search_call.completed'], Field(description='The type of the event. Always `response.file_search_call.completed`.')]

The type of the event. Always response.file_search_call.completed.

output_index Annotated[int, Field(description='The index of the output item that the file search call is initiated.')]

The index of the output item that the file search call is initiated.

item_id Annotated[str, Field(description='The ID of the output item that the file search call is initiated.')]

The ID of the output item that the file search call is initiated.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseFileSearchCallInProgressEvent

Bases: BaseAPITypeExtra

Emitted when a file search call is initiated.

Attributes:

Name Type Description
type Annotated[Literal['response.file_search_call.in_progress'], Field(description='The type of the event. Always `response.file_search_call.in_progress`.')]

The type of the event. Always response.file_search_call.in_progress.

output_index Annotated[int, Field(description='The index of the output item that the file search call is initiated.')]

The index of the output item that the file search call is initiated.

item_id Annotated[str, Field(description='The ID of the output item that the file search call is initiated.')]

The ID of the output item that the file search call is initiated.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseFileSearchCallSearchingEvent

Bases: BaseAPITypeExtra

Emitted when a file search is currently searching.

Attributes:

Name Type Description
type Annotated[Literal['response.file_search_call.searching'], Field(description='The type of the event. Always `response.file_search_call.searching`.')]

The type of the event. Always response.file_search_call.searching.

output_index Annotated[int, Field(description='The index of the output item that the file search call is searching.')]

The index of the output item that the file search call is searching.

item_id Annotated[str, Field(description='The ID of the output item that the file search call is initiated.')]

The ID of the output item that the file search call is initiated.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseFunctionCallArgumentsDeltaEvent

Bases: BaseAPITypeExtra

Emitted when there is a partial function-call arguments delta.

Attributes:

Name Type Description
type Annotated[Literal['response.function_call_arguments.delta'], Field(description='The type of the event. Always `response.function_call_arguments.delta`.')]

The type of the event. Always response.function_call_arguments.delta.

item_id Annotated[str, Field(description='The ID of the output item that the function-call arguments delta is added to.')]

The ID of the output item that the function-call arguments delta is added to.

output_index Annotated[int, Field(description='The index of the output item that the function-call arguments delta is added to.')]

The index of the output item that the function-call arguments delta is added to.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

delta Annotated[str, Field(description='The function-call arguments delta that is added.')]

The function-call arguments delta that is added.

ResponseFunctionCallArgumentsDoneEvent

Bases: BaseAPITypeExtra

Emitted when function-call arguments are finalized.

Attributes:

Name Type Description
item_id Annotated[str, Field(description='The ID of the item.')]

The ID of the item.

output_index Annotated[int, Field(description='The index of the output item.')]

The index of the output item.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

arguments Annotated[str, Field(description='The function-call arguments.')]

The function-call arguments.

ResponseImageGenCallCompletedEvent

Bases: BaseAPITypeExtra

ResponseImageGenCallCompletedEvent from the OpenAI API.

Emitted when an image generation tool call has completed and the final image is available.

Attributes:

Name Type Description
type Annotated[Literal['response.image_generation_call.completed'], Field(description="The type of the event. Always 'response.image_generation_call.completed'.")]

The type of the event. Always 'response.image_generation_call.completed'.

output_index Annotated[int, Field(description="The index of the output item in the response's output array.")]

The index of the output item in the response's output array.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

item_id Annotated[str, Field(description='The unique identifier of the image generation item being processed.')]

The unique identifier of the image generation item being processed.

ResponseImageGenCallGeneratingEvent

Bases: BaseAPITypeExtra

ResponseImageGenCallGeneratingEvent from the OpenAI API.

Emitted when an image generation tool call is actively generating an image (intermediate state).

Attributes:

Name Type Description
type Annotated[Literal['response.image_generation_call.generating'], Field(description="The type of the event. Always 'response.image_generation_call.generating'.")]

The type of the event. Always 'response.image_generation_call.generating'.

output_index Annotated[int, Field(description="The index of the output item in the response's output array.")]

The index of the output item in the response's output array.

item_id Annotated[str, Field(description='The unique identifier of the image generation item being processed.')]

The unique identifier of the image generation item being processed.

sequence_number Annotated[int, Field(description='The sequence number of the image generation item being processed.')]

The sequence number of the image generation item being processed.

ResponseImageGenCallInProgressEvent

Bases: BaseAPITypeExtra

Emitted when an image generation tool call is in progress.

Attributes:

Name Type Description
type Annotated[Literal['response.image_generation_call.in_progress'], Field(description="The type of the event. Always 'response.image_generation_call.in_progress'.")]

The type of the event. Always 'response.image_generation_call.in_progress'.

output_index Annotated[int, Field(description="The index of the output item in the response's output array.")]

The index of the output item in the response's output array.

item_id Annotated[str, Field(description='The unique identifier of the image generation item being processed.')]

The unique identifier of the image generation item being processed.

sequence_number Annotated[int, Field(description='The sequence number of the image generation item being processed.')]

The sequence number of the image generation item being processed.

ResponseImageGenCallPartialImageEvent

Bases: BaseAPITypeExtra

ResponseImageGenCallPartialImageEvent from the OpenAI API.

Emitted when a partial image is available during image generation streaming.

Attributes:

Name Type Description
type Annotated[Literal['response.image_generation_call.partial_image'], Field(description="The type of the event. Always 'response.image_generation_call.partial_image'.")]

The type of the event. Always 'response.image_generation_call.partial_image'.

output_index Annotated[int, Field(description="The index of the output item in the response's output array.")]

The index of the output item in the response's output array.

item_id Annotated[str, Field(description='The unique identifier of the image generation item being processed.')]

The unique identifier of the image generation item being processed.

sequence_number Annotated[int, Field(description='The sequence number of the image generation item being processed.')]

The sequence number of the image generation item being processed.

partial_image_index Annotated[int, Field(description='0-based index for the partial image (backend is 1-based, but this is 0-based for the user).')]

0-based index for the partial image (backend is 1-based, but this is 0-based for the user).

partial_image_b64 Annotated[str, Field(description='Base64-encoded partial image data, suitable for rendering as an image.')]

Base64-encoded partial image data, suitable for rendering as an image.

size Annotated[str | None, Field(description='The image size that was used.')]

The image size that was used.

quality Annotated[str | None, Field(description='The image quality that was used.')]

The image quality that was used.

background Annotated[str | None, Field(description='The background setting that was used.')]

The background setting that was used.

output_format Annotated[str | None, Field(description='The output format that was used.')]

The output format that was used.

ResponseIncompleteEvent

Bases: BaseAPITypeExtra

An event that is emitted when a response finishes as incomplete.

Over WebSocket, steering can finish a response with response.incomplete_details.reason set to steered, followed automatically by a successor response.created that commits the queued steering input.

Attributes:

Name Type Description
type Annotated[Literal['response.incomplete'], Field(description='The type of the event. Always `response.incomplete`.')]

The type of the event. Always response.incomplete.

response Annotated[Response, Field(description='The response that was incomplete.')]

The response that was incomplete.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseInProgressEvent

Bases: BaseAPITypeExtra

Emitted when the response is in progress.

Attributes:

Name Type Description
type Annotated[Literal['response.in_progress'], Field(description='The type of the event. Always `response.in_progress`.')]

The type of the event. Always response.in_progress.

response Annotated[Response, Field(description='The response that is in progress.')]

The response that is in progress.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseMCPCallArgumentsDeltaEvent

Bases: BaseAPITypeExtra

ResponseMCPCallArgumentsDeltaEvent from the OpenAI API.

Emitted when there is a delta (partial update) to the arguments of an MCP tool call.

Attributes:

Name Type Description
type Annotated[Literal['response.mcp_call_arguments.delta'], Field(description="The type of the event. Always 'response.mcp_call_arguments.delta'.")]

The type of the event. Always 'response.mcp_call_arguments.delta'.

output_index Annotated[int, Field(description="The index of the output item in the response's output array.")]

The index of the output item in the response's output array.

item_id Annotated[str, Field(description='The unique identifier of the MCP tool call item being processed.')]

The unique identifier of the MCP tool call item being processed.

delta Annotated[str, Field(description='A JSON string containing the partial update to the arguments for the MCP tool call.')]

A JSON string containing the partial update to the arguments for the MCP tool call.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseMCPCallArgumentsDoneEvent

Bases: BaseAPITypeExtra

Emitted when the arguments for an MCP tool call are finalized.

Attributes:

Name Type Description
type Annotated[Literal['response.mcp_call_arguments.done'], Field(description="The type of the event. Always 'response.mcp_call_arguments.done'.")]

The type of the event. Always 'response.mcp_call_arguments.done'.

output_index Annotated[int, Field(description="The index of the output item in the response's output array.")]

The index of the output item in the response's output array.

item_id Annotated[str, Field(description='The unique identifier of the MCP tool call item being processed.')]

The unique identifier of the MCP tool call item being processed.

arguments Annotated[str, Field(description='A JSON string containing the finalized arguments for the MCP tool call.')]

A JSON string containing the finalized arguments for the MCP tool call.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseMCPCallCompletedEvent

Bases: BaseAPITypeExtra

Emitted when an MCP tool call has completed successfully.

Attributes:

Name Type Description
type Annotated[Literal['response.mcp_call.completed'], Field(description="The type of the event. Always 'response.mcp_call.completed'.")]

The type of the event. Always 'response.mcp_call.completed'.

item_id Annotated[str, Field(description='The ID of the MCP tool call item that completed.')]

The ID of the MCP tool call item that completed.

output_index Annotated[int, Field(description='The index of the output item that completed.')]

The index of the output item that completed.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseMCPCallFailedEvent

Bases: BaseAPITypeExtra

Emitted when an MCP tool call has failed.

Attributes:

Name Type Description
type Annotated[Literal['response.mcp_call.failed'], Field(description="The type of the event. Always 'response.mcp_call.failed'.")]

The type of the event. Always 'response.mcp_call.failed'.

item_id Annotated[str, Field(description='The ID of the MCP tool call item that failed.')]

The ID of the MCP tool call item that failed.

output_index Annotated[int, Field(description='The index of the output item that failed.')]

The index of the output item that failed.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseMCPCallInProgressEvent

Bases: BaseAPITypeExtra

Emitted when an MCP tool call is in progress.

Attributes:

Name Type Description
type Annotated[Literal['response.mcp_call.in_progress'], Field(description="The type of the event. Always 'response.mcp_call.in_progress'.")]

The type of the event. Always 'response.mcp_call.in_progress'.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

output_index Annotated[int, Field(description="The index of the output item in the response's output array.")]

The index of the output item in the response's output array.

item_id Annotated[str, Field(description='The unique identifier of the MCP tool call item being processed.')]

The unique identifier of the MCP tool call item being processed.

ResponseMCPListToolsCompletedEvent

Bases: BaseAPITypeExtra

ResponseMCPListToolsCompletedEvent from the OpenAI API.

Emitted when the list of available MCP tools has been successfully retrieved.

Attributes:

Name Type Description
type Annotated[Literal['response.mcp_list_tools.completed'], Field(description="The type of the event. Always 'response.mcp_list_tools.completed'.")]

The type of the event. Always 'response.mcp_list_tools.completed'.

item_id Annotated[str, Field(description='The ID of the MCP tool call item that produced this output.')]

The ID of the MCP tool call item that produced this output.

output_index Annotated[int, Field(description='The index of the output item that was processed.')]

The index of the output item that was processed.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseMCPListToolsFailedEvent

Bases: BaseAPITypeExtra

Emitted when the attempt to list available MCP tools has failed.

Attributes:

Name Type Description
type Annotated[Literal['response.mcp_list_tools.failed'], Field(description="The type of the event. Always 'response.mcp_list_tools.failed'.")]

The type of the event. Always 'response.mcp_list_tools.failed'.

item_id Annotated[str, Field(description='The ID of the MCP tool call item that failed.')]

The ID of the MCP tool call item that failed.

output_index Annotated[int, Field(description='The index of the output item that failed.')]

The index of the output item that failed.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseMCPListToolsInProgressEvent

Bases: BaseAPITypeExtra

ResponseMCPListToolsInProgressEvent from the OpenAI API.

Emitted when the system is in the process of retrieving the list of available MCP tools.

Attributes:

Name Type Description
type Annotated[Literal['response.mcp_list_tools.in_progress'], Field(description="The type of the event. Always 'response.mcp_list_tools.in_progress'.")]

The type of the event. Always 'response.mcp_list_tools.in_progress'.

item_id Annotated[str, Field(description='The ID of the MCP tool call item that is being processed.')]

The ID of the MCP tool call item that is being processed.

output_index Annotated[int, Field(description='The index of the output item that is being processed.')]

The index of the output item that is being processed.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseOutputItemAddedEvent

Bases: BaseAPITypeExtra

Emitted when a new output item is added.

Attributes:

Name Type Description
type Annotated[Literal['response.output_item.added'], Field(description='The type of the event. Always `response.output_item.added`.')]

The type of the event. Always response.output_item.added.

output_index Annotated[int, Field(description='The index of the output item that was added.')]

The index of the output item that was added.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

item Annotated[OutputItem, Field(description='The output item that was added. For reasoning items, `encrypted_content`\nmay be incomplete while the item is in progress. Use the reasoning item\nfrom the corresponding `response.output_item.done` event when passing it\nas input to a subsequent request.')]

The output item that was added. For reasoning items, encrypted_content may be incomplete while the item is in progress. Use the reasoning item from the corresponding response.output_item.done event when passing it as input to a subsequent request.

ResponseOutputItemDoneEvent

Bases: BaseAPITypeExtra

Emitted when an output item is marked done.

Attributes:

Name Type Description
type Annotated[Literal['response.output_item.done'], Field(description='The type of the event. Always `response.output_item.done`.')]

The type of the event. Always response.output_item.done.

output_index Annotated[int, Field(description='The index of the output item that was marked done.')]

The index of the output item that was marked done.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

item Annotated[OutputItem, Field(description='The output item that was marked done.')]

The output item that was marked done.

ResponseOutputTextAnnotationAddedEvent

Bases: BaseAPITypeExtra

Emitted when an annotation is added to output text content.

Attributes:

Name Type Description
type Annotated[Literal['response.output_text.annotation.added'], Field(description="The type of the event. Always 'response.output_text.annotation.added'.")]

The type of the event. Always 'response.output_text.annotation.added'.

item_id Annotated[str, Field(description='The unique identifier of the item to which the annotation is being added.')]

The unique identifier of the item to which the annotation is being added.

output_index Annotated[int, Field(description="The index of the output item in the response's output array.")]

The index of the output item in the response's output array.

content_index Annotated[int, Field(description='The index of the content part within the output item.')]

The index of the content part within the output item.

annotation_index Annotated[int, Field(description='The index of the annotation within the content part.')]

The index of the annotation within the content part.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

annotation Annotated[Annotation | None, Field(description='The annotation object being added. (See annotation schema for details.)')]

The annotation object being added. (See annotation schema for details.)

ResponseQueuedEvent

Bases: BaseAPITypeExtra

Emitted when a response is queued and waiting to be processed.

Attributes:

Name Type Description
type Annotated[Literal['response.queued'], Field(description="The type of the event. Always 'response.queued'.")]

The type of the event. Always 'response.queued'.

response Annotated[Response, Field(description='The full response object that is queued.')]

The full response object that is queued.

sequence_number Annotated[int, Field(description='The sequence number for this event.')]

The sequence number for this event.

ResponseReasoningSummaryPartAddedEvent

Bases: BaseAPITypeExtra

Emitted when a new reasoning summary part is added.

Attributes:

Name Type Description
type Annotated[Literal['response.reasoning_summary_part.added'], Field(description='The type of the event. Always `response.reasoning_summary_part.added`.')]

The type of the event. Always response.reasoning_summary_part.added.

item_id Annotated[str, Field(description='The ID of the item this summary part is associated with.')]

The ID of the item this summary part is associated with.

output_index Annotated[int, Field(description='The index of the output item this summary part is associated with.')]

The index of the output item this summary part is associated with.

summary_index Annotated[int, Field(description='The index of the summary part within the reasoning summary.')]

The index of the summary part within the reasoning summary.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

part Annotated[ResponseReasoningSummaryPartAddedEventPart, Field(description='The summary part that was added.')]

The summary part that was added.

ResponseReasoningSummaryPartDoneEvent

Bases: BaseAPITypeExtra

Emitted when a reasoning summary part is completed.

Attributes:

Name Type Description
type Annotated[Literal['response.reasoning_summary_part.done'], Field(description='The type of the event. Always `response.reasoning_summary_part.done`.')]

The type of the event. Always response.reasoning_summary_part.done.

item_id Annotated[str, Field(description='The ID of the item this summary part is associated with.')]

The ID of the item this summary part is associated with.

output_index Annotated[int, Field(description='The index of the output item this summary part is associated with.')]

The index of the output item this summary part is associated with.

summary_index Annotated[int, Field(description='The index of the summary part within the reasoning summary.')]

The index of the summary part within the reasoning summary.

status Annotated[str | None, Field(description='The completion status of the summary part. Omitted when the part completed\nnormally and set to `incomplete` when generation was interrupted.')]

The completion status of the summary part. Omitted when the part completed normally and set to incomplete when generation was interrupted.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

part Annotated[ResponseReasoningSummaryPartDoneEventPart, Field(description='The completed summary part.')]

The completed summary part.

ResponseReasoningSummaryTextDeltaEvent

Bases: BaseAPITypeExtra

Emitted when a delta is added to a reasoning summary text.

Attributes:

Name Type Description
type Annotated[Literal['response.reasoning_summary_text.delta'], Field(description='The type of the event. Always `response.reasoning_summary_text.delta`.')]

The type of the event. Always response.reasoning_summary_text.delta.

item_id Annotated[str, Field(description='The ID of the item this summary text delta is associated with.')]

The ID of the item this summary text delta is associated with.

output_index Annotated[int, Field(description='The index of the output item this summary text delta is associated with.')]

The index of the output item this summary text delta is associated with.

summary_index Annotated[int, Field(description='The index of the summary part within the reasoning summary.')]

The index of the summary part within the reasoning summary.

delta Annotated[str, Field(description='The text delta that was added to the summary.')]

The text delta that was added to the summary.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseReasoningSummaryTextDoneEvent

Bases: BaseAPITypeExtra

Emitted when a reasoning summary text is completed.

Attributes:

Name Type Description
type Annotated[Literal['response.reasoning_summary_text.done'], Field(description='The type of the event. Always `response.reasoning_summary_text.done`.')]

The type of the event. Always response.reasoning_summary_text.done.

item_id Annotated[str, Field(description='The ID of the item this summary text is associated with.')]

The ID of the item this summary text is associated with.

output_index Annotated[int, Field(description='The index of the output item this summary text is associated with.')]

The index of the output item this summary text is associated with.

summary_index Annotated[int, Field(description='The index of the summary part within the reasoning summary.')]

The index of the summary part within the reasoning summary.

text Annotated[str, Field(description='The full text of the completed reasoning summary.')]

The full text of the completed reasoning summary.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseReasoningTextDeltaEvent

Bases: BaseAPITypeExtra

Emitted when a delta is added to a reasoning text.

Attributes:

Name Type Description
type Annotated[Literal['response.reasoning_text.delta'], Field(description='The type of the event. Always `response.reasoning_text.delta`.')]

The type of the event. Always response.reasoning_text.delta.

item_id Annotated[str, Field(description='The ID of the item this reasoning text delta is associated with.')]

The ID of the item this reasoning text delta is associated with.

output_index Annotated[int, Field(description='The index of the output item this reasoning text delta is associated with.')]

The index of the output item this reasoning text delta is associated with.

content_index Annotated[int, Field(description='The index of the reasoning content part this delta is associated with.')]

The index of the reasoning content part this delta is associated with.

delta Annotated[str, Field(description='The text delta that was added to the reasoning content.')]

The text delta that was added to the reasoning content.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseReasoningTextDoneEvent

Bases: BaseAPITypeExtra

Emitted when a reasoning text is completed.

Attributes:

Name Type Description
type Annotated[Literal['response.reasoning_text.done'], Field(description='The type of the event. Always `response.reasoning_text.done`.')]

The type of the event. Always response.reasoning_text.done.

item_id Annotated[str, Field(description='The ID of the item this reasoning text is associated with.')]

The ID of the item this reasoning text is associated with.

output_index Annotated[int, Field(description='The index of the output item this reasoning text is associated with.')]

The index of the output item this reasoning text is associated with.

content_index Annotated[int, Field(description='The index of the reasoning content part.')]

The index of the reasoning content part.

text Annotated[str, Field(description='The full text of the completed reasoning content.')]

The full text of the completed reasoning content.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseRefusalDeltaEvent

Bases: BaseAPITypeExtra

Emitted when there is a partial refusal text.

Attributes:

Name Type Description
type Annotated[Literal['response.refusal.delta'], Field(description='The type of the event. Always `response.refusal.delta`.')]

The type of the event. Always response.refusal.delta.

item_id Annotated[str, Field(description='The ID of the output item that the refusal text is added to.')]

The ID of the output item that the refusal text is added to.

output_index Annotated[int, Field(description='The index of the output item that the refusal text is added to.')]

The index of the output item that the refusal text is added to.

content_index Annotated[int, Field(description='The index of the content part that the refusal text is added to.')]

The index of the content part that the refusal text is added to.

delta Annotated[str, Field(description='The refusal text that is added.')]

The refusal text that is added.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseRefusalDoneEvent

Bases: BaseAPITypeExtra

Emitted when refusal text is finalized.

Attributes:

Name Type Description
type Annotated[Literal['response.refusal.done'], Field(description='The type of the event. Always `response.refusal.done`.')]

The type of the event. Always response.refusal.done.

item_id Annotated[str, Field(description='The ID of the output item that the refusal text is finalized.')]

The ID of the output item that the refusal text is finalized.

output_index Annotated[int, Field(description='The index of the output item that the refusal text is finalized.')]

The index of the output item that the refusal text is finalized.

content_index Annotated[int, Field(description='The index of the content part that the refusal text is finalized.')]

The index of the content part that the refusal text is finalized.

refusal Annotated[str, Field(description='The refusal text that is finalized.')]

The refusal text that is finalized.

sequence_number Annotated[int, Field(description='The sequence number of this event.')]

The sequence number of this event.

ResponseShellCallCommandAddedStreamingEvent

Bases: BaseAPITypeExtra

ResponseShellCallCommandAddedStreamingEvent.

A streaming event that indicated a shell command was added to a tool call.

Attributes:

Name Type Description
type Annotated[Literal['response.shell_call_command.added'], Field(description='The type of the event, always `response.shell_call_command.added`.')]

The type of the event, always response.shell_call_command.added.

sequence_number Annotated[int, Field(description='The sequence number of the event that was emitted.')]

The sequence number of the event that was emitted.

output_index Annotated[int, Field(description='The index of the output item that was updated.')]

The index of the output item that was updated.

command_index Annotated[int, Field(description='The index of the shell command that was added.')]

The index of the shell command that was added.

command Annotated[str, Field(description='The shell command that was added.')]

The shell command that was added.

ResponseShellCallCommandDeltaStreamingEvent

Bases: BaseAPITypeExtra

ResponseShellCallCommandDeltaStreamingEvent.

A streaming event that indicated a shell command was incrementally updated.

Attributes:

Name Type Description
type Annotated[Literal['response.shell_call_command.delta'], Field(description='The type of the event, always `response.shell_call_command.delta`.')]

The type of the event, always response.shell_call_command.delta.

sequence_number Annotated[int, Field(description='The sequence number of the event that was emitted.')]

The sequence number of the event that was emitted.

output_index Annotated[int, Field(description='The index of the output item that was updated.')]

The index of the output item that was updated.

command_index Annotated[int, Field(description='The index of the shell command that was updated.')]

The index of the shell command that was updated.

delta Annotated[str, Field(description='The shell command delta that was appended.')]

The shell command delta that was appended.

obfuscation Annotated[str | None, Field(description='An obfuscation string that was added to pad the event payload.')]

An obfuscation string that was added to pad the event payload.

ResponseShellCallCommandDoneStreamingEvent

Bases: BaseAPITypeExtra

A streaming event that indicated a shell command was completed.

Attributes:

Name Type Description
type Annotated[Literal['response.shell_call_command.done'], Field(description='The type of the event, always `response.shell_call_command.done`.')]

The type of the event, always response.shell_call_command.done.

sequence_number Annotated[int, Field(description='The sequence number of the event that was emitted.')]

The sequence number of the event that was emitted.

output_index Annotated[int, Field(description='The index of the output item that was updated.')]

The index of the output item that was updated.

command_index Annotated[int, Field(description='The index of the shell command that was completed.')]

The index of the shell command that was completed.

command Annotated[str, Field(description='The final shell command that was emitted.')]

The final shell command that was emitted.

ResponseShellCallOutputContentDeltaStreamingEvent

Bases: BaseAPITypeExtra

ResponseShellCallOutputContentDeltaStreamingEvent.

A streaming event that indicated shell call output was incrementally added.

Attributes:

Name Type Description
type Annotated[Literal['response.shell_call_output_content.delta'], Field(description='The type of the event, always `response.shell_call_output_content.delta`.')]

The type of the event, always response.shell_call_output_content.delta.

sequence_number Annotated[int, Field(description='The sequence number of the event that was emitted.')]

The sequence number of the event that was emitted.

item_id Annotated[str, Field(description='The ID of the output item that was updated.')]

The ID of the output item that was updated.

output_index Annotated[int, Field(description='The index of the output item that was updated.')]

The index of the output item that was updated.

command_index Annotated[int, Field(description='The index of the shell command that produced output.')]

The index of the shell command that produced output.

delta Annotated[ShellCallOutputDelta, Field(description='The stdout/stderr delta that was emitted.')]

The stdout/stderr delta that was emitted.

ResponseShellCallOutputContentDoneStreamingEvent

Bases: BaseAPITypeExtra

A streaming event that indicated shell call output was completed.

Attributes:

Name Type Description
type Annotated[Literal['response.shell_call_output_content.done'], Field(description='The type of the event, always `response.shell_call_output_content.done`.')]

The type of the event, always response.shell_call_output_content.done.

sequence_number Annotated[int, Field(description='The sequence number of the event that was emitted.')]

The sequence number of the event that was emitted.

item_id Annotated[str, Field(description='The ID of the output item that was updated.')]

The ID of the output item that was updated.

output_index Annotated[int, Field(description='The index of the output item that was updated.')]

The index of the output item that was updated.

command_index Annotated[int, Field(description='The index of the shell command that produced output.')]

The index of the shell command that produced output.

output Annotated[list[FunctionShellCallOutputContent], Field(description='The output contents emitted for the shell command.')]

The output contents emitted for the shell command.

ResponseTextDeltaEvent

Bases: BaseAPITypeExtra

Emitted when there is an additional text delta.

Attributes:

Name Type Description
type Annotated[Literal['response.output_text.delta'], Field(description='The type of the event. Always `response.output_text.delta`.')]

The type of the event. Always response.output_text.delta.

item_id Annotated[str, Field(description='The ID of the output item that the text delta was added to.')]

The ID of the output item that the text delta was added to.

output_index Annotated[int, Field(description='The index of the output item that the text delta was added to.')]

The index of the output item that the text delta was added to.

content_index Annotated[int, Field(description='The index of the content part that the text delta was added to.')]

The index of the content part that the text delta was added to.

delta Annotated[str, Field(description='The text delta that was added.')]

The text delta that was added.

sequence_number Annotated[int, Field(description='The sequence number for this event.')]

The sequence number for this event.

logprobs Annotated[list[ResponseLogProb], Field(description='The log probabilities of the tokens in the delta.')]

The log probabilities of the tokens in the delta.

ResponseTextDoneEvent

Bases: BaseAPITypeExtra

Emitted when text content is finalized.

Attributes:

Name Type Description
type Annotated[Literal['response.output_text.done'], Field(description='The type of the event. Always `response.output_text.done`.')]

The type of the event. Always response.output_text.done.

item_id Annotated[str, Field(description='The ID of the output item that the text content is finalized.')]

The ID of the output item that the text content is finalized.

output_index Annotated[int, Field(description='The index of the output item that the text content is finalized.')]

The index of the output item that the text content is finalized.

content_index Annotated[int, Field(description='The index of the content part that the text content is finalized.')]

The index of the content part that the text content is finalized.

text Annotated[str, Field(description='The text content that is finalized.')]

The text content that is finalized.

sequence_number Annotated[int, Field(description='The sequence number for this event.')]

The sequence number for this event.

logprobs Annotated[list[ResponseLogProb], Field(description='The log probabilities of the tokens in the delta.')]

The log probabilities of the tokens in the delta.

ResponseWebSearchCallCompletedEvent

Bases: BaseAPITypeExtra

Emitted when a web search call is completed.

Attributes:

Name Type Description
type Annotated[Literal['response.web_search_call.completed'], Field(description='The type of the event. Always `response.web_search_call.completed`.')]

The type of the event. Always response.web_search_call.completed.

output_index Annotated[int, Field(description='The index of the output item that the web search call is associated with.')]

The index of the output item that the web search call is associated with.

item_id Annotated[str, Field(description='Unique ID for the output item associated with the web search call.')]

Unique ID for the output item associated with the web search call.

sequence_number Annotated[int, Field(description='The sequence number of the web search call being processed.')]

The sequence number of the web search call being processed.

ResponseWebSearchCallInProgressEvent

Bases: BaseAPITypeExtra

Emitted when a web search call is initiated.

Attributes:

Name Type Description
type Annotated[Literal['response.web_search_call.in_progress'], Field(description='The type of the event. Always `response.web_search_call.in_progress`.')]

The type of the event. Always response.web_search_call.in_progress.

output_index Annotated[int, Field(description='The index of the output item that the web search call is associated with.')]

The index of the output item that the web search call is associated with.

item_id Annotated[str, Field(description='Unique ID for the output item associated with the web search call.')]

Unique ID for the output item associated with the web search call.

sequence_number Annotated[int, Field(description='The sequence number of the web search call being processed.')]

The sequence number of the web search call being processed.

ResponseWebSearchCallSearchingEvent

Bases: BaseAPITypeExtra

Emitted when a web search call is executing.

Attributes:

Name Type Description
type Annotated[Literal['response.web_search_call.searching'], Field(description='The type of the event. Always `response.web_search_call.searching`.')]

The type of the event. Always response.web_search_call.searching.

output_index Annotated[int, Field(description='The index of the output item that the web search call is associated with.')]

The index of the output item that the web search call is associated with.

item_id Annotated[str, Field(description='Unique ID for the output item associated with the web search call.')]

Unique ID for the output item associated with the web search call.

sequence_number Annotated[int, Field(description='The sequence number of the web search call being processed.')]

The sequence number of the web search call being processed.

ShellCallOutputDelta

Bases: BaseAPITypeExtra

A delta of stdout/stderr emitted while a shell call was running.

Attributes:

Name Type Description
stdout Annotated[str | None, Field(description='The stdout delta that was emitted.')]

The stdout delta that was emitted.

stderr Annotated[str | None, Field(description='The stderr delta that was emitted.')]

The stderr delta that was emitted.

ApplyPatchCreateFileOperation

Bases: BaseAPITypeExtra

ApplyPatchCreateFileOperation from the OpenAI API.

Instruction describing how to create a file via the apply_patch tool.

Attributes:

Name Type Description
type Annotated[Literal['create_file'], Field(description='Create a new file with the provided diff.')]

Create a new file with the provided diff.

path Annotated[str, Field(description='Path of the file to create.')]

Path of the file to create.

diff Annotated[str, Field(description='Diff to apply.')]

Diff to apply.

ApplyPatchCreateFileOperationParam

Bases: BaseAPITypeExtra

Instruction for creating a new file via the apply_patch tool.

Attributes:

Name Type Description
type Annotated[Literal['create_file'], Field(description='The operation type. Always `create_file`.')]

The operation type. Always create_file.

path Annotated[str, Field(description='Path of the file to create relative to the workspace root.', min_length=1)]

Path of the file to create relative to the workspace root.

diff Annotated[str, Field(description='Unified diff content to apply when creating the file.', max_length=10485760)]

Unified diff content to apply when creating the file.

ApplyPatchDeleteFileOperation

Bases: BaseAPITypeExtra

ApplyPatchDeleteFileOperation from the OpenAI API.

Instruction describing how to delete a file via the apply_patch tool.

Attributes:

Name Type Description
type Annotated[Literal['delete_file'], Field(description='Delete the specified file.')]

Delete the specified file.

path Annotated[str, Field(description='Path of the file to delete.')]

Path of the file to delete.

ApplyPatchDeleteFileOperationParam

Bases: BaseAPITypeExtra

ApplyPatchDeleteFileOperationParam from the OpenAI API.

Instruction for deleting an existing file via the apply_patch tool.

Attributes:

Name Type Description
type Annotated[Literal['delete_file'], Field(description='The operation type. Always `delete_file`.')]

The operation type. Always delete_file.

path Annotated[str, Field(description='Path of the file to delete relative to the workspace root.', min_length=1)]

Path of the file to delete relative to the workspace root.

ApplyPatchUpdateFileOperation

Bases: BaseAPITypeExtra

ApplyPatchUpdateFileOperation from the OpenAI API.

Instruction describing how to update a file via the apply_patch tool.

Attributes:

Name Type Description
type Annotated[Literal['update_file'], Field(description='Update an existing file with the provided diff.')]

Update an existing file with the provided diff.

path Annotated[str, Field(description='Path of the file to update.')]

Path of the file to update.

diff Annotated[str, Field(description='Diff to apply.')]

Diff to apply.

ApplyPatchUpdateFileOperationParam

Bases: BaseAPITypeExtra

ApplyPatchUpdateFileOperationParam from the OpenAI API.

Instruction for updating an existing file via the apply_patch tool.

Attributes:

Name Type Description
type Annotated[Literal['update_file'], Field(description='The operation type. Always `update_file`.')]

The operation type. Always update_file.

path Annotated[str, Field(description='Path of the file to update relative to the workspace root.', min_length=1)]

Path of the file to update relative to the workspace root.

diff Annotated[str, Field(description='Unified diff content to apply to the existing file.', max_length=10485760)]

Unified diff content to apply to the existing file.

ContainerFileCitationBody

Bases: BaseAPITypeExtra

ContainerFileCitationBody from the OpenAI API.

A citation for a container file used to generate a model response.

Attributes:

Name Type Description
type Annotated[Literal['container_file_citation'], Field(description='The type of the container file citation. Always `container_file_citation`.')]

The type of the container file citation. Always container_file_citation.

container_id Annotated[str, Field(description='The ID of the container file.')]

The ID of the container file.

file_id Annotated[str, Field(description='The ID of the file.')]

The ID of the file.

start_index Annotated[int, Field(description='The index of the first character of the container file citation in the message.')]

The index of the first character of the container file citation in the message.

end_index Annotated[int, Field(description='The index of the last character of the container file citation in the message.')]

The index of the last character of the container file citation in the message.

filename Annotated[str, Field(description='The filename of the container file cited.')]

The filename of the container file cited.

DeleteFileResponse

Bases: BaseAPITypeExtra

DeleteFileResponse from the OpenAI API.

FileCitationBody

Bases: BaseAPITypeExtra

A citation to a file.

Attributes:

Name Type Description
type Annotated[Literal['file_citation'], Field(description='The type of the file citation. Always `file_citation`.')]

The type of the file citation. Always file_citation.

file_id Annotated[str, Field(description='The ID of the file.')]

The ID of the file.

index Annotated[int, Field(description='The index in the output text at which to insert the file citation.')]

The index in the output text at which to insert the file citation.

filename Annotated[str, Field(description='The filename of the file cited.')]

The filename of the file cited.

FilePath

Bases: BaseAPITypeExtra

A path to a file.

Attributes:

Name Type Description
type Annotated[Literal['file_path'], Field(description='The type of the file path. Always `file_path`.')]

The type of the file path. Always file_path.

file_id Annotated[str, Field(description='The ID of the file.')]

The ID of the file.

index Annotated[int, Field(description='The index of the file in the list of files.')]

The index of the file in the list of files.

ListFilesResponse

Bases: BaseAPITypeExtra

ListFilesResponse from the OpenAI API.

Attributes:

Name Type Description
data list[OpenAIFile]

The File object represents a document that has been uploaded to OpenAI.

OpenAIFile

Bases: BaseAPITypeExtra

OpenAIFile from the OpenAI API (upstream: OpenAIFile).

The File object represents a document that has been uploaded to OpenAI.

Attributes:

Name Type Description
id Annotated[str, Field(description='The file identifier, which can be referenced in the API endpoints.')]

The file identifier, which can be referenced in the API endpoints.

bytes Annotated[int | None, Field(description='The size of the file, in bytes. In a completed file upload response, this can\nbe null when the file size is not yet available.')]

The size of the file, in bytes. In a completed file upload response, this can be null when the file size is not yet available.

created_at Annotated[int, Field(description='The Unix timestamp (in seconds) for when the file was created.')]

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

expires_at Annotated[int | None, Field(description='The Unix timestamp (in seconds) for when the file will expire. In a\ncompleted file upload response, this can be null when no expiry is set.')]

The Unix timestamp (in seconds) for when the file will expire. In a completed file upload response, this can be null when no expiry is set.

filename Annotated[str, Field(description='The name of the file.')]

The name of the file.

object Annotated[Literal['file'], Field(description='The object type, which is always `file`.')]

The object type, which is always file.

purpose Annotated[str, Field(description='The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.')]

The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.

status Annotated[str, Field(deprecated=True, description='Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.')]

Deprecated. The current status of the file, which can be either uploaded, processed, or error.

status_details Annotated[str | None, Field(deprecated=True, description='Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`. Completed file upload responses can return null when these details are unset.')]

Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job. Completed file upload responses can return null when these details are unset.

CodeInterpreterOutputImage

Bases: BaseAPITypeExtra

The image output from the code interpreter.

Attributes:

Name Type Description
type Annotated[Literal['image'], Field(description='The type of the output. Always `image`.')]

The type of the output. Always image.

url Annotated[AnyUrl, Field(description='The URL of the image output from the code interpreter.')]

The URL of the image output from the code interpreter.

ComputerScreenshotImage

Bases: BaseAPITypeExtra

A computer screenshot image used with the computer use tool.

Attributes:

Name Type Description
type Annotated[Literal['computer_screenshot'], Field(description='Specifies the event type. For a computer screenshot, this property is \nalways set to `computer_screenshot`.')]

Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot.

image_url Annotated[AnyUrl | None, Field(description='The URL of the screenshot image.')]

The URL of the screenshot image.

file_id Annotated[str | None, Field(description='The identifier of an uploaded file that contains the screenshot.')]

The identifier of an uploaded file that contains the screenshot.

ImageGenOutputTokensDetails

Bases: BaseAPITypeExtra

The output token details for the image generation.

Attributes:

Name Type Description
image_tokens Annotated[int, Field(description='The number of image output tokens generated by the model.')]

The number of image output tokens generated by the model.

text_tokens Annotated[int, Field(description='The number of text output tokens generated by the model.')]

The number of text output tokens generated by the model.

ResolvedImageOptions

Bases: BaseAPITypeExtra

ResolvedImageOptions from the OpenAI API.

Attributes:

Name Type Description
context_compression Annotated[ResolvedImageContextCompressionEnum, Field(description='Effective image context optimization policy.')]

Effective image context optimization policy.

FunctionShellCallOutputExitOutcome

Bases: BaseAPITypeExtra

FunctionShellCallOutputExitOutcome from the OpenAI API.

Indicates that the shell commands finished and returned an exit code.

Attributes:

Name Type Description
type Annotated[Literal['exit'], Field(description='The outcome type. Always `exit`.')]

The outcome type. Always exit.

exit_code Annotated[int, Field(description='Exit code from the shell process.')]

Exit code from the shell process.

FunctionShellCallOutputExitOutcomeParam

Bases: BaseAPITypeExtra

FunctionShellCallOutputExitOutcomeParam from the OpenAI API.

Indicates that the shell commands finished and returned an exit code.

Attributes:

Name Type Description
type Annotated[Literal['exit'], Field(description='The outcome type. Always `exit`.')]

The outcome type. Always exit.

exit_code Annotated[int, Field(description='The exit code returned by the shell process.')]

The exit code returned by the shell process.

FunctionShellCallOutputTimeoutOutcome

Bases: BaseAPITypeExtra

Indicates that the shell call exceeded its configured time limit.

Attributes:

Name Type Description
type Annotated[Literal['timeout'], Field(description='The outcome type. Always `timeout`.')]

The outcome type. Always timeout.

FunctionShellCallOutputTimeoutOutcomeParam

Bases: BaseAPITypeExtra

Indicates that the shell call exceeded its configured time limit.

Attributes:

Name Type Description
type Annotated[Literal['timeout'], Field(description='The outcome type. Always `timeout`.')]

The outcome type. Always timeout.

InputFileContent

Bases: BaseAPITypeExtra

A file input to the model.

Attributes:

Name Type Description
type Annotated[Literal['input_file'], Field(description='The type of the input item. Always `input_file`.')]

The type of the input item. Always input_file.

filename Annotated[str | None, Field(description='The name of the file to be sent to the model.')]

The name of the file to be sent to the model.

file_data Annotated[str | None, Field(description='The content of the file to be sent to the model.')]

The content of the file to be sent to the model.

prompt_cache_breakpoint PromptCacheBreakpointConfig | None

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

file_url Annotated[AnyUrl | None, Field(description='The URL of the file to be sent to the model.')]

The URL of the file to be sent to the model.

detail Annotated[FileInputDetail | None, Field(description='The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`.')]

The detail level of the file to be sent to the model. Use auto to let the system select the detail level; for GPT-5.6 and later models, auto uses high-quality rendering, which may increase input token usage. Use low for lower-cost rendering, or high to render the file at higher quality. Defaults to auto.

InputFileContentParam

Bases: BaseAPITypeExtra

A file input to the model.

Attributes:

Name Type Description
type Annotated[Literal['input_file'], Field(description='The type of the input item. Always `input_file`.')]

The type of the input item. Always input_file.

file_data InputFileContentParamFileData | None

The base64-encoded data of the file to be sent to the model.

detail Annotated[FileDetailEnum | None, Field(description='The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`.')]

The detail level of the file to be sent to the model. Use auto to let the system select the detail level; for GPT-5.6 and later models, auto uses high-quality rendering, which may increase input token usage. Use low for lower-cost rendering, or high to render the file at higher quality. Defaults to auto.

prompt_cache_breakpoint PromptCacheBreakpointParam | None

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

InputImageContent

Bases: BaseAPITypeExtra

An image input to the model.

Learn about image inputs.

Attributes:

Name Type Description
type Annotated[Literal['input_image'], Field(description='The type of the input item. Always `input_image`.')]

The type of the input item. Always input_image.

detail Annotated[ImageDetail, Field(description='The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.')]

The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.

prompt_cache_breakpoint PromptCacheBreakpointConfig | None

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

InputImageContentParamAutoParam

Bases: BaseAPITypeExtra

An image input to the model.

Learn about image inputs

Attributes:

Name Type Description
type Annotated[Literal['input_image'], Field(description='The type of the input item. Always `input_image`.')]

The type of the input item. Always input_image.

image_url InputImageContentParamAutoParamImageUrl | None

The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.

prompt_cache_breakpoint PromptCacheBreakpointParam | None

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

InputTextContent

Bases: BaseAPITypeExtra

A text input to the model.

Attributes:

Name Type Description
type Annotated[Literal['input_text'], Field(description='The type of the input item. Always `input_text`.')]

The type of the input item. Always input_text.

text Annotated[str, Field(description='The text input to the model.')]

The text input to the model.

prompt_cache_breakpoint PromptCacheBreakpointConfig | None

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

InputTextContentParam

Bases: BaseAPITypeExtra

A text input to the model.

Attributes:

Name Type Description
type Annotated[Literal['input_text'], Field(description='The type of the input item. Always `input_text`.')]

The type of the input item. Always input_text.

text Annotated[str, Field(description='The text input to the model.', max_length=10485760)]

The text input to the model.

prompt_cache_breakpoint PromptCacheBreakpointParam | None

Marks the exact end of a reusable prompt prefix. When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

LogProb

Bases: BaseAPITypeExtra

The log probability of a token.

Attributes:

Name Type Description
top_logprobs list[TopLogProb]

The top log probability of a token.

PromptCacheBreakpointConfig

Bases: BaseAPITypeExtra

Marks the exact end of a reusable prompt prefix.

When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

Attributes:

Name Type Description
mode Annotated[Literal['explicit'], Field(description='The breakpoint mode. Always `explicit`.')]

The breakpoint mode. Always explicit.

ttl Annotated[str | None, Field(description='The minimum lifetime of this cache breakpoint. Defaults to the request TTL.')]

The minimum lifetime of this cache breakpoint. Defaults to the request TTL.

PromptCacheBreakpointParam

Bases: BaseAPITypeExtra

Marks the exact end of a reusable prompt prefix.

When ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl; the boundary is not rounded to a token block.

Attributes:

Name Type Description
mode Annotated[Literal['explicit'], Field(description='The breakpoint mode. Always `explicit`.')]

The breakpoint mode. Always explicit.

ttl Annotated[str | None, Field(description='The minimum lifetime of this cache breakpoint. Defaults to the request TTL.')]

The minimum lifetime of this cache breakpoint. Defaults to the request TTL.

ReasoningTextContent

Bases: BaseAPITypeExtra

Reasoning text from the model.

Attributes:

Name Type Description
type Annotated[Literal['reasoning_text'], Field(description='The type of the reasoning text. Always `reasoning_text`.')]

The type of the reasoning text. Always reasoning_text.

text Annotated[str, Field(description='The reasoning text from the model.')]

The reasoning text from the model.

RefusalContent

Bases: BaseAPITypeExtra

A refusal from the model.

Attributes:

Name Type Description
type Annotated[Literal['refusal'], Field(description='The type of the refusal. Always `refusal`.')]

The type of the refusal. Always refusal.

refusal Annotated[str, Field(description='The refusal explanation from the model.')]

The refusal explanation from the model.

SummaryTextContent

Bases: BaseAPITypeExtra

A summary text from the model.

Attributes:

Name Type Description
type Annotated[Literal['summary_text'], Field(description='The type of the object. Always `summary_text`.')]

The type of the object. Always summary_text.

text Annotated[str, Field(description='A summary of the reasoning output from the model so far.')]

A summary of the reasoning output from the model so far.

TopLogProb

Bases: BaseAPITypeExtra

The top log probability of a token.

AccessProgramsBody

Bases: BaseAPITypeExtra

AccessProgramsBody from the OpenAI API.

Attributes:

Name Type Description
cyber Annotated[CyberAccessProgramEnum, Field(description='The effective Cyber access program used for this response.')]

The effective Cyber access program used for this response.

CompactionTriggerItemParam

Bases: BaseAPITypeExtra

Compacts the current context.

Must be the final input item.

Attributes:

Name Type Description
type Annotated[Literal['compaction_trigger'], Field(description='The type of the item. Always `compaction_trigger`.')]

The type of the item. Always compaction_trigger.

FieldMisalignmentSteer

Bases: BaseAPITypeExtra

FieldMisalignmentSteer from the OpenAI API.

Attributes:

Name Type Description
message Annotated[str, Field(description='The public continuation instruction.')]

The public continuation instruction.

ItemReferenceParam

Bases: BaseAPITypeExtra

An internal identifier for an item to reference.

Attributes:

Name Type Description
id Annotated[str, Field(description='The ID of the item to reference.')]

The ID of the item to reference.

MisalignmentErrorDetailsResource

Bases: BaseAPITypeExtra

MisalignmentErrorDetailsResource from the OpenAI API.

Attributes:

Name Type Description
review_target MisalignmentErrorDetailsResourceReviewTarget | None

An opaque target for explicitly continuing this review, or null when unavailable.

error_type Annotated[FieldMisalignmentErrorType | None, Field(description='An optional classification; clients must accept additional values.')]

An optional classification; clients must accept additional values.

detailed_explanation Annotated[str | None, Field(description='The public explanation for this block.')]

The public explanation for this block.

steer Annotated[FieldMisalignmentSteer | None, Field(description='An optional public continuation instruction.')]

An optional public continuation instruction.

ModelResponseProperties

Bases: BaseAPITypeExtra

ModelResponseProperties from the OpenAI API.

Attributes:

Name Type Description
top_logprobs ModelResponsePropertiesTopLogprobs | None

An integer between 0 and 20 specifying the maximum number of most likely tokens to return at each token position, each with an associated log probability. In some cases, the number of returned tokens may be fewer than requested.

temperature ModelResponsePropertiesTemperature | None

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

top_p ModelResponsePropertiesTopP | None

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.

user Annotated[str | None, Field(deprecated=True, description='This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations.\nA stable identifier for your end-users.\nUsed to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).', examples=['user-1234'])]

This field is being replaced by safety_identifier and prompt_cache_key. Use prompt_cache_key instead to maintain caching optimizations. A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn

more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). safety_identifier: A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user, with a maximum length of 128 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. Learn more.

Moderation

Bases: BaseAPITypeExtra

Moderation results or errors for the response input and output.

Attributes:

Name Type Description
input Annotated[Annotated[Annotated[ModerationResultBody, Tag('0')] | Annotated[ModerationErrorBody, Tag('1')] | Annotated[UnknownVariant, Tag(UNKNOWN)], Discriminator(by_type({'moderation_result': '0', 'error': '1'}))], Field(description='Moderation for the response input.')]

Moderation for the response input.

output Annotated[Annotated[Annotated[ModerationResultBody, Tag('0')] | Annotated[ModerationErrorBody, Tag('1')] | Annotated[UnknownVariant, Tag(UNKNOWN)], Discriminator(by_type({'moderation_result': '0', 'error': '1'}))], Field(description='Moderation for the response output.')]

Moderation for the response output.

ModerationErrorBody

Bases: BaseAPITypeExtra

ModerationErrorBody from the OpenAI API.

An error produced while attempting moderation for the response input or output.

Attributes:

Name Type Description
type Annotated[Literal['error'], Field(description='The object type, which was always `error` for moderation failures.')]

The object type, which was always error for moderation failures.

code Annotated[str, Field(description='The error code.')]

The error code.

message Annotated[str, Field(description='The error message.')]

The error message.

ModerationResultBody

Bases: BaseAPITypeExtra

A moderation result produced for the response input or output.

Attributes:

Name Type Description
type Annotated[Literal['moderation_result'], Field(description='The object type, which was always `moderation_result` for successful moderation results.')]

The object type, which was always moderation_result for successful moderation results.

model Annotated[str, Field(description='The moderation model that produced this result.')]

The moderation model that produced this result.

flagged Annotated[bool, Field(description='A boolean indicating whether the content was flagged by any category.')]

A boolean indicating whether the content was flagged by any category.

categories Annotated[dict[str, bool], Field(description='A dictionary of moderation categories to booleans, True if the input is flagged under this category.')]

A dictionary of moderation categories to booleans, True if the input is flagged under this category.

category_scores Annotated[dict[str, float], Field(description='A dictionary of moderation categories to scores.')]

A dictionary of moderation categories to scores.

category_applied_input_types Annotated[dict[str, list[ModerationInputType]], Field(description='Which modalities of input are reflected by the score for each category.')]

Which modalities of input are reflected by the score for each category.

ProgramItemParam

Bases: BaseAPITypeExtra

ProgramItemParam from the OpenAI API.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of this program item.', examples=['cm_123'])]

The unique ID of this program item.

type Annotated[Literal['program'], Field(description='The item type. Always `program`.')]

The item type. Always program.

call_id Annotated[str, Field(description='The stable call ID of the program item.', max_length=64, min_length=1)]

The stable call ID of the program item.

code Annotated[str, Field(description='The JavaScript source executed by programmatic tool calling.', max_length=10485760)]

The JavaScript source executed by programmatic tool calling.

fingerprint Annotated[str, Field(description='Opaque program replay fingerprint that must be round-tripped.', max_length=10485760)]

Opaque program replay fingerprint that must be round-tripped.

ProgramOutputItemParam

Bases: BaseAPITypeExtra

ProgramOutputItemParam from the OpenAI API.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of this program output item.', examples=['cmo_123'])]

The unique ID of this program output item.

type Annotated[Literal['program_output'], Field(description='The item type. Always `program_output`.')]

The item type. Always program_output.

call_id Annotated[str, Field(description='The call ID of the program item.', max_length=64, min_length=1)]

The call ID of the program item.

result Annotated[str, Field(description='The result produced by the program item.', max_length=10485760)]

The result produced by the program item.

status Annotated[ProgramOutputItemStatus, Field(description='The terminal status of the program output.')]

The terminal status of the program output.

PromptCacheComparisonResponseNotFoundDiagnosticsBody

Bases: BaseAPITypeExtra

PromptCacheComparisonResponseNotFoundDiagnosticsBody.

PromptCacheHitDiagnosticsBody

Bases: BaseAPITypeExtra

PromptCacheHitDiagnosticsBody from the OpenAI API.

PromptCacheMissDiagnosticsBody

Bases: BaseAPITypeExtra

PromptCacheMissDiagnosticsBody from the OpenAI API.

Attributes:

Name Type Description
reason Annotated[CacheMissReasonTypeEnum, Field(description='The reason prompt cache reuse did not occur.')]

The reason prompt cache reuse did not occur.

cache_missed_tokens Annotated[int, Field(description='The estimated number of input tokens affected after the first detected divergence.')]

The estimated number of input tokens affected after the first detected divergence.

comparison_reusable_tokens Annotated[int | None, Field(description='The raw token count of the reusable prefix in the compared response.')]

The raw token count of the reusable prefix in the compared response.

PromptCacheOptions

Bases: BaseAPITypeExtra

The prompt-caching options that were applied to the response.

Supported for gpt-5.6 and later models.

Attributes:

Name Type Description
ttl Annotated[str, Field(description='The minimum lifetime applied to each cache breakpoint.')]

The minimum lifetime applied to each cache breakpoint.

mode Annotated[PromptCacheModeEnum, Field(description='Whether implicit prompt-cache breakpoints were enabled.')]

Whether implicit prompt-cache breakpoints were enabled.

PromptCacheUnavailableDiagnosticsBody

Bases: BaseAPITypeExtra

PromptCacheUnavailableDiagnosticsBody from the OpenAI API.

Reasoning

Bases: BaseAPITypeExtra

Reasoning from the OpenAI API (upstream: Reasoning).

Configuration options for reasoning models.

Attributes:

Name Type Description
mode Annotated[ReasoningModeEnum | None, Field(description='Controls the reasoning execution mode for the request.\n\nWhen returned on a response, this is the effective execution mode.')]

Controls the reasoning execution mode for the request. When returned on a response, this is the effective execution mode.

ReasoningInputTransformation

Bases: BaseAPITypeExtra

ReasoningInputTransformation from the OpenAI API.

Attributes:

Name Type Description
id Annotated[str, Field(description='The original reasoning item ID.')]

The original reasoning item ID.

Response

Bases: BaseAPITypeExtra

Response from the OpenAI API (upstream: Response).

Attributes:

Name Type Description
top_logprobs ResponseTopLogprobs | None

An integer between 0 and 20 specifying the maximum number of most likely tokens to return at each token position, each with an associated log probability. In some cases, the number of returned tokens may be fewer than requested.

temperature ResponseTemperature | None

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

top_p ResponseTopP | None

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.

user Annotated[str | None, Field(deprecated=True, description='This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations.\nA stable identifier for your end-users.\nUsed to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).', examples=['user-1234'])]

This field is being replaced by safety_identifier and prompt_cache_key. Use prompt_cache_key instead to maintain caching optimizations. A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn

more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). safety_identifier: A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user, with a maximum length of 128 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. Learn more. model: Model ID used to generate the response, like gpt-6.2-astra. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models. text: Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - Text inputs and outputs - Structured Outputs tools: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call. id: Unique identifier for this Response. object: The object type of this resource - always set to response. status: The status of the response generation. One of completed, failed, in_progress, cancelled, queued, or incomplete. created_at: Unix timestamp (in seconds) of when this Response was created. incomplete_details: Details about why the response is incomplete. input_transformations: Reasoning inputs withheld from the model, in input order. output: An array of content items generated by the model. - The length and order of items in the output array is dependent on the model's response. - Rather than accessing the first item in the output array and assuming it's an assistant message with the content generated by the model, you might consider using the output_text property where supported in SDKs. reasoning: Configuration options for reasoning models. usage: Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. tool_usage: Usage reported by hosted tools, separate from base model usage. The field can be omitted when tool usage is unavailable. When present, tool families with no recorded usage have zero counts. image_gen sums available token counts across image generation calls. Calls with missing or incomplete usage records may be skipped. Output token details and cached input counts can be omitted. An omitted cache count means cache usage is unknown. web_search.num_requests counts billable searches. Discounted searches and actions such as opening a page are excluded. Use billing records to reconcile final charges. prompt_cache_options: The prompt-caching options that were applied to the response. Supported for gpt-5.6 and later models. prompt_cache_diagnostics: Prompt cache diagnostics requested for this response. moderation: Moderation results or errors for the response input and output. parallel_tool_calls: Whether to allow the model to run tool calls in parallel. conversation: The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation.

ResponseConfigurationUpdateItemParam

Bases: BaseAPITypeExtra

An update to the conversation's response configuration.

Supply reasoning, text, or both. Each setting stays in effect until a later update replaces it.

Attributes:

Name Type Description
type Annotated[Literal['configuration_update'], Field(description='The item type. Always `configuration_update`.')]

The item type. Always configuration_update.

reasoning Annotated[ResponseConfigurationUpdateItemParamReasoning | None, Field(description='Updates to reasoning configuration. Only effort is supported.')]

Updates to reasoning configuration. Only effort is supported.

text Annotated[ResponseConfigurationUpdateItemParamText | None, Field(description='The text output configuration for subsequent responses.')]

The text output configuration for subsequent responses.

ResponseConversation

Bases: BaseAPITypeExtra

The conversation that this response belonged to.

Input items and output items from this response were automatically added to this conversation.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of the conversation that this response was associated with.')]

The unique ID of the conversation that this response was associated with.

ResponseFormatJsonObject

Bases: BaseAPITypeExtra

JSON object response format.

An older method of generating JSON responses. Using json_schema is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.

Attributes:

Name Type Description
type Annotated[Literal['json_object'], Field(description='The type of response format being defined. Always `json_object`.')]

The type of response format being defined. Always json_object.

ResponseFormatJsonSchemaSchema

Bases: BaseAPITypeExtra

ResponseFormatJsonSchemaSchema from the OpenAI API.

The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas here.

ResponseFormatText

Bases: BaseAPITypeExtra

Default response format.

Used to generate text responses.

Attributes:

Name Type Description
type Annotated[Literal['text'], Field(description='The type of response format being defined. Always `text`.')]

The type of response format being defined. Always text.

ResponseLogProb

Bases: BaseAPITypeExtra

ResponseLogProb from the OpenAI API.

A logprob is the logarithmic probability that the model assigns to producing a particular token at a given position in the sequence. Less-negative (higher) logprob values indicate greater model confidence in that token choice.

Attributes:

Name Type Description
token Annotated[str, Field(description='A possible text token.')]

A possible text token.

logprob Annotated[float, Field(description='The log probability of this token.')]

The log probability of this token.

top_logprobs Annotated[list[ResponseLogProbTopLogprob] | None, Field(description='The log probabilities of up to 20 of the most likely tokens.')]

The log probabilities of up to 20 of the most likely tokens.

ResponseProperties

Bases: BaseAPITypeExtra

ResponseProperties from the OpenAI API.

Attributes:

Name Type Description
model Annotated[ModelIdsResponses | None, Field(description='Model ID used to generate the response, like `gpt-6.2-astra`. OpenAI\noffers a wide range of models with different capabilities, performance\ncharacteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models)\nto browse and compare available models.')]

Model ID used to generate the response, like gpt-6.2-astra. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.

text ResponseTextParam | None

Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and

outputs](https://developers.openai.com/api/docs/guides/text) - Structured Outputs tools: An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter. tool_choice: How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call.

ResponseTextParam

Bases: BaseAPITypeExtra

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more: - Text inputs and outputs - Structured Outputs

Attributes:

Name Type Description
format TextResponseFormatConfiguration | None

An object specifying the format that the model must output.

TextResponseFormatJsonSchema

Bases: BaseAPITypeExtra

JSON Schema response format.

Used to generate structured JSON responses. Learn more about Structured Outputs.

Attributes:

Name Type Description
type Annotated[Literal['json_schema'], Field(description='The type of response format being defined. Always `json_schema`.')]

The type of response format being defined. Always json_schema.

description Annotated[str | None, Field(description='A description of what the response format is for, used by the model to\ndetermine how to respond in the format.')]

A description of what the response format is for, used by the model to determine how to respond in the format.

name Annotated[str, Field(description='The name of the response format. Must be a-z, A-Z, 0-9, or contain\nunderscores and dashes, with a maximum length of 64.')]

The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

schema_ Annotated[ResponseFormatJsonSchemaSchema, Field(validation_alias='schema', serialization_alias='schema')]

The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas here.

AdditionalTools

Bases: BaseAPITypeExtra

AdditionalTools from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['additional_tools'], Field(description='The type of the item. Always `additional_tools`.')]

The type of the item. Always additional_tools.

id Annotated[str, Field(description='The unique ID of the additional tools item.')]

The unique ID of the additional tools item.

role Annotated[MessageRole, Field(description='The role that provided the additional tools.')]

The role that provided the additional tools.

tools Annotated[list[Tool], Field(description='The additional tool definitions made available at this item.')]

The additional tool definitions made available at this item.

AdditionalToolsItemParam

Bases: BaseAPITypeExtra

AdditionalToolsItemParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['additional_tools'], Field(description='The item type. Always `additional_tools`.')]

The item type. Always additional_tools.

role Annotated[Literal['developer'], Field(description='The role that provided the additional tools. Only `developer` is supported.')]

The role that provided the additional tools. Only developer is supported.

tools Annotated[list[Tool], Field(description='A list of additional tools made available at this item.')]

A list of additional tools made available at this item.

ApplyPatchToolCall

Bases: BaseAPITypeExtra

ApplyPatchToolCall from the OpenAI API.

A tool call that applies file diffs by creating, deleting, or updating files.

Attributes:

Name Type Description
type Annotated[Literal['apply_patch_call'], Field(description='The type of the item. Always `apply_patch_call`.')]

The type of the item. Always apply_patch_call.

id Annotated[str, Field(description='The unique ID of the apply patch tool call. Populated when this item is returned via API.')]

The unique ID of the apply patch tool call. Populated when this item is returned via API.

call_id Annotated[str, Field(description='The unique ID of the apply patch tool call generated by the model.')]

The unique ID of the apply patch tool call generated by the model.

caller ToolCallCaller | None

The execution context that produced this tool call.

status Annotated[ApplyPatchCallStatus, Field(description='The status of the apply patch tool call. One of `in_progress` or `completed`.')]

The status of the apply patch tool call. One of in_progress or completed.

operation Annotated[Annotated[Annotated[ApplyPatchCreateFileOperation, Tag('0')] | Annotated[ApplyPatchDeleteFileOperation, Tag('1')] | Annotated[ApplyPatchUpdateFileOperation, Tag('2')] | Annotated[UnknownVariant, Tag(UNKNOWN)], Discriminator(by_type({'create_file': '0', 'delete_file': '1', 'update_file': '2'}))], Field(description='One of the create_file, delete_file, or update_file operations applied via apply_patch.', title='Apply patch operation')]

One of the create_file, delete_file, or update_file operations applied via apply_patch.

created_by Annotated[str | None, Field(description='The ID of the entity that created this tool call.')]

The ID of the entity that created this tool call.

ApplyPatchToolCallItemParam

Bases: BaseAPITypeExtra

ApplyPatchToolCallItemParam from the OpenAI API.

A tool call representing a request to create, delete, or update files using diff patches.

Attributes:

Name Type Description
type Annotated[Literal['apply_patch_call'], Field(description='The type of the item. Always `apply_patch_call`.')]

The type of the item. Always apply_patch_call.

call_id Annotated[str, Field(description='The unique ID of the apply patch tool call generated by the model.', max_length=64, min_length=1)]

The unique ID of the apply patch tool call generated by the model.

caller ToolCallCallerParam | None

The execution context that produced this tool call.

status Annotated[ApplyPatchCallStatusParam, Field(description='The status of the apply patch tool call. One of `in_progress` or `completed`.')]

The status of the apply patch tool call. One of in_progress or completed.

operation Annotated[ApplyPatchOperationParam, Field(description='The specific create, delete, or update instruction for the apply_patch tool call.')]

The specific create, delete, or update instruction for the apply_patch tool call.

ApplyPatchToolCallOutput

Bases: BaseAPITypeExtra

The output emitted by an apply patch tool call.

Attributes:

Name Type Description
type Annotated[Literal['apply_patch_call_output'], Field(description='The type of the item. Always `apply_patch_call_output`.')]

The type of the item. Always apply_patch_call_output.

id Annotated[str, Field(description='The unique ID of the apply patch tool call output. Populated when this item is returned via API.')]

The unique ID of the apply patch tool call output. Populated when this item is returned via API.

call_id Annotated[str, Field(description='The unique ID of the apply patch tool call generated by the model.')]

The unique ID of the apply patch tool call generated by the model.

caller ToolCallCaller | None

The execution context that produced this tool call.

status Annotated[ApplyPatchCallOutputStatus, Field(description='The status of the apply patch tool call output. One of `completed` or `failed`.')]

The status of the apply patch tool call output. One of completed or failed.

created_by Annotated[str | None, Field(description='The ID of the entity that created this tool call output.')]

The ID of the entity that created this tool call output.

ApplyPatchToolCallOutputItemParam

Bases: BaseAPITypeExtra

The streamed output emitted by an apply patch tool call.

Attributes:

Name Type Description
type Annotated[Literal['apply_patch_call_output'], Field(description='The type of the item. Always `apply_patch_call_output`.')]

The type of the item. Always apply_patch_call_output.

call_id Annotated[str, Field(description='The unique ID of the apply patch tool call generated by the model.', max_length=64, min_length=1)]

The unique ID of the apply patch tool call generated by the model.

caller ToolCallCallerParam | None

The execution context that produced this tool call.

status Annotated[ApplyPatchCallOutputStatusParam, Field(description='The status of the apply patch tool call output. One of `completed` or `failed`.')]

The status of the apply patch tool call output. One of completed or failed.

output ApplyPatchToolCallOutputItemParamOutput | None

Optional human-readable log text from the apply patch tool (e.g., patch results or errors).

AutoCodeInterpreterToolParam

Bases: BaseAPITypeExtra

Configuration for a code interpreter container.

Optionally specify the IDs of the files to run the code on.

Attributes:

Name Type Description
type Annotated[Literal['auto'], Field(description='Always `auto`.')]

Always auto.

file_ids Annotated[list[str] | None, Field(description='An optional list of uploaded files to make available to your code.', max_length=50)]

An optional list of uploaded files to make available to your code.

network_policy Annotated[Annotated[Annotated[ContainerNetworkPolicyDisabledParam, Tag('0')] | Annotated[ContainerNetworkPolicyAllowlistParam, Tag('1')] | Annotated[UnknownVariant, Tag(UNKNOWN)], Discriminator(by_type({'disabled': '0', 'allowlist': '1'}))] | None, Field(description='Network access policy for the container.')]

Network access policy for the container.

CodeInterpreterTool

Bases: BaseAPITypeExtra

CodeInterpreterTool from the OpenAI API.

A tool that runs Python code to help generate a response to a prompt.

Attributes:

Name Type Description
type Annotated[Literal['code_interpreter'], Field(description='The type of the code interpreter tool. Always `code_interpreter`.')]

The type of the code interpreter tool. Always code_interpreter.

container Annotated[str | AutoCodeInterpreterToolParam, Field(description='The code interpreter container. Can be a container ID or an object that\nspecifies uploaded file IDs to make available to your code, along with an\noptional `memory_limit` setting.')]

The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code, along with an optional memory_limit setting.

allowed_callers CodeInterpreterToolAllowedCallers | None

The tool invocation context(s).

CodeInterpreterToolCall

Bases: BaseAPITypeExtra

A tool call to run code.

Attributes:

Name Type Description
type Annotated[Literal['code_interpreter_call'], Field(description='The type of the code interpreter tool call. Always `code_interpreter_call`.')]

The type of the code interpreter tool call. Always code_interpreter_call.

id Annotated[str, Field(description='The unique ID of the code interpreter tool call.')]

The unique ID of the code interpreter tool call.

status Annotated[str, Field(description='The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`.')]

The status of the code interpreter tool call. Valid values are in_progress, completed, incomplete, interpreting, and failed.

container_id Annotated[str, Field(description='The ID of the container used to run the code.')]

The ID of the container used to run the code.

CompactionBody

Bases: BaseAPITypeExtra

CompactionBody from the OpenAI API.

A compaction item generated by the v1/responses/compact API.

Attributes:

Name Type Description
type Annotated[Literal['compaction'], Field(description='The type of the item. Always `compaction`.')]

The type of the item. Always compaction.

id Annotated[str, Field(description='The unique ID of the compaction item.')]

The unique ID of the compaction item.

encrypted_content Annotated[str, Field(description='The encrypted content that was produced by compaction.')]

The encrypted content that was produced by compaction.

created_by Annotated[str | None, Field(description='The identifier of the actor that created the item.')]

The identifier of the actor that created the item.

CompactionSummaryItemParam

Bases: BaseAPITypeExtra

CompactionSummaryItemParam from the OpenAI API.

A compaction item generated by the v1/responses/compact API.

Attributes:

Name Type Description
type Annotated[Literal['compaction'], Field(description='The type of the item. Always `compaction`.')]

The type of the item. Always compaction.

encrypted_content Annotated[str, Field(description='The encrypted content of the compaction summary.', max_length=104857600)]

The encrypted content of the compaction summary.

ComputerCallOutputItemParam

Bases: BaseAPITypeExtra

The output of a computer tool call.

Attributes:

Name Type Description
call_id Annotated[str, Field(description='The ID of the computer tool call that produced the output.', max_length=64, min_length=1)]

The ID of the computer tool call that produced the output.

type Annotated[Literal['computer_call_output'], Field(description='The type of the computer tool call output. Always `computer_call_output`.')]

The type of the computer tool call output. Always computer_call_output.

output ComputerScreenshotImage

A computer screenshot image used with the computer use tool.

acknowledged_safety_checks list[ComputerCallSafetyCheckParam] | None

A pending safety check for the computer call.

ComputerCallSafetyCheckParam

Bases: BaseAPITypeExtra

A pending safety check for the computer call.

Attributes:

Name Type Description
id Annotated[str, Field(description='The ID of the pending safety check.')]

The ID of the pending safety check.

ComputerToolCall

Bases: BaseAPITypeExtra

A tool call to a computer use tool.

See the computer use guide for more information.

Attributes:

Name Type Description
type Annotated[Literal['computer_call'], Field(description='The type of the computer call. Always `computer_call`.')]

The type of the computer call. Always computer_call.

id Annotated[str, Field(description='The unique ID of the computer call.')]

The unique ID of the computer call.

call_id Annotated[str, Field(description='An identifier used when responding to the tool call with output.')]

An identifier used when responding to the tool call with output.

actions ComputerActionList | None

Flattened batched actions for computer_use. Each action includes an type discriminator and action-specific fields.

pending_safety_checks Annotated[list[ComputerCallSafetyCheckParam], Field(description='The pending safety checks for the computer call.')]

The pending safety checks for the computer call.

status Annotated[str, Field(description='The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.')]

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

ComputerToolCallOutput

Bases: BaseAPITypeExtra

The output of a computer tool call.

Attributes:

Name Type Description
type Annotated[Literal['computer_call_output'], Field(description='The type of the computer tool call output. Always `computer_call_output`.')]

The type of the computer tool call output. Always computer_call_output.

id Annotated[str | None, Field(description='The ID of the computer tool call output.')]

The ID of the computer tool call output.

call_id Annotated[str, Field(description='The ID of the computer tool call that produced the output.')]

The ID of the computer tool call that produced the output.

acknowledged_safety_checks Annotated[list[ComputerCallSafetyCheckParam] | None, Field(description='The safety checks reported by the API that have been acknowledged by the\ndeveloper.')]

The safety checks reported by the API that have been acknowledged by the developer.

output ComputerScreenshotImage

A computer screenshot image used with the computer use tool.

status Annotated[str | None, Field(description='The status of the message input. One of `in_progress`, `completed`, or\n`incomplete`. Populated when input items are returned via API.')]

The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.

ComputerToolCallOutputResource

Bases: BaseAPITypeExtra

The output of a computer tool call.

Attributes:

Name Type Description
type Annotated[Literal['computer_call_output'], Field(description='The type of the computer tool call output. Always `computer_call_output`.')]

The type of the computer tool call output. Always computer_call_output.

id Annotated[str, Field(description='The ID of the computer tool call output.')]

The ID of the computer tool call output.

call_id Annotated[str, Field(description='The ID of the computer tool call that produced the output.')]

The ID of the computer tool call that produced the output.

acknowledged_safety_checks Annotated[list[ComputerCallSafetyCheckParam] | None, Field(description='The safety checks reported by the API that have been acknowledged by the\ndeveloper.')]

The safety checks reported by the API that have been acknowledged by the developer.

output ComputerScreenshotImage

A computer screenshot image used with the computer use tool.

created_by Annotated[str | None, Field(description='The identifier of the actor that created the item.')]

The identifier of the actor that created the item.

ContainerAutoParam

Bases: BaseAPITypeExtra

ContainerAutoParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['container_auto'], Field(description='Automatically creates a container for this request')]

Automatically creates a container for this request

file_ids Annotated[list[str] | None, Field(description='An optional list of uploaded files to make available to your code.', max_length=50)]

An optional list of uploaded files to make available to your code.

network_policy Annotated[Annotated[Annotated[ContainerNetworkPolicyDisabledParam, Tag('0')] | Annotated[ContainerNetworkPolicyAllowlistParam, Tag('1')] | Annotated[UnknownVariant, Tag(UNKNOWN)], Discriminator(by_type({'disabled': '0', 'allowlist': '1'}))] | None, Field(description='Network access policy for the container.')]

Network access policy for the container.

skills Annotated[list[ContainerAutoParamSkills] | None, Field(description='An optional list of skills referenced by id or inline data. Across all inline skills in this list, decoded ZIP data must total at most 50 MiB and Base64 text must total at most 70,254,592 characters, including line breaks. Skill references do not count toward these limits.', max_length=200)]

An optional list of skills referenced by id or inline data. Across all inline skills in this list, decoded ZIP data must total at most 50 MiB and Base64 text must total at most 70,254,592 characters, including line breaks. Skill references do not count toward these limits.

ContainerReferenceParam

Bases: BaseAPITypeExtra

ContainerReferenceParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['container_reference'], Field(description='References a container created with the /v1/containers endpoint')]

References a container created with the /v1/containers endpoint

container_id Annotated[str, Field(description='The ID of the referenced container.', examples=['cntr_123'])]

The ID of the referenced container.

ContainerReferenceResource

Bases: BaseAPITypeExtra

Represents a container created with /v1/containers.

Attributes:

Name Type Description
type Annotated[Literal['container_reference'], Field(description='The environment type. Always `container_reference`.')]

The environment type. Always container_reference.

CustomToolCall

Bases: BaseAPITypeExtra

A call to a custom tool created by the model.

Attributes:

Name Type Description
type Annotated[Literal['custom_tool_call'], Field(description='The type of the custom tool call. Always `custom_tool_call`.')]

The type of the custom tool call. Always custom_tool_call.

id Annotated[str | None, Field(description='The unique ID of the custom tool call in the OpenAI platform.')]

The unique ID of the custom tool call in the OpenAI platform.

call_id Annotated[str, Field(description='An identifier used to map this custom tool call to a tool call output.')]

An identifier used to map this custom tool call to a tool call output.

caller ToolCallCaller | None

The execution context that produced this tool call.

namespace Annotated[str | None, Field(description='The namespace of the custom tool being called.')]

The namespace of the custom tool being called.

name Annotated[str, Field(description='The name of the custom tool being called.')]

The name of the custom tool being called.

input Annotated[str, Field(description='The input for the custom tool call generated by the model.')]

The input for the custom tool call generated by the model.

async_ Annotated[bool | None, Field(validation_alias='async', description='Whether the custom tool call runs asynchronously.', serialization_alias='async')]

Whether the custom tool call runs asynchronously.

CustomToolCallOutput

Bases: BaseAPITypeExtra

CustomToolCallOutput from the OpenAI API.

The output of a custom tool call from your code, being sent back to the model.

Attributes:

Name Type Description
type Annotated[Literal['custom_tool_call_output'], Field(description='The type of the custom tool call output. Always `custom_tool_call_output`.')]

The type of the custom tool call output. Always custom_tool_call_output.

id Annotated[str | None, Field(description='The unique ID of the custom tool call output in the OpenAI platform.')]

The unique ID of the custom tool call output in the OpenAI platform.

call_id Annotated[str, Field(description='The call ID, used to map this custom tool call output to a custom tool call.')]

The call ID, used to map this custom tool call output to a custom tool call.

caller ToolCallCallerParam | None

The execution context that produced this tool call.

output Annotated[str | list[FunctionAndCustomToolCallOutput], Field(description='The output from the custom tool call generated by your code.\nCan be a string or an list of output content.')]

The output from the custom tool call generated by your code. Can be a string or an list of output content.

CustomToolCallOutputResource

Bases: BaseAPITypeExtra

CustomToolCallOutputResource from the OpenAI API.

The output of a custom tool call from your code, being sent back to the model.

Attributes:

Name Type Description
type Annotated[Literal['custom_tool_call_output'], Field(description='The type of the custom tool call output. Always `custom_tool_call_output`.')]

The type of the custom tool call output. Always custom_tool_call_output.

call_id Annotated[str, Field(description='The call ID, used to map this custom tool call output to a custom tool call.')]

The call ID, used to map this custom tool call output to a custom tool call.

caller ToolCallCallerParam | None

The execution context that produced this tool call.

output Annotated[str | list[FunctionAndCustomToolCallOutput], Field(description='The output from the custom tool call generated by your code.\nCan be a string or an list of output content.')]

The output from the custom tool call generated by your code. Can be a string or an list of output content.

status Annotated[FunctionCallOutputStatusEnum, Field(description='The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.')]

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

created_by Annotated[str | None, Field(description='The identifier of the actor that created the item.')]

The identifier of the actor that created the item.

CustomToolParam

Bases: BaseAPITypeExtra

A custom tool that processes input using a specified format.

Learn more about custom tools

Attributes:

Name Type Description
type Annotated[Literal['custom'], Field(description='The type of the custom tool. Always `custom`.')]

The type of the custom tool. Always custom.

name Annotated[str, Field(description='The name of the custom tool, used to identify it in tool calls.')]

The name of the custom tool, used to identify it in tool calls.

async_ Annotated[bool | None, Field(validation_alias='async', description='Whether the tool response can be returned asynchronously versus immediately returned on next response creation.', serialization_alias='async')]

Whether the tool response can be returned asynchronously versus immediately returned on next response creation.

description Annotated[str | None, Field(description='Optional description of the custom tool, used to provide more context.')]

Optional description of the custom tool, used to provide more context.

format Annotated[Annotated[Annotated[CustomTextFormatParam, Tag('0')] | Annotated[CustomGrammarFormatParam, Tag('1')] | Annotated[UnknownVariant, Tag(UNKNOWN)], Discriminator(by_type({'text': '0', 'grammar': '1'}))] | None, Field(description='The input format for the custom tool. Default is unconstrained text.')]

The input format for the custom tool. Default is unconstrained text.

defer_loading Annotated[bool | None, Field(description='Whether this tool should be deferred and discovered via tool search.')]

Whether this tool should be deferred and discovered via tool search.

allowed_callers CustomToolParamAllowedCallers | None

The tool invocation context(s).

EasyInputMessage

Bases: BaseAPITypeExtra

EasyInputMessage from the OpenAI API.

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

Attributes:

Name Type Description
role Annotated[str, Field(description='The role of the message input. One of `user`, `assistant`, `system`, or\n`developer`.')]

The role of the message input. One of user, assistant, system, or developer.

content Annotated[str | InputMessageContentList, Field(description='Text, image, or audio input to the model, used to generate a response.\nCan also contain previous assistant responses.')]

Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses.

phase MessagePhase | None

Labels an assistant message as intermediate commentary (commentary) or the final answer (final_answer). For models like gpt-5.3-codex and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages.

type Annotated[Literal['message'] | None, Field(description='The type of the message input. Always `message`.')]

The type of the message input. Always message.

FunctionCallOutputItemParam

Bases: BaseAPITypeExtra

The output of a function tool call.

Attributes:

Name Type Description
call_id FunctionCallOutputItemParamCallId | None

The unique ID of the function tool call generated by the model.

type Annotated[Literal['function_call_output'], Field(description='The type of the function tool call output. Always `function_call_output`.')]

The type of the function tool call output. Always function_call_output.

output Annotated[FunctionCallOutputItemParamOutput | list[FunctionCallOutputItemParamOutput1], Field(description='Text, image, or file output of the function tool call.')]

Text, image, or file output of the function tool call.

name FunctionCallOutputItemParamName | None

The name of the tool that produced the output.

namespace FunctionCallOutputItemParamNamespace | None

The namespace of the tool that produced the output.

caller ToolCallCallerParam | None

The execution context that produced this tool call.

FunctionShellCall

Bases: BaseAPITypeExtra

FunctionShellCall from the OpenAI API.

A tool call that executes one or more shell commands in a managed environment.

Attributes:

Name Type Description
type Annotated[Literal['shell_call'], Field(description='The type of the item. Always `shell_call`.')]

The type of the item. Always shell_call.

id Annotated[str, Field(description='The unique ID of the shell tool call. Populated when this item is returned via API.')]

The unique ID of the shell tool call. Populated when this item is returned via API.

call_id Annotated[str, Field(description='The unique ID of the shell tool call generated by the model.')]

The unique ID of the shell tool call generated by the model.

caller ToolCallCaller | None

The execution context that produced this tool call.

action Annotated[FunctionShellAction, Field(description='The shell commands and limits that describe how to run the tool call.')]

The shell commands and limits that describe how to run the tool call.

status Annotated[FunctionShellCallStatus, Field(description='The status of the shell call. One of `in_progress`, `completed`, or `incomplete`.')]

The status of the shell call. One of in_progress, completed, or incomplete.

created_by Annotated[str | None, Field(description='The ID of the entity that created this tool call.')]

The ID of the entity that created this tool call.

FunctionShellCallItemParam

Bases: BaseAPITypeExtra

FunctionShellCallItemParam from the OpenAI API.

A tool representing a request to execute one or more shell commands.

Attributes:

Name Type Description
call_id Annotated[str, Field(description='The unique ID of the shell tool call generated by the model.', max_length=64, min_length=1)]

The unique ID of the shell tool call generated by the model.

caller ToolCallCallerParam | None

The execution context that produced this tool call.

type Annotated[Literal['shell_call'], Field(description='The type of the item. Always `shell_call`.')]

The type of the item. Always shell_call.

action Annotated[FunctionShellActionParam, Field(description='The shell commands and limits that describe how to run the tool call.')]

The shell commands and limits that describe how to run the tool call.

status FunctionShellCallItemStatus | None

Status values reported for shell tool calls.

FunctionShellCallOutput

Bases: BaseAPITypeExtra

The output of a shell tool call that was emitted.

Attributes:

Name Type Description
type Annotated[Literal['shell_call_output'], Field(description='The type of the shell call output. Always `shell_call_output`.')]

The type of the shell call output. Always shell_call_output.

id Annotated[str, Field(description='The unique ID of the shell call output. Populated when this item is returned via API.')]

The unique ID of the shell call output. Populated when this item is returned via API.

call_id Annotated[str, Field(description='The unique ID of the shell tool call generated by the model.')]

The unique ID of the shell tool call generated by the model.

caller ToolCallCaller | None

The execution context that produced this tool call.

status Annotated[FunctionShellCallOutputStatusEnum, Field(description='The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`.')]

The status of the shell call output. One of in_progress, completed, or incomplete.

output Annotated[list[FunctionShellCallOutputContent], Field(description='An array of shell call output contents')]

An array of shell call output contents

created_by Annotated[str | None, Field(description='The identifier of the actor that created the item.')]

The identifier of the actor that created the item.

FunctionShellCallOutputContent

Bases: BaseAPITypeExtra

The content of a shell tool call output that was emitted.

Attributes:

Name Type Description
stdout Annotated[str, Field(description='The standard output that was captured.')]

The standard output that was captured.

stderr Annotated[str, Field(description='The standard error output that was captured.')]

The standard error output that was captured.

outcome Annotated[Annotated[Annotated[FunctionShellCallOutputTimeoutOutcome, Tag('0')] | Annotated[FunctionShellCallOutputExitOutcome, Tag('1')] | Annotated[UnknownVariant, Tag(UNKNOWN)], Discriminator(by_type({'timeout': '0', 'exit': '1'}))], Field(description='Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk.', title='Shell call outcome')]

Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk.

created_by Annotated[str | None, Field(description='The identifier of the actor that created the item.')]

The identifier of the actor that created the item.

FunctionShellCallOutputContentParam

Bases: BaseAPITypeExtra

FunctionShellCallOutputContentParam from the OpenAI API.

Captured stdout and stderr for a portion of a shell tool call output.

Attributes:

Name Type Description
stdout Annotated[str, Field(description='Captured stdout output for the shell call.', max_length=10485760)]

Captured stdout output for the shell call.

stderr Annotated[str, Field(description='Captured stderr output for the shell call.', max_length=10485760)]

Captured stderr output for the shell call.

outcome Annotated[FunctionShellCallOutputOutcomeParam, Field(description='The exit or timeout outcome associated with this shell call.')]

The exit or timeout outcome associated with this shell call.

FunctionShellCallOutputItemParam

Bases: BaseAPITypeExtra

The streamed output items emitted by a shell tool call.

Attributes:

Name Type Description
call_id Annotated[str, Field(description='The unique ID of the shell tool call generated by the model.', max_length=64, min_length=1)]

The unique ID of the shell tool call generated by the model.

caller ToolCallCallerParam | None

The execution context that produced this tool call.

type Annotated[Literal['shell_call_output'], Field(description='The type of the item. Always `shell_call_output`.')]

The type of the item. Always shell_call_output.

output Annotated[list[FunctionShellCallOutputContentParam], Field(description='Captured chunks of stdout and stderr output, along with their associated outcomes.')]

Captured chunks of stdout and stderr output, along with their associated outcomes.

status FunctionShellCallItemStatus | None

Status values reported for shell tool calls.

FunctionShellToolParam

Bases: BaseAPITypeExtra

A tool that allows the model to execute shell commands.

Attributes:

Name Type Description
type Annotated[Literal['shell'], Field(description='The type of the shell tool. Always `shell`.')]

The type of the shell tool. Always shell.

allowed_callers FunctionShellToolParamAllowedCallers | None

The tool invocation context(s).

FunctionToolCall

Bases: BaseAPITypeExtra

A tool call to run a function.

See the function calling guide for more information.

Attributes:

Name Type Description
id Annotated[str | None, Field(description='The unique ID of the function tool call.')]

The unique ID of the function tool call.

type Annotated[Literal['function_call'], Field(description='The type of the function tool call. Always `function_call`.')]

The type of the function tool call. Always function_call.

call_id Annotated[str, Field(description='The unique ID of the function tool call generated by the model.')]

The unique ID of the function tool call generated by the model.

caller ToolCallCaller | None

The execution context that produced this tool call.

namespace Annotated[str | None, Field(description='The namespace of the function to run.')]

The namespace of the function to run.

name Annotated[str, Field(description='The name of the function to run.')]

The name of the function to run.

arguments Annotated[str, Field(description='A JSON string of the arguments to pass to the function.')]

A JSON string of the arguments to pass to the function.

status Annotated[str | None, Field(description='The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.')]

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

async_ Annotated[bool | None, Field(validation_alias='async', description='Whether the function tool call runs asynchronously.', serialization_alias='async')]

Whether the function tool call runs asynchronously.

FunctionToolCallOutput

Bases: BaseAPITypeExtra

The output of a function tool call.

Attributes:

Name Type Description
id Annotated[str | None, Field(description='The unique ID of the function tool call output. Populated when this item\nis returned via API.')]

The unique ID of the function tool call output. Populated when this item is returned via API.

type Annotated[Literal['function_call_output'], Field(description='The type of the function tool call output. Always `function_call_output`.')]

The type of the function tool call output. Always function_call_output.

call_id Annotated[str | None, Field(description='The unique ID of the function tool call generated by the model.')]

The unique ID of the function tool call generated by the model.

name Annotated[str | None, Field(description='The name of the tool that produced the output.')]

The name of the tool that produced the output.

namespace Annotated[str | None, Field(description='The namespace of the tool that produced the output.')]

The namespace of the tool that produced the output.

caller ToolCallCallerParam | None

The execution context that produced this tool call.

output Annotated[str | list[FunctionAndCustomToolCallOutput], Field(description='The output from the function call generated by your code.\nCan be a string or an list of output content.')]

The output from the function call generated by your code. Can be a string or an list of output content.

status Annotated[str | None, Field(description='The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.')]

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

FunctionToolCallOutputResource

Bases: BaseAPITypeExtra

The output of a function tool call.

Attributes:

Name Type Description
type Annotated[Literal['function_call_output'], Field(description='The type of the function tool call output. Always `function_call_output`.')]

The type of the function tool call output. Always function_call_output.

call_id Annotated[str | None, Field(description='The unique ID of the function tool call generated by the model.')]

The unique ID of the function tool call generated by the model.

name Annotated[str | None, Field(description='The name of the tool that produced the output.')]

The name of the tool that produced the output.

namespace Annotated[str | None, Field(description='The namespace of the tool that produced the output.')]

The namespace of the tool that produced the output.

caller ToolCallCallerParam | None

The execution context that produced this tool call.

output Annotated[str | list[FunctionAndCustomToolCallOutput], Field(description='The output from the function call generated by your code.\nCan be a string or an list of output content.')]

The output from the function call generated by your code. Can be a string or an list of output content.

created_by Annotated[str | None, Field(description='The identifier of the actor that created the item.')]

The identifier of the actor that created the item.

InputMessage

Bases: BaseAPITypeExtra

InputMessage from the OpenAI API (upstream: InputMessage).

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

Attributes:

Name Type Description
type Annotated[Literal['message'] | None, Field(description='The type of the message input. Always set to `message`.')]

The type of the message input. Always set to message.

role Annotated[str, Field(description='The role of the message input. One of `user`, `system`, or `developer`.')]

The role of the message input. One of user, system, or developer.

status Annotated[str | None, Field(description='The status of item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.')]

The status of item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

content InputMessageContentList

A list of one or many input items to the model, containing different content types.

LocalEnvironmentParam

Bases: BaseAPITypeExtra

LocalEnvironmentParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['local'], Field(description='Use a local computer environment.')]

Use a local computer environment.

skills Annotated[list[LocalSkillParam] | None, Field(description='An optional list of skills.', max_length=200)]

An optional list of skills.

LocalEnvironmentResource

Bases: BaseAPITypeExtra

LocalEnvironmentResource from the OpenAI API.

Represents the use of a local environment to perform shell actions.

Attributes:

Name Type Description
type Annotated[Literal['local'], Field(description='The environment type. Always `local`.')]

The environment type. Always local.

LocalSkillParam

Bases: BaseAPITypeExtra

LocalSkillParam from the OpenAI API.

Attributes:

Name Type Description
name Annotated[str, Field(description='The name of the skill.')]

The name of the skill.

description Annotated[str, Field(description='The description of the skill.')]

The description of the skill.

path Annotated[str, Field(description='The path to the directory containing the skill.')]

The path to the directory containing the skill.

MCPToolCall

Bases: BaseAPITypeExtra

An invocation of a tool on an MCP server.

Attributes:

Name Type Description
type Annotated[Literal['mcp_call'], Field(description='The type of the item. Always `mcp_call`.')]

The type of the item. Always mcp_call.

id Annotated[str, Field(description='The unique ID of the tool call.')]

The unique ID of the tool call.

server_label Annotated[str, Field(description='The label of the MCP server running the tool.')]

The label of the MCP server running the tool.

name Annotated[str, Field(description='The name of the tool that was run.')]

The name of the tool that was run.

arguments Annotated[str, Field(description='A JSON string of the arguments passed to the tool.')]

A JSON string of the arguments passed to the tool.

error Annotated[MCPToolCallError | None, Field(description='The error from the tool call, if any.')]

The error from the tool call, if any.

status Annotated[MCPToolCallStatus | None, Field(description='The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`.')]

The status of the tool call. One of in_progress, completed, incomplete, calling, or failed.

NamespaceToolParam

Bases: BaseAPITypeExtra

Groups function/custom tools under a shared namespace.

Attributes:

Name Type Description
type Annotated[Literal['namespace'], Field(description='The type of the tool. Always `namespace`.')]

The type of the tool. Always namespace.

name Annotated[str, Field(description='The namespace name used in tool calls (for example, `crm`).', min_length=1)]

The namespace name used in tool calls (for example, crm).

description Annotated[str, Field(description='A description of the namespace shown to the model.')]

A description of the namespace shown to the model.

tools Annotated[list[NamespaceToolParamTools], Field(description='The function/custom tools available inside this namespace.', min_length=1)]

The function/custom tools available inside this namespace.

OutputMessage

Bases: BaseAPITypeExtra

An output message from the model.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of the output message.')]

The unique ID of the output message.

type Annotated[Literal['message'], Field(description='The type of the output message. Always `message`.')]

The type of the output message. Always message.

role Annotated[Literal['assistant'], Field(description='The role of the output message. Always `assistant`.')]

The role of the output message. Always assistant.

content Annotated[list[OutputMessageContent], Field(description='The content of the output message.')]

The content of the output message.

phase MessagePhase | None

Labels an assistant message as intermediate commentary (commentary) or the final answer (final_answer). For models like gpt-5.3-codex and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages.

status Annotated[str, Field(description='The status of the message input. One of `in_progress`, `completed`, or\n`incomplete`. Populated when input items are returned via API.')]

The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.

OutputTextContent

Bases: BaseAPITypeExtra

A text output from the model.

Attributes:

Name Type Description
type Annotated[Literal['output_text'], Field(description='The type of the output text. Always `output_text`.')]

The type of the output text. Always output_text.

text Annotated[str, Field(description='The text output from the model.')]

The text output from the model.

annotations Annotated[list[Annotation], Field(description='The annotations of the text output.')]

The annotations of the text output.

logprobs list[LogProb]

The log probability of a token.

Program

Bases: BaseAPITypeExtra

Program from the OpenAI API (upstream: Program).

Attributes:

Name Type Description
type Annotated[Literal['program'], Field(description='The type of the item. Always `program`.')]

The type of the item. Always program.

id Annotated[str, Field(description='The unique ID of the program item.')]

The unique ID of the program item.

call_id Annotated[str, Field(description='The stable call ID of the program item.')]

The stable call ID of the program item.

code Annotated[str, Field(description='The JavaScript source executed by programmatic tool calling.')]

The JavaScript source executed by programmatic tool calling.

fingerprint Annotated[str, Field(description='Opaque program replay fingerprint that must be round-tripped.')]

Opaque program replay fingerprint that must be round-tripped.

ProgramOutput

Bases: BaseAPITypeExtra

ProgramOutput from the OpenAI API (upstream: ProgramOutput).

Attributes:

Name Type Description
type Annotated[Literal['program_output'], Field(description='The type of the item. Always `program_output`.')]

The type of the item. Always program_output.

id Annotated[str, Field(description='The unique ID of the program output item.')]

The unique ID of the program output item.

call_id Annotated[str, Field(description='The call ID of the program item.')]

The call ID of the program item.

result Annotated[str, Field(description='The result produced by the program item.')]

The result produced by the program item.

status Annotated[ProgramOutputStatus, Field(description='The terminal status of the program output item.')]

The terminal status of the program output item.

ReasoningItem

Bases: BaseAPITypeExtra

ReasoningItem from the OpenAI API (upstream: ReasoningItem).

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

Attributes:

Name Type Description
type Annotated[Literal['reasoning'], Field(description='The type of the object. Always `reasoning`.')]

The type of the object. Always reasoning.

id Annotated[str, Field(description='The unique identifier of the reasoning content.')]

The unique identifier of the reasoning content.

summary Annotated[list[SummaryTextContent], Field(description='Reasoning summary content.')]

Reasoning summary content.

content Annotated[list[ReasoningTextContent] | None, Field(description='Reasoning text content.')]

Reasoning text content.

status Annotated[str | None, Field(description='The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.')]

The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.

ToolSearchCallItemParam

Bases: BaseAPITypeExtra

ToolSearchCallItemParam from the OpenAI API.

Attributes:

Name Type Description
call_id ToolSearchCallItemParamCallId | None

The unique ID of the tool search call generated by the model.

type Annotated[Literal['tool_search_call'], Field(description='The item type. Always `tool_search_call`.')]

The item type. Always tool_search_call.

execution Annotated[ToolSearchExecutionType | None, Field(description='Whether tool search was executed by the server or by the client.')]

Whether tool search was executed by the server or by the client.

arguments Annotated[EmptyModelParam, Field(description='The arguments supplied to the tool search call.')]

The arguments supplied to the tool search call.

ToolSearchOutput

Bases: BaseAPITypeExtra

ToolSearchOutput from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['tool_search_output'], Field(description='The type of the item. Always `tool_search_output`.')]

The type of the item. Always tool_search_output.

id Annotated[str, Field(description='The unique ID of the tool search output item.')]

The unique ID of the tool search output item.

execution Annotated[ToolSearchExecutionType, Field(description='Whether tool search was executed by the server or by the client.')]

Whether tool search was executed by the server or by the client.

tools Annotated[list[Tool], Field(description='The loaded tool definitions returned by tool search.')]

The loaded tool definitions returned by tool search.

status Annotated[FunctionCallOutputStatusEnum, Field(description='The status of the tool search output item that was recorded.')]

The status of the tool search output item that was recorded.

created_by Annotated[str | None, Field(description='The identifier of the actor that created the item.')]

The identifier of the actor that created the item.

ToolSearchOutputItemParam

Bases: BaseAPITypeExtra

ToolSearchOutputItemParam from the OpenAI API.

Attributes:

Name Type Description
call_id ToolSearchOutputItemParamCallId | None

The unique ID of the tool search call generated by the model.

type Annotated[Literal['tool_search_output'], Field(description='The item type. Always `tool_search_output`.')]

The item type. Always tool_search_output.

execution Annotated[ToolSearchExecutionType | None, Field(description='Whether tool search was executed by the server or by the client.')]

Whether tool search was executed by the server or by the client.

tools Annotated[list[ToolSearchOutputTool], Field(description='The loaded tool definitions returned by the tool search output.')]

The loaded tool definitions returned by the tool search output.

ToolSearchOutputNamespaceToolParam

Bases: BaseAPITypeExtra

Groups function/custom tools under a shared namespace.

Attributes:

Name Type Description
type Annotated[Literal['namespace'], Field(description='The type of the tool. Always `namespace`.')]

The type of the tool. Always namespace.

name Annotated[str, Field(description='The namespace name used in tool calls (for example, `crm`).', min_length=1)]

The namespace name used in tool calls (for example, crm).

description Annotated[str, Field(description='A description of the namespace shown to the model.')]

A description of the namespace shown to the model.

tools Annotated[list[ToolSearchOutputNamespaceToolParamTools], Field(description='The function/custom tools loaded inside this namespace.', min_length=1)]

The function/custom tools loaded inside this namespace.

UrlCitationBody

Bases: BaseAPITypeExtra

A citation for a web resource used to generate a model response.

Attributes:

Name Type Description
type Annotated[Literal['url_citation'], Field(description='The type of the URL citation. Always `url_citation`.')]

The type of the URL citation. Always url_citation.

url Annotated[AnyUrl, Field(description='The URL of the web resource.')]

The URL of the web resource.

start_index Annotated[int, Field(description='The index of the first character of the URL citation in the message.')]

The index of the first character of the URL citation in the message.

end_index Annotated[int, Field(description='The index of the last character of the URL citation in the message.')]

The index of the last character of the URL citation in the message.

title Annotated[str, Field(description='The title of the web resource.')]

The title of the web resource.

WebSearchToolCall

Bases: BaseAPITypeExtra

The results of a web search tool call.

See the web search guide for more information.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of the web search tool call.')]

The unique ID of the web search tool call.

type Annotated[Literal['web_search_call'], Field(description='The type of the web search tool call. Always `web_search_call`.')]

The type of the web search tool call. Always web_search_call.

status Annotated[WebSearchCallStatus, Field(description='The status of the web search tool call.')]

The status of the web search tool call.

action Annotated[Annotated[Annotated[WebSearchActionSearch, Tag('0')] | Annotated[WebSearchActionOpenPage, Tag('1')] | Annotated[WebSearchActionFind, Tag('2')] | Annotated[UnknownVariant, Tag(UNKNOWN)], Discriminator(by_type({'search': '0', 'open_page': '1', 'find_in_page': '2'}))] | None, Field(description='An object describing the specific action taken in this web search call.\nIncludes details on how the model used the web (search, open_page, find_in_page).')]

An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page).

ApplyPatchToolParam

Bases: BaseAPITypeExtra

ApplyPatchToolParam from the OpenAI API.

Allows the assistant to create, delete, or update files using unified diffs.

Attributes:

Name Type Description
type Annotated[Literal['apply_patch'], Field(description='The type of the tool. Always `apply_patch`.')]

The type of the tool. Always apply_patch.

allowed_callers ApplyPatchToolParamAllowedCallers | None

The tool invocation context(s).

ApproximateLocation

Bases: BaseAPITypeExtra

ApproximateLocation from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['approximate'], Field(description='The type of location approximation. Always `approximate`.')]

The type of location approximation. Always approximate.

ClickParam

Bases: BaseAPITypeExtra

A click action.

Attributes:

Name Type Description
type Annotated[Literal['click'], Field(description='Specifies the event type. For a click action, this property is always `click`.')]

Specifies the event type. For a click action, this property is always click.

button Annotated[ClickButtonType, Field(description='Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.')]

Indicates which mouse button was pressed during the click. One of left, right, wheel, back, or forward.

x Annotated[int, Field(description='The x-coordinate where the click occurred.')]

The x-coordinate where the click occurred.

y Annotated[int, Field(description='The y-coordinate where the click occurred.')]

The y-coordinate where the click occurred.

CodeInterpreterOutputLogs

Bases: BaseAPITypeExtra

The logs output from the code interpreter.

Attributes:

Name Type Description
type Annotated[Literal['logs'], Field(description='The type of the output. Always `logs`.')]

The type of the output. Always logs.

logs Annotated[str, Field(description='The logs output from the code interpreter.')]

The logs output from the code interpreter.

ComparisonFilter

Bases: BaseAPITypeExtra

ComparisonFilter from the OpenAI API.

A filter used to compare a specified attribute key to a given value using a defined comparison operation.

Attributes:

Name Type Description
type Annotated[str, Field(description='Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`.\n- `eq`: equals\n- `ne`: not equal\n- `gt`: greater than\n- `gte`: greater than or equal\n- `lt`: less than\n- `lte`: less than or equal\n- `in`: in\n- `nin`: not in')]

Specifies the comparison operator: eq, ne, gt, gte, lt, lte, in, nin. - eq: equals - ne: not equal - gt: greater than - gte: greater than or equal - lt: less than - lte: less than or equal - in: in - nin: not in

key Annotated[str, Field(description='The key to compare against the value.')]

The key to compare against the value.

value Annotated[str | float | bool | list[str | float], Field(description='The value to compare against the attribute key; supports string, number, or boolean types.')]

The value to compare against the attribute key; supports string, number, or boolean types.

CompoundFilter

Bases: BaseAPITypeExtra

Combine multiple filters using and or or.

Attributes:

Name Type Description
type Annotated[str, Field(description='Type of operation: `and` or `or`.')]

Type of operation: and or or.

filters Annotated[list[ComparisonFilter | CompoundFilter], Field(description='Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.')]

Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.

ComputerTool

Bases: BaseAPITypeExtra

A tool that controls a virtual computer.

Learn more about the computer tool.

Attributes:

Name Type Description
type Annotated[Literal['computer'], Field(description='The type of the computer tool. Always `computer`.')]

The type of the computer tool. Always computer.

ComputerUsePreviewTool

Bases: BaseAPITypeExtra

A tool that controls a virtual computer.

Learn more about the computer tool.

Attributes:

Name Type Description
type Annotated[Literal['computer_use_preview'], Field(description='The type of the computer use tool. Always `computer_use_preview`.')]

The type of the computer use tool. Always computer_use_preview.

environment Annotated[ComputerEnvironment, Field(description='The type of computer environment to control.')]

The type of computer environment to control.

display_width Annotated[int, Field(description='The width of the computer display.')]

The width of the computer display.

display_height Annotated[int, Field(description='The height of the computer display.')]

The height of the computer display.

ContainerNetworkPolicyAllowlistParam

Bases: BaseAPITypeExtra

ContainerNetworkPolicyAllowlistParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['allowlist'], Field(description='Allow outbound network access only to specified domains. Always `allowlist`.')]

Allow outbound network access only to specified domains. Always allowlist.

allowed_domains Annotated[list[str], Field(description='A list of allowed domains when type is `allowlist`.', min_length=1)]

A list of allowed domains when type is allowlist.

domain_secrets Annotated[list[ContainerNetworkPolicyDomainSecretParam] | None, Field(description='Optional domain-scoped secrets for allowlisted domains.', min_length=1)]

Optional domain-scoped secrets for allowlisted domains.

ContainerNetworkPolicyDisabledParam

Bases: BaseAPITypeExtra

ContainerNetworkPolicyDisabledParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['disabled'], Field(description='Disable outbound network access. Always `disabled`.')]

Disable outbound network access. Always disabled.

ContainerNetworkPolicyDomainSecretParam

Bases: BaseAPITypeExtra

ContainerNetworkPolicyDomainSecretParam from the OpenAI API.

Attributes:

Name Type Description
domain Annotated[str, Field(description='The domain associated with the secret.', min_length=1)]

The domain associated with the secret.

name Annotated[str, Field(description='The name of the secret to inject for the domain.', min_length=1)]

The name of the secret to inject for the domain.

value Annotated[str, Field(description='The secret value to inject for the domain.', max_length=10485760, min_length=1)]

The secret value to inject for the domain.

CoordParam

Bases: BaseAPITypeExtra

An x/y coordinate pair, e.g.

{ x: 100, y: 200 }.

Attributes:

Name Type Description
x Annotated[int, Field(description='The x-coordinate.')]

The x-coordinate.

y Annotated[int, Field(description='The y-coordinate.')]

The y-coordinate.

CustomGrammarFormatParam

Bases: BaseAPITypeExtra

A grammar defined by the user.

Attributes:

Name Type Description
type Annotated[Literal['grammar'], Field(description='Grammar format. Always `grammar`.')]

Grammar format. Always grammar.

syntax Annotated[GrammarSyntax1, Field(description='The syntax of the grammar definition. One of `lark` or `regex`.')]

The syntax of the grammar definition. One of lark or regex.

definition Annotated[str, Field(description='The grammar definition.')]

The grammar definition.

CustomTextFormatParam

Bases: BaseAPITypeExtra

Unconstrained free-form text.

Attributes:

Name Type Description
type Annotated[Literal['text'], Field(description='Unconstrained text format. Always `text`.')]

Unconstrained text format. Always text.

DirectToolCallCaller

Bases: BaseAPITypeExtra

DirectToolCallCaller from the OpenAI API.

DirectToolCallCallerParam

Bases: BaseAPITypeExtra

DirectToolCallCallerParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['direct'], Field(description='The caller type. Always `direct`.')]

The caller type. Always direct.

DoubleClickAction

Bases: BaseAPITypeExtra

A double click action.

Attributes:

Name Type Description
type Annotated[Literal['double_click'], Field(description='Specifies the event type. For a double click action, this property is always set to `double_click`.')]

Specifies the event type. For a double click action, this property is always set to double_click.

x Annotated[int, Field(description='The x-coordinate where the double click occurred.')]

The x-coordinate where the double click occurred.

y Annotated[int, Field(description='The y-coordinate where the double click occurred.')]

The y-coordinate where the double click occurred.

DragParam

Bases: BaseAPITypeExtra

A drag action.

Attributes:

Name Type Description
type Annotated[Literal['drag'], Field(description='Specifies the event type. For a drag action, this property is always set to `drag`.')]

Specifies the event type. For a drag action, this property is always set to drag.

path Annotated[list[CoordParam], Field(description='An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg\n```\n[\n { x: 100, y: 200 },\n { x: 200, y: 300 }\n]\n```')]

An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg [ { x: 100, y: 200 }, { x: 200, y: 300 } ]

EmptyModelParam

Bases: BaseAPITypeExtra

EmptyModelParam from the OpenAI API.

FileSearchTool

Bases: BaseAPITypeExtra

A tool that searches for relevant content from uploaded files.

Learn more about the file search tool.

Attributes:

Name Type Description
type Annotated[Literal['file_search'], Field(description='The type of the file search tool. Always `file_search`.')]

The type of the file search tool. Always file_search.

vector_store_ids Annotated[list[str], Field(description='The IDs of the vector stores to search.')]

The IDs of the vector stores to search.

max_num_results Annotated[int | None, Field(description='The maximum number of results to return. This number should be between 1 and 50 inclusive.')]

The maximum number of results to return. This number should be between 1 and 50 inclusive.

ranking_options Annotated[RankingOptions | None, Field(description='Ranking options for search.')]

Ranking options for search.

FileSearchToolCall

Bases: BaseAPITypeExtra

The results of a file search tool call.

See the file search guide for more information.

Attributes:

Name Type Description
id Annotated[str, Field(description='The unique ID of the file search tool call.')]

The unique ID of the file search tool call.

type Annotated[Literal['file_search_call'], Field(description='The type of the file search tool call. Always `file_search_call`.')]

The type of the file search tool call. Always file_search_call.

status Annotated[str, Field(description='The status of the file search tool call. One of `in_progress`,\n`searching`, `incomplete` or `failed`,')]

The status of the file search tool call. One of in_progress, searching, incomplete or failed,

queries Annotated[list[str], Field(description='The queries used to search for files.')]

The queries used to search for files.

FunctionShellAction

Bases: BaseAPITypeExtra

Execute a shell command.

FunctionShellActionParam

Bases: BaseAPITypeExtra

Commands and limits describing how to run the shell tool call.

Attributes:

Name Type Description
commands Annotated[list[str], Field(description='Ordered shell commands for the execution environment to run.')]

Ordered shell commands for the execution environment to run.

FunctionTool

Bases: BaseAPITypeExtra

Defines a function in your own code the model can choose to call.

Learn more about function calling.

Attributes:

Name Type Description
type Annotated[Literal['function'], Field(description='The type of the function tool. Always `function`.')]

The type of the function tool. Always function.

name Annotated[str, Field(description='The name of the function to call.')]

The name of the function to call.

defer_loading Annotated[bool | None, Field(description='Whether this function is deferred and loaded via tool search.')]

Whether this function is deferred and loaded via tool search.

FunctionToolParam

Bases: BaseAPITypeExtra

FunctionToolParam from the OpenAI API.

Attributes:

Name Type Description
async_ Annotated[bool | None, Field(validation_alias='async', description='Whether the tool response can be returned asynchronously versus immediately returned on next response creation.', serialization_alias='async')]

Whether the tool response can be returned asynchronously versus immediately returned on next response creation.

defer_loading Annotated[bool | None, Field(description='Whether this function should be deferred and discovered via tool search.')]

Whether this function should be deferred and discovered via tool search.

allowed_callers FunctionToolParamAllowedCallers | None

The tool invocation context(s).

HTTPError

Bases: BaseAPITypeExtra

HTTPError from the OpenAI API (upstream: HTTPError).

HybridSearchOptions

Bases: BaseAPITypeExtra

HybridSearchOptions from the OpenAI API.

Attributes:

Name Type Description
embedding_weight Annotated[float, Field(description='The weight of the embedding in the reciprocal ranking fusion.')]

The weight of the embedding in the reciprocal ranking fusion.

text_weight Annotated[float, Field(description='The weight of the text in the reciprocal ranking fusion.')]

The weight of the text in the reciprocal ranking fusion.

ImageGenTool

Bases: BaseAPITypeExtra

A tool that generates images using the GPT image models.

Attributes:

Name Type Description
type Annotated[Literal['image_generation'], Field(description='The type of the image generation tool. Always `image_generation`.')]

The type of the image generation tool. Always image_generation.

complexity Annotated[str | None, Field(description="Computation spent planning the image, independently of rendering quality.\nOverrides the outer response's `reasoning.effort` for image generation.\nWhen omitted, inherits a supported outer reasoning effort or uses the\nimage model's configured default.\nFor SVG output, controls the reference image, not the SVG author's\nreasoning.")]

Computation spent planning the image, independently of rendering quality. Overrides the outer response's reasoning.effort for image generation. When omitted, inherits a supported outer reasoning effort or uses the image model's configured default. For SVG output, controls the reference image, not the SVG author's reasoning.

quality Annotated[str, Field(description='The quality of the generated image. The GPT image models support `low`,\n`medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`,\nincluding their `2026-09-08` snapshots, also support `xhigh` and `max`.\nDefault: `auto`.')]

The quality of the generated image. The GPT image models support low, medium, and high. gpt-image-2.5-sunburst and gpt-image-2.5-flare, including their 2026-09-08 snapshots, also support xhigh and max. Default: auto.

size Annotated[str, Field(description="The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing.")]

The size of the generated images. For gpt-image-2, gpt-image-2-2026-04-21, gpt-image-2.5-sunburst, gpt-image-2.5-sunburst-2026-09-08, gpt-image-2.5-flare, and gpt-image-2.5-flare-2026-09-08, arbitrary resolutions are supported as WIDTHxHEIGHT strings, for example 1536x864. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above 2560x1440 are experimental, and the maximum supported resolution is 3840x2160. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes 1024x1024, 1536x1024, and 1024x1536 are supported by the GPT image models; auto is supported for models that allow automatic sizing.

output_format Annotated[str, Field(description='The output format of the generated image. One of `png`, `webp`, `jpeg`,\n`gif`, or `svg`. Default: `png`. GIF and SVG output require a model\nthat supports the selected format. GIF output does not support\npartial image streaming (`partial_images` greater than `0`),\n`input_image_mask`, or custom `output_compression`.\nResponses lifecycle events can still be streamed for GIF output.')]

The output format of the generated image. One of png, webp, jpeg, gif, or svg. Default: png. GIF and SVG output require a model that supports the selected format. GIF output does not support partial image streaming (partial_images greater than 0), input_image_mask, or custom output_compression. Responses lifecycle events can still be streamed for GIF output.

frame_count Annotated[int, Field(description='Number of GIF frames. Requires `output_format` to be `gif`. Default: 9.', ge=2, le=16)]

Number of GIF frames. Requires output_format to be gif. Default: 9.

frame_duration_ms Annotated[int, Field(description='Duration of each GIF frame in milliseconds, rounded to 10 ms.\nRequires `output_format` to be `gif`. Default: 200.', ge=20, le=2000)]

Duration of each GIF frame in milliseconds, rounded to 10 ms. Requires output_format to be gif. Default: 200.

svg Annotated[SvgParam | None, Field(description='SVG author model settings. Requires `output_format` to be `svg`.\nWhen SVG model selection is enabled, omitting this object uses the\nouter response model. Otherwise, the default SVG author is used and\nexplicit model overrides are unavailable.')]

SVG author model settings. Requires output_format to be svg. When SVG model selection is enabled, omitting this object uses the outer response model. Otherwise, the default SVG author is used and explicit model overrides are unavailable.

output_compression Annotated[int, Field(description='Compression level for the output image. Default: 100.', ge=0, le=100)]

Compression level for the output image. Default: 100.

moderation Annotated[str, Field(description='Moderation level for the generated image. Default: `auto`.')]

Moderation level for the generated image. Default: auto.

background Annotated[str, Field(description='Set the background of the generated image. One of `transparent`, `opaque`,\nor `auto`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including\ntheir `2026-09-08` snapshots, support `opaque` and `transparent`\nbackgrounds. Transparent backgrounds are available for supported GPT Image\nmodels. For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in\npreview. When using `transparent`, set the output format to `png` or `webp`.\nDefault: `auto`.')]

Set the background of the generated image. One of transparent, opaque, or auto. gpt-image-2.5-sunburst and gpt-image-2.5-flare, including their 2026-09-08 snapshots, support opaque and transparent backgrounds. Transparent backgrounds are available for supported GPT Image models. For gpt-image-2 and gpt-image-2-2026-04-21, this support is in preview. When using transparent, set the output format to png or webp. Default: auto.

input_fidelity InputFidelity | None

Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports high and low on gpt-image-1.5; gpt-image-1-mini supports only low. For gpt-image-2, omit this parameter. Defaults to low on supported models.

input_image_mask Annotated[ImageGenToolInputImageMask | None, Field(description='Optional mask for inpainting. Contains `image_url`\n(string, optional) and `file_id` (string, optional).')]

Optional mask for inpainting. Contains image_url (string, optional) and file_id (string, optional).

partial_images Annotated[int, Field(description='Number of partial images to generate in streaming mode, from 0 (default value) to 3.', ge=0, le=3)]

Number of partial images to generate in streaming mode, from 0 (default value) to 3.

action Annotated[ImageGenActionEnum | None, Field(description='Whether to generate a new image or edit an existing image. Default: `auto`.')]

Whether to generate a new image or edit an existing image. Default: auto.

ImageGenToolCall

Bases: BaseAPITypeExtra

An image generation request made by the model.

Attributes:

Name Type Description
type Annotated[Literal['image_generation_call'], Field(description='The type of the image generation call. Always `image_generation_call`.')]

The type of the image generation call. Always image_generation_call.

id Annotated[str, Field(description='The unique ID of the image generation call.')]

The unique ID of the image generation call.

status Annotated[str, Field(description='The status of the image generation call.')]

The status of the image generation call.

error Annotated[ImageGenToolCallError | None, Field(description='Details of a moderation failure, when available.')]

Details of a moderation failure, when available.

ImageGenToolCallError

Bases: BaseAPITypeExtra

ImageGenToolCallError from the OpenAI API.

Attributes:

Name Type Description
type Annotated[str, Field(description='The error type.')]

The error type.

message Annotated[str, Field(description='A description of the error.')]

A description of the error.

moderation_details Annotated[ImageGenToolCallModerationDetails | None, Field(description='Public details for a `moderation_blocked` error, when available.')]

Public details for a moderation_blocked error, when available.

ImageGenToolCallModerationDetails

Bases: BaseAPITypeExtra

ImageGenToolCallModerationDetails from the OpenAI API.

Attributes:

Name Type Description
moderation_stage Annotated[str, Field(description='The stage where moderation blocked the image generation call.')]

The stage where moderation blocked the image generation call.

categories Annotated[list[str], Field(description='Public moderation categories. New category values may be added over time.')]

Public moderation categories. New category values may be added over time.

InlineSkillParam

Bases: BaseAPITypeExtra

InlineSkillParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['inline'], Field(description='Defines an inline skill for this request.')]

Defines an inline skill for this request.

name Annotated[str, Field(description='The name of the skill.')]

The name of the skill.

description Annotated[str, Field(description='The description of the skill.')]

The description of the skill.

source Annotated[InlineSkillSourceParam, Field(description='Inline skill payload')]

Inline skill payload

InlineSkillSourceParam

Bases: BaseAPITypeExtra

Inline skill payload.

Attributes:

Name Type Description
type Annotated[Literal['base64'], Field(description='The type of the inline skill source. Must be `base64`.')]

The type of the inline skill source. Must be base64.

media_type Annotated[Literal['application/zip'], Field(description='The media type of the inline skill payload. Must be `application/zip`.')]

The media type of the inline skill payload. Must be application/zip.

data Annotated[str, Field(description='Base64-encoded skill zip bundle.', max_length=70254592, min_length=1)]

Base64-encoded skill zip bundle.

KeyPressAction

Bases: BaseAPITypeExtra

A collection of keypresses the model would like to perform.

Attributes:

Name Type Description
type Annotated[Literal['keypress'], Field(description='Specifies the event type. For a keypress action, this property is always set to `keypress`.')]

Specifies the event type. For a keypress action, this property is always set to keypress.

keys Annotated[list[str], Field(description='The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.')]

The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.

LocalShellExecAction

Bases: BaseAPITypeExtra

Execute a shell command on the server.

Attributes:

Name Type Description
type Annotated[Literal['exec'], Field(description='The type of the local shell action. Always `exec`.')]

The type of the local shell action. Always exec.

command Annotated[list[str], Field(description='The command to run.')]

The command to run.

env Annotated[dict[str, str], Field(description='Environment variables to set for the command.')]

Environment variables to set for the command.

LocalShellToolCall

Bases: BaseAPITypeExtra

A tool call to run a command on the local shell.

Attributes:

Name Type Description
type Annotated[Literal['local_shell_call'], Field(description='The type of the local shell call. Always `local_shell_call`.')]

The type of the local shell call. Always local_shell_call.

id Annotated[str, Field(description='The unique ID of the local shell call.')]

The unique ID of the local shell call.

call_id Annotated[str, Field(description='The unique ID of the local shell tool call generated by the model.')]

The unique ID of the local shell tool call generated by the model.

action LocalShellExecAction

Execute a shell command on the server.

status Annotated[str, Field(description='The status of the local shell call.')]

The status of the local shell call.

LocalShellToolCallOutput

Bases: BaseAPITypeExtra

The output of a local shell tool call.

Attributes:

Name Type Description
type Annotated[Literal['local_shell_call_output'], Field(description='The type of the local shell tool call output. Always `local_shell_call_output`.')]

The type of the local shell tool call output. Always local_shell_call_output.

id Annotated[str, Field(description='The unique ID of the local shell tool call generated by the model.')]

The unique ID of the local shell tool call generated by the model.

output Annotated[str, Field(description='A JSON string of the output of the local shell tool call.')]

A JSON string of the output of the local shell tool call.

LocalShellToolParam

Bases: BaseAPITypeExtra

LocalShellToolParam from the OpenAI API.

A tool that allows the model to execute shell commands in a local environment.

Attributes:

Name Type Description
type Annotated[Literal['local_shell'], Field(description='The type of the local shell tool. Always `local_shell`.')]

The type of the local shell tool. Always local_shell.

MCPApprovalRequest

Bases: BaseAPITypeExtra

A request for human approval of a tool invocation.

Attributes:

Name Type Description
type Annotated[Literal['mcp_approval_request'], Field(description='The type of the item. Always `mcp_approval_request`.')]

The type of the item. Always mcp_approval_request.

id Annotated[str, Field(description='The unique ID of the approval request.')]

The unique ID of the approval request.

server_label Annotated[str, Field(description='The label of the MCP server making the request.')]

The label of the MCP server making the request.

name Annotated[str, Field(description='The name of the tool to run.')]

The name of the tool to run.

arguments Annotated[str, Field(description='A JSON string of arguments for the tool.')]

A JSON string of arguments for the tool.

MCPApprovalResponse

Bases: BaseAPITypeExtra

A response to an MCP approval request.

Attributes:

Name Type Description
type Annotated[Literal['mcp_approval_response'], Field(description='The type of the item. Always `mcp_approval_response`.')]

The type of the item. Always mcp_approval_response.

approval_request_id Annotated[str, Field(description='The ID of the approval request being answered.')]

The ID of the approval request being answered.

approve Annotated[bool, Field(description='Whether the request was approved.')]

Whether the request was approved.

MCPApprovalResponseResource

Bases: BaseAPITypeExtra

A response to an MCP approval request.

Attributes:

Name Type Description
type Annotated[Literal['mcp_approval_response'], Field(description='The type of the item. Always `mcp_approval_response`.')]

The type of the item. Always mcp_approval_response.

id Annotated[str, Field(description='The unique ID of the approval response')]

The unique ID of the approval response

approval_request_id Annotated[str, Field(description='The ID of the approval request being answered.')]

The ID of the approval request being answered.

approve Annotated[bool, Field(description='Whether the request was approved.')]

Whether the request was approved.

MCPListTools

Bases: BaseAPITypeExtra

A list of tools available on an MCP server.

Attributes:

Name Type Description
type Annotated[Literal['mcp_list_tools'], Field(description='The type of the item. Always `mcp_list_tools`.')]

The type of the item. Always mcp_list_tools.

id Annotated[str, Field(description='The unique ID of the list.')]

The unique ID of the list.

server_label Annotated[str, Field(description='The label of the MCP server.')]

The label of the MCP server.

tools Annotated[list[MCPListToolsTool], Field(description='The tools available on the server.')]

The tools available on the server.

MCPListToolsTool

Bases: BaseAPITypeExtra

A tool available on an MCP server.

Attributes:

Name Type Description
name Annotated[str, Field(description='The name of the tool.')]

The name of the tool.

input_schema Annotated[dict[str, Any], Field(description="The JSON schema describing the tool's input.")]

The JSON schema describing the tool's input.

MCPProtocolError

Bases: BaseAPITypeExtra

MCPProtocolError from the OpenAI API.

MCPTool

Bases: BaseAPITypeExtra

MCPTool from the OpenAI API (upstream: MCPTool).

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.

Attributes:

Name Type Description
type Annotated[Literal['mcp'], Field(description='The type of the MCP tool. Always `mcp`.')]

The type of the MCP tool. Always mcp.

server_label Annotated[str, Field(description='A label for this MCP server, used to identify it in tool calls.')]

A label for this MCP server, used to identify it in tool calls.

server_url Annotated[AnyUrl | None, Field(description='The URL for the MCP server. One of `server_url`, `connector_id`, or\n`tunnel_id` must be provided.')]

The URL for the MCP server. One of server_url, connector_id, or tunnel_id must be provided.

connector_id Annotated[str | None, Field(deprecated=True, description='Identifier for service connectors, like those available in ChatGPT. One of\n`server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more\nabout service connectors [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors).\n\nThis field is deprecated for models released after September 1, 2026.\nUse `server_url` to connect to a remote MCP server, or `tunnel_id` to\nconnect through a Secure MCP Tunnel.\n\nCurrently supported `connector_id` values are:\n\n- Dropbox: `connector_dropbox`\n- Gmail: `connector_gmail`\n- Google Calendar: `connector_googlecalendar`\n- Google Drive: `connector_googledrive`\n- Microsoft Teams: `connector_microsoftteams`\n- Outlook Calendar: `connector_outlookcalendar`\n- Outlook Email: `connector_outlookemail`\n- SharePoint: `connector_sharepoint`')]

Identifier for service connectors, like those available in ChatGPT. One of server_url, connector_id, or tunnel_id must be provided. Learn more about service connectors

here. This field is deprecated for models released after September 1, 2026. Use server_url to connect to a remote MCP server, or tunnel_id to connect through a Secure MCP Tunnel. Currently supported connector_id values are: - Dropbox: connector_dropbox - Gmail: connector_gmail - Google Calendar: connector_googlecalendar - Google Drive: connector_googledrive - Microsoft Teams: connector_microsoftteams - Outlook Calendar: connector_outlookcalendar - Outlook Email: connector_outlookemail - SharePoint: connector_sharepoint tunnel_id: The Secure MCP Tunnel ID to use instead of a direct server URL. One of server_url, connector_id, or tunnel_id must be provided. authorization: An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here. server_description: Optional description of the MCP server, used to provide more context. allowed_tools: A filter object to specify which tools are allowed. allowed_callers: The tool invocation context(s). require_approval: Specify which of the MCP server's tools require approval. Can be always, never, or a filter object associated with tools that require approval. defer_loading: Whether this MCP tool is deferred and discovered via tool search.

MCPToolExecutionError

Bases: BaseAPITypeExtra

MCPToolExecutionError from the OpenAI API.

MCPToolFilter

Bases: BaseAPITypeExtra

A filter object to specify which tools are allowed.

Attributes:

Name Type Description
tool_names Annotated[list[str] | None, Field(description='List of allowed tool names.', title='MCP allowed tools')]

List of allowed tool names.

read_only Annotated[bool | None, Field(description='Indicates whether or not a tool modifies data or is read-only. If an\nMCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),\nit will match this filter.')]

Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with

readOnlyHint](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter.

MoveParam

Bases: BaseAPITypeExtra

A mouse move action.

Attributes:

Name Type Description
type Annotated[Literal['move'], Field(description='Specifies the event type. For a move action, this property is always set to `move`.')]

Specifies the event type. For a move action, this property is always set to move.

x Annotated[int, Field(description='The x-coordinate to move to.')]

The x-coordinate to move to.

y Annotated[int, Field(description='The y-coordinate to move to.')]

The y-coordinate to move to.

ProgrammaticToolCallingParam

Bases: BaseAPITypeExtra

ProgrammaticToolCallingParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['programmatic_tool_calling'], Field(description='The type of the tool. Always `programmatic_tool_calling`.')]

The type of the tool. Always programmatic_tool_calling.

ProgramToolCallCaller

Bases: BaseAPITypeExtra

ProgramToolCallCaller from the OpenAI API.

Attributes:

Name Type Description
caller_id Annotated[str, Field(description='The call ID of the program item that produced this tool call.')]

The call ID of the program item that produced this tool call.

ProgramToolCallCallerParam

Bases: BaseAPITypeExtra

ProgramToolCallCallerParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['program'], Field(description='The caller type. Always `program`.')]

The caller type. Always program.

caller_id Annotated[str, Field(description='The call ID of the program item that produced this tool call.', max_length=64, min_length=1)]

The call ID of the program item that produced this tool call.

RankingOptions

Bases: BaseAPITypeExtra

RankingOptions from the OpenAI API.

Attributes:

Name Type Description
ranker Annotated[RankerVersionType | None, Field(description='The ranker to use for the file search.')]

The ranker to use for the file search.

score_threshold Annotated[float | None, Field(description='The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.')]

The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.

hybrid_search Annotated[HybridSearchOptions | None, Field(description='Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.')]

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

ScreenshotParam

Bases: BaseAPITypeExtra

A screenshot action.

Attributes:

Name Type Description
type Annotated[Literal['screenshot'], Field(description='Specifies the event type. For a screenshot action, this property is always set to `screenshot`.')]

Specifies the event type. For a screenshot action, this property is always set to screenshot.

ScrollParam

Bases: BaseAPITypeExtra

A scroll action.

Attributes:

Name Type Description
type Annotated[Literal['scroll'], Field(description='Specifies the event type. For a scroll action, this property is always set to `scroll`.')]

Specifies the event type. For a scroll action, this property is always set to scroll.

x Annotated[int, Field(description='The x-coordinate where the scroll occurred.')]

The x-coordinate where the scroll occurred.

y Annotated[int, Field(description='The y-coordinate where the scroll occurred.')]

The y-coordinate where the scroll occurred.

scroll_x Annotated[int, Field(description='The horizontal scroll distance.')]

The horizontal scroll distance.

scroll_y Annotated[int, Field(description='The vertical scroll distance.')]

The vertical scroll distance.

SkillReferenceParam

Bases: BaseAPITypeExtra

SkillReferenceParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['skill_reference'], Field(description='References a skill created with the /v1/skills endpoint.')]

References a skill created with the /v1/skills endpoint.

skill_id Annotated[str, Field(description='The ID of the referenced skill.', max_length=64, min_length=1)]

The ID of the referenced skill.

version Annotated[str | None, Field(description="Optional skill version. Use a positive integer or 'latest'. Omit for default.")]

Optional skill version. Use a positive integer or 'latest'. Omit for default.

SpecificApplyPatchParam

Bases: BaseAPITypeExtra

SpecificApplyPatchParam from the OpenAI API.

Forces the model to call the apply_patch tool when executing a tool call.

Attributes:

Name Type Description
type Annotated[Literal['apply_patch'], Field(description='The tool to call. Always `apply_patch`.')]

The tool to call. Always apply_patch.

SpecificFunctionShellParam

Bases: BaseAPITypeExtra

SpecificFunctionShellParam from the OpenAI API.

Forces the model to call the shell tool when a tool call is required.

Attributes:

Name Type Description
type Annotated[Literal['shell'], Field(description='The tool to call. Always `shell`.')]

The tool to call. Always shell.

SpecificProgrammaticToolCallingParam

Bases: BaseAPITypeExtra

SpecificProgrammaticToolCallingParam from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['programmatic_tool_calling'], Field(description='The tool to call. Always `programmatic_tool_calling`.')]

The tool to call. Always programmatic_tool_calling.

SvgParam

Bases: BaseAPITypeExtra

SvgParam from the OpenAI API (upstream: SvgParam).

Attributes:

Name Type Description
reasoning SvgReasoningParam | None

Reasoning effort for SVG authoring. When omitted, uses the author model's default in both Images and Responses.

SvgReasoningParam

Bases: BaseAPITypeExtra

Reasoning effort for SVG authoring.

When omitted, uses the author model's default in both Images and Responses.

ToolChoiceAllowed

Bases: BaseAPITypeExtra

Constrains the tools available to the model to a pre-defined set.

Attributes:

Name Type Description
type Annotated[Literal['allowed_tools'], Field(description='Allowed tool configuration type. Always `allowed_tools`.')]

Allowed tool configuration type. Always allowed_tools.

mode Annotated[str, Field(description='Constrains the tools available to the model to a pre-defined set.\n\n`auto` allows the model to pick from among the allowed tools and generate a\nmessage.\n\n`required` requires the model to call one or more of the allowed tools.')]

Constrains the tools available to the model to a pre-defined set. auto allows the model to pick from among the allowed tools and generate a message. required requires the model to call one or more of the allowed tools.

tools Annotated[list[dict[str, Any]], Field(description='A list of tool definitions that the model should be allowed to call.\n\nFor the Responses API, the list of tool definitions might look like:\n```json\n[\n { "type": "function", "name": "get_weather" },\n { "type": "mcp", "server_label": "deepwiki" },\n { "type": "image_generation" }\n]\n```')]

A list of tool definitions that the model should be allowed to call. For the Responses API, the list of tool definitions might look like: json [ { "type": "function", "name": "get_weather" }, { "type": "mcp", "server_label": "deepwiki" }, { "type": "image_generation" } ]

ToolChoiceCustom

Bases: BaseAPITypeExtra

ToolChoiceCustom from the OpenAI API.

Use this option to force the model to call a specific custom tool.

Attributes:

Name Type Description
type Annotated[Literal['custom'], Field(description='For custom tool calling, the type is always `custom`.')]

For custom tool calling, the type is always custom.

name Annotated[str, Field(description='The name of the custom tool to call.')]

The name of the custom tool to call.

ToolChoiceFunction

Bases: BaseAPITypeExtra

Use this option to force the model to call a specific function.

Attributes:

Name Type Description
type Annotated[Literal['function'], Field(description='For function calling, the type is always `function`.')]

For function calling, the type is always function.

name Annotated[str, Field(description='The name of the function to call.')]

The name of the function to call.

ToolChoiceMCP

Bases: BaseAPITypeExtra

ToolChoiceMCP from the OpenAI API (upstream: ToolChoiceMCP).

Use this option to force the model to call a specific tool on a remote MCP server.

Attributes:

Name Type Description
type Annotated[Literal['mcp'], Field(description='For MCP tools, the type is always `mcp`.')]

For MCP tools, the type is always mcp.

server_label Annotated[str, Field(description='The label of the MCP server to use.')]

The label of the MCP server to use.

ToolChoiceTypes

Bases: BaseAPITypeExtra

ToolChoiceTypes from the OpenAI API.

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

Attributes:

Name Type Description
type Annotated[str, Field(description='The type of hosted tool the model should to use. Learn more about\n[built-in tools](https://developers.openai.com/api/docs/guides/tools).\n\nAllowed values are:\n- `file_search`\n- `web_search_preview`\n- `computer`\n- `computer_use_preview`\n- `computer_use`\n- `code_interpreter`\n- `image_generation`')]

The type of hosted tool the model should to use. Learn more about [built-in

tools](https://developers.openai.com/api/docs/guides/tools). Allowed values are: - file_search - web_search_preview - computer - computer_use_preview - computer_use - code_interpreter - image_generation

ToolSearchCall

Bases: BaseAPITypeExtra

ToolSearchCall from the OpenAI API.

Attributes:

Name Type Description
type Annotated[Literal['tool_search_call'], Field(description='The type of the item. Always `tool_search_call`.')]

The type of the item. Always tool_search_call.

id Annotated[str, Field(description='The unique ID of the tool search call item.')]

The unique ID of the tool search call item.

execution Annotated[ToolSearchExecutionType, Field(description='Whether tool search was executed by the server or by the client.')]

Whether tool search was executed by the server or by the client.

arguments Annotated[Any, Field(description='Arguments used for the tool search call.')]

Arguments used for the tool search call.

status Annotated[FunctionCallStatus, Field(description='The status of the tool search call item that was recorded.')]

The status of the tool search call item that was recorded.

created_by Annotated[str | None, Field(description='The identifier of the actor that created the item.')]

The identifier of the actor that created the item.

ToolSearchOutputFunctionToolParam

Bases: BaseAPITypeExtra

ToolSearchOutputFunctionToolParam from the OpenAI API.

Attributes:

Name Type Description
name Annotated[str, Field(description='The name of the loaded function tool.', max_length=128, min_length=1, pattern='^(?![\\s\\S]*[\\r\\n])[a-zA-Z0-9_.-]+$')]

The name of the loaded function tool.

async_ Annotated[bool | None, Field(validation_alias='async', description='Whether the tool response can be returned asynchronously versus immediately returned on next response creation.', serialization_alias='async')]

Whether the tool response can be returned asynchronously versus immediately returned on next response creation.

defer_loading Annotated[bool | None, Field(description='Whether this function should be deferred and discovered via tool search.')]

Whether this function should be deferred and discovered via tool search.

allowed_callers ToolSearchOutputFunctionToolParamAllowedCallers | None

The tool invocation context(s).

ToolSearchToolParam

Bases: BaseAPITypeExtra

Hosted or BYOT tool search configuration for deferred tools.

Attributes:

Name Type Description
type Annotated[Literal['tool_search'], Field(description='The type of the tool. Always `tool_search`.')]

The type of the tool. Always tool_search.

execution Annotated[ToolSearchExecutionType | None, Field(description='Whether tool search is executed by the server or by the client.')]

Whether tool search is executed by the server or by the client.

TypeParam

Bases: BaseAPITypeExtra

An action to type in text.

Attributes:

Name Type Description
type Annotated[Literal['type'], Field(description='Specifies the event type. For a type action, this property is always set to `type`.')]

Specifies the event type. For a type action, this property is always set to type.

text Annotated[str, Field(description='The text to type.')]

The text to type.

WaitParam

Bases: BaseAPITypeExtra

A wait action.

Attributes:

Name Type Description
type Annotated[Literal['wait'], Field(description='Specifies the event type. For a wait action, this property is always set to `wait`.')]

Specifies the event type. For a wait action, this property is always set to wait.

WebSearchActionFind

Bases: BaseAPITypeExtra

WebSearchActionFind from the OpenAI API.

Action type "find_in_page": Searches for a pattern within a loaded page.

Attributes:

Name Type Description
type Annotated[Literal['find_in_page'], Field(description='The action type.')]

The action type.

url Annotated[AnyUrl | None, Field(description='The URL of the page searched for the pattern, when available.')]

The URL of the page searched for the pattern, when available.

pattern Annotated[str, Field(description='The pattern or text to search for within the page.')]

The pattern or text to search for within the page.

WebSearchActionOpenPage

Bases: BaseAPITypeExtra

WebSearchActionOpenPage from the OpenAI API.

Action type "open_page" - Opens a specific URL from search results.

Attributes:

Name Type Description
type Annotated[Literal['open_page'], Field(description='The action type.')]

The action type.

url Annotated[AnyUrl | None, Field(description='The URL opened by the model.')]

The URL opened by the model.

WebSearchActionSearch

Bases: BaseAPITypeExtra

Action type "search" - Performs a web search query.

Attributes:

Name Type Description
type Annotated[Literal['search'], Field(description='The action type.')]

The action type.

query Annotated[str | None, Field(deprecated=True, description='The search query.')]

The search query.

queries Annotated[list[str] | None, Field(description='The search queries.', title='Search queries')]

The search queries.

sources Annotated[list[WebSearchActionSearchSource] | None, Field(description='The sources used in the search.', title='Web search sources')]

The sources used in the search.

WebSearchPreviewTool

Bases: BaseAPITypeExtra

WebSearchPreviewTool from the OpenAI API.

This tool searches the web for relevant results to use in a response. Learn more about the web search tool.

Attributes:

Name Type Description
type Annotated[str, Field(description='The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.')]

The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11.

search_context_size Annotated[SearchContextSize | None, Field(description='High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.')]

High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.

WebSearchTool

Bases: BaseAPITypeExtra

Search the Internet for sources related to the prompt.

Learn more about the web search tool.

Attributes:

Name Type Description
type Annotated[str, Field(description='The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.')]

The type of the web search tool. One of web_search or web_search_2025_08_26.

external_web_access Annotated[bool, Field(description='Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content.')]

Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content.

filters WebSearchToolFilters | None

Filters for the search.

user_location Annotated[WebSearchApproximateLocation | None, Field(description='The approximate location of the user. If omitted or null, defaults to the\nUnited States. To avoid this fallback, pass `{"type": "approximate"}` without\nlocation fields. To localize results, provide the relevant location fields.')]

The approximate location of the user. If omitted or null, defaults to the United States. To avoid this fallback, pass {"type": "approximate"} without location fields. To localize results, provide the relevant location fields.

search_context_size Annotated[str, Field(description='High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.')]

High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.

CachedUsageDetails

Bases: BaseAPITypeExtra

CachedUsageDetails from the OpenAI API.

CacheWriteTokensDetails

Bases: BaseAPITypeExtra

CacheWriteTokensDetails from the OpenAI API.

Attributes:

Name Type Description
ttl_30m_tokens Annotated[int, Field(description='The number of input tokens written with 30-minute retention.')]

The number of input tokens written with 30-minute retention.

ttl_12h_tokens Annotated[int, Field(description='The number of input tokens written with 12-hour retention.')]

The number of input tokens written with 12-hour retention.

ImageGenInputUsageDetails

Bases: BaseAPITypeExtra

The input tokens detailed information for the image generation.

Attributes:

Name Type Description
text_tokens Annotated[int, Field(description='The number of text tokens in the input prompt.')]

The number of text tokens in the input prompt.

image_tokens Annotated[int, Field(description='The number of image tokens in the input prompt.')]

The number of image tokens in the input prompt.

ImageGenToolUsage

Bases: BaseAPITypeExtra

Token usage for image generation tool calls in a response.

Attributes:

Name Type Description
input_tokens Annotated[int, Field(description='The number of tokens (images and text) in the input prompt.')]

The number of tokens (images and text) in the input prompt.

total_tokens Annotated[int, Field(description='The total number of tokens (images and text) used for the image generation.')]

The total number of tokens (images and text) used for the image generation.

output_tokens Annotated[int, Field(description='The number of output tokens generated by the model.')]

The number of output tokens generated by the model.

output_tokens_details ImageGenOutputTokensDetails | None

The output token details for the image generation.

input_tokens_details ImageGenInputUsageDetails

The input tokens detailed information for the image generation.

ResponseToolUsage

Bases: BaseAPITypeExtra

ResponseToolUsage from the OpenAI API.

Aggregated usage details for billable tools that ran while generating the response.

Attributes:

Name Type Description
image_gen Annotated[ImageGenToolUsage, Field(description='Aggregated usage statistics for image generation tool calls.')]

Aggregated usage statistics for image generation tool calls.

web_search Annotated[WebSearchUsage, Field(description='Aggregated billable usage statistics for web search tool calls.')]

Aggregated billable usage statistics for web search tool calls.

ResponseUsage

Bases: BaseAPITypeExtra

ResponseUsage from the OpenAI API (upstream: ResponseUsage).

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

Attributes:

Name Type Description
input_tokens Annotated[int, Field(description='The number of input tokens.')]

The number of input tokens.

input_tokens_details Annotated[ResponseUsageInputTokensDetails, Field(description='A detailed breakdown of the input tokens.')]

A detailed breakdown of the input tokens.

output_tokens Annotated[int, Field(description='The number of output tokens.')]

The number of output tokens.

output_tokens_details Annotated[ResponseUsageOutputTokensDetails, Field(description='A detailed breakdown of the output tokens.')]

A detailed breakdown of the output tokens.

total_tokens Annotated[int, Field(description='The total number of tokens used.')]

The total number of tokens used.

SvgUsage

Bases: BaseAPITypeExtra

SvgUsage from the OpenAI API (upstream: SvgUsage).

WebSearchUsage

Bases: BaseAPITypeExtra

WebSearchUsage from the OpenAI API.

Usage details for web search requests that ran while generating the response.

Attributes:

Name Type Description
num_requests Annotated[int, Field(description='The number of billable web search requests issued.')]

The number of billable web search requests issued.