openai
Version:
The official TypeScript library for the OpenAI API
1,418 lines • 348 kB
TypeScript
import { APIResource } from "../../../core/resource.js";
import * as ResponsesAPI from "./responses.js";
import * as InputItemsAPI from "./input-items.js";
import { BetaResponseItemList, InputItemListParams, InputItems } from "./input-items.js";
import * as InputTokensAPI from "./input-tokens.js";
import { InputTokenCountParams, InputTokenCountResponse, InputTokens } from "./input-tokens.js";
import { APIPromise } from "../../../core/api-promise.js";
import { CursorPage } from "../../../core/pagination.js";
import { Stream } from "../../../core/streaming.js";
import { RequestOptions } from "../../../internal/request-options.js";
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;
/**
* The sta