### Hosted Tool Invocation Example

Source: https://www.openresponses.org/specification

This example demonstrates how a client can request a custom hosted tool (`implementor_slug:custom_document_search`) and the structure of the expected response item from the implementer.

```APIDOC
### Request Example
```json
{
  "model": "my-model",
  "messages": [
    {"role": "user", "content": "Find relevant documents about climate change."}
  ],
  "tools": [
    {
      "type": "implementor_slug:custom_document_search",
      "documents": [
        { "type": "external_file", "url": "https://arxiv.org/example.pdf" }
      ]
    }
  ]
}
```

### Response Example (Hosted Tool Result)
```json
{
  "type": "implementor_slug:custom_document_search",
  "id": "cdc_759bd159770647a681a6ed186843fcca",
  "query": ["climate change", "global warming"],
  "status": "completed",
  "results": [
    {
      "document_id": "result_6064c25dad6b4218b62e675234946de7",
      "chunk": "Climate change threatens Cambodia’s crops, floods cities, heats temperatures, strains resources..."
    }
    ...
  ]
}
```

### Description
In this example, the client requests the `implementor_slug:custom_document_search` hosted tool exposed by the implementer. The implementer executes the tool directly, returning results to the client and abstracting away the internal workings. Hosted tools must have corresponding item types. When building custom tools, the tool should have its own item type that provides developers a receipt of what occurred during tool call execution. The item at minimum should contain a representation of how the model invoked the tool, the status of the tool call, and the result from the tool. The item’s schema should allow for enough information to pass to the developer that it can be round-tripped back to the API for lossless rehydration on a followup request.
```

--------------------------------

### Example of Extending Streaming Event with Custom Fields

Source: https://www.openresponses.org/specification

This example shows how to introduce a custom streaming event, `acme:trace_event`, to provide implementation-specific metadata such as `phase`, `latency_ms`, `related_item_id`, and `details`. This allows for enhanced observability and debugging. Clients that recognize this extension can leverage the extra information, while others can safely disregard it.

```json
{
  "type": "acme:trace_event",
  "sequence_number": 1,
  "phase": "tool_resolution",
  "latency_ms": 34,
  "related_item_id": "tc_789",
  "details": "Resolved tool endpoint from local cache."
}
```

--------------------------------

### Example of Invoking a Hosted Tool

Source: https://www.openresponses.org/specification

Demonstrates how a client can request a custom hosted tool, such as document search, from an Open Responses implementation. The implementer processes the request and returns results.

```json
{
  "model": "my-model",
  "messages": [
    {"role": "user", "content": "Find relevant documents about climate change."}
  ],
  "tools": [
    {
      "type": "implementor_slug:custom_document_search",
      "documents": [
        { "type": "external_file", "url": "https://arxiv.org/example.pdf" }
      ]
    }
  ]
}
```

--------------------------------

### Extensible Item Example

Source: https://www.openresponses.org/specification

Model providers can define their own item types, which must be prefixed with the canonical provider slug. This example shows a web search call item from the 'openai' provider.

```json
{
  "id": "ws_0df093a2d268cd7f0068efe79ac9408190b9833ec01e5d05ed",
  "type": "openai:web_search_call",
  "status": "completed",
  "action": {
    "type": "search",
    "query": "weather: San Francisco, CA"
  }
}
```

--------------------------------

### Function Call Item Example (JSON)

Source: https://www.openresponses.org/specification

Demonstrates the structure of a 'function_call' item, which includes the item type, ID, the function name to be called, a call identifier, and the arguments for the function as a JSON string.

```json
{
  "type": "function_call",
  "id": "fc_00123xyzabc9876def0gh1ij2klmno345",
  "name": "sendEmail",
  "call_id": "call_987zyx654wvu321",
  "arguments": "{\"recipient\":\"jane.doe@example.com\",\"subject\":\"Meeting Reminder\",\"body\":\"Don't forget about our meeting tomorrow at 10am.\"}"
}
```

--------------------------------

### Message Item Example (JSON)

Source: https://www.openresponses.org/specification

Illustrates the structure of a 'message' item, including its type, unique ID, role, status, and content. The content is an array that can hold different types of output, such as text.

```json
{
  "type": "message",
  "id": "msg_01A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6",
  "role": "assistant",
  "status": "completed",
  "content": [
    {
      "type": "output_text",
      "text": "Hello! How can I assist you today?"
    }
  ]
}
```

--------------------------------

### Response Object Details

Source: https://www.openresponses.org/openapi/openapi

Provides the structure and example of a complete response object returned by the Responses API.

```APIDOC
## Response Object

### Description
The complete response object that was returned by the Responses API.

### Properties
- **id** (string) - Unique identifier for the response.
- **object** (string) - Type of the object, always `response`.
- **created_at** (integer) - Timestamp when the response was created.
- **status** (string) - Current status of the response (e.g., `completed`).
- **completed_at** (integer) - Timestamp when the response was completed.
- **model** (string) - The model used to generate the response.
- **output** (array) - An array of output objects, typically containing messages.
  - **type** (string) - Type of the output (e.g., `message`).
  - **id** (string) - Unique identifier for the output message.
  - **status** (string) - Status of the output message (e.g., `completed`).
  - **role** (string) - Role of the sender (e.g., `assistant`).
  - **content** (array) - Array of content objects within the message.
    - **type** (string) - Type of content (e.g., `output_text`).
    - **text** (string) - The actual text content.
    - **annotations** (array) - Annotations associated with the text.
- **parallel_tool_calls** (boolean) - Indicates if parallel tool calls were enabled.
- **reasoning** (object) - Details about the reasoning process.
- **store** (boolean) - Flag indicating if the response should be stored.
- **background** (boolean) - Flag indicating if the response was generated in the background.
- **temperature** (number) - The temperature setting for generation.
- **presence_penalty** (number) - The presence penalty setting.
- **frequency_penalty** (number) - The frequency penalty setting.
- **text** (object) - Text-specific formatting options.
  - **format** (object)
    - **type** (string) - The format type (e.g., `text`).
- **tool_choice** (string) - The tool choice setting (e.g., `auto`).
- **tools** (array) - List of tools used.
- **top_p** (number) - The top_p setting.
- **truncation** (string) - The truncation setting (e.g., `disabled`).
- **usage** (object) - Token usage details.
  - **input_tokens** (integer) - Number of input tokens.
  - **input_tokens_details** (object)
    - **cached_tokens** (integer) - Cached input tokens.
  - **output_tokens** (integer) - Number of output tokens.
  - **output_tokens_details** (object)
    - **reasoning_tokens** (integer) - Reasoning tokens.
  - **total_tokens** (integer) - Total tokens used.
- **metadata** (object) - Additional metadata.

### Response Example
```json
{
  "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
  "object": "response",
  "created_at": 1741476777,
  "status": "completed",
  "completed_at": 1741476778,
  "model": "gpt-4o-2024-08-06",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "reasoning": {},
  "store": true,
  "background": false,
  "temperature": 1,
  "presence_penalty": 0,
  "frequency_penalty": 0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 328,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 52,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 380
  },
  "metadata": {}
}
```
```

--------------------------------

### Reasoning Item Structure Example

Source: https://www.openresponses.org/specification

This JSON object demonstrates the structure of a 'reasoning' item, including optional fields for summary, raw content, and encrypted content. It shows how a model's thought process can be exposed.

```json
{
  "type": "reasoning",
  "status": "completed",
  "summary": [
    {
      "type": "summary_text",
      "text": "Determined that the user is asking for restaurant recommendations in a specific city, then filtered options by distance and rating before selecting three suggestions."
    }
  ],
  "content": [
    {
      "type": "output_text",
      "text": "User asked: \"Where should I eat dinner in downtown Seattle tonight?\"↵↵1. Interpreted task as a search for nearby restaurants suitable for dinner.↵2. Prioritized places within a short walking radius of downtown.↵3. Filtered candidates by overall rating and number of reviews.↵4. Preferred options with vegetarian choices and moderate price range.↵5. Selected three restaurants that best match the inferred preferences."
    }
  ],
  "encrypted_content": null
}
```

--------------------------------

### Example of Extending Item Type with Custom Fields

Source: https://www.openresponses.org/specification

This example demonstrates how an implementor can extend the standard `Item` type with custom fields like `request_id`, `sequence`, `latency_ms`, and `cache_hit`. The custom type `acme:telemetry_chunk` is prefixed with the implementor's slug. Clients that understand this extension can utilize the additional data for observability or UX, while others can ignore it.

```json
{
  "type": "acme:telemetry_chunk",
  "id": "tc_123",
  "status": "completed",
  "request_id": "req_123",
  "sequence": 4,
  "latency_ms": 72,
  "cache_hit": true,
  "notes": "Model responded from warm cache."
}
```

--------------------------------

### Hosted Tool Execution Result

Source: https://www.openresponses.org/specification

An example of the output an API might emit after executing a hosted tool. This includes the tool's type, a unique ID, the query parameters, execution status, and the search results.

```json
{
  "type": "implementor_slug:custom_document_search",
  "id": "cdc_759bd159770647a681a6ed186843fcca",
  "query": ["climate change", "global warming"],
  "status": "completed",
  "results": [
    {
      "document_id": "result_6064c25dad6b4218b62e675234946de7",
      "chunk": "Climate change threatens Cambodia’s crops, floods cities, heats temperatures, strains resources..."
    }
    ...
  ]
}
```

--------------------------------

### Implementing Hosted Tools

Source: https://www.openresponses.org/specification

This section describes how clients can interact with hosted tools, such as `custom_document_search`, where the implementer executes the tool directly and returns results, abstracting the internal processes.

```APIDOC
## POST /v1/chat/completions (with Hosted Tool Execution)

### Description
Allows clients to request the execution of hosted tools. The server directly executes the specified tool and returns its results within the response.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The model to use.
- **input** (array) - Required - The conversation input.
- **tools** (array) - Required - A list of available tools, including hosted ones like `custom_document_search`.
- **tool_choice** (object) - Required - Specifies that a particular tool should be used. Example: `{"type": "function", "name": "custom_document_search"}`.

### Request Example
```json
{
  "model": "gpt-internal-tool-executor",
  "input": [
    {"role": "user", "content": [{"type": "input_text", "text": "Search for documents related to 'API documentation'."}]}
  ],
  "tools": [
    {
      "type": "function",
      "name": "custom_document_search",
      "description": "Searches a custom document repository.",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "The search query."
          }
        },
        "required": ["query"]
      }
    }
  ],
  "tool_choice": {
    "type": "function",
    "name": "custom_document_search"
  }
}
```

### Response
#### Success Response (200)
- **content** (array) - The response containing the results from the executed hosted tool.

#### Response Example
```json
{
  "content": [
    {
      "type": "tool_code",
      "code": "print(custom_document_search(query='API documentation'))"
    },
    {
      "type": "tool_result",
      "tool_code": "print(custom_document_search(query='API documentation'))",
      "results": [
        {
          "document_id": "doc_123",
          "title": "OpenAPI Specification",
          "snippet": "The OpenAPI Specification (OAS) allows you to standardize the description of RESTful APIs."
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Tool Choice Parameters

Source: https://www.openresponses.org/openapi/openapi

This section describes the parameters related to tool selection within the API.

```APIDOC
## Tool Choice Parameters

### Description
Controls which tool the model should use, if any.

### Parameters
#### Request Body
- **ToolChoiceParam** (object) - Required - Controls which tool the model should use, if any. Can be one of:
    - **SpecificToolChoiceParam**
    - **ToolChoiceValueEnum** (string, enum: `none`, `auto`, `required`) - Let the model choose the tools from among the provided set (`auto`), restrict the model from calling any tools (`none`), or require the model to call a tool (`required`).
    - **AllowedToolsParam** (object) - 
        - **type** (string) - Required - The tool choice type. Always `allowed_tools`.
        - **tools** (array) - Required - The list of tools that are permitted for this request. Max items: 128, Min items: 1.
        - **mode** (string) - Optional - How to select a tool from the allowed set. See `ToolChoiceValueEnum` for possible values.

### Request Example
```json
{
  "ToolChoiceParam": {
    "type": "allowed_tools",
    "tools": [{"id": "tool1"}, {"id": "tool2"}],
    "mode": "auto"
  }
}
```

### Response
#### Success Response (200)
*No specific success response fields are documented for this parameter section.*

#### Response Example
*No specific response example is documented for this parameter section.*
```

--------------------------------

### POST /websites/openresponses

Source: https://www.openresponses.org/openapi/openapi

Creates a new response with the specified parameters. This endpoint is designed for GPT-5 and O-series models and supports advanced configuration for reasoning and tools.

```APIDOC
## POST /websites/openresponses

### Description
Creates a new response with the specified parameters. This endpoint is designed for GPT-5 and O-series models and supports advanced configuration for reasoning and tools.

### Method
POST

### Endpoint
/websites/openresponses

### Parameters
#### Request Body
- **model** (string | null) - The model to use for this request, e.g. 'gpt-5.2'.
- **input** (string | array | null) - Context to provide to the model for the scope of this request. May either be a string or an array of input items. If a string is provided, it is interpreted as a user message. Max length for string input is 10485760.
- **previous_response_id** (string | null) - The ID of the response to use as the prior turn for this request.
- **include** (array) - Specifies additional information to include in the response. Items must be of type IncludeEnum.
- **tools** (array | null) - A list of tools that the model may call while generating the response. Items must be of type ResponsesToolParam.
- **tool_choice** (object | null) - Controls which tool the model should use, if any. Must conform to ToolChoiceParam schema.
- **metadata** (object | null) - Set of 16 key-value pairs that can be attached to an object. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

### Request Example
```json
{
  "model": "gpt-5.2",
  "input": "Explain the concept of recursion.",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get weather information for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": {
    "type": "function",
    "function": {
      "name": "get_weather"
    }
  },
  "metadata": {
    "user_id": "user123"
  }
}
```

### Response
#### Success Response (200)
- **model** (string | null) - The model used for the request.
- **input** (string | array | null) - The input provided to the model.
- **previous_response_id** (string | null) - The ID of the previous response.
- **include** (array) - Included information in the response.
- **tools** (array | null) - Tools that the model may call.
- **tool_choice** (object | null) - The chosen tool for the model.
- **metadata** (object | null) - Metadata associated with the response.

#### Response Example
```json
{
  "id": "resp_abc123",
  "model": "gpt-5.2",
  "input": "Explain the concept of recursion.",
  "previous_response_id": null,
  "created_at": 1677652800,
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 200,
    "total_tokens": 300
  },
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Recursion is a programming technique where a function calls itself to solve a problem."
      }
    }
  ]
}
```
```

--------------------------------

### Structured Error Object Example

Source: https://www.openresponses.org/specification

This JSON object represents a structured error response from the API. It includes a human-readable message, the type of error, the parameter involved (if any), and a specific error code for more granular detail.

```json
{
  "error": {
    "message": "The requested model 'fake-model' does not exist.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}
```

--------------------------------

### Extending OpenResponses with Hosted Tools

Source: https://www.openresponses.org/specification

Implementers can extend OpenResponses by exposing their own hosted tools. These are distinct from standard function tools and allow for custom capabilities like search, retrieval, or workflow orchestration within the implementer's environment. When a hosted tool is invoked, the implementer executes it and returns the result, abstracting away implementation details and maintaining a consistent tool interface.

```APIDOC
## Extending OpenResponses

### Description
Any implementer can be considered to have a Open Responses-compliant API if they have an API that implements this spec directly or is a proper superset of Open Responses. The spec acknowledges that providers will want to build features that are not part of the spec. Features that gain broad adoption among frontier models should be considered for standardization by the TSC.

### Extending Tools
Implementers can expose their own hosted tools—distinct from standard function tools—by providing new capabilities directly within their Open Responses implementation, such as custom search, retrieval, or workflow orchestration. When a user or model invokes a hosted tool, the implementer executes it within their own environment, often integrating with services or logic outside the model provider, and returns the result without exposing the implementation details. This enables implementors to add custom features while maintaining a consistent tool interface for both users and models.
```

--------------------------------

### Streamable Content Events

Source: https://www.openresponses.org/specification

These events manage streamable content, typically text from a model. It starts with `response.content_part.added`, followed by `response.<content_type>.delta` events for incremental updates, ending with `response.<content_type>.done`. The content part is finalized with `response.content_part.done`.

```json
{
  "type": "response.content_part.added",
  "sequence_number": 12,
  "item_id": "msg_0f7983f1618f89d20068efe9b45d748191a5239d49c2971a65",
  "output_index": 3,
  "content_index": 0,
  "part": {
    "type": "output_text",
    "annotations": [],
    "text": ""
  }
}


{
  "type": "response.output_text.delta",
  "sequence_number": 13,
  "item_id": "msg_0f7983f1618f89d20068efe9b45d748191a5239d49c2971a65",
  "output_index": 3,
  "content_index": 0,
  "delta": "Here"
}


...


{
  "type": "response.output_text.done",
  "sequence_number": 25,
  "item_id": "msg_0f7983f1618f89d20068efe9b45d748191a5239d49c2971a65",
  "output_index": 3,
  "content_index": 0,
  "text": "Here\u2019s the current weather for San Francisco, CA (as of Wednesday, October 15, 2025):\n\n- Current conditions: Cloudy, 58\u00b0F (14\u00b0C).\n- Today\u2019s outlook: A shower in spots late this morning; oth
erwise a cloudy start with sunshine returning later. High near 67\u00b0F (19\u00b0C), low around 51\u00b0F (11\u00b0C).\n\nIf you\u2019d like wind speed, humidity, or hourly updates, I can pull those too. "
}


{
  "type": "response.content_part.done",
  "sequence_number": 26,
  "item_id": "msg_0f7983f1618f89d20068efe9b45d748191a5239d49c2971a65",
  "output_index": 3,
  "content_index": 0,
  "part": {
    "type": "output_text",
    "annotations": [],
    "text": "Here\u2019s the current weather for San Francisco, CA (as of Wednesday, October 15, 2025):\n\n- Current conditions: Cloudy, 58\u00b0F (14\u00b0C).\n- Today\u2019s outlook: A shower in spots late this morning; o
therwise a cloudy start with sunshine returning later. High near 67\u00b0F (19\u00b0C), low around 51\u00b0F (11\u00b0C).\n\nIf you\u2019d like wind speed, humidity, or hourly updates, I can pull those too. "
  }
}
```

--------------------------------

### Tools

Source: https://www.openresponses.org/specification

Introduces the concept of tool-use in Open Responses, focusing on externally-hosted tools where implementation resides outside the model provider's system.

```APIDOC
## Tools

### Description
Tool-use is a core capability for LLM agents. Open Responses supports externally-hosted tools, where the tool's implementation exists outside the model provider's infrastructure.

### Externally-hosted tools
These tools require the developer to run the implementation and return the output back to the LLM. Functions are a prime example of this type of tool.
```

--------------------------------

### Streaming HTTP Response Example (Open Responses)

Source: https://www.openresponses.org/specification

This snippet demonstrates the structure of a streaming HTTP response according to the Open Responses specification. It includes the 'event' type and a JSON-encoded 'data' object representing a text delta. The specification requires the terminal event to be '[DONE]'.

```text
event: response.output_text.delta
data: { "type":"response.output_text.delta","sequence_number":10,"item_id":"msg_07315d23576898080068e95daa2e34819685fb0a98a0503f78","output_index":0,"content_index":0,"delta":" a","logprobs":[],"obfuscation":"Wd6S45xQ7SyQLT"}


```

--------------------------------

### Usage Schema

Source: https://www.openresponses.org/openapi/openapi

Details token usage for a request, including input tokens, output tokens, and total tokens.

```APIDOC
## Usage

### Description
Details token usage for a request, including input tokens, output tokens, and total tokens.

### Method
N/A (Schema Definition)

### Endpoint
N/A

### Parameters
#### Request Body
- **input_tokens** (integer) - Required - The number of input tokens used.
- **output_tokens** (integer) - Required - The number of output tokens generated.
- **total_tokens** (integer) - Required - The total number of tokens used.

### Request Example
```json
{
  "input_tokens": 100,
  "output_tokens": 50,
  "total_tokens": 150
}
```

### Response
#### Success Response (200)
- **input_tokens** (integer) - The number of input tokens used.
- **output_tokens** (integer) - The number of output tokens generated.
- **total_tokens** (integer) - The total number of tokens used.

#### Response Example
```json
{
  "input_tokens": 100,
  "output_tokens": 50,
  "total_tokens": 150
}
```
```

--------------------------------

### Context Window Management with `truncation`

Source: https://www.openresponses.org/specification

The `truncation` parameter allows clients to manage how the server handles input that exceeds the model's context window. Setting it to `"auto"` permits the server to intelligently shorten the context, while `"disabled"` enforces a strict policy, causing requests to fail if the context is too long.

```APIDOC
## POST /v1/chat/completions

### Description
Sends a chat completion request, with options to control context truncation behavior when input exceeds the model's context window.

### Method
POST

### Endpoint
/v1/chat/completions

### Parameters
#### Request Body
- **truncation** (string) - Optional - Controls context window management. 
  - `"auto"`: The server MAY truncate earlier parts of the context to fit within the model’s context window.
  - `"disabled"`: The server MUST NOT truncate any input. If the combined context exceeds the model’s maximum context window, the request MUST fail with an error.

### Request Example
```json
{
  "model": "gpt-4",
  "input": [
    // ... long conversation history ...
  ],
  "truncation": "disabled"
}
```

### Response
#### Success Response (200)
- **content** (array) - The generated response from the model.

#### Error Response (400)
- **error** (object) - Details about the error, likely indicating context overflow if `truncation` is `"disabled"`.

#### Response Example (Success)
```json
{
  "content": [
    {"type": "input_text", "text": "Response to the long context."}
  ]
}
```
```

--------------------------------

### Reasoning Schema

Source: https://www.openresponses.org/openapi/openapi

Configuration and metadata for model reasoning. Includes requested effort and generated summary.

```APIDOC
## Reasoning

### Description
Configuration and metadata for model reasoning. Includes requested effort and generated summary.

### Method
N/A (Schema Definition)

### Endpoint
N/A

### Parameters
#### Request Body
- **effort** (object or null) - Optional - The requested reasoning effort, referencing ReasoningEffortEnum schema.
- **summary** (object or null) - Optional - A model-generated summary of its reasoning, referencing ReasoningSummaryEnum schema.

### Request Example
```json
{
  "effort": "low",
  "summary": "standard"
}
```

### Response
#### Success Response (200)
- **effort** (object or null) - The reasoning effort that was requested or used.
- **summary** (object or null) - The model-generated summary of its reasoning.

#### Response Example
```json
{
  "effort": "low",
  "summary": "standard"
}
```
```

--------------------------------

### InputFileContent Object

Source: https://www.openresponses.org/reference

Represents a file input to the model.

```APIDOC
## InputFileContent Object

### Description
A file input to the model.

### Fields
- **type** (string) - Required. Always `input_file`.
- **filename** (string) - The name of the file to be sent to the model.
- **file_url** (string) - The URL of the file to be sent to the model.
```

--------------------------------

### Text Parameter

Source: https://www.openresponses.org/openapi/openapi

Configures text output options, including format and verbosity.

```APIDOC
## Text Parameter

### Description
Options that control text output behavior.

### Parameters
#### Request Body
- **TextParam** (object) - Optional - 
    - **format** (object or null) - Optional - The format configuration for text output. See `TextFormatParam`.
    - **verbosity** (string) - Optional - Controls the level of detail in generated text output. Possible values: `low`, `medium`, `high`.
        - `high`: Instruct the model to emit more verbose final responses.
        - `low`: Instruct the model to emit less verbose final responses.
        - `medium`: Use the model's default verbosity setting.

### Request Example
```json
{
  "TextParam": {
    "verbosity": "high"
  }
}
```

### Response
#### Success Response (200)
*No specific success response fields are documented for this parameter section.*

#### Response Example
*No specific response example is documented for this parameter section.*
```

--------------------------------

### OutputTokensDetails Schema

Source: https://www.openresponses.org/openapi/openapi

Provides a breakdown of output token usage, specifically the number of tokens attributed to reasoning.

```APIDOC
## OutputTokensDetails

### Description
Provides a breakdown of output token usage, specifically the number of tokens attributed to reasoning.

### Method
N/A (Schema Definition)

### Endpoint
N/A

### Parameters
#### Request Body
- **reasoning_tokens** (integer) - Required - The number of output tokens that were attributed to reasoning.

### Request Example
```json
{
  "reasoning_tokens": 20
}
```

### Response
#### Success Response (200)
- **reasoning_tokens** (integer) - The number of output tokens attributed to reasoning.

#### Response Example
```json
{
  "reasoning_tokens": 20
}
```
```

--------------------------------

### InputTokensDetails Schema

Source: https://www.openresponses.org/openapi/openapi

Provides a breakdown of input token usage, specifically the number of tokens served from cache.

```APIDOC
## InputTokensDetails

### Description
Provides a breakdown of input token usage, specifically the number of tokens served from cache.

### Method
N/A (Schema Definition)

### Endpoint
N/A

### Parameters
#### Request Body
- **cached_tokens** (integer) - Required - The number of input tokens that were served from cache.

### Request Example
```json
{
  "cached_tokens": 50
}
```

### Response
#### Success Response (200)
- **cached_tokens** (integer) - The number of input tokens that were served from cache.

#### Response Example
```json
{
  "cached_tokens": 50
}
```
```

--------------------------------

### POST /responses

Source: https://www.openresponses.org/openapi/openapi

Creates a response. This endpoint supports both standard JSON responses and streaming responses via Server-Sent Events (SSE).

```APIDOC
## POST /responses

### Description
Creates a response. This endpoint handles requests for generating responses, supporting both immediate JSON output and real-time streaming updates via Server-Sent Events (SSE).

### Method
POST

### Endpoint
/responses

### Parameters

#### Request Body
- **content** (object) - Required - The content for the response generation request. This can include text, tool calls, or other forms of input.
- **format** (object) - Optional - Specifies the desired format for the response. Defaults to text if not provided.
  - **type** (string) - Required - The type of response format. Can be `text` or `json_schema`.
  - **schema** (object) - Required if `type` is `json_schema` - The JSON schema defining the structure of the response.
  - **name** (string) - Optional - The name of the response format.
  - **description** (string) - Optional - A description of the response format.
  - **strict** (boolean) - Optional - If true, enables strict schema adherence. Defaults to false.
- **model** (string) - Optional - The identifier of the model to use for generating the response.
- **response_format** (object) - Optional - Specifies the desired format for the response.
  - **type** (string) - Required - The type of response format. Can be `text` or `json_schema`.
  - **schema** (object) - Required if `type` is `json_schema` - The JSON schema defining the structure of the response.
  - **name** (string) - Optional - The name of the response format.
  - **description** (string) - Optional - A description of the response format.
  - **strict** (boolean) - Optional - If true, enables strict schema adherence. Defaults to false.

### Request Example (JSON Response)
```json
{
  "content": {
    "type": "text",
    "text": "Hello, world!"
  },
  "model": "example-model",
  "response_format": {
    "type": "text"
  }
}
```

### Request Example (JSON Schema Response)
```json
{
  "content": {
    "type": "text",
    "text": "Generate a user object."
  },
  "model": "example-model",
  "response_format": {
    "type": "json_schema",
    "schema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "age": {
          "type": "integer"
        }
      },
      "required": ["name", "age"]
    }
  }
}
```

### Response

#### Success Response (200 - JSON)
- **id** (string) - The unique identifier for the response.
- **content** (object) - The generated content of the response.
  - **type** (string) - The type of content (e.g., `text`, `tool_code`).
  - **text** (string) - The text content, if applicable.
  - **tool_code** (string) - The tool code, if applicable.
- **model** (string) - The model used to generate the response.
- **finished_at** (timestamp) - The timestamp when the response generation was finished.
- **usage** (object) - Information about token usage.

#### Success Response (200 - SSE Stream)
Responses are streamed as Server-Sent Events (SSE). Each event has a `data` field containing a JSON object describing the event. Event types include:
- `response_created`
- `response_queued`
- `response_in_progress`
- `response_completed`
- `response_failed`
- `response_incomplete`
- `response_output_item_added`
- `response_output_item_done`
- `response_reasoning_summary_part_added`
- `response_reasoning_summary_part_done`
- `response_content_part_added`
- `response_content_part_done`
- `response_output_text_delta`
- `response_output_text_done`
- `response_refusal_delta`
- `response_refusal_done`

### Response Example (200 - JSON)
```json
{
  "id": "resp_abc123",
  "content": {
    "type": "text",
    "text": "This is a sample response."
  },
  "model": "example-model",
  "finished_at": "2023-10-27T10:00:00Z",
  "usage": {
    "prompt_tokens": 100,
    "total_tokens": 150
  }
}
```

### Response Example (200 - SSE Stream Event)
```
data: {"type": "response_output_text_delta", "delta": {"text": "This is a "}}
```
```
data: {"type": "response_output_text_delta", "delta": {"text": "sample "}}
```
```
data: {"type": "response_output_text_delta", "delta": {"text": "stream."}}
```
```
data: {"type": "response_output_text_done", "done": true}
```

```

--------------------------------

### OpenAI API

Source: https://www.openresponses.org/openapi/openapi

This section details the OpenAI API, including its base URL, authentication methods, and various request/response schemas for interacting with AI models.

```APIDOC
## OpenAI API

### Description
This document outlines the OpenAI API, detailing its available endpoints, request parameters, and response structures for leveraging various AI capabilities.

### Server URL
`https://api.openai.com/v1`

### Security
- **ApiKeyAuth**: `http` scheme, `bearer` type, sent in `header`.

### Schemas

#### ItemReferenceParam
An internal identifier for an item to reference.

- **type** (string) - Optional - The type of item to reference. Always `item_reference`.
- **id** (string) - Required - The ID of the item to reference.

#### ReasoningSummaryContentParam
Reasoning summary content associated with an item.

- **type** (string) - Required - The content type. Always `summary_text`.
- **text** (string) - Required - The reasoning summary text (max 10485760 characters).

#### ReasoningItemParam
Represents a reasoning item with associated summary and content.

- **id** (string) - Optional - The unique ID of this reasoning item (e.g., `rs_123`).
- **type** (string) - Required - The item type. Always `reasoning`.
- **summary** (array) - Required - An array of `ReasoningSummaryContentParam` objects.
- **content** (null) - Optional
- **encrypted_content** (string) - Optional - An encrypted representation of the reasoning content.

#### InputTextContentParam
A text input to the model.

- **type** (string) - Required - The type of the input item. Always `input_text`.
- **text** (string) - Required - The text input to the model (max 10485760 characters).

#### DetailEnum
Enum for detail level.

- **auto**: Choose the detail level automatically.
- **high**: Allows the model to "see" a higher-resolution version of the image, usually increasing input token costs.
- **low**: Restricts the model to a lower-resolution version of the image.

#### InputImageContentParamAutoParam
Represents an image input to the model, with automatic detail level selection.

- **type** (string) - Required - The type of the input item. Always `input_image`.
- **image_url** (string) - Optional - The URL of the image (max 20971520 characters). A fully qualified URL or base64 encoded image in a data URL.
- **detail** (ImageDetail) - Optional - Controls the detail level of the image analysis.
```