{ "openapi": "3.1.0", "info": { "title": "OpenAI API", "version": "2.3.0" }, "servers": [ { "url": "https://api.openai.com/v1" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "in": "header" } }, "schemas": { "ItemReferenceParam": { "properties": { "type": { "anyOf": [ { "type": "string", "enum": ["item_reference"], "description": "The type of item to reference. Always `item_reference`.", "default": "item_reference" }, { "type": "null" } ] }, "id": { "type": "string", "description": "The ID of the item to reference." } }, "type": "object", "required": ["id"], "title": "Item reference", "description": "An internal identifier for an item to reference." }, "ReasoningSummaryContentParam": { "properties": { "type": { "type": "string", "enum": ["summary_text"], "description": "The content type. Always `summary_text`.", "default": "summary_text" }, "text": { "type": "string", "maxLength": 10485760, "description": "The reasoning summary text." } }, "type": "object", "required": ["type", "text"] }, "ReasoningItemParam": { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this reasoning item.", "example": "rs_123" }, { "type": "null" } ] }, "type": { "type": "string", "enum": ["reasoning"], "description": "The item type. Always `reasoning`.", "default": "reasoning" }, "summary": { "items": { "$ref": "#/components/schemas/ReasoningSummaryContentParam" }, "type": "array", "description": "Reasoning summary content associated with this item." }, "content": { "anyOf": [ { "type": "null" } ] }, "encrypted_content": { "anyOf": [ { "type": "string", "description": "An encrypted representation of the reasoning content." }, { "type": "null" } ] } }, "type": "object", "required": ["type", "summary"] }, "InputTextContentParam": { "properties": { "type": { "type": "string", "enum": ["input_text"], "description": "The type of the input item. Always `input_text`.", "default": "input_text" }, "text": { "type": "string", "maxLength": 10485760, "description": "The text input to the model." } }, "type": "object", "required": ["type", "text"], "title": "Input text", "description": "A text input to the model.", "x-unionDisplay": "section", "x-unionTitle": "Content Type" }, "DetailEnum": { "type": "string", "enum": ["low", "high", "auto"], "x-enumDescriptions": { "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": { "properties": { "type": { "type": "string", "enum": ["input_image"], "description": "The type of the input item. Always `input_image`.", "default": "input_image" }, "image_url": { "anyOf": [ { "type": "string", "maxLength": 20971520, "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL." }, { "type": "null" } ] }, "detail": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ImageDetail" }, { "description": "The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`." } ] }, { "type": "null" } ] } }, "type": "object", "required": ["type"], "title": "Input image", "description": "An image input to the model. Learn about [image inputs](/docs/guides/vision)" }, "InputFileContentParam": { "properties": { "type": { "type": "string", "enum": ["input_file"], "description": "The type of the input item. Always `input_file`.", "default": "input_file" }, "filename": { "anyOf": [ { "type": "string", "description": "The name of the file to be sent to the model." }, { "type": "null" } ] }, "file_data": { "anyOf": [ { "type": "string", "maxLength": 33554432, "description": "The base64-encoded data of the file to be sent to the model." }, { "type": "null" } ] }, "file_url": { "anyOf": [ { "type": "string", "description": "The URL of the file to be sent to the model." }, { "type": "null" } ] } }, "type": "object", "required": ["type"], "title": "Input file", "description": "A file input to the model." }, "UserMessageItemParam": { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, { "type": "null" } ] }, "type": { "type": "string", "enum": ["message"], "description": "The item type. Always `message`.", "default": "message" }, "role": { "type": "string", "enum": ["user"], "description": "The message role. Always `user`.", "default": "user" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" }, { "$ref": "#/components/schemas/InputImageContentParamAutoParam" }, { "$ref": "#/components/schemas/InputFileContentParam" } ], "description": "A piece of message content, such as text, an image, or a file.", "discriminator": { "propertyName": "type" } }, "type": "array" }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "status": { "anyOf": [ { "type": "string", "description": "The status of the message item." }, { "type": "null" } ] } }, "type": "object", "required": ["type", "role", "content"] }, "SystemMessageItemParam": { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, { "type": "null" } ] }, "type": { "type": "string", "enum": ["message"], "description": "The item type. Always `message`.", "default": "message" }, "role": { "type": "string", "enum": ["system"], "description": "The message role. Always `system`.", "default": "system" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" } ], "discriminator": { "propertyName": "type" } }, "type": "array" }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "status": { "anyOf": [ { "type": "string", "description": "The status of the message item." }, { "type": "null" } ] } }, "type": "object", "required": ["type", "role", "content"] }, "DeveloperMessageItemParam": { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, { "type": "null" } ] }, "type": { "type": "string", "enum": ["message"], "description": "The item type. Always `message`.", "default": "message" }, "role": { "type": "string", "enum": ["developer"], "description": "The message role. Always `developer`.", "default": "developer" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" } ], "discriminator": { "propertyName": "type" } }, "type": "array" }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "status": { "anyOf": [ { "type": "string", "description": "The status of the message item." }, { "type": "null" } ] } }, "type": "object", "required": ["type", "role", "content"] }, "UrlCitationParam": { "properties": { "type": { "type": "string", "enum": ["url_citation"], "description": "The citation type. Always `url_citation`.", "default": "url_citation" }, "start_index": { "type": "integer", "minimum": 0, "description": "The index of the first character of the citation in the message." }, "end_index": { "type": "integer", "minimum": 0, "description": "The index of the last character of the citation in the message." }, "url": { "type": "string", "description": "The URL of the cited resource." }, "title": { "type": "string", "description": "The title of the cited resource." } }, "type": "object", "required": ["type", "start_index", "end_index", "url", "title"] }, "OutputTextContentParam": { "properties": { "type": { "type": "string", "enum": ["output_text"], "description": "The content type. Always `output_text`.", "default": "output_text" }, "text": { "type": "string", "maxLength": 10485760, "description": "The text content." }, "annotations": { "oneOf": [ { "items": { "$ref": "#/components/schemas/UrlCitationParam" }, "type": "array" } ], "description": "Citations associated with the text content." } }, "type": "object", "required": ["type", "text"] }, "RefusalContentParam": { "properties": { "type": { "type": "string", "enum": ["refusal"], "description": "The content type. Always `refusal`.", "default": "refusal" }, "refusal": { "type": "string", "maxLength": 10485760, "description": "The refusal text." } }, "type": "object", "required": ["type", "refusal"] }, "AssistantMessageItemParam": { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this message item.", "example": "msg_123" }, { "type": "null" } ] }, "type": { "type": "string", "enum": ["message"], "description": "The item type. Always `message`.", "default": "message" }, "role": { "type": "string", "enum": ["assistant"], "description": "The role of the message author. Always `assistant`.", "default": "assistant" }, "content": { "oneOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/OutputTextContentParam" }, { "$ref": "#/components/schemas/RefusalContentParam" } ], "description": "A piece of assistant message content, such as text or a refusal.", "discriminator": { "propertyName": "type" } }, "type": "array" }, { "type": "string", "maxLength": 10485760, "description": "The message content, as a single string." } ], "description": "The message content, as an array of content parts." }, "status": { "anyOf": [ { "type": "string", "description": "The status of the message item." }, { "type": "null" } ] } }, "type": "object", "required": ["type", "role", "content"] }, "FunctionCallItemStatus": { "type": "string", "enum": ["in_progress", "completed", "incomplete"] }, "FunctionCallItemParam": { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of this function tool call.", "example": "fc_123" }, { "type": "null" } ] }, "call_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The unique ID of the function tool call generated by the model." }, "type": { "type": "string", "enum": ["function_call"], "description": "The item type. Always `function_call`.", "default": "function_call" }, "name": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "description": "The name of the function to call." }, "arguments": { "type": "string", "description": "The function arguments as a JSON string." }, "status": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/FunctionCallStatus" }, { "description": "The status of the function tool call." } ] }, { "type": "null" } ] } }, "type": "object", "required": ["call_id", "type", "name", "arguments"] }, "FunctionCallOutputItemParam": { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of the function tool call output. Populated when this item is returned via API.", "example": "fc_123" }, { "type": "null" } ] }, "call_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The unique ID of the function tool call generated by the model." }, "type": { "type": "string", "enum": ["function_call_output"], "description": "The type of the function tool call output. Always `function_call_output`.", "default": "function_call_output" }, "output": { "oneOf": [ { "type": "string", "maxLength": 10485760, "description": "A JSON string of the output of the function tool call." }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContentParam" }, { "$ref": "#/components/schemas/InputImageContentParamAutoParam" }, { "$ref": "#/components/schemas/InputFileContentParam" }, { "$ref": "#/components/schemas/InputVideoContent" } ], "description": "A piece of message content, such as text, an image, or a file.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "An array of content outputs (text, image, file) for the function tool call." } ], "description": "Text, image, or file output of the function tool call." }, "status": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/FunctionCallStatus" }, { "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API." } ] }, { "type": "null" } ] } }, "type": "object", "required": ["call_id", "type", "output"], "title": "Function tool call output", "description": "The output of a function tool call." }, "ItemParam": { "oneOf": [ { "$ref": "#/components/schemas/ItemReferenceParam" }, { "$ref": "#/components/schemas/ReasoningItemParam" }, { "$ref": "#/components/schemas/UserMessageItemParam" }, { "$ref": "#/components/schemas/SystemMessageItemParam" }, { "$ref": "#/components/schemas/DeveloperMessageItemParam" }, { "$ref": "#/components/schemas/AssistantMessageItemParam" }, { "$ref": "#/components/schemas/FunctionCallItemParam" }, { "$ref": "#/components/schemas/FunctionCallOutputItemParam" } ], "discriminator": { "propertyName": "type" }, "x-unionDisplay": "section", "x-unionTitle": "Input Item Types" }, "IncludeEnum": { "type": "string", "enum": ["reasoning.encrypted_content", "message.output_text.logprobs"], "description": "", "x-enumDescriptions": { "message.output_text.logprobs": "includes sampled logprobs in assistant messages.", "reasoning.encrypted_content": "includes encrypted reasoning content so that it may be rehydrated on a subsequent request." } }, "EmptyModelParam": { "properties": {}, "type": "object", "required": [] }, "FunctionToolParam": { "properties": { "name": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "parameters": { "anyOf": [ { "$ref": "#/components/schemas/EmptyModelParam" }, { "type": "null" } ] }, "strict": { "type": "boolean" }, "type": { "type": "string", "enum": ["function"], "default": "function" } }, "type": "object", "required": ["name", "type"] }, "ResponsesToolParam": { "oneOf": [ { "$ref": "#/components/schemas/FunctionToolParam" } ], "discriminator": { "propertyName": "type" }, "x-unionDisplay": "section", "x-unionTitle": "Tool Types" }, "SpecificFunctionParam": { "properties": { "type": { "type": "string", "enum": ["function"], "description": "The tool to call. Always `function`.", "default": "function" }, "name": { "type": "string", "description": "The name of the function tool to call." } }, "type": "object", "required": ["type", "name"] }, "SpecificToolChoiceParam": { "oneOf": [ { "$ref": "#/components/schemas/SpecificFunctionParam" } ] }, "ToolChoiceValueEnum": { "type": "string", "enum": ["none", "auto", "required"], "x-enumDescriptions": { "auto": "Let the model choose the tools from among the provided set.", "none": "Restrict the model from calling any tools.", "required": "Require the model to call a tool." } }, "AllowedToolsParam": { "properties": { "type": { "type": "string", "enum": ["allowed_tools"], "description": "The tool choice type. Always `allowed_tools`.", "default": "allowed_tools" }, "tools": { "items": { "$ref": "#/components/schemas/SpecificToolChoiceParam" }, "type": "array", "maxItems": 128, "minItems": 1, "description": "The list of tools that are permitted for this request." }, "mode": { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceValueEnum" }, { "description": "How to select a tool from the allowed set." } ] } }, "type": "object", "required": ["type", "tools"] }, "ToolChoiceParam": { "oneOf": [ { "$ref": "#/components/schemas/SpecificToolChoiceParam" }, { "$ref": "#/components/schemas/ToolChoiceValueEnum" }, { "$ref": "#/components/schemas/AllowedToolsParam" } ], "description": "Controls which tool the model should use, if any." }, "MetadataParam": { "additionalProperties": { "type": "string", "maxLength": 512 }, "type": "object", "maxProperties": 16, "description": "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.\n Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters." }, "VerbosityEnum": { "type": "string", "enum": ["low", "medium", "high"], "x-enumDescriptions": { "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." } }, "TextParam": { "properties": { "format": { "description": "The format configuration for text output.", "oneOf": [ { "$ref": "#/components/schemas/TextFormatParam" }, { "type": "null" } ] }, "verbosity": { "allOf": [ { "$ref": "#/components/schemas/VerbosityEnum" }, { "description": "Controls the level of detail in generated text output." } ] } }, "type": "object", "required": [] }, "StreamOptionsParam": { "properties": { "include_obfuscation": { "type": "boolean", "description": "Whether to obfuscate sensitive information in streamed output. Defaults to `true`." } }, "type": "object", "required": [], "description": "Options that control streamed response behavior." }, "ReasoningEffortEnum": { "type": "string", "enum": ["none", "low", "medium", "high", "xhigh"], "x-enumDescriptions": { "high": "Use a higher reasoning effort to improve answer quality.", "medium": "Use a balanced reasoning effort.", "low": "Use a lower reasoning effort for faster responses.", "minimal": "Use the lowest non-zero reasoning effort.", "none": "Restrict the model from performing any reasoning before emitting a final answer.", "xhigh": "Use the maximum reasoning effort available." } }, "ReasoningSummaryEnum": { "type": "string", "enum": ["concise", "detailed", "auto"], "x-enumDescriptions": { "auto": "Allow the model to decide when to summarize.", "concise": "Emit concise summaries of reasoning content.", "detailed": "Emit details summaries of reasoning content." } }, "ReasoningParam": { "properties": { "effort": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/ReasoningEffortEnum" } ], "description": "Controls the level of reasoning effort the model should apply. Higher effort may increase latency and cost." }, { "type": "null" } ] }, "summary": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningSummaryEnum" }, { "description": "Controls whether the response includes a reasoning summary." } ] }, { "type": "null" } ] } }, "type": "object", "required": [], "description": "**gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning)." }, "TruncationEnum": { "type": "string", "enum": ["auto", "disabled"], "x-enumDescriptions": { "auto": "Let the service decide how to truncate.", "disabled": "Disable service truncation. Context over the model's context limit will result in a 400 error." } }, "ServiceTierEnum": { "type": "string", "enum": ["auto", "default", "flex", "priority"], "x-enumDescriptions": { "auto": "Choose a service tier automatically based on current account state.", "default": "Choose the default service tier.", "flex": "Choose the flex service tier.", "priority": "Choose the priority service tier." } }, "CreateResponseBody": { "properties": { "model": { "anyOf": [ { "type": "string", "description": "The model to use for this request, e.g. 'gpt-5.2'." }, { "type": "null" } ] }, "input": { "anyOf": [ { "oneOf": [ { "type": "string", "maxLength": 10485760 }, { "items": { "$ref": "#/components/schemas/ItemParam" }, "type": "array" } ], "description": "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." }, { "type": "null" } ] }, "previous_response_id": { "anyOf": [ { "type": "string", "description": "The ID of the response to use as the prior turn for this request.", "example": "resp_123" }, { "type": "null" } ] }, "include": { "items": { "$ref": "#/components/schemas/IncludeEnum" }, "type": "array" }, "tools": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ResponsesToolParam" }, "type": "array", "description": "A list of tools that the model may call while generating the response." }, { "type": "null" } ] }, "tool_choice": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ToolChoiceParam" }, { "description": "Controls which tool the model should use, if any." } ] }, { "type": "null" } ], "x-unionTitle": "ToolChoiceParam" }, "metadata": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/MetadataParam" }, { "description": "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.\n Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters." } ] }, { "type": "null" } ] }, "text": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/TextParam" }, { "description": "Configuration options for text output." } ] }, { "type": "null" } ] }, "temperature": { "anyOf": [ { "type": "number", "description": "Sampling temperature to use, between 0 and 2. Higher values make the output more random." }, { "type": "null" } ] }, "top_p": { "anyOf": [ { "type": "number", "description": "Nucleus sampling parameter, between 0 and 1. The model considers only the tokens with the top cumulative probability." }, { "type": "null" } ] }, "presence_penalty": { "anyOf": [ { "type": "number", "description": "Penalizes new tokens based on whether they appear in the text so far." }, { "type": "null" } ] }, "frequency_penalty": { "anyOf": [ { "type": "number", "description": "Penalizes new tokens based on their frequency in the text so far." }, { "type": "null" } ] }, "parallel_tool_calls": { "anyOf": [ { "type": "boolean", "description": "Whether the model may call multiple tools in parallel." }, { "type": "null" } ] }, "stream": { "type": "boolean", "description": "Whether to stream response events as server-sent events." }, "stream_options": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/StreamOptionsParam" }, { "description": "Options that control streamed response behavior." } ] }, { "type": "null" } ] }, "background": { "type": "boolean", "description": "Whether to run the request in the background and return immediately." }, "max_output_tokens": { "anyOf": [ { "type": "integer", "minimum": 16, "description": "The maximum number of tokens the model may generate for this response." }, { "type": "null" } ] }, "max_tool_calls": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "The maximum number of tool calls the model may make while generating the response." }, { "type": "null" } ] }, "reasoning": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningParam" }, { "description": "Configuration options for reasoning behavior." } ] }, { "type": "null" } ] }, "safety_identifier": { "anyOf": [ { "type": "string", "maxLength": 64, "description": "A stable identifier used for safety monitoring and abuse detection." }, { "type": "null" } ] }, "prompt_cache_key": { "anyOf": [ { "type": "string", "maxLength": 64, "description": "A key to use when reading from or writing to the prompt cache." }, { "type": "null" } ] }, "truncation": { "allOf": [ { "$ref": "#/components/schemas/TruncationEnum" }, { "description": "Controls how the service truncates the input when it exceeds the model context window." } ] }, "instructions": { "anyOf": [ { "type": "string", "description": "Additional instructions to guide the model for this request." }, { "type": "null" } ] }, "store": { "type": "boolean", "description": "Whether to store the response so it can be retrieved later." }, "service_tier": { "allOf": [ { "$ref": "#/components/schemas/ServiceTierEnum" }, { "description": "The service tier to use for this request." } ] }, "top_logprobs": { "anyOf": [ { "type": "integer", "maximum": 20, "minimum": 0, "description": "The number of most likely tokens to return at each position, along with their log probabilities." }, { "type": "null" } ] } }, "type": "object", "required": [] }, "IncompleteDetails": { "properties": { "reason": { "type": "string", "description": "The reason the response could not be completed." } }, "type": "object", "required": ["reason"], "title": "Incomplete details", "description": "Details about why the response was incomplete." }, "MessageRole": { "type": "string", "enum": ["user", "assistant", "system", "developer"], "x-enumDescriptions": { "assistant": "Model-generated content in the conversation.", "developer": "Developer-supplied guidance that shapes the assistant\u2019s behavior.", "system": "System-level instructions that set global behavior.", "user": "End\u2011user input in the conversation." } }, "InputTextContent": { "properties": { "type": { "type": "string", "enum": ["input_text"], "description": "The type of the input item. Always `input_text`.", "default": "input_text" }, "text": { "type": "string", "description": "The text input to the model." } }, "type": "object", "required": ["type", "text"], "title": "Input text", "description": "A text input to the model." }, "UrlCitationBody": { "properties": { "type": { "type": "string", "enum": ["url_citation"], "description": "The type of the URL citation. Always `url_citation`.", "default": "url_citation" }, "url": { "type": "string", "description": "The URL of the web resource." }, "start_index": { "type": "integer", "description": "The index of the first character of the URL citation in the message." }, "end_index": { "type": "integer", "description": "The index of the last character of the URL citation in the message." }, "title": { "type": "string", "description": "The title of the web resource." } }, "type": "object", "required": ["type", "url", "start_index", "end_index", "title"], "title": "URL citation", "description": "A citation for a web resource used to generate a model response." }, "Annotation": { "oneOf": [ { "$ref": "#/components/schemas/UrlCitationBody" } ], "description": "An annotation that applies to a span of output text.", "discriminator": { "propertyName": "type" } }, "TopLogProb": { "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "items": { "type": "integer" }, "type": "array" } }, "type": "object", "required": ["token", "logprob", "bytes"], "title": "Top log probability", "description": "The top log probability of a token." }, "LogProb": { "properties": { "token": { "type": "string" }, "logprob": { "type": "number" }, "bytes": { "items": { "type": "integer" }, "type": "array" }, "top_logprobs": { "items": { "$ref": "#/components/schemas/TopLogProb" }, "type": "array" } }, "type": "object", "required": ["token", "logprob", "bytes", "top_logprobs"], "title": "Log probability", "description": "The log probability of a token." }, "OutputTextContent": { "properties": { "type": { "type": "string", "enum": ["output_text"], "description": "The type of the output text. Always `output_text`.", "default": "output_text" }, "text": { "type": "string", "description": "The text output from the model." }, "annotations": { "items": { "$ref": "#/components/schemas/Annotation" }, "type": "array", "description": "The annotations of the text output." }, "logprobs": { "items": { "$ref": "#/components/schemas/LogProb" }, "type": "array" } }, "type": "object", "required": ["type", "text", "annotations"], "title": "Output text", "description": "A text output from the model." }, "TextContent": { "properties": { "type": { "type": "string", "enum": ["text"], "default": "text" }, "text": { "type": "string" } }, "type": "object", "required": ["type", "text"], "title": "Text Content", "description": "A text content." }, "SummaryTextContent": { "properties": { "type": { "type": "string", "enum": ["summary_text"], "description": "The type of the object. Always `summary_text`.", "default": "summary_text" }, "text": { "type": "string", "description": "A summary of the reasoning output from the model so far." } }, "type": "object", "required": ["type", "text"], "title": "Summary text", "description": "A summary text from the model." }, "ReasoningTextContent": { "properties": { "type": { "type": "string", "enum": ["reasoning_text"], "description": "The type of the reasoning text. Always `reasoning_text`.", "default": "reasoning_text" }, "text": { "type": "string", "description": "The reasoning text from the model." } }, "type": "object", "required": ["type", "text"], "title": "Reasoning text", "description": "Reasoning text from the model." }, "RefusalContent": { "properties": { "type": { "type": "string", "enum": ["refusal"], "description": "The type of the refusal. Always `refusal`.", "default": "refusal" }, "refusal": { "type": "string", "description": "The refusal explanation from the model." } }, "type": "object", "required": ["type", "refusal"], "title": "Refusal", "description": "A refusal from the model." }, "ImageDetail": { "type": "string", "enum": ["low", "high", "auto"], "x-enumDescriptions": { "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." } }, "InputImageContent": { "properties": { "type": { "type": "string", "enum": ["input_image"], "description": "The type of the input item. Always `input_image`.", "default": "input_image" }, "image_url": { "anyOf": [ { "type": "string", "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL." }, { "type": "null" } ] }, "detail": { "allOf": [ { "$ref": "#/components/schemas/ImageDetail" }, { "description": "The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`." } ] } }, "type": "object", "required": ["type", "image_url", "detail"], "title": "Input image", "description": "An image input to the model. Learn about [image inputs](/docs/guides/vision)." }, "InputFileContent": { "properties": { "type": { "type": "string", "enum": ["input_file"], "description": "The type of the input item. Always `input_file`.", "default": "input_file" }, "filename": { "type": "string", "description": "The name of the file to be sent to the model." }, "file_url": { "type": "string", "description": "The URL of the file to be sent to the model." } }, "type": "object", "required": ["type"], "title": "Input file", "description": "A file input to the model." }, "MessageStatus": { "type": "string", "enum": ["in_progress", "completed", "incomplete"], "x-enumDescriptions": { "completed": "Model has finished sampling this item.", "in_progress": "Model is currently sampling this item.", "incomplete": "Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget." } }, "Message": { "properties": { "type": { "type": "string", "enum": ["message"], "description": "The type of the message. Always set to `message`.", "default": "message" }, "id": { "type": "string", "description": "The unique ID of the message." }, "status": { "allOf": [ { "$ref": "#/components/schemas/MessageStatus" }, { "description": "The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API." } ] }, "role": { "allOf": [ { "$ref": "#/components/schemas/MessageRole" }, { "description": "The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`." } ] }, "content": { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" }, { "$ref": "#/components/schemas/InputVideoContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "The content of the message" } }, "type": "object", "required": ["type", "id", "status", "role", "content"], "title": "Message", "description": "A message to or from the model." }, "FunctionCallStatus": { "type": "string", "enum": ["in_progress", "completed", "incomplete"], "x-enumDescriptions": { "completed": "Model has finished sampling this item.", "in_progress": "Model is currently sampling this item.", "incomplete": "Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget." } }, "FunctionCall": { "properties": { "type": { "type": "string", "enum": ["function_call"], "description": "The type of the item. Always `function_call`.", "default": "function_call" }, "id": { "type": "string", "description": "The unique ID of the function call item." }, "call_id": { "type": "string", "description": "The unique ID of the function tool call that was generated." }, "name": { "type": "string", "description": "The name of the function that was called." }, "arguments": { "type": "string", "description": "The arguments JSON string that was generated." }, "status": { "allOf": [ { "$ref": "#/components/schemas/FunctionCallStatus" }, { "description": "The status of the function call item that was recorded." } ] } }, "type": "object", "required": ["type", "id", "call_id", "name", "arguments", "status"], "title": "Function call", "description": "A function tool call that was generated by the model." }, "FunctionCallOutputStatusEnum": { "type": "string", "enum": ["in_progress", "completed", "incomplete"], "description": "Similar to `FunctionCallStatus`. All three options are allowed here for compatibility, but because in practice these items will be provided by developers, only `completed` should be used." }, "FunctionCallOutput": { "properties": { "type": { "type": "string", "enum": ["function_call_output"], "description": "The type of the function tool call output. Always `function_call_output`.", "default": "function_call_output" }, "id": { "type": "string", "description": "The unique ID of the function tool call output. Populated when this item is returned via API." }, "call_id": { "type": "string", "description": "The unique ID of the function tool call generated by the model." }, "output": { "oneOf": [ { "type": "string", "description": "A JSON string of the output of the function tool call." }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "An array of output contents (images, files, text) for the function tool call." } ] }, "status": { "allOf": [ { "$ref": "#/components/schemas/FunctionCallOutputStatusEnum" }, { "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API." } ] } }, "type": "object", "required": ["type", "id", "call_id", "output", "status"], "title": "Function call output", "description": "A function tool call output that was returned by the tool." }, "ReasoningBody": { "properties": { "type": { "type": "string", "enum": ["reasoning"], "description": "The type of the item. Always `reasoning`.", "default": "reasoning" }, "id": { "type": "string", "description": "The unique ID of the reasoning item." }, "content": { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "The reasoning content that was generated." }, "summary": { "items": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } }, "type": "array", "description": "The reasoning summary content that was generated." }, "encrypted_content": { "type": "string", "description": "The encrypted reasoning content that was generated." } }, "type": "object", "required": ["type", "id", "summary"], "title": "Reasoning item", "description": "A reasoning item that was generated by the model." }, "ItemField": { "oneOf": [ { "$ref": "#/components/schemas/Message" }, { "$ref": "#/components/schemas/FunctionCall" }, { "$ref": "#/components/schemas/FunctionCallOutput" }, { "$ref": "#/components/schemas/ReasoningBody" } ], "description": "An item representing a message, tool call, tool output, reasoning, or other response element.", "discriminator": { "propertyName": "type" } }, "Error": { "properties": { "code": { "type": "string", "description": "A machine-readable error code that was returned." }, "message": { "type": "string", "description": "A human-readable description of the error that was returned." } }, "type": "object", "required": ["code", "message"], "title": "Error", "description": "An error that occurred while generating the response." }, "FunctionTool": { "properties": { "type": { "type": "string", "enum": ["function"], "description": "The type of the function tool. Always `function`.", "default": "function" }, "name": { "type": "string", "description": "The name of the function to call." }, "description": { "anyOf": [ { "type": "string", "description": "A description of the function. Used by the model to determine whether or not to call the function." }, { "type": "null" } ] }, "parameters": { "anyOf": [ { "additionalProperties": {}, "type": "object", "description": "A JSON schema object describing the parameters of the function." }, { "type": "null" } ] }, "strict": { "anyOf": [ { "type": "boolean", "description": "Whether to enforce strict parameter validation. Default `true`." }, { "type": "null" } ] } }, "type": "object", "required": ["type", "name", "description", "parameters", "strict"], "title": "Function", "description": "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)." }, "Tool": { "oneOf": [ { "$ref": "#/components/schemas/FunctionTool" } ], "description": "A tool that can be used to generate a response.", "discriminator": { "propertyName": "type" } }, "FunctionToolChoice": { "properties": { "type": { "type": "string", "enum": ["function"], "default": "function" }, "name": { "type": "string" } }, "type": "object", "required": ["type"] }, "AllowedToolChoice": { "properties": { "type": { "type": "string", "enum": ["allowed_tools"], "default": "allowed_tools" }, "tools": { "items": { "oneOf": [ { "$ref": "#/components/schemas/FunctionToolChoice" } ] }, "type": "array" }, "mode": { "$ref": "#/components/schemas/ToolChoiceValueEnum" } }, "type": "object", "required": ["type", "tools", "mode"] }, "TextResponseFormat": { "properties": { "type": { "type": "string", "enum": ["text"], "default": "text" } }, "type": "object", "required": ["type"] }, "JsonObjectResponseFormat": { "properties": { "type": { "type": "string", "enum": ["json_object"], "default": "json_object" } }, "type": "object", "required": ["type"] }, "JsonSchemaResponseFormat": { "properties": { "type": { "type": "string", "enum": ["json_schema"], "default": "json_schema" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema": { "anyOf": [ { "type": "null" } ] }, "strict": { "type": "boolean" } }, "type": "object", "required": ["type", "name", "description", "schema", "strict"] }, "TextField": { "properties": { "format": { "oneOf": [ { "$ref": "#/components/schemas/TextResponseFormat" }, { "$ref": "#/components/schemas/JsonObjectResponseFormat" }, { "$ref": "#/components/schemas/JsonSchemaResponseFormat" } ] }, "verbosity": { "$ref": "#/components/schemas/VerbosityEnum" } }, "type": "object", "required": ["format"] }, "Reasoning": { "properties": { "effort": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/ReasoningEffortEnum" } ], "description": "The reasoning effort that was requested for the model, if specified." }, { "type": "null" } ] }, "summary": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ReasoningSummaryEnum" }, { "description": "A model-generated summary of its reasoning that was produced, if available." } ] }, { "type": "null" } ] } }, "type": "object", "required": ["effort", "summary"], "title": "Reasoning", "description": "Reasoning configuration and metadata that were used for the response." }, "InputTokensDetails": { "properties": { "cached_tokens": { "type": "integer", "description": "The number of input tokens that were served from cache." } }, "type": "object", "required": ["cached_tokens"], "title": "Input tokens details", "description": "A breakdown of input token usage that was recorded." }, "OutputTokensDetails": { "properties": { "reasoning_tokens": { "type": "integer", "description": "The number of output tokens that were attributed to reasoning." } }, "type": "object", "required": ["reasoning_tokens"], "title": "Output tokens details", "description": "A breakdown of output token usage that was recorded." }, "Usage": { "properties": { "input_tokens": { "type": "integer", "description": "The number of input tokens that were used to generate the response." }, "output_tokens": { "type": "integer", "description": "The number of output tokens that were generated by the model." }, "total_tokens": { "type": "integer", "description": "The total number of tokens that were used." }, "input_tokens_details": { "allOf": [ { "$ref": "#/components/schemas/InputTokensDetails" }, { "description": "A breakdown of input token usage that was recorded." } ] }, "output_tokens_details": { "allOf": [ { "$ref": "#/components/schemas/OutputTokensDetails" }, { "description": "A breakdown of output token usage that was recorded." } ] } }, "type": "object", "required": [ "input_tokens", "output_tokens", "total_tokens", "input_tokens_details", "output_tokens_details" ], "title": "Usage", "description": "Token usage statistics that were recorded for the response." }, "ResponseResource": { "properties": { "id": { "type": "string", "description": "The unique ID of the response that was created." }, "object": { "type": "string", "enum": ["response"], "description": "The object type, which was always `response`.", "default": "response" }, "created_at": { "type": "integer", "description": "The Unix timestamp (in seconds) for when the response was created." }, "completed_at": { "anyOf": [ { "type": "integer", "description": "The Unix timestamp (in seconds) for when the response was completed, if it was completed." }, { "type": "null" } ] }, "status": { "type": "string", "description": "The status that was set for the response." }, "incomplete_details": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/IncompleteDetails" }, { "description": "Details about why the response was incomplete, if applicable." } ] }, { "type": "null" } ] }, "model": { "type": "string", "description": "The model that generated this response." }, "previous_response_id": { "anyOf": [ { "type": "string", "description": "The ID of the previous response in the chain that was referenced, if any." }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "oneOf": [ { "type": "string" } ], "description": "Additional instructions that were used to guide the model for this response." }, { "type": "null" } ] }, "output": { "items": { "$ref": "#/components/schemas/ItemField" }, "type": "array", "description": "The output items that were generated by the model." }, "error": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "description": "The error that occurred, if the response failed." } ] }, { "type": "null" } ] }, "tools": { "items": { "$ref": "#/components/schemas/Tool" }, "type": "array", "description": "The tools that were available to the model during response generation." }, "tool_choice": { "oneOf": [ { "$ref": "#/components/schemas/FunctionToolChoice" }, { "$ref": "#/components/schemas/ToolChoiceValueEnum" }, { "$ref": "#/components/schemas/AllowedToolChoice" } ] }, "truncation": { "allOf": [ { "$ref": "#/components/schemas/TruncationEnum" }, { "description": "How the input was truncated by the service when it exceeded the model context window." } ] }, "parallel_tool_calls": { "type": "boolean", "description": "Whether the model was allowed to call multiple tools in parallel." }, "text": { "allOf": [ { "$ref": "#/components/schemas/TextField" }, { "description": "Configuration options for text output that were used." } ] }, "top_p": { "type": "number", "description": "The nucleus sampling parameter that was used for this response." }, "presence_penalty": { "type": "number", "description": "The presence penalty that was used to penalize new tokens based on whether they appear in the text so far." }, "frequency_penalty": { "type": "number", "description": "The frequency penalty that was used to penalize new tokens based on their frequency in the text so far." }, "top_logprobs": { "type": "integer", "description": "The number of most likely tokens that were returned at each position, along with their log probabilities." }, "temperature": { "type": "number", "description": "The sampling temperature that was used for this response." }, "reasoning": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/Reasoning" }, { "description": "Reasoning configuration and outputs that were produced for this response." } ] }, { "type": "null" } ] }, "usage": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/Usage" }, { "description": "Token usage statistics that were recorded for the response, if available." } ] }, { "type": "null" } ] }, "max_output_tokens": { "anyOf": [ { "type": "integer", "description": "The maximum number of tokens the model was allowed to generate for this response." }, { "type": "null" } ] }, "max_tool_calls": { "anyOf": [ { "type": "integer", "description": "The maximum number of tool calls the model was allowed to make while generating the response." }, { "type": "null" } ] }, "store": { "type": "boolean", "description": "Whether this response was stored so it can be retrieved later." }, "background": { "type": "boolean", "description": "Whether this request was run in the background." }, "service_tier": { "type": "string", "description": "The service tier that was used for this response." }, "metadata": { "description": "Developer-defined metadata that was associated with the response." }, "safety_identifier": { "anyOf": [ { "type": "string", "description": "A stable identifier that was used for safety monitoring and abuse detection." }, { "type": "null" } ] }, "prompt_cache_key": { "anyOf": [ { "type": "string", "description": "A key that was used to read from or write to the prompt cache." }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "object", "created_at", "completed_at", "status", "incomplete_details", "model", "previous_response_id", "instructions", "output", "error", "tools", "tool_choice", "truncation", "parallel_tool_calls", "text", "top_p", "presence_penalty", "frequency_penalty", "top_logprobs", "temperature", "reasoning", "usage", "max_output_tokens", "max_tool_calls", "store", "background", "service_tier", "metadata", "safety_identifier", "prompt_cache_key" ], "title": "The response object", "description": "The complete response object that was returned by the Responses API.", "example": { "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": {}, "service_tier": "default", "top_logprobs": 0 } }, "ResponseCreatedStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.created"], "description": "The type of the event, always `response.created`.", "default": "response.created" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": ["type", "sequence_number", "response"], "title": "Response created event", "description": "A streaming event that indicated the response was created." }, "ResponseQueuedStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.queued"], "description": "The type of the event, always `response.queued`.", "default": "response.queued" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": ["type", "sequence_number", "response"], "title": "Response queued event", "description": "A streaming event that indicated the response was queued." }, "ResponseInProgressStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.in_progress"], "description": "The type of the event, always `response.in_progress`.", "default": "response.in_progress" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": ["type", "sequence_number", "response"], "title": "Response in progress event", "description": "A streaming event that indicated the response was in progress." }, "ResponseCompletedStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.completed"], "description": "The type of the event, always `response.completed`.", "default": "response.completed" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": ["type", "sequence_number", "response"], "title": "Response completed event", "description": "A streaming event that indicated the response was completed." }, "ResponseFailedStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.failed"], "description": "The type of the event, always `response.failed`.", "default": "response.failed" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": ["type", "sequence_number", "response"], "title": "Response failed event", "description": "A streaming event that indicated the response had failed." }, "ResponseIncompleteStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.incomplete"], "description": "The type of the event, always `response.incomplete`.", "default": "response.incomplete" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "response": { "allOf": [ { "$ref": "#/components/schemas/ResponseResource" }, { "description": "The response snapshot that was emitted with the event." } ] } }, "type": "object", "required": ["type", "sequence_number", "response"], "title": "Response incomplete event", "description": "A streaming event that indicated the response was incomplete." }, "ResponseOutputItemAddedStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.output_item.added"], "description": "The type of the event, always `response.output_item.added`.", "default": "response.output_item.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "output_index": { "type": "integer", "description": "The index of the output item that was added." }, "item": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ItemField" }, { "description": "An item representing a message, tool call, tool output, reasoning, or other response element." } ] }, { "type": "null" } ] } }, "type": "object", "required": ["type", "sequence_number", "output_index", "item"], "title": "Response output item added event", "description": "A streaming event that indicated an output item was added to the response." }, "ResponseOutputItemDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.output_item.done"], "description": "The type of the event, always `response.output_item.done`.", "default": "response.output_item.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "output_index": { "type": "integer", "description": "The index of the output item that was completed." }, "item": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ItemField" }, { "description": "An item representing a message, tool call, tool output, reasoning, or other response element." } ] }, { "type": "null" } ] } }, "type": "object", "required": ["type", "sequence_number", "output_index", "item"], "title": "Response output item done event", "description": "A streaming event that indicated an output item was completed." }, "ResponseReasoningSummaryPartAddedStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.reasoning_summary_part.added"], "description": "The type of the event, always `response.reasoning_summary_part.added`.", "default": "response.reasoning_summary_part.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary part that was added." }, "part": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "part" ], "title": "Response reasoning summary part added event", "description": "A streaming event that indicated a reasoning summary part was added." }, "ResponseReasoningSummaryPartDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.reasoning_summary_part.done"], "description": "The type of the event, always `response.reasoning_summary_part.done`.", "default": "response.reasoning_summary_part.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary part that was completed." }, "part": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "part" ], "title": "Response reasoning summary part done event", "description": "A streaming event that indicated a reasoning summary part was completed." }, "ResponseContentPartAddedStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.content_part.added"], "description": "The type of the event, always `response.content_part.added`.", "default": "response.content_part.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was added." }, "part": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "part" ], "title": "Response content part added event", "description": "A streaming event that indicated a content part was added." }, "ResponseContentPartDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.content_part.done"], "description": "The type of the event, always `response.content_part.done`.", "default": "response.content_part.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was completed." }, "part": { "oneOf": [ { "$ref": "#/components/schemas/InputTextContent" }, { "$ref": "#/components/schemas/OutputTextContent" }, { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/SummaryTextContent" }, { "$ref": "#/components/schemas/ReasoningTextContent" }, { "$ref": "#/components/schemas/RefusalContent" }, { "$ref": "#/components/schemas/InputImageContent" }, { "$ref": "#/components/schemas/InputFileContent" } ], "description": "A content part that makes up an input or output item.", "discriminator": { "propertyName": "type" } } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "part" ], "title": "Response content part done event", "description": "A streaming event that indicated a content part was completed." }, "ResponseOutputTextDeltaStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.output_text.delta"], "description": "The type of the event, always `response.output_text.delta`.", "default": "response.output_text.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was updated." }, "delta": { "type": "string", "description": "The text delta that was appended." }, "logprobs": { "items": { "$ref": "#/components/schemas/LogProb" }, "type": "array", "description": "The token log probabilities that were emitted with the delta, if any." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "delta" ], "title": "Response output text delta event", "description": "A streaming event that indicated output text was incrementally added." }, "ResponseOutputTextDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.output_text.done"], "description": "The type of the event, always `response.output_text.done`.", "default": "response.output_text.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the content part that was completed." }, "text": { "type": "string", "description": "The final text that was emitted." }, "logprobs": { "items": { "$ref": "#/components/schemas/LogProb" }, "type": "array", "description": "The token log probabilities that were emitted with the final text, if any." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "text" ], "title": "Response output text done event", "description": "A streaming event that indicated output text was completed." }, "ResponseRefusalDeltaStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.refusal.delta"], "description": "The type of the event, always `response.refusal.delta`.", "default": "response.refusal.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the refusal content that was updated." }, "delta": { "type": "string", "description": "The refusal text delta that was appended." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "delta" ], "title": "Response refusal delta event", "description": "A streaming event that indicated refusal text was incrementally added." }, "ResponseRefusalDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.refusal.done"], "description": "The type of the event, always `response.refusal.done`.", "default": "response.refusal.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the refusal content that was completed." }, "refusal": { "type": "string", "description": "The final refusal text that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "refusal" ], "title": "Response refusal done event", "description": "A streaming event that indicated refusal text was completed." }, "ResponseReasoningDeltaStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.reasoning.delta"], "description": "The type of the event, always `response.reasoning.delta`.", "default": "response.reasoning.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the reasoning content that was updated." }, "delta": { "type": "string", "description": "The reasoning text delta that was appended." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "delta" ], "title": "Response reasoning delta event", "description": "A streaming event that indicated reasoning text was incrementally added." }, "ResponseReasoningDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.reasoning.done"], "description": "The type of the event, always `response.reasoning.done`.", "default": "response.reasoning.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the reasoning content that was completed." }, "text": { "type": "string", "description": "The final reasoning text that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "text" ], "title": "Response reasoning done event", "description": "A streaming event that indicated reasoning text was completed." }, "ResponseReasoningSummaryDeltaStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.reasoning_summary_text.delta"], "description": "The type of the event, always `response.reasoning_summary.delta`.", "default": "response.reasoning_summary_text.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary content that was updated." }, "delta": { "type": "string", "description": "The summary text delta that was appended." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "delta" ], "title": "Response reasoning summary delta event", "description": "A streaming event that indicated a reasoning summary was incrementally added." }, "ResponseReasoningSummaryDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.reasoning_summary_text.done"], "description": "The type of the event, always `response.reasoning_summary.done`.", "default": "response.reasoning_summary_text.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "summary_index": { "type": "integer", "description": "The index of the summary content that was completed." }, "text": { "type": "string", "description": "The final summary text that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "summary_index", "text" ], "title": "Response reasoning summary done event", "description": "A streaming event that indicated a reasoning summary was completed." }, "ResponseOutputTextAnnotationAddedStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.output_text.annotation.added"], "description": "The type of the event, always `response.output_text.annotation.added`.", "default": "response.output_text.annotation.added" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "content_index": { "type": "integer", "description": "The index of the output text content that was updated." }, "annotation_index": { "type": "integer", "description": "The index of the annotation that was added." }, "annotation": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/Annotation" }, { "description": "An annotation that applies to a span of output text." } ] }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "content_index", "annotation_index", "annotation" ], "title": "Response output text annotation added event", "description": "A streaming event that indicated an output text annotation was added." }, "ResponseFunctionCallArgumentsDeltaStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.function_call_arguments.delta"], "description": "The type of the event, always `response.function_call_arguments.delta`.", "default": "response.function_call_arguments.delta" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the tool call item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "delta": { "type": "string", "description": "The arguments delta that was appended." }, "obfuscation": { "type": "string", "description": "An obfuscation string that was added to pad the event payload." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "delta" ], "title": "Response function call arguments delta event", "description": "A streaming event that indicated function call arguments were incrementally added." }, "ResponseFunctionCallArgumentsDoneStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["response.function_call_arguments.done"], "description": "The type of the event, always `response.function_call_arguments.done`.", "default": "response.function_call_arguments.done" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "item_id": { "type": "string", "description": "The ID of the tool call item that was updated." }, "output_index": { "type": "integer", "description": "The index of the output item that was updated." }, "arguments": { "type": "string", "description": "The final arguments string that was emitted." } }, "type": "object", "required": [ "type", "sequence_number", "item_id", "output_index", "arguments" ], "title": "Response function call arguments done event", "description": "A streaming event that indicated function call arguments were completed." }, "ErrorPayload": { "properties": { "type": { "type": "string", "description": "The error type that was emitted." }, "code": { "anyOf": [ { "type": "string", "description": "The error code that was emitted, if any." }, { "type": "null" } ] }, "message": { "type": "string", "description": "The human-readable error message that was emitted." }, "param": { "anyOf": [ { "type": "string", "description": "The parameter name that was associated with the error, if any." }, { "type": "null" } ] }, "headers": { "additionalProperties": { "type": "string", "description": "The header value that was emitted." }, "type": "object", "description": "The response headers that were emitted with the error, if any." } }, "type": "object", "required": ["type", "code", "message", "param"], "title": "Error payload", "description": "An error payload that was emitted for a streaming error event." }, "ErrorStreamingEvent": { "properties": { "type": { "type": "string", "enum": ["error"], "description": "The type of the event, always `error`.", "default": "error" }, "sequence_number": { "type": "integer", "description": "The sequence number of the event that was emitted." }, "error": { "allOf": [ { "$ref": "#/components/schemas/ErrorPayload" }, { "description": "The error payload that was emitted." } ] } }, "type": "object", "required": ["type", "sequence_number", "error"], "title": "Error event", "description": "A streaming event that indicated an error was emitted." }, "InputVideoContent": { "type": "object", "description": "A content block representing a video input to the model.", "properties": { "type": { "type": "string", "enum": ["input_video"], "description": "The type of the input content. Always `input_video`." }, "video_url": { "type": "string", "description": "A base64 or remote url that resolves to a video file." } }, "required": ["type", "video_url"] }, "JsonSchemaResponseFormatParam": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `json_schema`.", "enum": ["json_schema"] }, "description": { "type": "string", "description": "A description of what the response format is for, used by the model to\ndetermine how to respond in the format.\n" }, "name": { "type": "string", "description": "The name of the response format. Must be a-z, A-Z, 0-9, or contain\nunderscores and dashes, with a maximum length of 64.\n" }, "schema": { "type": "object", "title": "JSON schema", "description": "The schema for the response format, described as a JSON Schema object.\n", "additionalProperties": true }, "strict": { "anyOf": [ { "type": "boolean", "default": false, "description": "Whether to enable strict schema adherence when generating the output.\nIf set to true, the model will always follow the exact schema defined\nin the `schema` field. Only a subset of JSON Schema is supported when\n`strict` is `true`.\n" }, { "type": "null" } ] } } }, "TextFormatParam": { "oneOf": [ { "$ref": "#/components/schemas/TextResponseFormat" }, { "$ref": "#/components/schemas/JsonSchemaResponseFormatParam" } ] } } }, "paths": { "/responses": { "post": { "summary": "Create response", "description": "Creates a response.", "operationId": "createResponse", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponseBody" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CreateResponseBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseResource" } }, "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ResponseCreatedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseQueuedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseInProgressStreamingEvent" }, { "$ref": "#/components/schemas/ResponseCompletedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseFailedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseIncompleteStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputItemAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputItemDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryPartAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryPartDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseContentPartAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseContentPartDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputTextDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputTextDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseRefusalDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseRefusalDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseReasoningSummaryDoneStreamingEvent" }, { "$ref": "#/components/schemas/ResponseOutputTextAnnotationAddedStreamingEvent" }, { "$ref": "#/components/schemas/ResponseFunctionCallArgumentsDeltaStreamingEvent" }, { "$ref": "#/components/schemas/ResponseFunctionCallArgumentsDoneStreamingEvent" }, { "$ref": "#/components/schemas/ErrorStreamingEvent" } ], "discriminator": { "propertyName": "type" } } } } } } } } } }