ruby/resources/conversations/methods/create/index.md

Create a conversation

conversations.create(**kwargs) -> Conversation

post /conversations

Create a conversation.

Parameters

items: Array[ResponseInputItem]

Initial items to include in the conversation context. You may add up to 20 items at a time.
- class EasyInputMessage
  
  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.
  - content: String | ResponseInputMessageContentList
    
    Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses.
    - String = String
      
      A text input to the model.
    - ResponseInputMessageContentList = Array[ResponseInputContent]
      
      A list of one or many input items to the model, containing different content types.
      - class ResponseInputText
        
        A text input to the model.
        
        text: String
        
        The text input to the model.
        
        type: :input_text
        
        The type of the input item. Always input_text.
        
        :input_text
      - class ResponseInputImage
        
        An image input to the model. Learn about image inputs.
        
        detail: :low | :high | :auto | :original
        
        The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.
        
        :low
        
        :high
        
        :auto
        
        :original
        
        type: :input_image
        
        The type of the input item. Always input_image.
        
        :input_image
        
        file_id: String
        
        The ID of the file to be sent to the model.
        
        image_url: String
        
        The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.
      - class ResponseInputFile
        
        A file input to the model.
        
        type: :input_file
        
        The type of the input item. Always input_file.
        
        :input_file
        
        detail: :low | :high
        
        The detail level of the file to be sent to the model. Use low for the default rendering behavior, or high to render the file at higher quality. Defaults to low.
        
        :low
        
        :high
        
        file_data: String
        
        The content of the file to be sent to the model.
        
        file_id: String
        
        The ID of the file to be sent to the model.
        
        file_url: String
        
        The URL of the file to be sent to the model.
        
        filename: String
        
        The name of the file to be sent to the model.
  - role: :user | :assistant | :system | :developer
    
    The role of the message input. One of user, assistant, system, or developer.
    - :user
    - :assistant
    - :system
    - :developer
  - phase: :commentary | :final_answer
    
    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.
    - :commentary
    - :final_answer
  - type: :message
    
    The type of the message input. Always message.
    - :message
- class Message
  
  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.
  - content: ResponseInputMessageContentList
    
    A list of one or many input items to the model, containing different content types.
  - role: :user | :system | :developer
    
    The role of the message input. One of user, system, or developer.
    - :user
    - :system
    - :developer
  - status: :in_progress | :completed | :incomplete
    
    The status of item. One of in_progress, completed, or incomplete. Populated when items are returned via API.
    - :in_progress
    - :completed
    - :incomplete
  - type: :message
    
    The type of the message input. Always set to message.
    - :message
- class ResponseOutputMessage
  
  An output message from the model.
  - id: String
    
    The unique ID of the output message.
  - content: Array[ResponseOutputText | ResponseOutputRefusal]
    
    The content of the output message.
    - class ResponseOutputText
      
      A text output from the model.
      - annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]
        
        The annotations of the text output.
        
        class FileCitation
        
        A citation to a file.
        
        file_id: String
        
        The ID of the file.
        
        filename: String
        
        The filename of the file cited.
        
        index: Integer
        
        The index of the file in the list of files.
        
        type: :file_citation
        
        The type of the file citation. Always file_citation.
        
        :file_citation
        
        class URLCitation
        
        A citation for a web resource used to generate a model response.
        
        end_index: Integer
        
        The index of the last character of the URL citation in the message.
        
        start_index: Integer
        
        The index of the first character of the URL citation in the message.
        
        title: String
        
        The title of the web resource.
        
        type: :url_citation
        
        The type of the URL citation. Always url_citation.
        
        :url_citation
        
        url: String
        
        The URL of the web resource.
        
        class ContainerFileCitation
        
        A citation for a container file used to generate a model response.
        
        container_id: String
        
        The ID of the container file.
        
        end_index: Integer
        
        The index of the last character of the container file citation in the message.
        
        file_id: String
        
        The ID of the file.
        
        filename: String
        
        The filename of the container file cited.
        
        start_index: Integer
        
        The index of the first character of the container file citation in the message.
        
        type: :container_file_citation
        
        The type of the container file citation. Always container_file_citation.
        
        :container_file_citation
        
        class FilePath
        
        A path to a file.
        
        file_id: String
        
        The ID of the file.
        
        index: Integer
        
        The index of the file in the list of files.
        
        type: :file_path
        
        The type of the file path. Always file_path.
        
        :file_path
      - text: String
        
        The text output from the model.
      - type: :output_text
        
        The type of the output text. Always output_text.
        
        :output_text
      - logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]
        
        token: String
        
        bytes: Array[Integer]
        
        logprob: Float
        
        top_logprobs: Array[TopLogprob{ token, bytes, logprob}]
        
        token: String
        
        bytes: Array[Integer]
        
        logprob: Float
    - class ResponseOutputRefusal
      
      A refusal from the model.
      - refusal: String
        
        The refusal explanation from the model.
      - type: :refusal
        
        The type of the refusal. Always refusal.
        
        :refusal
  - role: :assistant
    
    The role of the output message. Always assistant.
    - :assistant
  - status: :in_progress | :completed | :incomplete
    
    The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.
    - :in_progress
    - :completed
    - :incomplete
  - type: :message
    
    The type of the output message. Always message.
    - :message
  - phase: :commentary | :final_answer
    
    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.
    - :commentary
    - :final_answer
- class ResponseFileSearchToolCall
  
  The results of a file search tool call. See the file search guide for more information.
  - id: String
    
    The unique ID of the file search tool call.
  - queries: Array[String]
    
    The queries used to search for files.
  - status: :in_progress | :searching | :completed | 2 more
    
    The status of the file search tool call. One of in_progress, searching, incomplete or failed,
    - :in_progress
    - :searching
    - :completed
    - :incomplete
    - :failed
  - type: :file_search_call
    
    The type of the file search tool call. Always file_search_call.
    - :file_search_call
  - results: Array[Result{ attributes, file_id, filename, 2 more}]
    
    The results of the file search tool call.
    - attributes: Hash[Symbol, String | Float | bool]
      
      Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters, booleans, or numbers.
      - String = String
      - Float = Float
      - UnionMember2 = bool
    - file_id: String
      
      The unique ID of the file.
    - filename: String
      
      The name of the file.
    - score: Float
      
      The relevance score of the file - a value between 0 and 1.
    - text: String
      
      The text that was retrieved from the file.
- class ResponseComputerToolCall
  
  A tool call to a computer use tool. See the computer use guide for more information.
  - id: String
    
    The unique ID of the computer call.
  - call_id: String
    
    An identifier used when responding to the tool call with output.
  - pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]
    
    The pending safety checks for the computer call.
    - id: String
      
      The ID of the pending safety check.
    - code: String
      
      The type of the pending safety check.
    - message: String
      
      Details about the pending safety check.
  - status: :in_progress | :completed | :incomplete
    
    The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.
    - :in_progress
    - :completed
    - :incomplete
  - type: :computer_call
    
    The type of the computer call. Always computer_call.
    - :computer_call
  - action: Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more
    
    A click action.
    - class Click
      
      A click action.
      - button: :left | :right | :wheel | 2 more
        
        Indicates which mouse button was pressed during the click. One of left, right, wheel, back, or forward.
        
        :left
        
        :right
        
        :wheel
        
        :back
        
        :forward
      - type: :click
        
        Specifies the event type. For a click action, this property is always click.
        
        :click
      - x: Integer
        
        The x-coordinate where the click occurred.
      - y_: Integer
        
        The y-coordinate where the click occurred.
      - keys: Array[String]
        
        The keys being held while clicking.
    - class DoubleClick
      
      A double click action.
      - keys: Array[String]
        
        The keys being held while double-clicking.
      - type: :double_click
        
        Specifies the event type. For a double click action, this property is always set to double_click.
        
        :double_click
      - x: Integer
        
        The x-coordinate where the double click occurred.
      - y_: Integer
        
        The y-coordinate where the double click occurred.
    - class Drag
      
      A drag action.
      - path: Array[Path{ x, y_}]
        
        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 } ]
        
        x: Integer
        
        The x-coordinate.
        
        y_: Integer
        
        The y-coordinate.
      - type: :drag
        
        Specifies the event type. For a drag action, this property is always set to drag.
        
        :drag
      - keys: Array[String]
        
        The keys being held while dragging the mouse.
    - class Keypress
      
      A collection of keypresses the model would like to perform.
      - keys: Array[String]
        
        The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.
      - type: :keypress
        
        Specifies the event type. For a keypress action, this property is always set to keypress.
        
        :keypress
    - class Move
      
      A mouse move action.
      - type: :move
        
        Specifies the event type. For a move action, this property is always set to move.
        
        :move
      - x: Integer
        
        The x-coordinate to move to.
      - y_: Integer
        
        The y-coordinate to move to.
      - keys: Array[String]
        
        The keys being held while moving the mouse.
    - class Screenshot
      
      A screenshot action.
      - type: :screenshot
        
        Specifies the event type. For a screenshot action, this property is always set to screenshot.
        
        :screenshot
    - class Scroll
      
      A scroll action.
      - scroll_x: Integer
        
        The horizontal scroll distance.
      - scroll_y: Integer
        
        The vertical scroll distance.
      - type: :scroll
        
        Specifies the event type. For a scroll action, this property is always set to scroll.
        
        :scroll
      - x: Integer
        
        The x-coordinate where the scroll occurred.
      - y_: Integer
        
        The y-coordinate where the scroll occurred.
      - keys: Array[String]
        
        The keys being held while scrolling.
    - class Type
      
      An action to type in text.
      - text: String
        
        The text to type.
      - type: :type
        
        Specifies the event type. For a type action, this property is always set to type.
        
        :type
    - class Wait
      
      A wait action.
      - type: :wait
        
        Specifies the event type. For a wait action, this property is always set to wait.
        
        :wait
  - actions: ComputerActionList
    
    Flattened batched actions for computer_use. Each action includes an type discriminator and action-specific fields.
    - class Click
      
      A click action.
      - button: :left | :right | :wheel | 2 more
        
        Indicates which mouse button was pressed during the click. One of left, right, wheel, back, or forward.
        
        :left
        
        :right
        
        :wheel
        
        :back
        
        :forward
      - type: :click
        
        Specifies the event type. For a click action, this property is always click.
        
        :click
      - x: Integer
        
        The x-coordinate where the click occurred.
      - y_: Integer
        
        The y-coordinate where the click occurred.
      - keys: Array[String]
        
        The keys being held while clicking.
    - class DoubleClick
      
      A double click action.
      - keys: Array[String]
        
        The keys being held while double-clicking.
      - type: :double_click
        
        Specifies the event type. For a double click action, this property is always set to double_click.
        
        :double_click
      - x: Integer
        
        The x-coordinate where the double click occurred.
      - y_: Integer
        
        The y-coordinate where the double click occurred.
    - class Drag
      
      A drag action.
      - path: Array[Path{ x, y_}]
        
        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 } ]
        
        x: Integer
        
        The x-coordinate.
        
        y_: Integer
        
        The y-coordinate.
      - type: :drag
        
        Specifies the event type. For a drag action, this property is always set to drag.
        
        :drag
      - keys: Array[String]
        
        The keys being held while dragging the mouse.
    - class Keypress
      
      A collection of keypresses the model would like to perform.
      - keys: Array[String]
        
        The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.
      - type: :keypress
        
        Specifies the event type. For a keypress action, this property is always set to keypress.
        
        :keypress
    - class Move
      
      A mouse move action.
      - type: :move
        
        Specifies the event type. For a move action, this property is always set to move.
        
        :move
      - x: Integer
        
        The x-coordinate to move to.
      - y_: Integer
        
        The y-coordinate to move to.
      - keys: Array[String]
        
        The keys being held while moving the mouse.
    - class Screenshot
      
      A screenshot action.
      - type: :screenshot
        
        Specifies the event type. For a screenshot action, this property is always set to screenshot.
        
        :screenshot
    - class Scroll
      
      A scroll action.
      - scroll_x: Integer
        
        The horizontal scroll distance.
      - scroll_y: Integer
        
        The vertical scroll distance.
      - type: :scroll
        
        Specifies the event type. For a scroll action, this property is always set to scroll.
        
        :scroll
      - x: Integer
        
        The x-coordinate where the scroll occurred.
      - y_: Integer
        
        The y-coordinate where the scroll occurred.
      - keys: Array[String]
        
        The keys being held while scrolling.
    - class Type
      
      An action to type in text.
      - text: String
        
        The text to type.
      - type: :type
        
        Specifies the event type. For a type action, this property is always set to type.
        
        :type
    - class Wait
      
      A wait action.
      - type: :wait
        
        Specifies the event type. For a wait action, this property is always set to wait.
        
        :wait
- class ComputerCallOutput
  
  The output of a computer tool call.
  - call_id: String
    
    The ID of the computer tool call that produced the output.
  - output: ResponseComputerToolCallOutputScreenshot
    
    A computer screenshot image used with the computer use tool.
    - type: :computer_screenshot
      
      Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot.
      - :computer_screenshot
    - file_id: String
      
      The identifier of an uploaded file that contains the screenshot.
    - image_url: String
      
      The URL of the screenshot image.
  - type: :computer_call_output
    
    The type of the computer tool call output. Always computer_call_output.
    - :computer_call_output
  - id: String
    
    The ID of the computer tool call output.
  - acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]
    
    The safety checks reported by the API that have been acknowledged by the developer.
    - id: String
      
      The ID of the pending safety check.
    - code: String
      
      The type of the pending safety check.
    - message: String
      
      Details about the pending safety check.
  - status: :in_progress | :completed | :incomplete
    
    The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.
    - :in_progress
    - :completed
    - :incomplete
- class ResponseFunctionWebSearch
  
  The results of a web search tool call. See the web search guide for more information.
  - id: String
    
    The unique ID of the web search tool call.
  - action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}
    
    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).
    - class Search
      
      Action type "search" - Performs a web search query.
      - type: :search
        
        The action type.
        
        :search
      - queries: Array[String]
        
        The search queries.
      - query: String
        
        The search query.
      - sources: Array[Source{ type, url}]
        
        The sources used in the search.
        
        type: :url
        
        The type of source. Always url.
        
        :url
        
        url: String
        
        The URL of the source.
    - class OpenPage
      
      Action type "open_page" - Opens a specific URL from search results.
      - type: :open_page
        
        The action type.
        
        :open_page
      - url: String
        
        The URL opened by the model.
    - class FindInPage
      
      Action type "find_in_page": Searches for a pattern within a loaded page.
      - pattern: String
        
        The pattern or text to search for within the page.
      - type: :find_in_page
        
        The action type.
        
        :find_in_page
      - url: String
        
        The URL of the page searched for the pattern.
  - status: :in_progress | :searching | :completed | :failed
    
    The status of the web search tool call.
    - :in_progress
    - :searching
    - :completed
    - :failed
  - type: :web_search_call
    
    The type of the web search tool call. Always web_search_call.
    - :web_search_call
- class ResponseFunctionToolCall
  
  A tool call to run a function. See the function calling guide for more information.
  - arguments: String
    
    A JSON string of the arguments to pass to the function.
  - call_id: String
    
    The unique ID of the function tool call generated by the model.
  - name: String
    
    The name of the function to run.
  - type: :function_call
    
    The type of the function tool call. Always function_call.
    - :function_call
  - id: String
    
    The unique ID of the function tool call.
  - namespace: String
    
    The namespace of the function to run.
  - status: :in_progress | :completed | :incomplete
    
    The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.
    - :in_progress
    - :completed
    - :incomplete
- class FunctionCallOutput
  
  The output of a function tool call.
  - call_id: String
    
    The unique ID of the function tool call generated by the model.
  - output: String | ResponseFunctionCallOutputItemList
    
    Text, image, or file output of the function tool call.
    - String = String
      
      A JSON string of the output of the function tool call.
    - ResponseFunctionCallOutputItemList = Array[ResponseFunctionCallOutputItem]
      
      An array of content outputs (text, image, file) for the function tool call.
      - class ResponseInputTextContent
        
        A text input to the model.
        
        text: String
        
        The text input to the model.
        
        type: :input_text
        
        The type of the input item. Always input_text.
        
        :input_text
      - class ResponseInputImageContent
        
        An image input to the model. Learn about image inputs
        
        type: :input_image
        
        The type of the input item. Always input_image.
        
        :input_image
        
        detail: :low | :high | :auto | :original
        
        The detail level of the image to be sent to the model. One of high, low, auto, or original. Defaults to auto.
        
        :low
        
        :high
        
        :auto
        
        :original
        
        file_id: String
        
        The ID of the file to be sent to the model.
        
        image_url: String
        
        The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.
      - class ResponseInputFileContent
        
        A file input to the model.
        
        type: :input_file
        
        The type of the input item. Always input_file.
        
        :input_file
        
        detail: :low | :high
        
        The detail level of the file to be sent to the model. Use low for the default rendering behavior, or high to render the file at higher quality. Defaults to low.
        
        :low
        
        :high
        
        file_data: String
        
        The base64-encoded data of the file to be sent to the model.
        
        file_id: String
        
        The ID of the file to be sent to the model.
        
        file_url: String
        
        The URL of the file to be sent to the model.
        
        filename: String
        
        The name of the file to be sent to the model.
  - type: :function_call_output
    
    The type of the function tool call output. Always function_call_output.
    - :function_call_output
  - id: String
    
    The unique ID of the function tool call output. Populated when this item is returned via API.
  - status: :in_progress | :completed | :incomplete
    
    The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.
    - :in_progress
    - :completed
    - :incomplete
- class ToolSearchCall
  - arguments: untyped
    
    The arguments supplied to the tool search call.
  - type: :tool_search_call
    
    The item type. Always tool_search_call.
    - :tool_search_call
  - id: String
    
    The unique ID of this tool search call.
  - call_id: String
    
    The unique ID of the tool search call generated by the model.
  - execution: :server | :client
    
    Whether tool search was executed by the server or by the client.
    - :server
    - :client
  - status: :in_progress | :completed | :incomplete
    
    The status of the tool search call.
    - :in_progress
    - :completed
    - :incomplete
- class ResponseToolSearchOutputItemParam
  - tools: Array[Tool]
    
    The loaded tool definitions returned by the tool search output.
    - class FunctionTool
      
      Defines a function in your own code the model can choose to call. Learn more about function calling.
      - name: String
        
        The name of the function to call.
      - parameters: Hash[Symbol, untyped]
        
        A JSON schema object describing the parameters of the function.
      - strict: bool
        
        Whether to enforce strict parameter validation. Default true.
      - type: :function
        
        The type of the function tool. Always function.
        
        :function
      - defer_loading: bool
        
        Whether this function is deferred and loaded via tool search.
      - description: String
        
        A description of the function. Used by the model to determine whether or not to call the function.
    - class FileSearchTool
      
      A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
      - type: :file_search
        
        The type of the file search tool. Always file_search.
        
        :file_search
      - vector_store_ids: Array[String]
        
        The IDs of the vector stores to search.
      - filters: ComparisonFilter | CompoundFilter
        
        A filter to apply.
        
        class ComparisonFilter
        
        A filter used to compare a specified attribute key to a given value using a defined comparison operation.
        
        key: String
        
        The key to compare against the value.
        
        type: :eq | :ne | :gt | 5 more
        
        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
        
        :eq
        
        :ne
        
        :gt
        
        :gte
        
        :lt
        
        :lte
        
        :in
        
        :nin
        
        value: String | Float | bool | Array[String | Float]
        
        The value to compare against the attribute key; supports string, number, or boolean types.
        
        String = String
        
        Float = Float
        
        UnionMember2 = bool
        
        UnionMember3 = Array[String | Float]
        
        String = String
        
        Float = Float
        
        class CompoundFilter
        
        Combine multiple filters using and or or.
        
        filters: Array[ComparisonFilter | untyped]
        
        Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
        
        class ComparisonFilter
        
        A filter used to compare a specified attribute key to a given value using a defined comparison operation.
        
        UnionMember1 = untyped
        
        type: :and | :or
        
        Type of operation: and or or.
        
        :and
        
        :or
      - max_num_results: Integer
        
        The maximum number of results to return. This number should be between 1 and 50 inclusive.
      - ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}
        
        Ranking options for search.
        
        hybrid_search: HybridSearch{ embedding_weight, text_weight}
        
        Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.
        
        embedding_weight: Float
        
        The weight of the embedding in the reciprocal ranking fusion.
        
        text_weight: Float
        
        The weight of the text in the reciprocal ranking fusion.
        
        ranker: :auto | :"default-2024-11-15"
        
        The ranker to use for the file search.
        
        :auto
        
        :"default-2024-11-15"
        
        score_threshold: Float
        
        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.
    - class ComputerTool
      
      A tool that controls a virtual computer. Learn more about the computer tool.
      - type: :computer
        
        The type of the computer tool. Always computer.
        
        :computer
    - class ComputerUsePreviewTool
      
      A tool that controls a virtual computer. Learn more about the computer tool.
      - display_height: Integer
        
        The height of the computer display.
      - display_width: Integer
        
        The width of the computer display.
      - environment: :windows | :mac | :linux | 2 more
        
        The type of computer environment to control.
        
        :windows
        
        :mac
        
        :linux
        
        :ubuntu
        
        :browser
      - type: :computer_use_preview
        
        The type of the computer use tool. Always computer_use_preview.
        
        :computer_use_preview
    - class WebSearchTool
      
      Search the Internet for sources related to the prompt. Learn more about the web search tool.
      - type: :web_search | :web_search_2025_08_26
        
        The type of the web search tool. One of web_search or web_search_2025_08_26.
        
        :web_search
        
        :web_search_2025_08_26
      - filters: Filters{ allowed_domains}
        
        Filters for the search.
        
        allowed_domains: Array[String]
        
        Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well.
        
        Example: ["pubmed.ncbi.nlm.nih.gov"]
      - search_context_size: :low | :medium | :high
        
        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.
        
        :low
        
        :medium
        
        :high
      - user_location: UserLocation{ city, country, region, 2 more}
        
        The approximate location of the user.
        
        city: String
        
        Free text input for the city of the user, e.g. San Francisco.
        
        country: String
        
        The two-letter ISO country code of the user, e.g. US.
        
        region: String
        
        Free text input for the region of the user, e.g. California.
        
        timezone: String
        
        The IANA timezone of the user, e.g. America/Los_Angeles.
        
        type: :approximate
        
        The type of location approximation. Always approximate.
        
        :approximate
    - class Mcp
      
      Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.
      - server_label: String
        
        A label for this MCP server, used to identify it in tool calls.
      - type: :mcp
        
        The type of the MCP tool. Always mcp.
        
        :mcp
      - allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}
        
        List of allowed tool names or a filter object.
        
        McpAllowedTools = Array[String]
        
        A string array of allowed tool names
        
        class McpToolFilter
        
        A filter object to specify which tools are allowed.
        
        read_only: bool
        
        Indicates whether or not a tool modifies data or is read-only. If an MCP server is annotated with readOnlyHint, it will match this filter.
        
        tool_names: Array[String]
        
        List of allowed tool names.
      - authorization: String
        
        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.
      - connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more
        
        Identifier for service connectors, like those available in ChatGPT. One of server_url or connector_id must be provided. Learn more about service connectors here.
        
        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
        
        :connector_dropbox
        
        :connector_gmail
        
        :connector_googlecalendar
        
        :connector_googledrive
        
        :connector_microsoftteams
        
        :connector_outlookcalendar
        
        :connector_outlookemail
        
        :connector_sharepoint
      - defer_loading: bool
        
        Whether this MCP tool is deferred and discovered via tool search.
      - headers: Hash[Symbol, String]
        
        Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.
      - require_approval: McpToolApprovalFilter{ always, never} | :always | :never
        
        Specify which of the MCP server's tools require approval.
        
        class McpToolApprovalFilter
        
        Specify which of the MCP server's tools require approval. Can be always, never, or a filter object associated with tools that require approval.
        
        always: Always{ read_only, tool_names}
        
        A filter object to specify which tools are allowed.
        
        read_only: bool
        
        Indicates whether or not a tool modifies data or is read-only. If an MCP server is annotated with readOnlyHint, it will match this filter.
        
        tool_names: Array[String]
        
        List of allowed tool names.
        
        never: Never{ read_only, tool_names}
        
        A filter object to specify which tools are allowed.
        
        read_only: bool
        
        Indicates whether or not a tool modifies data or is read-only. If an MCP server is annotated with readOnlyHint, it will match this filter.
        
        tool_names: Array[String]
        
        List of allowed tool names.
        
        McpToolApprovalSetting = :always | :never
        
        Specify a single approval policy for all tools. One of always or never. When set to always, all tools will require approval. When set to never, all tools will not require approval.
        
        :always
        
        :never
      - server_description: String
        
        Optional description of the MCP server, used to provide more context.
      - server_url: String
        
        The URL for the MCP server. One of server_url or connector_id must be provided.
    - class CodeInterpreter
      
      A tool that runs Python code to help generate a response to a prompt.
      - container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}
        
        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.
        
        String = String
        
        The container ID.
        
        class CodeInterpreterToolAuto
        
        Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
        
        type: :auto
        
        Always auto.
        
        :auto
        
        file_ids: Array[String]
        
        An optional list of uploaded files to make available to your code.
        
        memory_limit: :"1g" | :"4g" | :"16g" | :"64g"
        
        The memory limit for the code interpreter container.
        
        :"1g"
        
        :"4g"
        
        :"16g"
        
        :"64g"
        
        network_policy: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist
        
        Network access policy for the container.
        
        class ContainerNetworkPolicyDisabled
        
        type: :disabled
        
        Disable outbound network access. Always disabled.
        
        :disabled
        
        class ContainerNetworkPolicyAllowlist
        
        allowed_domains: Array[String]
        
        A list of allowed domains when type is allowlist.
        
        type: :allowlist
        
        Allow outbound network access only to specified domains. Always allowlist.
        
        :allowlist
        
        domain_secrets: Array[ContainerNetworkPolicyDomainSecret]
        
        Optional domain-scoped secrets for allowlisted domains.
        
        domain: String
        
        The domain associated with the secret.
        
        name: String
        
        The name of the secret to inject for the domain.
        
        value: String
        
        The secret value to inject for the domain.
      - type: :code_interpreter
        
        The type of the code interpreter tool. Always code_interpreter.
        
        :code_interpreter
    - class ImageGeneration
      
      A tool that generates images using the GPT image models.
      - type: :image_generation
        
        The type of the image generation tool. Always image_generation.
        
        :image_generation
      - action: :generate | :edit | :auto
        
        Whether to generate a new image or edit an existing image. Default: auto.
        
        :generate
        
        :edit
        
        :auto
      - background: :transparent | :opaque | :auto
        
        Allows to set transparency for the background of the generated image(s). This parameter is only supported for GPT image models that support transparent backgrounds. Must be one of transparent, opaque, or auto (default value). When auto is used, the model will automatically determine the best background for the image.
        
        gpt-image-2 and gpt-image-2-2026-04-21 do not support transparent backgrounds. Requests with background set to transparent will return an error for these models; use opaque or auto instead.
        
        If transparent, the output format needs to support transparency, so it should be set to either png (default value) or webp.
        
        :transparent
        
        :opaque
        
        :auto
      - input_fidelity: :high | :low
        
        Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for gpt-image-1 and gpt-image-1.5 and later models, unsupported for gpt-image-1-mini. Supports high and low. Defaults to low.
        
        :high
        
        :low
      - input_image_mask: InputImageMask{ file_id, image_url}
        
        Optional mask for inpainting. Contains image_url (string, optional) and file_id (string, optional).
        
        file_id: String
        
        File ID for the mask image.
        
        image_url: String
        
        Base64-encoded mask image.
      - model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more
        
        The image generation model to use. Default: gpt-image-1.
        
        String = String
        
        Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more
        
        The image generation model to use. Default: gpt-image-1.
        
        :"gpt-image-1"
        
        :"gpt-image-1-mini"
        
        :"gpt-image-2"
        
        :"gpt-image-2-2026-04-21"
        
        :"gpt-image-1.5"
        
        :"chatgpt-image-latest"
      - moderation: :auto | :low
        
        Moderation level for the generated image. Default: auto.
        
        :auto
        
        :low
      - output_compression: Integer
        
        Compression level for the output image. Default: 100.
      - output_format: :png | :webp | :jpeg
        
        The output format of the generated image. One of png, webp, or jpeg. Default: png.
        
        :png
        
        :webp
        
        :jpeg
      - partial_images: Integer
        
        Number of partial images to generate in streaming mode, from 0 (default value) to 3.
      - quality: :low | :medium | :high | :auto
        
        The quality of the generated image. One of low, medium, high, or auto. Default: auto.
        
        :low
        
        :medium
        
        :high
        
        :auto
      - size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto
        
        The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21, 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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
        
        String = String
        
        Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto
        
        The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21, 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. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
        
        :"1024x1024"
        
        :"1024x1536"
        
        :"1536x1024"
        
        :auto
    - class LocalShell
      
      A tool that allows the model to execute shell commands in a local environment.
      - type: :local_shell
        
        The type of the local shell tool. Always local_shell.
        
        :local_shell
    - class FunctionShellTool
      
      A tool that allows the model to execute shell commands.
      - type: :shell
        
        The type of the shell tool. Always shell.
        
        :shell
      - environment: ContainerAuto | LocalEnvironment | ContainerReference
        
        class ContainerAuto
        
        type: :container_auto
        
        Automatically creates a container for this request
        
        :container_auto
        
        file_ids: Array[String]
        
        An optional list of uploaded files to make available to your code.
        
        memory_limit: :"1g" | :"4g" | :"16g" | :"64g"
        
        The memory limit for the container.
        
        :"1g"
        
        :"4g"
        
        :"16g"
        
        :"64g"
        
        network_policy: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist
        
        Network access policy for the container.
        
        class ContainerNetworkPolicyDisabled
        
        class ContainerNetworkPolicyAllowlist
        
        skills: Array[SkillReference | InlineSkill]
        
        An optional list of skills referenced by id or inline data.
        
        class SkillReference
        
        skill_id: String
        
        The ID of the referenced skill.
        
        type: :skill_reference
        
        References a skill created with the /v1/skills endpoint.
        
        :skill_reference
        
        version: String
        
        Optional skill version. Use a positive integer or 'latest'. Omit for default.
        
        class InlineSkill
        
        description: String
        
        The description of the skill.
        
        name: String
        
        The name of the skill.
        
        source: InlineSkillSource
        
        Inline skill payload
        
        data: String
        
        Base64-encoded skill zip bundle.
        
        media_type: :"application/zip"
        
        The media type of the inline skill payload. Must be application/zip.
        
        :"application/zip"
        
        type: :base64
        
        The type of the inline skill source. Must be base64.
        
        :base64
        
        type: :inline
        
        Defines an inline skill for this request.
        
        :inline
        
        class LocalEnvironment
        
        type: :local
        
        Use a local computer environment.
        
        :local
        
        skills: Array[LocalSkill]
        
        An optional list of skills.
        
        description: String
        
        The description of the skill.
        
        name: String
        
        The name of the skill.
        
        path: String
        
        The path to the directory containing the skill.
        
        class ContainerReference
        
        container_id: String
        
        The ID of the referenced container.
        
        type: :container_reference
        
        References a container created with the /v1/containers endpoint
        
        :container_reference
    - class CustomTool
      
      A custom tool that processes input using a specified format. Learn more about custom tools
      - name: String
        
        The name of the custom tool, used to identify it in tool calls.
      - type: :custom
        
        The type of the custom tool. Always custom.
        
        :custom
      - defer_loading: bool
        
        Whether this tool should be deferred and discovered via tool search.
      - description: String
        
        Optional description of the custom tool, used to provide more context.
      - format_: CustomToolInputFormat
        
        The input format for the custom tool. Default is unconstrained text.
        
        class Text
        
        Unconstrained free-form text.
        
        type: :text
        
        Unconstrained text format. Always text.
        
        :text
        
        class Grammar
        
        A grammar defined by the user.
        
        definition: String
        
        The grammar definition.
        
        syntax: :lark | :regex
        
        The syntax of the grammar definition. One of lark or regex.
        
        :lark
        
        :regex
        
        type: :grammar
        
        Grammar format. Always grammar.
        
        :grammar
    - class NamespaceTool
      
      Groups function/custom tools under a shared namespace.
      - description: String
        
        A description of the namespace shown to the model.
      - name: String
        
        The namespace name used in tool calls (for example, crm).
      - tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]
        
        The function/custom tools available inside this namespace.
        
        class Function
        
        name: String
        
        type: :function
        
        :function
        
        defer_loading: bool
        
        Whether this function should be deferred and discovered via tool search.
        
        description: String
        
        parameters: untyped
        
        strict: bool
        
        class CustomTool
        
        A custom tool that processes input using a specified format. Learn more about custom tools
      - type: :namespace
        
        The type of the tool. Always namespace.
        
        :namespace
    - class ToolSearchTool
      
      Hosted or BYOT tool search configuration for deferred tools.
      - type: :tool_search
        
        The type of the tool. Always tool_search.
        
        :tool_search
      - description: String
        
        Description shown to the model for a client-executed tool search tool.
      - execution: :server | :client
        
        Whether tool search is executed by the server or by the client.
        
        :server
        
        :client
      - parameters: untyped
        
        Parameter schema for a client-executed tool search tool.
    - class WebSearchPreviewTool
      
      This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
      - type: :web_search_preview | :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.
        
        :web_search_preview
        
        :web_search_preview_2025_03_11
      - search_content_types: Array[:text | :image]
        
        :text
        
        :image
      - search_context_size: :low | :medium | :high
        
        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.
        
        :low
        
        :medium
        
        :high
      - user_location: UserLocation{ type, city, country, 2 more}
        
        The user's location.
        
        type: :approximate
        
        The type of location approximation. Always approximate.
        
        :approximate
        
        city: String
        
        Free text input for the city of the user, e.g. San Francisco.
        
        country: String
        
        The two-letter ISO country code of the user, e.g. US.
        
        region: String
        
        Free text input for the region of the user, e.g. California.
        
        timezone: String
        
        The IANA timezone of the user, e.g. America/Los_Angeles.
    - class ApplyPatchTool
      
      Allows the assistant to create, delete, or update files using unified diffs.
      - type: :apply_patch
        
        The type of the tool. Always apply_patch.
        
        :apply_patch
  - type: :tool_search_output
    
    The item type. Always tool_search_output.
    - :tool_search_output
  - id: String
    
    The unique ID of this tool search output.
  - call_id: String
    
    The unique ID of the tool search call generated by the model.
  - execution: :server | :client
    
    Whether tool search was executed by the server or by the client.
    - :server
    - :client
  - status: :in_progress | :completed | :incomplete
    
    The status of the tool search output.
    - :in_progress
    - :completed
    - :incomplete
- class AdditionalTools
  - role: :developer
    
    The role that provided the additional tools. Only developer is supported.
    - :developer
  - tools: Array[Tool]
    
    A list of additional tools made available at this item.
    - class FunctionTool
      
      Defines a function in your own code the model can choose to call. Learn more about function calling.
    - class FileSearchTool
      
      A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
    - class ComputerTool
      
      A tool that controls a virtual computer. Learn more about the computer tool.
    - class ComputerUsePreviewTool
      
      A tool that controls a virtual computer. Learn more about the computer tool.
    - class WebSearchTool
      
      Search the Internet for sources related to the prompt. Learn more about the web search tool.
    - class Mcp
      
      Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.
    - class CodeInterpreter
      
      A tool that runs Python code to help generate a response to a prompt.
    - class ImageGeneration
      
      A tool that generates images using the GPT image models.
    - class LocalShell
      
      A tool that allows the model to execute shell commands in a local environment.
    - class FunctionShellTool
      
      A tool that allows the model to execute shell commands.
    - class CustomTool
      
      A custom tool that processes input using a specified format. Learn more about custom tools
    - class NamespaceTool
      
      Groups function/custom tools under a shared namespace.
    - class ToolSearchTool
      
      Hosted or BYOT tool search configuration for deferred tools.
    - class WebSearchPreviewTool
      
      This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
    - class ApplyPatchTool
      
      Allows the assistant to create, delete, or update files using unified diffs.
  - type: :additional_tools
    
    The item type. Always additional_tools.
    - :additional_tools
  - id: String
    
    The unique ID of this additional tools item.
- class ResponseReasoningItem
  
  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.
  - id: String
    
    The unique identifier of the reasoning content.
  - summary: Array[Summary{ text, type}]
    
    Reasoning summary content.
    - text: String
      
      A summary of the reasoning output from the model so far.
    - type: :summary_text
      
      The type of the object. Always summary_text.
      - :summary_text
  - type: :reasoning
    
    The type of the object. Always reasoning.
    - :reasoning
  - content: Array[Content{ text, type}]
    
    Reasoning text content.
    - text: String
      
      The reasoning text from the model.
    - type: :reasoning_text
      
      The type of the reasoning text. Always reasoning_text.
      - :reasoning_text
  - encrypted_content: String
    
    The encrypted content of the reasoning item - populated when a response is generated with reasoning.encrypted_content in the include parameter.
  - status: :in_progress | :completed | :incomplete
    
    The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.
    - :in_progress
    - :completed
    - :incomplete
- class ResponseCompactionItemParam
  
  A compaction item generated by the v1/responses/compact API.
  - encrypted_content: String
    
    The encrypted content of the compaction summary.
  - type: :compaction
    
    The type of the item. Always compaction.
    - :compaction
  - id: String
    
    The ID of the compaction item.
- class ImageGenerationCall
  
  An image generation request made by the model.
  - id: String
    
    The unique ID of the image generation call.
  - result: String
    
    The generated image encoded in base64.
  - status: :in_progress | :completed | :generating | :failed
    
    The status of the image generation call.
    - :in_progress
    - :completed
    - :generating
    - :failed
  - type: :image_generation_call
    
    The type of the image generation call. Always image_generation_call.
    - :image_generation_call
- class ResponseCodeInterpreterToolCall
  
  A tool call to run code.
  - id: String
    
    The unique ID of the code interpreter tool call.
  - code: String
    
    The code to run, or null if not available.
  - container_id: String
    
    The ID of the container used to run the code.
  - outputs: Array[Logs{ logs, type} | Image{ type, url}]
    
    The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available.
    - class Logs
      
      The logs output from the code interpreter.
      - logs: String
        
        The logs output from the code interpreter.
      - type: :logs
        
        The type of the output. Always logs.
        
        :logs
    - class Image
      
      The image output from the code interpreter.
      - type: :image
        
        The type of the output. Always image.
        
        :image
      - url: String
        
        The URL of the image output from the code interpreter.
  - status: :in_progress | :completed | :incomplete | 2 more
    
    The status of the code interpreter tool call. Valid values are in_progress, completed, incomplete, interpreting, and failed.
    - :in_progress
    - :completed
    - :incomplete
    - :interpreting
    - :failed
  - type: :code_interpreter_call
    
    The type of the code interpreter tool call. Always code_interpreter_call.
    - :code_interpreter_call
- class LocalShellCall
  
  A tool call to run a command on the local shell.
  - id: String
    
    The unique ID of the local shell call.
  - action: Action{ command, env, type, 3 more}
    
    Execute a shell command on the server.
    - command: Array[String]
      
      The command to run.
    - env: Hash[Symbol, String]
      
      Environment variables to set for the command.
    - type: :exec
      
      The type of the local shell action. Always exec.
      - :exec
    - timeout_ms: Integer
      
      Optional timeout in milliseconds for the command.
    - user: String
      
      Optional user to run the command as.
    - working_directory: String
      
      Optional working directory to run the command in.
  - call_id: String
    
    The unique ID of the local shell tool call generated by the model.
  - status: :in_progress | :completed | :incomplete
    
    The status of the local shell call.
    - :in_progress
    - :completed
    - :incomplete
  - type: :local_shell_call
    
    The type of the local shell call. Always local_shell_call.
    - :local_shell_call
- class LocalShellCallOutput
  
  The output of a local shell tool call.
  - id: String
    
    The unique ID of the local shell tool call generated by the model.
  - output: String
    
    A JSON string of the output of the local shell tool call.
  - type: :local_shell_call_output
    
    The type of the local shell tool call output. Always local_shell_call_output.
    - :local_shell_call_output
  - status: :in_progress | :completed | :incomplete
    
    The status of the item. One of in_progress, completed, or incomplete.
    - :in_progress
    - :completed
    - :incomplete
- class ShellCall
  
  A tool representing a request to execute one or more shell commands.
  - action: Action{ commands, max_output_length, timeout_ms}
    
    The shell commands and limits that describe how to run the tool call.
    - commands: Array[String]
      
      Ordered shell commands for the execution environment to run.
    - max_output_length: Integer
      
      Maximum number of UTF-8 characters to capture from combined stdout and stderr output.
    - timeout_ms: Integer
      
      Maximum wall-clock time in milliseconds to allow the shell commands to run.
  - call_id: String
    
    The unique ID of the shell tool call generated by the model.
  - type: :shell_call
    
    The type of the item. Always shell_call.
    - :shell_call
  - id: String
    
    The unique ID of the shell tool call. Populated when this item is returned via API.
  - environment: LocalEnvironment | ContainerReference
    
    The environment to execute the shell commands in.
    - class LocalEnvironment
    - class ContainerReference
  - status: :in_progress | :completed | :incomplete
    
    The status of the shell call. One of in_progress, completed, or incomplete.
    - :in_progress
    - :completed
    - :incomplete
- class ShellCallOutput
  
  The streamed output items emitted by a shell tool call.
  - call_id: String
    
    The unique ID of the shell tool call generated by the model.
  - output: Array[ResponseFunctionShellCallOutputContent]
    
    Captured chunks of stdout and stderr output, along with their associated outcomes.
    - outcome: Timeout{ type} | Exit{ exit_code, type}
      
      The exit or timeout outcome associated with this shell call.
      - class Timeout
        
        Indicates that the shell call exceeded its configured time limit.
        
        type: :timeout
        
        The outcome type. Always timeout.
        
        :timeout
      - class Exit
        
        Indicates that the shell commands finished and returned an exit code.
        
        exit_code: Integer
        
        The exit code returned by the shell process.
        
        type: :exit
        
        The outcome type. Always exit.
        
        :exit
    - stderr: String
      
      Captured stderr output for the shell call.
    - stdout: String
      
      Captured stdout output for the shell call.
  - type: :shell_call_output
    
    The type of the item. Always shell_call_output.
    - :shell_call_output
  - id: String
    
    The unique ID of the shell tool call output. Populated when this item is returned via API.
  - max_output_length: Integer
    
    The maximum number of UTF-8 characters captured for this shell call's combined output.
  - status: :in_progress | :completed | :incomplete
    
    The status of the shell call output.
    - :in_progress
    - :completed
    - :incomplete
- class ApplyPatchCall
  
  A tool call representing a request to create, delete, or update files using diff patches.
  - call_id: String
    
    The unique ID of the apply patch tool call generated by the model.
  - operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}
    
    The specific create, delete, or update instruction for the apply_patch tool call.
    - class CreateFile
      
      Instruction for creating a new file via the apply_patch tool.
      - diff: String
        
        Unified diff content to apply when creating the file.
      - path: String
        
        Path of the file to create relative to the workspace root.
      - type: :create_file
        
        The operation type. Always create_file.
        
        :create_file
    - class DeleteFile
      
      Instruction for deleting an existing file via the apply_patch tool.
      - path: String
        
        Path of the file to delete relative to the workspace root.
      - type: :delete_file
        
        The operation type. Always delete_file.
        
        :delete_file
    - class UpdateFile
      
      Instruction for updating an existing file via the apply_patch tool.
      - diff: String
        
        Unified diff content to apply to the existing file.
      - path: String
        
        Path of the file to update relative to the workspace root.
      - type: :update_file
        
        The operation type. Always update_file.
        
        :update_file
  - status: :in_progress | :completed
    
    The status of the apply patch tool call. One of in_progress or completed.
    - :in_progress
    - :completed
  - type: :apply_patch_call
    
    The type of the item. Always apply_patch_call.
    - :apply_patch_call
  - id: String
    
    The unique ID of the apply patch tool call. Populated when this item is returned via API.
- class ApplyPatchCallOutput
  
  The streamed output emitted by an apply patch tool call.
  - call_id: String
    
    The unique ID of the apply patch tool call generated by the model.
  - status: :completed | :failed
    
    The status of the apply patch tool call output. One of completed or failed.
    - :completed
    - :failed
  - type: :apply_patch_call_output
    
    The type of the item. Always apply_patch_call_output.
    - :apply_patch_call_output
  - id: String
    
    The unique ID of the apply patch tool call output. Populated when this item is returned via API.
  - output: String
    
    Optional human-readable log text from the apply patch tool (e.g., patch results or errors).
- class McpListTools
  
  A list of tools available on an MCP server.
  - id: String
    
    The unique ID of the list.
  - server_label: String
    
    The label of the MCP server.
  - tools: Array[Tool{ input_schema, name, annotations, description}]
    
    The tools available on the server.
    - input_schema: untyped
      
      The JSON schema describing the tool's input.
    - name: String
      
      The name of the tool.
    - annotations: untyped
      
      Additional annotations about the tool.
    - description: String
      
      The description of the tool.
  - type: :mcp_list_tools
    
    The type of the item. Always mcp_list_tools.
    - :mcp_list_tools
  - error: String
    
    Error message if the server could not list tools.
- class McpApprovalRequest
  
  A request for human approval of a tool invocation.
  - id: String
    
    The unique ID of the approval request.
  - arguments: String
    
    A JSON string of arguments for the tool.
  - name: String
    
    The name of the tool to run.
  - server_label: String
    
    The label of the MCP server making the request.
  - type: :mcp_approval_request
    
    The type of the item. Always mcp_approval_request.
    - :mcp_approval_request
- class McpApprovalResponse
  
  A response to an MCP approval request.
  - approval_request_id: String
    
    The ID of the approval request being answered.
  - approve: bool
    
    Whether the request was approved.
  - type: :mcp_approval_response
    
    The type of the item. Always mcp_approval_response.
    - :mcp_approval_response
  - id: String
    
    The unique ID of the approval response
  - reason: String
    
    Optional reason for the decision.
- class McpCall
  
  An invocation of a tool on an MCP server.
  - id: String
    
    The unique ID of the tool call.
  - arguments: String
    
    A JSON string of the arguments passed to the tool.
  - name: String
    
    The name of the tool that was run.
  - server_label: String
    
    The label of the MCP server running the tool.
  - type: :mcp_call
    
    The type of the item. Always mcp_call.
    - :mcp_call
  - approval_request_id: String
    
    Unique identifier for the MCP tool call approval request. Include this value in a subsequent mcp_approval_response input to approve or reject the corresponding tool call.
  - error: String
    
    The error from the tool call, if any.
  - output: String
    
    The output from the tool call.
  - status: :in_progress | :completed | :incomplete | 2 more
    
    The status of the tool call. One of in_progress, completed, incomplete, calling, or failed.
    - :in_progress
    - :completed
    - :incomplete
    - :calling
    - :failed
- class ResponseCustomToolCallOutput
  
  The output of a custom tool call from your code, being sent back to the model.
  - call_id: String
    
    The call ID, used to map this custom tool call output to a custom tool call.
  - output: String | Array[ResponseInputText | ResponseInputImage | ResponseInputFile]
    
    The output from the custom tool call generated by your code. Can be a string or an list of output content.
    - String = String
      
      A string of the output of the custom tool call.
    - OutputContentList = Array[ResponseInputText | ResponseInputImage | ResponseInputFile]
      
      Text, image, or file output of the custom tool call.
      - class ResponseInputText
        
        A text input to the model.
      - class ResponseInputImage
        
        An image input to the model. Learn about image inputs.
      - class ResponseInputFile
        
        A file input to the model.
  - type: :custom_tool_call_output
    
    The type of the custom tool call output. Always custom_tool_call_output.
    - :custom_tool_call_output
  - id: String
    
    The unique ID of the custom tool call output in the OpenAI platform.
- class ResponseCustomToolCall
  
  A call to a custom tool created by the model.
  - call_id: String
    
    An identifier used to map this custom tool call to a tool call output.
  - input: String
    
    The input for the custom tool call generated by the model.
  - name: String
    
    The name of the custom tool being called.
  - type: :custom_tool_call
    
    The type of the custom tool call. Always custom_tool_call.
    - :custom_tool_call
  - id: String
    
    The unique ID of the custom tool call in the OpenAI platform.
  - namespace: String
    
    The namespace of the custom tool being called.
- class CompactionTrigger
  
  Compacts the current context. Must be the final input item.
  - type: :compaction_trigger
    
    The type of the item. Always compaction_trigger.
    - :compaction_trigger
- class ItemReference
  
  An internal identifier for an item to reference.
  - id: String
    
    The ID of the item to reference.
  - type: :item_reference
    
    The type of item to reference. Always item_reference.
    - :item_reference
metadata: Metadata

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

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

Returns

class Conversation
- id: String
  
  The unique ID of the conversation.
- created_at: Integer
  
  The time at which the conversation was created, measured in seconds since the Unix epoch.
- metadata: untyped
  
  Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
- object: :conversation
  
  The object type, which is always conversation.
  - :conversation

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

conversation = openai.conversations.create

puts(conversation)

Response

{
  "id": "id",
  "created_at": 0,
  "metadata": {},
  "object": "conversation"
}

ruby/resources/conversations/methods/create/index.md +3116 −0 created

1## Create a conversation

3`conversations.create(**kwargs) -> Conversation`

5**post** `/conversations`

7Create a conversation.

9### Parameters

11- `items: Array[ResponseInputItem]`

13 Initial items to include in the conversation context. You may add up to 20 items at a time.

15 - `class EasyInputMessage`

17 A message input to the model with a role indicating instruction following

18 hierarchy. Instructions given with the `developer` or `system` role take

19 precedence over instructions given with the `user` role. Messages with the

20 `assistant` role are presumed to have been generated by the model in previous

21 interactions.

23 - `content: String | ResponseInputMessageContentList`

25 Text, image, or audio input to the model, used to generate a response.

26 Can also contain previous assistant responses.

28 - `String = String`

30 A text input to the model.

32 - `ResponseInputMessageContentList = Array[ResponseInputContent]`

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

35 types.

37 - `class ResponseInputText`

39 A text input to the model.

41 - `text: String`

43 The text input to the model.

45 - `type: :input_text`

47 The type of the input item. Always `input_text`.

49 - `:input_text`

51 - `class ResponseInputImage`

53 An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision).

55 - `detail: :low | :high | :auto | :original`

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

59 - `:low`

61 - `:high`

63 - `:auto`

65 - `:original`

67 - `type: :input_image`

69 The type of the input item. Always `input_image`.

71 - `:input_image`

73 - `file_id: String`

75 The ID of the file to be sent to the model.

77 - `image_url: String`

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

81 - `class ResponseInputFile`

83 A file input to the model.

85 - `type: :input_file`

87 The type of the input item. Always `input_file`.

89 - `:input_file`

91 - `detail: :low | :high`

93 The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`.

95 - `:low`

97 - `:high`

99 - `file_data: String`

100

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

102

103 - `file_id: String`

104

105 The ID of the file to be sent to the model.

106

107 - `file_url: String`

108

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

110

111 - `filename: String`

112

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

114

115 - `role: :user | :assistant | :system | :developer`

116

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

118 `developer`.

119

120 - `:user`

121

122 - `:assistant`

123

124 - `:system`

125

126 - `:developer`

127

128 - `phase: :commentary | :final_answer`

129

130 Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`).

131 For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend

132 phase on all assistant messages — dropping it can degrade performance. Not used for user messages.

133

134 - `:commentary`

135

136 - `:final_answer`

137

138 - `type: :message`

139

140 The type of the message input. Always `message`.

141

142 - `:message`

143

144 - `class Message`

145

146 A message input to the model with a role indicating instruction following

147 hierarchy. Instructions given with the `developer` or `system` role take

148 precedence over instructions given with the `user` role.

149

150 - `content: ResponseInputMessageContentList`

151

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

153 types.

154

155 - `role: :user | :system | :developer`

156

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

158

159 - `:user`

160

161 - `:system`

162

163 - `:developer`

164

165 - `status: :in_progress | :completed | :incomplete`

166

167 The status of item. One of `in_progress`, `completed`, or

168 `incomplete`. Populated when items are returned via API.

169

170 - `:in_progress`

171

172 - `:completed`

173

174 - `:incomplete`

175

176 - `type: :message`

177

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

179

180 - `:message`

181

182 - `class ResponseOutputMessage`

183

184 An output message from the model.

185

186 - `id: String`

187

188 The unique ID of the output message.

189

190 - `content: Array[ResponseOutputText | ResponseOutputRefusal]`

191

192 The content of the output message.

193

194 - `class ResponseOutputText`

195

196 A text output from the model.

197

198 - `annotations: Array[FileCitation{ file_id, filename, index, type} | URLCitation{ end_index, start_index, title, 2 more} | ContainerFileCitation{ container_id, end_index, file_id, 3 more} | FilePath{ file_id, index, type}]`

199

200 The annotations of the text output.

201

202 - `class FileCitation`

203

204 A citation to a file.

205

206 - `file_id: String`

207

208 The ID of the file.

209

210 - `filename: String`

211

212 The filename of the file cited.

213

214 - `index: Integer`

215

216 The index of the file in the list of files.

217

218 - `type: :file_citation`

219

220 The type of the file citation. Always `file_citation`.

221

222 - `:file_citation`

223

224 - `class URLCitation`

225

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

227

228 - `end_index: Integer`

229

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

231

232 - `start_index: Integer`

233

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

235

236 - `title: String`

237

238 The title of the web resource.

239

240 - `type: :url_citation`

241

242 The type of the URL citation. Always `url_citation`.

243

244 - `:url_citation`

245

246 - `url: String`

247

248 The URL of the web resource.

249

250 - `class ContainerFileCitation`

251

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

253

254 - `container_id: String`

255

256 The ID of the container file.

257

258 - `end_index: Integer`

259

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

261

262 - `file_id: String`

263

264 The ID of the file.

265

266 - `filename: String`

267

268 The filename of the container file cited.

269

270 - `start_index: Integer`

271

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

273

274 - `type: :container_file_citation`

275

276 The type of the container file citation. Always `container_file_citation`.

277

278 - `:container_file_citation`

279

280 - `class FilePath`

281

282 A path to a file.

283

284 - `file_id: String`

285

286 The ID of the file.

287

288 - `index: Integer`

289

290 The index of the file in the list of files.

291

292 - `type: :file_path`

293

294 The type of the file path. Always `file_path`.

295

296 - `:file_path`

297

298 - `text: String`

299

300 The text output from the model.

301

302 - `type: :output_text`

303

304 The type of the output text. Always `output_text`.

305

306 - `:output_text`

307

308 - `logprobs: Array[Logprob{ token, bytes, logprob, top_logprobs}]`

309

310 - `token: String`

311

312 - `bytes: Array[Integer]`

313

314 - `logprob: Float`

315

316 - `top_logprobs: Array[TopLogprob{ token, bytes, logprob}]`

317

318 - `token: String`

319

320 - `bytes: Array[Integer]`

321

322 - `logprob: Float`

323

324 - `class ResponseOutputRefusal`

325

326 A refusal from the model.

327

328 - `refusal: String`

329

330 The refusal explanation from the model.

331

332 - `type: :refusal`

333

334 The type of the refusal. Always `refusal`.

335

336 - `:refusal`

337

338 - `role: :assistant`

339

340 The role of the output message. Always `assistant`.

341

342 - `:assistant`

343

344 - `status: :in_progress | :completed | :incomplete`

345

346 The status of the message input. One of `in_progress`, `completed`, or

347 `incomplete`. Populated when input items are returned via API.

348

349 - `:in_progress`

350

351 - `:completed`

352

353 - `:incomplete`

354

355 - `type: :message`

356

357 The type of the output message. Always `message`.

358

359 - `:message`

360

361 - `phase: :commentary | :final_answer`

362

363 Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`).

364 For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend

365 phase on all assistant messages — dropping it can degrade performance. Not used for user messages.

366

367 - `:commentary`

368

369 - `:final_answer`

370

371 - `class ResponseFileSearchToolCall`

372

373 The results of a file search tool call. See the

374 [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information.

375

376 - `id: String`

377

378 The unique ID of the file search tool call.

379

380 - `queries: Array[String]`

381

382 The queries used to search for files.

383

384 - `status: :in_progress | :searching | :completed | 2 more`

385

386 The status of the file search tool call. One of `in_progress`,

387 `searching`, `incomplete` or `failed`,

388

389 - `:in_progress`

390

391 - `:searching`

392

393 - `:completed`

394

395 - `:incomplete`

396

397 - `:failed`

398

399 - `type: :file_search_call`

400

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

402

403 - `:file_search_call`

404

405 - `results: Array[Result{ attributes, file_id, filename, 2 more}]`

406

407 The results of the file search tool call.

408

409 - `attributes: Hash[Symbol, String | Float | bool]`

410

411 Set of 16 key-value pairs that can be attached to an object. This can be

412 useful for storing additional information about the object in a structured

413 format, and querying for objects via API or the dashboard. Keys are strings

414 with a maximum length of 64 characters. Values are strings with a maximum

415 length of 512 characters, booleans, or numbers.

416

417 - `String = String`

418

419 - `Float = Float`

420

421 - `UnionMember2 = bool`

422

423 - `file_id: String`

424

425 The unique ID of the file.

426

427 - `filename: String`

428

429 The name of the file.

430

431 - `score: Float`

432

433 The relevance score of the file - a value between 0 and 1.

434

435 - `text: String`

436

437 The text that was retrieved from the file.

438

439 - `class ResponseComputerToolCall`

440

441 A tool call to a computer use tool. See the

442 [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information.

443

444 - `id: String`

445

446 The unique ID of the computer call.

447

448 - `call_id: String`

449

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

451

452 - `pending_safety_checks: Array[PendingSafetyCheck{ id, code, message}]`

453

454 The pending safety checks for the computer call.

455

456 - `id: String`

457

458 The ID of the pending safety check.

459

460 - `code: String`

461

462 The type of the pending safety check.

463

464 - `message: String`

465

466 Details about the pending safety check.

467

468 - `status: :in_progress | :completed | :incomplete`

469

470 The status of the item. One of `in_progress`, `completed`, or

471 `incomplete`. Populated when items are returned via API.

472

473 - `:in_progress`

474

475 - `:completed`

476

477 - `:incomplete`

478

479 - `type: :computer_call`

480

481 The type of the computer call. Always `computer_call`.

482

483 - `:computer_call`

484

485 - `action: Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more`

486

487 A click action.

488

489 - `class Click`

490

491 A click action.

492

493 - `button: :left | :right | :wheel | 2 more`

494

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

496

497 - `:left`

498

499 - `:right`

500

501 - `:wheel`

502

503 - `:back`

504

505 - `:forward`

506

507 - `type: :click`

508

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

510

511 - `:click`

512

513 - `x: Integer`

514

515 The x-coordinate where the click occurred.

516

517 - `y_: Integer`

518

519 The y-coordinate where the click occurred.

520

521 - `keys: Array[String]`

522

523 The keys being held while clicking.

524

525 - `class DoubleClick`

526

527 A double click action.

528

529 - `keys: Array[String]`

530

531 The keys being held while double-clicking.

532

533 - `type: :double_click`

534

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

536

537 - `:double_click`

538

539 - `x: Integer`

540

541 The x-coordinate where the double click occurred.

542

543 - `y_: Integer`

544

545 The y-coordinate where the double click occurred.

546

547 - `class Drag`

548

549 A drag action.

550

551 - `path: Array[Path{ x, y_}]`

552

553 An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg

554

555 ```

556 [

557 { x: 100, y: 200 },

558 { x: 200, y: 300 }

559 ]

560 ```

561

562 - `x: Integer`

563

564 The x-coordinate.

565

566 - `y_: Integer`

567

568 The y-coordinate.

569

570 - `type: :drag`

571

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

573

574 - `:drag`

575

576 - `keys: Array[String]`

577

578 The keys being held while dragging the mouse.

579

580 - `class Keypress`

581

582 A collection of keypresses the model would like to perform.

583

584 - `keys: Array[String]`

585

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

587

588 - `type: :keypress`

589

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

591

592 - `:keypress`

593

594 - `class Move`

595

596 A mouse move action.

597

598 - `type: :move`

599

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

601

602 - `:move`

603

604 - `x: Integer`

605

606 The x-coordinate to move to.

607

608 - `y_: Integer`

609

610 The y-coordinate to move to.

611

612 - `keys: Array[String]`

613

614 The keys being held while moving the mouse.

615

616 - `class Screenshot`

617

618 A screenshot action.

619

620 - `type: :screenshot`

621

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

623

624 - `:screenshot`

625

626 - `class Scroll`

627

628 A scroll action.

629

630 - `scroll_x: Integer`

631

632 The horizontal scroll distance.

633

634 - `scroll_y: Integer`

635

636 The vertical scroll distance.

637

638 - `type: :scroll`

639

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

641

642 - `:scroll`

643

644 - `x: Integer`

645

646 The x-coordinate where the scroll occurred.

647

648 - `y_: Integer`

649

650 The y-coordinate where the scroll occurred.

651

652 - `keys: Array[String]`

653

654 The keys being held while scrolling.

655

656 - `class Type`

657

658 An action to type in text.

659

660 - `text: String`

661

662 The text to type.

663

664 - `type: :type`

665

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

667

668 - `:type`

669

670 - `class Wait`

671

672 A wait action.

673

674 - `type: :wait`

675

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

677

678 - `:wait`

679

680 - `actions: ComputerActionList`

681

682 Flattened batched actions for `computer_use`. Each action includes an

683 `type` discriminator and action-specific fields.

684

685 - `class Click`

686

687 A click action.

688

689 - `button: :left | :right | :wheel | 2 more`

690

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

692

693 - `:left`

694

695 - `:right`

696

697 - `:wheel`

698

699 - `:back`

700

701 - `:forward`

702

703 - `type: :click`

704

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

706

707 - `:click`

708

709 - `x: Integer`

710

711 The x-coordinate where the click occurred.

712

713 - `y_: Integer`

714

715 The y-coordinate where the click occurred.

716

717 - `keys: Array[String]`

718

719 The keys being held while clicking.

720

721 - `class DoubleClick`

722

723 A double click action.

724

725 - `keys: Array[String]`

726

727 The keys being held while double-clicking.

728

729 - `type: :double_click`

730

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

732

733 - `:double_click`

734

735 - `x: Integer`

736

737 The x-coordinate where the double click occurred.

738

739 - `y_: Integer`

740

741 The y-coordinate where the double click occurred.

742

743 - `class Drag`

744

745 A drag action.

746

747 - `path: Array[Path{ x, y_}]`

748

749 An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg

750

751 ```

752 [

753 { x: 100, y: 200 },

754 { x: 200, y: 300 }

755 ]

756 ```

757

758 - `x: Integer`

759

760 The x-coordinate.

761

762 - `y_: Integer`

763

764 The y-coordinate.

765

766 - `type: :drag`

767

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

769

770 - `:drag`

771

772 - `keys: Array[String]`

773

774 The keys being held while dragging the mouse.

775

776 - `class Keypress`

777

778 A collection of keypresses the model would like to perform.

779

780 - `keys: Array[String]`

781

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

783

784 - `type: :keypress`

785

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

787

788 - `:keypress`

789

790 - `class Move`

791

792 A mouse move action.

793

794 - `type: :move`

795

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

797

798 - `:move`

799

800 - `x: Integer`

801

802 The x-coordinate to move to.

803

804 - `y_: Integer`

805

806 The y-coordinate to move to.

807

808 - `keys: Array[String]`

809

810 The keys being held while moving the mouse.

811

812 - `class Screenshot`

813

814 A screenshot action.

815

816 - `type: :screenshot`

817

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

819

820 - `:screenshot`

821

822 - `class Scroll`

823

824 A scroll action.

825

826 - `scroll_x: Integer`

827

828 The horizontal scroll distance.

829

830 - `scroll_y: Integer`

831

832 The vertical scroll distance.

833

834 - `type: :scroll`

835

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

837

838 - `:scroll`

839

840 - `x: Integer`

841

842 The x-coordinate where the scroll occurred.

843

844 - `y_: Integer`

845

846 The y-coordinate where the scroll occurred.

847

848 - `keys: Array[String]`

849

850 The keys being held while scrolling.

851

852 - `class Type`

853

854 An action to type in text.

855

856 - `text: String`

857

858 The text to type.

859

860 - `type: :type`

861

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

863

864 - `:type`

865

866 - `class Wait`

867

868 A wait action.

869

870 - `type: :wait`

871

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

873

874 - `:wait`

875

876 - `class ComputerCallOutput`

877

878 The output of a computer tool call.

879

880 - `call_id: String`

881

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

883

884 - `output: ResponseComputerToolCallOutputScreenshot`

885

886 A computer screenshot image used with the computer use tool.

887

888 - `type: :computer_screenshot`

889

890 Specifies the event type. For a computer screenshot, this property is

891 always set to `computer_screenshot`.

892

893 - `:computer_screenshot`

894

895 - `file_id: String`

896

897 The identifier of an uploaded file that contains the screenshot.

898

899 - `image_url: String`

900

901 The URL of the screenshot image.

902

903 - `type: :computer_call_output`

904

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

906

907 - `:computer_call_output`

908

909 - `id: String`

910

911 The ID of the computer tool call output.

912

913 - `acknowledged_safety_checks: Array[AcknowledgedSafetyCheck{ id, code, message}]`

914

915 The safety checks reported by the API that have been acknowledged by the developer.

916

917 - `id: String`

918

919 The ID of the pending safety check.

920

921 - `code: String`

922

923 The type of the pending safety check.

924

925 - `message: String`

926

927 Details about the pending safety check.

928

929 - `status: :in_progress | :completed | :incomplete`

930

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

932

933 - `:in_progress`

934

935 - `:completed`

936

937 - `:incomplete`

938

939 - `class ResponseFunctionWebSearch`

940

941 The results of a web search tool call. See the

942 [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information.

943

944 - `id: String`

945

946 The unique ID of the web search tool call.

947

948 - `action: Search{ type, queries, query, sources} | OpenPage{ type, url} | FindInPage{ pattern, type, url}`

949

950 An object describing the specific action taken in this web search call.

951 Includes details on how the model used the web (search, open_page, find_in_page).

952

953 - `class Search`

954

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

956

957 - `type: :search`

958

959 The action type.

960

961 - `:search`

962

963 - `queries: Array[String]`

964

965 The search queries.

966

967 - `query: String`

968

969 The search query.

970

971 - `sources: Array[Source{ type, url}]`

972

973 The sources used in the search.

974

975 - `type: :url`

976

977 The type of source. Always `url`.

978

979 - `:url`

980

981 - `url: String`

982

983 The URL of the source.

984

985 - `class OpenPage`

986

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

988

989 - `type: :open_page`

990

991 The action type.

992

993 - `:open_page`

994

995 - `url: String`

996

997 The URL opened by the model.

998

999 - `class FindInPage`

1000

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

1002

1003 - `pattern: String`

1004

1005 The pattern or text to search for within the page.

1006

1007 - `type: :find_in_page`

1008

1009 The action type.

1010

1011 - `:find_in_page`

1012

1013 - `url: String`

1014

1015 The URL of the page searched for the pattern.

1016

1017 - `status: :in_progress | :searching | :completed | :failed`

1018

1019 The status of the web search tool call.

1020

1021 - `:in_progress`

1022

1023 - `:searching`

1024

1025 - `:completed`

1026

1027 - `:failed`

1028

1029 - `type: :web_search_call`

1030

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

1032

1033 - `:web_search_call`

1034

1035 - `class ResponseFunctionToolCall`

1036

1037 A tool call to run a function. See the

1038 [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information.

1039

1040 - `arguments: String`

1041

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

1043

1044 - `call_id: String`

1045

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

1047

1048 - `name: String`

1049

1050 The name of the function to run.

1051

1052 - `type: :function_call`

1053

1054 The type of the function tool call. Always `function_call`.

1055

1056 - `:function_call`

1057

1058 - `id: String`

1059

1060 The unique ID of the function tool call.

1061

1062 - `namespace: String`

1063

1064 The namespace of the function to run.

1065

1066 - `status: :in_progress | :completed | :incomplete`

1067

1068 The status of the item. One of `in_progress`, `completed`, or

1069 `incomplete`. Populated when items are returned via API.

1070

1071 - `:in_progress`

1072

1073 - `:completed`

1074

1075 - `:incomplete`

1076

1077 - `class FunctionCallOutput`

1078

1079 The output of a function tool call.

1080

1081 - `call_id: String`

1082

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

1084

1085 - `output: String | ResponseFunctionCallOutputItemList`

1086

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

1088

1089 - `String = String`

1090

1091 A JSON string of the output of the function tool call.

1092

1093 - `ResponseFunctionCallOutputItemList = Array[ResponseFunctionCallOutputItem]`

1094

1095 An array of content outputs (text, image, file) for the function tool call.

1096

1097 - `class ResponseInputTextContent`

1098

1099 A text input to the model.

1100

1101 - `text: String`

1102

1103 The text input to the model.

1104

1105 - `type: :input_text`

1106

1107 The type of the input item. Always `input_text`.

1108

1109 - `:input_text`

1110

1111 - `class ResponseInputImageContent`

1112

1113 An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision)

1114

1115 - `type: :input_image`

1116

1117 The type of the input item. Always `input_image`.

1118

1119 - `:input_image`

1120

1121 - `detail: :low | :high | :auto | :original`

1122

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

1124

1125 - `:low`

1126

1127 - `:high`

1128

1129 - `:auto`

1130

1131 - `:original`

1132

1133 - `file_id: String`

1134

1135 The ID of the file to be sent to the model.

1136

1137 - `image_url: String`

1138

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

1140

1141 - `class ResponseInputFileContent`

1142

1143 A file input to the model.

1144

1145 - `type: :input_file`

1146

1147 The type of the input item. Always `input_file`.

1148

1149 - `:input_file`

1150

1151 - `detail: :low | :high`

1152

1153 The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`.

1154

1155 - `:low`

1156

1157 - `:high`

1158

1159 - `file_data: String`

1160

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

1162

1163 - `file_id: String`

1164

1165 The ID of the file to be sent to the model.

1166

1167 - `file_url: String`

1168

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

1170

1171 - `filename: String`

1172

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

1174

1175 - `type: :function_call_output`

1176

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

1178

1179 - `:function_call_output`

1180

1181 - `id: String`

1182

1183 The unique ID of the function tool call output. Populated when this item is returned via API.

1184

1185 - `status: :in_progress | :completed | :incomplete`

1186

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

1188

1189 - `:in_progress`

1190

1191 - `:completed`

1192

1193 - `:incomplete`

1194

1195 - `class ToolSearchCall`

1196

1197 - `arguments: untyped`

1198

1199 The arguments supplied to the tool search call.

1200

1201 - `type: :tool_search_call`

1202

1203 The item type. Always `tool_search_call`.

1204

1205 - `:tool_search_call`

1206

1207 - `id: String`

1208

1209 The unique ID of this tool search call.

1210

1211 - `call_id: String`

1212

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

1214

1215 - `execution: :server | :client`

1216

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

1218

1219 - `:server`

1220

1221 - `:client`

1222

1223 - `status: :in_progress | :completed | :incomplete`

1224

1225 The status of the tool search call.

1226

1227 - `:in_progress`

1228

1229 - `:completed`

1230

1231 - `:incomplete`

1232

1233 - `class ResponseToolSearchOutputItemParam`

1234

1235 - `tools: Array[Tool]`

1236

1237 The loaded tool definitions returned by the tool search output.

1238

1239 - `class FunctionTool`

1240

1241 Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling).

1242

1243 - `name: String`

1244

1245 The name of the function to call.

1246

1247 - `parameters: Hash[Symbol, untyped]`

1248

1249 A JSON schema object describing the parameters of the function.

1250

1251 - `strict: bool`

1252

1253 Whether to enforce strict parameter validation. Default `true`.

1254

1255 - `type: :function`

1256

1257 The type of the function tool. Always `function`.

1258

1259 - `:function`

1260

1261 - `defer_loading: bool`

1262

1263 Whether this function is deferred and loaded via tool search.

1264

1265 - `description: String`

1266

1267 A description of the function. Used by the model to determine whether or not to call the function.

1268

1269 - `class FileSearchTool`

1270

1271 A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search).

1272

1273 - `type: :file_search`

1274

1275 The type of the file search tool. Always `file_search`.

1276

1277 - `:file_search`

1278

1279 - `vector_store_ids: Array[String]`

1280

1281 The IDs of the vector stores to search.

1282

1283 - `filters: ComparisonFilter | CompoundFilter`

1284

1285 A filter to apply.

1286

1287 - `class ComparisonFilter`

1288

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

1290

1291 - `key: String`

1292

1293 The key to compare against the value.

1294

1295 - `type: :eq | :ne | :gt | 5 more`

1296

1297 Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`.

1298

1299 - `eq`: equals

1300 - `ne`: not equal

1301 - `gt`: greater than

1302 - `gte`: greater than or equal

1303 - `lt`: less than

1304 - `lte`: less than or equal

1305 - `in`: in

1306 - `nin`: not in

1307

1308 - `:eq`

1309

1310 - `:ne`

1311

1312 - `:gt`

1313

1314 - `:gte`

1315

1316 - `:lt`

1317

1318 - `:lte`

1319

1320 - `:in`

1321

1322 - `:nin`

1323

1324 - `value: String | Float | bool | Array[String | Float]`

1325

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

1327

1328 - `String = String`

1329

1330 - `Float = Float`

1331

1332 - `UnionMember2 = bool`

1333

1334 - `UnionMember3 = Array[String | Float]`

1335

1336 - `String = String`

1337

1338 - `Float = Float`

1339

1340 - `class CompoundFilter`

1341

1342 Combine multiple filters using `and` or `or`.

1343

1344 - `filters: Array[ComparisonFilter | untyped]`

1345

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

1347

1348 - `class ComparisonFilter`

1349

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

1351

1352 - `UnionMember1 = untyped`

1353

1354 - `type: :and | :or`

1355

1356 Type of operation: `and` or `or`.

1357

1358 - `:and`

1359

1360 - `:or`

1361

1362 - `max_num_results: Integer`

1363

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

1365

1366 - `ranking_options: RankingOptions{ hybrid_search, ranker, score_threshold}`

1367

1368 Ranking options for search.

1369

1370 - `hybrid_search: HybridSearch{ embedding_weight, text_weight}`

1371

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

1373

1374 - `embedding_weight: Float`

1375

1376 The weight of the embedding in the reciprocal ranking fusion.

1377

1378 - `text_weight: Float`

1379

1380 The weight of the text in the reciprocal ranking fusion.

1381

1382 - `ranker: :auto | :"default-2024-11-15"`

1383

1384 The ranker to use for the file search.

1385

1386 - `:auto`

1387

1388 - `:"default-2024-11-15"`

1389

1390 - `score_threshold: Float`

1391

1392 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.

1393

1394 - `class ComputerTool`

1395

1396 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

1397

1398 - `type: :computer`

1399

1400 The type of the computer tool. Always `computer`.

1401

1402 - `:computer`

1403

1404 - `class ComputerUsePreviewTool`

1405

1406 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

1407

1408 - `display_height: Integer`

1409

1410 The height of the computer display.

1411

1412 - `display_width: Integer`

1413

1414 The width of the computer display.

1415

1416 - `environment: :windows | :mac | :linux | 2 more`

1417

1418 The type of computer environment to control.

1419

1420 - `:windows`

1421

1422 - `:mac`

1423

1424 - `:linux`

1425

1426 - `:ubuntu`

1427

1428 - `:browser`

1429

1430 - `type: :computer_use_preview`

1431

1432 The type of the computer use tool. Always `computer_use_preview`.

1433

1434 - `:computer_use_preview`

1435

1436 - `class WebSearchTool`

1437

1438 Search the Internet for sources related to the prompt. Learn more about the

1439 [web search tool](https://platform.openai.com/docs/guides/tools-web-search).

1440

1441 - `type: :web_search | :web_search_2025_08_26`

1442

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

1444

1445 - `:web_search`

1446

1447 - `:web_search_2025_08_26`

1448

1449 - `filters: Filters{ allowed_domains}`

1450

1451 Filters for the search.

1452

1453 - `allowed_domains: Array[String]`

1454

1455 Allowed domains for the search. If not provided, all domains are allowed.

1456 Subdomains of the provided domains are allowed as well.

1457

1458 Example: `["pubmed.ncbi.nlm.nih.gov"]`

1459

1460 - `search_context_size: :low | :medium | :high`

1461

1462 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.

1463

1464 - `:low`

1465

1466 - `:medium`

1467

1468 - `:high`

1469

1470 - `user_location: UserLocation{ city, country, region, 2 more}`

1471

1472 The approximate location of the user.

1473

1474 - `city: String`

1475

1476 Free text input for the city of the user, e.g. `San Francisco`.

1477

1478 - `country: String`

1479

1480 The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.

1481

1482 - `region: String`

1483

1484 Free text input for the region of the user, e.g. `California`.

1485

1486 - `timezone: String`

1487

1488 The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.

1489

1490 - `type: :approximate`

1491

1492 The type of location approximation. Always `approximate`.

1493

1494 - `:approximate`

1495

1496 - `class Mcp`

1497

1498 Give the model access to additional tools via remote Model Context Protocol

1499 (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp).

1500

1501 - `server_label: String`

1502

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

1504

1505 - `type: :mcp`

1506

1507 The type of the MCP tool. Always `mcp`.

1508

1509 - `:mcp`

1510

1511 - `allowed_tools: Array[String] | McpToolFilter{ read_only, tool_names}`

1512

1513 List of allowed tool names or a filter object.

1514

1515 - `McpAllowedTools = Array[String]`

1516

1517 A string array of allowed tool names

1518

1519 - `class McpToolFilter`

1520

1521 A filter object to specify which tools are allowed.

1522

1523 - `read_only: bool`

1524

1525 Indicates whether or not a tool modifies data or is read-only. If an

1526 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1527 it will match this filter.

1528

1529 - `tool_names: Array[String]`

1530

1531 List of allowed tool names.

1532

1533 - `authorization: String`

1534

1535 An OAuth access token that can be used with a remote MCP server, either

1536 with a custom MCP server URL or a service connector. Your application

1537 must handle the OAuth authorization flow and provide the token here.

1538

1539 - `connector_id: :connector_dropbox | :connector_gmail | :connector_googlecalendar | 5 more`

1540

1541 Identifier for service connectors, like those available in ChatGPT. One of

1542 `server_url` or `connector_id` must be provided. Learn more about service

1543 connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors).

1544

1545 Currently supported `connector_id` values are:

1546

1547 - Dropbox: `connector_dropbox`

1548 - Gmail: `connector_gmail`

1549 - Google Calendar: `connector_googlecalendar`

1550 - Google Drive: `connector_googledrive`

1551 - Microsoft Teams: `connector_microsoftteams`

1552 - Outlook Calendar: `connector_outlookcalendar`

1553 - Outlook Email: `connector_outlookemail`

1554 - SharePoint: `connector_sharepoint`

1555

1556 - `:connector_dropbox`

1557

1558 - `:connector_gmail`

1559

1560 - `:connector_googlecalendar`

1561

1562 - `:connector_googledrive`

1563

1564 - `:connector_microsoftteams`

1565

1566 - `:connector_outlookcalendar`

1567

1568 - `:connector_outlookemail`

1569

1570 - `:connector_sharepoint`

1571

1572 - `defer_loading: bool`

1573

1574 Whether this MCP tool is deferred and discovered via tool search.

1575

1576 - `headers: Hash[Symbol, String]`

1577

1578 Optional HTTP headers to send to the MCP server. Use for authentication

1579 or other purposes.

1580

1581 - `require_approval: McpToolApprovalFilter{ always, never} | :always | :never`

1582

1583 Specify which of the MCP server's tools require approval.

1584

1585 - `class McpToolApprovalFilter`

1586

1587 Specify which of the MCP server's tools require approval. Can be

1588 `always`, `never`, or a filter object associated with tools

1589 that require approval.

1590

1591 - `always: Always{ read_only, tool_names}`

1592

1593 A filter object to specify which tools are allowed.

1594

1595 - `read_only: bool`

1596

1597 Indicates whether or not a tool modifies data or is read-only. If an

1598 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1599 it will match this filter.

1600

1601 - `tool_names: Array[String]`

1602

1603 List of allowed tool names.

1604

1605 - `never: Never{ read_only, tool_names}`

1606

1607 A filter object to specify which tools are allowed.

1608

1609 - `read_only: bool`

1610

1611 Indicates whether or not a tool modifies data or is read-only. If an

1612 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1613 it will match this filter.

1614

1615 - `tool_names: Array[String]`

1616

1617 List of allowed tool names.

1618

1619 - `McpToolApprovalSetting = :always | :never`

1620

1621 Specify a single approval policy for all tools. One of `always` or

1622 `never`. When set to `always`, all tools will require approval. When

1623 set to `never`, all tools will not require approval.

1624

1625 - `:always`

1626

1627 - `:never`

1628

1629 - `server_description: String`

1630

1631 Optional description of the MCP server, used to provide more context.

1632

1633 - `server_url: String`

1634

1635 The URL for the MCP server. One of `server_url` or `connector_id` must be

1636 provided.

1637

1638 - `class CodeInterpreter`

1639

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

1641

1642 - `container: String | CodeInterpreterToolAuto{ type, file_ids, memory_limit, network_policy}`

1643

1644 The code interpreter container. Can be a container ID or an object that

1645 specifies uploaded file IDs to make available to your code, along with an

1646 optional `memory_limit` setting.

1647

1648 - `String = String`

1649

1650 The container ID.

1651

1652 - `class CodeInterpreterToolAuto`

1653

1654 Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

1655

1656 - `type: :auto`

1657

1658 Always `auto`.

1659

1660 - `:auto`

1661

1662 - `file_ids: Array[String]`

1663

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

1665

1666 - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"`

1667

1668 The memory limit for the code interpreter container.

1669

1670 - `:"1g"`

1671

1672 - `:"4g"`

1673

1674 - `:"16g"`

1675

1676 - `:"64g"`

1677

1678 - `network_policy: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist`

1679

1680 Network access policy for the container.

1681

1682 - `class ContainerNetworkPolicyDisabled`

1683

1684 - `type: :disabled`

1685

1686 Disable outbound network access. Always `disabled`.

1687

1688 - `:disabled`

1689

1690 - `class ContainerNetworkPolicyAllowlist`

1691

1692 - `allowed_domains: Array[String]`

1693

1694 A list of allowed domains when type is `allowlist`.

1695

1696 - `type: :allowlist`

1697

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

1699

1700 - `:allowlist`

1701

1702 - `domain_secrets: Array[ContainerNetworkPolicyDomainSecret]`

1703

1704 Optional domain-scoped secrets for allowlisted domains.

1705

1706 - `domain: String`

1707

1708 The domain associated with the secret.

1709

1710 - `name: String`

1711

1712 The name of the secret to inject for the domain.

1713

1714 - `value: String`

1715

1716 The secret value to inject for the domain.

1717

1718 - `type: :code_interpreter`

1719

1720 The type of the code interpreter tool. Always `code_interpreter`.

1721

1722 - `:code_interpreter`

1723

1724 - `class ImageGeneration`

1725

1726 A tool that generates images using the GPT image models.

1727

1728 - `type: :image_generation`

1729

1730 The type of the image generation tool. Always `image_generation`.

1731

1732 - `:image_generation`

1733

1734 - `action: :generate | :edit | :auto`

1735

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

1737

1738 - `:generate`

1739

1740 - `:edit`

1741

1742 - `:auto`

1743

1744 - `background: :transparent | :opaque | :auto`

1745

1746 Allows to set transparency for the background of the generated image(s).

1747 This parameter is only supported for GPT image models that support

1748 transparent backgrounds. Must be one of `transparent`, `opaque`, or

1749 `auto` (default value). When `auto` is used, the model will

1750 automatically determine the best background for the image.

1751

1752 `gpt-image-2` and `gpt-image-2-2026-04-21` do not support

1753 transparent backgrounds. Requests with `background` set to

1754 `transparent` will return an error for these models; use `opaque` or

1755 `auto` instead.

1756

1757 If `transparent`, the output format needs to support transparency,

1758 so it should be set to either `png` (default value) or `webp`.

1759

1760 - `:transparent`

1761

1762 - `:opaque`

1763

1764 - `:auto`

1765

1766 - `input_fidelity: :high | :low`

1767

1768 Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.

1769

1770 - `:high`

1771

1772 - `:low`

1773

1774 - `input_image_mask: InputImageMask{ file_id, image_url}`

1775

1776 Optional mask for inpainting. Contains `image_url`

1777 (string, optional) and `file_id` (string, optional).

1778

1779 - `file_id: String`

1780

1781 File ID for the mask image.

1782

1783 - `image_url: String`

1784

1785 Base64-encoded mask image.

1786

1787 - `model: String | :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more`

1788

1789 The image generation model to use. Default: `gpt-image-1`.

1790

1791 - `String = String`

1792

1793 - `Model = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 3 more`

1794

1795 The image generation model to use. Default: `gpt-image-1`.

1796

1797 - `:"gpt-image-1"`

1798

1799 - `:"gpt-image-1-mini"`

1800

1801 - `:"gpt-image-2"`

1802

1803 - `:"gpt-image-2-2026-04-21"`

1804

1805 - `:"gpt-image-1.5"`

1806

1807 - `:"chatgpt-image-latest"`

1808

1809 - `moderation: :auto | :low`

1810

1811 Moderation level for the generated image. Default: `auto`.

1812

1813 - `:auto`

1814

1815 - `:low`

1816

1817 - `output_compression: Integer`

1818

1819 Compression level for the output image. Default: 100.

1820

1821 - `output_format: :png | :webp | :jpeg`

1822

1823 The output format of the generated image. One of `png`, `webp`, or

1824 `jpeg`. Default: `png`.

1825

1826 - `:png`

1827

1828 - `:webp`

1829

1830 - `:jpeg`

1831

1832 - `partial_images: Integer`

1833

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

1835

1836 - `quality: :low | :medium | :high | :auto`

1837

1838 The quality of the generated image. One of `low`, `medium`, `high`,

1839 or `auto`. Default: `auto`.

1840

1841 - `:low`

1842

1843 - `:medium`

1844

1845 - `:high`

1846

1847 - `:auto`

1848

1849 - `size: String | :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`

1850

1851 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

1852

1853 - `String = String`

1854

1855 - `Size = :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`

1856

1857 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, 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. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

1858

1859 - `:"1024x1024"`

1860

1861 - `:"1024x1536"`

1862

1863 - `:"1536x1024"`

1864

1865 - `:auto`

1866

1867 - `class LocalShell`

1868

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

1870

1871 - `type: :local_shell`

1872

1873 The type of the local shell tool. Always `local_shell`.

1874

1875 - `:local_shell`

1876

1877 - `class FunctionShellTool`

1878

1879 A tool that allows the model to execute shell commands.

1880

1881 - `type: :shell`

1882

1883 The type of the shell tool. Always `shell`.

1884

1885 - `:shell`

1886

1887 - `environment: ContainerAuto | LocalEnvironment | ContainerReference`

1888

1889 - `class ContainerAuto`

1890

1891 - `type: :container_auto`

1892

1893 Automatically creates a container for this request

1894

1895 - `:container_auto`

1896

1897 - `file_ids: Array[String]`

1898

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

1900

1901 - `memory_limit: :"1g" | :"4g" | :"16g" | :"64g"`

1902

1903 The memory limit for the container.

1904

1905 - `:"1g"`

1906

1907 - `:"4g"`

1908

1909 - `:"16g"`

1910

1911 - `:"64g"`

1912

1913 - `network_policy: ContainerNetworkPolicyDisabled | ContainerNetworkPolicyAllowlist`

1914

1915 Network access policy for the container.

1916

1917 - `class ContainerNetworkPolicyDisabled`

1918

1919 - `class ContainerNetworkPolicyAllowlist`

1920

1921 - `skills: Array[SkillReference | InlineSkill]`

1922

1923 An optional list of skills referenced by id or inline data.

1924

1925 - `class SkillReference`

1926

1927 - `skill_id: String`

1928

1929 The ID of the referenced skill.

1930

1931 - `type: :skill_reference`

1932

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

1934

1935 - `:skill_reference`

1936

1937 - `version: String`

1938

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

1940

1941 - `class InlineSkill`

1942

1943 - `description: String`

1944

1945 The description of the skill.

1946

1947 - `name: String`

1948

1949 The name of the skill.

1950

1951 - `source: InlineSkillSource`

1952

1953 Inline skill payload

1954

1955 - `data: String`

1956

1957 Base64-encoded skill zip bundle.

1958

1959 - `media_type: :"application/zip"`

1960

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

1962

1963 - `:"application/zip"`

1964

1965 - `type: :base64`

1966

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

1968

1969 - `:base64`

1970

1971 - `type: :inline`

1972

1973 Defines an inline skill for this request.

1974

1975 - `:inline`

1976

1977 - `class LocalEnvironment`

1978

1979 - `type: :local`

1980

1981 Use a local computer environment.

1982

1983 - `:local`

1984

1985 - `skills: Array[LocalSkill]`

1986

1987 An optional list of skills.

1988

1989 - `description: String`

1990

1991 The description of the skill.

1992

1993 - `name: String`

1994

1995 The name of the skill.

1996

1997 - `path: String`

1998

1999 The path to the directory containing the skill.

2000

2001 - `class ContainerReference`

2002

2003 - `container_id: String`

2004

2005 The ID of the referenced container.

2006

2007 - `type: :container_reference`

2008

2009 References a container created with the /v1/containers endpoint

2010

2011 - `:container_reference`

2012

2013 - `class CustomTool`

2014

2015 A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)

2016

2017 - `name: String`

2018

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

2020

2021 - `type: :custom`

2022

2023 The type of the custom tool. Always `custom`.

2024

2025 - `:custom`

2026

2027 - `defer_loading: bool`

2028

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

2030

2031 - `description: String`

2032

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

2034

2035 - `format_: CustomToolInputFormat`

2036

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

2038

2039 - `class Text`

2040

2041 Unconstrained free-form text.

2042

2043 - `type: :text`

2044

2045 Unconstrained text format. Always `text`.

2046

2047 - `:text`

2048

2049 - `class Grammar`

2050

2051 A grammar defined by the user.

2052

2053 - `definition: String`

2054

2055 The grammar definition.

2056

2057 - `syntax: :lark | :regex`

2058

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

2060

2061 - `:lark`

2062

2063 - `:regex`

2064

2065 - `type: :grammar`

2066

2067 Grammar format. Always `grammar`.

2068

2069 - `:grammar`

2070

2071 - `class NamespaceTool`

2072

2073 Groups function/custom tools under a shared namespace.

2074

2075 - `description: String`

2076

2077 A description of the namespace shown to the model.

2078

2079 - `name: String`

2080

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

2082

2083 - `tools: Array[Function{ name, type, defer_loading, 3 more} | CustomTool]`

2084

2085 The function/custom tools available inside this namespace.

2086

2087 - `class Function`

2088

2089 - `name: String`

2090

2091 - `type: :function`

2092

2093 - `:function`

2094

2095 - `defer_loading: bool`

2096

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

2098

2099 - `description: String`

2100

2101 - `parameters: untyped`

2102

2103 - `strict: bool`

2104

2105 - `class CustomTool`

2106

2107 A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)

2108

2109 - `type: :namespace`

2110

2111 The type of the tool. Always `namespace`.

2112

2113 - `:namespace`

2114

2115 - `class ToolSearchTool`

2116

2117 Hosted or BYOT tool search configuration for deferred tools.

2118

2119 - `type: :tool_search`

2120

2121 The type of the tool. Always `tool_search`.

2122

2123 - `:tool_search`

2124

2125 - `description: String`

2126

2127 Description shown to the model for a client-executed tool search tool.

2128

2129 - `execution: :server | :client`

2130

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

2132

2133 - `:server`

2134

2135 - `:client`

2136

2137 - `parameters: untyped`

2138

2139 Parameter schema for a client-executed tool search tool.

2140

2141 - `class WebSearchPreviewTool`

2142

2143 This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search).

2144

2145 - `type: :web_search_preview | :web_search_preview_2025_03_11`

2146

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

2148

2149 - `:web_search_preview`

2150

2151 - `:web_search_preview_2025_03_11`

2152

2153 - `search_content_types: Array[:text | :image]`

2154

2155 - `:text`

2156

2157 - `:image`

2158

2159 - `search_context_size: :low | :medium | :high`

2160

2161 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.

2162

2163 - `:low`

2164

2165 - `:medium`

2166

2167 - `:high`

2168

2169 - `user_location: UserLocation{ type, city, country, 2 more}`

2170

2171 The user's location.

2172

2173 - `type: :approximate`

2174

2175 The type of location approximation. Always `approximate`.

2176

2177 - `:approximate`

2178

2179 - `city: String`

2180

2181 Free text input for the city of the user, e.g. `San Francisco`.

2182

2183 - `country: String`

2184

2185 The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.

2186

2187 - `region: String`

2188

2189 Free text input for the region of the user, e.g. `California`.

2190

2191 - `timezone: String`

2192

2193 The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.

2194

2195 - `class ApplyPatchTool`

2196

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

2198

2199 - `type: :apply_patch`

2200

2201 The type of the tool. Always `apply_patch`.

2202

2203 - `:apply_patch`

2204

2205 - `type: :tool_search_output`

2206

2207 The item type. Always `tool_search_output`.

2208

2209 - `:tool_search_output`

2210

2211 - `id: String`

2212

2213 The unique ID of this tool search output.

2214

2215 - `call_id: String`

2216

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

2218

2219 - `execution: :server | :client`

2220

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

2222

2223 - `:server`

2224

2225 - `:client`

2226

2227 - `status: :in_progress | :completed | :incomplete`

2228

2229 The status of the tool search output.

2230

2231 - `:in_progress`

2232

2233 - `:completed`

2234

2235 - `:incomplete`

2236

2237 - `class AdditionalTools`

2238

2239 - `role: :developer`

2240

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

2242

2243 - `:developer`

2244

2245 - `tools: Array[Tool]`

2246

2247 A list of additional tools made available at this item.

2248

2249 - `class FunctionTool`

2250

2251 Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling).

2252

2253 - `class FileSearchTool`

2254

2255 A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search).

2256

2257 - `class ComputerTool`

2258

2259 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

2260

2261 - `class ComputerUsePreviewTool`

2262

2263 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

2264

2265 - `class WebSearchTool`

2266

2267 Search the Internet for sources related to the prompt. Learn more about the

2268 [web search tool](https://platform.openai.com/docs/guides/tools-web-search).

2269

2270 - `class Mcp`

2271

2272 Give the model access to additional tools via remote Model Context Protocol

2273 (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp).

2274

2275 - `class CodeInterpreter`

2276

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

2278

2279 - `class ImageGeneration`

2280

2281 A tool that generates images using the GPT image models.

2282

2283 - `class LocalShell`

2284

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

2286

2287 - `class FunctionShellTool`

2288

2289 A tool that allows the model to execute shell commands.

2290

2291 - `class CustomTool`

2292

2293 A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)

2294

2295 - `class NamespaceTool`

2296

2297 Groups function/custom tools under a shared namespace.

2298

2299 - `class ToolSearchTool`

2300

2301 Hosted or BYOT tool search configuration for deferred tools.

2302

2303 - `class WebSearchPreviewTool`

2304

2305 This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search).

2306

2307 - `class ApplyPatchTool`

2308

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

2310

2311 - `type: :additional_tools`

2312

2313 The item type. Always `additional_tools`.

2314

2315 - `:additional_tools`

2316

2317 - `id: String`

2318

2319 The unique ID of this additional tools item.

2320

2321 - `class ResponseReasoningItem`

2322

2323 A description of the chain of thought used by a reasoning model while generating

2324 a response. Be sure to include these items in your `input` to the Responses API

2325 for subsequent turns of a conversation if you are manually

2326 [managing context](https://platform.openai.com/docs/guides/conversation-state).

2327

2328 - `id: String`

2329

2330 The unique identifier of the reasoning content.

2331

2332 - `summary: Array[Summary{ text, type}]`

2333

2334 Reasoning summary content.

2335

2336 - `text: String`

2337

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

2339

2340 - `type: :summary_text`

2341

2342 The type of the object. Always `summary_text`.

2343

2344 - `:summary_text`

2345

2346 - `type: :reasoning`

2347

2348 The type of the object. Always `reasoning`.

2349

2350 - `:reasoning`

2351

2352 - `content: Array[Content{ text, type}]`

2353

2354 Reasoning text content.

2355

2356 - `text: String`

2357

2358 The reasoning text from the model.

2359

2360 - `type: :reasoning_text`

2361

2362 The type of the reasoning text. Always `reasoning_text`.

2363

2364 - `:reasoning_text`

2365

2366 - `encrypted_content: String`

2367

2368 The encrypted content of the reasoning item - populated when a response is

2369 generated with `reasoning.encrypted_content` in the `include` parameter.

2370

2371 - `status: :in_progress | :completed | :incomplete`

2372

2373 The status of the item. One of `in_progress`, `completed`, or

2374 `incomplete`. Populated when items are returned via API.

2375

2376 - `:in_progress`

2377

2378 - `:completed`

2379

2380 - `:incomplete`

2381

2382 - `class ResponseCompactionItemParam`

2383

2384 A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact).

2385

2386 - `encrypted_content: String`

2387

2388 The encrypted content of the compaction summary.

2389

2390 - `type: :compaction`

2391

2392 The type of the item. Always `compaction`.

2393

2394 - `:compaction`

2395

2396 - `id: String`

2397

2398 The ID of the compaction item.

2399

2400 - `class ImageGenerationCall`

2401

2402 An image generation request made by the model.

2403

2404 - `id: String`

2405

2406 The unique ID of the image generation call.

2407

2408 - `result: String`

2409

2410 The generated image encoded in base64.

2411

2412 - `status: :in_progress | :completed | :generating | :failed`

2413

2414 The status of the image generation call.

2415

2416 - `:in_progress`

2417

2418 - `:completed`

2419

2420 - `:generating`

2421

2422 - `:failed`

2423

2424 - `type: :image_generation_call`

2425

2426 The type of the image generation call. Always `image_generation_call`.

2427

2428 - `:image_generation_call`

2429

2430 - `class ResponseCodeInterpreterToolCall`

2431

2432 A tool call to run code.

2433

2434 - `id: String`

2435

2436 The unique ID of the code interpreter tool call.

2437

2438 - `code: String`

2439

2440 The code to run, or null if not available.

2441

2442 - `container_id: String`

2443

2444 The ID of the container used to run the code.

2445

2446 - `outputs: Array[Logs{ logs, type} | Image{ type, url}]`

2447

2448 The outputs generated by the code interpreter, such as logs or images.

2449 Can be null if no outputs are available.

2450

2451 - `class Logs`

2452

2453 The logs output from the code interpreter.

2454

2455 - `logs: String`

2456

2457 The logs output from the code interpreter.

2458

2459 - `type: :logs`

2460

2461 The type of the output. Always `logs`.

2462

2463 - `:logs`

2464

2465 - `class Image`

2466

2467 The image output from the code interpreter.

2468

2469 - `type: :image`

2470

2471 The type of the output. Always `image`.

2472

2473 - `:image`

2474

2475 - `url: String`

2476

2477 The URL of the image output from the code interpreter.

2478

2479 - `status: :in_progress | :completed | :incomplete | 2 more`

2480

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

2482

2483 - `:in_progress`

2484

2485 - `:completed`

2486

2487 - `:incomplete`

2488

2489 - `:interpreting`

2490

2491 - `:failed`

2492

2493 - `type: :code_interpreter_call`

2494

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

2496

2497 - `:code_interpreter_call`

2498

2499 - `class LocalShellCall`

2500

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

2502

2503 - `id: String`

2504

2505 The unique ID of the local shell call.

2506

2507 - `action: Action{ command, env, type, 3 more}`

2508

2509 Execute a shell command on the server.

2510

2511 - `command: Array[String]`

2512

2513 The command to run.

2514

2515 - `env: Hash[Symbol, String]`

2516

2517 Environment variables to set for the command.

2518

2519 - `type: :exec`

2520

2521 The type of the local shell action. Always `exec`.

2522

2523 - `:exec`

2524

2525 - `timeout_ms: Integer`

2526

2527 Optional timeout in milliseconds for the command.

2528

2529 - `user: String`

2530

2531 Optional user to run the command as.

2532

2533 - `working_directory: String`

2534

2535 Optional working directory to run the command in.

2536

2537 - `call_id: String`

2538

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

2540

2541 - `status: :in_progress | :completed | :incomplete`

2542

2543 The status of the local shell call.

2544

2545 - `:in_progress`

2546

2547 - `:completed`

2548

2549 - `:incomplete`

2550

2551 - `type: :local_shell_call`

2552

2553 The type of the local shell call. Always `local_shell_call`.

2554

2555 - `:local_shell_call`

2556

2557 - `class LocalShellCallOutput`

2558

2559 The output of a local shell tool call.

2560

2561 - `id: String`

2562

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

2564

2565 - `output: String`

2566

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

2568

2569 - `type: :local_shell_call_output`

2570

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

2572

2573 - `:local_shell_call_output`

2574

2575 - `status: :in_progress | :completed | :incomplete`

2576

2577 The status of the item. One of `in_progress`, `completed`, or `incomplete`.

2578

2579 - `:in_progress`

2580

2581 - `:completed`

2582

2583 - `:incomplete`

2584

2585 - `class ShellCall`

2586

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

2588

2589 - `action: Action{ commands, max_output_length, timeout_ms}`

2590

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

2592

2593 - `commands: Array[String]`

2594

2595 Ordered shell commands for the execution environment to run.

2596

2597 - `max_output_length: Integer`

2598

2599 Maximum number of UTF-8 characters to capture from combined stdout and stderr output.

2600

2601 - `timeout_ms: Integer`

2602

2603 Maximum wall-clock time in milliseconds to allow the shell commands to run.

2604

2605 - `call_id: String`

2606

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

2608

2609 - `type: :shell_call`

2610

2611 The type of the item. Always `shell_call`.

2612

2613 - `:shell_call`

2614

2615 - `id: String`

2616

2617 The unique ID of the shell tool call. Populated when this item is returned via API.

2618

2619 - `environment: LocalEnvironment | ContainerReference`

2620

2621 The environment to execute the shell commands in.

2622

2623 - `class LocalEnvironment`

2624

2625 - `class ContainerReference`

2626

2627 - `status: :in_progress | :completed | :incomplete`

2628

2629 The status of the shell call. One of `in_progress`, `completed`, or `incomplete`.

2630

2631 - `:in_progress`

2632

2633 - `:completed`

2634

2635 - `:incomplete`

2636

2637 - `class ShellCallOutput`

2638

2639 The streamed output items emitted by a shell tool call.

2640

2641 - `call_id: String`

2642

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

2644

2645 - `output: Array[ResponseFunctionShellCallOutputContent]`

2646

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

2648

2649 - `outcome: Timeout{ type} | Exit{ exit_code, type}`

2650

2651 The exit or timeout outcome associated with this shell call.

2652

2653 - `class Timeout`

2654

2655 Indicates that the shell call exceeded its configured time limit.

2656

2657 - `type: :timeout`

2658

2659 The outcome type. Always `timeout`.

2660

2661 - `:timeout`

2662

2663 - `class Exit`

2664

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

2666

2667 - `exit_code: Integer`

2668

2669 The exit code returned by the shell process.

2670

2671 - `type: :exit`

2672

2673 The outcome type. Always `exit`.

2674

2675 - `:exit`

2676

2677 - `stderr: String`

2678

2679 Captured stderr output for the shell call.

2680

2681 - `stdout: String`

2682

2683 Captured stdout output for the shell call.

2684

2685 - `type: :shell_call_output`

2686

2687 The type of the item. Always `shell_call_output`.

2688

2689 - `:shell_call_output`

2690

2691 - `id: String`

2692

2693 The unique ID of the shell tool call output. Populated when this item is returned via API.

2694

2695 - `max_output_length: Integer`

2696

2697 The maximum number of UTF-8 characters captured for this shell call's combined output.

2698

2699 - `status: :in_progress | :completed | :incomplete`

2700

2701 The status of the shell call output.

2702

2703 - `:in_progress`

2704

2705 - `:completed`

2706

2707 - `:incomplete`

2708

2709 - `class ApplyPatchCall`

2710

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

2712

2713 - `call_id: String`

2714

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

2716

2717 - `operation: CreateFile{ diff, path, type} | DeleteFile{ path, type} | UpdateFile{ diff, path, type}`

2718

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

2720

2721 - `class CreateFile`

2722

2723 Instruction for creating a new file via the apply_patch tool.

2724

2725 - `diff: String`

2726

2727 Unified diff content to apply when creating the file.

2728

2729 - `path: String`

2730

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

2732

2733 - `type: :create_file`

2734

2735 The operation type. Always `create_file`.

2736

2737 - `:create_file`

2738

2739 - `class DeleteFile`

2740

2741 Instruction for deleting an existing file via the apply_patch tool.

2742

2743 - `path: String`

2744

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

2746

2747 - `type: :delete_file`

2748

2749 The operation type. Always `delete_file`.

2750

2751 - `:delete_file`

2752

2753 - `class UpdateFile`

2754

2755 Instruction for updating an existing file via the apply_patch tool.

2756

2757 - `diff: String`

2758

2759 Unified diff content to apply to the existing file.

2760

2761 - `path: String`

2762

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

2764

2765 - `type: :update_file`

2766

2767 The operation type. Always `update_file`.

2768

2769 - `:update_file`

2770

2771 - `status: :in_progress | :completed`

2772

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

2774

2775 - `:in_progress`

2776

2777 - `:completed`

2778

2779 - `type: :apply_patch_call`

2780

2781 The type of the item. Always `apply_patch_call`.

2782

2783 - `:apply_patch_call`

2784

2785 - `id: String`

2786

2787 The unique ID of the apply patch tool call. Populated when this item is returned via API.

2788

2789 - `class ApplyPatchCallOutput`

2790

2791 The streamed output emitted by an apply patch tool call.

2792

2793 - `call_id: String`

2794

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

2796

2797 - `status: :completed | :failed`

2798

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

2800

2801 - `:completed`

2802

2803 - `:failed`

2804

2805 - `type: :apply_patch_call_output`

2806

2807 The type of the item. Always `apply_patch_call_output`.

2808

2809 - `:apply_patch_call_output`

2810

2811 - `id: String`

2812

2813 The unique ID of the apply patch tool call output. Populated when this item is returned via API.

2814

2815 - `output: String`

2816

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

2818

2819 - `class McpListTools`

2820

2821 A list of tools available on an MCP server.

2822

2823 - `id: String`

2824

2825 The unique ID of the list.

2826

2827 - `server_label: String`

2828

2829 The label of the MCP server.

2830

2831 - `tools: Array[Tool{ input_schema, name, annotations, description}]`

2832

2833 The tools available on the server.

2834

2835 - `input_schema: untyped`

2836

2837 The JSON schema describing the tool's input.

2838

2839 - `name: String`

2840

2841 The name of the tool.

2842

2843 - `annotations: untyped`

2844

2845 Additional annotations about the tool.

2846

2847 - `description: String`

2848

2849 The description of the tool.

2850

2851 - `type: :mcp_list_tools`

2852

2853 The type of the item. Always `mcp_list_tools`.

2854

2855 - `:mcp_list_tools`

2856

2857 - `error: String`

2858

2859 Error message if the server could not list tools.

2860

2861 - `class McpApprovalRequest`

2862

2863 A request for human approval of a tool invocation.

2864

2865 - `id: String`

2866

2867 The unique ID of the approval request.

2868

2869 - `arguments: String`

2870

2871 A JSON string of arguments for the tool.

2872

2873 - `name: String`

2874

2875 The name of the tool to run.

2876

2877 - `server_label: String`

2878

2879 The label of the MCP server making the request.

2880

2881 - `type: :mcp_approval_request`

2882

2883 The type of the item. Always `mcp_approval_request`.

2884

2885 - `:mcp_approval_request`

2886

2887 - `class McpApprovalResponse`

2888

2889 A response to an MCP approval request.

2890

2891 - `approval_request_id: String`

2892

2893 The ID of the approval request being answered.

2894

2895 - `approve: bool`

2896

2897 Whether the request was approved.

2898

2899 - `type: :mcp_approval_response`

2900

2901 The type of the item. Always `mcp_approval_response`.

2902

2903 - `:mcp_approval_response`

2904

2905 - `id: String`

2906

2907 The unique ID of the approval response

2908

2909 - `reason: String`

2910

2911 Optional reason for the decision.

2912

2913 - `class McpCall`

2914

2915 An invocation of a tool on an MCP server.

2916

2917 - `id: String`

2918

2919 The unique ID of the tool call.

2920

2921 - `arguments: String`

2922

2923 A JSON string of the arguments passed to the tool.

2924

2925 - `name: String`

2926

2927 The name of the tool that was run.

2928

2929 - `server_label: String`

2930

2931 The label of the MCP server running the tool.

2932

2933 - `type: :mcp_call`

2934

2935 The type of the item. Always `mcp_call`.

2936

2937 - `:mcp_call`

2938

2939 - `approval_request_id: String`

2940

2941 Unique identifier for the MCP tool call approval request.

2942 Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call.

2943

2944 - `error: String`

2945

2946 The error from the tool call, if any.

2947

2948 - `output: String`

2949

2950 The output from the tool call.

2951

2952 - `status: :in_progress | :completed | :incomplete | 2 more`

2953

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

2955

2956 - `:in_progress`

2957

2958 - `:completed`

2959

2960 - `:incomplete`

2961

2962 - `:calling`

2963

2964 - `:failed`

2965

2966 - `class ResponseCustomToolCallOutput`

2967

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

2969

2970 - `call_id: String`

2971

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

2973

2974 - `output: String | Array[ResponseInputText | ResponseInputImage | ResponseInputFile]`

2975

2976 The output from the custom tool call generated by your code.

2977 Can be a string or an list of output content.

2978

2979 - `String = String`

2980

2981 A string of the output of the custom tool call.

2982

2983 - `OutputContentList = Array[ResponseInputText | ResponseInputImage | ResponseInputFile]`

2984

2985 Text, image, or file output of the custom tool call.

2986

2987 - `class ResponseInputText`

2988

2989 A text input to the model.

2990

2991 - `class ResponseInputImage`

2992

2993 An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision).

2994

2995 - `class ResponseInputFile`

2996

2997 A file input to the model.

2998

2999 - `type: :custom_tool_call_output`

3000

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

3002

3003 - `:custom_tool_call_output`

3004

3005 - `id: String`

3006

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

3008

3009 - `class ResponseCustomToolCall`

3010

3011 A call to a custom tool created by the model.

3012

3013 - `call_id: String`

3014

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

3016

3017 - `input: String`

3018

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

3020

3021 - `name: String`

3022

3023 The name of the custom tool being called.

3024

3025 - `type: :custom_tool_call`

3026

3027 The type of the custom tool call. Always `custom_tool_call`.

3028

3029 - `:custom_tool_call`

3030

3031 - `id: String`

3032

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

3034

3035 - `namespace: String`

3036

3037 The namespace of the custom tool being called.

3038

3039 - `class CompactionTrigger`

3040

3041 Compacts the current context. Must be the final input item.

3042

3043 - `type: :compaction_trigger`

3044

3045 The type of the item. Always `compaction_trigger`.

3046

3047 - `:compaction_trigger`

3048

3049 - `class ItemReference`

3050

3051 An internal identifier for an item to reference.

3052

3053 - `id: String`

3054

3055 The ID of the item to reference.

3056

3057 - `type: :item_reference`

3058

3059 The type of item to reference. Always `item_reference`.

3060

3061 - `:item_reference`

3062

3063- `metadata: Metadata`

3064

3065 Set of 16 key-value pairs that can be attached to an object. This can be

3066 useful for storing additional information about the object in a structured

3067 format, and querying for objects via API or the dashboard.

3068

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

3070 with a maximum length of 512 characters.

3071

3072### Returns

3073

3074- `class Conversation`

3075

3076 - `id: String`

3077

3078 The unique ID of the conversation.

3079

3080 - `created_at: Integer`

3081

3082 The time at which the conversation was created, measured in seconds since the Unix epoch.

3083

3084 - `metadata: untyped`

3085

3086 Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

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

3088

3089 - `object: :conversation`

3090

3091 The object type, which is always `conversation`.

3092

3093 - `:conversation`

3094

3095### Example

3096

3097```ruby

3098require "openai"

3099

3100openai = OpenAI::Client.new(api_key: "My API Key")

3101

3102conversation = openai.conversations.create

3103

3104puts(conversation)

3105```

3106

3107#### Response

3108

3109```json

3110{

3111 "id": "id",

3112 "created_at": 0,

3113 "metadata": {},

3114 "object": "conversation"

3115}

3116```