Implementation:Openai Openai python Response Input Item Param

Knowledge Sources	Openai_Openai_python
Domains	API_Types, Python
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete TypedDict parameter definitions for response input items provided by the openai-python SDK.

Description

The response_input_item_param.py module defines the TypedDict variants of all response input item types. These are the request/serialization counterparts to the Pydantic BaseModel classes in response_input_item.py. While the Pydantic models are used for deserializing API responses, these TypedDict classes are used for constructing request parameters with full type safety.

The central type is ResponseInputItemParam, a Union of 25 TypedDict classes that mirrors the structure of ResponseInputItem.

Key TypedDict classes defined in this module:

Message -- TypedDict with content: Required[ResponseInputMessageContentListParam], role: Required[Literal["user", "system", "developer"]], and optional status and type.
ComputerCallOutput -- TypedDict with required call_id, output (screenshot param), and type.
FunctionCallOutput -- TypedDict with required call_id, output (str or structured list), and type.
ImageGenerationCall -- TypedDict with required id, result, status, and type.
LocalShellCall / LocalShellCallOutput -- TypedDict variants for local shell commands.
ShellCall / ShellCallOutput -- TypedDict variants for remote shell execution.
ApplyPatchCall / ApplyPatchCallOutput -- TypedDict variants for file patch operations.
McpListTools -- TypedDict for MCP server tool listings.
McpApprovalRequest / McpApprovalResponse -- TypedDict variants for MCP approval flow.
McpCall -- TypedDict for MCP tool invocations.
ItemReference -- TypedDict for referencing existing items by ID.

The Required and Optional markers from typing_extensions indicate which fields must be provided vs. which can be omitted (using total=False semantics).

This file is auto-generated from the OpenAI API spec by the Stainless code generation toolchain.

Usage

Use these TypedDict types when constructing input items for the input parameter of client.responses.create(). They provide static type checking and IDE autocompletion for building well-formed request payloads. For working with API response data, use the Pydantic models from response_input_item.py.

Code Reference

Source Location

Repository: openai-python
File: src/openai/types/responses/response_input_item_param.py
Lines: 1-543

Signature

class Message(TypedDict, total=False):
    content: Required[ResponseInputMessageContentListParam]
    role: Required[Literal["user", "system", "developer"]]
    status: Literal["in_progress", "completed", "incomplete"]
    type: Literal["message"]

class ComputerCallOutput(TypedDict, total=False):
    call_id: Required[str]
    output: Required[ResponseComputerToolCallOutputScreenshotParam]
    type: Required[Literal["computer_call_output"]]
    id: Optional[str]
    acknowledged_safety_checks: Optional[Iterable[ComputerCallOutputAcknowledgedSafetyCheck]]
    status: Optional[Literal["in_progress", "completed", "incomplete"]]

class FunctionCallOutput(TypedDict, total=False):
    call_id: Required[str]
    output: Required[Union[str, ResponseFunctionCallOutputItemListParam]]
    type: Required[Literal["function_call_output"]]
    id: Optional[str]
    status: Optional[Literal["in_progress", "completed", "incomplete"]]

class ShellCall(TypedDict, total=False):
    action: Required[ShellCallAction]
    call_id: Required[str]
    type: Required[Literal["shell_call"]]
    id: Optional[str]
    environment: Optional[ShellCallEnvironment]
    status: Optional[Literal["in_progress", "completed", "incomplete"]]

class McpCall(TypedDict, total=False):
    id: Required[str]
    arguments: Required[str]
    name: Required[str]
    server_label: Required[str]
    type: Required[Literal["mcp_call"]]
    approval_request_id: Optional[str]
    error: Optional[str]
    output: Optional[str]
    status: Literal["in_progress", "completed", "incomplete", "calling", "failed"]

class ItemReference(TypedDict, total=False):
    id: Required[str]
    type: Optional[Literal["item_reference"]]

ResponseInputItemParam: TypeAlias = Union[
    EasyInputMessageParam, Message, ResponseOutputMessageParam,
    ResponseFileSearchToolCallParam, ResponseComputerToolCallParam,
    ComputerCallOutput, ResponseFunctionWebSearchParam,
    ResponseFunctionToolCallParam, FunctionCallOutput,
    ResponseReasoningItemParam, ResponseCompactionItemParamParam,
    ImageGenerationCall, ResponseCodeInterpreterToolCallParam,
    LocalShellCall, LocalShellCallOutput,
    ShellCall, ShellCallOutput,
    ApplyPatchCall, ApplyPatchCallOutput,
    McpListTools, McpApprovalRequest, McpApprovalResponse,
    McpCall, ResponseCustomToolCallOutputParam,
    ResponseCustomToolCallParam, ItemReference,
]

Import

from openai.types.responses.response_input_item_param import (
    ResponseInputItemParam,
    Message,
    ComputerCallOutput,
    FunctionCallOutput,
    McpCall,
    McpApprovalResponse,
    ItemReference,
)
# Or via the top-level re-export:
from openai.types.responses import ResponseInputItemParam

I/O Contract

Inputs

Name	Type	Required	Description
content	ResponseInputMessageContentListParam	Yes (Message)	List of typed content items for message input
role	Literal["user", "system", "developer"]	Yes (Message)	Role of the message sender
call_id	str	Yes (ComputerCallOutput, FunctionCallOutput, ShellCall, etc.)	ID of the tool call this output corresponds to
output	varies	Yes (FunctionCallOutput, ShellCallOutput, etc.)	The output content from a tool call
type	Literal[...]	Yes (most types)	Discriminator field identifying the input item type
id	str	Yes/Optional (varies)	Unique identifier for the input item
status	Literal[...]	No	Processing status of the item
arguments	str	Yes (McpCall, McpApprovalRequest)	JSON string of tool arguments
name	str	Yes (McpCall, McpApprovalRequest)	Name of the MCP tool
server_label	str	Yes (McpCall, McpListTools, McpApprovalRequest)	Label identifying the MCP server
approve	bool	Yes (McpApprovalResponse)	Whether the MCP tool call is approved
approval_request_id	str	Yes (McpApprovalResponse)	ID of the approval request being answered

Outputs

Name	Type	Description
ResponseInputItemParam	TypeAlias (Union)	Union of all 25 TypedDict input item parameter types for use in request construction
Message	TypedDict	User/system/developer message parameter with content and role
ComputerCallOutput	TypedDict	Computer tool call output parameter with screenshot
FunctionCallOutput	TypedDict	Function tool call output parameter with text or structured output
ImageGenerationCall	TypedDict	Image generation call parameter with result and status
ShellCall	TypedDict	Shell command execution parameter with action and environment
McpCall	TypedDict	MCP server tool invocation parameter
McpApprovalResponse	TypedDict	MCP approval response parameter with approve/deny decision
ItemReference	TypedDict	Item reference parameter for referencing existing items by ID

Usage Examples

Constructing a Message Input Item

from openai.types.responses.response_input_item_param import Message

message: Message = {
    "role": "user",
    "content": [
        {"type": "input_text", "text": "What is the capital of France?"}
    ],
    "type": "message",
}

Providing Function Call Output

from openai.types.responses.response_input_item_param import FunctionCallOutput

function_output: FunctionCallOutput = {
    "call_id": "call_abc123",
    "output": '{"temperature": 72, "unit": "fahrenheit"}',
    "type": "function_call_output",
}

Responding to MCP Approval Request

from openai.types.responses.response_input_item_param import McpApprovalResponse

approval: McpApprovalResponse = {
    "approval_request_id": "req_xyz789",
    "approve": True,
    "type": "mcp_approval_response",
    "reason": "Tool invocation looks safe.",
}

Building a Multi-Item Input List

from openai.types.responses.response_input_item_param import (
    ResponseInputItemParam,
    Message,
    FunctionCallOutput,
)

items: list[ResponseInputItemParam] = [
    {
        "role": "user",
        "content": [{"type": "input_text", "text": "Get the weather."}],
        "type": "message",
    },
    {
        "call_id": "call_abc123",
        "output": '{"temp": 72}',
        "type": "function_call_output",
    },
]

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment