openai/resources/beta/responses/responses.d.mts

The official TypeScript library for the OpenAI API

import { APIResource } from "../../../core/resource.mjs";
import * as ResponsesAPI from "./responses.mjs";
import * as InputItemsAPI from "./input-items.mjs";
import { BetaResponseItemList, InputItemListParams, InputItems } from "./input-items.mjs";
import * as InputTokensAPI from "./input-tokens.mjs";
import { InputTokenCountParams, InputTokenCountResponse, InputTokens } from "./input-tokens.mjs";
import { APIPromise } from "../../../core/api-promise.mjs";
import { CursorPage } from "../../../core/pagination.mjs";
import { Stream } from "../../../core/streaming.mjs";
import { RequestOptions } from "../../../internal/request-options.mjs";
export declare class Responses extends APIResource {
    inputItems: InputItemsAPI.InputItems;
    inputTokens: InputTokensAPI.InputTokens;
    /**
     * Creates a model response. Provide
     * [text](https://platform.openai.com/docs/guides/text) or
     * [image](https://platform.openai.com/docs/guides/images) inputs to generate
     * [text](https://platform.openai.com/docs/guides/text) or
     * [JSON](https://platform.openai.com/docs/guides/structured-outputs) outputs. Have
     * the model call your own
     * [custom code](https://platform.openai.com/docs/guides/function-calling) or use
     * built-in [tools](https://platform.openai.com/docs/guides/tools) like
     * [web search](https://platform.openai.com/docs/guides/tools-web-search) or
     * [file search](https://platform.openai.com/docs/guides/tools-file-search) to use
     * your own data as input for the model's response.
     *
     * @example
     * ```ts
     * const betaResponse = await client.beta.responses.create();
     * ```
     */
    create(params: ResponseCreateParamsNonStreaming, options?: RequestOptions): APIPromise<BetaResponse>;
    create(params: ResponseCreateParamsStreaming, options?: RequestOptions): APIPromise<Stream<BetaResponseStreamEvent>>;
    create(params: ResponseCreateParamsBase, options?: RequestOptions): APIPromise<Stream<BetaResponseStreamEvent> | BetaResponse>;
    /**
     * Retrieves a model response with the given ID.
     *
     * @example
     * ```ts
     * const betaResponse = await client.beta.responses.retrieve(
     *   'resp_677efb5139a88190b512bc3fef8e535d',
     * );
     * ```
     */
    retrieve(responseID: string, params?: ResponseRetrieveParamsNonStreaming, options?: RequestOptions): APIPromise<BetaResponse>;
    retrieve(responseID: string, params: ResponseRetrieveParamsStreaming, options?: RequestOptions): APIPromise<Stream<BetaResponseStreamEvent>>;
    retrieve(responseID: string, params?: ResponseRetrieveParamsBase | undefined, options?: RequestOptions): APIPromise<Stream<BetaResponseStreamEvent> | BetaResponse>;
    /**
     * Deletes a model response with the given ID.
     *
     * @example
     * ```ts
     * await client.beta.responses.delete(
     *   'resp_677efb5139a88190b512bc3fef8e535d',
     * );
     * ```
     */
    delete(responseID: string, params?: ResponseDeleteParams | null | undefined, options?: RequestOptions): APIPromise<void>;
    /**
     * Cancels a model response with the given ID. Only responses created with the
     * `background` parameter set to `true` can be cancelled.
     * [Learn more](https://platform.openai.com/docs/guides/background).
     *
     * @example
     * ```ts
     * const betaResponse = await client.beta.responses.cancel(
     *   'resp_677efb5139a88190b512bc3fef8e535d',
     * );
     * ```
     */
    cancel(responseID: string, params?: ResponseCancelParams | null | undefined, options?: RequestOptions): APIPromise<BetaResponse>;
    /**
     * Compact a conversation. Returns a compacted response object.
     *
     * Learn when and how to compact long-running conversations in the
     * [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window).
     * For ZDR-compatible compaction details, see
     * [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced).
     *
     * @example
     * ```ts
     * const betaCompactedResponse =
     *   await client.beta.responses.compact({
     *     model: 'gpt-5.6-sol',
     *   });
     * ```
     */
    compact(params: ResponseCompactParams, options?: RequestOptions): APIPromise<BetaCompactedResponse>;
}
export type BetaResponseItemsPage = CursorPage<BetaResponseItem>;
/**
 * Allows the assistant to create, delete, or update files using unified diffs.
 */
export interface BetaApplyPatchTool {
    /**
     * The type of the tool. Always `apply_patch`.
     */
    type: 'apply_patch';
    /**
     * The tool invocation context(s).
     */
    allowed_callers?: Array<'direct' | 'programmatic'> | null;
}
export interface BetaCompactedResponse {
    /**
     * The unique identifier for the compacted response.
     */
    id: string;
    /**
     * Unix timestamp (in seconds) when the compacted conversation was created.
     */
    created_at: number;
    /**
     * The object type. Always `response.compaction`.
     */
    object: 'response.compaction';
    /**
     * The compacted list of output items. This is a list of all user messages,
     * followed by a single compaction item.
     */
    output: Array<BetaResponseOutputItem>;
    /**
     * Token accounting for the compaction pass, including cached, reasoning, and total
     * tokens.
     */
    usage: BetaResponseUsage;
}
/**
 * A click action.
 */
export type BetaComputerAction = BetaComputerAction.Click | BetaComputerAction.DoubleClick | BetaComputerAction.Drag | BetaComputerAction.Keypress | BetaComputerAction.Move | BetaComputerAction.Screenshot | BetaComputerAction.Scroll | BetaComputerAction.Type | BetaComputerAction.Wait;
export declare namespace BetaComputerAction {
    /**
     * A click action.
     */
    interface Click {
        /**
         * Indicates which mouse button was pressed during the click. One of `left`,
         * `right`, `wheel`, `back`, or `forward`.
         */
        button: 'left' | 'right' | 'wheel' | 'back' | 'forward';
        /**
         * Specifies the event type. For a click action, this property is always `click`.
         */
        type: 'click';
        /**
         * The x-coordinate where the click occurred.
         */
        x: number;
        /**
         * The y-coordinate where the click occurred.
         */
        y: number;
        /**
         * The keys being held while clicking.
         */
        keys?: Array<string> | null;
    }
    /**
     * A double click action.
     */
    interface DoubleClick {
        /**
         * The keys being held while double-clicking.
         */
        keys: Array<string> | null;
        /**
         * Specifies the event type. For a double click action, this property is always set
         * to `double_click`.
         */
        type: 'double_click';
        /**
         * The x-coordinate where the double click occurred.
         */
        x: number;
        /**
         * The y-coordinate where the double click occurred.
         */
        y: number;
    }
    /**
     * A drag action.
     */
    interface Drag {
        /**
         * An array of coordinates representing the path of the drag action. Coordinates
         * will appear as an array of objects, eg
         *
         * ```
         * [
         *   { x: 100, y: 200 },
         *   { x: 200, y: 300 }
         * ]
         * ```
         */
        path: Array<Drag.Path>;
        /**
         * Specifies the event type. For a drag action, this property is always set to
         * `drag`.
         */
        type: 'drag';
        /**
         * The keys being held while dragging the mouse.
         */
        keys?: Array<string> | null;
    }
    namespace Drag {
        /**
         * An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.
         */
        interface Path {
            /**
             * The x-coordinate.
             */
            x: number;
            /**
             * The y-coordinate.
             */
            y: number;
        }
    }
    /**
     * A collection of keypresses the model would like to perform.
     */
    interface Keypress {
        /**
         * The combination of keys the model is requesting to be pressed. This is an array
         * of strings, each representing a key.
         */
        keys: Array<string>;
        /**
         * Specifies the event type. For a keypress action, this property is always set to
         * `keypress`.
         */
        type: 'keypress';
    }
    /**
     * A mouse move action.
     */
    interface Move {
        /**
         * Specifies the event type. For a move action, this property is always set to
         * `move`.
         */
        type: 'move';
        /**
         * The x-coordinate to move to.
         */
        x: number;
        /**
         * The y-coordinate to move to.
         */
        y: number;
        /**
         * The keys being held while moving the mouse.
         */
        keys?: Array<string> | null;
    }
    /**
     * A screenshot action.
     */
    interface Screenshot {
        /**
         * Specifies the event type. For a screenshot action, this property is always set
         * to `screenshot`.
         */
        type: 'screenshot';
    }
    /**
     * A scroll action.
     */
    interface Scroll {
        /**
         * The horizontal scroll distance.
         */
        scroll_x: number;
        /**
         * The vertical scroll distance.
         */
        scroll_y: number;
        /**
         * Specifies the event type. For a scroll action, this property is always set to
         * `scroll`.
         */
        type: 'scroll';
        /**
         * The x-coordinate where the scroll occurred.
         */
        x: number;
        /**
         * The y-coordinate where the scroll occurred.
         */
        y: number;
        /**
         * The keys being held while scrolling.
         */
        keys?: Array<string> | null;
    }
    /**
     * An action to type in text.
     */
    interface Type {
        /**
         * The text to type.
         */
        text: string;
        /**
         * Specifies the event type. For a type action, this property is always set to
         * `type`.
         */
        type: 'type';
    }
    /**
     * A wait action.
     */
    interface Wait {
        /**
         * Specifies the event type. For a wait action, this property is always set to
         * `wait`.
         */
        type: 'wait';
    }
}
/**
 * Flattened batched actions for `computer_use`. Each action includes an `type`
 * discriminator and action-specific fields.
 */
export type BetaComputerActionList = Array<BetaComputerAction>;
/**
 * A tool that controls a virtual computer. Learn more about the
 * [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).
 */
export interface BetaComputerTool {
    /**
     * The type of the computer tool. Always `computer`.
     */
    type: 'computer';
}
/**
 * A tool that controls a virtual computer. Learn more about the
 * [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).
 */
export interface BetaComputerUsePreviewTool {
    /**
     * The height of the computer display.
     */
    display_height: number;
    /**
     * The width of the computer display.
     */
    display_width: number;
    /**
     * The type of computer environment to control.
     */
    environment: 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser';
    /**
     * The type of the computer use tool. Always `computer_use_preview`.
     */
    type: 'computer_use_preview';
}
export interface BetaContainerAuto {
    /**
     * Automatically creates a container for this request
     */
    type: 'container_auto';
    /**
     * An optional list of uploaded files to make available to your code.
     */
    file_ids?: Array<string>;
    /**
     * The memory limit for the container.
     */
    memory_limit?: '1g' | '4g' | '16g' | '64g' | null;
    /**
     * Network access policy for the container.
     */
    network_policy?: BetaContainerNetworkPolicyDisabled | BetaContainerNetworkPolicyAllowlist;
    /**
     * An optional list of skills referenced by id or inline data.
     */
    skills?: Array<BetaSkillReference | BetaInlineSkill>;
}
export interface BetaContainerNetworkPolicyAllowlist {
    /**
     * A list of allowed domains when type is `allowlist`.
     */
    allowed_domains: Array<string>;
    /**
     * Allow outbound network access only to specified domains. Always `allowlist`.
     */
    type: 'allowlist';
    /**
     * Optional domain-scoped secrets for allowlisted domains.
     */
    domain_secrets?: Array<BetaContainerNetworkPolicyDomainSecret>;
}
export interface BetaContainerNetworkPolicyDisabled {
    /**
     * Disable outbound network access. Always `disabled`.
     */
    type: 'disabled';
}
export interface BetaContainerNetworkPolicyDomainSecret {
    /**
     * The domain associated with the secret.
     */
    domain: string;
    /**
     * The name of the secret to inject for the domain.
     */
    name: string;
    /**
     * The secret value to inject for the domain.
     */
    value: string;
}
export interface BetaContainerReference {
    /**
     * The ID of the referenced container.
     */
    container_id: string;
    /**
     * References a container created with the /v1/containers endpoint
     */
    type: 'container_reference';
}
/**
 * A custom tool that processes input using a specified format. Learn more about
 * [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
 */
export interface BetaCustomTool {
    /**
     * The name of the custom tool, used to identify it in tool calls.
     */
    name: string;
    /**
     * The type of the custom tool. Always `custom`.
     */
    type: 'custom';
    /**
     * The tool invocation context(s).
     */
    allowed_callers?: Array<'direct' | 'programmatic'> | null;
    /**
     * Whether this tool should be deferred and discovered via tool search.
     */
    defer_loading?: boolean;
    /**
     * Optional description of the custom tool, used to provide more context.
     */
    description?: string;
    /**
     * The input format for the custom tool. Default is unconstrained text.
     */
    format?: BetaCustomTool.Text | BetaCustomTool.Grammar;
}
export declare namespace BetaCustomTool {
    /**
     * Unconstrained free-form text.
     */
    interface Text {
        /**
         * Unconstrained text format. Always `text`.
         */
        type: 'text';
    }
    /**
     * A grammar defined by the user.
     */
    interface Grammar {
        /**
         * The grammar definition.
         */
        definition: string;
        /**
         * The syntax of the grammar definition. One of `lark` or `regex`.
         */
        syntax: 'lark' | 'regex';
        /**
         * Grammar format. Always `grammar`.
         */
        type: 'grammar';
    }
}
/**
 * A message input to the model with a role indicating instruction following
 * hierarchy. Instructions given with the `developer` or `system` role take
 * precedence over instructions given with the `user` role. Messages with the
 * `assistant` role are presumed to have been generated by the model in previous
 * interactions.
 */
export interface BetaEasyInputMessage {
    /**
     * Text, image, or audio input to the model, used to generate a response. Can also
     * contain previous assistant responses.
     */
    content: string | BetaResponseInputMessageContentList;
    /**
     * The role of the message input. One of `user`, `assistant`, `system`, or
     * `developer`.
     */
    role: 'user' | 'assistant' | 'system' | 'developer';
    /**
     * Labels an `assistant` message as intermediate commentary (`commentary`) or the
     * final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when
     * sending follow-up requests, preserve and resend phase on all assistant messages
     * — dropping it can degrade performance. Not used for user messages.
     */
    phase?: 'commentary' | 'final_answer' | null;
    /**
     * The type of the message input. Always `message`.
     */
    type?: 'message';
}
/**
 * A tool that searches for relevant content from uploaded files. Learn more about
 * the
 * [file search tool](https://platform.openai.com/docs/guides/tools-file-search).
 */
export interface BetaFileSearchTool {
    /**
     * The type of the file search tool. Always `file_search`.
     */
    type: 'file_search';
    /**
     * The IDs of the vector stores to search.
     */
    vector_store_ids: Array<string>;
    /**
     * A filter to apply.
     */
    filters?: BetaFileSearchTool.ComparisonFilter | BetaFileSearchTool.CompoundFilter | null;
    /**
     * The maximum number of results to return. This number should be between 1 and 50
     * inclusive.
     */
    max_num_results?: number;
    /**
     * Ranking options for search.
     */
    ranking_options?: BetaFileSearchTool.RankingOptions;
}
export declare namespace BetaFileSearchTool {
    /**
     * A filter used to compare a specified attribute key to a given value using a
     * defined comparison operation.
     */
    interface ComparisonFilter {
        /**
         * The key to compare against the value.
         */
        key: string;
        /**
         * Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`,
         * `nin`.
         *
         * - `eq`: equals
         * - `ne`: not equal
         * - `gt`: greater than
         * - `gte`: greater than or equal
         * - `lt`: less than
         * - `lte`: less than or equal
         * - `in`: in
         * - `nin`: not in
         */
        type: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin';
        /**
         * The value to compare against the attribute key; supports string, number, or
         * boolean types.
         */
        value: string | number | boolean | Array<string | number>;
    }
    /**
     * Combine multiple filters using `and` or `or`.
     */
    interface CompoundFilter {
        /**
         * Array of filters to combine. Items can be `ComparisonFilter` or
         * `CompoundFilter`.
         */
        filters: Array<CompoundFilter.ComparisonFilter | unknown>;
        /**
         * Type of operation: `and` or `or`.
         */
        type: 'and' | 'or';
    }
    namespace CompoundFilter {
        /**
         * A filter used to compare a specified attribute key to a given value using a
         * defined comparison operation.
         */
        interface ComparisonFilter {
            /**
             * The key to compare against the value.
             */
            key: string;
            /**
             * Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`,
             * `nin`.
             *
             * - `eq`: equals
             * - `ne`: not equal
             * - `gt`: greater than
             * - `gte`: greater than or equal
             * - `lt`: less than
             * - `lte`: less than or equal
             * - `in`: in
             * - `nin`: not in
             */
            type: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin';
            /**
             * The value to compare against the attribute key; supports string, number, or
             * boolean types.
             */
            value: string | number | boolean | Array<string | number>;
        }
    }
    /**
     * Ranking options for search.
     */
    interface RankingOptions {
        /**
         * Weights that control how reciprocal rank fusion balances semantic embedding
         * matches versus sparse keyword matches when hybrid search is enabled.
         */
        hybrid_search?: RankingOptions.HybridSearch;
        /**
         * The ranker to use for the file search.
         */
        ranker?: 'auto' | 'default-2024-11-15';
        /**
         * The score threshold for the file search, a number between 0 and 1. Numbers
         * closer to 1 will attempt to return only the most relevant results, but may
         * return fewer results.
         */
        score_threshold?: number;
    }
    namespace RankingOptions {
        /**
         * Weights that control how reciprocal rank fusion balances semantic embedding
         * matches versus sparse keyword matches when hybrid search is enabled.
         */
        interface HybridSearch {
            /**
             * The weight of the embedding in the reciprocal ranking fusion.
             */
            embedding_weight: number;
            /**
             * The weight of the text in the reciprocal ranking fusion.
             */
            text_weight: number;
        }
    }
}
/**
 * A tool that allows the model to execute shell commands.
 */
export interface BetaFunctionShellTool {
    /**
     * The type of the shell tool. Always `shell`.
     */
    type: 'shell';
    /**
     * The tool invocation context(s).
     */
    allowed_callers?: Array<'direct' | 'programmatic'> | null;
    environment?: BetaContainerAuto | BetaLocalEnvironment | BetaContainerReference | null;
}
/**
 * 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).
 */
export interface BetaFunctionTool {
    /**
     * The name of the function to call.
     */
    name: string;
    /**
     * A JSON schema object describing the parameters of the function.
     */
    parameters: {
        [key: string]: unknown;
    } | null;
    /**
     * Whether strict parameter validation is enforced for this function tool.
     */
    strict: boolean | null;
    /**
     * The type of the function tool. Always `function`.
     */
    type: 'function';
    /**
     * The tool invocation context(s).
     */
    allowed_callers?: Array<'direct' | 'programmatic'> | null;
    /**
     * Whether this function is deferred and loaded via tool search.
     */
    defer_loading?: boolean;
    /**
     * A description of the function. Used by the model to determine whether or not to
     * call the function.
     */
    description?: string | null;
    /**
     * A JSON schema object describing the JSON value encoded in string outputs for
     * this function.
     */
    output_schema?: {
        [key: string]: unknown;
    } | null;
}
export interface BetaInlineSkill {
    /**
     * The description of the skill.
     */
    description: string;
    /**
     * The name of the skill.
     */
    name: string;
    /**
     * Inline skill payload
     */
    source: BetaInlineSkillSource;
    /**
     * Defines an inline skill for this request.
     */
    type: 'inline';
}
/**
 * Inline skill payload
 */
export interface BetaInlineSkillSource {
    /**
     * Base64-encoded skill zip bundle.
     */
    data: string;
    /**
     * The media type of the inline skill payload. Must be `application/zip`.
     */
    media_type: 'application/zip';
    /**
     * The type of the inline skill source. Must be `base64`.
     */
    type: 'base64';
}
export interface BetaLocalEnvironment {
    /**
     * Use a local computer environment.
     */
    type: 'local';
    /**
     * An optional list of skills.
     */
    skills?: Array<BetaLocalSkill>;
}
export interface BetaLocalSkill {
    /**
     * The description of the skill.
     */
    description: string;
    /**
     * The name of the skill.
     */
    name: string;
    /**
     * The path to the directory containing the skill.
     */
    path: string;
}
/**
 * Groups function/custom tools under a shared namespace.
 */
export interface BetaNamespaceTool {
    /**
     * A description of the namespace shown to the model.
     */
    description: string;
    /**
     * The namespace name used in tool calls (for example, `crm`).
     */
    name: string;
    /**
     * The function/custom tools available inside this namespace.
     */
    tools: Array<BetaNamespaceTool.Function | BetaCustomTool>;
    /**
     * The type of the tool. Always `namespace`.
     */
    type: 'namespace';
}
export declare namespace BetaNamespaceTool {
    interface Function {
        name: string;
        type: 'function';
        /**
         * The tool invocation context(s).
         */
        allowed_callers?: Array<'direct' | 'programmatic'> | null;
        /**
         * Whether this function should be deferred and discovered via tool search.
         */
        defer_loading?: boolean;
        description?: string | null;
        /**
         * A JSON Schema describing the JSON value encoded in string outputs for this
         * function tool. This does not describe content-array outputs.
         */
        output_schema?: {
            [key: string]: unknown;
        } | null;
        parameters?: unknown | null;
        /**
         * Whether to enforce strict parameter validation. If omitted, Responses attempts
         * to use strict validation when the schema is compatible, and falls back to
         * non-strict validation otherwise.
         */
        strict?: boolean | null;
    }
}
export interface BetaResponse {
    /**
     * Unique identifier for this Response.
     */
    id: string;
    /**
     * Unix timestamp (in seconds) of when this Response was created.
     */
    created_at: number;
    /**
     * An error object returned when the model fails to generate a Response.
     */
    error: BetaResponseError | null;
    /**
     * Details about why the response is incomplete.
     */
    incomplete_details: BetaResponse.IncompleteDetails | null;
    /**
     * A system (or developer) message inserted into the model's context.
     *
     * When using along with `previous_response_id`, the instructions from a previous
     * response will not be carried over to the next response. This makes it simple to
     * swap out system (or developer) messages in new responses.
     */
    instructions: string | Array<BetaResponseInputItem> | null;
    /**
     * Set of 16 key-value pairs that can be attached to an object. This can be useful
     * for storing additional information about the object in a structured format, and
     * querying for objects via API or the dashboard.
     *
     * Keys are strings with a maximum length of 64 characters. Values are strings with
     * a maximum length of 512 characters.
     */
    metadata: {
        [key: string]: string;
    } | null;
    /**
     * Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a
     * wide range of models with different capabilities, performance characteristics,
     * and price points. Refer to the
     * [model guide](https://platform.openai.com/docs/models) to browse and compare
     * available models.
     */
    model: 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.4-mini-2026-03-17' | 'gpt-5.4-nano-2026-03-17' | 'gpt-5.3-chat-latest' | 'gpt-5.2' | 'gpt-5.2-2025-12-11' | 'gpt-5.2-chat-latest' | 'gpt-5.2-pro' | 'gpt-5.2-pro-2025-12-11' | 'gpt-5.1' | 'gpt-5.1-2025-11-13' | 'gpt-5.1-codex' | 'gpt-5.1-mini' | 'gpt-5.1-chat-latest' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5-2025-08-07' | 'gpt-5-mini-2025-08-07' | 'gpt-5-nano-2025-08-07' | 'gpt-5-chat-latest' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'gpt-4.1-nano-2025-04-14' | 'o4-mini' | 'o4-mini-2025-04-16' | 'o3' | 'o3-2025-04-16' | 'o3-mini' | 'o3-mini-2025-01-31' | 'o1' | 'o1-2024-12-17' | 'o1-preview' | 'o1-preview-2024-09-12' | 'o1-mini' | 'o1-mini-2024-09-12' | 'gpt-4o' | 'gpt-4o-2024-11-20' | 'gpt-4o-2024-08-06' | 'gpt-4o-2024-05-13' | 'gpt-4o-audio-preview' | 'gpt-4o-audio-preview-2024-10-01' | 'gpt-4o-audio-preview-2024-12-17' | 'gpt-4o-audio-preview-2025-06-03' | 'gpt-4o-mini-audio-preview' | 'gpt-4o-mini-audio-preview-2024-12-17' | 'gpt-4o-search-preview' | 'gpt-4o-mini-search-preview' | 'gpt-4o-search-preview-2025-03-11' | 'gpt-4o-mini-search-preview-2025-03-11' | 'chatgpt-4o-latest' | 'codex-mini-latest' | 'gpt-4o-mini' | 'gpt-4o-mini-2024-07-18' | 'gpt-4-turbo' | 'gpt-4-turbo-2024-04-09' | 'gpt-4-0125-preview' | 'gpt-4-turbo-preview' | 'gpt-4-1106-preview' | 'gpt-4-vision-preview' | 'gpt-4' | 'gpt-4-0314' | 'gpt-4-0613' | 'gpt-4-32k' | 'gpt-4-32k-0314' | 'gpt-4-32k-0613' | 'gpt-3.5-turbo' | 'gpt-3.5-turbo-16k' | 'gpt-3.5-turbo-0301' | 'gpt-3.5-turbo-0613' | 'gpt-3.5-turbo-1106' | 'gpt-3.5-turbo-0125' | 'gpt-3.5-turbo-16k-0613' | 'o1-pro' | 'o1-pro-2025-03-19' | 'o3-pro' | 'o3-pro-2025-06-10' | 'o3-deep-research' | 'o3-deep-research-2025-06-26' | 'o4-mini-deep-research' | 'o4-mini-deep-research-2025-06-26' | 'computer-use-preview' | 'computer-use-preview-2025-03-11' | 'gpt-5-codex' | 'gpt-5-pro' | 'gpt-5-pro-2025-10-06' | 'gpt-5.1-codex-max' | (string & {});
    /**
     * The object type of this resource - always set to `response`.
     */
    object: 'response';
    /**
     * An array of content items generated by the model.
     *
     * - The length and order of items in the `output` array is dependent on the
     *   model's response.
     * - Rather than accessing the first item in the `output` array and assuming it's
     *   an `assistant` message with the content generated by the model, you might
     *   consider using the `output_text` property where supported in SDKs.
     */
    output: Array<BetaResponseOutputItem>;
    /**
     * Whether to allow the model to run tool calls in parallel.
     */
    parallel_tool_calls: boolean;
    /**
     * What sampling temperature to use, between 0 and 2. Higher values like 0.8 will
     * make the output more random, while lower values like 0.2 will make it more
     * focused and deterministic. We generally recommend altering this or `top_p` but
     * not both.
     */
    temperature: number | null;
    /**
     * How the model should select which tool (or tools) to use when generating a
     * response. See the `tools` parameter to see how to specify which tools the model
     * can call.
     */
    tool_choice: BetaToolChoiceOptions | BetaToolChoiceAllowed | BetaToolChoiceTypes | BetaToolChoiceFunction | BetaToolChoiceMcp | BetaToolChoiceCustom | BetaResponse.BetaSpecificProgrammaticToolCallingParam | BetaToolChoiceApplyPatch | BetaToolChoiceShell;
    /**
     * An array of tools the model may call while generating a response. You can
     * specify which tool to use by setting the `tool_choice` parameter.
     *
     * We support the following categories of tools:
     *
     * - **Built-in tools**: Tools that are provided by OpenAI that extend the model's
     *   capabilities, like
     *   [web search](https://platform.openai.com/docs/guides/tools-web-search) or
     *   [file search](https://platform.openai.com/docs/guides/tools-file-search).
     *   Learn more about
     *   [built-in tools](https://platform.openai.com/docs/guides/tools).
     * - **MCP Tools**: Integrations with third-party systems via custom MCP servers or
     *   predefined connectors such as Google Drive and SharePoint. Learn more about
     *   [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp).
     * - **Function calls (custom tools)**: Functions that are defined by you, enabling
     *   the model to call your own code with strongly typed arguments and outputs.
     *   Learn more about
     *   [function calling](https://platform.openai.com/docs/guides/function-calling).
     *   You can also use custom tools to call your own code.
     */
    tools: Array<BetaTool>;
    /**
     * An alternative to sampling with temperature, called nucleus sampling, where the
     * model considers the results of the tokens with top_p probability mass. So 0.1
     * means only the tokens comprising the top 10% probability mass are considered.
     *
     * We generally recommend altering this or `temperature` but not both.
     */
    top_p: number | null;
    /**
     * Whether to run the model response in the background.
     * [Learn more](https://platform.openai.com/docs/guides/background).
     */
    background?: boolean | null;
    /**
     * Unix timestamp (in seconds) of when this Response was completed. Only present
     * when the status is `completed`.
     */
    completed_at?: number | null;
    /**
     * The conversation that this response belonged to. Input items and output items
     * from this response were automatically added to this conversation.
     */
    conversation?: BetaResponse.Conversation | null;
    /**
     * An upper bound for the number of tokens that can be generated for a response,
     * including visible output tokens and
     * [reasoning tokens](https://platform.openai.com/docs/guides/reasoning).
     */
    max_output_tokens?: number | null;
    /**
     * The maximum number of total calls to built-in tools that can be processed in a
     * response. This maximum number applies across all built-in tool calls, not per
     * individual tool. Any further attempts to call a tool by the model will be
     * ignored.
     */
    max_tool_calls?: number | null;
    /**
     * Moderation results for the response input and output, if moderated completions
     * were requested.
     */
    moderation?: BetaResponse.Moderation | null;
    /**
     * The unique ID of the previous response to the model. Use this to create
     * multi-turn conversations. Learn more about
     * [conversation state](https://platform.openai.com/docs/guides/conversation-state).
     * Cannot be used in conjunction with `conversation`.
     */
    previous_response_id?: string | null;
    /**
     * Reference to a prompt template and its variables.
     * [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
     */
    prompt?: BetaResponsePrompt | null;
    /**
     * Used by OpenAI to cache responses for similar requests to optimize your cache
     * hit rates. Replaces the `user` field.
     * [Learn more](https://platform.openai.com/docs/guides/prompt-caching).
     */
    prompt_cache_key?: string | null;
    /**
     * The prompt-caching options that were applied to the response. Supported for
     * `gpt-5.6` and later models.
     */
    prompt_cache_options?: BetaResponse.PromptCacheOptions;
    /**
     * @deprecated Deprecated. Use `prompt_cache_options.ttl` instead.
     *
     * The retention policy for the prompt cache. Set to `24h` to enable extended
     * prompt caching, which keeps cached prefixes active for longer, up to a maximum
     * of 24 hours.
     * [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention).
     * This field expresses a maximum retention policy, while
     * `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two fields
     * are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future
     * models, only `24h` is supported.
     *
     * For older models that support both `in_memory` and `24h`, the default depends on
     * your organization's data retention policy:
     *
     * - Organizations without ZDR enabled default to `24h`.
     * - Organizations with ZDR enabled default to `in_memory` when
     *   `prompt_cache_retention` is not specified.
     */
    prompt_cache_retention?: 'in_memory' | '24h' | null;
    /**
     * **gpt-5 and o-series models only**
     *
     * Configuration options for
     * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
     */
    reasoning?: BetaResponse.Reasoning | null;
    /**
     * A stable identifier used to help detect users of your application that may be
     * violating OpenAI's usage policies. The IDs should be a string that uniquely
     * identifies each user, with a maximum length of 64 characters. We recommend
     * hashing their username or email address, in order to avoid sending us any
     * identifying information.
     * [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers).
     */
    safety_identifier?: string | null;
    /**
     * Specifies the processing type used for serving the request.
     *
     * - If set to 'auto', then the request will be processed with the service tier
     *   configured in the Project settings. Unless otherwise configured, the Project
     *   will use 'default'.
     * - If set to 'default', then the request will be processed with the standard
     *   pricing and performance for the selected model.
     * - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or
     *   '[priority](https://openai.com/api-priority-processing/)', then the request
     *   will be processed with the corresponding service tier.
     * - When not set, the default behavior is 'auto'.
     *
     * When the `service_tier` parameter is set, the response body will include the
     * `service_tier` value based on the processing mode actually used to serve the
     * request. This response value may be different from the value set in the
     * parameter.
     */
    service_tier?: 'auto' | 'default' | 'flex' | 'scale' | 'priority' | null;
    /**
     * The status of the response generation. One of `completed`, `failed`,
     * `in_progress`, `cancelled`, `queued`, or `incomplete`.
     */
    status?: BetaResponseStatus;
    /**
     * Configuration options for a text response from the model. Can be plain text or
     * structured JSON data. Learn more:
     *
     * - [Text inputs and outputs](https://platform.openai.com/docs/guides/text)
     * - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs)
     */
    text?: BetaResponseTextConfig;
    /**
     * An integer between 0 and 20 specifying the maximum number of most likely tokens
     * to return at each token position, each with an associated log probability. In
     * some cases, the number of returned tokens may be fewer than requested.
     */
    top_logprobs?: number | null;
    /**
     * The truncation strategy to use for the model response.
     *
     * - `auto`: If the input to this Response exceeds the model's context window size,
     *   the model will truncate the response to fit the context window by dropping
     *   items from the beginning of the conversation.
     * - `disabled` (default): If the input size will exceed the context window size
     *   for a model, the request will fail with a 400 error.
     */
    truncation?: 'auto' | 'disabled' | null;
    /**
     * Represents token usage details including input tokens, output tokens, a
     * breakdown of output tokens, and the total tokens used.
     */
    usage?: BetaResponseUsage;
    /**
     * @deprecated This field is being replaced by `safety_identifier` and
     * `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching
     * optimizations. A stable identifier for your end-users. Used to boost cache hit
     * rates by better bucketing similar requests and to help OpenAI detect and prevent
     * abuse.
     * [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers).
     */
    user?: string;
}
export declare namespace BetaResponse {
    /**
     * Details about why the response is incomplete.
     */
    interface IncompleteDetails {
        /**
         * The reason why the response is incomplete.
         */
        reason?: 'max_output_tokens' | 'content_filter';
    }
    interface BetaSpecificProgrammaticToolCallingParam {
        /**
         * The tool to call. Always `programmatic_tool_calling`.
         */
        type: 'programmatic_tool_calling';
    }
    /**
     * The conversation that this response belonged to. Input items and output items
     * from this response were automatically added to this conversation.
     */
    interface Conversation {
        /**
         * The unique ID of the conversation that this response was associated with.
         */
        id: string;
    }
    /**
     * Moderation results for the response input and output, if moderated completions
     * were requested.
     */
    interface Moderation {
        /**
         * Moderation for the response input.
         */
        input: Moderation.ModerationResult | Moderation.Error;
        /**
         * Moderation for the response output.
         */
        output: Moderation.ModerationResult | Moderation.Error;
    }
    namespace Moderation {
        /**
         * A moderation result produced for the response input or output.
         */
        interface ModerationResult {
            /**
             * A dictionary of moderation categories to booleans, True if the input is flagged
             * under this category.
             */
            categories: {
                [key: string]: boolean;
            };
            /**
             * Which modalities of input are reflected by the score for each category.
             */
            category_applied_input_types: {
                [key: string]: Array<'text' | 'image'>;
            };
            /**
             * A dictionary of moderation categories to scores.
             */
            category_scores: {
                [key: string]: number;
            };
            /**
             * A boolean indicating whether the content was flagged by any category.
             */
            flagged: boolean;
            /**
             * The moderation model that produced this result.
             */
            model: string;
            /**
             * The object type, which was always `moderation_result` for successful moderation
             * results.
             */
            type: 'moderation_result';
        }
        /**
         * An error produced while attempting moderation for the response input or output.
         */
        interface Error {
            /**
             * The error code.
             */
            code: string;
            /**
             * The error message.
             */
            message: string;
            /**
             * The object type, which was always `error` for moderation failures.
             */
            type: 'error';
        }
        /**
         * A moderation result produced for the response input or output.
         */
        interface ModerationResult {
            /**
             * A dictionary of moderation categories to booleans, True if the input is flagged
             * under this category.
             */
            categories: {
                [key: string]: boolean;
            };
            /**
             * Which modalities of input are reflected by the score for each category.
             */
            category_applied_input_types: {
                [key: string]: Array<'text' | 'image'>;
            };
            /**
             * A dictionary of moderation categories to scores.
             */
            category_scores: {
                [key: string]: number;
            };
            /**
             * A boolean indicating whether the content was flagged by any category.
             */
            flagged: boolean;
            /**
             * The moderation model that produced this result.
             */
            model: string;
            /**
             * The object type, which was always `moderation_result` for successful moderation
             * results.
             */
            type: 'moderation_result';
        }
        /**
         * An error produced while attempting moderation for the response input or output.
         */
        interface Error {
            /**
             * The error code.
             */
            code: string;
            /**
             * The error message.
             */
            message: string;
            /**
             * The object type, which was always `error` for moderation failures.
             */
            type: 'error';
        }
    }
    /**
     * The prompt-caching options that were applied to the response. Supported for
     * `gpt-5.6` and later models.
     */
    interface PromptCacheOptions {
        /**
         * Whether implicit prompt-cache breakpoints were enabled.
         */
        mode: 'implicit' | 'explicit';
        /**
         * The minimum lifetime applied to each cache breakpoint.
         */
        ttl: '30m';
    }
    /**
     * **gpt-5 and o-series models only**
     *
     * Configuration options for
     * [reasoning models](https://platform.openai.com/docs/guides/reasoning).
     */
    interface Reasoning {
        /**
         * Controls which reasoning items are rendered back to the model on later turns. If
         * omitted or set to `auto`, the model determines the context mode. The `gpt-5.6`
         * model family defaults to `all_turns`; earlier models default to `current_turn`.
         *
         * When returned on a response, this is the effective reasoning context mode used
         * for the response.
         */
        context?: 'auto' | 'current_turn' | 'all_turns' | null;
        /**
         * Constrains effort on reasoning for reasoning models. Currently supported values
         * are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Reducing
         * reasoning effort can result in faster responses and fewer tokens used on
         * reasoning in a response. Not all reasoning models support every value. See the
         * [reasoning guide](https://platform.openai.com/docs/guides/reasoning) for
         * model-specific support.
         */
        effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null;
        /**
         * @deprecated **Deprecated:** use `summary` instead.
         *
         * A summary of the reasoning performed by the model. This can be useful for
         * debugging and understanding the model's reasoning process. One of `auto`,
         * `concise`, or `detailed`.
         */
        generate_summary?: 'auto' | 'concise' | 'detailed' | null;
        /**
         * Controls the reasoning execution mode for the request.
         *
         * When returned on a response, this is the effective execution mode.
         */
        mode?: (string & {}) | 'standard' | 'pro';
        /**
         * A summary of the reasoning performed by the model. This can be useful for
         * debugging and understanding the model's reasoning process. One of `auto`,
         * `concise`, or `detailed`.
         *
         * `concise` is supported for `computer-use-preview` models and all reasoning
         * models after `gpt-5`.
         */
        summary?: 'auto' | 'concise' | 'detailed' | null;
    }
}
/**
 * A tool call that applies file diffs by creating, deleting, or updating files.
 */
export interface BetaResponseApplyPatchToolCall {
    /**
     * The unique ID of the apply patch tool call. Populated when this item is returned
     * via API.
     */
    id: string;
    /**
     * The unique ID of the apply patch tool call generated by the model.
     */
    call_id: string;
    /**
     * One of the create_file, delete_file, or update_file operations applied via
     * apply_patch.
     */
    operation: BetaResponseApplyPatchToolCall.CreateFile | BetaResponseApplyPatchToolCall.DeleteFile | BetaResponseApplyPatchToolCall.UpdateFile;
    /**
     * The status of the apply patch tool call. One of `in_progress` or `completed`.
     */
    status: 'in_progress' | 'completed';
    /**
     * The type of the item. Always `apply_patch_call`.
     */
    type: 'apply_patch_call';
    /**
     * The agent that produced this item.
     */
    agent?: BetaResponseApplyPatchToolCall.Agent;
    /**
     * The execution context that produced this tool call.
     */
    caller?: BetaResponseApplyPatchToolCall.Direct | BetaResponseApplyPatchToolCall.Program | null;
    /**
     * The ID of the entity that created this tool call.
     */
    created_by?: string;
}
export declare namespace BetaResponseApplyPatchToolCall {
    /**
     * Instruction describing how to create a file via the apply_patch tool.
     */
    interface CreateFile {
        /**
         * Diff to apply.
         */
        diff: string;
        /**
         * Path of the file to create.
         */
        path: string;
        /**
         * Create a new file with the provided diff.
         */
        type: 'create_file';
    }
    /**
     * Instruction describing how to delete a file via the apply_patch tool.
     */
    interface DeleteFile {
        /**
         * Path of the file to delete.
         */
        path: string;
        /**
         * Delete the specified file.
         */
        type: 'delete_file';
    }
    /**
     * Instruction describing how to update a file via the apply_patch tool.
     */
    interface UpdateFile {
        /**
         * Diff to apply.
         */
        diff: string;
        /**
         * Path of the file to update.
         */
        path: string;
        /**
         * Update an existing file with the provided diff.
         */
        type: 'update_file';
    }
    /**
     * The agent that produced this item.
     */
    interface Agent {
        /**
         * The canonical name of the agent that produced this item.
         */
        agent_name: string;
    }
    interface Direct {
        type: 'direct';
    }
    interface Program {
        /**
         * The call ID of the program item that produced this tool call.
         */
        caller_id: string;
        type: 'program';
    }
}
/**
 * The output emitted by an apply patch tool call.
 */
export interface BetaResponseApplyPatchToolCallOutput {
    /**
     * The unique ID of the apply patch tool call output. Populated when this item is
     * returned via API.
     */
    id: string;
    /**
     * The unique ID of the apply patch tool call generated by the model.
     */
    call_id: string;
    /**