OpenAiSchema

The OpenAiSchema module defines the request, response, streaming, and embedding schemas used by the handwritten OpenAI client. These schemas are the transport boundary for JSON sent to and decoded from the Responses and embeddings endpoints.

35 exports Added in v4.0.0 Source

Models

Annotation type

Added in v4.0.0 Source

Citation or file-path annotation attached to output text content.

Details

Accepted annotation variants are file_citation, url_citation, container_file_citation, and file_path.

Signature

type Annotation = typeof Annotation.Type;

CreateEmbeddingRequest type

Added in v4.0.0 Source

Request payload sent to the OpenAI embeddings endpoint.

Signature

type CreateEmbeddingRequest = typeof CreateEmbeddingRequest.Type;

CreateEmbeddingResponse type

Added in v4.0.0 Source

Successful response payload returned by the OpenAI embeddings endpoint.

When to use

Use when typing successful OpenAI embeddings responses.

Details

Contains embedding items, the model name, optional list marker, and optional token usage counts.

Signature

type CreateEmbeddingResponse = typeof CreateEmbeddingResponse.Type;

Embedding type

Added in v4.0.0 Source

One embedding item returned by the OpenAI embeddings API.

Details

Contains the item index and embedding payload. The embedding payload may be a numeric vector or a string.

Signature

type Embedding = typeof Embedding.Type;

IncludeEnum type

Added in v4.0.0 Source

Type of optional include values accepted by OpenAI Responses requests.

Signature

type IncludeEnum = typeof IncludeEnum.Type;

InputContent type

Added in v4.0.0 Source

Content block accepted in OpenAI Responses input messages.

Details

Accepted block variants are input_text, input_image, and input_file.

Signature

type InputContent = typeof InputContent.Type;

InputItem type

Added in v4.0.0 Source

Item shape accepted by an OpenAI Responses request input field.

When to use

Use when typing structured CreateResponse.input array items.

Details

Accepted item families include request/output messages, function call and function call output, reasoning items, item references, shell and local shell calls and outputs, apply-patch output, and MCP approval responses.

Signature

type InputItem = typeof InputItem.Type;

MessageStatus type

Added in v4.0.0 Source

Lifecycle status shared by messages, reasoning items, and tool calls.

Details

Accepted values are "in_progress", "completed", and "incomplete".

Signature

type MessageStatus = typeof MessageStatus.Type;

ReasoningItem type

Added in v4.0.0 Source

Reasoning output item containing encrypted content, summaries, and optional reasoning text.

When to use

Use when typing OpenAI Responses reasoning items that may be carried into later request input.

Details

Reasoning items represent model reasoning content. summary is required, while content and status are optional.

Gotchas

encrypted_content is populated only when reasoning.encrypted_content is requested through include.

Signature

type ReasoningItem = typeof ReasoningItem.Type;

Response type

Added in v4.0.0 Source

OpenAI Responses API response object.

When to use

Use when typing non-streaming OpenAI Responses API responses.

Details

Response objects include metadata, output items, optional token usage, and optional incomplete details.

Signature

type Response = typeof Response.Type;

ResponseStreamEvent type

Added in v4.0.0 Source

Server-sent event shape emitted by OpenAI Responses API streams.

When to use

Use when typing events from a streaming OpenAI Responses API request.

Details

Includes known response stream events plus a fallback shape for unknown future event types.

Signature

type ResponseStreamEvent = typeof ResponseStreamEvent.Type;

ResponseUsage type

Added in v4.0.0 Source

Token accounting reported on OpenAI Responses API response objects.

Details

Includes total input, output, and combined token counts, with provider-specific token detail fields preserved when present.

Signature

type ResponseUsage = typeof ResponseUsage.Type;

SummaryTextContent type

Added in v4.0.0 Source

Text content block used for model-provided reasoning summaries.

Signature

type SummaryTextContent = typeof SummaryTextContent.Type;

TextResponseFormatConfiguration type

Added in v4.0.0 Source

Text output format configuration for plain text, JSON object, or JSON Schema responses.

Signature

type TextResponseFormatConfiguration = typeof TextResponseFormatConfiguration.Type;

Tool type

Added in v4.0.0 Source

Tool definition that can be supplied to an OpenAI Responses request.

Signature

type Tool = typeof Tool.Type;

ToolChoice type

Added in v4.0.0 Source

Tool selection mode or named tool choice for a Responses request.

Details

Accepted forms are "none", "auto", "required", an allowed-tools set, a named function or custom tool, or a provider-defined tool choice.

Signature

type ToolChoice = typeof ToolChoice.Type;

UnknownResponseStreamEvent type

Added in v4.0.0 Source

Fallback event shape for future or provider-specific response stream events.

Signature

type UnknownResponseStreamEvent = {
  [key: string]: unknown;
  readonly type: string;
};

Options

CreateResponse type

Added in v4.0.0 Source

Request options used to create an OpenAI Responses API response.

Signature

type CreateResponse = typeof CreateResponse.Type;

Schemas

Annotation

Added in v4.0.0 Source

Schema for citation and file-path annotations attached to output text content.

Details

Accepts annotation objects discriminated by type: file_citation, url_citation, container_file_citation, or file_path.

Signature

declare const Annotation: Union<
  readonly [
    Struct<{
      readonly file_id: String;
      readonly filename: String;
      readonly index: Int;
      readonly type: Literal<"file_citation">;
    }>,
    Struct<{
      readonly end_index: Int;
      readonly start_index: Int;
      readonly title: String;
      readonly type: Literal<"url_citation">;
      readonly url: String;
    }>,
    Struct<{
      readonly container_id: String;
      readonly end_index: Int;
      readonly file_id: String;
      readonly filename: String;
      readonly start_index: Int;
      readonly type: Literal<"container_file_citation">;
    }>,
    Struct<{
      readonly file_id: String;
      readonly index: Int;
      readonly type: Literal<"file_path">;
    }>,
  ]
>;

CreateEmbeddingRequest

Added in v4.0.0 Source

Schema for the request payload sent to the OpenAI embeddings endpoint.

When to use

Use when validating or encoding embeddings requests before sending them to OpenAI, while leaving model-specific limits to the provider.

Details

Requires input and model. input may be a string, an array of strings, a token array, or an array of token arrays. Optional fields configure the embedding encoding format, requested dimensions, and user identifier.

Gotchas

This schema validates the transport shape, but OpenAI still enforces provider-side constraints such as non-empty input, integer token ids, input size limits, positive dimensions, and model-specific dimension support.

Signature

declare const CreateEmbeddingRequest: Struct<{
  readonly dimensions: optionalKey<Int>;
  readonly encoding_format: optionalKey<Literals<readonly ["float", "base64"]>>;
  readonly input: Union<readonly [String, $Array<String>, $Array<Int>, $Array<$Array<Int>>]>;
  readonly model: String;
  readonly user: optionalKey<String>;
}>;

CreateEmbeddingResponse

Added in v4.0.0 Source

Schema for a successful response payload returned by the OpenAI embeddings endpoint.

When to use

Use when you need to validate embeddings responses at an OpenAI client boundary before trusting item shapes, especially when numeric and string embeddings are both allowed.

Details

The response contains an array of Embedding items, the model name, an optional object: "list" marker, and optional token usage counts for prompt and total tokens.

Gotchas

Each Embedding may contain either a numeric vector or a string embedding. Callers that require numeric vectors must account for string embeddings.

See

CreateEmbeddingRequest for the request schema sent to the embeddings endpoint
Embedding for individual embedding items in the response

Signature

declare const CreateEmbeddingResponse: Struct<{
  readonly data: $Array<
    Struct<{
      readonly embedding: Union<readonly [$Array<Finite>, String]>;
      readonly index: Int;
      readonly object: optionalKey<String>;
    }>
  >;
  readonly model: String;
  readonly object: optionalKey<Literal<"list">>;
  readonly usage: optionalKey<
    Struct<{
      readonly prompt_tokens: Int;
      readonly total_tokens: Int;
    }>
  >;
}>;

CreateResponse

Added in v4.0.0 Source

Schema for request options used to create an OpenAI Responses API response.

When to use

Use to validate or encode payloads sent to the OpenAI Responses API.

Details

Validates the Responses API request payload, including input content, model selection, instructions, reasoning options, text output format, tools, tool_choice, streaming, storage, response continuation, sampling options, and optional response fields requested through include.

Gotchas

When stream is true, the API returns stream events instead of a single response object.

See

Response for decoded non-streaming response objects
ResponseStreamEvent for decoded streaming event objects

Signature

declare const CreateResponse: Struct<{
  readonly background: optional<Boolean>;
  readonly conversation: optional<String>;
  readonly include: optional<$Array<Literals<readonly ["message.input_image.image_url", "reasoning.encrypted_content", "message.output_text.logprobs", "code_interpreter_call.outputs", "web_search_call.action.sources"]>>>;
  readonly input: optional<Union<readonly [String, $Array<Union<readonly [Struct<{
    readonly content: Union<...>;
    readonly role: Literals<...>;
    readonly status: optionalKey<...>;
    readonly type: optionalKey<...>;
  }>, Struct<{
    readonly content: $Array<...>;
    readonly id: String;
    readonly role: Literal<...>;
    readonly status: Literals<...>;
    readonly type: Literal<...>;
  }>, Struct<{
    readonly arguments: String;
    readonly call_id: String;
    readonly id: optionalKey<...>;
    readonly name: String;
    readonly status: optionalKey<...>;
    readonly type: Literal<...>;
  }>, Struct<{
    readonly call_id: String;
    readonly id: optionalKey<...>;
    readonly output: Union<...>;
    readonly status: optionalKey<...>;
    readonly type: Literal<...>;
  }>, Struct<{
    readonly content: optionalKey<...>;
    readonly encrypted_content: optionalKey<...>;
    readonly id: String;
    readonly status: optionalKey<...>;
    readonly summary: $Array<...>;
    readonly type: Literal<...>;
  }>, Struct<{
    readonly id: String;
    readonly type: Literal<...>;
  }>, Struct<{
    readonly action: Unknown;
    readonly call_id: String;
    readonly id: optionalKey<...>;
    readonly status: optionalKey<...>;
    readonly type: Literal<...>;
  }>, Struct<{
    readonly call_id: String;
    readonly id: optionalKey<...>;
    readonly output: Unknown;
    readonly status: optionalKey<...>;
    readonly type: Literal<...>;
  }>, Struct<{
    readonly action: Unknown;
    readonly call_id: String;
    readonly id: optionalKey<...>;
    readonly status: optionalKey<...>;
    readonly type: Literal<...>;
  }>, Struct<{
    readonly call_id: String;
    readonly id: optionalKey<...>;
    readonly output: Unknown;
    readonly status: optionalKey<...>;
    readonly type: Literal<...>;
  }>, Struct<{
    readonly call_id: String;
    readonly id: optionalKey<...>;
    readonly output: optionalKey<...>;
    readonly status: optionalKey<...>;
    readonly type: Literal<...>;
  }>, Struct<{
    readonly approval_request_id: String;
    readonly approve: Boolean;
    readonly type: Literal<...>;
  }>]>>]>>;
  readonly instructions: optional<String>;
  readonly max_output_tokens: optional<Int>;
  readonly max_tool_calls: optional<Int>;
  readonly metadata: optional<$Record<String, String>>;
  readonly modalities: optional<$Array<Literals<readonly ["text", "audio"]>>>;
  readonly model: optional<String>;
  readonly previous_response_id: optional<String>;
  readonly reasoning: optional<Struct<{
    readonly effort: optional<Literals<readonly ["none", "minimal", "low", "medium", "high", "xhigh"]>>;
    readonly generate_summary: optional<Literals<readonly ["auto", "concise", "detailed"]>>;
    readonly summary: optional<Literals<readonly ["auto", "concise", "detailed"]>>;
  }>>;
  readonly seed: optional<Int>;
  readonly service_tier: optional<String>;
  readonly store: optional<Boolean>;
  readonly stream: optional<Boolean>;
  readonly temperature: optional<Finite>;
  readonly text: optional<Struct<{
    readonly format: optional<Union<readonly [Struct<{
      readonly type: Literal<...>;
    }>, Struct<{
      readonly description: optionalKey<...>;
      readonly name: String;
      readonly schema: $Record<..., ...>;
      readonly strict: optionalKey<...>;
      readonly type: Literal<...>;
    }>, Struct<{
      readonly type: Literal<...>;
    }>]>>;
    readonly verbosity: optional<Literals<readonly ["low", "medium", "high"]>>;
  }>>;
  readonly tool_choice: optional<Union<readonly [Literals<readonly ["none", "auto", "required"]>, Struct<{
    readonly mode: Literals<readonly ["auto", "required"]>;
    readonly tools: $Array<$Record<String, Unknown>>;
    readonly type: Literal<"allowed_tools">;
  }>, Struct<{
    readonly name: String;
    readonly type: Literal<"function">;
  }>, Struct<{
    readonly name: String;
    readonly type: Literal<"custom">;
  }>, StructWithRest<Struct<{
    readonly type: Literals<readonly ["apply_patch", "code_interpreter", "file_search", "image_generation", "local_shell", "mcp", "shell", "web_search", "web_search_preview"]>;
  }>, readonly [$Record<String, Unknown>]>]>>;
  readonly tools: optional<$Array<Union<readonly [Struct<{
    readonly description: optionalKey<NullOr<String>>;
    readonly name: String;
    readonly parameters: optionalKey<NullOr<$Record<..., ...>>>;
    readonly strict: optionalKey<NullOr<Boolean>>;
    readonly type: Literal<"function">;
  }>, Struct<{
    readonly description: optionalKey<String>;
    readonly format: optionalKey<Unknown>;
    readonly name: String;
    readonly type: Literal<"custom">;
  }>, StructWithRest<Struct<{
    readonly type: Literals<readonly [..., ..., ..., ..., ..., ..., ..., ..., ...]>;
  }>, readonly [$Record<String, Unknown>]>]>>>;
  readonly top_logprobs: optional<Int>;
  readonly top_p: optional<Finite>;
  readonly truncation: optional<Literals<readonly ["auto", "disabled"]>>;
  readonly user: optional<String>;
}>

Embedding

Added in v4.0.0 Source

Schema for one embedding item returned by the OpenAI embeddings API.

When to use

Use when validating individual embedding entries at the OpenAI client boundary before assuming the embedding payload is a numeric vector.

Details

An embedding item contains its index, optional object marker, and an embedding represented either as a numeric vector or as a string.

Gotchas

Callers that need numeric vectors must account for string embeddings, such as base64-encoded embeddings returned for string encoding formats.

Signature

declare const Embedding: Struct<{
  readonly embedding: Union<readonly [$Array<Finite>, String]>;
  readonly index: Int;
  readonly object: optionalKey<String>;
}>;

IncludeEnum

Added in v4.0.0 Source

Schema for optional include values supported by the local handwritten Responses client schema.

Details

These values request additional response fields such as image URLs, encrypted reasoning content, output logprobs, code interpreter outputs, or web search sources. This schema enumerates the include values supported by this client path.

Signature

declare const IncludeEnum: Literals<
  readonly [
    "message.input_image.image_url",
    "reasoning.encrypted_content",
    "message.output_text.logprobs",
    "code_interpreter_call.outputs",
    "web_search_call.action.sources",
  ]
>;

InputContent

Added in v4.0.0 Source

Schema for content blocks accepted in OpenAI Responses input messages.

Details

Accepted block variants are input_text, input_image, and input_file.

See

InputItem for request input item shapes that can contain these content blocks

Signature

declare const InputContent: Union<
  readonly [
    Struct<{
      readonly text: String;
      readonly type: Literal<"input_text">;
    }>,
    Struct<{
      readonly detail: optionalKey<NullOr<Literals<readonly ["low", "high", "auto"]>>>;
      readonly file_id: optionalKey<NullOr<String>>;
      readonly image_url: optionalKey<NullOr<String>>;
      readonly type: Literal<"input_image">;
    }>,
    Struct<{
      readonly file_data: optionalKey<String>;
      readonly file_id: optionalKey<NullOr<String>>;
      readonly file_url: optionalKey<String>;
      readonly filename: optionalKey<String>;
      readonly type: Literal<"input_file">;
    }>,
  ]
>;

InputItem

Added in v4.0.0 Source

Schema for item shapes accepted by an OpenAI Responses request input field.

When to use

Use when validating structured CreateResponse.input array items.

Details

See

CreateResponse for the request schema that consumes input items
InputContent for content blocks inside message items

Signature

declare const InputItem: Union<readonly [Struct<{
  readonly content: Union<readonly [String, $Array<Union<readonly [Struct<{
    readonly text: ...;
    readonly type: ...;
  }>, Struct<{
    readonly detail: ...;
    readonly file_id: ...;
    readonly image_url: ...;
    readonly type: ...;
  }>, Struct<{
    readonly file_data: ...;
    readonly file_id: ...;
    readonly file_url: ...;
    readonly filename: ...;
    readonly type: ...;
  }>]>>]>;
  readonly role: Literals<readonly ["system", "developer", "user", "assistant"]>;
  readonly status: optionalKey<Literals<readonly ["in_progress", "completed", "incomplete"]>>;
  readonly type: optionalKey<Literal<"message">>;
}>, Struct<{
  readonly content: $Array<Union<readonly [Struct<{
    readonly text: String;
    readonly type: Literal<"input_text">;
  }>, Struct<{
    readonly annotations: $Array<Union<...>>;
    readonly logprobs: optionalKey<$Array<...>>;
    readonly text: String;
    readonly type: Literal<"output_text">;
  }>, Struct<{
    readonly text: String;
    readonly type: Literal<"text">;
  }>, Struct<{
    readonly text: String;
    readonly type: Literal<"summary_text">;
  }>, Struct<{
    readonly text: String;
    readonly type: Literal<"reasoning_text">;
  }>, Struct<{
    readonly refusal: String;
    readonly type: Literal<"refusal">;
  }>, Struct<{
    readonly detail: optionalKey<NullOr<...>>;
    readonly file_id: optionalKey<NullOr<...>>;
    readonly image_url: optionalKey<NullOr<...>>;
    readonly type: Literal<"input_image">;
  }>, Struct<{
    readonly file_id: NullOr<String>;
    readonly image_url: NullOr<String>;
    readonly type: Literal<"computer_screenshot">;
  }>, Struct<{
    readonly file_data: optionalKey<String>;
    readonly file_id: optionalKey<NullOr<...>>;
    readonly file_url: optionalKey<String>;
    readonly filename: optionalKey<String>;
    readonly type: Literal<"input_file">;
  }>]>>;
  readonly id: String;
  readonly role: Literal<"assistant">;
  readonly status: Literals<readonly ["in_progress", "completed", "incomplete"]>;
  readonly type: Literal<"message">;
}>, Struct<{
  readonly arguments: String;
  readonly call_id: String;
  readonly id: optionalKey<String>;
  readonly name: String;
  readonly status: optionalKey<Literals<readonly ["in_progress", "completed", "incomplete"]>>;
  readonly type: Literal<"function_call">;
}>, Struct<{
  readonly call_id: String;
  readonly id: optionalKey<NullOr<String>>;
  readonly output: Union<readonly [String, $Array<Union<readonly [Struct<{
    readonly text: ...;
    readonly type: ...;
  }>, Struct<{
    readonly detail: ...;
    readonly file_id: ...;
    readonly image_url: ...;
    readonly type: ...;
  }>, Struct<{
    readonly file_data: ...;
    readonly file_id: ...;
    readonly file_url: ...;
    readonly filename: ...;
    readonly type: ...;
  }>]>>]>;
  readonly status: optionalKey<NullOr<Literals<readonly ["in_progress", "completed", "incomplete"]>>>;
  readonly type: Literal<"function_call_output">;
}>, Struct<{
  readonly content: optionalKey<$Array<Struct<{
    readonly text: String;
    readonly type: Literal<"reasoning_text">;
  }>>>;
  readonly encrypted_content: optionalKey<NullOr<String>>;
  readonly id: String;
  readonly status: optionalKey<Literals<readonly ["in_progress", "completed", "incomplete"]>>;
  readonly summary: $Array<Struct<{
    readonly text: String;
    readonly type: Literal<"summary_text">;
  }>>;
  readonly type: Literal<"reasoning">;
}>, Struct<{
  readonly id: String;
  readonly type: Literal<"item_reference">;
}>, Struct<{
  readonly action: Unknown;
  readonly call_id: String;
  readonly id: optionalKey<String>;
  readonly status: optionalKey<Literals<readonly ["in_progress", "completed", "incomplete"]>>;
  readonly type: Literal<"local_shell_call">;
}>, Struct<{
  readonly call_id: String;
  readonly id: optionalKey<String>;
  readonly output: Unknown;
  readonly status: optionalKey<Literals<readonly ["in_progress", "completed", "incomplete"]>>;
  readonly type: Literal<"local_shell_call_output">;
}>, Struct<{
  readonly action: Unknown;
  readonly call_id: String;
  readonly id: optionalKey<String>;
  readonly status: optionalKey<Literals<readonly ["in_progress", "completed", "incomplete"]>>;
  readonly type: Literal<"shell_call">;
}>, Struct<{
  readonly call_id: String;
  readonly id: optionalKey<String>;
  readonly output: Unknown;
  readonly status: optionalKey<Literals<readonly ["in_progress", "completed", "incomplete"]>>;
  readonly type: Literal<"shell_call_output">;
}>, Struct<{
  readonly call_id: String;
  readonly id: optionalKey<String>;
  readonly output: optionalKey<Unknown>;
  readonly status: optionalKey<Literals<readonly ["in_progress", "completed", "incomplete"]>>;
  readonly type: Literal<"apply_patch_call_output">;
}>, Struct<{
  readonly approval_request_id: String;
  readonly approve: Boolean;
  readonly type: Literal<"mcp_approval_response">;
}>]>

MessageStatus

Added in v4.0.0 Source

Schema for lifecycle statuses shared by messages, reasoning items, and tool calls.

Details

Accepted values are "in_progress", "completed", and "incomplete". This item-level status is used by message, reasoning, and tool-call shapes.

Signature

declare const MessageStatus: Literals<readonly ["in_progress", "completed", "incomplete"]>;

ReasoningItem

Added in v4.0.0 Source

Schema for a reasoning output item containing encrypted content, summaries, and optional reasoning text.

When to use

Use when decoding or encoding OpenAI Responses reasoning items that may be carried into later request input.

Details

Reasoning items represent model reasoning content. summary is required, while content and status are optional.

Gotchas

encrypted_content is populated only when reasoning.encrypted_content is requested through include.

See

InputItem for request input items that can carry reasoning items
IncludeEnum for requesting encrypted reasoning content

Signature

declare const ReasoningItem: Struct<{
  readonly content: optionalKey<
    $Array<
      Struct<{
        readonly text: String;
        readonly type: Literal<"reasoning_text">;
      }>
    >
  >;
  readonly encrypted_content: optionalKey<NullOr<String>>;
  readonly id: String;
  readonly status: optionalKey<Literals<readonly ["in_progress", "completed", "incomplete"]>>;
  readonly summary: $Array<
    Struct<{
      readonly text: String;
      readonly type: Literal<"summary_text">;
    }>
  >;
  readonly type: Literal<"reasoning">;
}>;

Response

Added in v4.0.0 Source

Schema for an OpenAI Responses API response object.

When to use

Use to decode non-streaming OpenAI Responses API responses.

Details

Response objects include the response id, model, creation time, output items, optional token usage, optional incomplete details, and optional service tier.

See

CreateResponse for the request schema that creates responses
ResponseUsage for token accounting on responses
ResponseStreamEvent for streaming response events

Signature

declare const Response: Struct<{
  readonly created_at: Int;
  readonly error: optionalKey<NullOr<Struct<{
    readonly code: String;
    readonly message: String;
  }>>>;
  readonly id: String;
  readonly incomplete_details: optionalKey<NullOr<Struct<{
    readonly reason: optionalKey<Literals<readonly ["max_output_tokens", "content_filter"]>>;
  }>>>;
  readonly model: String;
  readonly object: optionalKey<Literal<"response">>;
  readonly output: withDecodingDefault<$Array<Union<readonly [Struct<{
    readonly call_id: String;
    readonly id: String;
    readonly operation: Struct<{
      readonly diff: optionalKey<...>;
      readonly path: String;
      readonly type: String;
    }>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"apply_patch_call">;
  }>, Struct<{
    readonly code: optionalKey<String>;
    readonly container_id: String;
    readonly id: String;
    readonly outputs: optionalKey<$Array<Unknown>>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"code_interpreter_call">;
  }>, Struct<{
    readonly id: String;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"computer_call">;
  }>, Struct<{
    readonly id: String;
    readonly queries: optionalKey<$Array<String>>;
    readonly results: optionalKey<NullOr<Unknown>>;
    readonly status: optionalKey<String>;
    readonly type: Literal<"file_search_call">;
  }>, Struct<{
    readonly arguments: String;
    readonly call_id: String;
    readonly id: optionalKey<String>;
    readonly name: String;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"function_call">;
  }>, Struct<{
    readonly id: String;
    readonly result: optionalKey<NullOr<String>>;
    readonly status: optionalKey<Literals<readonly [..., ..., ..., ...]>>;
    readonly type: Literal<"image_generation_call">;
  }>, Struct<{
    readonly action: Unknown;
    readonly call_id: String;
    readonly id: optionalKey<String>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"local_shell_call">;
  }>, Struct<{
    readonly approval_request_id: optionalKey<NullOr<String>>;
    readonly arguments: Unknown;
    readonly error: optionalKey<Unknown>;
    readonly id: String;
    readonly name: String;
    readonly output: optionalKey<Unknown>;
    readonly server_label: optionalKey<NullOr<String>>;
    readonly type: Literal<"mcp_call">;
  }>, Struct<{
    readonly id: String;
    readonly type: Literal<"mcp_list_tools">;
  }>, Struct<{
    readonly approval_request_id: optionalKey<String>;
    readonly arguments: Unknown;
    readonly id: String;
    readonly name: String;
    readonly type: Literal<"mcp_approval_request">;
  }>, Struct<{
    readonly content: $Array<Union<readonly [..., ..., ..., ..., ..., ..., ..., ..., ...]>>;
    readonly id: String;
    readonly role: Literal<"assistant">;
    readonly status: Literals<readonly ["in_progress", "completed", "incomplete"]>;
    readonly type: Literal<"message">;
  }>, Struct<{
    readonly content: optionalKey<$Array<Struct<...>>>;
    readonly encrypted_content: optionalKey<NullOr<String>>;
    readonly id: String;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly summary: $Array<Struct<{
      readonly text: ...;
      readonly type: ...;
    }>>;
    readonly type: Literal<"reasoning">;
  }>, Struct<{
    readonly action: Unknown;
    readonly call_id: String;
    readonly id: optionalKey<String>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"shell_call">;
  }>, Struct<{
    readonly action: optionalKey<Unknown>;
    readonly id: String;
    readonly status: optionalKey<String>;
    readonly type: Literal<"web_search_call">;
  }>]>>, never>;
  readonly service_tier: optionalKey<String>;
  readonly usage: optionalKey<NullOr<StructWithRest<Struct<{
    readonly input_tokens: Int;
    readonly input_tokens_details: optionalKey<Unknown>;
    readonly output_tokens: Int;
    readonly output_tokens_details: optionalKey<Unknown>;
    readonly total_tokens: Int;
  }>, readonly [$Record<String, Unknown>]>>>;
}>

ResponseStreamEvent

Added in v4.0.0 Source

Schema for server-sent event shapes emitted by OpenAI Responses API streams.

When to use

Use to decode events from a streaming OpenAI Responses API request.

Details

Known event variants include response lifecycle events, output item events, text and reasoning deltas, tool-call deltas, partial image events, and error events.

Gotchas

Future event types decode through the fallback only when their type is not one of the known event types. Malformed known events still fail to decode.

See

Response for complete response objects carried by lifecycle events
UnknownResponseStreamEvent for the fallback shape for future event types

Signature

declare const ResponseStreamEvent: Union<readonly [Struct<{
  readonly response: Struct<{
    readonly created_at: Int;
    readonly error: optionalKey<NullOr<Struct<{
      readonly code: String;
      readonly message: String;
    }>>>;
    readonly id: String;
    readonly incomplete_details: optionalKey<NullOr<Struct<{
      readonly reason: optionalKey<...>;
    }>>>;
    readonly model: String;
    readonly object: optionalKey<Literal<"response">>;
    readonly output: withDecodingDefault<$Array<Union<readonly [Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>]>>, never>;
    readonly service_tier: optionalKey<String>;
    readonly usage: optionalKey<NullOr<StructWithRest<Struct<{
      readonly input_tokens: ...;
      readonly input_tokens_details: ...;
      readonly output_tokens: ...;
      readonly output_tokens_details: ...;
      readonly total_tokens: ...;
    }>, readonly [$Record<..., ...>]>>>;
  }>;
  readonly sequence_number: Int;
  readonly type: Literal<"response.created">;
}>, Struct<{
  readonly response: Struct<{
    readonly created_at: Int;
    readonly error: optionalKey<NullOr<Struct<{
      readonly code: String;
      readonly message: String;
    }>>>;
    readonly id: String;
    readonly incomplete_details: optionalKey<NullOr<Struct<{
      readonly reason: optionalKey<...>;
    }>>>;
    readonly model: String;
    readonly object: optionalKey<Literal<"response">>;
    readonly output: withDecodingDefault<$Array<Union<readonly [Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>]>>, never>;
    readonly service_tier: optionalKey<String>;
    readonly usage: optionalKey<NullOr<StructWithRest<Struct<{
      readonly input_tokens: ...;
      readonly input_tokens_details: ...;
      readonly output_tokens: ...;
      readonly output_tokens_details: ...;
      readonly total_tokens: ...;
    }>, readonly [$Record<..., ...>]>>>;
  }>;
  readonly sequence_number: Int;
  readonly type: Literal<"response.completed">;
}>, Struct<{
  readonly response: Struct<{
    readonly created_at: Int;
    readonly error: optionalKey<NullOr<Struct<{
      readonly code: String;
      readonly message: String;
    }>>>;
    readonly id: String;
    readonly incomplete_details: optionalKey<NullOr<Struct<{
      readonly reason: optionalKey<...>;
    }>>>;
    readonly model: String;
    readonly object: optionalKey<Literal<"response">>;
    readonly output: withDecodingDefault<$Array<Union<readonly [Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>]>>, never>;
    readonly service_tier: optionalKey<String>;
    readonly usage: optionalKey<NullOr<StructWithRest<Struct<{
      readonly input_tokens: ...;
      readonly input_tokens_details: ...;
      readonly output_tokens: ...;
      readonly output_tokens_details: ...;
      readonly total_tokens: ...;
    }>, readonly [$Record<..., ...>]>>>;
  }>;
  readonly sequence_number: Int;
  readonly type: Literal<"response.incomplete">;
}>, Struct<{
  readonly response: Struct<{
    readonly created_at: Int;
    readonly error: optionalKey<NullOr<Struct<{
      readonly code: String;
      readonly message: String;
    }>>>;
    readonly id: String;
    readonly incomplete_details: optionalKey<NullOr<Struct<{
      readonly reason: optionalKey<...>;
    }>>>;
    readonly model: String;
    readonly object: optionalKey<Literal<"response">>;
    readonly output: withDecodingDefault<$Array<Union<readonly [Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>, Struct<...>]>>, never>;
    readonly service_tier: optionalKey<String>;
    readonly usage: optionalKey<NullOr<StructWithRest<Struct<{
      readonly input_tokens: ...;
      readonly input_tokens_details: ...;
      readonly output_tokens: ...;
      readonly output_tokens_details: ...;
      readonly total_tokens: ...;
    }>, readonly [$Record<..., ...>]>>>;
  }>;
  readonly sequence_number: Int;
  readonly type: Literal<"response.failed">;
}>, Struct<{
  readonly item: Union<readonly [Struct<{
    readonly call_id: String;
    readonly id: String;
    readonly operation: Struct<{
      readonly diff: optionalKey<...>;
      readonly path: String;
      readonly type: String;
    }>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"apply_patch_call">;
  }>, Struct<{
    readonly code: optionalKey<String>;
    readonly container_id: String;
    readonly id: String;
    readonly outputs: optionalKey<$Array<Unknown>>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"code_interpreter_call">;
  }>, Struct<{
    readonly id: String;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"computer_call">;
  }>, Struct<{
    readonly id: String;
    readonly queries: optionalKey<$Array<String>>;
    readonly results: optionalKey<NullOr<Unknown>>;
    readonly status: optionalKey<String>;
    readonly type: Literal<"file_search_call">;
  }>, Struct<{
    readonly arguments: String;
    readonly call_id: String;
    readonly id: optionalKey<String>;
    readonly name: String;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"function_call">;
  }>, Struct<{
    readonly id: String;
    readonly result: optionalKey<NullOr<String>>;
    readonly status: optionalKey<Literals<readonly [..., ..., ..., ...]>>;
    readonly type: Literal<"image_generation_call">;
  }>, Struct<{
    readonly action: Unknown;
    readonly call_id: String;
    readonly id: optionalKey<String>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"local_shell_call">;
  }>, Struct<{
    readonly approval_request_id: optionalKey<NullOr<String>>;
    readonly arguments: Unknown;
    readonly error: optionalKey<Unknown>;
    readonly id: String;
    readonly name: String;
    readonly output: optionalKey<Unknown>;
    readonly server_label: optionalKey<NullOr<String>>;
    readonly type: Literal<"mcp_call">;
  }>, Struct<{
    readonly id: String;
    readonly type: Literal<"mcp_list_tools">;
  }>, Struct<{
    readonly approval_request_id: optionalKey<String>;
    readonly arguments: Unknown;
    readonly id: String;
    readonly name: String;
    readonly type: Literal<"mcp_approval_request">;
  }>, Struct<{
    readonly content: $Array<Union<readonly [..., ..., ..., ..., ..., ..., ..., ..., ...]>>;
    readonly id: String;
    readonly role: Literal<"assistant">;
    readonly status: Literals<readonly ["in_progress", "completed", "incomplete"]>;
    readonly type: Literal<"message">;
  }>, Struct<{
    readonly content: optionalKey<$Array<Struct<...>>>;
    readonly encrypted_content: optionalKey<NullOr<String>>;
    readonly id: String;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly summary: $Array<Struct<{
      readonly text: ...;
      readonly type: ...;
    }>>;
    readonly type: Literal<"reasoning">;
  }>, Struct<{
    readonly action: Unknown;
    readonly call_id: String;
    readonly id: optionalKey<String>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"shell_call">;
  }>, Struct<{
    readonly action: optionalKey<Unknown>;
    readonly id: String;
    readonly status: optionalKey<String>;
    readonly type: Literal<"web_search_call">;
  }>]>;
  readonly output_index: Int;
  readonly sequence_number: Int;
  readonly type: Literal<"response.output_item.added">;
}>, Struct<{
  readonly item: Union<readonly [Struct<{
    readonly call_id: String;
    readonly id: String;
    readonly operation: Struct<{
      readonly diff: optionalKey<...>;
      readonly path: String;
      readonly type: String;
    }>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"apply_patch_call">;
  }>, Struct<{
    readonly code: optionalKey<String>;
    readonly container_id: String;
    readonly id: String;
    readonly outputs: optionalKey<$Array<Unknown>>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"code_interpreter_call">;
  }>, Struct<{
    readonly id: String;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"computer_call">;
  }>, Struct<{
    readonly id: String;
    readonly queries: optionalKey<$Array<String>>;
    readonly results: optionalKey<NullOr<Unknown>>;
    readonly status: optionalKey<String>;
    readonly type: Literal<"file_search_call">;
  }>, Struct<{
    readonly arguments: String;
    readonly call_id: String;
    readonly id: optionalKey<String>;
    readonly name: String;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"function_call">;
  }>, Struct<{
    readonly id: String;
    readonly result: optionalKey<NullOr<String>>;
    readonly status: optionalKey<Literals<readonly [..., ..., ..., ...]>>;
    readonly type: Literal<"image_generation_call">;
  }>, Struct<{
    readonly action: Unknown;
    readonly call_id: String;
    readonly id: optionalKey<String>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"local_shell_call">;
  }>, Struct<{
    readonly approval_request_id: optionalKey<NullOr<String>>;
    readonly arguments: Unknown;
    readonly error: optionalKey<Unknown>;
    readonly id: String;
    readonly name: String;
    readonly output: optionalKey<Unknown>;
    readonly server_label: optionalKey<NullOr<String>>;
    readonly type: Literal<"mcp_call">;
  }>, Struct<{
    readonly id: String;
    readonly type: Literal<"mcp_list_tools">;
  }>, Struct<{
    readonly approval_request_id: optionalKey<String>;
    readonly arguments: Unknown;
    readonly id: String;
    readonly name: String;
    readonly type: Literal<"mcp_approval_request">;
  }>, Struct<{
    readonly content: $Array<Union<readonly [..., ..., ..., ..., ..., ..., ..., ..., ...]>>;
    readonly id: String;
    readonly role: Literal<"assistant">;
    readonly status: Literals<readonly ["in_progress", "completed", "incomplete"]>;
    readonly type: Literal<"message">;
  }>, Struct<{
    readonly content: optionalKey<$Array<Struct<...>>>;
    readonly encrypted_content: optionalKey<NullOr<String>>;
    readonly id: String;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly summary: $Array<Struct<{
      readonly text: ...;
      readonly type: ...;
    }>>;
    readonly type: Literal<"reasoning">;
  }>, Struct<{
    readonly action: Unknown;
    readonly call_id: String;
    readonly id: optionalKey<String>;
    readonly status: optionalKey<Literals<readonly [..., ..., ...]>>;
    readonly type: Literal<"shell_call">;
  }>, Struct<{
    readonly action: optionalKey<Unknown>;
    readonly id: String;
    readonly status: optionalKey<String>;
    readonly type: Literal<"web_search_call">;
  }>]>;
  readonly output_index: Int;
  readonly sequence_number: Int;
  readonly type: Literal<"response.output_item.done">;
}>, Struct<{
  readonly content_index: Int;
  readonly delta: String;
  readonly item_id: String;
  readonly logprobs: optionalKey<$Array<Unknown>>;
  readonly output_index: Int;
  readonly sequence_number: Int;
  readonly type: Literal<"response.output_text.delta">;
}>, Struct<{
  readonly annotation: Union<readonly [Struct<{
    readonly file_id: String;
    readonly filename: String;
    readonly index: Int;
    readonly type: Literal<"file_citation">;
  }>, Struct<{
    readonly end_index: Int;
    readonly start_index: Int;
    readonly title: String;
    readonly type: Literal<"url_citation">;
    readonly url: String;
  }>, Struct<{
    readonly container_id: String;
    readonly end_index: Int;
    readonly file_id: String;
    readonly filename: String;
    readonly start_index: Int;
    readonly type: Literal<"container_file_citation">;
  }>, Struct<{
    readonly file_id: String;
    readonly index: Int;
    readonly type: Literal<"file_path">;
  }>]>;
  readonly annotation_index: Int;
  readonly content_index: Int;
  readonly item_id: String;
  readonly output_index: Int;
  readonly sequence_number: Int;
  readonly type: Literal<"response.output_text.annotation.added">;
}>, Struct<{
  readonly item_id: String;
  readonly output_index: Int;
  readonly part: Struct<{
    readonly text: String;
    readonly type: Literal<"summary_text">;
  }>;
  readonly sequence_number: Int;
  readonly summary_index: Int;
  readonly type: Literal<"response.reasoning_summary_part.added">;
}>, Struct<{
  readonly item_id: String;
  readonly output_index: Int;
  readonly part: Struct<{
    readonly text: String;
    readonly type: Literal<"summary_text">;
  }>;
  readonly sequence_number: Int;
  readonly summary_index: Int;
  readonly type: Literal<"response.reasoning_summary_part.done">;
}>, Struct<{
  readonly delta: String;
  readonly item_id: String;
  readonly output_index: Int;
  readonly sequence_number: Int;
  readonly summary_index: Int;
  readonly type: Literal<"response.reasoning_summary_text.delta">;
}>, Struct<{
  readonly delta: String;
  readonly item_id: String;
  readonly output_index: Int;
  readonly sequence_number: Int;
  readonly type: Literal<"response.function_call_arguments.delta">;
}>, Struct<{
  readonly arguments: String;
  readonly item_id: String;
  readonly output_index: Int;
  readonly sequence_number: Int;
  readonly type: Literal<"response.function_call_arguments.done">;
}>, Struct<{
  readonly delta: String;
  readonly item_id: String;
  readonly output_index: Int;
  readonly sequence_number: Int;
  readonly type: Literal<"response.code_interpreter_call_code.delta">;
}>, Struct<{
  readonly code: String;
  readonly item_id: String;
  readonly output_index: Int;
  readonly sequence_number: Int;
  readonly type: Literal<"response.code_interpreter_call_code.done">;
}>, Struct<{
  readonly delta: String;
  readonly item_id: String;
  readonly output_index: Int;
  readonly sequence_number: Int;
  readonly type: Literal<"response.apply_patch_call_operation_diff.delta">;
}>, Struct<{
  readonly delta: optionalKey<String>;
  readonly item_id: String;
  readonly output_index: Int;
  readonly sequence_number: Int;
  readonly type: Literal<"response.apply_patch_call_operation_diff.done">;
}>, Struct<{
  readonly item_id: String;
  readonly output_index: Int;
  readonly partial_image_b64: String;
  readonly sequence_number: Int;
  readonly type: Literal<"response.image_generation_call.partial_image">;
}>, Struct<{
  readonly code: NullOr<String>;
  readonly message: String;
  readonly param: NullOr<String>;
  readonly sequence_number: Int;
  readonly status: optionalKey<Int>;
  readonly type: Literal<"error">;
}>, declare<UnknownResponseStreamEvent, UnknownResponseStreamEvent>]>

ResponseUsage

Added in v4.0.0 Source

Schema for token accounting reported on OpenAI Responses API response objects.

Details

The required counters are input_tokens, output_tokens, and total_tokens. Provider-specific token detail objects are preserved through input_tokens_details, output_tokens_details, and additional fields.

Signature

declare const ResponseUsage: StructWithRest<
  Struct<{
    readonly input_tokens: Int;
    readonly input_tokens_details: optionalKey<Unknown>;
    readonly output_tokens: Int;
    readonly output_tokens_details: optionalKey<Unknown>;
    readonly total_tokens: Int;
  }>,
  readonly [$Record<String, Unknown>]
>;

SummaryTextContent

Added in v4.0.0 Source

Schema for a text block containing a model-provided reasoning summary.

Details

The decoded shape is type: "summary_text" plus text containing the reasoning summary text.

See

ReasoningItem for reasoning output items that contain summary text blocks

Signature

declare const SummaryTextContent: Struct<{
  readonly text: String;
  readonly type: Literal<"summary_text">;
}>;

TextResponseFormatConfiguration

Added in v4.0.0 Source

Schema for text output format configuration, including plain text, JSON object, and JSON Schema responses.

When to use

Use when validating or encoding the text.format setting for a Responses request, especially when choosing structured JSON Schema output.

Details

Accepted variants are text, json_schema, and json_object.

Gotchas

json_object is the older JSON mode. Prefer json_schema for models that support it.

See

CreateResponse for the request schema that consumes text format configuration

Signature

declare const TextResponseFormatConfiguration: Union<
  readonly [
    Struct<{
      readonly type: Literal<"text">;
    }>,
    Struct<{
      readonly description: optionalKey<String>;
      readonly name: String;
      readonly schema: $Record<String, Unknown>;
      readonly strict: optionalKey<NullOr<Boolean>>;
      readonly type: Literal<"json_schema">;
    }>,
    Struct<{
      readonly type: Literal<"json_object">;
    }>,
  ]
>;

Tool

Added in v4.0.0 Source

Schema for tool definitions that can be supplied to an OpenAI Responses request.

When to use

Use when validating or encoding the tools array for a Responses request, including provider-defined tool records with provider-specific fields.

Details

Accepted variants are function tools, custom tools, and provider-defined OpenAI tools. Provider-defined type literals include apply_patch, code_interpreter, file_search, image_generation, local_shell, mcp, shell, web_search, and web_search_preview.

Gotchas

Provider-defined tools use Schema.StructWithRest, so this schema checks the provider tool type and permits additional provider fields rather than fully validating every provider-specific tool payload.

See

ToolChoice for selecting whether and which tools the model may call
CreateResponse for the request schema that consumes tools

Signature

declare const Tool: Union<
  readonly [
    Struct<{
      readonly description: optionalKey<NullOr<String>>;
      readonly name: String;
      readonly parameters: optionalKey<NullOr<$Record<String, Unknown>>>;
      readonly strict: optionalKey<NullOr<Boolean>>;
      readonly type: Literal<"function">;
    }>,
    Struct<{
      readonly description: optionalKey<String>;
      readonly format: optionalKey<Unknown>;
      readonly name: String;
      readonly type: Literal<"custom">;
    }>,
    StructWithRest<
      Struct<{
        readonly type: Literals<
          readonly [
            "apply_patch",
            "code_interpreter",
            "file_search",
            "image_generation",
            "local_shell",
            "mcp",
            "shell",
            "web_search",
            "web_search_preview",
          ]
        >;
      }>,
      readonly [$Record<String, Unknown>]
    >,
  ]
>;

ToolChoice

Added in v4.0.0 Source

Schema for selecting whether and which tools the model may call in a Responses request.

When to use

Use when validating or encoding the tool_choice field that constrains model tool use separately from the tool definitions themselves.

Details

Accepted forms are "none", "auto", "required", an allowed-tools set, a named function or custom tool, or a provider-defined tool choice.

See

Tool for tool definitions referenced by tool choices
CreateResponse for the request schema that consumes tool_choice

Signature

declare const ToolChoice: Union<
  readonly [
    Literals<readonly ["none", "auto", "required"]>,
    Struct<{
      readonly mode: Literals<readonly ["auto", "required"]>;
      readonly tools: $Array<$Record<String, Unknown>>;
      readonly type: Literal<"allowed_tools">;
    }>,
    Struct<{
      readonly name: String;
      readonly type: Literal<"function">;
    }>,
    Struct<{
      readonly name: String;
      readonly type: Literal<"custom">;
    }>,
    StructWithRest<
      Struct<{
        readonly type: Literals<
          readonly [
            "apply_patch",
            "code_interpreter",
            "file_search",
            "image_generation",
            "local_shell",
            "mcp",
            "shell",
            "web_search",
            "web_search_preview",
          ]
        >;
      }>,
      readonly [$Record<String, Unknown>]
    >,
  ]
>;