heymegabyte/agent-skills / skills/openai
openai
VerifiedOpenAI API API skill — auto-forged from OpenAPI 2.3.0. The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference for more details.
types.ts
View on GitHub// Auto-generated by forge-skill-from-openapi
// API: openai
// Source: OpenAI API v2.3.0
// DO NOT EDIT — re-run forge to regenerate
export type AddUploadPartRequest = {
"data": string;
};
/** Represents an individual Admin API key in an org. */
export type AdminApiKey = {
"object": "organization.admin_api_key";
"id": string;
"name"?: Record<string, unknown>;
"redacted_value": string;
"created_at": number;
"last_used_at"?: Record<string, unknown>;
"owner": {
"type"?: string;
"object"?: string;
"id"?: string;
"name"?: string;
"created_at"?: number;
"role"?: string;
};
};
export type AdminApiKeyCreateResponse = Record<string, unknown>;
export type ApiKeyList = {
"object": "list";
"data": Array<AdminApiKey>;
"has_more": boolean;
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
};
/** Detailed information about a role assignment entry returned when listing assignments. */
export type AssignedRoleDetails = {
"id": string;
"name": string;
"permissions": Array<string>;
"resource_type": string;
"predefined_role": boolean;
"description": Record<string, unknown>;
"created_at": Record<string, unknown>;
"updated_at": Record<string, unknown>;
"created_by": Record<string, unknown>;
"created_by_user_obj": Record<string, unknown>;
"metadata": Record<string, unknown>;
};
/** Represents an `assistant` that can call the model and use tools. */
export type AssistantObject = {
"id": string;
"object": "assistant";
"created_at": number;
"name": Record<string, unknown>;
"description": Record<string, unknown>;
"model": string;
"instructions": Record<string, unknown>;
"tools": Array<Record<string, unknown>>;
"tool_resources"?: Record<string, unknown>;
"metadata": Metadata;
"temperature"?: Record<string, unknown>;
"top_p"?: Record<string, unknown>;
"response_format"?: Record<string, unknown>;
};
/** Represents an event emitted when streaming a Run.
Each event in a server-sent events stream has an `event` and `data` property:
```
event: thread.created
data: {"id": "thread_123", "object": "thread", ...}
```
We emit events whenever a new object is created, transitions to a new state, or is being
streamed in parts (deltas). For example, we emit `thread.run.created` when a new run
is created, `thread.run.completed` when a run completes, and so on. When an Assistant chooses
to create a message during a run, we emit a `thread.message.created event`, a
`thread.message.in_progress` event, many `thread.message.delta` events, and finally a
`thread.message.completed` event.
We may add additional events over time, so we recommend handling unknown events gracefully
in your code. See the [Assistants API quickstart](/docs/assistants/overview) to learn how to
integrate the Assistants API with streaming.
*/
export type AssistantStreamEvent = Record<string, unknown>;
export type AssistantSupportedModels = "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-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" | "o3-mini" | "o3-mini-2025-01-31" | "o1" | "o1-2024-12-17" | "gpt-4o" | "gpt-4o-2024-11-20" | "gpt-4o-2024-08-06" | "gpt-4o-2024-05-13" | "gpt-4o-mini" | "gpt-4o-mini-2024-07-18" | "gpt-4.5-preview" | "gpt-4.5-preview-2025-02-27" | "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-0613" | "gpt-3.5-turbo-1106" | "gpt-3.5-turbo-0125" | "gpt-3.5-turbo-16k-0613";
export type AssistantToolsCode = {
"type": "code_interpreter";
};
export type AssistantToolsFileSearch = {
"type": "file_search";
"file_search"?: {
"max_num_results"?: number;
"ranking_options"?: FileSearchRankingOptions;
};
};
export type AssistantToolsFileSearchTypeOnly = {
"type": "file_search";
};
export type AssistantToolsFunction = {
"type": "function";
"function": FunctionObject;
};
/** Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.
Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).
Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.
**Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.
*/
export type AssistantsApiResponseFormatOption = Record<string, unknown>;
/** Controls which (if any) tool is called by the model.
`none` means the model will not call any tools and instead generates a message.
`auto` is the default value and means the model can pick between generating a message or calling one or more tools.
`required` means the model must call one or more tools before responding to the user.
Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.
*/
export type AssistantsApiToolChoiceOption = Record<string, unknown>;
/** Specifies a tool the model should use. Use to force the model to call a specific tool. */
export type AssistantsNamedToolChoice = {
"type": "function" | "code_interpreter" | "file_search";
"function"?: {
"name": string;
};
};
/** The format of the output, in one of these options: `json`, `text`, `srt`, `verbose_json`, `vtt`, or `diarized_json`. For `gpt-4o-transcribe` and `gpt-4o-mini-transcribe`, the only supported format is `json`. For `gpt-4o-transcribe-diarize`, the supported formats are `json`, `text`, and `diarized_json`, with `diarized_json` required to receive speaker annotations.
*/
export type AudioResponseFormat = "json" | "text" | "srt" | "verbose_json" | "vtt" | "diarized_json";
export type AudioTranscription = {
"model"?: Record<string, unknown>;
"language"?: string;
"prompt"?: string;
"delay"?: "minimal" | "low" | "medium" | "high" | "xhigh";
};
export type AudioTranscriptionResponse = {
"model"?: Record<string, unknown>;
"language"?: string;
"prompt"?: string;
};
/** A log of a user action or configuration change within this organization. */
export type AuditLog = {
"id": string;
"type": AuditLogEventType;
"effective_at": number;
"project"?: {
"id"?: string;
"name"?: string;
};
"actor"?: Record<string, unknown>;
"api_key.created"?: {
"id"?: string;
"data"?: {
"scopes"?: Array<string>;
};
};
"api_key.updated"?: {
"id"?: string;
"changes_requested"?: {
"scopes"?: Array<string>;
};
};
"api_key.deleted"?: {
"id"?: string;
};
"checkpoint.permission.created"?: {
"id"?: string;
"data"?: {
"project_id"?: string;
"fine_tuned_model_checkpoint"?: string;
};
};
"checkpoint.permission.deleted"?: {
"id"?: string;
};
"external_key.registered"?: {
"id"?: string;
"data"?: Record<string, unknown>;
};
"external_key.removed"?: {
"id"?: string;
};
"group.created"?: {
"id"?: string;
"data"?: {
"group_name"?: string;
};
};
"group.updated"?: {
"id"?: string;
"changes_requested"?: {
"group_name"?: string;
};
};
"group.deleted"?: {
"id"?: string;
};
"scim.enabled"?: {
"id"?: string;
};
"scim.disabled"?: {
"id"?: string;
};
"invite.sent"?: {
"id"?: string;
"data"?: {
"email"?: string;
"role"?: string;
};
};
"invite.accepted"?: {
"id"?: string;
};
"invite.deleted"?: {
"id"?: string;
};
"ip_allowlist.created"?: {
"id"?: string;
"name"?: string;
"allowed_ips"?: Array<string>;
};
"ip_allowlist.updated"?: {
"id"?: string;
"allowed_ips"?: Array<string>;
};
"ip_allowlist.deleted"?: {
"id"?: string;
"name"?: string;
"allowed_ips"?: Array<string>;
};
"ip_allowlist.config.activated"?: {
"configs"?: Array<{
"id"?: string;
"name"?: string;
}>;
};
"ip_allowlist.config.deactivated"?: {
"configs"?: Array<{
"id"?: string;
"name"?: string;
}>;
};
"login.succeeded"?: Record<string, unknown>;
"login.failed"?: {
"error_code"?: string;
"error_message"?: string;
};
"logout.succeeded"?: Record<string, unknown>;
"logout.failed"?: {
"error_code"?: string;
"error_message"?: string;
};
"organization.updated"?: {
"id"?: string;
"changes_requested"?: {
"title"?: string;
"description"?: string;
"name"?: string;
"threads_ui_visibility"?: string;
"usage_dashboard_visibility"?: string;
"api_call_logging"?: string;
"api_call_logging_project_ids"?: string;
};
};
"project.created"?: {
"id"?: string;
"data"?: {
"name"?: string;
"title"?: string;
};
};
"project.updated"?: {
"id"?: string;
"changes_requested"?: {
"title"?: string;
};
};
"project.archived"?: {
"id"?: string;
};
"project.deleted"?: {
"id"?: string;
};
"rate_limit.updated"?: {
"id"?: string;
"changes_requested"?: {
"max_requests_per_1_minute"?: number;
"max_tokens_per_1_minute"?: number;
"max_images_per_1_minute"?: number;
"max_audio_megabytes_per_1_minute"?: number;
"max_requests_per_1_day"?: number;
"batch_1_day_max_input_tokens"?: number;
};
};
"rate_limit.deleted"?: {
"id"?: string;
};
"role.created"?: {
"id"?: string;
"role_name"?: string;
"permissions"?: Array<string>;
"resource_type"?: string;
"resource_id"?: string;
};
"role.updated"?: {
"id"?: string;
"changes_requested"?: {
"role_name"?: string;
"resource_id"?: string;
"resource_type"?: string;
"permissions_added"?: Array<string>;
"permissions_removed"?: Array<string>;
"description"?: string;
"metadata"?: Record<string, unknown>;
};
};
"role.deleted"?: {
"id"?: string;
};
"role.assignment.created"?: {
"id"?: string;
"principal_id"?: string;
"principal_type"?: string;
"resource_id"?: string;
"resource_type"?: string;
};
"role.assignment.deleted"?: {
"id"?: string;
"principal_id"?: string;
"principal_type"?: string;
"resource_id"?: string;
"resource_type"?: string;
};
"service_account.created"?: {
"id"?: string;
"data"?: {
"role"?: string;
};
};
"service_account.updated"?: {
"id"?: string;
"changes_requested"?: {
"role"?: string;
};
};
"service_account.deleted"?: {
"id"?: string;
};
"user.added"?: {
"id"?: string;
"data"?: {
"role"?: string;
};
};
"user.updated"?: {
"id"?: string;
"changes_requested"?: {
"role"?: string;
};
};
"user.deleted"?: {
"id"?: string;
};
"certificate.created"?: {
"id"?: string;
"name"?: string;
};
"certificate.updated"?: {
"id"?: string;
"name"?: string;
};
"certificate.deleted"?: {
"id"?: string;
"name"?: string;
"certificate"?: string;
};
"certificates.activated"?: {
"certificates"?: Array<{
"id"?: string;
"name"?: string;
}>;
};
"certificates.deactivated"?: {
"certificates"?: Array<{
"id"?: string;
"name"?: string;
}>;
};
};
/** The actor who performed the audit logged action. */
export type AuditLogActor = {
"type"?: "session" | "api_key";
"session"?: AuditLogActorSession;
"api_key"?: AuditLogActorApiKey;
};
/** The API Key used to perform the audit logged action. */
export type AuditLogActorApiKey = {
"id"?: string;
"type"?: "user" | "service_account";
"user"?: AuditLogActorUser;
"service_account"?: AuditLogActorServiceAccount;
};
/** The service account that performed the audit logged action. */
export type AuditLogActorServiceAccount = {
"id"?: string;
};
/** The session in which the audit logged action was performed. */
export type AuditLogActorSession = {
"user"?: AuditLogActorUser;
"ip_address"?: string;
};
/** The user who performed the audit logged action. */
export type AuditLogActorUser = {
"id"?: string;
"email"?: string;
};
/** The event type. */
export type AuditLogEventType = "api_key.created" | "api_key.updated" | "api_key.deleted" | "certificate.created" | "certificate.updated" | "certificate.deleted" | "certificates.activated" | "certificates.deactivated" | "checkpoint.permission.created" | "checkpoint.permission.deleted" | "external_key.registered" | "external_key.removed" | "group.created" | "group.updated" | "group.deleted" | "invite.sent" | "invite.accepted" | "invite.deleted" | "ip_allowlist.created" | "ip_allowlist.updated" | "ip_allowlist.deleted" | "ip_allowlist.config.activated" | "ip_allowlist.config.deactivated" | "login.succeeded" | "login.failed" | "logout.succeeded" | "logout.failed" | "organization.updated" | "project.created" | "project.updated" | "project.archived" | "project.deleted" | "rate_limit.updated" | "rate_limit.deleted" | "resource.deleted" | "tunnel.created" | "tunnel.updated" | "tunnel.deleted" | "role.created" | "role.updated" | "role.deleted" | "role.assignment.created" | "role.assignment.deleted" | "scim.enabled" | "scim.disabled" | "service_account.created" | "service_account.updated" | "service_account.deleted" | "user.added" | "user.updated" | "user.deleted";
/** The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. */
export type AutoChunkingStrategyRequestParam = {
"type": "auto";
};
export type Batch = {
"id": string;
"object": "batch";
"endpoint": string;
"model"?: string;
"errors"?: {
"object"?: string;
"data"?: Array<{
"code"?: string;
"message"?: string;
"param"?: Record<string, unknown>;
"line"?: Record<string, unknown>;
}>;
};
"input_file_id": string;
"completion_window": string;
"status": "validating" | "failed" | "in_progress" | "finalizing" | "completed" | "expired" | "cancelling" | "cancelled";
"output_file_id"?: string;
"error_file_id"?: string;
"created_at": number;
"in_progress_at"?: number;
"expires_at"?: number;
"finalizing_at"?: number;
"completed_at"?: number;
"failed_at"?: number;
"expired_at"?: number;
"cancelling_at"?: number;
"cancelled_at"?: number;
"request_counts"?: {
"total": number;
"completed": number;
"failed": number;
};
"usage"?: {
"input_tokens": number;
"input_tokens_details": {
"cached_tokens": number;
};
"output_tokens": number;
"output_tokens_details": {
"reasoning_tokens": number;
};
"total_tokens": number;
};
"metadata"?: Metadata;
};
/** The expiration policy for the output and/or error file that are generated for a batch. */
export type BatchFileExpirationAfter = {
"anchor": "created_at";
"seconds": number;
};
/** Represents an individual `certificate` uploaded to the organization. */
export type Certificate = {
"object": "certificate" | "organization.certificate" | "organization.project.certificate";
"id": string;
"name": Record<string, unknown>;
"created_at": number;
"certificate_details": {
"valid_at"?: number;
"expires_at"?: number;
"content"?: string;
};
"active"?: boolean;
};
/** Constrains the tools available to the model to a pre-defined set.
*/
export type ChatCompletionAllowedTools = {
"mode": "auto" | "required";
"tools": Array<Record<string, Record<string, unknown>>>;
};
/** Constrains the tools available to the model to a pre-defined set.
*/
export type ChatCompletionAllowedToolsChoice = {
"type": "allowed_tools";
"allowed_tools": ChatCompletionAllowedTools;
};
export type ChatCompletionDeleted = {
"object": "chat.completion.deleted";
"id": string;
"deleted": boolean;
};
/** Specifying a particular function via `{"name": "my_function"}` forces the model to call that function.
*/
export type ChatCompletionFunctionCallOption = {
"name": string;
};
export type ChatCompletionFunctions = {
"description"?: string;
"name": string;
"parameters"?: FunctionParameters;
};
/** An object representing a list of Chat Completions.
*/
export type ChatCompletionList = {
"object": "list";
"data": Array<CreateChatCompletionResponse>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
/** A call to a custom tool created by the model.
*/
export type ChatCompletionMessageCustomToolCall = {
"id": string;
"type": "custom";
"custom": {
"name": string;
"input": string;
};
};
/** An object representing a list of chat completion messages.
*/
export type ChatCompletionMessageList = {
"object": "list";
"data": Array<Record<string, unknown>>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
/** A call to a function tool created by the model.
*/
export type ChatCompletionMessageToolCall = {
"id": string;
"type": "function";
"function": {
"name": string;
"arguments": string;
};
};
export type ChatCompletionMessageToolCallChunk = {
"index": number;
"id"?: string;
"type"?: "function";
"function"?: {
"name"?: string;
"arguments"?: string;
};
};
/** The tool calls generated by the model, such as function calls. */
export type ChatCompletionMessageToolCalls = Array<Record<string, unknown>>;
export type ChatCompletionModalities = Record<string, unknown>;
/** Specifies a tool the model should use. Use to force the model to call a specific function. */
export type ChatCompletionNamedToolChoice = {
"type": "function";
"function": {
"name": string;
};
};
/** Specifies a tool the model should use. Use to force the model to call a specific custom tool. */
export type ChatCompletionNamedToolChoiceCustom = {
"type": "custom";
"custom": {
"name": string;
};
};
/** Messages sent by the model in response to user messages.
*/
export type ChatCompletionRequestAssistantMessage = {
"content"?: Record<string, unknown>;
"refusal"?: Record<string, unknown>;
"role": "assistant";
"name"?: string;
"audio"?: Record<string, unknown>;
"tool_calls"?: ChatCompletionMessageToolCalls;
"function_call"?: Record<string, unknown>;
};
export type ChatCompletionRequestAssistantMessageContentPart = Record<string, unknown>;
/** Developer-provided instructions that the model should follow, regardless of
messages sent by the user. With o1 models and newer, `developer` messages
replace the previous `system` messages.
*/
export type ChatCompletionRequestDeveloperMessage = {
"content": Record<string, unknown>;
"role": "developer";
"name"?: string;
};
export type ChatCompletionRequestFunctionMessage = {
"role": "function";
"content": Record<string, unknown>;
"name": string;
};
export type ChatCompletionRequestMessage = Record<string, unknown>;
/** Learn about [audio inputs](/docs/guides/audio).
*/
export type ChatCompletionRequestMessageContentPartAudio = {
"type": "input_audio";
"input_audio": {
"data": string;
"format": "wav" | "mp3";
};
};
/** Learn about [file inputs](/docs/guides/text) for text generation.
*/
export type ChatCompletionRequestMessageContentPartFile = {
"type": "file";
"file": {
"filename"?: string;
"file_data"?: string;
"file_id"?: string;
};
};
/** Learn about [image inputs](/docs/guides/vision).
*/
export type ChatCompletionRequestMessageContentPartImage = {
"type": "image_url";
"image_url": {
"url": string;
"detail"?: "auto" | "low" | "high";
};
};
export type ChatCompletionRequestMessageContentPartRefusal = {
"type": "refusal";
"refusal": string;
};
/** Learn about [text inputs](/docs/guides/text-generation).
*/
export type ChatCompletionRequestMessageContentPartText = {
"type": "text";
"text": string;
};
/** Developer-provided instructions that the model should follow, regardless of
messages sent by the user. With o1 models and newer, use `developer` messages
for this purpose instead.
*/
export type ChatCompletionRequestSystemMessage = {
"content": Record<string, unknown>;
"role": "system";
"name"?: string;
};
export type ChatCompletionRequestSystemMessageContentPart = Record<string, unknown>;
export type ChatCompletionRequestToolMessage = {
"role": "tool";
"content": Record<string, unknown>;
"tool_call_id": string;
};
export type ChatCompletionRequestToolMessageContentPart = Record<string, unknown>;
/** Messages sent by an end user, containing prompts or additional context
information.
*/
export type ChatCompletionRequestUserMessage = {
"content": Record<string, unknown>;
"role": "user";
"name"?: string;
};
export type ChatCompletionRequestUserMessageContentPart = Record<string, unknown>;
/** A chat completion message generated by the model. */
export type ChatCompletionResponseMessage = {
"content": Record<string, unknown>;
"refusal": Record<string, unknown>;
"tool_calls"?: ChatCompletionMessageToolCalls;
"annotations"?: Array<{
"type": "url_citation";
"url_citation": {
"end_index": number;
"start_index": number;
"url": string;
"title": string;
};
}>;
"role": "assistant";
"function_call"?: {
"arguments": string;
"name": string;
};
"audio"?: Record<string, unknown>;
};
/** The role of the author of a message */
export type ChatCompletionRole = "developer" | "system" | "user" | "assistant" | "tool" | "function";
export type ChatCompletionStreamOptions = Record<string, unknown>;
/** A chat completion delta generated by streamed model responses. */
export type ChatCompletionStreamResponseDelta = {
"content"?: Record<string, unknown>;
"function_call"?: {
"arguments"?: string;
"name"?: string;
};
"tool_calls"?: Array<ChatCompletionMessageToolCallChunk>;
"role"?: "developer" | "system" | "user" | "assistant" | "tool";
"refusal"?: Record<string, unknown>;
};
export type ChatCompletionTokenLogprob = {
"token": string;
"logprob": number;
"bytes": Record<string, unknown>;
"top_logprobs": Array<{
"token": string;
"logprob": number;
"bytes": Record<string, unknown>;
}>;
};
/** A function tool that can be used to generate a response.
*/
export type ChatCompletionTool = {
"type": "function";
"function": FunctionObject;
};
/** Controls which (if any) tool is called by the model.
`none` means the model will not call any tool and instead generates a message.
`auto` means the model can pick between generating a message or calling one or more tools.
`required` means the model must call one or more tools.
Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.
`none` is the default when no tools are present. `auto` is the default if tools are present.
*/
export type ChatCompletionToolChoiceOption = Record<string, unknown>;
/** The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. */
export type ChunkingStrategyRequestParam = Record<string, unknown>;
/** The output of a code interpreter tool call that is a file.
*/
export type CodeInterpreterFileOutput = {
"type": "files";
"files": Array<{
"mime_type": string;
"file_id": string;
}>;
};
/** The output of a code interpreter tool call that is text.
*/
export type CodeInterpreterTextOutput = {
"type": "logs";
"logs": string;
};
/** A tool that runs Python code to help generate a response to a prompt.
*/
export type CodeInterpreterTool = {
"type": "code_interpreter";
"container": Record<string, unknown>;
};
/** A tool call to run code.
*/
export type CodeInterpreterToolCall = {
"type": "code_interpreter_call";
"id": string;
"status": "in_progress" | "completed" | "incomplete" | "interpreting" | "failed";
"container_id": string;
"code": Record<string, unknown>;
"outputs": Record<string, unknown>;
};
/** A filter used to compare a specified attribute key to a given value using a defined comparison operation.
*/
export type ComparisonFilter = {
"type": "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin";
"key": string;
"value": Record<string, unknown>;
};
export type CompleteUploadRequest = {
"part_ids": Array<string>;
"md5"?: string;
};
/** Usage statistics for the completion request. */
export type CompletionUsage = {
"completion_tokens": number;
"prompt_tokens": number;
"total_tokens": number;
"completion_tokens_details"?: {
"accepted_prediction_tokens"?: number;
"audio_tokens"?: number;
"reasoning_tokens"?: number;
"rejected_prediction_tokens"?: number;
};
"prompt_tokens_details"?: {
"audio_tokens"?: number;
"cached_tokens"?: number;
};
};
/** Combine multiple filters using `and` or `or`. */
export type CompoundFilter = {
"type": "and" | "or";
"filters": Array<Record<string, unknown>>;
};
export type ComputerAction = Record<string, unknown>;
/** Flattened batched actions for `computer_use`. Each action includes an
`type` discriminator and action-specific fields.
*/
export type ComputerActionList = Array<ComputerAction>;
/** A computer screenshot image used with the computer use tool.
*/
export type ComputerScreenshotImage = {
"type": "computer_screenshot";
"image_url"?: string;
"file_id"?: string;
};
/** A tool call to a computer use tool. See the
[computer use guide](/docs/guides/tools-computer-use) for more information.
*/
export type ComputerToolCall = {
"type": "computer_call";
"id": string;
"call_id": string;
"action"?: ComputerAction;
"actions"?: ComputerActionList;
"pending_safety_checks": Array<ComputerCallSafetyCheckParam>;
"status": "in_progress" | "completed" | "incomplete";
};
/** The output of a computer tool call.
*/
export type ComputerToolCallOutput = {
"type": "computer_call_output";
"id"?: string;
"call_id": string;
"acknowledged_safety_checks"?: Array<ComputerCallSafetyCheckParam>;
"output": ComputerScreenshotImage;
"status"?: "in_progress" | "completed" | "incomplete";
};
export type ComputerToolCallOutputResource = Record<string, unknown>;
export type ContainerFileListResource = {
"object": "list";
"data": Array<ContainerFileResource>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
export type ContainerFileResource = {
"id": string;
"object": string;
"container_id": string;
"created_at": number;
"bytes": number;
"path": string;
"source": string;
};
export type ContainerListResource = {
"object": "list";
"data": Array<ContainerResource>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
export type ContainerResource = {
"id": string;
"object": string;
"name": string;
"created_at": number;
"status": string;
"last_active_at"?: number;
"expires_after"?: {
"anchor"?: "last_active_at";
"minutes"?: number;
};
"memory_limit"?: "1g" | "4g" | "16g" | "64g";
"network_policy"?: {
"type": "allowlist" | "disabled";
"allowed_domains"?: Array<string>;
};
};
/** Multi-modal input and output contents.
*/
export type Content = Record<string, unknown>;
/** A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](/docs/api-reference/responses/object#responses/object-output). */
export type ConversationItem = Record<string, unknown>;
/** A list of Conversation items. */
export type ConversationItemList = {
"object": "list";
"data": Array<ConversationItem>;
"has_more": boolean;
"first_id": string;
"last_id": string;
};
/** The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request.
Input items and output items from this response are automatically added to this conversation after this response completes.
*/
export type ConversationParam = Record<string, unknown>;
/** The aggregated costs details of the specific time bucket. */
export type CostsResult = {
"object": "organization.costs.result";
"amount"?: {
"value"?: number;
"currency"?: string;
};
"line_item"?: Record<string, unknown>;
"project_id"?: Record<string, unknown>;
"api_key_id"?: Record<string, unknown>;
"quantity"?: Record<string, unknown>;
};
export type CreateAssistantRequest = {
"model": Record<string, unknown>;
"name"?: Record<string, unknown>;
"description"?: Record<string, unknown>;
"instructions"?: Record<string, unknown>;
"reasoning_effort"?: ReasoningEffort;
"tools"?: Array<Record<string, unknown>>;
"tool_resources"?: Record<string, unknown>;
"metadata"?: Metadata;
"temperature"?: Record<string, unknown>;
"top_p"?: Record<string, unknown>;
"response_format"?: Record<string, unknown>;
};
export type CreateChatCompletionRequest = Record<string, unknown>;
/** Represents a chat completion response returned by model, based on the provided input. */
export type CreateChatCompletionResponse = {
"id": string;
"choices": Array<{
"finish_reason": "stop" | "length" | "tool_calls" | "content_filter" | "function_call";
"index": number;
"message": ChatCompletionResponseMessage;
"logprobs": Record<string, unknown>;
}>;
"created": number;
"model": string;
"service_tier"?: ServiceTier;
"system_fingerprint"?: string;
"object": "chat.completion";
"usage"?: CompletionUsage;
};
/** Represents a streamed chunk of a chat completion response returned
by the model, based on the provided input.
[Learn more](/docs/guides/streaming-responses).
*/
export type CreateChatCompletionStreamResponse = {
"id": string;
"choices": Array<{
"delta": ChatCompletionStreamResponseDelta;
"logprobs"?: {
"content": Array<ChatCompletionTokenLogprob>;
"refusal": Array<ChatCompletionTokenLogprob>;
};
"finish_reason": "stop" | "length" | "tool_calls" | "content_filter" | "function_call";
"index": number;
}>;
"created": number;
"model": string;
"service_tier"?: ServiceTier;
"system_fingerprint"?: string;
"object": "chat.completion.chunk";
"usage"?: CompletionUsage;
};
export type CreateCompletionRequest = {
"model": Record<string, unknown>;
"prompt": Record<string, unknown>;
"best_of"?: number;
"echo"?: boolean;
"frequency_penalty"?: number;
"logit_bias"?: Record<string, number>;
"logprobs"?: number;
"max_tokens"?: number;
"n"?: number;
"presence_penalty"?: number;
"seed"?: number;
"stop"?: StopConfiguration;
"stream"?: boolean;
"stream_options"?: ChatCompletionStreamOptions;
"suffix"?: string;
"temperature"?: number;
"top_p"?: number;
"user"?: string;
};
/** Represents a completion response from the API. Note: both the streamed and non-streamed response objects share the same shape (unlike the chat endpoint).
*/
export type CreateCompletionResponse = {
"id": string;
"choices": Array<{
"finish_reason": "stop" | "length" | "content_filter";
"index": number;
"logprobs": Record<string, unknown>;
"text": string;
}>;
"created": number;
"model": string;
"system_fingerprint"?: string;
"object": "text_completion";
"usage"?: CompletionUsage;
};
export type CreateContainerBody = {
"name": string;
"file_ids"?: Array<string>;
"expires_after"?: {
"anchor": "last_active_at";
"minutes": number;
};
"skills"?: Array<Record<string, unknown>>;
"memory_limit"?: "1g" | "4g" | "16g" | "64g";
"network_policy"?: Record<string, unknown>;
};
export type CreateContainerFileBody = {
"file_id"?: string;
"file"?: string;
};
export type CreateEmbeddingRequest = {
"input": Record<string, unknown>;
"model": Record<string, unknown>;
"encoding_format"?: "float" | "base64";
"dimensions"?: number;
"user"?: string;
};
export type CreateEmbeddingResponse = {
"data": Array<Embedding>;
"model": string;
"object": "list";
"usage": {
"prompt_tokens": number;
"total_tokens": number;
};
};
/** A CompletionsRunDataSource object describing a model sampling configuration.
*/
export type CreateEvalCompletionsRunDataSource = {
"type": "completions";
"input_messages"?: Record<string, unknown>;
"sampling_params"?: {
"reasoning_effort"?: ReasoningEffort;
"temperature"?: number;
"max_completion_tokens"?: number;
"top_p"?: number;
"seed"?: number;
"response_format"?: Record<string, unknown>;
"tools"?: Array<ChatCompletionTool>;
};
"model"?: string;
"source": Record<string, unknown>;
};
/** A CustomDataSourceConfig object that defines the schema for the data source used for the evaluation runs.
This schema is used to define the shape of the data that will be:
- Used to define your testing criteria and
- What data is required when creating a run
*/
export type CreateEvalCustomDataSourceConfig = {
"type": "custom";
"item_schema": Record<string, Record<string, unknown>>;
"include_sample_schema"?: boolean;
};
/** A chat message that makes up the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}. */
export type CreateEvalItem = Record<string, unknown>;
/** A JsonlRunDataSource object with that specifies a JSONL file that matches the eval
*/
export type CreateEvalJsonlRunDataSource = {
"type": "jsonl";
"source": Record<string, unknown>;
};
/** A LabelModelGrader object which uses a model to assign labels to each item
in the evaluation.
*/
export type CreateEvalLabelModelGrader = {
"type": "label_model";
"name": string;
"model": string;
"input": Array<CreateEvalItem>;
"labels": Array<string>;
"passing_labels": Array<string>;
};
/** A data source config which specifies the metadata property of your logs query.
This is usually metadata like `usecase=chatbot` or `prompt-version=v2`, etc.
*/
export type CreateEvalLogsDataSourceConfig = {
"type": "logs";
"metadata"?: Record<string, Record<string, unknown>>;
};
export type CreateEvalRequest = {
"name"?: string;
"metadata"?: Metadata;
"data_source_config": Record<string, unknown>;
"testing_criteria": Array<Record<string, unknown>>;
};
/** A ResponsesRunDataSource object describing a model sampling configuration.
*/
export type CreateEvalResponsesRunDataSource = {
"type": "responses";
"input_messages"?: Record<string, unknown>;
"sampling_params"?: {
"reasoning_effort"?: ReasoningEffort;
"temperature"?: number;
"max_completion_tokens"?: number;
"top_p"?: number;
"seed"?: number;
"tools"?: Array<Tool>;
"text"?: {
"format"?: TextResponseFormatConfiguration;
};
};
"model"?: string;
"source": Record<string, unknown>;
};
export type CreateEvalRunRequest = {
"name"?: string;
"metadata"?: Metadata;
"data_source": Record<string, unknown>;
};
/** Deprecated in favor of LogsDataSourceConfig.
*/
export type CreateEvalStoredCompletionsDataSourceConfig = {
"type": "stored_completions";
"metadata"?: Record<string, Record<string, unknown>>;
};
export type CreateFileRequest = {
"file": string;
"purpose": "assistants" | "batch" | "fine-tune" | "vision" | "user_data" | "evals";
"expires_after"?: FileExpirationAfter;
};
export type CreateFineTuningCheckpointPermissionRequest = {
"project_ids": Array<string>;
};
export type CreateFineTuningJobRequest = {
"model": Record<string, unknown>;
"training_file": string;
"hyperparameters"?: {
"batch_size"?: Record<string, unknown>;
"learning_rate_multiplier"?: Record<string, unknown>;
"n_epochs"?: Record<string, unknown>;
};
"suffix"?: string;
"validation_file"?: string;
"integrations"?: Array<{
"type": Record<string, unknown>;
"wandb": {
"project": string;
"name"?: string;
"entity"?: string;
"tags"?: Array<string>;
};
}>;
"seed"?: number;
"method"?: FineTuneMethod;
"metadata"?: Metadata;
};
/** Request payload for creating a new group in the organization. */
export type CreateGroupBody = {
"name": string;
};
/** Request payload for adding a user to a group. */
export type CreateGroupUserBody = {
"user_id": string;
};
export type CreateImageEditRequest = {
"image": Record<string, unknown>;
"prompt": string;
"mask"?: string;
"background"?: "transparent" | "opaque" | "auto";
"model"?: Record<string, unknown>;
"n"?: number;
"size"?: Record<string, unknown>;
"response_format"?: "url" | "b64_json";
"output_format"?: "png" | "jpeg" | "webp";
"output_compression"?: number;
"user"?: string;
"input_fidelity"?: Record<string, unknown>;
"stream"?: boolean;
"partial_images"?: PartialImages;
"quality"?: "standard" | "low" | "medium" | "high" | "auto";
};
export type CreateImageRequest = {
"prompt": string;
"model"?: Record<string, unknown>;
"n"?: number;
"quality"?: "standard" | "hd" | "low" | "medium" | "high" | "auto";
"response_format"?: "url" | "b64_json";
"output_format"?: "png" | "jpeg" | "webp";
"output_compression"?: number;
"stream"?: boolean;
"partial_images"?: PartialImages;
"size"?: Record<string, unknown>;
"moderation"?: "low" | "auto";
"background"?: "transparent" | "opaque" | "auto";
"style"?: "vivid" | "natural";
"user"?: string;
};
export type CreateImageVariationRequest = {
"image": string;
"model"?: Record<string, unknown>;
"n"?: number;
"response_format"?: "url" | "b64_json";
"size"?: "256x256" | "512x512" | "1024x1024";
"user"?: string;
};
export type CreateMessageRequest = {
"role": "user" | "assistant";
"content": Record<string, unknown>;
"attachments"?: Record<string, unknown>;
"metadata"?: Metadata;
};
export type CreateModelResponseProperties = Record<string, unknown>;
export type CreateModerationRequest = {
"input": Record<string, unknown>;
"model"?: Record<string, unknown>;
};
/** Represents if a given text input is potentially harmful. */
export type CreateModerationResponse = {
"id": string;
"model": string;
"results": Array<{
"flagged": boolean;
"categories": {
"hate": boolean;
"hate/threatening": boolean;
"harassment": boolean;
"harassment/threatening": boolean;
"illicit": Record<string, unknown>;
"illicit/violent": Record<string, unknown>;
"self-harm": boolean;
"self-harm/intent": boolean;
"self-harm/instructions": boolean;
"sexual": boolean;
"sexual/minors": boolean;
"violence": boolean;
"violence/graphic": boolean;
};
"category_scores": {
"hate": number;
"hate/threatening": number;
"harassment": number;
"harassment/threatening": number;
"illicit": number;
"illicit/violent": number;
"self-harm": number;
"self-harm/intent": number;
"self-harm/instructions": number;
"sexual": number;
"sexual/minors": number;
"violence": number;
"violence/graphic": number;
};
"category_applied_input_types": {
"hate": Array<"text">;
"hate/threatening": Array<"text">;
"harassment": Array<"text">;
"harassment/threatening": Array<"text">;
"illicit": Array<"text">;
"illicit/violent": Array<"text">;
"self-harm": Array<"text" | "image">;
"self-harm/intent": Array<"text" | "image">;
"self-harm/instructions": Array<"text" | "image">;
"sexual": Array<"text" | "image">;
"sexual/minors": Array<"text">;
"violence": Array<"text" | "image">;
"violence/graphic": Array<"text" | "image">;
};
}>;
};
export type CreateResponse = Record<string, unknown>;
export type CreateRunRequest = {
"assistant_id": string;
"model"?: Record<string, unknown>;
"reasoning_effort"?: ReasoningEffort;
"instructions"?: string;
"additional_instructions"?: string;
"additional_messages"?: Array<CreateMessageRequest>;
"tools"?: Array<Record<string, unknown>>;
"metadata"?: Metadata;
"temperature"?: number;
"top_p"?: number;
"stream"?: boolean;
"max_prompt_tokens"?: number;
"max_completion_tokens"?: number;
"truncation_strategy"?: Record<string, unknown>;
"tool_choice"?: Record<string, unknown>;
"parallel_tool_calls"?: ParallelToolCalls;
"response_format"?: AssistantsApiResponseFormatOption;
};
export type CreateSpeechRequest = {
"model": Record<string, unknown>;
"input": string;
"instructions"?: string;
"voice": VoiceIdsOrCustomVoice;
"response_format"?: "mp3" | "opus" | "aac" | "flac" | "wav" | "pcm";
"speed"?: number;
"stream_format"?: "sse" | "audio";
};
export type CreateSpeechResponseStreamEvent = Record<string, unknown>;
export type CreateThreadAndRunRequest = {
"assistant_id": string;
"thread"?: CreateThreadRequest;
"model"?: Record<string, unknown>;
"instructions"?: string;
"tools"?: Array<Record<string, unknown>>;
"tool_resources"?: {
"code_interpreter"?: {
"file_ids"?: Array<string>;
};
"file_search"?: {
"vector_store_ids"?: Array<string>;
};
};
"metadata"?: Metadata;
"temperature"?: number;
"top_p"?: number;
"stream"?: boolean;
"max_prompt_tokens"?: number;
"max_completion_tokens"?: number;
"truncation_strategy"?: Record<string, unknown>;
"tool_choice"?: Record<string, unknown>;
"parallel_tool_calls"?: ParallelToolCalls;
"response_format"?: AssistantsApiResponseFormatOption;
};
/** Options to create a new thread. If no thread is provided when running a
request, an empty thread will be created.
*/
export type CreateThreadRequest = {
"messages"?: Array<CreateMessageRequest>;
"tool_resources"?: Record<string, unknown>;
"metadata"?: Metadata;
};
export type CreateTranscriptionRequest = {
"file": string;
"model": Record<string, unknown>;
"language"?: string;
"prompt"?: string;
"response_format"?: AudioResponseFormat;
"temperature"?: number;
"include"?: Array<TranscriptionInclude>;
"timestamp_granularities"?: Array<"word" | "segment">;
"stream"?: Record<string, unknown>;
"chunking_strategy"?: Record<string, unknown>;
"known_speaker_names"?: Array<string>;
"known_speaker_references"?: Array<string>;
};
/** Represents a diarized transcription response returned by the model, including the combined transcript and speaker-segment annotations.
*/
export type CreateTranscriptionResponseDiarizedJson = {
"task": "transcribe";
"duration": number;
"text": string;
"segments": Array<TranscriptionDiarizedSegment>;
"usage"?: Record<string, unknown>;
};
/** Represents a transcription response returned by model, based on the provided input. */
export type CreateTranscriptionResponseJson = {
"text": string;
"logprobs"?: Array<{
"token"?: string;
"logprob"?: number;
"bytes"?: Array<number>;
}>;
"usage"?: Record<string, unknown>;
};
export type CreateTranscriptionResponseStreamEvent = Record<string, unknown>;
/** Represents a verbose json transcription response returned by model, based on the provided input. */
export type CreateTranscriptionResponseVerboseJson = {
"language": string;
"duration": number;
"text": string;
"words"?: Array<TranscriptionWord>;
"segments"?: Array<TranscriptionSegment>;
"usage"?: TranscriptTextUsageDuration;
};
export type CreateTranslationRequest = {
"file": string;
"model": Record<string, unknown>;
"prompt"?: string;
"response_format"?: "json" | "text" | "srt" | "verbose_json" | "vtt";
"temperature"?: number;
};
export type CreateTranslationResponseJson = {
"text": string;
};
export type CreateTranslationResponseVerboseJson = {
"language": string;
"duration": number;
"text": string;
"segments"?: Array<TranscriptionSegment>;
};
export type CreateUploadRequest = {
"filename": string;
"purpose": "assistants" | "batch" | "fine-tune" | "vision";
"bytes": number;
"mime_type": string;
"expires_after"?: FileExpirationAfter;
};
export type CreateVectorStoreFileBatchRequest = {
"file_ids"?: Array<string>;
"files"?: Array<CreateVectorStoreFileRequest>;
"chunking_strategy"?: ChunkingStrategyRequestParam;
"attributes"?: VectorStoreFileAttributes;
};
export type CreateVectorStoreFileRequest = {
"file_id": string;
"chunking_strategy"?: ChunkingStrategyRequestParam;
"attributes"?: VectorStoreFileAttributes;
};
export type CreateVectorStoreRequest = {
"file_ids"?: Array<string>;
"name"?: string;
"description"?: string;
"expires_after"?: VectorStoreExpirationAfter;
"chunking_strategy"?: Record<string, unknown>;
"metadata"?: Metadata;
};
export type CreateVoiceConsentRequest = {
"name": string;
"recording": string;
"language": string;
};
export type CreateVoiceRequest = {
"name": string;
"audio_sample": string;
"consent": string;
};
/** A call to a custom tool created by the model.
*/
export type CustomToolCall = {
"type": "custom_tool_call";
"id"?: string;
"call_id": string;
"namespace"?: string;
"name": string;
"input": string;
};
/** The output of a custom tool call from your code, being sent back to the model.
*/
export type CustomToolCallOutput = {
"type": "custom_tool_call_output";
"id"?: string;
"call_id": string;
"output": Record<string, unknown>;
};
export type CustomToolCallOutputResource = Record<string, unknown>;
export type CustomToolCallResource = Record<string, unknown>;
/** A custom tool that processes input using a specified format.
*/
export type CustomToolChatCompletions = {
"type": "custom";
"custom": {
"name": string;
"description"?: string;
"format"?: Record<string, unknown>;
};
};
export type DeleteAssistantResponse = {
"id": string;
"deleted": boolean;
"object": "assistant.deleted";
};
export type DeleteCertificateResponse = {
"object": "certificate.deleted";
"id": string;
};
export type DeleteFileResponse = {
"id": string;
"object": "file";
"deleted": boolean;
};
export type DeleteFineTuningCheckpointPermissionResponse = {
"id": string;
"object": "checkpoint.permission";
"deleted": boolean;
};
export type DeleteMessageResponse = {
"id": string;
"deleted": boolean;
"object": "thread.message.deleted";
};
export type DeleteModelResponse = {
"id": string;
"deleted": boolean;
"object": string;
};
export type DeleteThreadResponse = {
"id": string;
"deleted": boolean;
"object": "thread.deleted";
};
export type DeleteVectorStoreFileResponse = {
"id": string;
"deleted": boolean;
"object": "vector_store.file.deleted";
};
export type DeleteVectorStoreResponse = {
"id": string;
"deleted": boolean;
"object": "vector_store.deleted";
};
export type DeletedConversation = Record<string, unknown>;
/** Confirmation payload returned after unassigning a role. */
export type DeletedRoleAssignmentResource = {
"object": string;
"deleted": boolean;
};
/** Occurs when a stream ends. */
export type DoneEvent = {
"event": "done";
"data": "[DONE]";
};
/** 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 type EasyInputMessage = {
"role": "user" | "assistant" | "system" | "developer";
"content": Record<string, unknown>;
"phase"?: Record<string, unknown>;
"type"?: "message";
};
/** JSON request body for image edits.
Use `images` (array of `ImageRefParam`) instead of multipart `image` uploads.
You can reference images via external URLs, data URLs, or uploaded file IDs.
JSON edits support GPT image models only; DALL-E edits require multipart (`dall-e-2` only).
*/
export type EditImageBodyJsonParam = {
"model"?: Record<string, unknown>;
"images": Array<ImageRefParam>;
"mask"?: ImageRefParam;
"prompt": string;
"n"?: Record<string, unknown>;
"quality"?: Record<string, unknown>;
"input_fidelity"?: Record<string, unknown>;
"size"?: Record<string, unknown>;
"user"?: string;
"output_format"?: Record<string, unknown>;
"output_compression"?: Record<string, unknown>;
"moderation"?: Record<string, unknown>;
"background"?: Record<string, unknown>;
"stream"?: Record<string, unknown>;
"partial_images"?: PartialImages;
};
/** Represents an embedding vector returned by embedding endpoint.
*/
export type Embedding = {
"index": number;
"embedding": Array<number>;
"object": "embedding";
};
export type Error = {
"code": Record<string, unknown>;
"message": string;
"param": Record<string, unknown>;
"type": string;
};
/** Occurs when an [error](/docs/guides/error-codes#api-errors) occurs. This can happen due to an internal server error or a timeout. */
export type ErrorEvent = {
"event": "error";
"data": Error;
};
export type ErrorResponse = {
"error": Error;
};
/** An Eval object with a data source config and testing criteria.
An Eval represents a task to be done for your LLM integration.
Like:
- Improve the quality of my chatbot
- See how well my chatbot handles customer support
- Check if o4-mini is better at my usecase than gpt-4o
*/
export type Eval = {
"object": "eval";
"id": string;
"name": string;
"data_source_config": Record<string, unknown>;
"testing_criteria": Array<Record<string, unknown>>;
"created_at": number;
"metadata": Metadata;
};
/** An object representing an error response from the Eval API.
*/
export type EvalApiError = {
"code": string;
"message": string;
};
/** A CustomDataSourceConfig which specifies the schema of your `item` and optionally `sample` namespaces.
The response schema defines the shape of the data that will be:
- Used to define your testing criteria and
- What data is required when creating a run
*/
export type EvalCustomDataSourceConfig = {
"type": "custom";
"schema": Record<string, Record<string, unknown>>;
};
export type EvalGraderLabelModel = Record<string, unknown>;
export type EvalGraderPython = Record<string, unknown>;
export type EvalGraderScoreModel = Record<string, unknown>;
export type EvalGraderStringCheck = Record<string, unknown>;
export type EvalGraderTextSimilarity = Record<string, unknown>;
/** 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 type EvalItem = {
"role": "user" | "assistant" | "system" | "developer";
"content": EvalItemContent;
"type"?: "message";
};
/** Inputs to the model - can contain template strings. Supports text, output text, input images, and input audio, either as a single item or an array of items.
*/
export type EvalItemContent = Record<string, unknown>;
/** A list of inputs, each of which may be either an input text, output text, input
image, or input audio object.
*/
export type EvalItemContentArray = Array<EvalItemContentItem>;
/** A single content item: input text, output text, input image, or input audio.
*/
export type EvalItemContentItem = Record<string, unknown>;
/** A text output from the model.
*/
export type EvalItemContentOutputText = {
"type": "output_text";
"text": string;
};
/** A text input to the model.
*/
export type EvalItemContentText = string;
/** An image input block used within EvalItem content arrays. */
export type EvalItemInputImage = {
"type": "input_image";
"image_url": string;
"detail"?: string;
};
export type EvalJsonlFileContentSource = {
"type": "file_content";
"content": Array<{
"item": Record<string, Record<string, unknown>>;
"sample"?: Record<string, Record<string, unknown>>;
}>;
};
export type EvalJsonlFileIdSource = {
"type": "file_id";
"id": string;
};
/** An object representing a list of evals.
*/
export type EvalList = {
"object": "list";
"data": Array<Eval>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
/** A LogsDataSourceConfig which specifies the metadata property of your logs query.
This is usually metadata like `usecase=chatbot` or `prompt-version=v2`, etc.
The schema returned by this data source config is used to defined what variables are available in your evals.
`item` and `sample` are both defined when using this data source config.
*/
export type EvalLogsDataSourceConfig = {
"type": "logs";
"metadata"?: Metadata;
"schema": Record<string, Record<string, unknown>>;
};
/** A EvalResponsesSource object describing a run data source configuration.
*/
export type EvalResponsesSource = {
"type": "responses";
"metadata"?: Record<string, unknown>;
"model"?: Record<string, unknown>;
"instructions_search"?: Record<string, unknown>;
"created_after"?: Record<string, unknown>;
"created_before"?: Record<string, unknown>;
"reasoning_effort"?: Record<string, unknown>;
"temperature"?: Record<string, unknown>;
"top_p"?: Record<string, unknown>;
"users"?: Record<string, unknown>;
"tools"?: Record<string, unknown>;
};
/** A schema representing an evaluation run.
*/
export type EvalRun = {
"object": "eval.run";
"id": string;
"eval_id": string;
"status": string;
"model": string;
"name": string;
"created_at": number;
"report_url": string;
"result_counts": {
"total": number;
"errored": number;
"failed": number;
"passed": number;
};
"per_model_usage": Array<{
"model_name": string;
"invocation_count": number;
"prompt_tokens": number;
"completion_tokens": number;
"total_tokens": number;
"cached_tokens": number;
}>;
"per_testing_criteria_results": Array<{
"testing_criteria": string;
"passed": number;
"failed": number;
}>;
"data_source": Record<string, unknown>;
"metadata": Metadata;
"error": EvalApiError;
};
/** An object representing a list of runs for an evaluation.
*/
export type EvalRunList = {
"object": "list";
"data": Array<EvalRun>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
/** A schema representing an evaluation run output item.
*/
export type EvalRunOutputItem = {
"object": "eval.run.output_item";
"id": string;
"run_id": string;
"eval_id": string;
"created_at": number;
"status": string;
"datasource_item_id": number;
"datasource_item": Record<string, Record<string, unknown>>;
"results": Array<EvalRunOutputItemResult>;
"sample": {
"input": Array<{
"role": string;
"content": string;
}>;
"output": Array<{
"role"?: string;
"content"?: string;
}>;
"finish_reason": string;
"model": string;
"usage": {
"total_tokens": number;
"completion_tokens": number;
"prompt_tokens": number;
"cached_tokens": number;
};
"error": EvalApiError;
"temperature": number;
"max_completion_tokens": number;
"top_p": number;
"seed": number;
};
};
/** An object representing a list of output items for an evaluation run.
*/
export type EvalRunOutputItemList = {
"object": "list";
"data": Array<EvalRunOutputItem>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
/** A single grader result for an evaluation run output item.
*/
export type EvalRunOutputItemResult = {
"name": string;
"type"?: string;
"score": number;
"passed": boolean;
"sample"?: Record<string, unknown>;
};
/** Deprecated in favor of LogsDataSourceConfig.
*/
export type EvalStoredCompletionsDataSourceConfig = {
"type": "stored_completions";
"metadata"?: Metadata;
"schema": Record<string, Record<string, unknown>>;
};
/** A StoredCompletionsRunDataSource configuration describing a set of filters
*/
export type EvalStoredCompletionsSource = {
"type": "stored_completions";
"metadata"?: Metadata;
"model"?: Record<string, unknown>;
"created_after"?: Record<string, unknown>;
"created_before"?: Record<string, unknown>;
"limit"?: Record<string, unknown>;
};
/** The expiration policy for a file. By default, files with `purpose=batch` expire after 30 days and all other files are persisted until they are manually deleted. */
export type FileExpirationAfter = {
"anchor": "created_at";
"seconds": number;
};
/** A path to a file.
*/
export type FilePath = {
"type": "file_path";
"file_id": string;
"index": number;
};
/** The ranker to use for the file search. If not specified will use the `auto` ranker. */
export type FileSearchRanker = "auto" | "default_2024_08_21";
/** The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0.
See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information.
*/
export type FileSearchRankingOptions = {
"ranker"?: FileSearchRanker;
"score_threshold": number;
};
/** The results of a file search tool call. See the
[file search guide](/docs/guides/tools-file-search) for more information.
*/
export type FileSearchToolCall = {
"id": string;
"type": "file_search_call";
"status": "in_progress" | "searching" | "completed" | "incomplete" | "failed";
"queries": Array<string>;
"results"?: Record<string, unknown>;
};
export type FineTuneChatCompletionRequestAssistantMessage = Record<string, unknown>;
/** The hyperparameters used for the DPO fine-tuning job. */
export type FineTuneDPOHyperparameters = {
"beta"?: Record<string, unknown>;
"batch_size"?: Record<string, unknown>;
"learning_rate_multiplier"?: Record<string, unknown>;
"n_epochs"?: Record<string, unknown>;
};
/** Configuration for the DPO fine-tuning method. */
export type FineTuneDPOMethod = {
"hyperparameters"?: FineTuneDPOHyperparameters;
};
/** The method used for fine-tuning. */
export type FineTuneMethod = {
"type": "supervised" | "dpo" | "reinforcement";
"supervised"?: FineTuneSupervisedMethod;
"dpo"?: FineTuneDPOMethod;
"reinforcement"?: FineTuneReinforcementMethod;
};
/** The hyperparameters used for the reinforcement fine-tuning job. */
export type FineTuneReinforcementHyperparameters = {
"batch_size"?: Record<string, unknown>;
"learning_rate_multiplier"?: Record<string, unknown>;
"n_epochs"?: Record<string, unknown>;
"reasoning_effort"?: "default" | "low" | "medium" | "high";
"compute_multiplier"?: Record<string, unknown>;
"eval_interval"?: Record<string, unknown>;
"eval_samples"?: Record<string, unknown>;
};
/** Configuration for the reinforcement fine-tuning method. */
export type FineTuneReinforcementMethod = {
"grader": Record<string, unknown>;
"hyperparameters"?: FineTuneReinforcementHyperparameters;
};
/** The hyperparameters used for the fine-tuning job. */
export type FineTuneSupervisedHyperparameters = {
"batch_size"?: Record<string, unknown>;
"learning_rate_multiplier"?: Record<string, unknown>;
"n_epochs"?: Record<string, unknown>;
};
/** Configuration for the supervised fine-tuning method. */
export type FineTuneSupervisedMethod = {
"hyperparameters"?: FineTuneSupervisedHyperparameters;
};
/** The `checkpoint.permission` object represents a permission for a fine-tuned model checkpoint.
*/
export type FineTuningCheckpointPermission = {
"id": string;
"created_at": number;
"project_id": string;
"object": "checkpoint.permission";
};
export type FineTuningIntegration = {
"type": "wandb";
"wandb": {
"project": string;
"name"?: Record<string, unknown>;
"entity"?: Record<string, unknown>;
"tags"?: Array<string>;
};
};
/** The `fine_tuning.job` object represents a fine-tuning job that has been created through the API.
*/
export type FineTuningJob = {
"id": string;
"created_at": number;
"error": Record<string, unknown>;
"fine_tuned_model": Record<string, unknown>;
"finished_at": Record<string, unknown>;
"hyperparameters": {
"batch_size"?: Record<string, unknown>;
"learning_rate_multiplier"?: Record<string, unknown>;
"n_epochs"?: Record<string, unknown>;
};
"model": string;
"object": "fine_tuning.job";
"organization_id": string;
"result_files": Array<string>;
"status": "validating_files" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
"trained_tokens": Record<string, unknown>;
"training_file": string;
"validation_file": Record<string, unknown>;
"integrations"?: Record<string, unknown>;
"seed": number;
"estimated_finish"?: Record<string, unknown>;
"method"?: FineTuneMethod;
"metadata"?: Metadata;
};
/** The `fine_tuning.job.checkpoint` object represents a model checkpoint for a fine-tuning job that is ready to use.
*/
export type FineTuningJobCheckpoint = {
"id": string;
"created_at": number;
"fine_tuned_model_checkpoint": string;
"step_number": number;
"metrics": {
"step"?: number;
"train_loss"?: number;
"train_mean_token_accuracy"?: number;
"valid_loss"?: number;
"valid_mean_token_accuracy"?: number;
"full_valid_loss"?: number;
"full_valid_mean_token_accuracy"?: number;
};
"fine_tuning_job_id": string;
"object": "fine_tuning.job.checkpoint";
};
/** Fine-tuning job event object */
export type FineTuningJobEvent = {
"object": "fine_tuning.job.event";
"id": string;
"created_at": number;
"level": "info" | "warn" | "error";
"message": string;
"type"?: "message" | "metrics";
"data"?: Record<string, unknown>;
};
export type FunctionAndCustomToolCallOutput = Record<string, unknown>;
export type FunctionObject = {
"description"?: string;
"name": string;
"parameters"?: FunctionParameters;
"strict"?: Record<string, unknown>;
};
/** The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format.
Omitting `parameters` defines a function with an empty parameter list. */
export type FunctionParameters = Record<string, Record<string, unknown>>;
/** A tool call to run a function. See the
[function calling guide](/docs/guides/function-calling) for more information.
*/
export type FunctionToolCall = {
"id"?: string;
"type": "function_call";
"call_id": string;
"namespace"?: string;
"name": string;
"arguments": string;
"status"?: "in_progress" | "completed" | "incomplete";
};
/** The output of a function tool call.
*/
export type FunctionToolCallOutput = {
"id"?: string;
"type": "function_call_output";
"call_id": string;
"output": Record<string, unknown>;
"status"?: "in_progress" | "completed" | "incomplete";
};
export type FunctionToolCallOutputResource = Record<string, unknown>;
export type FunctionToolCallResource = Record<string, unknown>;
/** A LabelModelGrader object which uses a model to assign labels to each item
in the evaluation.
*/
export type GraderLabelModel = {
"type": "label_model";
"name": string;
"model": string;
"input": Array<EvalItem>;
"labels": Array<string>;
"passing_labels": Array<string>;
};
/** A MultiGrader object combines the output of multiple graders to produce a single score. */
export type GraderMulti = {
"type": "multi";
"name": string;
"graders": Record<string, unknown>;
"calculate_output": string;
};
/** A PythonGrader object that runs a python script on the input.
*/
export type GraderPython = {
"type": "python";
"name": string;
"source": string;
"image_tag"?: string;
};
/** A ScoreModelGrader object that uses a model to assign a score to the input.
*/
export type GraderScoreModel = {
"type": "score_model";
"name": string;
"model": string;
"sampling_params"?: {
"seed"?: Record<string, unknown>;
"top_p"?: Record<string, unknown>;
"temperature"?: Record<string, unknown>;
"max_completions_tokens"?: Record<string, unknown>;
"reasoning_effort"?: ReasoningEffort;
};
"input": Array<EvalItem>;
"range"?: Array<number>;
};
/** A StringCheckGrader object that performs a string comparison between input and reference using a specified operation.
*/
export type GraderStringCheck = {
"type": "string_check";
"name": string;
"input": string;
"reference": string;
"operation": "eq" | "ne" | "like" | "ilike";
};
/** A TextSimilarityGrader object which grades text based on similarity metrics.
*/
export type GraderTextSimilarity = {
"type": "text_similarity";
"name": string;
"input": string;
"reference": string;
"evaluation_metric": "cosine" | "fuzzy_match" | "bleu" | "gleu" | "meteor" | "rouge_1" | "rouge_2" | "rouge_3" | "rouge_4" | "rouge_5" | "rouge_l";
};
/** Summary information about a group returned in role assignment responses. */
export type Group = {
"object": "group";
"id": string;
"name": string;
"created_at": number;
"scim_managed": boolean;
};
/** Confirmation payload returned after deleting a group. */
export type GroupDeletedResource = {
"object": "group.deleted";
"id": string;
"deleted": boolean;
};
/** Paginated list of organization groups. */
export type GroupListResource = {
"object": "list";
"data": Array<GroupResponse>;
"has_more": boolean;
"next": Record<string, unknown>;
};
/** Response returned after updating a group. */
export type GroupResourceWithSuccess = {
"id": string;
"name": string;
"created_at": number;
"is_scim_managed": boolean;
};
/** Details about an organization group. */
export type GroupResponse = {
"id": string;
"name": string;
"created_at": number;
"is_scim_managed": boolean;
"group_type": string;
};
/** Role assignment linking a group to a role. */
export type GroupRoleAssignment = {
"object": "group.role";
"group": Group;
"role": Role;
};
/** Represents an individual user returned when inspecting group membership. */
export type GroupUser = {
"id": string;
"name": string;
"email": Record<string, unknown>;
};
/** Confirmation payload returned after adding a user to a group. */
export type GroupUserAssignment = {
"object": "group.user";
"user_id": string;
"group_id": string;
};
/** Confirmation payload returned after removing a user from a group. */
export type GroupUserDeletedResource = {
"object": "group.user.deleted";
"deleted": boolean;
};
/** Represents the content or the URL of an image generated by the OpenAI API. */
export type Image = {
"b64_json"?: string;
"url"?: string;
"revised_prompt"?: string;
};
/** Emitted when image editing has completed and the final image is available.
*/
export type ImageEditCompletedEvent = {
"type": "image_edit.completed";
"b64_json": string;
"created_at": number;
"size": "1024x1024" | "1024x1536" | "1536x1024" | "auto";
"quality": "low" | "medium" | "high" | "auto";
"background": "transparent" | "opaque" | "auto";
"output_format": "png" | "webp" | "jpeg";
"usage": ImagesUsage;
};
/** Emitted when a partial image is available during image editing streaming.
*/
export type ImageEditPartialImageEvent = {
"type": "image_edit.partial_image";
"b64_json": string;
"created_at": number;
"size": "1024x1024" | "1024x1536" | "1536x1024" | "auto";
"quality": "low" | "medium" | "high" | "auto";
"background": "transparent" | "opaque" | "auto";
"output_format": "png" | "webp" | "jpeg";
"partial_image_index": number;
};
export type ImageEditStreamEvent = Record<string, unknown>;
/** Emitted when image generation has completed and the final image is available.
*/
export type ImageGenCompletedEvent = {
"type": "image_generation.completed";
"b64_json": string;
"created_at": number;
"size": "1024x1024" | "1024x1536" | "1536x1024" | "auto";
"quality": "low" | "medium" | "high" | "auto";
"background": "transparent" | "opaque" | "auto";
"output_format": "png" | "webp" | "jpeg";
"usage": ImagesUsage;
};
/** Emitted when a partial image is available during image generation streaming.
*/
export type ImageGenPartialImageEvent = {
"type": "image_generation.partial_image";
"b64_json": string;
"created_at": number;
"size": "1024x1024" | "1024x1536" | "1536x1024" | "auto";
"quality": "low" | "medium" | "high" | "auto";
"background": "transparent" | "opaque" | "auto";
"output_format": "png" | "webp" | "jpeg";
"partial_image_index": number;
};
export type ImageGenStreamEvent = Record<string, unknown>;
/** A tool that generates images using the GPT image models.
*/
export type ImageGenTool = {
"type": "image_generation";
"model"?: Record<string, unknown>;
"quality"?: "low" | "medium" | "high" | "auto";
"size"?: Record<string, unknown>;
"output_format"?: "png" | "webp" | "jpeg";
"output_compression"?: number;
"moderation"?: "auto" | "low";
"background"?: "transparent" | "opaque" | "auto";
"input_fidelity"?: Record<string, unknown>;
"input_image_mask"?: {
"image_url"?: string;
"file_id"?: string;
};
"partial_images"?: number;
"action"?: ImageGenActionEnum;
};
/** An image generation request made by the model.
*/
export type ImageGenToolCall = {
"type": "image_generation_call";
"id": string;
"status": "in_progress" | "completed" | "generating" | "failed";
"result": Record<string, unknown>;
};
/** Reference an input image by either URL or uploaded file ID.
Provide exactly one of `image_url` or `file_id`.
*/
export type ImageRefParam = {
"image_url"?: string;
"file_id"?: string;
};
/** The response from the image generation endpoint. */
export type ImagesResponse = {
"created": number;
"data"?: Array<Image>;
"background"?: "transparent" | "opaque";
"output_format"?: "png" | "webp" | "jpeg";
"size"?: "1024x1024" | "1024x1536" | "1536x1024";
"quality"?: "low" | "medium" | "high";
"usage"?: ImageGenUsage;
};
/** For the GPT image models only, the token usage information for the image generation.
*/
export type ImagesUsage = {
"total_tokens": number;
"input_tokens": number;
"output_tokens": number;
"input_tokens_details": {
"text_tokens": number;
"image_tokens": number;
};
};
/** An audio input to the model.
*/
export type InputAudio = {
"type": "input_audio";
"input_audio": {
"data": string;
"format": "mp3" | "wav";
};
};
export type InputContent = Record<string, unknown>;
export type InputItem = Record<string, unknown>;
/** 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.
*/
export type InputMessage = {
"type"?: "message";
"role": "user" | "system" | "developer";
"status"?: "in_progress" | "completed" | "incomplete";
"content": InputMessageContentList;
};
/** A list of one or many input items to the model, containing different content
types.
*/
export type InputMessageContentList = Array<InputContent>;
export type InputMessageResource = Record<string, unknown>;
/** Text, image, or file inputs to the model, used to generate a response.
Learn more:
- [Text inputs and outputs](/docs/guides/text)
- [Image inputs](/docs/guides/images)
- [File inputs](/docs/guides/pdf-files)
- [Conversation state](/docs/guides/conversation-state)
- [Function calling](/docs/guides/function-calling)
*/
export type InputParam = Record<string, unknown>;
/** Represents an individual `invite` to the organization. */
export type Invite = {
"object": "organization.invite";
"id": string;
"email": string;
"role": "owner" | "reader";
"status": "accepted" | "expired" | "pending";
"created_at": number;
"expires_at"?: Record<string, unknown>;
"accepted_at"?: Record<string, unknown>;
"projects": Array<{
"id": string;
"role": "member" | "owner";
}>;
};
export type InviteDeleteResponse = {
"object": "organization.invite.deleted";
"id": string;
"deleted": boolean;
};
export type InviteListResponse = {
"object": "list";
"data": Array<Invite>;
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
"has_more": boolean;
};
/** Request payload for granting a group access to a project. */
export type InviteProjectGroupBody = {
"group_id": string;
"role": string;
};
export type InviteRequest = {
"email": string;
"role": "reader" | "owner";
"projects"?: Array<{
"id": string;
"role": "member" | "owner";
}>;
};
/** Content item used to generate a response.
*/
export type Item = Record<string, unknown>;
/** Content item used to generate a response.
*/
export type ItemResource = Record<string, unknown>;
export type ListAssistantsResponse = {
"object": string;
"data": Array<AssistantObject>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
export type ListAuditLogsResponse = {
"object": "list";
"data": Array<AuditLog>;
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
"has_more": boolean;
};
export type ListBatchesResponse = {
"data": Array<Batch>;
"first_id"?: string;
"last_id"?: string;
"has_more": boolean;
"object": "list";
};
export type ListCertificatesResponse = {
"data": Array<OrganizationCertificate>;
"first_id": Record<string, unknown>;
"last_id": Record<string, unknown>;
"has_more": boolean;
"object": "list";
};
export type ListFilesResponse = {
"object": string;
"data": Array<OpenAIFile>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
export type ListFineTuningCheckpointPermissionResponse = {
"data": Array<FineTuningCheckpointPermission>;
"object": "list";
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
"has_more": boolean;
};
export type ListFineTuningJobCheckpointsResponse = {
"data": Array<FineTuningJobCheckpoint>;
"object": "list";
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
"has_more": boolean;
};
export type ListFineTuningJobEventsResponse = {
"data": Array<FineTuningJobEvent>;
"object": "list";
"has_more": boolean;
};
export type ListMessagesResponse = {
"object": string;
"data": Array<MessageObject>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
export type ListModelsResponse = {
"object": "list";
"data": Array<Model>;
};
export type ListPaginatedFineTuningJobsResponse = {
"data": Array<FineTuningJob>;
"has_more": boolean;
"object": "list";
};
export type ListProjectCertificatesResponse = {
"data": Array<OrganizationProjectCertificate>;
"first_id": Record<string, unknown>;
"last_id": Record<string, unknown>;
"has_more": boolean;
"object": "list";
};
export type ListRunStepsResponse = {
"object": string;
"data": Array<RunStepObject>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
export type ListRunsResponse = {
"object": string;
"data": Array<RunObject>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
export type ListVectorStoreFilesResponse = {
"object": string;
"data": Array<VectorStoreFileObject>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
export type ListVectorStoresResponse = {
"object": string;
"data": Array<VectorStoreObject>;
"first_id": string;
"last_id": string;
"has_more": boolean;
};
/** A tool call to run a command on the local shell.
*/
export type LocalShellToolCall = {
"type": "local_shell_call";
"id": string;
"call_id": string;
"action": LocalShellExecAction;
"status": "in_progress" | "completed" | "incomplete";
};
/** The output of a local shell tool call.
*/
export type LocalShellToolCallOutput = {
"type": "local_shell_call_output";
"id": string;
"output": string;
"status"?: Record<string, unknown>;
};
/** A log probability object.
*/
export type LogProbProperties = {
"token": string;
"logprob": number;
"bytes": Array<number>;
};
/** A request for human approval of a tool invocation.
*/
export type MCPApprovalRequest = {
"type": "mcp_approval_request";
"id": string;
"server_label": string;
"name": string;
"arguments": string;
};
/** A response to an MCP approval request.
*/
export type MCPApprovalResponse = {
"type": "mcp_approval_response";
"id"?: Record<string, unknown>;
"approval_request_id": string;
"approve": boolean;
"reason"?: Record<string, unknown>;
};
/** A response to an MCP approval request.
*/
export type MCPApprovalResponseResource = {
"type": "mcp_approval_response";
"id": string;
"approval_request_id": string;
"approve": boolean;
"reason"?: Record<string, unknown>;
};
/** A list of tools available on an MCP server.
*/
export type MCPListTools = {
"type": "mcp_list_tools";
"id": string;
"server_label": string;
"tools": Array<MCPListToolsTool>;
"error"?: Record<string, unknown>;
};
/** A tool available on an MCP server.
*/
export type MCPListToolsTool = {
"name": string;
"description"?: Record<string, unknown>;
"input_schema": Record<string, unknown>;
"annotations"?: Record<string, unknown>;
};
/** Give the model access to additional tools via remote Model Context Protocol
(MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp).
*/
export type MCPTool = {
"type": "mcp";
"server_label": string;
"server_url"?: string;
"connector_id"?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | "connector_googledrive" | "connector_microsoftteams" | "connector_outlookcalendar" | "connector_outlookemail" | "connector_sharepoint";
"authorization"?: string;
"server_description"?: string;
"headers"?: Record<string, unknown>;
"allowed_tools"?: Record<string, unknown>;
"require_approval"?: Record<string, unknown>;
"defer_loading"?: boolean;
};
/** An invocation of a tool on an MCP server.
*/
export type MCPToolCall = {
"type": "mcp_call";
"id": string;
"server_label": string;
"name": string;
"arguments": string;
"output"?: Record<string, unknown>;
"error"?: Record<string, unknown>;
"status"?: MCPToolCallStatus;
"approval_request_id"?: Record<string, unknown>;
};
/** A filter object to specify which tools are allowed.
*/
export type MCPToolFilter = {
"tool_names"?: Array<string>;
"read_only"?: boolean;
};
/** References an image [File](/docs/api-reference/files) in the content of a message. */
export type MessageContentImageFileObject = {
"type": "image_file";
"image_file": {
"file_id": string;
"detail"?: "auto" | "low" | "high";
};
};
/** References an image URL in the content of a message. */
export type MessageContentImageUrlObject = {
"type": "image_url";
"image_url": {
"url": string;
"detail"?: "auto" | "low" | "high";
};
};
/** The refusal content generated by the assistant. */
export type MessageContentRefusalObject = {
"type": "refusal";
"refusal": string;
};
/** A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. */
export type MessageContentTextAnnotationsFileCitationObject = {
"type": "file_citation";
"text": string;
"file_citation": {
"file_id": string;
};
"start_index": number;
"end_index": number;
};
/** A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. */
export type MessageContentTextAnnotationsFilePathObject = {
"type": "file_path";
"text": string;
"file_path": {
"file_id": string;
};
"start_index": number;
"end_index": number;
};
/** The text content that is part of a message. */
export type MessageContentTextObject = {
"type": "text";
"text": {
"value": string;
"annotations": Array<Record<string, unknown>>;
};
};
/** References an image [File](/docs/api-reference/files) in the content of a message. */
export type MessageDeltaContentImageFileObject = {
"index": number;
"type": "image_file";
"image_file"?: {
"file_id"?: string;
"detail"?: "auto" | "low" | "high";
};
};
/** References an image URL in the content of a message. */
export type MessageDeltaContentImageUrlObject = {
"index": number;
"type": "image_url";
"image_url"?: {
"url"?: string;
"detail"?: "auto" | "low" | "high";
};
};
/** The refusal content that is part of a message. */
export type MessageDeltaContentRefusalObject = {
"index": number;
"type": "refusal";
"refusal"?: string;
};
/** A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. */
export type MessageDeltaContentTextAnnotationsFileCitationObject = {
"index": number;
"type": "file_citation";
"text"?: string;
"file_citation"?: {
"file_id"?: string;
"quote"?: string;
};
"start_index"?: number;
"end_index"?: number;
};
/** A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. */
export type MessageDeltaContentTextAnnotationsFilePathObject = {
"index": number;
"type": "file_path";
"text"?: string;
"file_path"?: {
"file_id"?: string;
};
"start_index"?: number;
"end_index"?: number;
};
/** The text content that is part of a message. */
export type MessageDeltaContentTextObject = {
"index": number;
"type": "text";
"text"?: {
"value"?: string;
"annotations"?: Array<Record<string, unknown>>;
};
};
/** Represents a message delta i.e. any changed fields on a message during streaming.
*/
export type MessageDeltaObject = {
"id": string;
"object": "thread.message.delta";
"delta": {
"role"?: "user" | "assistant";
"content"?: Array<Record<string, unknown>>;
};
};
/** Represents a message within a [thread](/docs/api-reference/threads). */
export type MessageObject = {
"id": string;
"object": "thread.message";
"created_at": number;
"thread_id": string;
"status": "in_progress" | "incomplete" | "completed";
"incomplete_details": Record<string, unknown>;
"completed_at": Record<string, unknown>;
"incomplete_at": Record<string, unknown>;
"role": "user" | "assistant";
"content": Array<Record<string, unknown>>;
"assistant_id": Record<string, unknown>;
"run_id": Record<string, unknown>;
"attachments": Record<string, unknown>;
"metadata": Metadata;
};
/** 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.
*/
export type MessagePhase = "commentary" | "final_answer";
/** The text content that is part of a message. */
export type MessageRequestContentTextObject = {
"type": "text";
"text": string;
};
export type MessageStreamEvent = Record<string, unknown>;
export type Metadata = Record<string, unknown>;
/** Describes an OpenAI model offering that can be used with the API. */
export type Model = {
"id": string;
"created": number;
"object": "model";
"owned_by": string;
};
export type ModelIds = Record<string, unknown>;
/** Model ID used to generate the response, like `gpt-5` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](/docs/models) to browse and compare available models. */
export type ModelIdsCompaction = Record<string, unknown>;
export type ModelIdsResponses = Record<string, unknown>;
export type ModelIdsShared = Record<string, unknown>;
export type ModelResponseProperties = {
"metadata"?: Metadata;
"top_logprobs"?: Record<string, unknown>;
"temperature"?: Record<string, unknown>;
"top_p"?: Record<string, unknown>;
"user"?: string;
"safety_identifier"?: string;
"prompt_cache_key"?: string;
"service_tier"?: ServiceTier;
"prompt_cache_retention"?: Record<string, unknown>;
};
export type ModifyAssistantRequest = {
"model"?: Record<string, unknown>;
"reasoning_effort"?: ReasoningEffort;
"name"?: Record<string, unknown>;
"description"?: Record<string, unknown>;
"instructions"?: Record<string, unknown>;
"tools"?: Array<Record<string, unknown>>;
"tool_resources"?: Record<string, unknown>;
"metadata"?: Metadata;
"temperature"?: Record<string, unknown>;
"top_p"?: Record<string, unknown>;
"response_format"?: Record<string, unknown>;
};
export type ModifyCertificateRequest = {
"name"?: string;
};
export type ModifyMessageRequest = {
"metadata"?: Metadata;
};
export type ModifyRunRequest = {
"metadata"?: Metadata;
};
export type ModifyThreadRequest = {
"tool_resources"?: Record<string, unknown>;
"metadata"?: Metadata;
};
/** Type of noise reduction. `near_field` is for close-talking microphones such as headphones, `far_field` is for far-field microphones such as laptop or conference room microphones.
*/
export type NoiseReductionType = "near_field" | "far_field";
/** The `File` object represents a document that has been uploaded to OpenAI. */
export type OpenAIFile = {
"id": string;
"bytes": number;
"created_at": number;
"expires_at"?: number;
"filename": string;
"object": "file";
"purpose": "assistants" | "assistants_output" | "batch" | "batch_output" | "fine-tune" | "fine-tune-results" | "vision" | "user_data";
"status": "uploaded" | "processed" | "error";
"status_details"?: string;
};
/** Represents an individual certificate configured at the organization level. */
export type OrganizationCertificate = {
"object": "organization.certificate";
"id": string;
"name": Record<string, unknown>;
"created_at": number;
"certificate_details": {
"valid_at"?: number;
"expires_at"?: number;
};
"active": boolean;
};
export type OrganizationCertificateActivationResponse = {
"object": "organization.certificate.activation";
"data": Array<OrganizationCertificate>;
};
export type OrganizationCertificateDeactivationResponse = {
"object": "organization.certificate.deactivation";
"data": Array<OrganizationCertificate>;
};
/** Represents an individual certificate configured at the project level. */
export type OrganizationProjectCertificate = {
"object": "organization.project.certificate";
"id": string;
"name": Record<string, unknown>;
"created_at": number;
"certificate_details": {
"valid_at"?: number;
"expires_at"?: number;
};
"active": boolean;
};
export type OrganizationProjectCertificateActivationResponse = {
"object": "organization.project.certificate.activation";
"data": Array<OrganizationProjectCertificate>;
};
export type OrganizationProjectCertificateDeactivationResponse = {
"object": "organization.project.certificate.deactivation";
"data": Array<OrganizationProjectCertificate>;
};
/** This is returned when the chunking strategy is unknown. Typically, this is because the file was indexed before the `chunking_strategy` concept was introduced in the API. */
export type OtherChunkingStrategyResponseParam = {
"type": "other";
};
/** An audio output from the model.
*/
export type OutputAudio = {
"type": "output_audio";
"data": string;
"transcript": string;
};
export type OutputContent = Record<string, unknown>;
export type OutputItem = Record<string, unknown>;
/** An output message from the model.
*/
export type OutputMessage = {
"id": string;
"type": "message";
"role": "assistant";
"content": Array<OutputMessageContent>;
"phase"?: Record<string, unknown>;
"status": "in_progress" | "completed" | "incomplete";
};
export type OutputMessageContent = Record<string, unknown>;
/** Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. */
export type ParallelToolCalls = boolean;
export type PartialImages = Record<string, unknown>;
/** Static predicted output content, such as the content of a text file that is
being regenerated.
*/
export type PredictionContent = {
"type": "content";
"content": Record<string, unknown>;
};
/** Represents an individual project. */
export type Project = {
"id": string;
"object": "organization.project";
"name"?: Record<string, unknown>;
"created_at": number;
"archived_at"?: Record<string, unknown>;
"status"?: Record<string, unknown>;
"external_key_id"?: Record<string, unknown>;
};
/** Represents an individual API key in a project. */
export type ProjectApiKey = {
"object": "organization.project.api_key";
"redacted_value": string;
"name": string;
"created_at": number;
"last_used_at": Record<string, unknown>;
"id": string;
"owner": {
"type"?: "user" | "service_account";
"user"?: ProjectApiKeyOwnerUser;
"service_account"?: ProjectApiKeyOwnerServiceAccount;
};
};
export type ProjectApiKeyDeleteResponse = {
"object": "organization.project.api_key.deleted";
"id": string;
"deleted": boolean;
};
export type ProjectApiKeyListResponse = {
"object": "list";
"data": Array<ProjectApiKey>;
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
"has_more": boolean;
};
/** The service account that owns a project API key. */
export type ProjectApiKeyOwnerServiceAccount = {
"id": string;
"name": string;
"created_at": number;
"role": string;
};
/** The user that owns a project API key. */
export type ProjectApiKeyOwnerUser = {
"id": string;
"email": string;
"name": string;
"created_at": number;
"role": string;
};
export type ProjectCreateRequest = {
"name": string;
"geography"?: Record<string, unknown>;
"external_key_id"?: Record<string, unknown>;
};
/** Details about a group's membership in a project. */
export type ProjectGroup = {
"object": "project.group";
"project_id": string;
"group_id": string;
"group_name": string;
"group_type": string;
"created_at": number;
};
/** Confirmation payload returned after removing a group from a project. */
export type ProjectGroupDeletedResource = {
"object": "project.group.deleted";
"deleted": boolean;
};
/** Paginated list of groups that have access to a project. */
export type ProjectGroupListResource = {
"object": "list";
"data": Array<ProjectGroup>;
"has_more": boolean;
"next": Record<string, unknown>;
};
export type ProjectListResponse = {
"object": "list";
"data": Array<Project>;
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
"has_more": boolean;
};
/** Represents a project rate limit config. */
export type ProjectRateLimit = {
"object": "project.rate_limit";
"id": string;
"model": string;
"max_requests_per_1_minute": number;
"max_tokens_per_1_minute": number;
"max_images_per_1_minute"?: number;
"max_audio_megabytes_per_1_minute"?: number;
"max_requests_per_1_day"?: number;
"batch_1_day_max_input_tokens"?: number;
};
export type ProjectRateLimitListResponse = {
"object": "list";
"data": Array<ProjectRateLimit>;
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
"has_more": boolean;
};
export type ProjectRateLimitUpdateRequest = {
"max_requests_per_1_minute"?: number;
"max_tokens_per_1_minute"?: number;
"max_images_per_1_minute"?: number;
"max_audio_megabytes_per_1_minute"?: number;
"max_requests_per_1_day"?: number;
"batch_1_day_max_input_tokens"?: number;
};
/** Represents an individual service account in a project. */
export type ProjectServiceAccount = {
"object": "organization.project.service_account";
"id": string;
"name": string;
"role": "owner" | "member";
"created_at": number;
};
export type ProjectServiceAccountApiKey = {
"object": "organization.project.service_account.api_key";
"value": string;
"name": string;
"created_at": number;
"id": string;
};
export type ProjectServiceAccountCreateRequest = {
"name": string;
};
export type ProjectServiceAccountCreateResponse = {
"object": "organization.project.service_account";
"id": string;
"name": string;
"role": "member";
"created_at": number;
"api_key": Record<string, unknown>;
};
export type ProjectServiceAccountDeleteResponse = {
"object": "organization.project.service_account.deleted";
"id": string;
"deleted": boolean;
};
export type ProjectServiceAccountListResponse = {
"object": "list";
"data": Array<ProjectServiceAccount>;
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
"has_more": boolean;
};
export type ProjectUpdateRequest = {
"name"?: Record<string, unknown>;
"external_key_id"?: Record<string, unknown>;
"geography"?: Record<string, unknown>;
};
/** Represents an individual user in a project. */
export type ProjectUser = {
"object": "organization.project.user";
"id": string;
"name"?: Record<string, unknown>;
"email"?: Record<string, unknown>;
"role": string;
"added_at": number;
};
export type ProjectUserCreateRequest = {
"user_id"?: Record<string, unknown>;
"email"?: Record<string, unknown>;
"role": string;
};
export type ProjectUserDeleteResponse = {
"object": "organization.project.user.deleted";
"id": string;
"deleted": boolean;
};
export type ProjectUserListResponse = {
"object": string;
"data": Array<ProjectUser>;
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
"has_more": boolean;
};
export type ProjectUserUpdateRequest = {
"role"?: Record<string, unknown>;
};
export type Prompt = Record<string, unknown>;
/** Request payload for assigning a role to a group or user. */
export type PublicAssignOrganizationGroupRoleBody = {
"role_id": string;
};
/** Request payload for creating a custom role. */
export type PublicCreateOrganizationRoleBody = {
"role_name": string;
"permissions": Array<string>;
"description"?: Record<string, unknown>;
};
/** Paginated list of roles available on an organization or project. */
export type PublicRoleListResource = {
"object": "list";
"data": Array<Role>;
"has_more": boolean;
"next": Record<string, unknown>;
};
/** Request payload for updating an existing role. */
export type PublicUpdateOrganizationRoleBody = {
"permissions"?: Record<string, unknown>;
"description"?: Record<string, unknown>;
"role_name"?: Record<string, unknown>;
};
export type RealtimeAudioFormats = Record<string, unknown>;
/** Add a new Item to the Conversation's context, including messages, function
calls, and function call responses. This event can be used both to populate a
"history" of the conversation and to add new items mid-stream, but has the
current limitation that it cannot populate assistant audio messages.
If successful, the server will respond with a `conversation.item.created`
event, otherwise an `error` event will be sent.
*/
export type RealtimeBetaClientEventConversationItemCreate = {
"event_id"?: string;
"type": "conversation.item.create";
"previous_item_id"?: string;
"item": RealtimeConversationItem;
};
/** Send this event when you want to remove any item from the conversation
history. The server will respond with a `conversation.item.deleted` event,
unless the item does not exist in the conversation history, in which case the
server will respond with an error.
*/
export type RealtimeBetaClientEventConversationItemDelete = {
"event_id"?: string;
"type": "conversation.item.delete";
"item_id": string;
};
/** Send this event when you want to retrieve the server's representation of a specific item in the conversation history. This is useful, for example, to inspect user audio after noise cancellation and VAD.
The server will respond with a `conversation.item.retrieved` event,
unless the item does not exist in the conversation history, in which case the
server will respond with an error.
*/
export type RealtimeBetaClientEventConversationItemRetrieve = {
"event_id"?: string;
"type": "conversation.item.retrieve";
"item_id": string;
};
/** Send this event to truncate a previous assistant message’s audio. The server
will produce audio faster than realtime, so this event is useful when the user
interrupts to truncate audio that has already been sent to the client but not
yet played. This will synchronize the server's understanding of the audio with
the client's playback.
Truncating audio will delete the server-side text transcript to ensure there
is not text in the context that hasn't been heard by the user.
If successful, the server will respond with a `conversation.item.truncated`
event.
*/
export type RealtimeBetaClientEventConversationItemTruncate = {
"event_id"?: string;
"type": "conversation.item.truncate";
"item_id": string;
"content_index": number;
"audio_end_ms": number;
};
/** Send this event to append audio bytes to the input audio buffer. The audio
buffer is temporary storage you can write to and later commit. In Server VAD
mode, the audio buffer is used to detect speech and the server will decide
when to commit. When Server VAD is disabled, you must commit the audio buffer
manually.
The client may choose how much audio to place in each event up to a maximum
of 15 MiB, for example streaming smaller chunks from the client may allow the
VAD to be more responsive. Unlike made other client events, the server will
not send a confirmation response to this event.
*/
export type RealtimeBetaClientEventInputAudioBufferAppend = {
"event_id"?: string;
"type": "input_audio_buffer.append";
"audio": string;
};
/** Send this event to clear the audio bytes in the buffer. The server will
respond with an `input_audio_buffer.cleared` event.
*/
export type RealtimeBetaClientEventInputAudioBufferClear = {
"event_id"?: string;
"type": "input_audio_buffer.clear";
};
/** Send this event to commit the user input audio buffer, which will create a
new user message item in the conversation. This event will produce an error
if the input audio buffer is empty. When in Server VAD mode, the client does
not need to send this event, the server will commit the audio buffer
automatically.
Committing the input audio buffer will trigger input audio transcription
(if enabled in session configuration), but it will not create a response
from the model. The server will respond with an `input_audio_buffer.committed`
event.
*/
export type RealtimeBetaClientEventInputAudioBufferCommit = {
"event_id"?: string;
"type": "input_audio_buffer.commit";
};
/** **WebRTC/SIP Only:** Emit to cut off the current audio response. This will trigger the server to
stop generating audio and emit a `output_audio_buffer.cleared` event. This
event should be preceded by a `response.cancel` client event to stop the
generation of the current response.
[Learn more](/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc).
*/
export type RealtimeBetaClientEventOutputAudioBufferClear = {
"event_id"?: string;
"type": "output_audio_buffer.clear";
};
/** Send this event to cancel an in-progress response. The server will respond
with a `response.done` event with a status of `response.status=cancelled`. If
there is no response to cancel, the server will respond with an error.
*/
export type RealtimeBetaClientEventResponseCancel = {
"event_id"?: string;
"type": "response.cancel";
"response_id"?: string;
};
/** This event instructs the server to create a Response, which means triggering
model inference. When in Server VAD mode, the server will create Responses
automatically.
A Response will include at least one Item, and may have two, in which case
the second will be a function call. These Items will be appended to the
conversation history.
The server will respond with a `response.created` event, events for Items
and content created, and finally a `response.done` event to indicate the
Response is complete.
The `response.create` event can optionally include inference configuration like
`instructions`, and `temperature`. These fields will override the Session's
configuration for this Response only.
Responses can be created out-of-band of the default Conversation, meaning that they can
have arbitrary input, and it's possible to disable writing the output to the Conversation.
Only one Response can write to the default Conversation at a time, but otherwise multiple
Responses can be created in parallel.
Clients can set `conversation` to `none` to create a Response that does not write to the default
Conversation. Arbitrary input can be provided with the `input` field, which is an array accepting
raw Items and references to existing Items.
*/
export type RealtimeBetaClientEventResponseCreate = {
"event_id"?: string;
"type": "response.create";
"response"?: RealtimeBetaResponseCreateParams;
};
/** Send this event to update the session’s default configuration.
The client may send this event at any time to update any field,
except for `voice`. However, note that once a session has been
initialized with a particular `model`, it can’t be changed to
another model using `session.update`.
When the server receives a `session.update`, it will respond
with a `session.updated` event showing the full, effective configuration.
Only the fields that are present are updated. To clear a field like
`instructions`, pass an empty string.
*/
export type RealtimeBetaClientEventSessionUpdate = {
"event_id"?: string;
"type": "session.update";
"session": RealtimeSessionCreateRequest;
};
/** Send this event to update a transcription session.
*/
export type RealtimeBetaClientEventTranscriptionSessionUpdate = {
"event_id"?: string;
"type": "transcription_session.update";
"session": RealtimeTranscriptionSessionCreateRequest;
};
/** The response resource. */
export type RealtimeBetaResponse = {
"id"?: string;
"object"?: "realtime.response";
"status"?: "completed" | "cancelled" | "failed" | "incomplete" | "in_progress";
"status_details"?: {
"type"?: "completed" | "cancelled" | "failed" | "incomplete";
"reason"?: "turn_detected" | "client_cancelled" | "max_output_tokens" | "content_filter";
"error"?: {
"type"?: string;
"code"?: string;
};
};
"output"?: Array<RealtimeConversationItem>;
"metadata"?: Metadata;
"usage"?: {
"total_tokens"?: number;
"input_tokens"?: number;
"output_tokens"?: number;
"input_token_details"?: {
"cached_tokens"?: number;
"text_tokens"?: number;
"image_tokens"?: number;
"audio_tokens"?: number;
"cached_tokens_details"?: {
"text_tokens"?: number;
"image_tokens"?: number;
"audio_tokens"?: number;
};
};
"output_token_details"?: {
"text_tokens"?: number;
"audio_tokens"?: number;
};
};
"conversation_id"?: string;
"voice"?: VoiceIdsShared;
"modalities"?: Array<"text" | "audio">;
"output_audio_format"?: "pcm16" | "g711_ulaw" | "g711_alaw";
"temperature"?: number;
"max_output_tokens"?: Record<string, unknown>;
};
/** Create a new Realtime response with these parameters */
export type RealtimeBetaResponseCreateParams = {
"modalities"?: Array<"text" | "audio">;
"instructions"?: string;
"voice"?: VoiceIdsOrCustomVoice;
"output_audio_format"?: "pcm16" | "g711_ulaw" | "g711_alaw";
"tools"?: Array<{
"type"?: "function";
"name"?: string;
"description"?: string;
"parameters"?: Record<string, unknown>;
}>;
"tool_choice"?: Record<string, unknown>;
"temperature"?: number;
"max_output_tokens"?: Record<string, unknown>;
"conversation"?: Record<string, unknown>;
"metadata"?: Metadata;
"prompt"?: Prompt;
"input"?: Array<RealtimeConversationItem>;
};
/** Returned when a conversation item is created. There are several scenarios that produce this event:
- The server is generating a Response, which if successful will produce
either one or two Items, which will be of type `message`
(role `assistant`) or type `function_call`.
- The input audio buffer has been committed, either by the client or the
server (in `server_vad` mode). The server will take the content of the
input audio buffer and add it to a new user message Item.
- The client has sent a `conversation.item.create` event to add a new Item
to the Conversation.
*/
export type RealtimeBetaServerEventConversationItemCreated = {
"event_id": string;
"type": "conversation.item.created";
"previous_item_id"?: Record<string, unknown>;
"item": RealtimeConversationItem;
};
/** Returned when an item in the conversation is deleted by the client with a
`conversation.item.delete` event. This event is used to synchronize the
server's understanding of the conversation history with the client's view.
*/
export type RealtimeBetaServerEventConversationItemDeleted = {
"event_id": string;
"type": "conversation.item.deleted";
"item_id": string;
};
/** This event is the output of audio transcription for user audio written to the
user audio buffer. Transcription begins when the input audio buffer is
committed by the client or server (in `server_vad` mode). Transcription runs
asynchronously with Response creation, so this event may come before or after
the Response events.
Realtime API models accept audio natively, and thus input transcription is a
separate process run on a separate ASR (Automatic Speech Recognition) model.
The transcript may diverge somewhat from the model's interpretation, and
should be treated as a rough guide.
*/
export type RealtimeBetaServerEventConversationItemInputAudioTranscriptionCompleted = {
"event_id": string;
"type": "conversation.item.input_audio_transcription.completed";
"item_id": string;
"content_index": number;
"transcript": string;
"logprobs"?: Record<string, unknown>;
"usage": Record<string, unknown>;
};
/** Returned when the text value of an input audio transcription content part is updated.
*/
export type RealtimeBetaServerEventConversationItemInputAudioTranscriptionDelta = {
"event_id": string;
"type": "conversation.item.input_audio_transcription.delta";
"item_id": string;
"content_index"?: number;
"delta"?: string;
"logprobs"?: Record<string, unknown>;
};
/** Returned when input audio transcription is configured, and a transcription
request for a user message failed. These events are separate from other
`error` events so that the client can identify the related Item.
*/
export type RealtimeBetaServerEventConversationItemInputAudioTranscriptionFailed = {
"event_id": string;
"type": "conversation.item.input_audio_transcription.failed";
"item_id": string;
"content_index": number;
"error": {
"type"?: string;
"code"?: string;
"message"?: string;
"param"?: string;
};
};
/** Returned when an input audio transcription segment is identified for an item. */
export type RealtimeBetaServerEventConversationItemInputAudioTranscriptionSegment = {
"event_id": string;
"type": "conversation.item.input_audio_transcription.segment";
"item_id": string;
"content_index": number;
"text": string;
"id": string;
"speaker": string;
"start": number;
"end": number;
};
/** Returned when a conversation item is retrieved with `conversation.item.retrieve`.
*/
export type RealtimeBetaServerEventConversationItemRetrieved = {
"event_id": string;
"type": "conversation.item.retrieved";
"item": RealtimeConversationItem;
};
/** Returned when an earlier assistant audio message item is truncated by the
client with a `conversation.item.truncate` event. This event is used to
synchronize the server's understanding of the audio with the client's playback.
This action will truncate the audio and remove the server-side text transcript
to ensure there is no text in the context that hasn't been heard by the user.
*/
export type RealtimeBetaServerEventConversationItemTruncated = {
"event_id": string;
"type": "conversation.item.truncated";
"item_id": string;
"content_index": number;
"audio_end_ms": number;
};
/** Returned when an error occurs, which could be a client problem or a server
problem. Most errors are recoverable and the session will stay open, we
recommend to implementors to monitor and log error messages by default.
*/
export type RealtimeBetaServerEventError = {
"event_id": string;
"type": "error";
"error": {
"type": string;
"code"?: Record<string, unknown>;
"message": string;
"param"?: Record<string, unknown>;
"event_id"?: Record<string, unknown>;
};
};
/** Returned when the input audio buffer is cleared by the client with a
`input_audio_buffer.clear` event.
*/
export type RealtimeBetaServerEventInputAudioBufferCleared = {
"event_id": string;
"type": "input_audio_buffer.cleared";
};
/** Returned when an input audio buffer is committed, either by the client or
automatically in server VAD mode. The `item_id` property is the ID of the user
message item that will be created, thus a `conversation.item.created` event
will also be sent to the client.
*/
export type RealtimeBetaServerEventInputAudioBufferCommitted = {
"event_id": string;
"type": "input_audio_buffer.committed";
"previous_item_id"?: Record<string, unknown>;
"item_id": string;
};
/** Sent by the server when in `server_vad` mode to indicate that speech has been
detected in the audio buffer. This can happen any time audio is added to the
buffer (unless speech is already detected). The client may want to use this
event to interrupt audio playback or provide visual feedback to the user.
The client should expect to receive a `input_audio_buffer.speech_stopped` event
when speech stops. The `item_id` property is the ID of the user message item
that will be created when speech stops and will also be included in the
`input_audio_buffer.speech_stopped` event (unless the client manually commits
the audio buffer during VAD activation).
*/
export type RealtimeBetaServerEventInputAudioBufferSpeechStarted = {
"event_id": string;
"type": "input_audio_buffer.speech_started";
"audio_start_ms": number;
"item_id": string;
};
/** Returned in `server_vad` mode when the server detects the end of speech in
the audio buffer. The server will also send an `conversation.item.created`
event with the user message item that is created from the audio buffer.
*/
export type RealtimeBetaServerEventInputAudioBufferSpeechStopped = {
"event_id": string;
"type": "input_audio_buffer.speech_stopped";
"audio_end_ms": number;
"item_id": string;
};
/** Returned when listing MCP tools has completed for an item. */
export type RealtimeBetaServerEventMCPListToolsCompleted = {
"event_id": string;
"type": "mcp_list_tools.completed";
"item_id": string;
};
/** Returned when listing MCP tools has failed for an item. */
export type RealtimeBetaServerEventMCPListToolsFailed = {
"event_id": string;
"type": "mcp_list_tools.failed";
"item_id": string;
};
/** Returned when listing MCP tools is in progress for an item. */
export type RealtimeBetaServerEventMCPListToolsInProgress = {
"event_id": string;
"type": "mcp_list_tools.in_progress";
"item_id": string;
};
/** Emitted at the beginning of a Response to indicate the updated rate limits.
When a Response is created some tokens will be "reserved" for the output
tokens, the rate limits shown here reflect that reservation, which is then
adjusted accordingly once the Response is completed.
*/
export type RealtimeBetaServerEventRateLimitsUpdated = {
"event_id": string;
"type": "rate_limits.updated";
"rate_limits": Array<{
"name"?: "requests" | "tokens";
"limit"?: number;
"remaining"?: number;
"reset_seconds"?: number;
}>;
};
/** Returned when the model-generated audio is updated. */
export type RealtimeBetaServerEventResponseAudioDelta = {
"event_id": string;
"type": "response.output_audio.delta";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"delta": string;
};
/** Returned when the model-generated audio is done. Also emitted when a Response
is interrupted, incomplete, or cancelled.
*/
export type RealtimeBetaServerEventResponseAudioDone = {
"event_id": string;
"type": "response.output_audio.done";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
};
/** Returned when the model-generated transcription of audio output is updated.
*/
export type RealtimeBetaServerEventResponseAudioTranscriptDelta = {
"event_id": string;
"type": "response.output_audio_transcript.delta";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"delta": string;
};
/** Returned when the model-generated transcription of audio output is done
streaming. Also emitted when a Response is interrupted, incomplete, or
cancelled.
*/
export type RealtimeBetaServerEventResponseAudioTranscriptDone = {
"event_id": string;
"type": "response.output_audio_transcript.done";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"transcript": string;
};
/** Returned when a new content part is added to an assistant message item during
response generation.
*/
export type RealtimeBetaServerEventResponseContentPartAdded = {
"event_id": string;
"type": "response.content_part.added";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"part": {
"type"?: "audio" | "text";
"text"?: string;
"audio"?: string;
"transcript"?: string;
};
};
/** Returned when a content part is done streaming in an assistant message item.
Also emitted when a Response is interrupted, incomplete, or cancelled.
*/
export type RealtimeBetaServerEventResponseContentPartDone = {
"event_id": string;
"type": "response.content_part.done";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"part": {
"type"?: "audio" | "text";
"text"?: string;
"audio"?: string;
"transcript"?: string;
};
};
/** Returned when a new Response is created. The first event of response creation,
where the response is in an initial state of `in_progress`.
*/
export type RealtimeBetaServerEventResponseCreated = {
"event_id": string;
"type": "response.created";
"response": RealtimeBetaResponse;
};
/** Returned when a Response is done streaming. Always emitted, no matter the
final state. The Response object included in the `response.done` event will
include all output Items in the Response but will omit the raw audio data.
*/
export type RealtimeBetaServerEventResponseDone = {
"event_id": string;
"type": "response.done";
"response": RealtimeBetaResponse;
};
/** Returned when the model-generated function call arguments are updated.
*/
export type RealtimeBetaServerEventResponseFunctionCallArgumentsDelta = {
"event_id": string;
"type": "response.function_call_arguments.delta";
"response_id": string;
"item_id": string;
"output_index": number;
"call_id": string;
"delta": string;
};
/** Returned when the model-generated function call arguments are done streaming.
Also emitted when a Response is interrupted, incomplete, or cancelled.
*/
export type RealtimeBetaServerEventResponseFunctionCallArgumentsDone = {
"event_id": string;
"type": "response.function_call_arguments.done";
"response_id": string;
"item_id": string;
"output_index": number;
"call_id": string;
"name": string;
"arguments": string;
};
/** Returned when MCP tool call arguments are updated during response generation. */
export type RealtimeBetaServerEventResponseMCPCallArgumentsDelta = {
"event_id": string;
"type": "response.mcp_call_arguments.delta";
"response_id": string;
"item_id": string;
"output_index": number;
"delta": string;
"obfuscation"?: Record<string, unknown>;
};
/** Returned when MCP tool call arguments are finalized during response generation. */
export type RealtimeBetaServerEventResponseMCPCallArgumentsDone = {
"event_id": string;
"type": "response.mcp_call_arguments.done";
"response_id": string;
"item_id": string;
"output_index": number;
"arguments": string;
};
/** Returned when an MCP tool call has completed successfully. */
export type RealtimeBetaServerEventResponseMCPCallCompleted = {
"event_id": string;
"type": "response.mcp_call.completed";
"output_index": number;
"item_id": string;
};
/** Returned when an MCP tool call has failed. */
export type RealtimeBetaServerEventResponseMCPCallFailed = {
"event_id": string;
"type": "response.mcp_call.failed";
"output_index": number;
"item_id": string;
};
/** Returned when an MCP tool call has started and is in progress. */
export type RealtimeBetaServerEventResponseMCPCallInProgress = {
"event_id": string;
"type": "response.mcp_call.in_progress";
"output_index": number;
"item_id": string;
};
/** Returned when a new Item is created during Response generation. */
export type RealtimeBetaServerEventResponseOutputItemAdded = {
"event_id": string;
"type": "response.output_item.added";
"response_id": string;
"output_index": number;
"item": RealtimeConversationItem;
};
/** Returned when an Item is done streaming. Also emitted when a Response is
interrupted, incomplete, or cancelled.
*/
export type RealtimeBetaServerEventResponseOutputItemDone = {
"event_id": string;
"type": "response.output_item.done";
"response_id": string;
"output_index": number;
"item": RealtimeConversationItem;
};
/** Returned when the text value of an "output_text" content part is updated. */
export type RealtimeBetaServerEventResponseTextDelta = {
"event_id": string;
"type": "response.output_text.delta";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"delta": string;
};
/** Returned when the text value of an "output_text" content part is done streaming. Also
emitted when a Response is interrupted, incomplete, or cancelled.
*/
export type RealtimeBetaServerEventResponseTextDone = {
"event_id": string;
"type": "response.output_text.done";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"text": string;
};
/** Returned when a Session is created. Emitted automatically when a new
connection is established as the first server event. This event will contain
the default Session configuration.
*/
export type RealtimeBetaServerEventSessionCreated = {
"event_id": string;
"type": "session.created";
"session": RealtimeSession;
};
/** Returned when a session is updated with a `session.update` event, unless
there is an error.
*/
export type RealtimeBetaServerEventSessionUpdated = {
"event_id": string;
"type": "session.updated";
"session": RealtimeSession;
};
/** Returned when a transcription session is created.
*/
export type RealtimeBetaServerEventTranscriptionSessionCreated = {
"event_id": string;
"type": "transcription_session.created";
"session": RealtimeTranscriptionSessionCreateResponse;
};
/** Returned when a transcription session is updated with a `transcription_session.update` event, unless
there is an error.
*/
export type RealtimeBetaServerEventTranscriptionSessionUpdated = {
"event_id": string;
"type": "transcription_session.updated";
"session": RealtimeTranscriptionSessionCreateResponse;
};
/** Parameters required to initiate a realtime call and receive the SDP answer
needed to complete a WebRTC peer connection. Provide an SDP offer generated
by your client and optionally configure the session that will answer the call. */
export type RealtimeCallCreateRequest = {
"sdp": string;
"session"?: Record<string, unknown>;
};
/** Parameters required to transfer a SIP call to a new destination using the
Realtime API. */
export type RealtimeCallReferRequest = {
"target_uri": string;
};
/** Parameters used to decline an incoming SIP call handled by the Realtime API. */
export type RealtimeCallRejectRequest = {
"status_code"?: number;
};
/** A realtime client event.
*/
export type RealtimeClientEvent = Record<string, unknown>;
/** Add a new Item to the Conversation's context, including messages, function
calls, and function call responses. This event can be used both to populate a
"history" of the conversation and to add new items mid-stream, but has the
current limitation that it cannot populate assistant audio messages.
If successful, the server will respond with a `conversation.item.created`
event, otherwise an `error` event will be sent.
*/
export type RealtimeClientEventConversationItemCreate = {
"event_id"?: string;
"type": "conversation.item.create";
"previous_item_id"?: string;
"item": RealtimeConversationItem;
};
/** Send this event when you want to remove any item from the conversation
history. The server will respond with a `conversation.item.deleted` event,
unless the item does not exist in the conversation history, in which case the
server will respond with an error.
*/
export type RealtimeClientEventConversationItemDelete = {
"event_id"?: string;
"type": "conversation.item.delete";
"item_id": string;
};
/** Send this event when you want to retrieve the server's representation of a specific item in the conversation history. This is useful, for example, to inspect user audio after noise cancellation and VAD.
The server will respond with a `conversation.item.retrieved` event,
unless the item does not exist in the conversation history, in which case the
server will respond with an error.
*/
export type RealtimeClientEventConversationItemRetrieve = {
"event_id"?: string;
"type": "conversation.item.retrieve";
"item_id": string;
};
/** Send this event to truncate a previous assistant message’s audio. The server
will produce audio faster than realtime, so this event is useful when the user
interrupts to truncate audio that has already been sent to the client but not
yet played. This will synchronize the server's understanding of the audio with
the client's playback.
Truncating audio will delete the server-side text transcript to ensure there
is not text in the context that hasn't been heard by the user.
If successful, the server will respond with a `conversation.item.truncated`
event.
*/
export type RealtimeClientEventConversationItemTruncate = {
"event_id"?: string;
"type": "conversation.item.truncate";
"item_id": string;
"content_index": number;
"audio_end_ms": number;
};
/** Send this event to append audio bytes to the input audio buffer. The audio
buffer is temporary storage you can write to and later commit. A "commit" will create a new
user message item in the conversation history from the buffer content and clear the buffer.
Input audio transcription (if enabled) will be generated when the buffer is committed.
If VAD is enabled the audio buffer is used to detect speech and the server will decide
when to commit. When Server VAD is disabled, you must commit the audio buffer
manually. Input audio noise reduction operates on writes to the audio buffer.
The client may choose how much audio to place in each event up to a maximum
of 15 MiB, for example streaming smaller chunks from the client may allow the
VAD to be more responsive. Unlike most other client events, the server will
not send a confirmation response to this event.
*/
export type RealtimeClientEventInputAudioBufferAppend = {
"event_id"?: string;
"type": "input_audio_buffer.append";
"audio": string;
};
/** Send this event to clear the audio bytes in the buffer. The server will
respond with an `input_audio_buffer.cleared` event.
*/
export type RealtimeClientEventInputAudioBufferClear = {
"event_id"?: string;
"type": "input_audio_buffer.clear";
};
/** Send this event to commit the user input audio buffer, which will create a new user message item in the conversation. This event will produce an error if the input audio buffer is empty. When in Server VAD mode, the client does not need to send this event, the server will commit the audio buffer automatically.
Committing the input audio buffer will trigger input audio transcription (if enabled in session configuration), but it will not create a response from the model. The server will respond with an `input_audio_buffer.committed` event.
*/
export type RealtimeClientEventInputAudioBufferCommit = {
"event_id"?: string;
"type": "input_audio_buffer.commit";
};
/** **WebRTC/SIP Only:** Emit to cut off the current audio response. This will trigger the server to
stop generating audio and emit a `output_audio_buffer.cleared` event. This
event should be preceded by a `response.cancel` client event to stop the
generation of the current response.
[Learn more](/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc).
*/
export type RealtimeClientEventOutputAudioBufferClear = {
"event_id"?: string;
"type": "output_audio_buffer.clear";
};
/** Send this event to cancel an in-progress response. The server will respond
with a `response.done` event with a status of `response.status=cancelled`. If
there is no response to cancel, the server will respond with an error. It's safe
to call `response.cancel` even if no response is in progress, an error will be
returned the session will remain unaffected.
*/
export type RealtimeClientEventResponseCancel = {
"event_id"?: string;
"type": "response.cancel";
"response_id"?: string;
};
/** This event instructs the server to create a Response, which means triggering
model inference. When in Server VAD mode, the server will create Responses
automatically.
A Response will include at least one Item, and may have two, in which case
the second will be a function call. These Items will be appended to the
conversation history by default.
The server will respond with a `response.created` event, events for Items
and content created, and finally a `response.done` event to indicate the
Response is complete.
The `response.create` event includes inference configuration like
`instructions` and `tools`. If these are set, they will override the Session's
configuration for this Response only.
Responses can be created out-of-band of the default Conversation, meaning that they can
have arbitrary input, and it's possible to disable writing the output to the Conversation.
Only one Response can write to the default Conversation at a time, but otherwise multiple
Responses can be created in parallel. The `metadata` field is a good way to disambiguate
multiple simultaneous Responses.
Clients can set `conversation` to `none` to create a Response that does not write to the default
Conversation. Arbitrary input can be provided with the `input` field, which is an array accepting
raw Items and references to existing Items.
*/
export type RealtimeClientEventResponseCreate = {
"event_id"?: string;
"type": "response.create";
"response"?: RealtimeResponseCreateParams;
};
/** Send this event to update the session’s configuration.
The client may send this event at any time to update any field
except for `voice` and `model`. `voice` can be updated only if there have been no other audio outputs yet.
When the server receives a `session.update`, it will respond
with a `session.updated` event showing the full, effective configuration.
Only the fields that are present in the `session.update` are updated. To clear a field like
`instructions`, pass an empty string. To clear a field like `tools`, pass an empty array.
To clear a field like `turn_detection`, pass `null`.
*/
export type RealtimeClientEventSessionUpdate = {
"event_id"?: string;
"type": "session.update";
"session": Record<string, unknown>;
};
/** Send this event to update a transcription session.
*/
export type RealtimeClientEventTranscriptionSessionUpdate = {
"event_id"?: string;
"type": "transcription_session.update";
"session": RealtimeTranscriptionSessionCreateRequest;
};
/** A single item within a Realtime conversation. */
export type RealtimeConversationItem = Record<string, unknown>;
/** A function call item in a Realtime conversation. */
export type RealtimeConversationItemFunctionCall = {
"id"?: string;
"object"?: "realtime.item";
"type": "function_call";
"status"?: "completed" | "incomplete" | "in_progress";
"call_id"?: string;
"name": string;
"arguments": string;
};
/** A function call output item in a Realtime conversation. */
export type RealtimeConversationItemFunctionCallOutput = {
"id"?: string;
"object"?: "realtime.item";
"type": "function_call_output";
"status"?: "completed" | "incomplete" | "in_progress";
"call_id": string;
"output": string;
};
/** An assistant message item in a Realtime conversation. */
export type RealtimeConversationItemMessageAssistant = {
"id"?: string;
"object"?: "realtime.item";
"type": "message";
"status"?: "completed" | "incomplete" | "in_progress";
"role": "assistant";
"content": Array<{
"type"?: "output_text" | "output_audio";
"text"?: string;
"audio"?: string;
"transcript"?: string;
}>;
};
/** A system message in a Realtime conversation can be used to provide additional context or instructions to the model. This is similar but distinct from the instruction prompt provided at the start of a conversation, as system messages can be added at any point in the conversation. For major changes to the conversation's behavior, use instructions, but for smaller updates (e.g. "the user is now asking about a different topic"), use system messages. */
export type RealtimeConversationItemMessageSystem = {
"id"?: string;
"object"?: "realtime.item";
"type": "message";
"status"?: "completed" | "incomplete" | "in_progress";
"role": "system";
"content": Array<{
"type"?: "input_text";
"text"?: string;
}>;
};
/** A user message item in a Realtime conversation. */
export type RealtimeConversationItemMessageUser = {
"id"?: string;
"object"?: "realtime.item";
"type": "message";
"status"?: "completed" | "incomplete" | "in_progress";
"role": "user";
"content": Array<{
"type"?: "input_text" | "input_audio" | "input_image";
"text"?: string;
"audio"?: string;
"image_url"?: string;
"detail"?: "auto" | "low" | "high";
"transcript"?: string;
}>;
};
/** The item to add to the conversation. */
export type RealtimeConversationItemWithReference = {
"id"?: string;
"type"?: "message" | "function_call" | "function_call_output";
"object"?: "realtime.item";
"status"?: "completed" | "incomplete" | "in_progress";
"role"?: "user" | "assistant" | "system";
"content"?: Array<{
"type"?: "input_audio" | "input_text" | "item_reference" | "text";
"text"?: string;
"id"?: string;
"audio"?: string;
"transcript"?: string;
}>;
"call_id"?: string;
"name"?: string;
"arguments"?: string;
"output"?: string;
};
/** Create a session and client secret for the Realtime API. The request can specify
either a realtime or a transcription session configuration.
[Learn more about the Realtime API](/docs/guides/realtime).
*/
export type RealtimeCreateClientSecretRequest = {
"expires_after"?: {
"anchor"?: "created_at";
"seconds"?: number;
};
"session"?: Record<string, unknown>;
};
/** Response from creating a session and client secret for the Realtime API.
*/
export type RealtimeCreateClientSecretResponse = {
"value": string;
"expires_at": number;
"session": Record<string, unknown>;
};
export type RealtimeFunctionTool = {
"type"?: "function";
"name"?: string;
"description"?: string;
"parameters"?: Record<string, unknown>;
};
/** A Realtime item requesting human approval of a tool invocation.
*/
export type RealtimeMCPApprovalRequest = {
"type": "mcp_approval_request";
"id": string;
"server_label": string;
"name": string;
"arguments": string;
};
/** A Realtime item responding to an MCP approval request.
*/
export type RealtimeMCPApprovalResponse = {
"type": "mcp_approval_response";
"id": string;
"approval_request_id": string;
"approve": boolean;
"reason"?: Record<string, unknown>;
};
export type RealtimeMCPHTTPError = {
"type": "http_error";
"code": number;
"message": string;
};
/** A Realtime item listing tools available on an MCP server.
*/
export type RealtimeMCPListTools = {
"type": "mcp_list_tools";
"id"?: string;
"server_label": string;
"tools": Array<MCPListToolsTool>;
};
export type RealtimeMCPProtocolError = {
"type": "protocol_error";
"code": number;
"message": string;
};
/** A Realtime item representing an invocation of a tool on an MCP server.
*/
export type RealtimeMCPToolCall = {
"type": "mcp_call";
"id": string;
"server_label": string;
"name": string;
"arguments": string;
"approval_request_id"?: Record<string, unknown>;
"output"?: Record<string, unknown>;
"error"?: Record<string, unknown>;
};
export type RealtimeMCPToolExecutionError = {
"type": "tool_execution_error";
"message": string;
};
/** Configuration for reasoning-capable Realtime models such as `gpt-realtime-2`.
*/
export type RealtimeReasoning = {
"effort"?: RealtimeReasoningEffort;
};
/** Constrains effort on reasoning for reasoning-capable Realtime models such as
`gpt-realtime-2`.
*/
export type RealtimeReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh";
/** The response resource. */
export type RealtimeResponse = {
"id"?: string;
"object"?: "realtime.response";
"status"?: "completed" | "cancelled" | "failed" | "incomplete" | "in_progress";
"status_details"?: {
"type"?: "completed" | "cancelled" | "failed" | "incomplete";
"reason"?: "turn_detected" | "client_cancelled" | "max_output_tokens" | "content_filter";
"error"?: {
"type"?: string;
"code"?: string;
};
};
"output"?: Array<RealtimeConversationItem>;
"metadata"?: Metadata;
"audio"?: {
"output"?: {
"format"?: RealtimeAudioFormats;
"voice"?: VoiceIdsShared;
};
};
"usage"?: {
"total_tokens"?: number;
"input_tokens"?: number;
"output_tokens"?: number;
"input_token_details"?: {
"cached_tokens"?: number;
"text_tokens"?: number;
"image_tokens"?: number;
"audio_tokens"?: number;
"cached_tokens_details"?: {
"text_tokens"?: number;
"image_tokens"?: number;
"audio_tokens"?: number;
};
};
"output_token_details"?: {
"text_tokens"?: number;
"audio_tokens"?: number;
};
};
"conversation_id"?: string;
"output_modalities"?: Array<"text" | "audio">;
"max_output_tokens"?: Record<string, unknown>;
};
/** Create a new Realtime response with these parameters */
export type RealtimeResponseCreateParams = {
"output_modalities"?: Array<"text" | "audio">;
"instructions"?: string;
"audio"?: {
"output"?: {
"format"?: RealtimeAudioFormats;
"voice"?: VoiceIdsOrCustomVoice;
};
};
"tools"?: Array<Record<string, unknown>>;
"tool_choice"?: Record<string, unknown>;
"parallel_tool_calls"?: boolean;
"reasoning"?: RealtimeReasoning;
"max_output_tokens"?: Record<string, unknown>;
"conversation"?: Record<string, unknown>;
"metadata"?: Metadata;
"prompt"?: Prompt;
"input"?: Array<RealtimeConversationItem>;
};
/** A realtime server event.
*/
export type RealtimeServerEvent = Record<string, unknown>;
/** Returned when a conversation is created. Emitted right after session creation.
*/
export type RealtimeServerEventConversationCreated = {
"event_id": string;
"type": "conversation.created";
"conversation": {
"id"?: string;
"object"?: string;
};
};
/** Sent by the server when an Item is added to the default Conversation. This can happen in several cases:
- When the client sends a `conversation.item.create` event.
- When the input audio buffer is committed. In this case the item will be a user message containing the audio from the buffer.
- When the model is generating a Response. In this case the `conversation.item.added` event will be sent when the model starts generating a specific Item, and thus it will not yet have any content (and `status` will be `in_progress`).
The event will include the full content of the Item (except when model is generating a Response) except for audio data, which can be retrieved separately with a `conversation.item.retrieve` event if necessary.
*/
export type RealtimeServerEventConversationItemAdded = {
"event_id": string;
"type": "conversation.item.added";
"previous_item_id"?: Record<string, unknown>;
"item": RealtimeConversationItem;
};
/** Returned when a conversation item is created. There are several scenarios that produce this event:
- The server is generating a Response, which if successful will produce
either one or two Items, which will be of type `message`
(role `assistant`) or type `function_call`.
- The input audio buffer has been committed, either by the client or the
server (in `server_vad` mode). The server will take the content of the
input audio buffer and add it to a new user message Item.
- The client has sent a `conversation.item.create` event to add a new Item
to the Conversation.
*/
export type RealtimeServerEventConversationItemCreated = {
"event_id": string;
"type": "conversation.item.created";
"previous_item_id"?: Record<string, unknown>;
"item": RealtimeConversationItem;
};
/** Returned when an item in the conversation is deleted by the client with a
`conversation.item.delete` event. This event is used to synchronize the
server's understanding of the conversation history with the client's view.
*/
export type RealtimeServerEventConversationItemDeleted = {
"event_id": string;
"type": "conversation.item.deleted";
"item_id": string;
};
/** Returned when a conversation item is finalized.
The event will include the full content of the Item except for audio data, which can be retrieved separately with a `conversation.item.retrieve` event if needed.
*/
export type RealtimeServerEventConversationItemDone = {
"event_id": string;
"type": "conversation.item.done";
"previous_item_id"?: Record<string, unknown>;
"item": RealtimeConversationItem;
};
/** This event is the output of audio transcription for user audio written to the
user audio buffer. Transcription begins when the input audio buffer is
committed by the client or server (when VAD is enabled). Transcription runs
asynchronously with Response creation, so this event may come before or after
the Response events.
Realtime API models accept audio natively, and thus input transcription is a
separate process run on a separate ASR (Automatic Speech Recognition) model.
The transcript may diverge somewhat from the model's interpretation, and
should be treated as a rough guide.
*/
export type RealtimeServerEventConversationItemInputAudioTranscriptionCompleted = {
"event_id": string;
"type": "conversation.item.input_audio_transcription.completed";
"item_id": string;
"content_index": number;
"transcript": string;
"logprobs"?: Record<string, unknown>;
"usage": Record<string, unknown>;
};
/** Returned when the text value of an input audio transcription content part is updated with incremental transcription results.
*/
export type RealtimeServerEventConversationItemInputAudioTranscriptionDelta = {
"event_id": string;
"type": "conversation.item.input_audio_transcription.delta";
"item_id": string;
"content_index"?: number;
"delta"?: string;
"logprobs"?: Record<string, unknown>;
};
/** Returned when input audio transcription is configured, and a transcription
request for a user message failed. These events are separate from other
`error` events so that the client can identify the related Item.
*/
export type RealtimeServerEventConversationItemInputAudioTranscriptionFailed = {
"event_id": string;
"type": "conversation.item.input_audio_transcription.failed";
"item_id": string;
"content_index": number;
"error": {
"type"?: string;
"code"?: string;
"message"?: string;
"param"?: string;
};
};
/** Returned when an input audio transcription segment is identified for an item. */
export type RealtimeServerEventConversationItemInputAudioTranscriptionSegment = {
"event_id": string;
"type": "conversation.item.input_audio_transcription.segment";
"item_id": string;
"content_index": number;
"text": string;
"id": string;
"speaker": string;
"start": number;
"end": number;
};
/** Returned when a conversation item is retrieved with `conversation.item.retrieve`. This is provided as a way to fetch the server's representation of an item, for example to get access to the post-processed audio data after noise cancellation and VAD. It includes the full content of the Item, including audio data.
*/
export type RealtimeServerEventConversationItemRetrieved = {
"event_id": string;
"type": "conversation.item.retrieved";
"item": RealtimeConversationItem;
};
/** Returned when an earlier assistant audio message item is truncated by the
client with a `conversation.item.truncate` event. This event is used to
synchronize the server's understanding of the audio with the client's playback.
This action will truncate the audio and remove the server-side text transcript
to ensure there is no text in the context that hasn't been heard by the user.
*/
export type RealtimeServerEventConversationItemTruncated = {
"event_id": string;
"type": "conversation.item.truncated";
"item_id": string;
"content_index": number;
"audio_end_ms": number;
};
/** Returned when an error occurs, which could be a client problem or a server
problem. Most errors are recoverable and the session will stay open, we
recommend to implementors to monitor and log error messages by default.
*/
export type RealtimeServerEventError = {
"event_id": string;
"type": "error";
"error": {
"type": string;
"code"?: Record<string, unknown>;
"message": string;
"param"?: Record<string, unknown>;
"event_id"?: Record<string, unknown>;
};
};
/** Returned when the input audio buffer is cleared by the client with a
`input_audio_buffer.clear` event.
*/
export type RealtimeServerEventInputAudioBufferCleared = {
"event_id": string;
"type": "input_audio_buffer.cleared";
};
/** Returned when an input audio buffer is committed, either by the client or
automatically in server VAD mode. The `item_id` property is the ID of the user
message item that will be created, thus a `conversation.item.created` event
will also be sent to the client.
*/
export type RealtimeServerEventInputAudioBufferCommitted = {
"event_id": string;
"type": "input_audio_buffer.committed";
"previous_item_id"?: Record<string, unknown>;
"item_id": string;
};
/** **SIP Only:** Returned when an DTMF event is received. A DTMF event is a message that
represents a telephone keypad press (0–9, *, #, A–D). The `event` property
is the keypad that the user press. The `received_at` is the UTC Unix Timestamp
that the server received the event.
*/
export type RealtimeServerEventInputAudioBufferDtmfEventReceived = {
"type": "input_audio_buffer.dtmf_event_received";
"event": string;
"received_at": number;
};
/** Sent by the server when in `server_vad` mode to indicate that speech has been
detected in the audio buffer. This can happen any time audio is added to the
buffer (unless speech is already detected). The client may want to use this
event to interrupt audio playback or provide visual feedback to the user.
The client should expect to receive a `input_audio_buffer.speech_stopped` event
when speech stops. The `item_id` property is the ID of the user message item
that will be created when speech stops and will also be included in the
`input_audio_buffer.speech_stopped` event (unless the client manually commits
the audio buffer during VAD activation).
*/
export type RealtimeServerEventInputAudioBufferSpeechStarted = {
"event_id": string;
"type": "input_audio_buffer.speech_started";
"audio_start_ms": number;
"item_id": string;
};
/** Returned in `server_vad` mode when the server detects the end of speech in
the audio buffer. The server will also send an `conversation.item.created`
event with the user message item that is created from the audio buffer.
*/
export type RealtimeServerEventInputAudioBufferSpeechStopped = {
"event_id": string;
"type": "input_audio_buffer.speech_stopped";
"audio_end_ms": number;
"item_id": string;
};
/** Returned when the Server VAD timeout is triggered for the input audio buffer. This is configured
with `idle_timeout_ms` in the `turn_detection` settings of the session, and it indicates that
there hasn't been any speech detected for the configured duration.
The `audio_start_ms` and `audio_end_ms` fields indicate the segment of audio after the last
model response up to the triggering time, as an offset from the beginning of audio written
to the input audio buffer. This means it demarcates the segment of audio that was silent and
the difference between the start and end values will roughly match the configured timeout.
The empty audio will be committed to the conversation as an `input_audio` item (there will be a
`input_audio_buffer.committed` event) and a model response will be generated. There may be speech
that didn't trigger VAD but is still detected by the model, so the model may respond with
something relevant to the conversation or a prompt to continue speaking.
*/
export type RealtimeServerEventInputAudioBufferTimeoutTriggered = {
"event_id": string;
"type": "input_audio_buffer.timeout_triggered";
"audio_start_ms": number;
"audio_end_ms": number;
"item_id": string;
};
/** Returned when listing MCP tools has completed for an item. */
export type RealtimeServerEventMCPListToolsCompleted = {
"event_id": string;
"type": "mcp_list_tools.completed";
"item_id": string;
};
/** Returned when listing MCP tools has failed for an item. */
export type RealtimeServerEventMCPListToolsFailed = {
"event_id": string;
"type": "mcp_list_tools.failed";
"item_id": string;
};
/** Returned when listing MCP tools is in progress for an item. */
export type RealtimeServerEventMCPListToolsInProgress = {
"event_id": string;
"type": "mcp_list_tools.in_progress";
"item_id": string;
};
/** **WebRTC/SIP Only:** Emitted when the output audio buffer is cleared. This happens either in VAD
mode when the user has interrupted (`input_audio_buffer.speech_started`),
or when the client has emitted the `output_audio_buffer.clear` event to manually
cut off the current audio response.
[Learn more](/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc).
*/
export type RealtimeServerEventOutputAudioBufferCleared = {
"event_id": string;
"type": "output_audio_buffer.cleared";
"response_id": string;
};
/** **WebRTC/SIP Only:** Emitted when the server begins streaming audio to the client. This event is
emitted after an audio content part has been added (`response.content_part.added`)
to the response.
[Learn more](/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc).
*/
export type RealtimeServerEventOutputAudioBufferStarted = {
"event_id": string;
"type": "output_audio_buffer.started";
"response_id": string;
};
/** **WebRTC/SIP Only:** Emitted when the output audio buffer has been completely drained on the server,
and no more audio is forthcoming. This event is emitted after the full response
data has been sent to the client (`response.done`).
[Learn more](/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc).
*/
export type RealtimeServerEventOutputAudioBufferStopped = {
"event_id": string;
"type": "output_audio_buffer.stopped";
"response_id": string;
};
/** Emitted at the beginning of a Response to indicate the updated rate limits.
When a Response is created some tokens will be "reserved" for the output
tokens, the rate limits shown here reflect that reservation, which is then
adjusted accordingly once the Response is completed.
*/
export type RealtimeServerEventRateLimitsUpdated = {
"event_id": string;
"type": "rate_limits.updated";
"rate_limits": Array<{
"name"?: "requests" | "tokens";
"limit"?: number;
"remaining"?: number;
"reset_seconds"?: number;
}>;
};
/** Returned when the model-generated audio is updated. */
export type RealtimeServerEventResponseAudioDelta = {
"event_id": string;
"type": "response.output_audio.delta";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"delta": string;
};
/** Returned when the model-generated audio is done. Also emitted when a Response
is interrupted, incomplete, or cancelled.
*/
export type RealtimeServerEventResponseAudioDone = {
"event_id": string;
"type": "response.output_audio.done";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
};
/** Returned when the model-generated transcription of audio output is updated.
*/
export type RealtimeServerEventResponseAudioTranscriptDelta = {
"event_id": string;
"type": "response.output_audio_transcript.delta";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"delta": string;
};
/** Returned when the model-generated transcription of audio output is done
streaming. Also emitted when a Response is interrupted, incomplete, or
cancelled.
*/
export type RealtimeServerEventResponseAudioTranscriptDone = {
"event_id": string;
"type": "response.output_audio_transcript.done";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"transcript": string;
};
/** Returned when a new content part is added to an assistant message item during
response generation.
*/
export type RealtimeServerEventResponseContentPartAdded = {
"event_id": string;
"type": "response.content_part.added";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"part": {
"type"?: "audio" | "text";
"text"?: string;
"audio"?: string;
"transcript"?: string;
};
};
/** Returned when a content part is done streaming in an assistant message item.
Also emitted when a Response is interrupted, incomplete, or cancelled.
*/
export type RealtimeServerEventResponseContentPartDone = {
"event_id": string;
"type": "response.content_part.done";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"part": {
"type"?: "audio" | "text";
"text"?: string;
"audio"?: string;
"transcript"?: string;
};
};
/** Returned when a new Response is created. The first event of response creation,
where the response is in an initial state of `in_progress`.
*/
export type RealtimeServerEventResponseCreated = {
"event_id": string;
"type": "response.created";
"response": RealtimeResponse;
};
/** Returned when a Response is done streaming. Always emitted, no matter the
final state. The Response object included in the `response.done` event will
include all output Items in the Response but will omit the raw audio data.
Clients should check the `status` field of the Response to determine if it was successful
(`completed`) or if there was another outcome: `cancelled`, `failed`, or `incomplete`.
A response will contain all output items that were generated during the response, excluding
any audio content.
*/
export type RealtimeServerEventResponseDone = {
"event_id": string;
"type": "response.done";
"response": RealtimeResponse;
};
/** Returned when the model-generated function call arguments are updated.
*/
export type RealtimeServerEventResponseFunctionCallArgumentsDelta = {
"event_id": string;
"type": "response.function_call_arguments.delta";
"response_id": string;
"item_id": string;
"output_index": number;
"call_id": string;
"delta": string;
};
/** Returned when the model-generated function call arguments are done streaming.
Also emitted when a Response is interrupted, incomplete, or cancelled.
*/
export type RealtimeServerEventResponseFunctionCallArgumentsDone = {
"event_id": string;
"type": "response.function_call_arguments.done";
"response_id": string;
"item_id": string;
"output_index": number;
"call_id": string;
"name": string;
"arguments": string;
};
/** Returned when MCP tool call arguments are updated during response generation. */
export type RealtimeServerEventResponseMCPCallArgumentsDelta = {
"event_id": string;
"type": "response.mcp_call_arguments.delta";
"response_id": string;
"item_id": string;
"output_index": number;
"delta": string;
"obfuscation"?: Record<string, unknown>;
};
/** Returned when MCP tool call arguments are finalized during response generation. */
export type RealtimeServerEventResponseMCPCallArgumentsDone = {
"event_id": string;
"type": "response.mcp_call_arguments.done";
"response_id": string;
"item_id": string;
"output_index": number;
"arguments": string;
};
/** Returned when an MCP tool call has completed successfully. */
export type RealtimeServerEventResponseMCPCallCompleted = {
"event_id": string;
"type": "response.mcp_call.completed";
"output_index": number;
"item_id": string;
};
/** Returned when an MCP tool call has failed. */
export type RealtimeServerEventResponseMCPCallFailed = {
"event_id": string;
"type": "response.mcp_call.failed";
"output_index": number;
"item_id": string;
};
/** Returned when an MCP tool call has started and is in progress. */
export type RealtimeServerEventResponseMCPCallInProgress = {
"event_id": string;
"type": "response.mcp_call.in_progress";
"output_index": number;
"item_id": string;
};
/** Returned when a new Item is created during Response generation. */
export type RealtimeServerEventResponseOutputItemAdded = {
"event_id": string;
"type": "response.output_item.added";
"response_id": string;
"output_index": number;
"item": RealtimeConversationItem;
};
/** Returned when an Item is done streaming. Also emitted when a Response is
interrupted, incomplete, or cancelled.
*/
export type RealtimeServerEventResponseOutputItemDone = {
"event_id": string;
"type": "response.output_item.done";
"response_id": string;
"output_index": number;
"item": RealtimeConversationItem;
};
/** Returned when the text value of an "output_text" content part is updated. */
export type RealtimeServerEventResponseTextDelta = {
"event_id": string;
"type": "response.output_text.delta";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"delta": string;
};
/** Returned when the text value of an "output_text" content part is done streaming. Also
emitted when a Response is interrupted, incomplete, or cancelled.
*/
export type RealtimeServerEventResponseTextDone = {
"event_id": string;
"type": "response.output_text.done";
"response_id": string;
"item_id": string;
"output_index": number;
"content_index": number;
"text": string;
};
/** Returned when a Session is created. Emitted automatically when a new
connection is established as the first server event. This event will contain
the default Session configuration.
*/
export type RealtimeServerEventSessionCreated = {
"event_id": string;
"type": "session.created";
"session": Record<string, unknown>;
};
/** Returned when a session is updated with a `session.update` event, unless
there is an error.
*/
export type RealtimeServerEventSessionUpdated = {
"event_id": string;
"type": "session.updated";
"session": Record<string, unknown>;
};
/** Returned when a transcription session is updated with a `transcription_session.update` event, unless
there is an error.
*/
export type RealtimeServerEventTranscriptionSessionUpdated = {
"event_id": string;
"type": "transcription_session.updated";
"session": RealtimeTranscriptionSessionCreateResponse;
};
/** Realtime session object for the beta interface. */
export type RealtimeSession = {
"id"?: string;
"object"?: "realtime.session";
"modalities"?: Record<string, unknown>;
"model"?: Record<string, unknown>;
"instructions"?: string;
"voice"?: VoiceIdsShared;
"input_audio_format"?: "pcm16" | "g711_ulaw" | "g711_alaw";
"output_audio_format"?: "pcm16" | "g711_ulaw" | "g711_alaw";
"input_audio_transcription"?: Record<string, unknown>;
"turn_detection"?: RealtimeTurnDetection;
"input_audio_noise_reduction"?: {
"type"?: NoiseReductionType;
};
"speed"?: number;
"tracing"?: Record<string, unknown>;
"tools"?: Array<RealtimeFunctionTool>;
"tool_choice"?: string;
"temperature"?: number;
"max_response_output_tokens"?: Record<string, unknown>;
"expires_at"?: number;
"prompt"?: Record<string, unknown>;
"include"?: Record<string, unknown>;
};
/** A new Realtime session configuration, with an ephemeral key. Default TTL
for keys is one minute.
*/
export type RealtimeSessionCreateRequest = {
"client_secret": {
"value": string;
"expires_at": number;
};
"modalities"?: Record<string, unknown>;
"instructions"?: string;
"voice"?: VoiceIdsOrCustomVoice;
"input_audio_format"?: string;
"output_audio_format"?: string;
"input_audio_transcription"?: {
"model"?: string;
};
"speed"?: number;
"tracing"?: Record<string, unknown>;
"turn_detection"?: {
"type"?: string;
"threshold"?: number;
"prefix_padding_ms"?: number;
"silence_duration_ms"?: number;
};
"tools"?: Array<{
"type"?: "function";
"name"?: string;
"description"?: string;
"parameters"?: Record<string, unknown>;
}>;
"tool_choice"?: string;
"temperature"?: number;
"max_response_output_tokens"?: Record<string, unknown>;
"truncation"?: RealtimeTruncation;
"prompt"?: Prompt;
};
/** Realtime session object configuration. */
export type RealtimeSessionCreateRequestGA = {
"type": "realtime";
"output_modalities"?: Array<"text" | "audio">;
"model"?: Record<string, unknown>;
"instructions"?: string;
"audio"?: {
"input"?: {
"format"?: RealtimeAudioFormats;
"transcription"?: AudioTranscription;
"noise_reduction"?: {
"type"?: NoiseReductionType;
};
"turn_detection"?: RealtimeTurnDetection;
};
"output"?: {
"format"?: RealtimeAudioFormats;
"voice"?: VoiceIdsOrCustomVoice;
"speed"?: number;
};
};
"include"?: Array<"item.input_audio_transcription.logprobs">;
"tracing"?: Record<string, unknown>;
"tools"?: Array<Record<string, unknown>>;
"tool_choice"?: Record<string, unknown>;
"parallel_tool_calls"?: boolean;
"reasoning"?: RealtimeReasoning;
"max_output_tokens"?: Record<string, unknown>;
"truncation"?: RealtimeTruncation;
"prompt"?: Prompt;
};
/** A Realtime session configuration object.
*/
export type RealtimeSessionCreateResponse = {
"id"?: string;
"object"?: string;
"expires_at"?: number;
"include"?: Array<"item.input_audio_transcription.logprobs">;
"model"?: string;
"output_modalities"?: Record<string, unknown>;
"instructions"?: string;
"audio"?: {
"input"?: {
"format"?: RealtimeAudioFormats;
"transcription"?: AudioTranscriptionResponse;
"noise_reduction"?: {
"type"?: NoiseReductionType;
};
"turn_detection"?: {
"type"?: string;
"threshold"?: number;
"prefix_padding_ms"?: number;
"silence_duration_ms"?: number;
};
};
"output"?: {
"format"?: RealtimeAudioFormats;
"voice"?: VoiceIdsShared;
"speed"?: number;
};
};
"tracing"?: Record<string, unknown>;
"turn_detection"?: {
"type"?: string;
"threshold"?: number;
"prefix_padding_ms"?: number;
"silence_duration_ms"?: number;
};
"tools"?: Array<RealtimeFunctionTool>;
"tool_choice"?: string;
"max_output_tokens"?: Record<string, unknown>;
};
/** A Realtime session configuration object.
*/
export type RealtimeSessionCreateResponseGA = {
"type": "realtime";
"id": string;
"object": "realtime.session";
"expires_at"?: number;
"output_modalities"?: Array<"text" | "audio">;
"model"?: Record<string, unknown>;
"instructions"?: string;
"audio"?: {
"input"?: {
"format"?: RealtimeAudioFormats;
"transcription"?: AudioTranscriptionResponse;
"noise_reduction"?: {
"type"?: NoiseReductionType;
};
"turn_detection"?: RealtimeTurnDetection;
};
"output"?: {
"format"?: RealtimeAudioFormats;
"voice"?: VoiceIdsShared;
"speed"?: number;
};
};
"include"?: Array<"item.input_audio_transcription.logprobs">;
"tracing"?: Record<string, unknown>;
"tools"?: Array<Record<string, unknown>>;
"tool_choice"?: Record<string, unknown>;
"reasoning"?: RealtimeReasoning;
"max_output_tokens"?: Record<string, unknown>;
"truncation"?: RealtimeTruncation;
"prompt"?: Prompt;
};
/** Realtime transcription session object configuration. */
export type RealtimeTranscriptionSessionCreateRequest = {
"turn_detection"?: {
"type"?: "server_vad";
"threshold"?: number;
"prefix_padding_ms"?: number;
"silence_duration_ms"?: number;
};
"input_audio_noise_reduction"?: {
"type"?: NoiseReductionType;
};
"input_audio_format"?: "pcm16" | "g711_ulaw" | "g711_alaw";
"input_audio_transcription"?: AudioTranscription;
"include"?: Array<"item.input_audio_transcription.logprobs">;
};
/** Realtime transcription session object configuration. */
export type RealtimeTranscriptionSessionCreateRequestGA = {
"type": "transcription";
"audio"?: {
"input"?: {
"format"?: RealtimeAudioFormats;
"transcription"?: AudioTranscription;
"noise_reduction"?: {
"type"?: NoiseReductionType;
};
"turn_detection"?: RealtimeTurnDetection;
};
};
"include"?: Array<"item.input_audio_transcription.logprobs">;
};
/** A new Realtime transcription session configuration.
When a session is created on the server via REST API, the session object
also contains an ephemeral key. Default TTL for keys is 10 minutes. This
property is not present when a session is updated via the WebSocket API.
*/
export type RealtimeTranscriptionSessionCreateResponse = {
"client_secret": {
"value": string;
"expires_at": number;
};
"modalities"?: Record<string, unknown>;
"input_audio_format"?: string;
"input_audio_transcription"?: AudioTranscriptionResponse;
"turn_detection"?: {
"type"?: string;
"threshold"?: number;
"prefix_padding_ms"?: number;
"silence_duration_ms"?: number;
};
};
/** A Realtime transcription session configuration object.
*/
export type RealtimeTranscriptionSessionCreateResponseGA = {
"type": "transcription";
"id": string;
"object": string;
"expires_at"?: number;
"include"?: Array<"item.input_audio_transcription.logprobs">;
"audio"?: {
"input"?: {
"format"?: RealtimeAudioFormats;
"transcription"?: AudioTranscriptionResponse;
"noise_reduction"?: {
"type"?: NoiseReductionType;
};
"turn_detection"?: Record<string, unknown>;
};
};
};
/** A Realtime translation client event.
*/
export type RealtimeTranslationClientEvent = Record<string, unknown>;
/** Send this event to append audio bytes to the translation session input audio buffer.
WebSocket translation sessions accept base64-encoded 24 kHz PCM16 mono
little-endian raw audio bytes. Unsupported websocket audio formats return a
validation error because lower-quality audio materially degrades translation
quality.
Translation consumes 200 ms engine frames. For best realtime behavior, append
audio in 200 ms chunks. If a chunk is shorter, the server buffers it until it
has enough audio for one frame. If a chunk is longer, the server splits it into
200 ms frames and enqueues them back-to-back.
Keep appending silence while the session is active. If a client stops sending
audio and later resumes, model time treats the resumed audio as contiguous with
the previous audio rather than as a real-world pause.
*/
export type RealtimeTranslationClientEventInputAudioBufferAppend = {
"event_id"?: string;
"type": "session.input_audio_buffer.append";
"audio": string;
};
/** Gracefully close the realtime translation session. The server flushes pending
input audio and emits any remaining translated output before closing the
session.
*/
export type RealtimeTranslationClientEventSessionClose = {
"event_id"?: string;
"type": "session.close";
};
/** Send this event to update the translation session configuration. Translation
sessions support updates to `audio.output.language`, `audio.input.transcription`,
and `audio.input.noise_reduction`.
*/
export type RealtimeTranslationClientEventSessionUpdate = {
"event_id"?: string;
"type": "session.update";
"session": RealtimeTranslationSessionUpdateRequest;
};
/** Create a translation session and client secret for the Realtime API.
*/
export type RealtimeTranslationClientSecretCreateRequest = {
"expires_after"?: {
"anchor"?: "created_at";
"seconds"?: number;
};
"session": RealtimeTranslationSessionCreateRequest;
};
/** Response from creating a translation session and client secret for the Realtime API.
*/
export type RealtimeTranslationClientSecretCreateResponse = {
"value": string;
"expires_at": number;
"session": RealtimeTranslationSession;
};
/** A Realtime translation server event.
*/
export type RealtimeTranslationServerEvent = Record<string, unknown>;
/** Returned when a realtime translation session is closed.
*/
export type RealtimeTranslationServerEventSessionClosed = {
"event_id": string;
"type": "session.closed";
};
/** Returned when a translation session is created. Emitted automatically when a
new connection is established as the first server event. This event contains
the default translation session configuration.
*/
export type RealtimeTranslationServerEventSessionCreated = {
"event_id": string;
"type": "session.created";
"session": RealtimeTranslationSession;
};
/** Returned when optional source-language transcript text is available. This event
is emitted only when `audio.input.transcription` is configured.
Transcript deltas are append-only text fragments. Clients should not insert
unconditional spaces between deltas.
*/
export type RealtimeTranslationServerEventSessionInputTranscriptDelta = {
"event_id": string;
"type": "session.input_transcript.delta";
"delta": string;
"elapsed_ms"?: Record<string, unknown>;
};
/** Returned when translated output audio is available. Output audio deltas are
200 ms frames of PCM16 audio.
*/
export type RealtimeTranslationServerEventSessionOutputAudioDelta = {
"event_id": string;
"type": "session.output_audio.delta";
"delta": string;
"sample_rate"?: number;
"channels"?: number;
"format"?: "pcm16";
"elapsed_ms"?: Record<string, unknown>;
};
/** Returned when translated transcript text is available.
Transcript deltas are append-only text fragments. Clients should not insert
unconditional spaces between deltas.
*/
export type RealtimeTranslationServerEventSessionOutputTranscriptDelta = {
"event_id": string;
"type": "session.output_transcript.delta";
"delta": string;
"elapsed_ms"?: Record<string, unknown>;
};
/** Returned when a translation session is updated with a `session.update` event,
unless there is an error.
*/
export type RealtimeTranslationServerEventSessionUpdated = {
"event_id": string;
"type": "session.updated";
"session": RealtimeTranslationSession;
};
/** A Realtime translation session. Translation sessions continuously translate input
audio into the configured output language.
*/
export type RealtimeTranslationSession = {
"id": string;
"type": "translation";
"expires_at": number;
"model": string;
"audio": {
"input"?: {
"transcription"?: Record<string, unknown>;
"noise_reduction"?: Record<string, unknown>;
};
"output"?: {
"language"?: string;
};
};
};
/** Realtime translation session configuration. Translation sessions stream source
audio in and translated audio plus transcript deltas out continuously.
*/
export type RealtimeTranslationSessionCreateRequest = {
"model": string;
"audio"?: {
"input"?: {
"transcription"?: Record<string, unknown>;
"noise_reduction"?: Record<string, unknown>;
};
"output"?: {
"language"?: string;
};
};
};
/** Realtime translation session fields that can be updated with `session.update`.
*/
export type RealtimeTranslationSessionUpdateRequest = {
"audio"?: {
"input"?: {
"transcription"?: Record<string, unknown>;
"noise_reduction"?: Record<string, unknown>;
};
"output"?: {
"language"?: string;
};
};
};
/** When the number of tokens in a conversation exceeds the model's input token limit, the conversation be truncated, meaning messages (starting from the oldest) will not be included in the model's context. A 32k context model with 4,096 max output tokens can only include 28,224 tokens in the context before truncation occurs.
Clients can configure truncation behavior to truncate with a lower max token limit, which is an effective way to control token usage and cost.
Truncation will reduce the number of cached tokens on the next turn (busting the cache), since messages are dropped from the beginning of the context. However, clients can also configure truncation to retain messages up to a fraction of the maximum context size, which will reduce the need for future truncations and thus improve the cache rate.
Truncation can be disabled entirely, which means the server will never truncate but would instead return an error if the conversation exceeds the model's input token limit.
*/
export type RealtimeTruncation = Record<string, unknown>;
export type RealtimeTurnDetection = Record<string, unknown>;
/** **gpt-5 and o-series models only**
Configuration options for
[reasoning models](https://platform.openai.com/docs/guides/reasoning).
*/
export type Reasoning = {
"effort"?: ReasoningEffort;
"summary"?: Record<string, unknown>;
"generate_summary"?: Record<string, unknown>;
};
export type ReasoningEffort = Record<string, unknown>;
/** A description of the chain of thought used by a reasoning model while generating
a response. Be sure to include these items in your `input` to the Responses API
for subsequent turns of a conversation if you are manually
[managing context](/docs/guides/conversation-state).
*/
export type ReasoningItem = {
"type": "reasoning";
"id": string;
"encrypted_content"?: Record<string, unknown>;
"summary": Array<SummaryTextContent>;
"content"?: Array<ReasoningTextContent>;
"status"?: "in_progress" | "completed" | "incomplete";
};
export type Response = Record<string, unknown>;
/** Emitted when there is a partial audio response. */
export type ResponseAudioDeltaEvent = {
"type": "response.audio.delta";
"sequence_number": number;
"delta": string;
};
/** Emitted when the audio response is complete. */
export type ResponseAudioDoneEvent = {
"type": "response.audio.done";
"sequence_number": number;
};
/** Emitted when there is a partial transcript of audio. */
export type ResponseAudioTranscriptDeltaEvent = {
"type": "response.audio.transcript.delta";
"delta": string;
"sequence_number": number;
};
/** Emitted when the full audio transcript is completed. */
export type ResponseAudioTranscriptDoneEvent = {
"type": "response.audio.transcript.done";
"sequence_number": number;
};
/** Emitted when a partial code snippet is streamed by the code interpreter. */
export type ResponseCodeInterpreterCallCodeDeltaEvent = {
"type": "response.code_interpreter_call_code.delta";
"output_index": number;
"item_id": string;
"delta": string;
"sequence_number": number;
};
/** Emitted when the code snippet is finalized by the code interpreter. */
export type ResponseCodeInterpreterCallCodeDoneEvent = {
"type": "response.code_interpreter_call_code.done";
"output_index": number;
"item_id": string;
"code": string;
"sequence_number": number;
};
/** Emitted when the code interpreter call is completed. */
export type ResponseCodeInterpreterCallCompletedEvent = {
"type": "response.code_interpreter_call.completed";
"output_index": number;
"item_id": string;
"sequence_number": number;
};
/** Emitted when a code interpreter call is in progress. */
export type ResponseCodeInterpreterCallInProgressEvent = {
"type": "response.code_interpreter_call.in_progress";
"output_index": number;
"item_id": string;
"sequence_number": number;
};
/** Emitted when the code interpreter is actively interpreting the code snippet. */
export type ResponseCodeInterpreterCallInterpretingEvent = {
"type": "response.code_interpreter_call.interpreting";
"output_index": number;
"item_id": string;
"sequence_number": number;
};
/** Emitted when the model response is complete. */
export type ResponseCompletedEvent = {
"type": "response.completed";
"response": Response;
"sequence_number": number;
};
/** Emitted when a new content part is added. */
export type ResponseContentPartAddedEvent = {
"type": "response.content_part.added";
"item_id": string;
"output_index": number;
"content_index": number;
"part": OutputContent;
"sequence_number": number;
};
/** Emitted when a content part is done. */
export type ResponseContentPartDoneEvent = {
"type": "response.content_part.done";
"item_id": string;
"output_index": number;
"content_index": number;
"sequence_number": number;
"part": OutputContent;
};
/** An event that is emitted when a response is created.
*/
export type ResponseCreatedEvent = {
"type": "response.created";
"response": Response;
"sequence_number": number;
};
/** Event representing a delta (partial update) to the input of a custom tool call.
*/
export type ResponseCustomToolCallInputDeltaEvent = {
"type": "response.custom_tool_call_input.delta";
"sequence_number": number;
"output_index": number;
"item_id": string;
"delta": string;
};
/** Event indicating that input for a custom tool call is complete.
*/
export type ResponseCustomToolCallInputDoneEvent = {
"type": "response.custom_tool_call_input.done";
"sequence_number": number;
"output_index": number;
"item_id": string;
"input": string;
};
export type ResponseError = Record<string, unknown>;
/** The error code for the response.
*/
export type ResponseErrorCode = "server_error" | "rate_limit_exceeded" | "invalid_prompt" | "vector_store_timeout" | "invalid_image" | "invalid_image_format" | "invalid_base64_image" | "invalid_image_url" | "image_too_large" | "image_too_small" | "image_parse_error" | "image_content_policy_violation" | "invalid_image_mode" | "image_file_too_large" | "unsupported_image_media_type" | "empty_image_file" | "failed_to_download_image" | "image_file_not_found";
/** Emitted when an error occurs. */
export type ResponseErrorEvent = {
"type": "error";
"code": Record<string, unknown>;
"message": string;
"param": Record<string, unknown>;
"sequence_number": number;
};
/** An event that is emitted when a response fails.
*/
export type ResponseFailedEvent = {
"type": "response.failed";
"sequence_number": number;
"response": Response;
};
/** Emitted when a file search call is completed (results found). */
export type ResponseFileSearchCallCompletedEvent = {
"type": "response.file_search_call.completed";
"output_index": number;
"item_id": string;
"sequence_number": number;
};
/** Emitted when a file search call is initiated. */
export type ResponseFileSearchCallInProgressEvent = {
"type": "response.file_search_call.in_progress";
"output_index": number;
"item_id": string;
"sequence_number": number;
};
/** Emitted when a file search is currently searching. */
export type ResponseFileSearchCallSearchingEvent = {
"type": "response.file_search_call.searching";
"output_index": number;
"item_id": string;
"sequence_number": number;
};
/** JSON object response format. An older method of generating JSON responses.
Using `json_schema` is recommended for models that support it. Note that the
model will not generate JSON without a system or user message instructing it
to do so.
*/
export type ResponseFormatJsonObject = {
"type": "json_object";
};
/** JSON Schema response format. Used to generate structured JSON responses.
Learn more about [Structured Outputs](/docs/guides/structured-outputs).
*/
export type ResponseFormatJsonSchema = {
"type": "json_schema";
"json_schema": {
"description"?: string;
"name": string;
"schema"?: ResponseFormatJsonSchemaSchema;
"strict"?: Record<string, unknown>;
};
};
/** The schema for the response format, described as a JSON Schema object.
Learn how to build JSON schemas [here](https://json-schema.org/).
*/
export type ResponseFormatJsonSchemaSchema = Record<string, Record<string, unknown>>;
/** Default response format. Used to generate text responses.
*/
export type ResponseFormatText = {
"type": "text";
};
/** A custom grammar for the model to follow when generating text.
Learn more in the [custom grammars guide](/docs/guides/custom-grammars).
*/
export type ResponseFormatTextGrammar = {
"type": "grammar";
"grammar": string;
};
/** Configure the model to generate valid Python code. See the
[custom grammars guide](/docs/guides/custom-grammars) for more details.
*/
export type ResponseFormatTextPython = {
"type": "python";
};
/** Emitted when there is a partial function-call arguments delta. */
export type ResponseFunctionCallArgumentsDeltaEvent = {
"type": "response.function_call_arguments.delta";
"item_id": string;
"output_index": number;
"sequence_number": number;
"delta": string;
};
/** Emitted when function-call arguments are finalized. */
export type ResponseFunctionCallArgumentsDoneEvent = {
"type": "response.function_call_arguments.done";
"item_id": string;
"name": string;
"output_index": number;
"sequence_number": number;
"arguments": string;
};
/** Emitted when an image generation tool call has completed and the final image is available.
*/
export type ResponseImageGenCallCompletedEvent = {
"type": "response.image_generation_call.completed";
"output_index": number;
"sequence_number": number;
"item_id": string;
};
/** Emitted when an image generation tool call is actively generating an image (intermediate state).
*/
export type ResponseImageGenCallGeneratingEvent = {
"type": "response.image_generation_call.generating";
"output_index": number;
"item_id": string;
"sequence_number": number;
};
/** Emitted when an image generation tool call is in progress.
*/
export type ResponseImageGenCallInProgressEvent = {
"type": "response.image_generation_call.in_progress";
"output_index": number;
"item_id": string;
"sequence_number": number;
};
/** Emitted when a partial image is available during image generation streaming.
*/
export type ResponseImageGenCallPartialImageEvent = {
"type": "response.image_generation_call.partial_image";
"output_index": number;
"item_id": string;
"sequence_number": number;
"partial_image_index": number;
"partial_image_b64": string;
};
/** Emitted when the response is in progress. */
export type ResponseInProgressEvent = {
"type": "response.in_progress";
"response": Response;
"sequence_number": number;
};
/** An event that is emitted when a response finishes as incomplete.
*/
export type ResponseIncompleteEvent = {
"type": "response.incomplete";
"response": Response;
"sequence_number": number;
};
/** A list of Response items. */
export type ResponseItemList = {
"object": "list";
"data": Array<ItemResource>;
"has_more": boolean;
"first_id": string;
"last_id": string;
};
/** A logprob is the logarithmic probability that the model assigns to producing
a particular token at a given position in the sequence. Less-negative (higher)
logprob values indicate greater model confidence in that token choice.
*/
export type ResponseLogProb = {
"token": string;
"logprob": number;
"top_logprobs"?: Array<{
"token"?: string;
"logprob"?: number;
}>;
};
/** Emitted when there is a delta (partial update) to the arguments of an MCP tool call.
*/
export type ResponseMCPCallArgumentsDeltaEvent = {
"type": "response.mcp_call_arguments.delta";
"output_index": number;
"item_id": string;
"delta": string;
"sequence_number": number;
};
/** Emitted when the arguments for an MCP tool call are finalized.
*/
export type ResponseMCPCallArgumentsDoneEvent = {
"type": "response.mcp_call_arguments.done";
"output_index": number;
"item_id": string;
"arguments": string;
"sequence_number": number;
};
/** Emitted when an MCP tool call has completed successfully.
*/
export type ResponseMCPCallCompletedEvent = {
"type": "response.mcp_call.completed";
"item_id": string;
"output_index": number;
"sequence_number": number;
};
/** Emitted when an MCP tool call has failed.
*/
export type ResponseMCPCallFailedEvent = {
"type": "response.mcp_call.failed";
"item_id": string;
"output_index": number;
"sequence_number": number;
};
/** Emitted when an MCP tool call is in progress.
*/
export type ResponseMCPCallInProgressEvent = {
"type": "response.mcp_call.in_progress";
"sequence_number": number;
"output_index": number;
"item_id": string;
};
/** Emitted when the list of available MCP tools has been successfully retrieved.
*/
export type ResponseMCPListToolsCompletedEvent = {
"type": "response.mcp_list_tools.completed";
"item_id": string;
"output_index": number;
"sequence_number": number;
};
/** Emitted when the attempt to list available MCP tools has failed.
*/
export type ResponseMCPListToolsFailedEvent = {
"type": "response.mcp_list_tools.failed";
"item_id": string;
"output_index": number;
"sequence_number": number;
};
/** Emitted when the system is in the process of retrieving the list of available MCP tools.
*/
export type ResponseMCPListToolsInProgressEvent = {
"type": "response.mcp_list_tools.in_progress";
"item_id": string;
"output_index": number;
"sequence_number": number;
};
export type ResponseModalities = Record<string, unknown>;
/** Emitted when a new output item is added. */
export type ResponseOutputItemAddedEvent = {
"type": "response.output_item.added";
"output_index": number;
"sequence_number": number;
"item": OutputItem;
};
/** Emitted when an output item is marked done. */
export type ResponseOutputItemDoneEvent = {
"type": "response.output_item.done";
"output_index": number;
"sequence_number": number;
"item": OutputItem;
};
/** Emitted when an annotation is added to output text content.
*/
export type ResponseOutputTextAnnotationAddedEvent = {
"type": "response.output_text.annotation.added";
"item_id": string;
"output_index": number;
"content_index": number;
"annotation_index": number;
"sequence_number": number;
"annotation": Record<string, unknown>;
};
export type ResponsePromptVariables = Record<string, unknown>;
export type ResponseProperties = {
"previous_response_id"?: Record<string, unknown>;
"model"?: ModelIdsResponses;
"reasoning"?: Record<string, unknown>;
"background"?: Record<string, unknown>;
"max_tool_calls"?: Record<string, unknown>;
"text"?: ResponseTextParam;
"tools"?: ToolsArray;
"tool_choice"?: ToolChoiceParam;
"prompt"?: Prompt;
"truncation"?: Record<string, unknown>;
};
/** Emitted when a response is queued and waiting to be processed.
*/
export type ResponseQueuedEvent = {
"type": "response.queued";
"response": Response;
"sequence_number": number;
};
/** Emitted when a new reasoning summary part is added. */
export type ResponseReasoningSummaryPartAddedEvent = {
"type": "response.reasoning_summary_part.added";
"item_id": string;
"output_index": number;
"summary_index": number;
"sequence_number": number;
"part": {
"type": "summary_text";
"text": string;
};
};
/** Emitted when a reasoning summary part is completed. */
export type ResponseReasoningSummaryPartDoneEvent = {
"type": "response.reasoning_summary_part.done";
"item_id": string;
"output_index": number;
"summary_index": number;
"sequence_number": number;
"part": {
"type": "summary_text";
"text": string;
};
};
/** Emitted when a delta is added to a reasoning summary text. */
export type ResponseReasoningSummaryTextDeltaEvent = {
"type": "response.reasoning_summary_text.delta";
"item_id": string;
"output_index": number;
"summary_index": number;
"delta": string;
"sequence_number": number;
};
/** Emitted when a reasoning summary text is completed. */
export type ResponseReasoningSummaryTextDoneEvent = {
"type": "response.reasoning_summary_text.done";
"item_id": string;
"output_index": number;
"summary_index": number;
"text": string;
"sequence_number": number;
};
/** Emitted when a delta is added to a reasoning text. */
export type ResponseReasoningTextDeltaEvent = {
"type": "response.reasoning_text.delta";
"item_id": string;
"output_index": number;
"content_index": number;
"delta": string;
"sequence_number": number;
};
/** Emitted when a reasoning text is completed. */
export type ResponseReasoningTextDoneEvent = {
"type": "response.reasoning_text.done";
"item_id": string;
"output_index": number;
"content_index": number;
"text": string;
"sequence_number": number;
};
/** Emitted when there is a partial refusal text. */
export type ResponseRefusalDeltaEvent = {
"type": "response.refusal.delta";
"item_id": string;
"output_index": number;
"content_index": number;
"delta": string;
"sequence_number": number;
};
/** Emitted when refusal text is finalized. */
export type ResponseRefusalDoneEvent = {
"type": "response.refusal.done";
"item_id": string;
"output_index": number;
"content_index": number;
"refusal": string;
"sequence_number": number;
};
export type ResponseStreamEvent = Record<string, unknown>;
export type ResponseStreamOptions = Record<string, unknown>;
/** Emitted when there is an additional text delta. */
export type ResponseTextDeltaEvent = {
"type": "response.output_text.delta";
"item_id": string;
"output_index": number;
"content_index": number;
"delta": string;
"sequence_number": number;
"logprobs": Array<ResponseLogProb>;
};
/** Emitted when text content is finalized. */
export type ResponseTextDoneEvent = {
"type": "response.output_text.done";
"item_id": string;
"output_index": number;
"content_index": number;
"text": string;
"sequence_number": number;
"logprobs": Array<ResponseLogProb>;
};
/** Configuration options for a text response from the model. Can be plain
text or structured JSON data. Learn more:
- [Text inputs and outputs](/docs/guides/text)
- [Structured Outputs](/docs/guides/structured-outputs)
*/
export type ResponseTextParam = {
"format"?: TextResponseFormatConfiguration;
"verbosity"?: Verbosity;
};
/** Represents token usage details including input tokens, output tokens,
a breakdown of output tokens, and the total tokens used.
*/
export type ResponseUsage = {
"input_tokens": number;
"input_tokens_details": {
"cached_tokens": number;
};
"output_tokens": number;
"output_tokens_details": {
"reasoning_tokens": number;
};
"total_tokens": number;
};
/** Emitted when a web search call is completed. */
export type ResponseWebSearchCallCompletedEvent = {
"type": "response.web_search_call.completed";
"output_index": number;
"item_id": string;
"sequence_number": number;
};
/** Emitted when a web search call is initiated. */
export type ResponseWebSearchCallInProgressEvent = {
"type": "response.web_search_call.in_progress";
"output_index": number;
"item_id": string;
"sequence_number": number;
};
/** Emitted when a web search call is executing. */
export type ResponseWebSearchCallSearchingEvent = {
"type": "response.web_search_call.searching";
"output_index": number;
"item_id": string;
"sequence_number": number;
};
/** Client events accepted by the Responses WebSocket server.
*/
export type ResponsesClientEvent = Record<string, unknown>;
/** Client event for creating a response over a persistent WebSocket connection.
This payload uses the same top-level fields as `POST /v1/responses`.
Notes:
- `stream` is implicit over WebSocket and should not be sent.
- `background` is not supported over WebSocket.
*/
export type ResponsesClientEventResponseCreate = Record<string, unknown>;
/** Server events emitted by the Responses WebSocket server.
*/
export type ResponsesServerEvent = Record<string, unknown>;
/** Details about a role that can be assigned through the public Roles API. */
export type Role = {
"object": "role";
"id": string;
"name": string;
"description": Record<string, unknown>;
"permissions": Array<string>;
"resource_type": string;
"predefined_role": boolean;
};
/** Confirmation payload returned after deleting a role. */
export type RoleDeletedResource = {
"object": "role.deleted";
"id": string;
"deleted": boolean;
};
/** Paginated list of roles assigned to a principal. */
export type RoleListResource = {
"object": "list";
"data": Array<AssignedRoleDetails>;
"has_more": boolean;
"next": Record<string, unknown>;
};
export type RunCompletionUsage = Record<string, unknown>;
export type RunGraderRequest = {
"grader": Record<string, unknown>;
"item"?: Record<string, unknown>;
"model_sample": string;
};
export type RunGraderResponse = {
"reward": number;
"metadata": {
"name": string;
"type": string;
"errors": {
"formula_parse_error": boolean;
"sample_parse_error": boolean;
"truncated_observation_error": boolean;
"unresponsive_reward_error": boolean;
"invalid_variable_error": boolean;
"other_error": boolean;
"python_grader_server_error": boolean;
"python_grader_server_error_type": Record<string, unknown>;
"python_grader_runtime_error": boolean;
"python_grader_runtime_error_details": Record<string, unknown>;
"model_grader_server_error": boolean;
"model_grader_refusal_error": boolean;
"model_grader_parse_error": boolean;
"model_grader_server_error_details": Record<string, unknown>;
};
"execution_time": number;
"scores": Record<string, Record<string, unknown>>;
"token_usage": Record<string, unknown>;
"sampled_model_name": Record<string, unknown>;
};
"sub_rewards": Record<string, Record<string, unknown>>;
"model_grader_token_usage_per_model": Record<string, Record<string, unknown>>;
};
/** Represents an execution run on a [thread](/docs/api-reference/threads). */
export type RunObject = {
"id": string;
"object": "thread.run";
"created_at": number;
"thread_id": string;
"assistant_id": string;
"status": "queued" | "in_progress" | "requires_action" | "cancelling" | "cancelled" | "failed" | "completed" | "incomplete" | "expired";
"required_action": {
"type": "submit_tool_outputs";
"submit_tool_outputs": {
"tool_calls": Array<RunToolCallObject>;
};
};
"last_error": {
"code": "server_error" | "rate_limit_exceeded" | "invalid_prompt";
"message": string;
};
"expires_at": number;
"started_at": number;
"cancelled_at": number;
"failed_at": number;
"completed_at": number;
"incomplete_details": {
"reason"?: "max_completion_tokens" | "max_prompt_tokens";
};
"model": string;
"instructions": string;
"tools": Array<Record<string, unknown>>;
"metadata": Metadata;
"usage": RunCompletionUsage;
"temperature"?: number;
"top_p"?: number;
"max_prompt_tokens": number;
"max_completion_tokens": number;
"truncation_strategy": Record<string, unknown>;
"tool_choice": Record<string, unknown>;
"parallel_tool_calls": ParallelToolCalls;
"response_format": AssistantsApiResponseFormatOption;
};
export type RunStepCompletionUsage = Record<string, unknown>;
/** Represents a run step delta i.e. any changed fields on a run step during streaming.
*/
export type RunStepDeltaObject = {
"id": string;
"object": "thread.run.step.delta";
"delta": {
"step_details"?: Record<string, unknown>;
};
};
/** Details of the message creation by the run step. */
export type RunStepDeltaStepDetailsMessageCreationObject = {
"type": "message_creation";
"message_creation"?: {
"message_id"?: string;
};
};
/** Details of the Code Interpreter tool call the run step was involved in. */
export type RunStepDeltaStepDetailsToolCallsCodeObject = {
"index": number;
"id"?: string;
"type": "code_interpreter";
"code_interpreter"?: {
"input"?: string;
"outputs"?: Array<Record<string, unknown>>;
};
};
export type RunStepDeltaStepDetailsToolCallsCodeOutputImageObject = {
"index": number;
"type": "image";
"image"?: {
"file_id"?: string;
};
};
/** Text output from the Code Interpreter tool call as part of a run step. */
export type RunStepDeltaStepDetailsToolCallsCodeOutputLogsObject = {
"index": number;
"type": "logs";
"logs"?: string;
};
export type RunStepDeltaStepDetailsToolCallsFileSearchObject = {
"index": number;
"id"?: string;
"type": "file_search";
"file_search": Record<string, unknown>;
};
export type RunStepDeltaStepDetailsToolCallsFunctionObject = {
"index": number;
"id"?: string;
"type": "function";
"function"?: {
"name"?: string;
"arguments"?: string;
"output"?: Record<string, unknown>;
};
};
/** Details of the tool call. */
export type RunStepDeltaStepDetailsToolCallsObject = {
"type": "tool_calls";
"tool_calls"?: Array<Record<string, unknown>>;
};
/** Details of the message creation by the run step. */
export type RunStepDetailsMessageCreationObject = {
"type": "message_creation";
"message_creation": {
"message_id": string;
};
};
/** Details of the Code Interpreter tool call the run step was involved in. */
export type RunStepDetailsToolCallsCodeObject = {
"id": string;
"type": "code_interpreter";
"code_interpreter": {
"input": string;
"outputs": Array<Record<string, unknown>>;
};
};
export type RunStepDetailsToolCallsCodeOutputImageObject = {
"type": "image";
"image": {
"file_id": string;
};
};
/** Text output from the Code Interpreter tool call as part of a run step. */
export type RunStepDetailsToolCallsCodeOutputLogsObject = {
"type": "logs";
"logs": string;
};
export type RunStepDetailsToolCallsFileSearchObject = {
"id": string;
"type": "file_search";
"file_search": {
"ranking_options"?: RunStepDetailsToolCallsFileSearchRankingOptionsObject;
"results"?: Array<RunStepDetailsToolCallsFileSearchResultObject>;
};
};
/** The ranking options for the file search. */
export type RunStepDetailsToolCallsFileSearchRankingOptionsObject = {
"ranker": FileSearchRanker;
"score_threshold": number;
};
/** A result instance of the file search. */
export type RunStepDetailsToolCallsFileSearchResultObject = {
"file_id": string;
"file_name": string;
"score": number;
"content"?: Array<{
"type"?: "text";
"text"?: string;
}>;
};
export type RunStepDetailsToolCallsFunctionObject = {
"id": string;
"type": "function";
"function": {
"name": string;
"arguments": string;
"output": Record<string, unknown>;
};
};
/** Details of the tool call. */
export type RunStepDetailsToolCallsObject = {
"type": "tool_calls";
"tool_calls": Array<Record<string, unknown>>;
};
/** Represents a step in execution of a run.
*/
export type RunStepObject = {
"id": string;
"object": "thread.run.step";
"created_at": number;
"assistant_id": string;
"thread_id": string;
"run_id": string;
"type": "message_creation" | "tool_calls";
"status": "in_progress" | "cancelled" | "failed" | "completed" | "expired";
"step_details": Record<string, unknown>;
"last_error": Record<string, unknown>;
"expired_at": Record<string, unknown>;
"cancelled_at": Record<string, unknown>;
"failed_at": Record<string, unknown>;
"completed_at": Record<string, unknown>;
"metadata": Metadata;
"usage": RunStepCompletionUsage;
};
export type RunStepStreamEvent = Record<string, unknown>;
export type RunStreamEvent = Record<string, unknown>;
/** Tool call objects */
export type RunToolCallObject = {
"id": string;
"type": "function";
"function": {
"name": string;
"arguments": string;
};
};
export type ServiceTier = Record<string, unknown>;
/** Emitted for each chunk of audio data generated during speech synthesis. */
export type SpeechAudioDeltaEvent = {
"type": "speech.audio.delta";
"audio": string;
};
/** Emitted when the speech synthesis is complete and all audio has been streamed. */
export type SpeechAudioDoneEvent = {
"type": "speech.audio.done";
"usage": {
"input_tokens": number;
"output_tokens": number;
"total_tokens": number;
};
};
export type StaticChunkingStrategy = {
"max_chunk_size_tokens": number;
"chunk_overlap_tokens": number;
};
/** Customize your own chunking strategy by setting chunk size and chunk overlap. */
export type StaticChunkingStrategyRequestParam = {
"type": "static";
"static": StaticChunkingStrategy;
};
export type StaticChunkingStrategyResponseParam = {
"type": "static";
"static": StaticChunkingStrategy;
};
/** Not supported with latest reasoning models `o3` and `o4-mini`.
Up to 4 sequences where the API will stop generating further tokens. The
returned text will not contain the stop sequence.
*/
export type StopConfiguration = Record<string, unknown>;
export type SubmitToolOutputsRunRequest = {
"tool_outputs": Array<{
"tool_call_id"?: string;
"output"?: string;
}>;
"stream"?: Record<string, unknown>;
};
/** An object specifying the format that the model must output.
Configuring `{ "type": "json_schema" }` enables Structured Outputs,
which ensures the model will match your supplied JSON schema. Learn more in the
[Structured Outputs guide](/docs/guides/structured-outputs).
The default format is `{ "type": "text" }` with no additional options.
**Not recommended for gpt-4o and newer models:**
Setting to `{ "type": "json_object" }` enables the older JSON mode, which
ensures the message the model generates is valid JSON. Using `json_schema`
is preferred for models that support it.
*/
export type TextResponseFormatConfiguration = Record<string, unknown>;
/** JSON Schema response format. Used to generate structured JSON responses.
Learn more about [Structured Outputs](/docs/guides/structured-outputs).
*/
export type TextResponseFormatJsonSchema = {
"type": "json_schema";
"description"?: string;
"name": string;
"schema": ResponseFormatJsonSchemaSchema;
"strict"?: Record<string, unknown>;
};
/** Represents a thread that contains [messages](/docs/api-reference/messages). */
export type ThreadObject = {
"id": string;
"object": "thread";
"created_at": number;
"tool_resources": Record<string, unknown>;
"metadata": Metadata;
};
export type ThreadStreamEvent = Record<string, unknown>;
export type ToggleCertificatesRequest = {
"certificate_ids": Array<string>;
};
/** A tool that can be used to generate a response.
*/
export type Tool = Record<string, unknown>;
/** Constrains the tools available to the model to a pre-defined set.
*/
export type ToolChoiceAllowed = {
"type": "allowed_tools";
"mode": "auto" | "required";
"tools": Array<Record<string, Record<string, unknown>>>;
};
/** Use this option to force the model to call a specific custom tool.
*/
export type ToolChoiceCustom = {
"type": "custom";
"name": string;
};
/** Use this option to force the model to call a specific function.
*/
export type ToolChoiceFunction = {
"type": "function";
"name": string;
};
/** Use this option to force the model to call a specific tool on a remote MCP server.
*/
export type ToolChoiceMCP = {
"type": "mcp";
"server_label": string;
"name"?: Record<string, unknown>;
};
/** Controls which (if any) tool is called by the model.
`none` means the model will not call any tool and instead generates a message.
`auto` means the model can pick between generating a message or calling one or
more tools.
`required` means the model must call one or more tools.
*/
export type ToolChoiceOptions = "none" | "auto" | "required";
/** 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.
*/
export type ToolChoiceParam = Record<string, unknown>;
/** Indicates that the model should use a built-in tool to generate a response.
[Learn more about built-in tools](/docs/guides/tools).
*/
export type ToolChoiceTypes = {
"type": "file_search" | "web_search_preview" | "computer" | "computer_use_preview" | "computer_use" | "web_search_preview_2025_03_11" | "image_generation" | "code_interpreter";
};
/** 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](/docs/guides/tools-web-search)
or [file search](/docs/guides/tools-file-search). Learn more about
[built-in tools](/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](/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](/docs/guides/function-calling). You can also use
custom tools to call your own code.
*/
export type ToolsArray = Array<Tool>;
/** Emitted when there is an additional text delta. This is also the first event emitted when the transcription starts. Only emitted when you [create a transcription](/docs/api-reference/audio/create-transcription) with the `Stream` parameter set to `true`. */
export type TranscriptTextDeltaEvent = {
"type": "transcript.text.delta";
"delta": string;
"logprobs"?: Array<{
"token"?: string;
"logprob"?: number;
"bytes"?: Array<number>;
}>;
"segment_id"?: string;
};
/** Emitted when the transcription is complete. Contains the complete transcription text. Only emitted when you [create a transcription](/docs/api-reference/audio/create-transcription) with the `Stream` parameter set to `true`. */
export type TranscriptTextDoneEvent = {
"type": "transcript.text.done";
"text": string;
"logprobs"?: Array<{
"token"?: string;
"logprob"?: number;
"bytes"?: Array<number>;
}>;
"usage"?: TranscriptTextUsageTokens;
};
/** Emitted when a diarized transcription returns a completed segment with speaker information. Only emitted when you [create a transcription](/docs/api-reference/audio/create-transcription) with `stream` set to `true` and `response_format` set to `diarized_json`.
*/
export type TranscriptTextSegmentEvent = {
"type": "transcript.text.segment";
"id": string;
"start": number;
"end": number;
"text": string;
"speaker": string;
};
/** Usage statistics for models billed by audio input duration. */
export type TranscriptTextUsageDuration = {
"type": "duration";
"seconds": number;
};
/** Usage statistics for models billed by token usage. */
export type TranscriptTextUsageTokens = {
"type": "tokens";
"input_tokens": number;
"input_token_details"?: {
"text_tokens"?: number;
"audio_tokens"?: number;
};
"output_tokens": number;
"total_tokens": number;
};
/** Controls how the audio is cut into chunks. When set to `"auto"`, the
server first normalizes loudness and then uses voice activity detection (VAD) to
choose boundaries. `server_vad` object can be provided to tweak VAD detection
parameters manually. If unset, the audio is transcribed as a single block. */
export type TranscriptionChunkingStrategy = Record<string, unknown>;
/** A segment of diarized transcript text with speaker metadata. */
export type TranscriptionDiarizedSegment = {
"type": "transcript.text.segment";
"id": string;
"start": number;
"end": number;
"text": string;
"speaker": string;
};
export type TranscriptionInclude = "logprobs";
export type TranscriptionSegment = {
"id": number;
"seek": number;
"start": number;
"end": number;
"text": string;
"tokens": Array<number>;
"temperature": number;
"avg_logprob": number;
"compression_ratio": number;
"no_speech_prob": number;
};
export type TranscriptionWord = {
"word": string;
"start": number;
"end": number;
};
/** Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. */
export type TruncationObject = {
"type": "auto" | "last_messages";
"last_messages"?: Record<string, unknown>;
};
/** Request payload for updating the details of an existing group. */
export type UpdateGroupBody = {
"name": string;
};
export type UpdateVectorStoreFileAttributesRequest = {
"attributes": VectorStoreFileAttributes;
};
export type UpdateVectorStoreRequest = {
"name"?: string;
"expires_after"?: Record<string, unknown>;
"metadata"?: Metadata;
};
export type UpdateVoiceConsentRequest = {
"name": string;
};
/** The Upload object can accept byte chunks in the form of Parts.
*/
export type Upload = {
"id": string;
"created_at": number;
"filename": string;
"bytes": number;
"purpose": string;
"status": "pending" | "completed" | "cancelled" | "expired";
"expires_at": number;
"object"?: "upload";
"file"?: Record<string, unknown>;
};
export type UploadCertificateRequest = {
"name"?: string;
"certificate": string;
};
/** The upload Part represents a chunk of bytes we can add to an Upload object.
*/
export type UploadPart = {
"id": string;
"created_at": number;
"upload_id": string;
"object": "upload.part";
};
/** The aggregated audio speeches usage details of the specific time bucket. */
export type UsageAudioSpeechesResult = {
"object": "organization.usage.audio_speeches.result";
"characters": number;
"num_model_requests": number;
"project_id"?: Record<string, unknown>;
"user_id"?: Record<string, unknown>;
"api_key_id"?: Record<string, unknown>;
"model"?: Record<string, unknown>;
};
/** The aggregated audio transcriptions usage details of the specific time bucket. */
export type UsageAudioTranscriptionsResult = {
"object": "organization.usage.audio_transcriptions.result";
"seconds": number;
"num_model_requests": number;
"project_id"?: Record<string, unknown>;
"user_id"?: Record<string, unknown>;
"api_key_id"?: Record<string, unknown>;
"model"?: Record<string, unknown>;
};
/** The aggregated code interpreter sessions usage details of the specific time bucket. */
export type UsageCodeInterpreterSessionsResult = {
"object": "organization.usage.code_interpreter_sessions.result";
"num_sessions": number;
"project_id"?: Record<string, unknown>;
};
/** The aggregated completions usage details of the specific time bucket. */
export type UsageCompletionsResult = {
"object": "organization.usage.completions.result";
"input_tokens": number;
"input_cached_tokens"?: number;
"output_tokens": number;
"input_audio_tokens"?: number;
"output_audio_tokens"?: number;
"num_model_requests": number;
"project_id"?: Record<string, unknown>;
"user_id"?: Record<string, unknown>;
"api_key_id"?: Record<string, unknown>;
"model"?: Record<string, unknown>;
"batch"?: Record<string, unknown>;
"service_tier"?: Record<string, unknown>;
};
/** The aggregated embeddings usage details of the specific time bucket. */
export type UsageEmbeddingsResult = {
"object": "organization.usage.embeddings.result";
"input_tokens": number;
"num_model_requests": number;
"project_id"?: Record<string, unknown>;
"user_id"?: Record<string, unknown>;
"api_key_id"?: Record<string, unknown>;
"model"?: Record<string, unknown>;
};
/** The aggregated images usage details of the specific time bucket. */
export type UsageImagesResult = {
"object": "organization.usage.images.result";
"images": number;
"num_model_requests": number;
"source"?: Record<string, unknown>;
"size"?: Record<string, unknown>;
"project_id"?: Record<string, unknown>;
"user_id"?: Record<string, unknown>;
"api_key_id"?: Record<string, unknown>;
"model"?: Record<string, unknown>;
};
/** The aggregated moderations usage details of the specific time bucket. */
export type UsageModerationsResult = {
"object": "organization.usage.moderations.result";
"input_tokens": number;
"num_model_requests": number;
"project_id"?: Record<string, unknown>;
"user_id"?: Record<string, unknown>;
"api_key_id"?: Record<string, unknown>;
"model"?: Record<string, unknown>;
};
export type UsageResponse = {
"object": "page";
"data": Array<UsageTimeBucket>;
"has_more": boolean;
"next_page": Record<string, unknown>;
};
export type UsageTimeBucket = {
"object": "bucket";
"start_time": number;
"end_time": number;
"results": Array<Record<string, unknown>>;
};
/** The aggregated vector stores usage details of the specific time bucket. */
export type UsageVectorStoresResult = {
"object": "organization.usage.vector_stores.result";
"usage_bytes": number;
"project_id"?: Record<string, unknown>;
};
/** Represents an individual `user` within an organization. */
export type User = {
"object": "organization.user";
"id": string;
"name"?: Record<string, unknown>;
"email"?: Record<string, unknown>;
"role"?: Record<string, unknown>;
"added_at": number;
"is_default"?: boolean;
"created"?: number;
"user"?: {
"object": "user";
"id": string;
"email"?: Record<string, unknown>;
"name"?: Record<string, unknown>;
"picture"?: Record<string, unknown>;
"enabled"?: Record<string, unknown>;
"banned"?: Record<string, unknown>;
"banned_at"?: Record<string, unknown>;
};
"is_service_account"?: boolean;
"is_scale_tier_authorized_purchaser"?: Record<string, unknown>;
"is_scim_managed"?: boolean;
"api_key_last_used_at"?: Record<string, unknown>;
"technical_level"?: Record<string, unknown>;
"developer_persona"?: Record<string, unknown>;
"projects"?: Record<string, unknown>;
};
export type UserDeleteResponse = {
"object": "organization.user.deleted";
"id": string;
"deleted": boolean;
};
/** Paginated list of user objects returned when inspecting group membership. */
export type UserListResource = {
"object": "list";
"data": Array<GroupUser>;
"has_more": boolean;
"next": Record<string, unknown>;
};
export type UserListResponse = {
"object": "list";
"data": Array<User>;
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
"has_more": boolean;
};
/** Role assignment linking a user to a role. */
export type UserRoleAssignment = {
"object": "user.role";
"user": User;
"role": Role;
};
export type UserRoleUpdateRequest = {
"role"?: Record<string, unknown>;
"role_id"?: Record<string, unknown>;
"technical_level"?: Record<string, unknown>;
"developer_persona"?: Record<string, unknown>;
};
export type VadConfig = {
"type": "server_vad";
"prefix_padding_ms"?: number;
"silence_duration_ms"?: number;
"threshold"?: number;
};
export type ValidateGraderRequest = {
"grader": Record<string, unknown>;
};
export type ValidateGraderResponse = {
"grader"?: Record<string, unknown>;
};
/** The expiration policy for a vector store. */
export type VectorStoreExpirationAfter = {
"anchor": "last_active_at";
"days": number;
};
export type VectorStoreFileAttributes = Record<string, unknown>;
/** A batch of files attached to a vector store. */
export type VectorStoreFileBatchObject = {
"id": string;
"object": "vector_store.files_batch";
"created_at": number;
"vector_store_id": string;
"status": "in_progress" | "completed" | "cancelled" | "failed";
"file_counts": {
"in_progress": number;
"completed": number;
"failed": number;
"cancelled": number;
"total": number;
};
};
/** Represents the parsed content of a vector store file. */
export type VectorStoreFileContentResponse = {
"object": "vector_store.file_content.page";
"data": Array<{
"type"?: string;
"text"?: string;
}>;
"has_more": boolean;
"next_page": Record<string, unknown>;
};
/** A list of files attached to a vector store. */
export type VectorStoreFileObject = {
"id": string;
"object": "vector_store.file";
"usage_bytes": number;
"created_at": number;
"vector_store_id": string;
"status": "in_progress" | "completed" | "cancelled" | "failed";
"last_error": Record<string, unknown>;
"chunking_strategy"?: Record<string, unknown>;
"attributes"?: VectorStoreFileAttributes;
};
/** A vector store is a collection of processed files can be used by the `file_search` tool. */
export type VectorStoreObject = {
"id": string;
"object": "vector_store";
"created_at": number;
"name": string;
"usage_bytes": number;
"file_counts": {
"in_progress": number;
"completed": number;
"failed": number;
"cancelled": number;
"total": number;
};
"status": "expired" | "in_progress" | "completed";
"expires_after"?: VectorStoreExpirationAfter;
"expires_at"?: Record<string, unknown>;
"last_active_at": Record<string, unknown>;
"metadata": Metadata;
};
export type VectorStoreSearchRequest = {
"query": Record<string, unknown>;
"rewrite_query"?: boolean;
"max_num_results"?: number;
"filters"?: Record<string, unknown>;
"ranking_options"?: {
"ranker"?: "none" | "auto" | "default-2024-11-15";
"score_threshold"?: number;
};
};
export type VectorStoreSearchResultContentObject = {
"type": "text";
"text": string;
};
export type VectorStoreSearchResultItem = {
"file_id": string;
"filename": string;
"score": number;
"attributes": VectorStoreFileAttributes;
"content": Array<VectorStoreSearchResultContentObject>;
};
export type VectorStoreSearchResultsPage = {
"object": "vector_store.search_results.page";
"search_query": Array<string>;
"data": Array<VectorStoreSearchResultItem>;
"has_more": boolean;
"next_page": Record<string, unknown>;
};
export type Verbosity = Record<string, unknown>;
export type VoiceConsentDeletedResource = {
"id": string;
"object": "audio.voice_consent";
"deleted": boolean;
};
export type VoiceConsentListResource = {
"object": "list";
"data": Array<VoiceConsentResource>;
"first_id"?: Record<string, unknown>;
"last_id"?: Record<string, unknown>;
"has_more": boolean;
};
/** A consent recording used to authorize creation of a custom voice. */
export type VoiceConsentResource = {
"object": "audio.voice_consent";
"id": string;
"name": string;
"language": string;
"created_at": number;
};
/** A built-in voice name or a custom voice reference.
*/
export type VoiceIdsOrCustomVoice = Record<string, unknown>;
export type VoiceIdsShared = Record<string, unknown>;
/** A custom voice that can be used for audio output. */
export type VoiceResource = {
"object": "audio.voice";
"id": string;
"name": string;
"created_at": number;
};
/** Action type "find_in_page": Searches for a pattern within a loaded page.
*/
export type WebSearchActionFind = {
"type": "find_in_page";
"url": string;
"pattern": string;
};
/** Action type "open_page" - Opens a specific URL from search results.
*/
export type WebSearchActionOpenPage = {
"type": "open_page";
"url"?: Record<string, unknown>;
};
/** Action type "search" - Performs a web search query.
*/
export type WebSearchActionSearch = {
"type": "search";
"query": string;
"queries"?: Array<string>;
"sources"?: Array<{
"type": "url";
"url": string;
}>;
};
export type WebSearchApproximateLocation = Record<string, unknown>;
/** High level guidance for the amount of context window space to use for the
search. One of `low`, `medium`, or `high`. `medium` is the default.
*/
export type WebSearchContextSize = "low" | "medium" | "high";
/** Approximate location parameters for the search. */
export type WebSearchLocation = {
"country"?: string;
"region"?: string;
"city"?: string;
"timezone"?: string;
};
/** Search the Internet for sources related to the prompt. Learn more about the
[web search tool](/docs/guides/tools-web-search).
*/
export type WebSearchTool = {
"type": "web_search" | "web_search_2025_08_26";
"filters"?: Record<string, unknown>;
"user_location"?: WebSearchApproximateLocation;
"search_context_size"?: "low" | "medium" | "high";
};
/** The results of a web search tool call. See the
[web search guide](/docs/guides/tools-web-search) for more information.
*/
export type WebSearchToolCall = {
"id": string;
"type": "web_search_call";
"status": "in_progress" | "searching" | "completed" | "failed";
"action": Record<string, unknown>;
};
/** Sent when a batch API request has been cancelled.
*/
export type WebhookBatchCancelled = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "batch.cancelled";
};
/** Sent when a batch API request has been completed.
*/
export type WebhookBatchCompleted = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "batch.completed";
};
/** Sent when a batch API request has expired.
*/
export type WebhookBatchExpired = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "batch.expired";
};
/** Sent when a batch API request has failed.
*/
export type WebhookBatchFailed = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "batch.failed";
};
/** Sent when an eval run has been canceled.
*/
export type WebhookEvalRunCanceled = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "eval.run.canceled";
};
/** Sent when an eval run has failed.
*/
export type WebhookEvalRunFailed = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "eval.run.failed";
};
/** Sent when an eval run has succeeded.
*/
export type WebhookEvalRunSucceeded = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "eval.run.succeeded";
};
/** Sent when a fine-tuning job has been cancelled.
*/
export type WebhookFineTuningJobCancelled = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "fine_tuning.job.cancelled";
};
/** Sent when a fine-tuning job has failed.
*/
export type WebhookFineTuningJobFailed = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "fine_tuning.job.failed";
};
/** Sent when a fine-tuning job has succeeded.
*/
export type WebhookFineTuningJobSucceeded = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "fine_tuning.job.succeeded";
};
/** Sent when Realtime API Receives a incoming SIP call.
*/
export type WebhookRealtimeCallIncoming = {
"created_at": number;
"id": string;
"data": {
"call_id": string;
"sip_headers": Array<{
"name": string;
"value": string;
}>;
};
"object"?: "event";
"type": "realtime.call.incoming";
};
/** Sent when a background response has been cancelled.
*/
export type WebhookResponseCancelled = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "response.cancelled";
};
/** Sent when a background response has been completed.
*/
export type WebhookResponseCompleted = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "response.completed";
};
/** Sent when a background response has failed.
*/
export type WebhookResponseFailed = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "response.failed";
};
/** Sent when a background response has been interrupted.
*/
export type WebhookResponseIncomplete = {
"created_at": number;
"id": string;
"data": {
"id": string;
};
"object"?: "event";
"type": "response.incomplete";
};
export type SkillReferenceParam = {
"type": "skill_reference";
"skill_id": string;
"version"?: string;
};
/** Inline skill payload */
export type InlineSkillSourceParam = {
"type": "base64";
"media_type": "application/zip";
"data": string;
};
export type InlineSkillParam = {
"type": "inline";
"name": string;
"description": string;
"source": InlineSkillSourceParam;
};
export type ContainerNetworkPolicyDisabledParam = {
"type": "disabled";
};
export type ContainerNetworkPolicyDomainSecretParam = {
"domain": string;
"name": string;
"value": string;
};
export type ContainerNetworkPolicyAllowlistParam = {
"type": "allowlist";
"allowed_domains": Array<string>;
"domain_secrets"?: Array<ContainerNetworkPolicyDomainSecretParam>;
};
/** Specify additional output data to include in the model response. Currently supported values are:
- `web_search_call.results`: Include the search results of the web search tool call.
- `web_search_call.action.sources`: Include the sources of the web search tool call.
- `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items.
- `computer_call_output.output.image_url`: Include image urls from the computer call output.
- `file_search_call.results`: Include the search results of the file search tool call.
- `message.input_image.image_url`: Include image urls from the input message.
- `message.output_text.logprobs`: Include logprobs with assistant messages.
- `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). */
export type IncludeEnum = "file_search_call.results" | "web_search_call.results" | "web_search_call.action.sources" | "message.input_image.image_url" | "computer_call_output.output.image_url" | "code_interpreter_call.outputs" | "reasoning.encrypted_content" | "message.output_text.logprobs";
export type MessageStatus = "in_progress" | "completed" | "incomplete";
export type MessageRole = "unknown" | "user" | "assistant" | "system" | "critic" | "discriminator" | "developer" | "tool";
/** A text input to the model. */
export type InputTextContent = {
"type": "input_text";
"text": string;
};
/** A citation to a file. */
export type FileCitationBody = {
"type": "file_citation";
"file_id": string;
"index": number;
"filename": string;
};
/** A citation for a web resource used to generate a model response. */
export type UrlCitationBody = {
"type": "url_citation";
"url": string;
"start_index": number;
"end_index": number;
"title": string;
};
/** A citation for a container file used to generate a model response. */
export type ContainerFileCitationBody = {
"type": "container_file_citation";
"container_id": string;
"file_id": string;
"start_index": number;
"end_index": number;
"filename": string;
};
/** An annotation that applies to a span of output text. */
export type Annotation = Record<string, unknown>;
/** The top log probability of a token. */
export type TopLogProb = {
"token": string;
"logprob": number;
"bytes": Array<number>;
};
/** The log probability of a token. */
export type LogProb = {
"token": string;
"logprob": number;
"bytes": Array<number>;
"top_logprobs": Array<TopLogProb>;
};
/** A text output from the model. */
export type OutputTextContent = {
"type": "output_text";
"text": string;
"annotations": Array<Annotation>;
"logprobs": Array<LogProb>;
};
/** A text content. */
export type TextContent = {
"type": "text";
"text": string;
};
/** A summary text from the model. */
export type SummaryTextContent = {
"type": "summary_text";
"text": string;
};
/** Reasoning text from the model. */
export type ReasoningTextContent = {
"type": "reasoning_text";
"text": string;
};
/** A refusal from the model. */
export type RefusalContent = {
"type": "refusal";
"refusal": string;
};
export type ImageDetail = "low" | "high" | "auto" | "original";
/** An image input to the model. Learn about [image inputs](/docs/guides/vision). */
export type InputImageContent = {
"type": "input_image";
"image_url"?: Record<string, unknown>;
"file_id"?: Record<string, unknown>;
"detail": ImageDetail;
};
/** A screenshot of a computer. */
export type ComputerScreenshotContent = {
"type": "computer_screenshot";
"image_url": Record<string, unknown>;
"file_id": Record<string, unknown>;
"detail": ImageDetail;
};
export type FileInputDetail = "low" | "high";
/** A file input to the model. */
export type InputFileContent = {
"type": "input_file";
"file_id"?: Record<string, unknown>;
"filename"?: string;
"file_data"?: string;
"file_url"?: string;
"detail"?: FileInputDetail;
};
export type MessagePhase-2 = "commentary" | "final_answer";
/** A message to or from the model. */
export type Message = {
"type": "message";
"id": string;
"status": MessageStatus;
"role": MessageRole;
"content": Array<Record<string, unknown>>;
"phase"?: Record<string, unknown>;
};
export type FunctionCallStatus = "in_progress" | "completed" | "incomplete";
export type FunctionCallOutputStatusEnum = "in_progress" | "completed" | "incomplete";
export type ClickButtonType = "left" | "right" | "wheel" | "back" | "forward";
/** A click action. */
export type ClickParam = {
"type": "click";
"button": ClickButtonType;
"x": number;
"y": number;
"keys"?: Record<string, unknown>;
};
/** A double click action. */
export type DoubleClickAction = {
"type": "double_click";
"x": number;
"y": number;
"keys": Record<string, unknown>;
};
/** An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`. */
export type CoordParam = {
"x": number;
"y": number;
};
/** A drag action. */
export type DragParam = {
"type": "drag";
"path": Array<CoordParam>;
"keys"?: Record<string, unknown>;
};
/** A collection of keypresses the model would like to perform. */
export type KeyPressAction = {
"type": "keypress";
"keys": Array<string>;
};
/** A mouse move action. */
export type MoveParam = {
"type": "move";
"x": number;
"y": number;
"keys"?: Record<string, unknown>;
};
/** A screenshot action. */
export type ScreenshotParam = {
"type": "screenshot";
};
/** A scroll action. */
export type ScrollParam = {
"type": "scroll";
"x": number;
"y": number;
"scroll_x": number;
"scroll_y": number;
"keys"?: Record<string, unknown>;
};
/** An action to type in text. */
export type TypeParam = {
"type": "type";
"text": string;
};
/** A wait action. */
export type WaitParam = {
"type": "wait";
};
/** A pending safety check for the computer call. */
export type ComputerCallSafetyCheckParam = {
"id": string;
"code"?: Record<string, unknown>;
"message"?: Record<string, unknown>;
};
export type ComputerCallOutputStatus = "completed" | "incomplete" | "failed";
export type ToolSearchExecutionType = "server" | "client";
export type ToolSearchCall = {
"type": "tool_search_call";
"id": string;
"call_id": Record<string, unknown>;
"execution": ToolSearchExecutionType;
"arguments": Record<string, unknown>;
"status": FunctionCallStatus;
"created_by"?: string;
};
/** 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 type FunctionTool = {
"type": "function";
"name": string;
"description"?: Record<string, unknown>;
"parameters": Record<string, unknown>;
"strict": Record<string, unknown>;
"defer_loading"?: boolean;
};
export type RankerVersionType = "auto" | "default-2024-11-15";
export type HybridSearchOptions = {
"embedding_weight": number;
"text_weight": number;
};
export type RankingOptions = {
"ranker"?: RankerVersionType;
"score_threshold"?: number;
"hybrid_search"?: HybridSearchOptions;
};
export type Filters = Record<string, unknown>;
/** 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 type FileSearchTool = {
"type": "file_search";
"vector_store_ids": Array<string>;
"max_num_results"?: number;
"ranking_options"?: RankingOptions;
"filters"?: Record<string, unknown>;
};
/** A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). */
export type ComputerTool = {
"type": "computer";
};
export type ComputerEnvironment = "windows" | "mac" | "linux" | "ubuntu" | "browser";
/** A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). */
export type ComputerUsePreviewTool = {
"type": "computer_use_preview";
"environment": ComputerEnvironment;
"display_width": number;
"display_height": number;
};
export type ContainerMemoryLimit = "1g" | "4g" | "16g" | "64g";
/** Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. */
export type AutoCodeInterpreterToolParam = {
"type": "auto";
"file_ids"?: Array<string>;
"memory_limit"?: Record<string, unknown>;
"network_policy"?: Record<string, unknown>;
};
/** Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. */
export type InputFidelity = "high" | "low";
export type ImageGenActionEnum = "generate" | "edit" | "auto";
/** A tool that allows the model to execute shell commands in a local environment. */
export type LocalShellToolParam = {
"type": "local_shell";
};
export type ContainerAutoParam = {
"type": "container_auto";
"file_ids"?: Array<string>;
"memory_limit"?: Record<string, unknown>;
"network_policy"?: Record<string, unknown>;
"skills"?: Array<Record<string, unknown>>;
};
export type LocalSkillParam = {
"name": string;
"description": string;
"path": string;
};
export type LocalEnvironmentParam = {
"type": "local";
"skills"?: Array<LocalSkillParam>;
};
export type ContainerReferenceParam = {
"type": "container_reference";
"container_id": string;
};
/** A tool that allows the model to execute shell commands. */
export type FunctionShellToolParam = {
"type": "shell";
"environment"?: Record<string, unknown>;
};
/** Unconstrained free-form text. */
export type CustomTextFormatParam = {
"type": "text";
};
export type GrammarSyntax1 = "lark" | "regex";
/** A grammar defined by the user. */
export type CustomGrammarFormatParam = {
"type": "grammar";
"syntax": GrammarSyntax1;
"definition": string;
};
/** A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) */
export type CustomToolParam = {
"type": "custom";
"name": string;
"description"?: string;
"format"?: Record<string, unknown>;
"defer_loading"?: boolean;
};
export type EmptyModelParam = {
};
export type FunctionToolParam = {
"name": string;
"description"?: Record<string, unknown>;
"parameters"?: Record<string, unknown>;
"strict"?: Record<string, unknown>;
"type": "function";
"defer_loading"?: boolean;
};
/** Groups function/custom tools under a shared namespace. */
export type NamespaceToolParam = {
"type": "namespace";
"name": string;
"description": string;
"tools": Array<Record<string, unknown>>;
};
/** Hosted or BYOT tool search configuration for deferred tools. */
export type ToolSearchToolParam = {
"type": "tool_search";
"execution"?: ToolSearchExecutionType;
"description"?: Record<string, unknown>;
"parameters"?: Record<string, unknown>;
};
export type ApproximateLocation = {
"type": "approximate";
"country"?: Record<string, unknown>;
"region"?: Record<string, unknown>;
"city"?: Record<string, unknown>;
"timezone"?: Record<string, unknown>;
};
export type SearchContextSize = "low" | "medium" | "high";
export type SearchContentType = "text" | "image";
/** This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). */
export type WebSearchPreviewTool = {
"type": "web_search_preview" | "web_search_preview_2025_03_11";
"user_location"?: Record<string, unknown>;
"search_context_size"?: SearchContextSize;
"search_content_types"?: Array<SearchContentType>;
};
/** Allows the assistant to create, delete, or update files using unified diffs. */
export type ApplyPatchToolParam = {
"type": "apply_patch";
};
export type ToolSearchOutput = {
"type": "tool_search_output";
"id": string;
"call_id": Record<string, unknown>;
"execution": ToolSearchExecutionType;
"tools": Array<Tool>;
"status": FunctionCallOutputStatusEnum;
"created_by"?: string;
};
/** A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). */
export type CompactionBody = {
"type": "compaction";
"id": string;
"encrypted_content": string;
"created_by"?: string;
};
/** The logs output from the code interpreter. */
export type CodeInterpreterOutputLogs = {
"type": "logs";
"logs": string;
};
/** The image output from the code interpreter. */
export type CodeInterpreterOutputImage = {
"type": "image";
"url": string;
};
/** Execute a shell command on the server. */
export type LocalShellExecAction = {
"type": "exec";
"command": Array<string>;
"timeout_ms"?: Record<string, unknown>;
"working_directory"?: Record<string, unknown>;
"env": Record<string, string>;
"user"?: Record<string, unknown>;
};
/** Execute a shell command. */
export type FunctionShellAction = {
"commands": Array<string>;
"timeout_ms": Record<string, unknown>;
"max_output_length": Record<string, unknown>;
};
export type FunctionShellCallStatus = "in_progress" | "completed" | "incomplete";
/** Represents the use of a local environment to perform shell actions. */
export type LocalEnvironmentResource = {
"type": "local";
};
/** Represents a container created with /v1/containers. */
export type ContainerReferenceResource = {
"type": "container_reference";
"container_id": string;
};
/** A tool call that executes one or more shell commands in a managed environment. */
export type FunctionShellCall = {
"type": "shell_call";
"id": string;
"call_id": string;
"action": FunctionShellAction;
"status": FunctionShellCallStatus;
"environment": Record<string, unknown>;
"created_by"?: string;
};
export type FunctionShellCallOutputStatusEnum = "in_progress" | "completed" | "incomplete";
/** Indicates that the shell call exceeded its configured time limit. */
export type FunctionShellCallOutputTimeoutOutcome = {
"type": "timeout";
};
/** Indicates that the shell commands finished and returned an exit code. */
export type FunctionShellCallOutputExitOutcome = {
"type": "exit";
"exit_code": number;
};
/** The content of a shell tool call output that was emitted. */
export type FunctionShellCallOutputContent = {
"stdout": string;
"stderr": string;
"outcome": Record<string, unknown>;
"created_by"?: string;
};
/** The output of a shell tool call that was emitted. */
export type FunctionShellCallOutput = {
"type": "shell_call_output";
"id": string;
"call_id": string;
"status": FunctionShellCallOutputStatusEnum;
"output": Array<FunctionShellCallOutputContent>;
"max_output_length": Record<string, unknown>;
"created_by"?: string;
};
export type ApplyPatchCallStatus = "in_progress" | "completed";
/** Instruction describing how to create a file via the apply_patch tool. */
export type ApplyPatchCreateFileOperation = {
"type": "create_file";
"path": string;
"diff": string;
};
/** Instruction describing how to delete a file via the apply_patch tool. */
export type ApplyPatchDeleteFileOperation = {
"type": "delete_file";
"path": string;
};
/** Instruction describing how to update a file via the apply_patch tool. */
export type ApplyPatchUpdateFileOperation = {
"type": "update_file";
"path": string;
"diff": string;
};
/** A tool call that applies file diffs by creating, deleting, or updating files. */
export type ApplyPatchToolCall = {
"type": "apply_patch_call";
"id": string;
"call_id": string;
"status": ApplyPatchCallStatus;
"operation": Record<string, unknown>;
"created_by"?: string;
};
export type ApplyPatchCallOutputStatus = "completed" | "failed";
/** The output emitted by an apply patch tool call. */
export type ApplyPatchToolCallOutput = {
"type": "apply_patch_call_output";
"id": string;
"call_id": string;
"status": ApplyPatchCallOutputStatus;
"output"?: Record<string, unknown>;
"created_by"?: string;
};
export type MCPToolCallStatus = "in_progress" | "completed" | "incomplete" | "calling" | "failed";
export type DetailEnum = "low" | "high" | "auto" | "original";
export type FunctionCallItemStatus = "in_progress" | "completed" | "incomplete";
/** The output of a computer tool call. */
export type ComputerCallOutputItemParam = {
"id"?: Record<string, unknown>;
"call_id": string;
"type": "computer_call_output";
"output": ComputerScreenshotImage;
"acknowledged_safety_checks"?: Record<string, unknown>;
"status"?: Record<string, unknown>;
};
/** A text input to the model. */
export type InputTextContentParam = {
"type": "input_text";
"text": string;
};
/** An image input to the model. Learn about [image inputs](/docs/guides/vision) */
export type InputImageContentParamAutoParam = {
"type": "input_image";
"image_url"?: Record<string, unknown>;
"file_id"?: Record<string, unknown>;
"detail"?: Record<string, unknown>;
};
export type FileDetailEnum = "low" | "high";
/** A file input to the model. */
export type InputFileContentParam = {
"type": "input_file";
"file_id"?: Record<string, unknown>;
"filename"?: Record<string, unknown>;
"file_data"?: Record<string, unknown>;
"file_url"?: Record<string, unknown>;
"detail"?: FileDetailEnum;
};
/** The output of a function tool call. */
export type FunctionCallOutputItemParam = {
"id"?: Record<string, unknown>;
"call_id": string;
"type": "function_call_output";
"output": Record<string, unknown>;
"status"?: Record<string, unknown>;
};
export type ToolSearchCallItemParam = {
"id"?: Record<string, unknown>;
"call_id"?: Record<string, unknown>;
"type": "tool_search_call";
"execution"?: ToolSearchExecutionType;
"arguments": EmptyModelParam;
"status"?: Record<string, unknown>;
};
export type ToolSearchOutputItemParam = {
"id"?: Record<string, unknown>;
"call_id"?: Record<string, unknown>;
"type": "tool_search_output";
"execution"?: ToolSearchExecutionType;
"tools": Array<Tool>;
"status"?: Record<string, unknown>;
};
/** A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). */
export type CompactionSummaryItemParam = {
"id"?: Record<string, unknown>;
"type": "compaction";
"encrypted_content": string;
};
/** Commands and limits describing how to run the shell tool call. */
export type FunctionShellActionParam = {
"commands": Array<string>;
"timeout_ms"?: Record<string, unknown>;
"max_output_length"?: Record<string, unknown>;
};
/** Status values reported for shell tool calls. */
export type FunctionShellCallItemStatus = "in_progress" | "completed" | "incomplete";
/** A tool representing a request to execute one or more shell commands. */
export type FunctionShellCallItemParam = {
"id"?: Record<string, unknown>;
"call_id": string;
"type": "shell_call";
"action": FunctionShellActionParam;
"status"?: Record<string, unknown>;
"environment"?: Record<string, unknown>;
};
/** Indicates that the shell call exceeded its configured time limit. */
export type FunctionShellCallOutputTimeoutOutcomeParam = {
"type": "timeout";
};
/** Indicates that the shell commands finished and returned an exit code. */
export type FunctionShellCallOutputExitOutcomeParam = {
"type": "exit";
"exit_code": number;
};
/** The exit or timeout outcome associated with this shell call. */
export type FunctionShellCallOutputOutcomeParam = Record<string, unknown>;
/** Captured stdout and stderr for a portion of a shell tool call output. */
export type FunctionShellCallOutputContentParam = {
"stdout": string;
"stderr": string;
"outcome": FunctionShellCallOutputOutcomeParam;
};
/** The streamed output items emitted by a shell tool call. */
export type FunctionShellCallOutputItemParam = {
"id"?: Record<string, unknown>;
"call_id": string;
"type": "shell_call_output";
"output": Array<FunctionShellCallOutputContentParam>;
"status"?: Record<string, unknown>;
"max_output_length"?: Record<string, unknown>;
};
/** Status values reported for apply_patch tool calls. */
export type ApplyPatchCallStatusParam = "in_progress" | "completed";
/** Instruction for creating a new file via the apply_patch tool. */
export type ApplyPatchCreateFileOperationParam = {
"type": "create_file";
"path": string;
"diff": string;
};
/** Instruction for deleting an existing file via the apply_patch tool. */
export type ApplyPatchDeleteFileOperationParam = {
"type": "delete_file";
"path": string;
};
/** Instruction for updating an existing file via the apply_patch tool. */
export type ApplyPatchUpdateFileOperationParam = {
"type": "update_file";
"path": string;
"diff": string;
};
/** One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool. */
export type ApplyPatchOperationParam = Record<string, unknown>;
/** A tool call representing a request to create, delete, or update files using diff patches. */
export type ApplyPatchToolCallItemParam = {
"type": "apply_patch_call";
"id"?: Record<string, unknown>;
"call_id": string;
"status": ApplyPatchCallStatusParam;
"operation": ApplyPatchOperationParam;
};
/** Outcome values reported for apply_patch tool call outputs. */
export type ApplyPatchCallOutputStatusParam = "completed" | "failed";
/** The streamed output emitted by an apply patch tool call. */
export type ApplyPatchToolCallOutputItemParam = {
"type": "apply_patch_call_output";
"id"?: Record<string, unknown>;
"call_id": string;
"status": ApplyPatchCallOutputStatusParam;
"output"?: Record<string, unknown>;
};
/** An internal identifier for an item to reference. */
export type ItemReferenceParam = {
"type"?: Record<string, unknown>;
"id": string;
};
export type ConversationResource = {
"id": string;
"object": "conversation";
"metadata": Record<string, unknown>;
"created_at": number;
};
/** The output token details for the image generation. */
export type ImageGenOutputTokensDetails = {
"image_tokens": number;
"text_tokens": number;
};
/** The input tokens detailed information for the image generation. */
export type ImageGenInputUsageDetails = {
"text_tokens": number;
"image_tokens": number;
};
/** For `gpt-image-1` only, the token usage information for the image generation. */
export type ImageGenUsage = {
"input_tokens": number;
"total_tokens": number;
"output_tokens": number;
"output_tokens_details"?: ImageGenOutputTokensDetails;
"input_tokens_details": ImageGenInputUsageDetails;
};
/** Forces the model to call the apply_patch tool when executing a tool call. */
export type SpecificApplyPatchParam = {
"type": "apply_patch";
};
/** Forces the model to call the shell tool when a tool call is required. */
export type SpecificFunctionShellParam = {
"type": "shell";
};
/** The conversation that this response belongs to. */
export type ConversationParam-2 = {
"id": string;
};
export type ContextManagementParam = {
"type": string;
"compact_threshold"?: Record<string, unknown>;
};
/** The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. */
export type Conversation-2 = {
"id": string;
};
export type CreateConversationBody = {
"metadata"?: Record<string, unknown>;
"items"?: Record<string, unknown>;
};
export type UpdateConversationBody = {
"metadata": Metadata;
};
export type DeletedConversationResource = {
"object": "conversation.deleted";
"deleted": boolean;
"id": string;
};
export type OrderEnum = "asc" | "desc";
export type VideoModel = Record<string, unknown>;
export type VideoStatus = "queued" | "in_progress" | "completed" | "failed";
export type VideoSize = "720x1280" | "1280x720" | "1024x1792" | "1792x1024";
/** An error that occurred while generating the response. */
export type Error-2 = {
"code": string;
"message": string;
};
/** Structured information describing a generated video job. */
export type VideoResource = {
"id": string;
"object": "video";
"model": VideoModel;
"status": VideoStatus;
"progress": number;
"created_at": number;
"completed_at": Record<string, unknown>;
"expires_at": Record<string, unknown>;
"prompt": Record<string, unknown>;
"size": VideoSize;
"seconds": string;
"remixed_from_video_id": Record<string, unknown>;
"error": Record<string, unknown>;
};
export type VideoListResource = {
"object": "list";
"data": Array<VideoResource>;
"first_id": Record<string, unknown>;
"last_id": Record<string, unknown>;
"has_more": boolean;
};
export type ImageRefParam-2 = {
"image_url"?: string;
"file_id"?: string;
};
export type VideoSeconds = "4" | "8" | "12";
/** Multipart parameters for creating a new video generation job. */
export type CreateVideoMultipartBody = {
"model"?: VideoModel;
"prompt": string;
"input_reference"?: Record<string, unknown>;
"seconds"?: VideoSeconds;
"size"?: VideoSize;
};
/** JSON parameters for creating a new video generation job. */
export type CreateVideoJsonBody = {
"model"?: VideoModel;
"prompt": string;
"input_reference"?: ImageRefParam-2;
"seconds"?: VideoSeconds;
"size"?: VideoSize;
};
/** Parameters for creating a character from an uploaded video. */
export type CreateVideoCharacterBody = {
"video": string;
"name": string;
};
export type VideoCharacterResource = {
"id": Record<string, unknown>;
"name": Record<string, unknown>;
"created_at": number;
};
/** Reference to the completed video. */
export type VideoReferenceInputParam = {
"id": string;
};
/** Parameters for editing an existing generated video. */
export type CreateVideoEditMultipartBody = {
"video": Record<string, unknown>;
"prompt": string;
};
/** JSON parameters for editing an existing generated video. */
export type CreateVideoEditJsonBody = {
"video": VideoReferenceInputParam;
"prompt": string;
};
/** Multipart parameters for extending an existing generated video. */
export type CreateVideoExtendMultipartBody = {
"video": Record<string, unknown>;
"prompt": string;
"seconds": VideoSeconds;
};
/** JSON parameters for extending an existing generated video. */
export type CreateVideoExtendJsonBody = {
"video": VideoReferenceInputParam;
"prompt": string;
"seconds": VideoSeconds;
};
/** Confirmation payload returned after deleting a video. */
export type DeletedVideoResource = {
"object": "video.deleted";
"deleted": boolean;
"id": string;
};
export type VideoContentVariant = "video" | "thumbnail" | "spritesheet";
/** Parameters for remixing an existing generated video. */
export type CreateVideoRemixBody = {
"prompt": string;
};
export type TruncationEnum = "auto" | "disabled";
export type TokenCountsBody = {
"model"?: Record<string, unknown>;
"input"?: Record<string, unknown>;
"previous_response_id"?: Record<string, unknown>;
"tools"?: Record<string, unknown>;
"text"?: Record<string, unknown>;
"reasoning"?: Record<string, unknown>;
"truncation"?: TruncationEnum;
"instructions"?: Record<string, unknown>;
"conversation"?: Record<string, unknown>;
"tool_choice"?: Record<string, unknown>;
"parallel_tool_calls"?: Record<string, unknown>;
};
export type TokenCountsResource = {
"object": "response.input_tokens";
"input_tokens": number;
};
export type PromptCacheRetentionEnum = "in_memory" | "24h";
export type ServiceTierEnum = "auto" | "default" | "flex" | "priority";
export type CompactResponseMethodPublicBody = {
"model": ModelIdsCompaction;
"input"?: Record<string, unknown>;
"previous_response_id"?: Record<string, unknown>;
"instructions"?: Record<string, unknown>;
"prompt_cache_key"?: Record<string, unknown>;
"prompt_cache_retention"?: Record<string, unknown>;
"service_tier"?: Record<string, unknown>;
};
/** An item representing a message, tool call, tool output, reasoning, or other response element. */
export type ItemField = Record<string, unknown>;
export type CompactResource = {
"id": string;
"object": "response.compaction";
"output": Array<ItemField>;
"created_at": number;
"usage": ResponseUsage;
};
export type SkillResource = {
"id": string;
"object": "skill";
"name": string;
"description": string;
"created_at": number;
"default_version": string;
"latest_version": string;
};
export type SkillListResource = {
"object": "list";
"data": Array<SkillResource>;
"first_id": Record<string, unknown>;
"last_id": Record<string, unknown>;
"has_more": boolean;
};
/** Uploads a skill either as a directory (multipart `files[]`) or as a single zip file. */
export type CreateSkillBody = {
"files": Record<string, unknown>;
};
/** Updates the default version pointer for a skill. */
export type SetDefaultSkillVersionBody = {
"default_version": string;
};
export type DeletedSkillResource = {
"object": "skill.deleted";
"deleted": boolean;
"id": string;
};
export type SkillVersionResource = {
"object": "skill.version";
"id": string;
"skill_id": string;
"version": string;
"created_at": number;
"name": string;
"description": string;
};
export type SkillVersionListResource = {
"object": "list";
"data": Array<SkillVersionResource>;
"first_id": Record<string, unknown>;
"last_id": Record<string, unknown>;
"has_more": boolean;
};
/** Uploads a new immutable version of a skill. */
export type CreateSkillVersionBody = {
"files": Record<string, unknown>;
"default"?: boolean;
};
export type DeletedSkillVersionResource = {
"object": "skill.version.deleted";
"deleted": boolean;
"id": string;
"version": string;
};
/** Controls diagnostic tracing during the session. */
export type ChatkitWorkflowTracing = {
"enabled": boolean;
};
/** Workflow metadata and state returned for the session. */
export type ChatkitWorkflow = {
"id": string;
"version": Record<string, unknown>;
"state_variables": Record<string, unknown>;
"tracing": ChatkitWorkflowTracing;
};
/** Active per-minute request limit for the session. */
export type ChatSessionRateLimits = {
"max_requests_per_1_minute": number;
};
export type ChatSessionStatus = "active" | "expired" | "cancelled";
/** Automatic thread title preferences for the session. */
export type ChatSessionAutomaticThreadTitling = {
"enabled": boolean;
};
/** Upload permissions and limits applied to the session. */
export type ChatSessionFileUpload = {
"enabled": boolean;
"max_file_size": Record<string, unknown>;
"max_files": Record<string, unknown>;
};
/** History retention preferences returned for the session. */
export type ChatSessionHistory = {
"enabled": boolean;
"recent_threads": Record<string, unknown>;
};
/** ChatKit configuration for the session. */
export type ChatSessionChatkitConfiguration = {
"automatic_thread_titling": ChatSessionAutomaticThreadTitling;
"file_upload": ChatSessionFileUpload;
"history": ChatSessionHistory;
};
/** Represents a ChatKit session and its resolved configuration. */
export type ChatSessionResource = {
"id": string;
"object": "chatkit.session";
"expires_at": number;
"client_secret": string;
"workflow": ChatkitWorkflow;
"user": string;
"rate_limits": ChatSessionRateLimits;
"max_requests_per_1_minute": number;
"status": ChatSessionStatus;
"chatkit_configuration": ChatSessionChatkitConfiguration;
};
/** Controls diagnostic tracing during the session. */
export type WorkflowTracingParam = {
"enabled"?: boolean;
};
/** Workflow reference and overrides applied to the chat session. */
export type WorkflowParam = {
"id": string;
"version"?: string;
"state_variables"?: Record<string, Record<string, unknown>>;
"tracing"?: WorkflowTracingParam;
};
/** Controls when the session expires relative to an anchor timestamp. */
export type ExpiresAfterParam = {
"anchor": "created_at";
"seconds": number;
};
/** Controls request rate limits for the session. */
export type RateLimitsParam = {
"max_requests_per_1_minute"?: number;
};
/** Controls whether ChatKit automatically generates thread titles. */
export type AutomaticThreadTitlingParam = {
"enabled"?: boolean;
};
/** Controls whether users can upload files. */
export type FileUploadParam = {
"enabled"?: boolean;
"max_file_size"?: number;
"max_files"?: number;
};
/** Controls how much historical context is retained for the session. */
export type HistoryParam = {
"enabled"?: boolean;
"recent_threads"?: number;
};
/** Optional per-session configuration settings for ChatKit behavior. */
export type ChatkitConfigurationParam = {
"automatic_thread_titling"?: AutomaticThreadTitlingParam;
"file_upload"?: FileUploadParam;
"history"?: HistoryParam;
};
/** Parameters for provisioning a new ChatKit session. */
export type CreateChatSessionBody = {
"workflow": WorkflowParam;
"user": string;
"expires_after"?: ExpiresAfterParam;
"rate_limits"?: RateLimitsParam;
"chatkit_configuration"?: ChatkitConfigurationParam;
};
/** Text block that a user contributed to the thread. */
export type UserMessageInputText = {
"type": "input_text";
"text": string;
};
/** Quoted snippet that the user referenced in their message. */
export type UserMessageQuotedText = {
"type": "quoted_text";
"text": string;
};
export type AttachmentType = "image" | "file";
/** Attachment metadata included on thread items. */
export type Attachment = {
"type": AttachmentType;
"id": string;
"name": string;
"mime_type": string;
"preview_url": Record<string, unknown>;
};
/** Tool selection that the assistant should honor when executing the item. */
export type ToolChoice = {
"id": string;
};
/** Model and tool overrides applied when generating the assistant response. */
export type InferenceOptions = {
"tool_choice": Record<string, unknown>;
"model": Record<string, unknown>;
};
/** User-authored messages within a thread. */
export type UserMessageItem = {
"id": string;
"object": "chatkit.thread_item";
"created_at": number;
"thread_id": string;
"type": "chatkit.user_message";
"content": Array<Record<string, unknown>>;
"attachments": Array<Attachment>;
"inference_options": Record<string, unknown>;
};
/** Attachment source referenced by an annotation. */
export type FileAnnotationSource = {
"type": "file";
"filename": string;
};
/** Annotation that references an uploaded file. */
export type FileAnnotation = {
"type": "file";
"source": FileAnnotationSource;
};
/** URL backing an annotation entry. */
export type UrlAnnotationSource = {
"type": "url";
"url": string;
};
/** Annotation that references a URL. */
export type UrlAnnotation = {
"type": "url";
"source": UrlAnnotationSource;
};
/** Assistant response text accompanied by optional annotations. */
export type ResponseOutputText = {
"type": "output_text";
"text": string;
"annotations": Array<Record<string, unknown>>;
};
/** Assistant-authored message within a thread. */
export type AssistantMessageItem = {
"id": string;
"object": "chatkit.thread_item";
"created_at": number;
"thread_id": string;
"type": "chatkit.assistant_message";
"content": Array<ResponseOutputText>;
};
/** Thread item that renders a widget payload. */
export type WidgetMessageItem = {
"id": string;
"object": "chatkit.thread_item";
"created_at": number;
"thread_id": string;
"type": "chatkit.widget";
"widget": string;
};
export type ClientToolCallStatus = "in_progress" | "completed";
/** Record of a client side tool invocation initiated by the assistant. */
export type ClientToolCallItem = {
"id": string;
"object": "chatkit.thread_item";
"created_at": number;
"thread_id": string;
"type": "chatkit.client_tool_call";
"status": ClientToolCallStatus;
"call_id": string;
"name": string;
"arguments": string;
"output": Record<string, unknown>;
};
export type TaskType = "custom" | "thought";
/** Task emitted by the workflow to show progress and status updates. */
export type TaskItem = {
"id": string;
"object": "chatkit.thread_item";
"created_at": number;
"thread_id": string;
"type": "chatkit.task";
"task_type": TaskType;
"heading": Record<string, unknown>;
"summary": Record<string, unknown>;
};
/** Task entry that appears within a TaskGroup. */
export type TaskGroupTask = {
"type": TaskType;
"heading": Record<string, unknown>;
"summary": Record<string, unknown>;
};
/** Collection of workflow tasks grouped together in the thread. */
export type TaskGroupItem = {
"id": string;
"object": "chatkit.thread_item";
"created_at": number;
"thread_id": string;
"type": "chatkit.task_group";
"tasks": Array<TaskGroupTask>;
};
export type ThreadItem = Record<string, unknown>;
/** A paginated list of thread items rendered for the ChatKit API. */
export type ThreadItemListResource = {
"object": "list";
"data": Array<ThreadItem>;
"first_id": Record<string, unknown>;
"last_id": Record<string, unknown>;
"has_more": boolean;
};
/** Indicates that a thread is active. */
export type ActiveStatus = {
"type": "active";
};
/** Indicates that a thread is locked and cannot accept new input. */
export type LockedStatus = {
"type": "locked";
"reason": Record<string, unknown>;
};
/** Indicates that a thread has been closed. */
export type ClosedStatus = {
"type": "closed";
"reason": Record<string, unknown>;
};
/** Represents a ChatKit thread and its current status. */
export type ThreadResource = {
"id": string;
"object": "chatkit.thread";
"created_at": number;
"title": Record<string, unknown>;
"status": Record<string, unknown>;
"user": string;
};
/** Confirmation payload returned after deleting a thread. */
export type DeletedThreadResource = {
"id": string;
"object": "chatkit.thread.deleted";
"deleted": boolean;
};
/** A paginated list of ChatKit threads. */
export type ThreadListResource = {
"object": "list";
"data": Array<ThreadResource>;
"first_id": Record<string, unknown>;
"last_id": Record<string, unknown>;
"has_more": boolean;
};
/** An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`. */
export type DragPoint = {
"x": number;
"y": number;
};
export type listAssistantsResponse = ListAssistantsResponse;
export type createAssistantBody = CreateAssistantRequest;
export type createAssistantResponse = AssistantObject;
export type getAssistantResponse = AssistantObject;
export type modifyAssistantBody = ModifyAssistantRequest;
export type modifyAssistantResponse = AssistantObject;
export type deleteAssistantResponse = DeleteAssistantResponse;
export type createSpeechBody = CreateSpeechRequest;
export type createSpeechResponse = string;
export type createTranscriptionBody = CreateTranscriptionRequest;
export type createTranscriptionResponse = Record<string, unknown>;
export type createTranslationBody = CreateTranslationRequest;
export type createTranslationResponse = Record<string, unknown>;
export type listVoiceConsentsResponse = VoiceConsentListResource;
export type createVoiceConsentBody = CreateVoiceConsentRequest;
export type createVoiceConsentResponse = VoiceConsentResource;
export type getVoiceConsentResponse = VoiceConsentResource;
export type updateVoiceConsentBody = UpdateVoiceConsentRequest;
export type updateVoiceConsentResponse = VoiceConsentResource;
export type deleteVoiceConsentResponse = VoiceConsentDeletedResource;
export type createVoiceBody = CreateVoiceRequest;
export type createVoiceResponse = VoiceResource;
export type listBatchesResponse = ListBatchesResponse;
export type createBatchBody = {
"input_file_id": string;
"endpoint": "/v1/responses" | "/v1/chat/completions" | "/v1/embeddings" | "/v1/completions" | "/v1/moderations" | "/v1/images/generations" | "/v1/images/edits" | "/v1/videos";
"completion_window": "24h";
"metadata"?: Metadata;
"output_expires_after"?: BatchFileExpirationAfter;
};
export type createBatchResponse = Batch;
export type retrieveBatchResponse = Batch;
export type cancelBatchResponse = Batch;
export type listChatCompletionsResponse = ChatCompletionList;
export type createChatCompletionBody = CreateChatCompletionRequest;
export type createChatCompletionResponse = CreateChatCompletionResponse;
export type getChatCompletionResponse = CreateChatCompletionResponse;
export type updateChatCompletionBody = {
"metadata": Metadata;
};
export type updateChatCompletionResponse = CreateChatCompletionResponse;
export type deleteChatCompletionResponse = ChatCompletionDeleted;
export type getChatCompletionMessagesResponse = ChatCompletionMessageList;
export type createCompletionBody = CreateCompletionRequest;
export type createCompletionResponse = CreateCompletionResponse;
export type ListContainersResponse = ContainerListResource;
export type CreateContainerBody = CreateContainerBody;
export type CreateContainerResponse = ContainerResource;
export type RetrieveContainerResponse = ContainerResource;
export type ListContainerFilesResponse = ContainerFileListResource;
export type CreateContainerFileBody = CreateContainerFileBody;
export type CreateContainerFileResponse = ContainerFileResource;
export type RetrieveContainerFileResponse = ContainerFileResource;
export type listConversationItemsResponse = ConversationItemList;
export type createConversationItemsBody = {
"items": Array<InputItem>;
};
export type createConversationItemsResponse = ConversationItemList;
export type getConversationItemResponse = ConversationItem;
export type deleteConversationItemResponse = ConversationResource;
export type createEmbeddingBody = CreateEmbeddingRequest;
export type createEmbeddingResponse = CreateEmbeddingResponse;
export type listEvalsResponse = EvalList;
export type createEvalBody = CreateEvalRequest;
export type createEvalResponse = Eval;
export type getEvalResponse = Eval;
export type updateEvalBody = {
"name"?: string;
"metadata"?: Metadata;
};
export type updateEvalResponse = Eval;
export type deleteEvalResponse = {
"object": string;
"deleted": boolean;
"eval_id": string;
};
export type getEvalRunsResponse = EvalRunList;
export type createEvalRunBody = CreateEvalRunRequest;
export type createEvalRunResponse = EvalRun;
export type getEvalRunResponse = EvalRun;
export type cancelEvalRunResponse = EvalRun;
export type deleteEvalRunResponse = {
"object"?: string;
"deleted"?: boolean;
"run_id"?: string;
};
export type getEvalRunOutputItemsResponse = EvalRunOutputItemList;
export type getEvalRunOutputItemResponse = EvalRunOutputItem;
export type listFilesResponse = ListFilesResponse;
export type createFileBody = CreateFileRequest;
export type createFileResponse = OpenAIFile;
export type retrieveFileResponse = OpenAIFile;
export type deleteFileResponse = DeleteFileResponse;
export type downloadFileResponse = string;
export type runGraderBody = RunGraderRequest;
export type runGraderResponse = RunGraderResponse;
export type validateGraderBody = ValidateGraderRequest;
export type validateGraderResponse = ValidateGraderResponse;
export type listFineTuningCheckpointPermissionsResponse = ListFineTuningCheckpointPermissionResponse;
export type createFineTuningCheckpointPermissionBody = CreateFineTuningCheckpointPermissionRequest;
export type createFineTuningCheckpointPermissionResponse = ListFineTuningCheckpointPermissionResponse;
export type deleteFineTuningCheckpointPermissionResponse = DeleteFineTuningCheckpointPermissionResponse;
export type listPaginatedFineTuningJobsResponse = ListPaginatedFineTuningJobsResponse;
export type createFineTuningJobBody = CreateFineTuningJobRequest;
export type createFineTuningJobResponse = FineTuningJob;
export type retrieveFineTuningJobResponse = FineTuningJob;
export type cancelFineTuningJobResponse = FineTuningJob;
export type listFineTuningJobCheckpointsResponse = ListFineTuningJobCheckpointsResponse;
export type listFineTuningEventsResponse = ListFineTuningJobEventsResponse;
export type pauseFineTuningJobResponse = FineTuningJob;
export type resumeFineTuningJobResponse = FineTuningJob;
export type createImageEditBody = CreateImageEditRequest;
export type createImageEditResponse = ImagesResponse;
export type createImageBody = CreateImageRequest;
export type createImageResponse = ImagesResponse;
export type createImageVariationBody = CreateImageVariationRequest;
export type createImageVariationResponse = ImagesResponse;
export type listModelsResponse = ListModelsResponse;
export type retrieveModelResponse = Model;
export type deleteModelResponse = DeleteModelResponse;
export type createModerationBody = CreateModerationRequest;
export type createModerationResponse = CreateModerationResponse;
export type admin-api-keys-listResponse = ApiKeyList;
export type admin-api-keys-createBody = {
"name": string;
};
export type admin-api-keys-createResponse = AdminApiKeyCreateResponse;
export type admin-api-keys-getResponse = AdminApiKey;
export type admin-api-keys-deleteResponse = {
"id": string;
"object": "organization.admin_api_key.deleted";
"deleted": boolean;
};
export type list-audit-logsResponse = ListAuditLogsResponse;
export type listOrganizationCertificatesResponse = ListCertificatesResponse;
export type uploadCertificateBody = UploadCertificateRequest;
export type uploadCertificateResponse = Certificate;
export type activateOrganizationCertificatesBody = ToggleCertificatesRequest;
export type activateOrganizationCertificatesResponse = OrganizationCertificateActivationResponse;
export type deactivateOrganizationCertificatesBody = ToggleCertificatesRequest;
export type deactivateOrganizationCertificatesResponse = OrganizationCertificateDeactivationResponse;
export type getCertificateResponse = Certificate;
export type modifyCertificateBody = ModifyCertificateRequest;
export type modifyCertificateResponse = Certificate;
export type deleteCertificateResponse = DeleteCertificateResponse;
export type usage-costsResponse = UsageResponse;
export type list-groupsResponse = GroupListResource;
export type create-groupBody = CreateGroupBody;
export type create-groupResponse = GroupResponse;
export type update-groupBody = UpdateGroupBody;
export type update-groupResponse = GroupResourceWithSuccess;
export type delete-groupResponse = GroupDeletedResource;
export type list-group-role-assignmentsResponse = RoleListResource;
export type assign-group-roleBody = PublicAssignOrganizationGroupRoleBody;
export type assign-group-roleResponse = GroupRoleAssignment;
export type unassign-group-roleResponse = DeletedRoleAssignmentResource;
export type list-group-usersResponse = UserListResource;
export type add-group-userBody = CreateGroupUserBody;
export type add-group-userResponse = GroupUserAssignment;
export type remove-group-userResponse = GroupUserDeletedResource;
export type list-invitesResponse = InviteListResponse;
export type inviteUserBody = InviteRequest;
export type inviteUserResponse = Invite;
export type retrieve-inviteResponse = Invite;
export type delete-inviteResponse = InviteDeleteResponse;
export type list-projectsResponse = ProjectListResponse;
export type create-projectBody = ProjectCreateRequest;
export type create-projectResponse = Project;
export type retrieve-projectResponse = Project;
export type modify-projectBody = ProjectUpdateRequest;
export type modify-projectResponse = Project;
export type list-project-api-keysResponse = ProjectApiKeyListResponse;
export type retrieve-project-api-keyResponse = ProjectApiKey;
export type delete-project-api-keyResponse = ProjectApiKeyDeleteResponse;
export type archive-projectResponse = Project;
export type listProjectCertificatesResponse = ListProjectCertificatesResponse;
export type activateProjectCertificatesBody = ToggleCertificatesRequest;
export type activateProjectCertificatesResponse = OrganizationProjectCertificateActivationResponse;
export type deactivateProjectCertificatesBody = ToggleCertificatesRequest;
export type deactivateProjectCertificatesResponse = OrganizationProjectCertificateDeactivationResponse;
export type list-project-groupsResponse = ProjectGroupListResource;
export type add-project-groupBody = InviteProjectGroupBody;
export type add-project-groupResponse = ProjectGroup;
export type remove-project-groupResponse = ProjectGroupDeletedResource;
export type list-project-rate-limitsResponse = ProjectRateLimitListResponse;
export type update-project-rate-limitsBody = ProjectRateLimitUpdateRequest;
export type update-project-rate-limitsResponse = ProjectRateLimit;
export type list-project-service-accountsResponse = ProjectServiceAccountListResponse;
export type create-project-service-accountBody = ProjectServiceAccountCreateRequest;
export type create-project-service-accountResponse = ProjectServiceAccountCreateResponse;
export type retrieve-project-service-accountResponse = ProjectServiceAccount;
export type delete-project-service-accountResponse = ProjectServiceAccountDeleteResponse;
export type list-project-usersResponse = ProjectUserListResponse;
export type create-project-userBody = ProjectUserCreateRequest;
export type create-project-userResponse = ProjectUser;
export type retrieve-project-userResponse = ProjectUser;
export type modify-project-userBody = ProjectUserUpdateRequest;
export type modify-project-userResponse = ProjectUser;
export type delete-project-userResponse = ProjectUserDeleteResponse;
export type list-rolesResponse = PublicRoleListResource;
export type create-roleBody = PublicCreateOrganizationRoleBody;
export type create-roleResponse = Role;
export type update-roleBody = PublicUpdateOrganizationRoleBody;
export type update-roleResponse = Role;
export type delete-roleResponse = RoleDeletedResource;
export type usage-audio-speechesResponse = UsageResponse;
export type usage-audio-transcriptionsResponse = UsageResponse;
export type usage-code-interpreter-sessionsResponse = UsageResponse;
export type usage-completionsResponse = UsageResponse;
export type usage-embeddingsResponse = UsageResponse;
export type usage-imagesResponse = UsageResponse;
export type usage-moderationsResponse = UsageResponse;
export type usage-vector-storesResponse = UsageResponse;
export type list-usersResponse = UserListResponse;
export type retrieve-userResponse = User;
export type modify-userBody = UserRoleUpdateRequest;
export type modify-userResponse = User;
export type delete-userResponse = UserDeleteResponse;
export type list-user-role-assignmentsResponse = RoleListResource;
export type assign-user-roleBody = PublicAssignOrganizationGroupRoleBody;
export type assign-user-roleResponse = UserRoleAssignment;
export type unassign-user-roleResponse = DeletedRoleAssignmentResource;
export type list-project-group-role-assignmentsResponse = RoleListResource;
export type assign-project-group-roleBody = PublicAssignOrganizationGroupRoleBody;
export type assign-project-group-roleResponse = GroupRoleAssignment;
export type unassign-project-group-roleResponse = DeletedRoleAssignmentResource;
export type list-project-rolesResponse = PublicRoleListResource;
export type create-project-roleBody = PublicCreateOrganizationRoleBody;
export type create-project-roleResponse = Role;
export type update-project-roleBody = PublicUpdateOrganizationRoleBody;
export type update-project-roleResponse = Role;
export type delete-project-roleResponse = RoleDeletedResource;
export type list-project-user-role-assignmentsResponse = RoleListResource;
export type assign-project-user-roleBody = PublicAssignOrganizationGroupRoleBody;
export type assign-project-user-roleResponse = UserRoleAssignment;
export type unassign-project-user-roleResponse = DeletedRoleAssignmentResource;
export type create-realtime-callBody = RealtimeCallCreateRequest;
export type create-realtime-callResponse = string;
export type accept-realtime-callBody = RealtimeSessionCreateRequestGA;
export type refer-realtime-callBody = RealtimeCallReferRequest;
export type reject-realtime-callBody = RealtimeCallRejectRequest;
export type create-realtime-client-secretBody = RealtimeCreateClientSecretRequest;
export type create-realtime-client-secretResponse = RealtimeCreateClientSecretResponse;
export type create-realtime-sessionBody = RealtimeSessionCreateRequest;
export type create-realtime-sessionResponse = RealtimeSessionCreateResponse;
export type create-realtime-transcription-sessionBody = RealtimeTranscriptionSessionCreateRequest;
export type create-realtime-transcription-sessionResponse = RealtimeTranscriptionSessionCreateResponse;
export type create-realtime-translation-client-secretBody = RealtimeTranslationClientSecretCreateRequest;
export type create-realtime-translation-client-secretResponse = RealtimeTranslationClientSecretCreateResponse;
export type createResponseBody = CreateResponse;
export type createResponseResponse = Response;
export type getResponseResponse = Response;
export type cancelResponseResponse = Response;
export type listInputItemsResponse = ResponseItemList;
export type createThreadBody = CreateThreadRequest;
export type createThreadResponse = ThreadObject;
export type createThreadAndRunBody = CreateThreadAndRunRequest;
export type createThreadAndRunResponse = RunObject;
export type getThreadResponse = ThreadObject;
export type modifyThreadBody = ModifyThreadRequest;
export type modifyThreadResponse = ThreadObject;
export type deleteThreadResponse = DeleteThreadResponse;
export type listMessagesResponse = ListMessagesResponse;
export type createMessageBody = CreateMessageRequest;
export type createMessageResponse = MessageObject;
export type getMessageResponse = MessageObject;
export type modifyMessageBody = ModifyMessageRequest;
export type modifyMessageResponse = MessageObject;
export type deleteMessageResponse = DeleteMessageResponse;
export type listRunsResponse = ListRunsResponse;
export type createRunBody = CreateRunRequest;
export type createRunResponse = RunObject;
export type getRunResponse = RunObject;
export type modifyRunBody = ModifyRunRequest;
export type modifyRunResponse = RunObject;
export type cancelRunResponse = RunObject;
export type listRunStepsResponse = ListRunStepsResponse;
export type getRunStepResponse = RunStepObject;
export type submitToolOuputsToRunBody = SubmitToolOutputsRunRequest;
export type submitToolOuputsToRunResponse = RunObject;
export type createUploadBody = CreateUploadRequest;
export type createUploadResponse = Upload;
export type cancelUploadResponse = Upload;
export type completeUploadBody = CompleteUploadRequest;
export type completeUploadResponse = Upload;
export type addUploadPartBody = AddUploadPartRequest;
export type addUploadPartResponse = UploadPart;
export type listVectorStoresResponse = ListVectorStoresResponse;
export type createVectorStoreBody = CreateVectorStoreRequest;
export type createVectorStoreResponse = VectorStoreObject;
export type getVectorStoreResponse = VectorStoreObject;
export type modifyVectorStoreBody = UpdateVectorStoreRequest;
export type modifyVectorStoreResponse = VectorStoreObject;
export type deleteVectorStoreResponse = DeleteVectorStoreResponse;
export type createVectorStoreFileBatchBody = CreateVectorStoreFileBatchRequest;
export type createVectorStoreFileBatchResponse = VectorStoreFileBatchObject;
export type getVectorStoreFileBatchResponse = VectorStoreFileBatchObject;
export type cancelVectorStoreFileBatchResponse = VectorStoreFileBatchObject;
export type listFilesInVectorStoreBatchResponse = ListVectorStoreFilesResponse;
export type listVectorStoreFilesResponse = ListVectorStoreFilesResponse;
export type createVectorStoreFileBody = CreateVectorStoreFileRequest;
export type createVectorStoreFileResponse = VectorStoreFileObject;
export type getVectorStoreFileResponse = VectorStoreFileObject;
export type updateVectorStoreFileAttributesBody = UpdateVectorStoreFileAttributesRequest;
export type updateVectorStoreFileAttributesResponse = VectorStoreFileObject;
export type deleteVectorStoreFileResponse = DeleteVectorStoreFileResponse;
export type retrieveVectorStoreFileContentResponse = VectorStoreFileContentResponse;
export type searchVectorStoreBody = VectorStoreSearchRequest;
export type searchVectorStoreResponse = VectorStoreSearchResultsPage;
export type createConversationBody = CreateConversationBody;
export type createConversationResponse = ConversationResource;
export type getConversationResponse = ConversationResource;
export type updateConversationBody = UpdateConversationBody;
export type updateConversationResponse = ConversationResource;
export type deleteConversationResponse = DeletedConversationResource;
export type ListVideosResponse = VideoListResource;
export type createVideoBody = CreateVideoMultipartBody;
export type createVideoResponse = VideoResource;
export type CreateVideoCharacterBody = CreateVideoCharacterBody;
export type CreateVideoCharacterResponse = VideoCharacterResource;
export type GetVideoCharacterResponse = VideoCharacterResource;
export type CreateVideoEditBody = CreateVideoEditMultipartBody;
export type CreateVideoEditResponse = VideoResource;
export type CreateVideoExtendBody = CreateVideoExtendMultipartBody;
export type CreateVideoExtendResponse = VideoResource;
export type GetVideoResponse = VideoResource;
export type DeleteVideoResponse = DeletedVideoResource;
export type RetrieveVideoContentResponse = string;
export type CreateVideoRemixBody = CreateVideoRemixBody;
export type CreateVideoRemixResponse = VideoResource;
export type GetinputtokencountsBody = TokenCountsBody;
export type GetinputtokencountsResponse = TokenCountsResource;
export type CompactconversationBody = CompactResponseMethodPublicBody;
export type CompactconversationResponse = CompactResource;
export type ListSkillsResponse = SkillListResource;
export type CreateSkillBody = CreateSkillBody;
export type CreateSkillResponse = SkillResource;
export type GetSkillResponse = SkillResource;
export type UpdateSkillDefaultVersionBody = SetDefaultSkillVersionBody;
export type UpdateSkillDefaultVersionResponse = SkillResource;
export type DeleteSkillResponse = DeletedSkillResource;
export type GetSkillContentResponse = string;
export type ListSkillVersionsResponse = SkillVersionListResource;
export type CreateSkillVersionBody = CreateSkillVersionBody;
export type CreateSkillVersionResponse = SkillVersionResource;
export type GetSkillVersionResponse = SkillVersionResource;
export type DeleteSkillVersionResponse = DeletedSkillVersionResource;
export type GetSkillVersionContentResponse = string;
export type CancelChatSessionMethodResponse = ChatSessionResource;
export type CreateChatSessionMethodBody = CreateChatSessionBody;
export type CreateChatSessionMethodResponse = ChatSessionResource;
export type ListThreadItemsMethodResponse = ThreadItemListResource;
export type GetThreadMethodResponse = ThreadResource;
export type DeleteThreadMethodResponse = DeletedThreadResource;
export type ListThreadsMethodResponse = ThreadListResource;
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |