@inductiv/node-red-openai-api/src/responses/help.html

Enhance your Node-RED projects with advanced AI capabilities.

<section>
    <details>
        <summary style="font-weight: bold;">🗨️ Responses</summary>
        <a href="https://developers.openai.com/api/reference/typescript/resources/responses/" target="_blank">Official Documentation
            <i class="fa fa-external-link fa-sm" aria-hidden="true"></i></a>
        <h4 style="font-weight: bolder;"> ⋙ Create Model Response</h4>
        <p>Creates a model response.</p>
        <dl class="message-properties">
            <h4>msg.payload Properties</h4>

            <dt>
                input
                <span class="property-type">string | array</span>
            </dt>
            <dd>
                Text, image, or file inputs to the model, used to generate a response.
                For assistant message items in an array input, you may also set
                <code>phase</code> to <code>commentary</code> or <code>final_answer</code>.
                For file inputs, use <code>input_file</code> items and set
                <code>detail</code> to <code>low</code> or <code>high</code> when
                you need to control file rendering quality.
                To make extra tools available at a specific point in an array input,
                send an <code>additional_tools</code> item with
                <code>role: "developer"</code> and a <code>tools</code> array. The
                item may also include an <code>id</code>.
            </dd>

            <dt>
                model
                <span class="property-type">string</span>
            </dt>
            <dd>
                Model ID used to generate the response, including newer Responses-compatible
                model strings such as <code>gpt-5.4-mini</code>, <code>gpt-5.4-nano</code>,
                and dated variants like <code>gpt-5.4-mini-2026-03-17</code>.
            </dd>

            <dt class="optional">
                background
                <span class="property-type">boolean</span>
            </dt>
            <dd>Whether to run the model response in the background.</dd>

            <dt class="optional">
                context_management
                <span class="property-type">array</span>
            </dt>
            <dd>Context management settings, including compaction behavior.</dd>

            <dt class="optional">
                conversation
                <span class="property-type">string | object</span>
            </dt>
            <dd>Conversation context to prepend for this response.</dd>

            <dt class="optional">
                include
                <span class="property-type">array</span>
            </dt>
            <dd>
                Specify additional output data to include in the model response,
                for example <code>web_search_call.results</code>,
                <code>web_search_call.action.sources</code>, or
                <code>message.output_text.logprobs</code>.
                Web-search search actions use <code>queries</code> for current
                multi-query payloads. The older <code>query</code> field is
                deprecated and optional when present in returned action data.
            </dd>

            <dt class="optional">
                instructions
                <span class="property-type">string</span>
            </dt>
            <dd>Inserts a system (or developer) message as the first item in the model's context.</dd>

            <dt class="optional">
                max_output_tokens
                <span class="property-type">integer</span>
            </dt>
            <dd>An upper bound for the number of tokens that can be generated for a response.</dd>

            <dt class="optional">
                metadata
                <span class="property-type">object</span>
            </dt>
            <dd>Set of 16 key-value pairs that can be attached to an object.</dd>

            <dt class="optional">
                parallel_tool_calls
                <span class="property-type">boolean</span>
            </dt>
            <dd>Whether to allow the model to run tool calls in parallel.</dd>

            <dt class="optional">
                previous_response_id
                <span class="property-type">string</span>
            </dt>
            <dd>The unique ID of the previous response to the model.</dd>

            <dt class="optional">
                prompt
                <span class="property-type">object</span>
            </dt>
            <dd>Reference to a reusable prompt template and variables.</dd>

            <dt class="optional">
                prompt_cache_key
                <span class="property-type">string</span>
            </dt>
            <dd>Stable key used to improve prompt cache hit rates.</dd>

            <dt class="optional">
                prompt_cache_retention
                <span class="property-type">string</span>
            </dt>
            <dd>
                Prompt cache retention policy. Set <code>24h</code> for extended prompt caching.
                For <code>gpt-5.5</code>, <code>gpt-5.5-pro</code>, and future models, only
                <code>24h</code> is supported. For older models that support both <code>in_memory</code>
                and <code>24h</code>, the default depends on the organization's data retention policy:
                organizations without ZDR enabled default to <code>24h</code>, and organizations with
                ZDR enabled default to <code>in_memory</code> when <code>prompt_cache_retention</code>
                is not specified.
            </dd>

            <dt class="optional">
                reasoning
                <span class="property-type">object</span>
            </dt>
            <dd>o-series models only. See official docs for option properties.</dd>

            <dt class="optional">
                safety_identifier
                <span class="property-type">string</span>
            </dt>
            <dd>Stable end-user identifier used for abuse detection and safety controls.</dd>

            <dt class="optional">
                service_tier
                <span class="property-type">string</span>
            </dt>
            <dd>Service tier selection, for example <code>default</code>, <code>flex</code>, or <code>priority</code>.</dd>

            <dt class="optional">
                store
                <span class="property-type">boolean</span>
            </dt>
            <dd>Whether to store the generated model response for later retrieval via API.</dd>

            <dt class="optional">
                stream
                <span class="property-type">boolean</span>
            </dt>
            <dd>If set to true, the model response data will be streamed to the client as it is generated using
                server-sent events.</dd>

            <dt class="optional">
                stream_options
                <span class="property-type">object</span>
            </dt>
            <dd>Streaming options such as obfuscation behavior for event payloads.</dd>

            <dt class="optional">
                temperature
                <span class="property-type">number</span>
            </dt>
            <dd>What sampling temperature to use, between 0 and 2.</dd>

            <dt class="optional">
                text
                <span class="property-type">object</span>
            </dt>
            <dd>Configuration options for a text response from the model.</dd>

            <dt class="optional">
                tool_choice
                <span class="property-type">string or object</span>
            </dt>
            <dd>How the model should select which tool (or tools) to use when generating a response.</dd>

            <dt class="optional">
                tools
                <span class="property-type">array</span>
            </dt>
            <dd>
                An array of tools the model may call while generating a response.
                This includes Model Context Protocol tools, Tool Search via
                <code>{ "type": "tool_search" }</code>, and GA computer use via
                <code>{ "type": "computer" }</code>.
                Deferred tool loading is supported by setting
                <code>defer_loading: true</code> on tool definitions.
                Computer-tool workflows typically require follow-up requests that send
                <code>computer_call_output</code> items back through <code>input</code>.
                For Model Context Protocol (MCP) tools, each object in the array should follow <a
                    href="https://platform.openai.com/docs/guides/tools-remote-mcp?lang=javascript&utm_source==%40inductiv%2Fnode-red-openai-api"
                    target="_blank">this
                    structure</a>.
            </dd>

            <dt class="optional">
                top_logprobs
                <span class="property-type">integer</span>
            </dt>
            <dd>
                Integer between 0 and 20 specifying how many likely alternative
                tokens to return per position. Pair this with
                <code>include: ["message.output_text.logprobs"]</code> when you
                want the returned response to include those logprobs.
            </dd>

            <dt class="optional">
                top_p
                <span class="property-type">number</span>
            </dt>
            <dd>An alternative to sampling with temperature, called nucleus sampling.</dd>

            <dt class="optional">
                truncation
                <span class="property-type">string</span>
            </dt>
            <dd>The truncation strategy to use for the model response.</dd>

            <dt class="optional">
                user
                <span class="property-type">string</span>
            </dt>
            <dd>Deprecated. Prefer <code>safety_identifier</code> and <code>prompt_cache_key</code>.</dd>

        </dl>

        <h4 style="font-weight: bolder;"> ⋙ Parse Model Response</h4>
        <p>
            Creates a model response and returns the SDK-parsed result for structured-output payloads.
        </p>
        <p>
            Use the same request body shape as <code>Create Model Response</code> when your payload includes
            parseable text formats or tools that the official SDK can parse for you.
        </p>
        <dl class="message-properties">
            <h4>msg.payload Properties</h4>
            <dt>
                input
                <span class="property-type">string | array</span>
            </dt>
            <dd>Text, image, or file inputs to the model, used to generate a parsed response.</dd>
            <dt>
                model
                <span class="property-type">string</span>
            </dt>
            <dd>Model ID used to generate and parse the response.</dd>
            <dt class="optional">
                text
                <span class="property-type">object</span>
            </dt>
            <dd>Structured-output or text configuration used by the SDK parse helper.</dd>
            <dt class="optional">
                tools
                <span class="property-type">array</span>
            </dt>
            <dd>Tool definitions that the SDK can parse alongside the response.</dd>
        </dl>

        <h4 style="font-weight: bolder;"> ⋙ Get Model Response</h4>
        <p>Retrieves a model response with the given ID.</p>
        <dl class="message-properties">
            <h4>msg.payload Properties</h4>

            <dt>
                response_id
                <span class="property-type">string</span>
            </dt>
            <dd>The ID of the response to retrieve.</dd>

            <dt class="optional">
                include
                <span class="property-type">array</span>
            </dt>
            <dd>Additional output fields to include in the response.</dd>

            <dt class="optional">
                include_obfuscation
                <span class="property-type">boolean</span>
            </dt>
            <dd>Enable obfuscation payloads in streaming events.</dd>

            <dt class="optional">
                starting_after
                <span class="property-type">integer</span>
            </dt>
            <dd>Event sequence number after which to begin a streamed retrieval.</dd>

            <dt class="optional">
                stream
                <span class="property-type">boolean</span>
            </dt>
            <dd>When true, retrieve the response as a stream of events.</dd>
        </dl>

        <h4 style="font-weight: bolder;"> ⋙ Stream Model Response</h4>
        <p>
            Uses the SDK streaming helper to emit Responses stream events as they arrive and then returns the
            helper's final parsed response object when the stream completes.
        </p>
        <p>
            Use this helper for streamed create requests or streamed continuation by response id.
        </p>
        <p>
            When <code>response_id</code> is not provided, this helper uses the same request body shape as
            <code>Create Model Response</code>, including fields such as <code>include</code>,
            <code>prompt_cache_retention</code>, and <code>top_logprobs</code>.
        </p>
        <dl class="message-properties">
            <h4>msg.payload Properties</h4>
            <dt class="optional">
                response_id
                <span class="property-type">string</span>
            </dt>
            <dd>If provided, continue streaming an existing response by id.</dd>
            <dt class="optional">
                starting_after
                <span class="property-type">integer</span>
            </dt>
            <dd>When continuing by <code>response_id</code>, start after the given event sequence number.</dd>
            <dt class="optional">
                input
                <span class="property-type">string | array</span>
            </dt>
            <dd>
                Input used for a new streamed response when <code>response_id</code> is not provided.
                Array inputs may include <code>additional_tools</code> items with
                <code>role: "developer"</code>, <code>tools</code>, and optional <code>id</code>.
            </dd>
            <dt class="optional">
                model
                <span class="property-type">string</span>
            </dt>
            <dd>Model ID used for a new streamed response.</dd>
            <dt class="optional">
                text
                <span class="property-type">object</span>
            </dt>
            <dd>Text or structured-output configuration for the streamed response.</dd>
            <dt class="optional">
                tools
                <span class="property-type">array</span>
            </dt>
            <dd>Tool definitions to use while streaming the response.</dd>
        </dl>

        <h4 style="font-weight: bolder;"> ⋙ Delete Model Response</h4>
        <p>Deletes a model response with the given ID.</p>
        <dl class="message-properties">
            <h4>msg.payload Properties</h4>

            <dt>
                response_id
                <span class="property-type">string</span>
            </dt>
            <dd>The ID of the response to delete.</dd>
        </dl>

        <h4 style="font-weight: bolder;"> ⋙ Cancel Model Response</h4>
        <p>Cancels an in-progress model response.</p>
        <dl class="message-properties">
            <h4>msg.payload Properties</h4>

            <dt>
                response_id
                <span class="property-type">string</span>
            </dt>
            <dd>The ID of the response to cancel.</dd>
        </dl>

        <h4 style="font-weight: bolder;"> ⋙ Compact Model Response</h4>
        <p>Compacts prior conversation content to reduce context size while preserving continuity.</p>
        <dl class="message-properties">
            <h4>msg.payload Properties</h4>

            <dt>
                model
                <span class="property-type">string</span>
            </dt>
            <dd>Model ID used for compaction.</dd>

            <dt class="optional">
                input
                <span class="property-type">string | array</span>
            </dt>
            <dd>
                Optional input items used for compaction. Array inputs are passed to the SDK unchanged,
                including <code>additional_tools</code> items.
            </dd>

            <dt class="optional">
                instructions
                <span class="property-type">string</span>
            </dt>
            <dd>Optional system or developer instructions for compaction.</dd>

            <dt class="optional">
                previous_response_id
                <span class="property-type">string</span>
            </dt>
            <dd>Optional previous response id to continue compaction context.</dd>

            <dt class="optional">
                prompt_cache_retention
                <span class="property-type">string</span>
            </dt>
            <dd>
                Prompt cache retention policy for compaction requests. Set <code>24h</code> for extended
                prompt caching. For <code>gpt-5.5</code>, <code>gpt-5.5-pro</code>, and future models,
                only <code>24h</code> is supported. For older models that support both
                <code>in_memory</code> and <code>24h</code>, the default depends on the organization's
                data retention policy: organizations without ZDR enabled default to <code>24h</code>,
                and organizations with ZDR enabled default to <code>in_memory</code> when
                <code>prompt_cache_retention</code> is not specified.
            </dd>

            <dt class="optional">
                service_tier
                <span class="property-type">string | null</span>
            </dt>
            <dd>Service tier selection for compaction requests. Use <code>auto</code>, <code>default</code>, <code>flex</code>, <code>priority</code>, or <code>null</code>.</dd>
        </dl>

        <h4 style="font-weight: bolder;"> ⋙ List Input Items</h4>
        <p>Returns a list of input items for a given response.</p>
        <dl class="message-properties">
            <h4>msg.payload Properties</h4>

            <dt>
                response_id
                <span class="property-type">string</span>
            </dt>
            <dd>The ID of the response to retrieve input items for.</dd>

            <dt class="optional">
                after
                <span class="property-type">string</span>
            </dt>
            <dd>An item ID to list items after, used in pagination.</dd>

            <dt class="optional">
                before
                <span class="property-type">string</span>
            </dt>
            <dd>An item ID to list items before, used in pagination.</dd>

            <dt class="optional">
                limit
                <span class="property-type">integer</span>
            </dt>
            <dd>A limit on the number of objects to be returned.</dd>

            <dt class="optional">
                order
                <span class="property-type">string</span>
            </dt>
            <dd>The order to return the input items in. Default is <code>desc</code>.</dd>

            <dt class="optional">
                include
                <span class="property-type">array</span>
            </dt>
            <dd>Additional fields to include on the returned input items.</dd>

        </dl>

        <h4 style="font-weight: bolder;"> ⋙ Count Input Tokens</h4>
        <p>Counts input tokens before creating a model response.</p>
        <dl class="message-properties">
            <h4>msg.payload Properties</h4>

            <dt class="optional">
                model
                <span class="property-type">string</span>
            </dt>
            <dd>Model ID to use for token counting.</dd>

            <dt class="optional">
                input
                <span class="property-type">string | array</span>
            </dt>
            <dd>Input items to count.</dd>

            <dt class="optional">
                conversation
                <span class="property-type">string | object</span>
            </dt>
            <dd>Conversation context to include in counting.</dd>

            <dt class="optional">
                instructions
                <span class="property-type">string</span>
            </dt>
            <dd>System or developer instructions to include in counting.</dd>

            <dt class="optional">
                previous_response_id
                <span class="property-type">string</span>
            </dt>
            <dd>Previous response ID used to continue conversation context.</dd>

            <dt class="optional">
                parallel_tool_calls
                <span class="property-type">boolean</span>
            </dt>
            <dd>Whether tool calls may run in parallel for the modeled request.</dd>

            <dt class="optional">
                personality
                <span class="property-type">string</span>
            </dt>
            <dd>
                Model-owned style preset used for token counting. Supported named values include
                <code>friendly</code> and <code>pragmatic</code>; future SDK string values up to
                64 characters are also valid.
            </dd>

            <dt class="optional">
                reasoning
                <span class="property-type">object</span>
            </dt>
            <dd>Reasoning model configuration used for token accounting.</dd>

            <dt class="optional">
                text
                <span class="property-type">object</span>
            </dt>
            <dd>Text output configuration used when estimating token usage.</dd>

            <dt class="optional">
                tool_choice
                <span class="property-type">string | object</span>
            </dt>
            <dd>Tool selection mode used for token counting.</dd>

            <dt class="optional">
                tools
                <span class="property-type">array</span>
            </dt>
            <dd>Tool definitions used for token counting.</dd>

            <dt class="optional">
                truncation
                <span class="property-type">string</span>
            </dt>
            <dd>Truncation strategy for token counting context.
            </dd>

        </dl>

        <h4 style="font-weight: bolder;"> ⋙ Manage Model Response WebSocket</h4>
        <p>
            Opens, uses, and closes a persistent Responses websocket connection from a single
            <code>OpenAI API</code> node instance.
        </p>
        <p>
            Use the same node instance for all websocket actions. Set <code>msg.payload.action</code> to
            <code>connect</code>, <code>send</code>, or <code>close</code>.
        </p>
        <p>
            Incoming server events are emitted asynchronously from this node as new messages with the raw
            event object in <code>msg.payload</code>. Connection metadata is added under
            <code>msg.openai</code>.
        </p>
        <dl class="message-properties">
            <h4>msg.payload Properties</h4>

            <dt>
                action
                <span class="property-type">string</span>
            </dt>
            <dd>
                Required lifecycle action. Must be <code>connect</code>, <code>send</code>, or
                <code>close</code>.
            </dd>

            <dt>
                connection_id
                <span class="property-type">string</span>
            </dt>
            <dd>
                Stable identifier for the websocket connection owned by this node instance.
            </dd>

            <dt class="optional">
                event
                <span class="property-type">object</span>
            </dt>
            <dd>
                Required when <code>action</code> is <code>send</code>. Provide a Responses client event,
                currently <code>{ "type": "response.create", ... }</code>. For response-create events,
                use the same <code>prompt_cache_retention</code> guidance as
                <code>Create Model Response</code>.
            </dd>

            <dt class="optional">
                code
                <span class="property-type">integer</span>
            </dt>
            <dd>
                Optional websocket close code used when <code>action</code> is <code>close</code>.
                Defaults to <code>1000</code>.
            </dd>

            <dt class="optional">
                reason
                <span class="property-type">string</span>
            </dt>
            <dd>
                Optional websocket close reason used when <code>action</code> is <code>close</code>.
                Defaults to <code>OK</code>.
            </dd>

        </dl>
        <p>
            The websocket URL is derived from the configured <code>Service Host</code> API Base using the
            same auth contract as the rest of this node, including custom auth headers and query-string auth.
        </p>

    </details>
</section>