From 00b505de61f19a45cdc81182726635b57892687b Mon Sep 17 00:00:00 2001 From: markstuart-oai <323302876+markstuart-oai@users.noreply.github.com> Date: Mon, 21 Sep 2026 02:00:29 +0000 Subject: [PATCH] fix(cli): preserve complete plain-text audio responses Castiron-Internal-PR: https://github.com/openai/openai-cli-internal/pull/86 Castiron-Source-SHA: 9c2eb49628fd9cf3d3b96d5e3e123b24a1fd67c9 Castiron-Public-Base-SHA: 0169bff050ff9c05c4609b669c06709306d464fa --- .castiron.stats.yml | 14 +- api_reference/openapi.transformed.yml | 28607 ++++++++++++------------ pkg/cmd/audioresponse_test.go | 120 + pkg/cmd/audiotranscription.go | 9 +- pkg/cmd/audiotranslation.go | 9 +- 5 files changed, 14462 insertions(+), 14297 deletions(-) create mode 100644 pkg/cmd/audioresponse_test.go diff --git a/.castiron.stats.yml b/.castiron.stats.yml index 696dc87f..67108efc 100644 --- a/.castiron.stats.yml +++ b/.castiron.stats.yml @@ -1,8 +1,8 @@ schema_version: 1 -generation_id: 3febc428-f82e-4bfa-a3a2-be64927f1e59 -openapi_spec_hash: 06abf78143cc2d777012de4b4bada359 -openapi_transformed_spec_hash: fb78e9baa61748309d4571899a7e3455 -config_hash: e5cd2ea20dc089f47efc81a424eea9bd -codegen_sha: 4b2cf190871d6ed4ac225b5c059ae4ad84d0c8d5 -codegen_hash: dd4e3a7cc6b4311ba6a88d7bfd9ce9f1a34fd23345b2406f243d3756444aa146 -public_codegen_sha: e2629f8ccb85c11b93a1dc5f2688b25d013d4580 +generation_id: 28d56c0c-7ad7-4507-b4c9-9a1c53beb6b5 +openapi_spec_hash: e2cec1422c7704234fb7736cb865dac9 +openapi_transformed_spec_hash: a75d8cbbd7e0eb8e9c6f533de814d732 +config_hash: ed4b5ec7cc6680aa56f7887fb0f487ad +codegen_sha: bc72e7d8f8be200c2d633e61d89b4d4b774bbbb3 +codegen_hash: 8a87c1bee991b56b246c24cc7f9ed810d7436bbab0e502821ac67ec20f412f47 +public_codegen_sha: e68d4ce918cd03eaf8be6539f6ed0eda9503b5f3 diff --git a/api_reference/openapi.transformed.yml b/api_reference/openapi.transformed.yml index ba43beb2..00f8f825 100644 --- a/api_reference/openapi.transformed.yml +++ b/api_reference/openapi.transformed.yml @@ -599,6 +599,30 @@ paths: schema: type: string format: binary + audio/mpeg: + schema: + type: string + format: binary + audio/aac: + schema: + type: string + format: binary + audio/opus: + schema: + type: string + format: binary + audio/flac: + schema: + type: string + format: binary + audio/pcm: + schema: + type: string + format: binary + audio/wav: + schema: + type: string + format: binary text/event-stream: schema: $ref: '#/components/schemas/CreateSpeechResponseStreamEvent' @@ -692,7 +716,8 @@ paths: Transcribes audio into the input language. Returns a transcription object in `json`, `diarized_json`, or `verbose_json` - format, or a stream of transcript events. + format, plain text in `text`, `srt`, or `vtt` format, or a stream of transcript + events. Supported formats depend on the model. requestBody: required: true content: @@ -713,6 +738,9 @@ paths: - $ref: '#/components/schemas/CreateTranscriptionResponseVerboseJson' discriminator: propertyName: task + text/plain: + schema: + type: string text/event-stream: schema: $ref: '#/components/schemas/CreateTranscriptionResponseStreamEvent' @@ -1269,6 +1297,9 @@ paths: - $ref: '#/components/schemas/CreateTranslationResponseVerboseJson' x-stainless-skip: - go + text/plain: + schema: + type: string '429': $ref: '#/components/responses/InferenceRateLimited' '503': @@ -22620,6 +22651,121 @@ paths: "created_at": 1741900000, "metadata": {"topic": "project-x"} } + /responses/{response_id}/cancel?beta=true: + post: + operationId: beta_cancelResponse + tags: + - Responses + summary: Cancel a response + description: | + Cancels a model response with the given ID. Only responses created with + the `background` parameter set to `true` can be cancelled. + [Learn more](https://developers.openai.com/api/docs/guides/background). + parameters: + - in: path + name: response_id + required: true + schema: + type: string + example: resp_677efb5139a88190b512bc3fef8e535d + description: The ID of the response to cancel. + - name: openai-beta + in: header + required: false + description: Optional beta features to enable for this request. + style: simple + explode: false + schema: + type: array + x-stainless-param: betas + items: + type: string + enum: + - responses_multi_agent=v1 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/BetaResponse' + '404': + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/BetaError' + '429': + $ref: '#/components/responses/TooManyRequests' + x-oaiMeta: + group: responses + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/responses/resp_123/cancel \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" + javascript: | + import OpenAI from "openai"; + const client = new OpenAI(); + + const response = await client.responses.cancel("resp_123"); + console.log(response); + python: | + from openai import OpenAI + client = OpenAI() + + response = client.responses.cancel("resp_123") + print(response) + response: | + { + "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", + "object": "response", + "created_at": 1741386163, + "status": "cancelled", + "background": true, + "completed_at": null, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [ + { + "type": "message", + "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", + "status": "in_progress", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + } /safety/alerts/{id}: get: summary: Get project safety alert @@ -22689,216 +22835,623 @@ paths: x-oaiMeta: group: live returns: The stored session recording as binary stereo WAV audio. - /organization/spend_limit: - get: - summary: Get organization spend limit - description: Get the organization's hard spend limit. - operationId: Getorganizationspendlimit - parameters: [] - responses: - '200': - description: Hard spend limit retrieved successfully. - content: - application/json: - schema: - $ref: '#/components/schemas/OrganizationSpendLimitResource' + /responses/input_tokens?beta=true: + post: x-oaiMeta: - group: administration + group: responses examples: request: curl: | - curl https://api.openai.com/v1/organization/spend_limit \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" + curl -X POST https://api.openai.com/v1/responses/input_tokens \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-6-astra", + "input": "Tell me a joke." + }' + javascript: | + import OpenAI from "openai"; + + const client = new OpenAI(); + + const response = await client.responses.inputTokens.count({ + model: "gpt-6-astra", + input: "Tell me a joke.", + }); + + console.log(response.input_tokens); + python: | + from openai import OpenAI + + client = OpenAI() + + response = client.responses.input_tokens.count( + model="gpt-6-astra", + input="Tell me a joke." + ) + print(response.input_tokens) + go: | + package main + + import ( + "context" + "fmt" + + "github.com/openai/openai-go" + "github.com/openai/openai-go/responses" + ) + + func main() { + client := openai.NewClient() + response, err := client.Responses.InputTokens.Count(context.TODO(), responses.InputTokenCountParams{ + Model: "gpt-6-astra", + Input: "Tell me a joke.", + }) + if err != nil { + panic(err.Error()) + } + fmt.Printf("%+v\n", response.InputTokens) + } + ruby: | + require "openai" + + openai = OpenAI::Client.new + + response = openai.responses.input_tokens.count(model: "gpt-6-astra", input: "Tell me a joke.") + + puts(response) + java: | + package com.openai.example; + + import com.openai.client.OpenAIClient; + import com.openai.client.okhttp.OpenAIOkHttpClient; + import com.openai.models.responses.inputtokens.InputTokenCountParams; + import com.openai.models.responses.inputtokens.InputTokenCountResponse; + + public final class Main { + private Main() {} + + public static void main(String[] args) { + OpenAIClient client = OpenAIOkHttpClient.fromEnv(); + + InputTokenCountParams params = InputTokenCountParams.builder() + .model("gpt-6-astra") + .input("Tell me a joke.") + .build(); + + InputTokenCountResponse response = client.responses().inputTokens().count(params); + } + } response: | { - "object": "organization.spend_limit", - "threshold_amount": 10000, - "currency": "USD", - "interval": "month", - "enforcement": { - "status": "enforcing" - } + "object": "response.input_tokens", + "input_tokens": 11 } - security: - - AdminApiKeyAuth: [] - post: - summary: Update organization spend limit - description: Create or replace the organization's hard spend limit. - operationId: Updateorganizationspendlimit - parameters: [] + summary: Get input token counts + description: |- + Returns input token counts of the request. + + Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. + operationId: beta_Getinputtokencounts + parameters: + - name: openai-beta + in: header + required: false + description: Optional beta features to enable for this request. + style: simple + explode: false + schema: + type: array + x-stainless-param: betas + items: + type: string + enum: + - responses_multi_agent=v1 requestBody: - description: Parameters for the hard spend limit you want to create or replace. content: application/json: schema: - $ref: '#/components/schemas/UpdateOrganizationSpendLimitBody' - required: true - responses: - '200': - description: Hard spend limit created or replaced successfully. - content: - application/json: - schema: - $ref: '#/components/schemas/OrganizationSpendLimitResource' - x-oaiMeta: - group: administration - examples: - request: - curl: | - curl -X POST https://api.openai.com/v1/organization/spend_limit \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "threshold_amount": 10000, - "currency": "USD", - "interval": "month" - }' - response: | - { - "object": "organization.spend_limit", - "threshold_amount": 10000, - "currency": "USD", - "interval": "month", - "enforcement": { - "status": "enforcing" - } - } - security: - - AdminApiKeyAuth: [] - delete: - summary: Delete organization spend limit - description: Delete the organization's hard spend limit. - operationId: Deleteorganizationspendlimit - parameters: [] + $ref: '#/components/schemas/BetaTokenCountsBody' responses: '200': - description: Hard spend limit deleted successfully. + description: Success content: application/json: schema: - $ref: '#/components/schemas/OrganizationSpendLimitDeletedResource' - x-oaiMeta: - group: administration - examples: - request: - curl: | - curl -X DELETE https://api.openai.com/v1/organization/spend_limit \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" - response: | - { - "object": "organization.spend_limit.deleted", - "deleted": true - } - security: - - AdminApiKeyAuth: [] - /organization/projects/{project_id}/spend_limit: + $ref: '#/components/schemas/BetaTokenCountsResource' + '429': + $ref: '#/components/responses/TooManyRequests' + /responses/{response_id}/input_items?beta=true: get: - summary: Get project spend limit - description: Get a project's hard spend limit. - operationId: Getprojectspendlimit + operationId: beta_listInputItems + tags: + - Responses + summary: List input items + description: Returns a list of input items for a given response. parameters: - - name: project_id - in: path - description: The ID of the project whose hard spend limit is being managed. + - in: path + name: response_id required: true schema: - example: proj_123 type: string - responses: - '200': - description: Hard spend limit retrieved successfully. - content: - application/json: - schema: - $ref: '#/components/schemas/ProjectSpendLimitResource' - x-oaiMeta: - group: administration - examples: - request: - curl: | - curl https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" - response: | - { - "object": "project.spend_limit", - "threshold_amount": 10000, - "currency": "USD", - "interval": "month", - "enforcement": { - "status": "enforcing" - } - } - security: - - AdminApiKeyAuth: [] - delete: - summary: Delete project spend limit - description: Delete a project's hard spend limit. - operationId: Deleteprojectspendlimit - parameters: - - name: project_id - in: path - description: The ID of the project whose hard spend limit is being managed. - required: true + description: The ID of the response to retrieve input items for. + - name: limit + in: query + description: | + A limit on the number of objects to be returned. Limit can range between + 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - in: query + name: order + schema: + type: string + enum: + - asc + - desc + description: | + The order to return the input items in. Default is `desc`. + - `asc`: Return the input items in ascending order. + - `desc`: Return the input items in descending order. + - in: query + name: after schema: - example: proj_123 type: string + description: | + An item ID to list items after, used in pagination. + - in: query + name: include + schema: + type: array + items: + $ref: '#/components/schemas/BetaIncludeEnum' + description: | + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. + - name: openai-beta + in: header + required: false + description: Optional beta features to enable for this request. + style: simple + explode: false + schema: + type: array + x-stainless-param: betas + items: + type: string + enum: + - responses_multi_agent=v1 responses: '200': - description: Hard spend limit deleted successfully. + description: OK content: application/json: schema: - $ref: '#/components/schemas/ProjectSpendLimitDeletedResource' + $ref: '#/components/schemas/BetaResponseItemList' + '429': + $ref: '#/components/responses/TooManyRequests' x-oaiMeta: - group: administration + group: responses examples: request: curl: | - curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" + curl https://api.openai.com/v1/responses/resp_abc123/input_items \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" + javascript: | + import OpenAI from "openai"; + const client = new OpenAI(); + + const response = await client.responses.inputItems.list("resp_123"); + console.log(response.data); + python: | + from openai import OpenAI + client = OpenAI() + + response = client.responses.input_items.list("resp_123") + print(response.data) response: | { - "object": "project.spend_limit.deleted", - "deleted": true + "object": "list", + "data": [ + { + "id": "msg_abc123", + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Tell me a three sentence bedtime story about a unicorn." + } + ] + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc123", + "has_more": false } - security: - - AdminApiKeyAuth: [] + /responses/compact?beta=true: post: - summary: Update project spend limit - description: Create or replace a project's hard spend limit. - operationId: Updateprojectspendlimit - parameters: - - name: project_id - in: path - description: The ID of the project whose hard spend limit is being managed. - required: true - schema: - example: proj_123 - type: string - requestBody: - description: Parameters for the hard spend limit you want to create or replace. - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateProjectSpendLimitBody' - required: true - responses: - '200': - description: Hard spend limit created or replaced successfully. - content: - application/json: - schema: - $ref: '#/components/schemas/ProjectSpendLimitResource' x-oaiMeta: - group: administration + group: responses examples: request: curl: | - curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ + curl -X POST https://api.openai.com/v1/responses/compact \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-6-astra", + "input": [ + { + "role": "user", + "content": "Create a simple landing page for a dog petting café." + }, + { + "id": "msg_001", + "type": "message", + "status": "completed", + "content": [ + { + "type": "output_text", + "annotations": [], + "logprobs": [], + "text": "Below is a single file, ready-to-use landing page for a dog petting café:..." + } + ], + "role": "assistant" + } + ] + }' + javascript: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + // Compact the previous response if you are running out of tokens + const compactedResponse = await openai.responses.compact({ + model: "gpt-6-astra", + input: [ + { + role: "user", + content: "Create a simple landing page for a dog petting café.", + }, + // All items returned from previous requests are included here, like reasoning, message, function call, etc. + { + id: "msg_030d085c0b53e67e0069332e3a72d4819c96c6f2c4adc15d33", + type: "message", + status: "completed", + content: [ + { + type: "output_text", + annotations: [], + logprobs: [], + text: "Below is a single file, ready-to-use landing page for a dog petting café:...", + }, + ], + role: "assistant", + }, + ], + }); + + // Pass the compactedResponse.output as input to the next request + console.log(compactedResponse); + python: | + from openai import OpenAI + + client = OpenAI() + + compacted_response = client.responses.compact( + model="gpt-6-astra", + input=[ + { + "role": "user", + "content": "Create a simple landing page for a dog petting cafe.", + }, + # All items returned from previous requests are included here, like reasoning, message, function call, etc. + { + "id": "msg_001", + "type": "message", + "status": "completed", + "content": [ + { + "type": "output_text", + "annotations": [], + "logprobs": [], + "text": "Below is a single file, ready-to-use landing page for a dog petting café:...", + }, + ], + "role": "assistant", + }, + ] + ) + # Pass the compacted_response.output as input to the next request + print(compacted_response) + response: | + { + "id": "resp_001", + "object": "response.compaction", + "created_at": 1764967971, + "output": [ + { + "id": "msg_000", + "type": "message", + "status": "completed", + "content": [ + { + "type": "input_text", + "text": "Create a simple landing page for a dog petting cafe." + } + ], + "role": "user" + }, + { + "id": "cmp_001", + "type": "compaction", + "encrypted_content": "gAAAAABpM0Yj-...=" + } + ], + "usage": { + "input_tokens": 139, + "input_tokens_details": { + "cached_tokens": 0, + "cache_write_tokens": 0 + }, + "output_tokens": 438, + "output_tokens_details": { + "reasoning_tokens": 64 + }, + "total_tokens": 577 + } + } + summary: Compact conversation + description: |- + Compact a conversation. Returns a compacted response object. + + Learn when and how to compact long-running conversations in the [conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://developers.openai.com/api/docs/guides/conversation-state#compaction-advanced). + operationId: beta_Compactconversation + parameters: + - name: openai-beta + in: header + required: false + description: Optional beta features to enable for this request. + style: simple + explode: false + schema: + type: array + x-stainless-param: betas + items: + type: string + enum: + - responses_multi_agent=v1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BetaCompactResponseMethodPublicBody' + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/BetaCompactResource' + '429': + $ref: '#/components/responses/InferenceRateLimited' + '503': + $ref: '#/components/responses/InferenceServiceUnavailable' + /organization/spend_limit: + get: + summary: Get organization spend limit + description: Get the organization's hard spend limit. + operationId: Getorganizationspendlimit + parameters: [] + responses: + '200': + description: Hard spend limit retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationSpendLimitResource' + x-oaiMeta: + group: administration + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.spend_limit", + "threshold_amount": 10000, + "currency": "USD", + "interval": "month", + "enforcement": { + "status": "enforcing" + } + } + security: + - AdminApiKeyAuth: [] + post: + summary: Update organization spend limit + description: Create or replace the organization's hard spend limit. + operationId: Updateorganizationspendlimit + parameters: [] + requestBody: + description: Parameters for the hard spend limit you want to create or replace. + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateOrganizationSpendLimitBody' + required: true + responses: + '200': + description: Hard spend limit created or replaced successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationSpendLimitResource' + x-oaiMeta: + group: administration + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "threshold_amount": 10000, + "currency": "USD", + "interval": "month" + }' + response: | + { + "object": "organization.spend_limit", + "threshold_amount": 10000, + "currency": "USD", + "interval": "month", + "enforcement": { + "status": "enforcing" + } + } + security: + - AdminApiKeyAuth: [] + delete: + summary: Delete organization spend limit + description: Delete the organization's hard spend limit. + operationId: Deleteorganizationspendlimit + parameters: [] + responses: + '200': + description: Hard spend limit deleted successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationSpendLimitDeletedResource' + x-oaiMeta: + group: administration + examples: + request: + curl: | + curl -X DELETE https://api.openai.com/v1/organization/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "organization.spend_limit.deleted", + "deleted": true + } + security: + - AdminApiKeyAuth: [] + /organization/projects/{project_id}/spend_limit: + get: + summary: Get project spend limit + description: Get a project's hard spend limit. + operationId: Getprojectspendlimit + parameters: + - name: project_id + in: path + description: The ID of the project whose hard spend limit is being managed. + required: true + schema: + example: proj_123 + type: string + responses: + '200': + description: Hard spend limit retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ProjectSpendLimitResource' + x-oaiMeta: + group: administration + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "project.spend_limit", + "threshold_amount": 10000, + "currency": "USD", + "interval": "month", + "enforcement": { + "status": "enforcing" + } + } + security: + - AdminApiKeyAuth: [] + delete: + summary: Delete project spend limit + description: Delete a project's hard spend limit. + operationId: Deleteprojectspendlimit + parameters: + - name: project_id + in: path + description: The ID of the project whose hard spend limit is being managed. + required: true + schema: + example: proj_123 + type: string + responses: + '200': + description: Hard spend limit deleted successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ProjectSpendLimitDeletedResource' + x-oaiMeta: + group: administration + examples: + request: + curl: | + curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: | + { + "object": "project.spend_limit.deleted", + "deleted": true + } + security: + - AdminApiKeyAuth: [] + post: + summary: Update project spend limit + description: Create or replace a project's hard spend limit. + operationId: Updateprojectspendlimit + parameters: + - name: project_id + in: path + description: The ID of the project whose hard spend limit is being managed. + required: true + schema: + example: proj_123 + type: string + requestBody: + description: Parameters for the hard spend limit you want to create or replace. + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateProjectSpendLimitBody' + required: true + responses: + '200': + description: Hard spend limit created or replaced successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ProjectSpendLimitResource' + x-oaiMeta: + group: administration + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_limit \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ @@ -23742,27 +24295,6 @@ paths: } /responses/input_tokens: post: - summary: Get input token counts - description: |- - Returns input token counts of the request. - - Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. - operationId: Getinputtokencounts - parameters: [] - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TokenCountsBody' - responses: - '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/TokenCountsResource' - '429': - $ref: '#/components/responses/TooManyRequests' x-oaiMeta: group: responses examples: @@ -23853,31 +24385,29 @@ paths: "object": "response.input_tokens", "input_tokens": 11 } - /responses/compact: - post: - summary: Compact conversation + summary: Get input token counts description: |- - Compact a conversation. Returns a compacted response object. + Returns input token counts of the request. - Learn when and how to compact long-running conversations in the [conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://developers.openai.com/api/docs/guides/conversation-state#compaction-advanced). - operationId: Compactconversation + Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. + operationId: Getinputtokencounts parameters: [] requestBody: content: application/json: schema: - $ref: '#/components/schemas/CompactResponseMethodPublicBody' + $ref: '#/components/schemas/TokenCountsBody' responses: '200': description: Success content: application/json: schema: - $ref: '#/components/schemas/CompactResource' + $ref: '#/components/schemas/TokenCountsResource' '429': - $ref: '#/components/responses/InferenceRateLimited' - '503': - $ref: '#/components/responses/InferenceServiceUnavailable' + $ref: '#/components/responses/TooManyRequests' + /responses/compact: + post: x-oaiMeta: group: responses examples: @@ -24010,6 +24540,29 @@ paths: "total_tokens": 577 } } + summary: Compact conversation + description: |- + Compact a conversation. Returns a compacted response object. + + Learn when and how to compact long-running conversations in the [conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://developers.openai.com/api/docs/guides/conversation-state#compaction-advanced). + operationId: Compactconversation + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CompactResponseMethodPublicBody' + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/CompactResource' + '429': + $ref: '#/components/responses/InferenceRateLimited' + '503': + $ref: '#/components/responses/InferenceServiceUnavailable' /skills: post: tags: @@ -29887,578 +30440,56 @@ paths: "object": "response", "deleted": true } - /responses/{response_id}/cancel?beta=true: +webhooks: + batch_cancelled: post: - operationId: beta_cancelResponse - tags: - - Responses - summary: Cancel a response description: | - Cancels a model response with the given ID. Only responses created with - the `background` parameter set to `true` can be cancelled. - [Learn more](https://developers.openai.com/api/docs/guides/background). - parameters: - - in: path - name: response_id - required: true - schema: - type: string - example: resp_677efb5139a88190b512bc3fef8e535d - description: The ID of the response to cancel. - - name: openai-beta - in: header - required: false - description: Optional beta features to enable for this request. - style: simple - explode: false - schema: - type: array - x-stainless-param: betas - items: - type: string - enum: - - responses_multi_agent=v1 + Sent when a batch has been cancelled. + requestBody: + description: The event payload sent by the API. + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookBatchCancelled' responses: '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/BetaResponse' - '404': - description: Not Found - content: - application/json: - schema: - $ref: '#/components/schemas/BetaError' - '429': - $ref: '#/components/responses/TooManyRequests' - x-oaiMeta: - group: responses - examples: - request: - curl: | - curl -X POST https://api.openai.com/v1/responses/resp_123/cancel \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" - javascript: | - import OpenAI from "openai"; - const client = new OpenAI(); - - const response = await client.responses.cancel("resp_123"); - console.log(response); - python: | - from openai import OpenAI - client = OpenAI() - - response = client.responses.cancel("resp_123") - print(response) - response: | - { - "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", - "object": "response", - "created_at": 1741386163, - "status": "cancelled", - "background": true, - "completed_at": null, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [ - { - "type": "message", - "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", - "status": "in_progress", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", - "annotations": [] - } - ] - } - ], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1.0, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1.0, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} - } - /responses/compact?beta=true: + description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" + batch_completed: post: - summary: Compact conversation - description: |- - Compact a conversation. Returns a compacted response object. - - Learn when and how to compact long-running conversations in the [conversation state guide](https://developers.openai.com/api/docs/guides/conversation-state#managing-the-context-window). For ZDR-compatible compaction details, see [Compaction (advanced)](https://developers.openai.com/api/docs/guides/conversation-state#compaction-advanced). - operationId: beta_Compactconversation - parameters: - - name: openai-beta - in: header - required: false - description: Optional beta features to enable for this request. - style: simple - explode: false - schema: - type: array - x-stainless-param: betas - items: - type: string - enum: - - responses_multi_agent=v1 + description: | + Sent when a batch has completed processing. requestBody: + description: The event payload sent by the API. content: application/json: schema: - $ref: '#/components/schemas/BetaCompactResponseMethodPublicBody' + $ref: '#/components/schemas/WebhookBatchCompleted' responses: '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/BetaCompactResource' - '429': - $ref: '#/components/responses/InferenceRateLimited' - '503': - $ref: '#/components/responses/InferenceServiceUnavailable' - x-oaiMeta: - group: responses - examples: - request: - curl: | - curl -X POST https://api.openai.com/v1/responses/compact \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-6-astra", - "input": [ - { - "role": "user", - "content": "Create a simple landing page for a dog petting café." - }, - { - "id": "msg_001", - "type": "message", - "status": "completed", - "content": [ - { - "type": "output_text", - "annotations": [], - "logprobs": [], - "text": "Below is a single file, ready-to-use landing page for a dog petting café:..." - } - ], - "role": "assistant" - } - ] - }' - javascript: | - import OpenAI from "openai"; - - const openai = new OpenAI(); - - // Compact the previous response if you are running out of tokens - const compactedResponse = await openai.responses.compact({ - model: "gpt-6-astra", - input: [ - { - role: "user", - content: "Create a simple landing page for a dog petting café.", - }, - // All items returned from previous requests are included here, like reasoning, message, function call, etc. - { - id: "msg_030d085c0b53e67e0069332e3a72d4819c96c6f2c4adc15d33", - type: "message", - status: "completed", - content: [ - { - type: "output_text", - annotations: [], - logprobs: [], - text: "Below is a single file, ready-to-use landing page for a dog petting café:...", - }, - ], - role: "assistant", - }, - ], - }); - - // Pass the compactedResponse.output as input to the next request - console.log(compactedResponse); - python: | - from openai import OpenAI - - client = OpenAI() - - compacted_response = client.responses.compact( - model="gpt-6-astra", - input=[ - { - "role": "user", - "content": "Create a simple landing page for a dog petting cafe.", - }, - # All items returned from previous requests are included here, like reasoning, message, function call, etc. - { - "id": "msg_001", - "type": "message", - "status": "completed", - "content": [ - { - "type": "output_text", - "annotations": [], - "logprobs": [], - "text": "Below is a single file, ready-to-use landing page for a dog petting café:...", - }, - ], - "role": "assistant", - }, - ] - ) - # Pass the compacted_response.output as input to the next request - print(compacted_response) - response: | - { - "id": "resp_001", - "object": "response.compaction", - "created_at": 1764967971, - "output": [ - { - "id": "msg_000", - "type": "message", - "status": "completed", - "content": [ - { - "type": "input_text", - "text": "Create a simple landing page for a dog petting cafe." - } - ], - "role": "user" - }, - { - "id": "cmp_001", - "type": "compaction", - "encrypted_content": "gAAAAABpM0Yj-...=" - } - ], - "usage": { - "input_tokens": 139, - "input_tokens_details": { - "cached_tokens": 0, - "cache_write_tokens": 0 - }, - "output_tokens": 438, - "output_tokens_details": { - "reasoning_tokens": 64 - }, - "total_tokens": 577 - } - } - /responses/{response_id}/input_items?beta=true: - get: - operationId: beta_listInputItems - tags: - - Responses - summary: List input items - description: Returns a list of input items for a given response. - parameters: - - in: path - name: response_id - required: true - schema: - type: string - description: The ID of the response to retrieve input items for. - - name: limit - in: query - description: | - A limit on the number of objects to be returned. Limit can range between - 1 and 100, and the default is 20. - required: false - schema: - type: integer - default: 20 - - in: query - name: order - schema: - type: string - enum: - - asc - - desc - description: | - The order to return the input items in. Default is `desc`. - - `asc`: Return the input items in ascending order. - - `desc`: Return the input items in descending order. - - in: query - name: after - schema: - type: string - description: | - An item ID to list items after, used in pagination. - - in: query - name: include - schema: - type: array - items: - $ref: '#/components/schemas/BetaIncludeEnum' - description: | - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. - - name: openai-beta - in: header - required: false - description: Optional beta features to enable for this request. - style: simple - explode: false - schema: - type: array - x-stainless-param: betas - items: - type: string - enum: - - responses_multi_agent=v1 + description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" + batch_expired: + post: + description: | + Sent when a batch has expired before completion. + requestBody: + description: The event payload sent by the API. + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookBatchExpired' responses: '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/BetaResponseItemList' - '429': - $ref: '#/components/responses/TooManyRequests' - x-oaiMeta: - group: responses - examples: - request: - curl: | - curl https://api.openai.com/v1/responses/resp_abc123/input_items \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" - javascript: | - import OpenAI from "openai"; - const client = new OpenAI(); - - const response = await client.responses.inputItems.list("resp_123"); - console.log(response.data); - python: | - from openai import OpenAI - client = OpenAI() - - response = client.responses.input_items.list("resp_123") - print(response.data) - response: | - { - "object": "list", - "data": [ - { - "id": "msg_abc123", - "type": "message", - "role": "user", - "content": [ - { - "type": "input_text", - "text": "Tell me a three sentence bedtime story about a unicorn." - } - ] - } - ], - "first_id": "msg_abc123", - "last_id": "msg_abc123", - "has_more": false - } - /responses/input_tokens?beta=true: + description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" + batch_failed: post: - summary: Get input token counts - description: |- - Returns input token counts of the request. - - Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. - operationId: beta_Getinputtokencounts - parameters: - - name: openai-beta - in: header - required: false - description: Optional beta features to enable for this request. - style: simple - explode: false - schema: - type: array - x-stainless-param: betas - items: - type: string - enum: - - responses_multi_agent=v1 + description: | + Sent when a batch has failed. requestBody: + description: The event payload sent by the API. content: application/json: schema: - $ref: '#/components/schemas/BetaTokenCountsBody' - responses: - '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/BetaTokenCountsResource' - '429': - $ref: '#/components/responses/TooManyRequests' - x-oaiMeta: - group: responses - examples: - request: - curl: | - curl -X POST https://api.openai.com/v1/responses/input_tokens \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-6-astra", - "input": "Tell me a joke." - }' - javascript: | - import OpenAI from "openai"; - - const client = new OpenAI(); - - const response = await client.responses.inputTokens.count({ - model: "gpt-6-astra", - input: "Tell me a joke.", - }); - - console.log(response.input_tokens); - python: | - from openai import OpenAI - - client = OpenAI() - - response = client.responses.input_tokens.count( - model="gpt-6-astra", - input="Tell me a joke." - ) - print(response.input_tokens) - go: | - package main - - import ( - "context" - "fmt" - - "github.com/openai/openai-go" - "github.com/openai/openai-go/responses" - ) - - func main() { - client := openai.NewClient() - response, err := client.Responses.InputTokens.Count(context.TODO(), responses.InputTokenCountParams{ - Model: "gpt-6-astra", - Input: "Tell me a joke.", - }) - if err != nil { - panic(err.Error()) - } - fmt.Printf("%+v\n", response.InputTokens) - } - ruby: | - require "openai" - - openai = OpenAI::Client.new - - response = openai.responses.input_tokens.count(model: "gpt-6-astra", input: "Tell me a joke.") - - puts(response) - java: | - package com.openai.example; - - import com.openai.client.OpenAIClient; - import com.openai.client.okhttp.OpenAIOkHttpClient; - import com.openai.models.responses.inputtokens.InputTokenCountParams; - import com.openai.models.responses.inputtokens.InputTokenCountResponse; - - public final class Main { - private Main() {} - - public static void main(String[] args) { - OpenAIClient client = OpenAIOkHttpClient.fromEnv(); - - InputTokenCountParams params = InputTokenCountParams.builder() - .model("gpt-6-astra") - .input("Tell me a joke.") - .build(); - - InputTokenCountResponse response = client.responses().inputTokens().count(params); - } - } - response: | - { - "object": "response.input_tokens", - "input_tokens": 11 - } -webhooks: - batch_cancelled: - post: - description: | - Sent when a batch has been cancelled. - requestBody: - description: The event payload sent by the API. - content: - application/json: - schema: - $ref: '#/components/schemas/WebhookBatchCancelled' - responses: - '200': - description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" - batch_completed: - post: - description: | - Sent when a batch has completed processing. - requestBody: - description: The event payload sent by the API. - content: - application/json: - schema: - $ref: '#/components/schemas/WebhookBatchCompleted' - responses: - '200': - description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" - batch_expired: - post: - description: | - Sent when a batch has expired before completion. - requestBody: - description: The event payload sent by the API. - content: - application/json: - schema: - $ref: '#/components/schemas/WebhookBatchExpired' - responses: - '200': - description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" - batch_failed: - post: - description: | - Sent when a batch has failed. - requestBody: - description: The event payload sent by the API. - content: - application/json: - schema: - $ref: '#/components/schemas/WebhookBatchFailed' + $ref: '#/components/schemas/WebhookBatchFailed' responses: '200': description: "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n" @@ -31452,6 +31483,36 @@ components: id: type: string description: The ID of the external key configuration. + certificates.deactivated: + type: object + description: The details for events with this `type`. + properties: + certificates: + type: array + items: + type: object + properties: + id: + type: string + description: The certificate ID. + name: + type: string + description: The name of the certificate. + certificates.activated: + type: object + description: The details for events with this `type`. + properties: + certificates: + type: array + items: + type: object + properties: + id: + type: string + description: The certificate ID. + name: + type: string + description: The name of the certificate. group.created: type: object description: The details for events with this `type`. @@ -32106,36 +32167,6 @@ components: certificate: type: string description: The certificate content in PEM format. - certificates.activated: - type: object - description: The details for events with this `type`. - properties: - certificates: - type: array - items: - type: object - properties: - id: - type: string - description: The certificate ID. - name: - type: string - description: The name of the certificate. - certificates.deactivated: - type: object - description: The details for events with this `type`. - properties: - certificates: - type: array - items: - type: object - properties: - id: - type: string - description: The certificate ID. - name: - type: string - description: The name of the certificate. required: - id - type @@ -66130,6 +66161,40 @@ components: "type": "safety.alert.created", "data": {"id": "alert_0123456789abcdef0123456789abcdef"} } + BetaInputAudio: + type: object + title: Input audio + description: | + An audio input to the model. + properties: + type: + type: string + description: | + The type of the input item. Always `input_audio`. + enum: + - input_audio + x-stainless-const: true + input_audio: + type: object + properties: + data: + type: string + description: | + Base64-encoded audio data. + format: + type: string + description: | + The format of the audio data. Currently supported formats are `mp3` and + `wav`. + enum: + - mp3 + - wav + required: + - data + - format + required: + - type + - input_audio WebhookSafetyOrgAlertCreated: type: object title: safety.org_alert.created @@ -66181,6 +66246,31 @@ components: "type": "safety.org_alert.created", "data": {"id": "alert_0123456789abcdef0123456789abcdef"} } + BetaOutputAudio: + type: object + title: Output audio + description: | + An audio output from the model. + properties: + type: + type: string + description: | + The type of the output audio. Always `output_audio`. + enum: + - output_audio + x-stainless-const: true + data: + type: string + description: | + Base64-encoded audio data from the model. + transcript: + type: string + description: | + The transcript of the audio data from the model. + required: + - type + - data + - transcript ModerationInputType: type: string enum: @@ -70339,6 +70429,96 @@ components: URI that should appear in the SIP Refer-To header. Supports values like `tel:+14155550123` or `sip:agent@example.com`. example: tel:+14155550123 + BetaCreateModelResponseProperties: + allOf: + - $ref: '#/components/schemas/BetaModelResponseProperties' + - type: object + properties: + prompt_cache_options: + $ref: '#/components/schemas/BetaPromptCacheOptionsParam' + top_logprobs: + description: | + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + type: integer + minimum: 0 + maximum: 20 + BetaModerationMode: + type: string + enum: + - score + - block + BetaResponseSteerEvent: + type: object + title: ResponseSteerEvent + additionalProperties: false + description: | + Queues user input to steer a response on this WebSocket connection. Input + can contain text, images, and files. Steering is supported only for + single-agent responses on models and execution modes that support steering. + Responses bound to a conversation or using automatic compaction do not + support steering. + + A `response.steer.accepted` event acknowledges that the server owns the + queued input, not that it has been applied. The successor's `response.created` + event is the commit point. Input that cannot be committed is returned in + `response.steer.failed`. + + Steering may cause the active response to finish at a safe output boundary + with `response.incomplete` and `incomplete_details.reason` set to `steered`, + followed automatically by a successor `response.created`. Normal completion + can also be followed by an automatic successor. Automatic successors inherit + the previous response's settings and continue from it with the queued input. + + If the response stops for client-owned tool output or approval, accepted + steering input remains queued and `response.steer.pending` is emitted after + `response.completed`. Fill the `required_input` stubs from that event with + saved tool results or approval decisions, and send one explicit + `response.create` per parent with the same `previous_response_id` and + WebSocket lane. Do not rerun tools or resend accepted steering input. The + queued input is prepended in submission order to that request's input, and + the explicit request retains its own settings. + + This event accepts only `type`, `previous_response_id`, and `input`. Do not + send `stream_id`; the target response determines the WebSocket lane. + properties: + type: + type: string + enum: + - response.steer + description: The event discriminator. Always `response.steer`. + x-stainless-const: true + previous_response_id: + type: string + description: The ID of the response to steer on this WebSocket connection. + input: + $ref: '#/components/schemas/BetaResponseSteerInput' + required: + - type + - previous_response_id + - input + x-oaiMeta: + name: response.steer + group: responses + example: | + { + "type": "response.steer", + "previous_response_id": "resp_123", + "input": [ + { + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Prioritize the database rollout." + } + ] + } + ] + } PublicProjectResidency: type: string enum: @@ -70843,6 +71023,127 @@ components: - object - deleted - id + BetaResponsesClientEvent: + discriminator: + propertyName: type + description: | + Client events accepted by the Responses WebSocket server. + anyOf: + - $ref: '#/components/schemas/BetaResponsesClientEventResponseCreate' + - $ref: '#/components/schemas/BetaResponseSteerEvent' + - $ref: '#/components/schemas/BetaResponseInjectEvent' + BetaResponseInjectEvent: + type: object + title: ResponseInjectEvent + description: | + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. + properties: + type: + type: string + enum: + - response.inject + description: The event discriminator. Always `response.inject`. + x-stainless-const: true + response_id: + type: string + description: The ID of the active response that should receive the input. + input: + type: array + maxItems: 16384 + description: Input items to inject into the active response. + items: + $ref: '#/components/schemas/BetaInputItem' + required: + - type + - response_id + - input + x-oai-beta: responses_multi_agent=v1 + x-oaiMeta: + example: | + { + "type": "response.inject", + "response_id": "resp_123", + "input": [ + { + "type": "function_call_output", + "call_id": "call_123", + "output": "{\"temperature\":72}" + } + ] + } + BetaResponsesWebSocketStreamEvent: + allOf: + - anyOf: + - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' + - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' + - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' + - $ref: '#/components/schemas/BetaResponseCompletedEvent' + - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' + - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' + - $ref: '#/components/schemas/BetaResponseCreatedEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' + x-stainless-skip: + - go + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' + - $ref: '#/components/schemas/BetaResponseInProgressEvent' + - $ref: '#/components/schemas/BetaResponseFailedEvent' + - $ref: '#/components/schemas/BetaResponseIncompleteEvent' + - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' + - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' + - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' + - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' + - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' + - $ref: '#/components/schemas/BetaResponseQueuedEvent' + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. SafetyAlertErrorType: type: string enum: @@ -70890,6 +71191,282 @@ components: - request_paused - error_type - reason + BetaContextManagementParam: + properties: + type: + type: string + description: The context management entry type. Currently only 'compaction' is supported. + compact_threshold: + anyOf: + - type: integer + minimum: 1000 + description: Token threshold at which compaction should be triggered for this entry. + - type: 'null' + type: object + required: + - type + BetaCreateResponse: + allOf: + - $ref: '#/components/schemas/BetaCreateModelResponseProperties' + - $ref: '#/components/schemas/BetaResponseProperties' + - type: object + properties: + prompt_cache_options: + $ref: '#/components/schemas/BetaResponsePromptCacheOptionsParam' + service_tier: + $ref: '#/components/schemas/BetaServiceTierResponses' + truncation: + deprecated: true + anyOf: + - type: string + description: | + The truncation strategy to use for the model response. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + enum: + - auto + - disabled + default: disabled + - type: 'null' + reasoning: + anyOf: + - $ref: '#/components/schemas/BetaReasoning' + - type: 'null' + input: + $ref: '#/components/schemas/BetaInputParam' + include: + anyOf: + - type: array + description: |- + Specify additional output data to include in the model response. Currently supported values are: + - `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). + items: + $ref: '#/components/schemas/BetaIncludeEnum' + - type: 'null' + parallel_tool_calls: + anyOf: + - type: boolean + description: | + Whether to allow the model to run tool calls in parallel. + default: true + - type: 'null' + store: + anyOf: + - type: boolean + description: | + Whether to store the generated model response for later retrieval via + API. + Defaults to true when omitted. + If set to true, response data will be stored for at least 30 days, subject to the [data retention exceptions](https://developers.openai.com/api/docs/guides/your-data#v1responses). + default: true + - type: 'null' + instructions: + anyOf: + - type: string + description: | + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + - type: 'null' + moderation: + anyOf: + - $ref: '#/components/schemas/BetaModerationParam' + description: | + Configuration for running moderation on the input and output of this response. + - type: 'null' + stream: + anyOf: + - description: | + If set to true, the model response data will be streamed to the client + as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the [Streaming section below](https://developers.openai.com/api/reference/resources/responses/streaming-events) + for more information. + type: boolean + default: false + - type: 'null' + stream_options: + $ref: '#/components/schemas/BetaResponseStreamOptions' + conversation: + anyOf: + - $ref: '#/components/schemas/BetaConversationParam' + - type: 'null' + context_management: + anyOf: + - type: array + example: + - type: compaction + compact_threshold: 1000 + description: | + Context management configuration for this request. + minItems: 1 + items: + $ref: '#/components/schemas/BetaContextManagementParam' + - type: 'null' + max_output_tokens: + anyOf: + - description: | + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning). + type: integer + minimum: 16 + - type: 'null' + multi_agent: + anyOf: + - $ref: '#/components/schemas/BetaMultiAgentParam' + description: Configuration for server-hosted multi-agent execution. + - type: 'null' + BetaMultiAgentParam: + properties: + enabled: + type: boolean + description: Whether to enable server-hosted multi-agent execution for this response. + max_concurrent_subagents: + type: integer + minimum: 1 + description: |- + `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. + The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + type: object + required: + - enabled + description: Configuration for server-hosted multi-agent execution. + x-oai-beta: responses_multi_agent=v1 + BetaResponseStreamOptions: + anyOf: + - description: | + Options for streaming responses. Only set this when you set `stream: true`. + type: object + properties: + include_obfuscation: + type: boolean + description: | + When true, stream obfuscation will be enabled. Stream obfuscation adds + random characters to an `obfuscation` field on streaming delta events to + normalize payload sizes as a mitigation to certain side-channel attacks. + These obfuscation fields are included by default, but add a small amount + of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between + your application and the OpenAI API. + - type: 'null' + BetaResponseStreamEvent: + description: Event emitted while a response is streamed. + anyOf: + - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' + - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' + - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' + - $ref: '#/components/schemas/BetaResponseCompletedEvent' + - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' + - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' + - $ref: '#/components/schemas/BetaResponseCreatedEvent' + - $ref: '#/components/schemas/BetaResponseErrorEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' + x-stainless-skip: + - go + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' + - $ref: '#/components/schemas/BetaResponseInProgressEvent' + - $ref: '#/components/schemas/BetaResponseFailedEvent' + - $ref: '#/components/schemas/BetaResponseIncompleteEvent' + - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' + - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' + - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' + - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' + - $ref: '#/components/schemas/BetaResponseTextDoneEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' + - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' + - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' + - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' + - $ref: '#/components/schemas/BetaResponseQueuedEvent' + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' + discriminator: + propertyName: type + BetaResponsePromptCacheOptionsParam: + properties: + ttl: + $ref: '#/components/schemas/BetaPromptCacheTTLEnum' + description: The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + mode: + $ref: '#/components/schemas/BetaPromptCacheModeEnum' + description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + prewarm: + type: boolean + description: Prepares the prompt cache without generating output. Defaults to `false`. When set to `true`, overrides the `generate` field to `false`. + comparison_response_id: + anyOf: + - type: string + description: The ID of a response to compare when diagnosing prompt cache reuse. Supplying this field requests prompt cache diagnostics when the feature is enabled. + example: resp_123 + - type: 'null' + type: object + required: [] + title: Prompt cache options + description: Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for current details. + BetaModerationConfigParam: + properties: + mode: + $ref: '#/components/schemas/BetaModerationMode' + type: object + required: + - mode + description: The moderation policy for the response input. + BetaModerationParam: + properties: + model: + type: string + description: The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + policy: + anyOf: + - $ref: '#/components/schemas/BetaModerationPolicyParam' + description: The policy to apply to moderated response input and output. + - type: 'null' + type: object + required: + - model + description: Configuration for running moderation on the input and output of this response. SpendLimitCurrency: anyOf: - type: string @@ -78379,6 +78956,41 @@ components: - environment additionalProperties: false description: Emitted when a hosted session environment is ready to connect. + BetaErrorPayload: + properties: + type: + type: string + description: The error type that was emitted. + code: + anyOf: + - type: string + description: The error code that was emitted, if any. + - type: 'null' + message: + type: string + description: The human-readable error message that was emitted. + param: + anyOf: + - type: string + description: The parameter name that was associated with the error, if any. + - type: 'null' + headers: + additionalProperties: + type: string + description: The header value that was emitted. + type: object + description: The response headers that were emitted with the error, if any. + x-oaiTypeLabel: map + misalignment: + $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' + type: object + required: + - type + - code + - message + - param + title: Error payload + description: An error payload that was emitted for a streaming error event. SessionEventAgentOutputCommandExecutionOutputDelta: type: object properties: @@ -79566,6 +80178,7 @@ components: mapping: error: '#/components/schemas/SessionEventError' agent.session.environment.ready: '#/components/schemas/SessionEventAgentSessionEnvironmentReady' + agent.session.turn.reasoning_summary_text.done: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDone' agent.output.command_execution_output.delta: '#/components/schemas/SessionEventAgentOutputCommandExecutionOutputDelta' agent.session.created: '#/components/schemas/SessionEventAgentSessionCreated' agent.session.turn.created: '#/components/schemas/SessionEventAgentSessionTurnCreated' @@ -79593,7 +80206,6 @@ components: agent.session.turn.reasoning_summary_part.added: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartAdded' agent.session.turn.reasoning_summary_part.done: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartDone' agent.session.turn.reasoning_summary_text.delta: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDelta' - agent.session.turn.reasoning_summary_text.done: '#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDone' x-oai-discriminator-values: - error - agent.session.environment.ready @@ -80250,6 +80862,106 @@ components: - mcp_server_url additionalProperties: false description: Metadata for a bearer-token credential, without automatic OAuth refresh. + BetaInputParam: + description: | + Text, image, or file inputs to the model, used to generate a response. + + Learn more: + - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) + - [Image inputs](https://developers.openai.com/api/docs/guides/images-vision) + - [File inputs](https://developers.openai.com/api/docs/guides/file-inputs) + - [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) + - [Function calling](https://developers.openai.com/api/docs/guides/function-calling) + anyOf: + - type: string + title: Text input + description: | + A text input to the model, equivalent to a text input with the + `user` role. + - type: array + title: Input item list + description: | + A list of one or many input items to the model, containing + different content types. + items: + $ref: '#/components/schemas/BetaInputItem' + BetaContent: + description: | + Multi-modal input and output contents. + anyOf: + - title: Input content types + $ref: '#/components/schemas/BetaInputContent' + - title: Output content types + $ref: '#/components/schemas/BetaOutputContent' + BetaIncludeEnum: + type: string + enum: + - 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 + description: |- + 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). + BetaResponseWsError: + type: object + title: ResponseWsError + description: Emitted when an error occurs while processing a Responses WebSocket request. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: The type of the event. Always `error`. + enum: + - error + x-stainless-const: true + status: + type: integer + description: The HTTP status code associated with a WebSocket protocol error. + sequence_number: + type: integer + description: The sequence number of an error emitted by the response stream. + error: + $ref: '#/components/schemas/BetaErrorPayload' + description: Details about the error. + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present when the + originating `response.create` event supplied a `stream_id`. + required: + - type + - error + x-oaiMeta: + name: error + group: responses + example: | + { + "type": "error", + "status": 400, + "stream_id": "agent_1", + "error": { + "type": "invalid_request_error", + "code": "websocket_stream_limit_reached", + "message": "This WebSocket connection has reached its stream limit.", + "param": "stream_id" + } + } VaultCredentialAuthResource: description: The MCP server and authentication configuration of a vault credential, excluding secrets. discriminator: @@ -80522,12759 +81234,5981 @@ components: - token additionalProperties: false description: A bearer token for an MCP server, without automatic OAuth refresh. - CreateVaultCredentialAuthParam: - description: Authentication credentials for an MCP server used by agent tools. - discriminator: - propertyName: type - mapping: - mcp_oauth: '#/components/schemas/CreateVaultCredentialAuthParamMcpOauth' - static_bearer: '#/components/schemas/CreateVaultCredentialAuthParamStaticBearer' - x-oai-discriminator-values: - - mcp_oauth - - static_bearer - anyOf: - - $ref: '#/components/schemas/CreateVaultCredentialAuthParamMcpOauth' - - $ref: '#/components/schemas/CreateVaultCredentialAuthParamStaticBearer' - CreateVaultCredentialParams: - type: object - properties: - name: - type: string - minLength: 1 - maxLength: 1048576 - description: The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. - auth: - $ref: '#/components/schemas/CreateVaultCredentialAuthParam' - description: The authentication method and secret values to store for the MCP server. - required: - - auth - - name - additionalProperties: false - description: Parameters for storing a credential that authorizes access to an MCP server. - RotateMcpOauthTokenEndpointAuthParamClientSecretBasic: - type: object - properties: - type: - type: string - enum: - - client_secret_basic - default: client_secret_basic - x-stainless-const: true - description: The type of the object. Always `client_secret_basic`. - client_secret: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. - required: - - type - additionalProperties: false - description: Updates credentials sent using HTTP Basic authentication. - RotateMcpOauthTokenEndpointAuthParamClientSecretPost: - type: object - properties: - type: - type: string - enum: - - client_secret_post - default: client_secret_post - x-stainless-const: true - description: The type of the object. Always `client_secret_post`. - client_secret: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. - required: - - type - additionalProperties: false - description: Updates credentials sent in the token request body. - RotateMcpOauthTokenEndpointAuthParam: - description: Client-secret updates that preserve the credential's OAuth authentication method. - discriminator: - propertyName: type - mapping: - client_secret_basic: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretBasic' - client_secret_post: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretPost' - x-oai-discriminator-values: - - client_secret_basic - - client_secret_post - anyOf: - - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretBasic' - - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretPost' - RotateMcpOauthRefreshParam: - type: object - properties: - refresh_token: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: The replacement refresh token. Omit or pass `null` to keep the stored token. This secret is never returned in resources. - scope: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: Replacement space-separated OAuth scopes for refresh requests. Omit to keep the scopes, or pass `null` to stop sending a scope parameter. - token_endpoint_auth: - anyOf: - - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParam' - - type: 'null' - description: Client-secret updates for the existing token endpoint authentication method. - additionalProperties: false - description: Updates to an MCP credential's existing OAuth refresh configuration. - RotateVaultCredentialAuthParamMcpOauth: - type: object - properties: - type: - type: string - enum: - - mcp_oauth - default: mcp_oauth - x-stainless-const: true - description: The type of the object. Always `mcp_oauth`. - access_token: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: A write-only replacement OAuth access token. - expires_at: - type: - - string - - 'null' - minLength: 0 - maxLength: 1048576 - description: The replacement expiry as an RFC 3339 timestamp, or `null` to clear it. Omitting this field preserves the expiry unless a new access token is supplied, in which case the expiry is cleared. - refresh: - anyOf: - - $ref: '#/components/schemas/RotateMcpOauthRefreshParam' - - type: 'null' - description: Optional write-only refresh-token and client-secret updates. - required: - - type - additionalProperties: false - description: Rotate an OAuth credential for an HTTPS MCP destination. - RotateVaultCredentialAuthParamStaticBearer: - type: object - properties: - type: - type: string - enum: - - static_bearer - default: static_bearer - x-stainless-const: true - description: The type of the object. Always `static_bearer`. - token: - type: string - minLength: 0 - maxLength: 1048576 - description: The replacement bearer token. This secret is never returned in credential resources. - required: - - type - - token - additionalProperties: false - description: Replace the bearer token for the credential's MCP server. - RotateVaultCredentialAuthParam: - description: Updates to a vault credential without changing its authentication method or MCP server. + BetaResponsesServerEvent: discriminator: propertyName: type - mapping: - mcp_oauth: '#/components/schemas/RotateVaultCredentialAuthParamMcpOauth' - static_bearer: '#/components/schemas/RotateVaultCredentialAuthParamStaticBearer' - x-oai-discriminator-values: - - mcp_oauth - - static_bearer + description: | + Server events emitted by the Responses WebSocket server. anyOf: - - $ref: '#/components/schemas/RotateVaultCredentialAuthParamMcpOauth' - - $ref: '#/components/schemas/RotateVaultCredentialAuthParamStaticBearer' - RotateVaultCredentialParams: - type: object - properties: - auth: - $ref: '#/components/schemas/RotateVaultCredentialAuthParam' - description: Replacement values for the credential's existing authentication method. - required: - - auth - additionalProperties: false - description: Secret, expiry, and OAuth refresh scope updates for an existing vault credential. - DeletedVaultCredentialResource: - type: object - properties: - id: - type: string - minLength: 0 - description: The ID of the deleted credential. - object: - type: string - enum: - - vault.credential.deleted - default: vault.credential.deleted - x-stainless-const: true - description: The object type. Always `vault.credential.deleted`. - deleted: - type: boolean - description: Whether the resource was deleted. Always `true`. - required: - - id - - object - - deleted - additionalProperties: false - description: Confirmation that a vault credential was deleted. - WebhookEndpointBody: - properties: - id: - type: string - description: The unique ID of the webhook endpoint. - object: - type: string - enum: - - webhook_endpoint - description: The object type, which is always webhook_endpoint. - default: webhook_endpoint - x-stainless-const: true - created_at: - type: integer - format: unixtime - description: The Unix timestamp when the endpoint was created. - updated_at: - type: integer - format: unixtime - description: The Unix timestamp of the last endpoint configuration or signing-secret change. Initialized at creation; tests and unchanged updates do not advance it. - name: - type: string - description: The human-readable name of the endpoint. - url: - type: string - description: The HTTPS URL that receives webhook deliveries. - event_types: - items: - type: string - type: array - description: The event types that trigger deliveries to this endpoint. - signing_secret_hint: - anyOf: - - type: string - description: A masked hint for the endpoint's signing secret. - - type: 'null' - type: object - required: - - id - - object - - created_at - - name - - url - - event_types - - signing_secret_hint - WebhookEndpointListResource: - properties: - object: - type: string - enum: - - list - description: The object type, which is always list. - default: list - x-stainless-const: true - data: - items: - $ref: '#/components/schemas/WebhookEndpointBody' - type: array - description: The webhook endpoints in this page. - first_id: - anyOf: - - type: string - description: The ID of the first endpoint in this page. - - type: 'null' - last_id: - anyOf: - - type: string - description: The ID of the last endpoint in this page. - - type: 'null' - has_more: - type: boolean - description: Whether more webhook endpoints are available. - type: object - required: - - object - - data - - first_id - - last_id - - has_more - ProjectEventTypeEnum: - type: string - enum: - - batch.completed - - batch.failed - - batch.expired - - batch.cancelled - - response.completed - - response.failed - - response.cancelled - - response.incomplete - - eval.run.succeeded - - eval.run.failed - - eval.run.canceled - - fine_tuning.job.succeeded - - fine_tuning.job.failed - - fine_tuning.job.cancelled - - realtime.call.incoming - - video.completed - - video.failed - - safety.alert.created - PublicCreateEndpointBody: - properties: - name: - type: string - maxLength: 256 - minLength: 1 - description: A human-readable name for the webhook endpoint. - url: - type: string - maxLength: 2048 - pattern: ^https:// - description: The HTTPS URL that receives webhook deliveries. - event_types: - items: - $ref: '#/components/schemas/ProjectEventTypeEnum' - type: array - minItems: 1 - description: The event types that trigger deliveries to this endpoint. - type: object - required: - - name - - url - - event_types - WebhookEndpointWithSecretResource: - properties: - id: - type: string - description: The unique ID of the webhook endpoint. - object: - type: string - enum: - - webhook_endpoint - description: The object type, which is always webhook_endpoint. - default: webhook_endpoint - x-stainless-const: true - created_at: - type: integer - format: unixtime - description: The Unix timestamp when the endpoint was created. - updated_at: - type: integer - format: unixtime - description: The Unix timestamp of the last endpoint configuration or signing-secret change. Initialized at creation; tests and unchanged updates do not advance it. - name: - type: string - description: The human-readable name of the endpoint. - url: - type: string - description: The HTTPS URL that receives webhook deliveries. - event_types: - items: - type: string - type: array - description: The event types that trigger deliveries to this endpoint. - signing_secret_hint: - anyOf: - - type: string - description: A masked hint for the endpoint's signing secret. - - type: 'null' - signing_secret: - type: string - description: The endpoint's signing secret. This is returned only when the endpoint is created or the secret is rotated. - type: object - required: - - id - - object - - created_at - - name - - url - - event_types - - signing_secret_hint - - signing_secret - PublicUpdateEndpointBody: - properties: - name: - type: string - maxLength: 256 - minLength: 1 - description: A new human-readable name for the webhook endpoint. - url: - type: string - maxLength: 2048 - pattern: ^https:// - description: A new HTTPS URL that receives webhook deliveries. - event_types: - items: - $ref: '#/components/schemas/ProjectEventTypeEnum' - type: array - minItems: 1 - description: The complete set of event types that should trigger deliveries. - type: object - required: [] - DeletedWebhookEndpointResource: - properties: - id: - type: string - description: The ID of the deleted webhook endpoint. - object: - type: string - enum: - - webhook_endpoint.deleted - description: The object type, which is always webhook_endpoint.deleted. - default: webhook_endpoint.deleted - x-stainless-const: true - deleted: - type: boolean - description: Whether the endpoint was deleted. - type: object - required: - - id - - object - - deleted - PublicRotateSecretBody: - properties: - keep_old_secret_active_for_24_hours: - type: boolean - description: Whether to keep the previous signing secret valid for 24 hours after rotation. Defaults to false, which invalidates the previous secret immediately. - type: object - required: [] - PublicTestEndpointBody: - properties: - event_type: - $ref: '#/components/schemas/ProjectEventTypeEnum' - description: The event type to send as a sample delivery. - type: object - required: - - event_type - WebhookEndpointTestResultResource: - properties: - object: - type: string - enum: - - webhook_endpoint.test - description: The object type, which is always webhook_endpoint.test. - default: webhook_endpoint.test - x-stainless-const: true - webhook_endpoint_id: - type: string - description: The ID of the webhook endpoint that received the test. - event_type: - type: string - description: The event type sent in the test. - status_code: - type: integer - description: The HTTP status code returned by the endpoint. - success: - type: boolean - enum: - - true - description: Whether the test request completed. Always true for returned results; use status_code to determine the endpoint response. - default: true - x-stainless-const: true - type: object - required: - - object - - webhook_endpoint_id - - event_type - - status_code - - success - WebhookEventTypeListResource: - properties: - object: - type: string - enum: - - list - description: The object type, which is always list. - default: list - x-stainless-const: true - data: - items: - type: string - type: array - description: The webhook event types available to the authenticated project. - type: object - required: - - object - - data - DragPoint: - properties: - x: - type: integer - description: The x-coordinate. - y: - type: integer - description: The y-coordinate. - type: object - required: - - x - - y - title: Coordinate - description: 'An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.' - LiveSessionAudioFormatPCMParam: - description: Raw, mono 16-bit little-endian PCM audio for a Live WebSocket connection. - type: object - properties: - type: - description: The audio encoding. Always `audio/pcm`. - default: audio/pcm - x-stainless-const: true - type: string - enum: - - audio/pcm - rate: - description: Audio sample rate in hertz. Live WebSocket PCM audio supports 16000 or 24000 Hz. - type: integer - minimum: 16000 - maximum: 24000 - enum: - - 16000 - - 24000 - required: - - type - - rate - LiveSessionAudioFormatPCMUParam: - description: Raw, mono G.711 μ-law audio for a Live WebSocket connection. - type: object - properties: - type: - description: The audio encoding. Always `audio/pcmu`. - default: audio/pcmu - x-stainless-const: true - type: string - enum: - - audio/pcmu - rate: - description: Audio sample rate in hertz. G.711 audio uses 8000 Hz. - type: integer - minimum: 8000 - maximum: 8000 - required: - - type - - rate - LiveSessionAudioFormatPCMAParam: - description: Raw, mono G.711 A-law audio for a Live WebSocket connection. - type: object - properties: - type: - description: The audio encoding. Always `audio/pcma`. - default: audio/pcma - x-stainless-const: true - type: string - enum: - - audio/pcma - rate: - description: Audio sample rate in hertz. G.711 audio uses 8000 Hz. - type: integer - minimum: 8000 - maximum: 8000 - required: - - type - - rate - LiveAudioFormat: - description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveSessionAudioFormatPCMParam' - - $ref: '#/components/schemas/LiveSessionAudioFormatPCMUParam' - - $ref: '#/components/schemas/LiveSessionAudioFormatPCMAParam' - LiveInitialSessionAudioParam: - description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. - type: object - properties: - format: - description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. - $ref: '#/components/schemas/LiveAudioFormat' - output: - description: The voice used for speech generated by the Live model. - $ref: '#/components/schemas/LiveInitialSessionAudioOutputParam' - required: [] - LiveSessionCreateParams: - description: Initial configuration for a Live session, including its model, conversation instructions, audio, and delegated task handling. - type: object - properties: - model: - $ref: '#/components/schemas/ModelIdsLive' - instructions: - anyOf: - - description: Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup. - type: string - - type: 'null' - input: - description: Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total. - type: array - items: - $ref: '#/components/schemas/LiveInitialItem' - maxItems: 128 - audio: - description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. - $ref: '#/components/schemas/LiveInitialSessionAudioParam' - delegation: - anyOf: - - description: Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveClientDelegationParam' - - $ref: '#/components/schemas/LiveResponsesDelegationParam' - - type: 'null' - store: - description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. - type: boolean - client: - description: Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. - $ref: '#/components/schemas/LiveClientConfigParam' - required: - - model - LiveSessionStartEvent: - description: Start a Live session on a primary WebSocket. Send this event before other commands and wait for `session.started`. - example: - type: session.start - event_id: evt_start_001 - session: - model: gpt-live-1 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.start`. - default: session.start - x-stainless-const: true - type: string - enum: - - session.start - session: - description: Initial configuration for a primary WebSocket. Send session.start first and wait for session.started before application commands. WebRTC creation already starts the session; do not send this event again on its data channel. - $ref: '#/components/schemas/LiveSessionCreateParams' - required: - - type - - session - x-oaiMeta: - example: - type: session.start - event_id: evt_start_001 - session: - model: gpt-live-1 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client - LiveSessionUpdateParams: - description: Changes to an active Live session. Only delegation backend settings can be updated after startup. - type: object - properties: - delegation: - anyOf: - - description: Delegation settings to update. The delegation type must match the current session; omitted settings retain their values. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveClientDelegationParam' - - $ref: '#/components/schemas/LiveResponsesDelegationUpdateParam' - - type: 'null' - required: [] - LiveSessionUpdateParam: - description: Update the delegation settings of an active Live session. The server acknowledges accepted changes with `session.updated`. - example: - type: session.update - event_id: evt_update_001 - session: - delegation: - type: responses - responses: - instructions: Check restaurant availability. Ask before confirming a booking. - max_output_tokens: 1024 - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.update`. - default: session.update - x-stainless-const: true - type: string - enum: - - session.update - session: - description: Sparse delegation updates. Omitted settings retain their values. The delegation type cannot change, including resetting Responses delegation to null or client. Model, frontend instructions, audio, and startup input are immutable. - $ref: '#/components/schemas/LiveSessionUpdateParams' - required: - - type - - session - x-oaiMeta: - example: - type: session.update - event_id: evt_update_001 - session: - delegation: - type: responses - responses: - instructions: Check restaurant availability. Ask before confirming a booking. - max_output_tokens: 1024 - LiveInputAudioAppendEvent: - description: Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport. - example: - type: session.input_audio.append - audio: AACAAIAAAIAAAP9/AIAAgA== - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.input_audio.append`. - default: session.input_audio.append - x-stainless-const: true - type: string - enum: - - session.input_audio.append - audio: - description: Base64-encoded raw audio in the startup-selected format, without a WAV or other container header. Primary WebSocket only; media transports use their audio track. Audio appends have no acknowledgment. Reflected sideband server events reuse this event type and audio key, with no timestamps or event_id; their audio is always mono PCM16LE at 24 kHz. - type: string - minLength: 1 - required: - - type - - audio - x-oaiMeta: - example: - type: session.input_audio.append - audio: AACAAIAAAIAAAP9/AIAAgA== - LiveInputAudioMuteParam: - description: Mute audio input to the Live model without closing the session. The server acknowledges with `session.input_audio.muted`. - example: - type: session.input_audio.mute - event_id: evt_mute_001 - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.input_audio.mute`. - default: session.input_audio.mute - x-stainless-const: true - type: string - enum: - - session.input_audio.mute - required: - - type - x-oaiMeta: - example: - type: session.input_audio.mute - event_id: evt_mute_001 - LiveInputAudioUnmuteParam: - description: Resume audio input to a Live model after muting it. The server acknowledges with `session.input_audio.unmuted`. - example: - type: session.input_audio.unmute - event_id: evt_unmute_001 - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.input_audio.unmute`. - default: session.input_audio.unmute - x-stainless-const: true - type: string - enum: - - session.input_audio.unmute - required: - - type - x-oaiMeta: - example: - type: session.input_audio.unmute - event_id: evt_unmute_001 - LiveInstructionsAppendParam: - description: Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation. - example: - type: session.instructions.append - event_id: evt_instructions_001 - delegation_id: null - content: The caller prefers outdoor seating. - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.instructions.append`. - default: session.instructions.append - x-stainless-const: true - type: string - enum: - - session.instructions.append - delegation_id: - anyOf: - - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. - type: string - minLength: 1 - - type: 'null' - content: - description: Instruction text to append, limited to 500 tokens. This is a plain string, not an array of content parts. - type: string - required: - - type - - delegation_id - - content - x-oaiMeta: - example: - type: session.instructions.append - event_id: evt_instructions_001 - delegation_id: null - content: The caller prefers outdoor seating. - LiveThinkingAppendParam: - description: Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation. - example: - type: session.thinking.append - event_id: evt_thinking_001 - delegation_id: del_abc123 - content: Checking availability for two guests at 7 PM. - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.thinking.append`. - default: session.thinking.append - x-stainless-const: true - type: string - enum: - - session.thinking.append - delegation_id: - anyOf: - - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. - type: string - minLength: 1 - - type: 'null' - content: - description: Silent reasoning or progress context, limited to 500 tokens. It does not directly request speech, but can influence later speech and is not a secrecy boundary. - type: string - required: - - type - - delegation_id - - content - x-oaiMeta: - example: - type: session.thinking.append - event_id: evt_thinking_001 - delegation_id: del_abc123 - content: Checking availability for two guests at 7 PM. - LiveCommentaryAppendParam: - description: Provide context the Live model can communicate to the user, optionally for an existing client delegation. - example: - type: session.commentary.append - event_id: evt_commentary_001 - delegation_id: del_abc123 - content: There is an outdoor table for two at 7 PM. Ask whether to reserve it. - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.commentary.append`. - default: session.commentary.append - x-stainless-const: true - type: string - enum: - - session.commentary.append - delegation_id: - anyOf: - - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. - type: string - minLength: 1 - - type: 'null' - content: - description: Speakable context for the Live model, limited to 500 tokens. Use this for a result the model should communicate; use session.thinking.append for silent context. - type: string - required: - - type - - delegation_id - - content - x-oaiMeta: - example: - type: session.commentary.append - event_id: evt_commentary_001 - delegation_id: del_abc123 - content: There is an outdoor table for two at 7 PM. Ask whether to reserve it. - LiveResponseItemCreateParam: - description: Add an input item to the Live session’s Responses backend. Requires Responses delegation; use `response.create` to request a response. - example: - type: response.item.create - event_id: evt_item_001 - item: - type: message - role: user - content: - - type: input_text - text: Please check for a table for two at 7 PM. - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `response.item.create`. - default: response.item.create - x-stainless-const: true - type: string - enum: - - response.item.create - item: - description: An input item to append to the Responses backend conversation, such as a user message or a function tool result. - $ref: '#/components/schemas/InputItem' - required: - - type - - item - x-oaiMeta: - example: - type: response.item.create - event_id: evt_item_001 - item: - type: message - role: user - content: - - type: input_text - text: Please check for a table for two at 7 PM. - LiveResponseCreateParam: - description: Request a response from the Live session’s Responses backend, or continue a delegated response waiting for tool results. Requires Responses delegation. - example: - type: response.create - event_id: evt_response_001 - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `response.create`. - default: response.create - x-stainless-const: true - type: string - enum: - - response.create - required: - - type - x-oaiMeta: - example: - type: response.create - event_id: evt_response_001 - LiveSessionCloseParam: - description: Request that the Live session close. The terminal `session.closed` event contains the close reason and final usage. - example: - type: session.close - event_id: evt_close_001 - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.close`. - default: session.close - x-stainless-const: true - type: string - enum: - - session.close - required: - - type - x-oaiMeta: - example: - type: session.close - event_id: evt_close_001 - LiveForkAudioParam: - description: Audio format for the new WebSocket connection to a forked Live session. The stored voice is preserved. - type: object - properties: - format: - description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. - $ref: '#/components/schemas/LiveAudioFormat' - required: [] - LiveForkSessionConfigParam: - description: Overrides for a stored session after connecting to the fork WebSocket. An empty object inherits the stored configuration; do not supply a new model. audio.format applies only to the new WebSocket connection. client overrides are only supported for WebRTC forks. - type: object - properties: - audio: - description: Audio format for a WebSocket fork. WebRTC forks negotiate their audio format and must omit this field. - $ref: '#/components/schemas/LiveForkAudioParam' - delegation: - description: Overrides for the stored session’s Responses backend. Only supported when the stored session already uses Responses delegation; the delegation type cannot change. - $ref: '#/components/schemas/LiveResponsesDelegationUpdateParam' - store: - description: Whether to store the forked session. Omission inherits the stored session's setting. - type: boolean - client: - description: Frontend data-channel permissions for a WebRTC fork. Omitted permissions inherit the stored values. Not supported for WebSocket forks. - $ref: '#/components/schemas/LiveClientConfigParam' - required: [] - LiveForkSessionStartEvent: - description: Start a Live session after connecting to a stored session’s fork WebSocket. Send an empty `session` object to use the stored configuration. - example: - type: session.start - session: {} - type: object - properties: - event_id: - anyOf: - - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. - type: string - maxLength: 512 - - type: 'null' - type: - description: The Live client event type. Always `session.start`. - default: session.start - x-stainless-const: true - type: string - enum: - - session.start - session: - description: Overrides for a stored session after connecting to the fork WebSocket. An empty object inherits the stored configuration; do not supply a new model. audio.format applies only to the new WebSocket connection. client overrides are only supported for WebRTC forks. - $ref: '#/components/schemas/LiveForkSessionConfigParam' - required: - - type - - session - x-oaiMeta: - example: - type: session.start - session: {} - LiveSessionResourceParam: - description: The resolved Live session configuration and server-assigned session metadata. - type: object - properties: - model: - $ref: '#/components/schemas/ModelIdsLive' - instructions: - anyOf: - - description: Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup. - type: string - - type: 'null' - input: - description: Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total. - type: array - items: - $ref: '#/components/schemas/LiveInitialItem' - maxItems: 128 - audio: - description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. - $ref: '#/components/schemas/LiveInitialSessionAudioParam' - delegation: - anyOf: - - description: Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveClientDelegationParam' - - $ref: '#/components/schemas/LiveResponsesDelegationParam' - - type: 'null' - store: - description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. - type: boolean - client: - description: Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. - $ref: '#/components/schemas/LiveClientConfigParam' - id: - description: The unique ID of the Live session. Use this ID for sideband connections, forking, and recording download. - type: string - expires_at: - description: The Unix timestamp, in seconds, at which the Live session expires. - type: integer - status: - description: The status of the session snapshot. Always `active`, including the final snapshot in session.closed; use the event type to determine that the session has closed. - default: active - x-stainless-const: true - type: string - enum: - - active - required: - - model - - id - - expires_at - - status - LiveSessionStarted: - description: Returned when a Live session has started. Contains the resolved session configuration, including server defaults. - example: - type: session.started - event_id: evt_started_001 - client_event_id: evt_start_001 - session: - id: live_abc123 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client - type: object - properties: - type: - description: The event type, always `session.started`. - default: session.started - x-stainless-const: true - type: string - enum: - - session.started - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - session: - $ref: '#/components/schemas/LiveSessionResourceParam' - required: - - type - - event_id - - session - x-oaiMeta: - example: - type: session.started - event_id: evt_started_001 - client_event_id: evt_start_001 - session: - id: live_abc123 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client - LiveSessionUpdated: - description: Returned when a Live session update is accepted. Contains the resolved session configuration after the update. - example: - type: session.updated - event_id: evt_updated_001 - client_event_id: evt_update_001 - session: - id: live_def456 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: responses - responses: - model: gpt-6-astra - instructions: Check restaurant availability. Ask before confirming a booking. - max_output_tokens: 1024 - tools: [] - type: object - properties: - type: - description: The event type, always `session.updated`. - default: session.updated - x-stainless-const: true - type: string - enum: - - session.updated - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - session: - $ref: '#/components/schemas/LiveSessionResourceParam' - required: - - type - - event_id - - session - x-oaiMeta: - example: - type: session.updated - event_id: evt_updated_001 - client_event_id: evt_update_001 - session: - id: live_def456 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: responses - responses: - model: gpt-6-astra - instructions: Check restaurant availability. Ask before confirming a booking. - max_output_tokens: 1024 - tools: [] - LiveInputAudioMuted: - description: Returned when a session.input_audio.mute command is accepted. Input audio is no longer sent to the model; sideband audio reflection continues. - example: - type: session.input_audio.muted - event_id: evt_muted_001 - client_event_id: evt_mute_001 - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - description: The event type, always `session.input_audio.muted`. - default: session.input_audio.muted - x-stainless-const: true - type: string - enum: - - session.input_audio.muted - required: - - event_id - - type - x-oaiMeta: - example: - type: session.input_audio.muted - event_id: evt_muted_001 - client_event_id: evt_mute_001 - LiveInputAudioUnmuted: - description: Returned when a session.input_audio.unmute command is accepted. Input audio is sent to the model again. - example: - type: session.input_audio.unmuted - event_id: evt_unmuted_001 - client_event_id: evt_unmute_001 - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - description: The event type, always `session.input_audio.unmuted`. - default: session.input_audio.unmuted - x-stainless-const: true - type: string - enum: - - session.input_audio.unmuted - required: - - event_id - - type - x-oaiMeta: - example: - type: session.input_audio.unmuted - event_id: evt_unmuted_001 - client_event_id: evt_unmute_001 - LiveInstructionsAppended: - description: Returned when a session.instructions.append command is accepted into the Live session timeline. Acknowledges the appended instructions without guaranteeing that the model has acted on them. - example: - type: session.instructions.appended - event_id: evt_instructions_002 - client_event_id: evt_instructions_001 - start_ms: 1200 - end_ms: 1400 - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - start_ms: - description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - type: integer - end_ms: - description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - type: integer - type: - description: The event type, always `session.instructions.appended`. - default: session.instructions.appended - x-stainless-const: true - type: string - enum: - - session.instructions.appended - required: - - event_id - - start_ms - - end_ms - - type - x-oaiMeta: - example: - type: session.instructions.appended - event_id: evt_instructions_002 - client_event_id: evt_instructions_001 - start_ms: 1200 - end_ms: 1400 - LiveThinkingAppended: - description: Returned when a session.thinking.append command is accepted into the Live session timeline. Acknowledges the added reasoning context without guaranteeing any spoken output. - example: - type: session.thinking.appended - event_id: evt_thinking_002 - client_event_id: evt_thinking_001 - start_ms: 4600 - end_ms: 4800 - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - start_ms: - description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - type: integer - end_ms: - description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - type: integer - type: - description: The event type, always `session.thinking.appended`. - default: session.thinking.appended - x-stainless-const: true - type: string - enum: - - session.thinking.appended - required: - - event_id - - start_ms - - end_ms - - type - x-oaiMeta: - example: - type: session.thinking.appended - event_id: evt_thinking_002 - client_event_id: evt_thinking_001 - start_ms: 4600 - end_ms: 4800 - LiveCommentaryAppended: - description: Returned when a session.commentary.append command is accepted into the Live session timeline. Acknowledges the added commentary without guaranteeing exact wording or completed audio playback. - example: - type: session.commentary.appended - event_id: evt_commentary_002 - client_event_id: evt_commentary_001 - start_ms: 5200 - end_ms: 5400 - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - start_ms: - description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - type: integer - end_ms: - description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - type: integer - type: - description: The event type, always `session.commentary.appended`. - default: session.commentary.appended - x-stainless-const: true - type: string - enum: - - session.commentary.appended - required: - - event_id - - start_ms - - end_ms - - type - x-oaiMeta: - example: - type: session.commentary.appended - event_id: evt_commentary_002 - client_event_id: evt_commentary_001 - start_ms: 5200 - end_ms: 5400 - LiveInputAudioAppend: - description: Input audio received from the primary transport and reflected to a Live sideband connection before model-input muting. - example: - type: session.input_audio.append - audio: AACAAIAAAIAAAP9/AIAAgA== - type: object - properties: - type: - description: The event type, always `session.input_audio.append`. - default: session.input_audio.append - x-stainless-const: true - type: string - enum: - - session.input_audio.append - audio: - description: Base64-encoded raw mono PCM16LE at 24 kHz received from the primary transport, reflected to the sideband before model-input muting. This server event uses the same audio key as the client command, but is not an acknowledgment of it. - type: string - required: - - type - - audio - x-oaiMeta: - example: - type: session.input_audio.append - audio: AACAAIAAAIAAAP9/AIAAgA== - LiveOutputAudioDelta: - description: An audio chunk generated by the Live model. Decode and play primary WebSocket chunks in delivery order using the configured session audio format. Sideband connections receive reflected output audio with timestamps. - example: - type: session.output_audio.delta - delta: AACAAIAAAIAAAP9/AIAAgA== - start_ms: 1000 - end_ms: 1200 - type: object - properties: - type: - description: The event type, always `session.output_audio.delta`. - default: session.output_audio.delta - x-stainless-const: true - type: string - enum: - - session.output_audio.delta - delta: - description: Base64-encoded raw audio. Primary WebSocket events use the session's configured format; reflected sideband events use mono PCM16LE at 24 kHz. - type: string - start_ms: - description: Inclusive session-relative start in milliseconds. Required on reflected sideband events; omitted on the primary WebSocket. - type: integer - end_ms: - description: Exclusive session-relative end in milliseconds. Required on reflected sideband events; omitted on the primary WebSocket. Dropped output frames leave gaps between reflected ranges. - type: integer - required: - - type - - delta - x-oaiMeta: - example: - type: session.output_audio.delta - delta: AACAAIAAAIAAAP9/AIAAgA== - start_ms: 1000 - end_ms: 1200 - LiveInputTranscriptDelta: - description: A transcript fragment for user input audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event. - example: - type: session.input_transcript.delta - event_id: evt_input_transcript_001 - delta: A table for two at seven, please. - start_ms: 1600 - end_ms: 3400 - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - start_ms: - description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - type: integer - end_ms: - description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - type: integer - delta: - description: The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript. - type: string - type: - description: The event type, always `session.input_transcript.delta`. - default: session.input_transcript.delta - x-stainless-const: true - type: string - enum: - - session.input_transcript.delta - required: - - event_id - - start_ms - - end_ms - - delta - - type - x-oaiMeta: - example: - type: session.input_transcript.delta - event_id: evt_input_transcript_001 - delta: A table for two at seven, please. - start_ms: 1600 - end_ms: 3400 - LiveOutputTranscriptDelta: - description: A transcript fragment for assistant output audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event. - example: - type: session.output_transcript.delta - event_id: evt_output_transcript_001 - delta: Would you like me to reserve that table? - start_ms: 5400 - end_ms: 7200 - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - start_ms: - description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. - type: integer - end_ms: - description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. - type: integer - delta: - description: The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript. - type: string - type: - description: The event type, always `session.output_transcript.delta`. - default: session.output_transcript.delta - x-stainless-const: true - type: string - enum: - - session.output_transcript.delta - required: - - event_id - - start_ms - - end_ms - - delta - - type - x-oaiMeta: - example: - type: session.output_transcript.delta - event_id: evt_output_transcript_001 - delta: Would you like me to reserve that table? - start_ms: 5400 - end_ms: 7200 - LiveDelegationItem: - description: Metadata for work delegated by the Live model. Client delegations are handled by your application; Responses delegations run on the configured backend. - type: object - properties: - id: - description: The unique ID of the delegation. Use this as delegation_id when replying to client-owned work or correlating Responses events. - type: string - type: - description: The object type, always `delegation`. - default: delegation - x-stainless-const: true - type: string - enum: - - delegation - target: - description: 'Where the Live model delegated the work: `client` for your application, or `responses` for the configured Responses backend.' - anyOf: - - default: client - x-stainless-const: true - type: string - enum: - - client - - default: responses - x-stainless-const: true - type: string - enum: - - responses - response_id: - description: The ID of the Responses API response associated with a Responses delegation. Omitted for client delegations. - type: string - required: - - id - - type - - target - LiveDelegationCreated: - description: Returned when the Live model delegates work to your application or a Responses backend. Contains delegation metadata and the position on the session timeline where the work was delegated. - example: - type: session.delegation.created - event_id: evt_delegation_001 - offset_ms: 3600 - delegation: - id: del_abc123 - type: delegation - target: client - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - description: The event type, always `session.delegation.created`. - default: session.delegation.created - x-stainless-const: true - type: string - enum: - - session.delegation.created - offset_ms: - description: The position on the Live session timeline where the delegation was created, in milliseconds from the beginning of the session. - type: integer - delegation: - description: The delegated work identifier and destination. This object contains metadata, not the task text. - $ref: '#/components/schemas/LiveDelegationItem' - required: - - event_id - - type - - offset_ms - - delegation - x-oaiMeta: - example: - type: session.delegation.created - event_id: evt_delegation_001 - offset_ms: 3600 - delegation: - id: del_abc123 - type: delegation - target: client - LiveResponseEvent: - description: A streaming Responses API event from a backend delegated to by the Live session. Use the outer delegation_id to associate the nested stream with its Live delegation. - example: - type: response.event - event_id: evt_response_002 - delegation_id: del_responses123 - event: - type: response.output_text.delta - item_id: msg_abc123 - output_index: 0 - content_index: 0 - delta: An outdoor table is available at 7 PM. - sequence_number: 3 - logprobs: [] - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - description: The event type, always `response.event`. - default: response.event - x-stainless-const: true - type: string - enum: - - response.event - delegation_id: - anyOf: - - description: The Live delegation associated with the nested Responses event. May be null or omitted when the event cannot be correlated with a delegation. - type: string - - type: 'null' - event: - description: The nested Responses streaming event. Dispatch on its type field. Response lifecycle snapshots omit input and clear instructions, tools, and output to keep messages small; consume granular output events for the generated content. - type: object - additionalProperties: {} - required: - - event_id - - type - - event - x-oaiMeta: - example: - type: response.event - event_id: evt_response_002 - delegation_id: del_responses123 - event: - type: response.output_text.delta - item_id: msg_abc123 - output_index: 0 - content_index: 0 - delta: An outdoor table is available at 7 PM. - sequence_number: 3 - logprobs: [] - LiveSessionUsage: - description: Cumulative audio duration for a Live session. Values are totals for the session, not increments to sum across usage events. - type: object - properties: - seconds: - description: The cumulative Live audio duration in seconds. Do not sum this value across usage events. - type: number - required: - - seconds - LiveContextWindowUsage: - description: The latest measured context-window usage of the Live model. This is separate from billing usage and delegated Responses token usage. - type: object - properties: - usage_ratio: - description: The latest active context token count divided by the Live model context limit. Can decrease after compaction and may lag between measured audio frames. - type: number - required: - - usage_ratio - LiveSessionUsageUpdated: - description: Reports cumulative Live audio usage and, when available, the most recent context-window usage. Delegated Responses token usage is reported separately in response.event events. - example: - type: session.usage.updated - event_id: evt_usage_001 - usage: - seconds: 32.5 - context_window: - usage_ratio: 0.12 - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - description: The event type, always `session.usage.updated`. - default: session.usage.updated - x-stainless-const: true - type: string - enum: - - session.usage.updated - usage: - description: The cumulative Live audio usage so far. - $ref: '#/components/schemas/LiveSessionUsage' - context_window: - description: The latest measured Live context-window usage. Omitted when the context limit is unknown. - $ref: '#/components/schemas/LiveContextWindowUsage' - required: - - event_id - - type - - usage - x-oaiMeta: - example: - type: session.usage.updated - event_id: evt_usage_001 - usage: - seconds: 32.5 - context_window: - usage_ratio: 0.12 - LiveSessionClosed: - description: Returned after the Live session finishes finalizing, with the close reason, final session snapshot, and cumulative audio usage. A connection closing without this event does not confirm successful finalization. - example: - type: session.closed - event_id: evt_closed_001 - client_event_id: evt_close_001 - reason: close_requested - session: - id: live_abc123 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client - usage: - seconds: 45.8 - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - description: The event type, always `session.closed`. - default: session.closed - x-stainless-const: true - type: string - enum: - - session.closed - reason: - description: 'Why the Live session ended: `close_requested` for an application close or hangup request, `expired` for the session duration limit, `content` for a safety filter, `remote_hangup` for a graceful remote disconnect, or `connection_lost` for an unexpected primary or upstream disconnection.' - anyOf: - - default: close_requested - x-stainless-const: true - type: string - enum: - - close_requested - - default: expired - x-stainless-const: true - type: string - enum: - - expired - - default: content - x-stainless-const: true - type: string - enum: - - content - - default: remote_hangup - x-stainless-const: true - type: string - enum: - - remote_hangup - - default: connection_lost - x-stainless-const: true - type: string - enum: - - connection_lost - session: - $ref: '#/components/schemas/LiveSessionResourceParam' - usage: - description: The final cumulative Live audio usage after session finalization. - $ref: '#/components/schemas/LiveSessionUsage' - required: - - event_id - - type - - reason - - session - - usage - x-oaiMeta: - example: - type: session.closed - event_id: evt_closed_001 - client_event_id: evt_close_001 - reason: close_requested - session: - id: live_abc123 - model: gpt-live-1 - status: active - expires_at: 1788555600 - instructions: Help the caller plan a restaurant reservation. Confirm details before booking. - input: [] - audio: - format: - type: audio/pcm - rate: 24000 - output: - voice: marin - delegation: - type: client - usage: - seconds: 45.8 - LiveLiveError: - description: Details of an error encountered by the Live session, including the affected parameter or client command when available. - type: object - properties: - type: - description: The category of error, such as `invalid_request_error` for an invalid Live client command. - type: string - code: - description: A machine-readable code identifying the Live error, such as `unknown_parameter`. - type: string - message: - description: A human-readable explanation of the Live error. - type: string - param: - description: The parameter that caused the error, when applicable, such as `session.voice`. - type: string - client_event_id: - description: The event_id of the client command that caused the error, when supplied. - type: string - required: - - type - - code - - message - LiveErrorEvent: - description: Reports an error in the Live session, such as an invalid client command. Use error.client_event_id, when present, to identify the command that caused the error. - example: - type: error - event_id: evt_error_001 - error: - type: invalid_request_error - code: unknown_parameter - message: 'Unknown parameter: ''session.voice''.' - param: session.voice - client_event_id: evt_invalid_001 - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - description: The event type, always `error`. - default: error - x-stainless-const: true - type: string - enum: - - error - error: - description: Details of the Live error and the client command that caused it, when known. - $ref: '#/components/schemas/LiveLiveError' - required: - - event_id - - type - - error - x-oaiMeta: - example: - type: error - event_id: evt_error_001 - error: - type: invalid_request_error - code: unknown_parameter - message: 'Unknown parameter: ''session.voice''.' - param: session.voice - client_event_id: evt_invalid_001 - LiveInfoEvent: - description: An informational notice about the Live session, such as the event permissions applied to a frontend data channel. - example: - type: info - event_id: evt_info_001 - code: data_channel_permissions - message: The frontend data channel is configured with restricted event permissions. - type: object - properties: - event_id: - description: The unique ID of the Live server event. - type: string - client_event_id: - description: The event_id of the client command associated with this server event, when supplied. - type: string - type: - description: The event type, always `info`. - default: info - x-stainless-const: true - type: string - enum: - - info - code: - description: A machine-readable code for the notice, such as `data_channel_permissions`. - type: string - message: - description: A human-readable explanation of the Live session notice. - type: string - required: - - event_id - - type - - code - - message - x-oaiMeta: - example: - type: info - event_id: evt_info_001 - code: data_channel_permissions - message: The frontend data channel is configured with restricted event permissions. - LiveTransportDTMFReceived: - description: A SIP DTMF keypress received from the caller. Delivered only to sideband observers. - example: - type: transport.dtmf.received - event_id: event_dtmf_1 - event: '5' - type: object - properties: - type: - default: transport.dtmf.received - x-stainless-const: true - type: string - enum: - - transport.dtmf.received - event_id: - type: string - event: - type: string - minLength: 1 - maxLength: 1 - pattern: ^[0-9A-D*#]$ - required: - - type - - event_id - - event - x-oaiMeta: - example: - type: transport.dtmf.received - event_id: event_dtmf_1 - event: '5' - LiveTransportDTMFSend: - description: A SIP DTMF keypress successfully sent by the hosted tool. Delivered only to sideband observers; this is not a client command. - example: - type: transport.dtmf.send - event_id: event_dtmf_2 - event: '#' - type: object - properties: - type: - default: transport.dtmf.send - x-stainless-const: true - type: string - enum: - - transport.dtmf.send - event_id: - type: string - event: - type: string - minLength: 1 - maxLength: 1 - pattern: ^[0-9A-D*#]$ - required: - - type - - event_id - - event - x-oaiMeta: - example: - type: transport.dtmf.send - event_id: event_dtmf_2 - event: '#' - LiveTransportRinging: - description: The outbound SIP provider leg is ringing or providing early media. Delivered only to sideband observers. - example: - type: transport.ringing - event_id: event_call_1 - session_id: live_u0_123 - type: object - properties: - event_id: - type: string - session_id: - description: The canonical Live session ID. - type: string - type: - default: transport.ringing - x-stainless-const: true - type: string - enum: - - transport.ringing - required: - - event_id - - session_id - - type - x-oaiMeta: - example: - type: transport.ringing - event_id: event_call_1 - session_id: live_u0_123 - LiveTransportAnswered: - description: The outbound SIP provider leg answered and media is established. Delivered only to sideband observers. - example: - type: transport.answered - event_id: event_call_2 - session_id: live_u0_123 - type: object - properties: - event_id: - type: string - session_id: - description: The canonical Live session ID. - type: string - type: - default: transport.answered - x-stainless-const: true - type: string - enum: - - transport.answered - required: - - event_id - - session_id - - type - x-oaiMeta: - example: - type: transport.answered - event_id: event_call_2 - session_id: live_u0_123 - LiveTransportCallError: - type: object - properties: - type: - default: call_error - x-stainless-const: true - type: string - enum: - - call_error - code: - description: The call setup failure code. - type: string - message: - type: string - param: - description: The parameter related to the error, if any. Empty when no parameter applies. - type: string - required: - - type - - code - - message - LiveTransportFailed: - description: An asynchronous outbound SIP setup failure. Delivered only to sideband observers. - example: - type: transport.failed - event_id: event_call_4 - session_id: live_u0_123 - error: - type: call_error - code: provider_invite_failed - message: provider rejected the call - param: '' - type: object - properties: - event_id: - type: string - session_id: - description: The canonical Live session ID. - type: string - type: - default: transport.failed - x-stainless-const: true - type: string - enum: - - transport.failed - error: - $ref: '#/components/schemas/LiveTransportCallError' - required: - - event_id - - session_id - - type - - error - x-oaiMeta: - example: - type: transport.failed - event_id: event_call_4 - session_id: live_u0_123 - error: - type: call_error - code: provider_invite_failed - message: provider rejected the call - param: '' - LiveServerEvent-2: - description: An event sent by the Live API on a primary WebSocket or sideband connection. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/LiveSessionStarted' - - $ref: '#/components/schemas/LiveSessionUpdated' - - $ref: '#/components/schemas/LiveInputAudioMuted' - - $ref: '#/components/schemas/LiveInputAudioUnmuted' - - $ref: '#/components/schemas/LiveInstructionsAppended' - - $ref: '#/components/schemas/LiveThinkingAppended' - - $ref: '#/components/schemas/LiveCommentaryAppended' - - $ref: '#/components/schemas/LiveInputAudioAppend' - - $ref: '#/components/schemas/LiveOutputAudioDelta' - - $ref: '#/components/schemas/LiveInputTranscriptDelta' - - $ref: '#/components/schemas/LiveOutputTranscriptDelta' - - $ref: '#/components/schemas/LiveDelegationCreated' - - $ref: '#/components/schemas/LiveResponseEvent' - - $ref: '#/components/schemas/LiveSessionUsageUpdated' - - $ref: '#/components/schemas/LiveSessionClosed' - - $ref: '#/components/schemas/LiveErrorEvent' - - $ref: '#/components/schemas/LiveInfoEvent' - - $ref: '#/components/schemas/LiveTransportDTMFReceived' - - $ref: '#/components/schemas/LiveTransportDTMFSend' - - $ref: '#/components/schemas/LiveTransportRinging' - - $ref: '#/components/schemas/LiveTransportAnswered' - - $ref: '#/components/schemas/LiveTransportFailed' - UserMessageItemParam: - properties: - id: - anyOf: - - type: string - description: The unique ID of this message item. - example: msg_123 - - type: 'null' - type: - type: string - enum: - - message - description: The item type. Always `message`. - default: message - x-stainless-const: true - role: - type: string - enum: - - user - description: The message role. Always `user`. - default: user - x-stainless-const: true - content: - description: The message content, as an array of content parts. - anyOf: - - items: - $ref: '#/components/schemas/ResponseSteerInputContent' - description: A piece of message content, such as text, an image, or a file. - type: array - - type: string - maxLength: 10485760 - description: The message content, as a single string. - status: - anyOf: - - type: string - description: The status of the message item. - - type: 'null' - type: object - required: - - type - - role - - content - ErrorPayload: - properties: - type: - type: string - description: The error type that was emitted. - code: - anyOf: - - type: string - description: The error code that was emitted, if any. - - type: 'null' - message: - type: string - description: The human-readable error message that was emitted. - param: - anyOf: - - type: string - description: The parameter name that was associated with the error, if any. - - type: 'null' - headers: - additionalProperties: - type: string - description: The header value that was emitted. - type: object - description: The response headers that were emitted with the error, if any. - x-oaiTypeLabel: map - misalignment: - $ref: '#/components/schemas/MisalignmentErrorDetailsResource' - type: object - required: - - type - - code - - message - - param - title: Error payload - description: An error payload that was emitted for a streaming error event. - BetaTokenCountsResource: - properties: - object: - type: string - enum: - - response.input_tokens - default: response.input_tokens - x-stainless-const: true - input_tokens: - type: integer - type: object - required: - - object - - input_tokens - title: Token counts - example: - object: response.input_tokens - input_tokens: 123 - BetaTokenCountsBody: - properties: - model: - anyOf: - - type: string - description: Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models. - - type: 'null' - input: - anyOf: - - description: Text, image, or file inputs to the model, used to generate a response - anyOf: - - type: string - maxLength: 10485760 - description: A text input to the model, equivalent to a text input with the `user` role. - - items: - $ref: '#/components/schemas/BetaInputItem' - type: array - maxItems: 131072 - description: A list of one or many input items to the model, containing different content types. - - type: 'null' - previous_response_id: - anyOf: - - type: string - description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - example: resp_123 - - type: 'null' - tools: - anyOf: - - items: - $ref: '#/components/schemas/BetaTool' - type: array - description: 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. - - type: 'null' - text: - anyOf: - - $ref: '#/components/schemas/BetaResponseTextParam' - - type: 'null' - reasoning: - anyOf: - - $ref: '#/components/schemas/BetaReasoning' - description: '**gpt-5 and o-series models only** Configuration options for [reasoning models](https://developers.openai.com/api/docs/guides/reasoning).' - - type: 'null' - truncation: - $ref: '#/components/schemas/BetaTruncationEnum' - description: 'The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.' - deprecated: true - instructions: - anyOf: - - type: string - description: |- - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - - type: 'null' - personality: - $ref: '#/components/schemas/BetaPersonalityEnum' - description: A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. - conversation: - anyOf: - - $ref: '#/components/schemas/BetaConversationParam' - - type: 'null' - tool_choice: - anyOf: - - $ref: '#/components/schemas/BetaToolChoiceParam' - description: Controls which tool the model should use, if any. - - type: 'null' - parallel_tool_calls: - anyOf: - - type: boolean - description: Whether to allow the model to run tool calls in parallel. - - type: 'null' - type: object - required: [] - BetaToolChoiceParam: - description: | - 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. - anyOf: - - $ref: '#/components/schemas/BetaToolChoiceOptions' - - $ref: '#/components/schemas/BetaToolChoiceAllowed' - - $ref: '#/components/schemas/BetaToolChoiceTypes' - - $ref: '#/components/schemas/BetaToolChoiceFunction' - - $ref: '#/components/schemas/BetaToolChoiceMCP' - - $ref: '#/components/schemas/BetaToolChoiceCustom' - - $ref: '#/components/schemas/BetaSpecificProgrammaticToolCallingParam' - - $ref: '#/components/schemas/BetaSpecificApplyPatchParam' - - $ref: '#/components/schemas/BetaSpecificFunctionShellParam' - BetaSpecificFunctionShellParam: - properties: - type: - type: string - enum: - - shell - description: The tool to call. Always `shell`. - default: shell - x-stainless-const: true - type: object - required: - - type - title: Specific shell tool choice - description: Forces the model to call the shell tool when a tool call is required. - BetaSpecificApplyPatchParam: - properties: - type: - type: string - enum: - - apply_patch - description: The tool to call. Always `apply_patch`. - default: apply_patch - x-stainless-const: true - type: object - required: - - type - title: Specific apply patch tool choice - description: Forces the model to call the apply_patch tool when executing a tool call. - BetaSpecificProgrammaticToolCallingParam: - properties: - type: - type: string - enum: - - programmatic_tool_calling - description: The tool to call. Always `programmatic_tool_calling`. - default: programmatic_tool_calling - x-stainless-const: true - type: object - required: - - type - BetaToolChoiceCustom: - type: object - title: Custom tool - description: | - Use this option to force the model to call a specific custom tool. - properties: - type: - type: string - enum: - - custom - description: For custom tool calling, the type is always `custom`. - x-stainless-const: true - name: - type: string - description: The name of the custom tool to call. - required: - - type - - name - BetaToolChoiceMCP: - type: object - title: MCP tool - description: | - Use this option to force the model to call a specific tool on a remote MCP server. - properties: - type: - type: string - enum: - - mcp - description: For MCP tools, the type is always `mcp`. - x-stainless-const: true - server_label: - type: string - description: | - The label of the MCP server to use. - name: - anyOf: - - type: string - description: | - The name of the tool to call on the server. - - type: 'null' - required: - - type - - server_label - BetaToolChoiceFunction: - type: object - title: Function tool - description: | - Use this option to force the model to call a specific function. - properties: - type: - type: string - enum: - - function - description: For function calling, the type is always `function`. - x-stainless-const: true - name: - type: string - description: The name of the function to call. - required: - - type - - name - BetaToolChoiceTypes: - type: object - title: Hosted tool - description: | - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](https://developers.openai.com/api/docs/guides/tools). - properties: - type: - type: string - description: | - The type of hosted tool the model should to use. Learn more about - [built-in tools](https://developers.openai.com/api/docs/guides/tools). - - Allowed values are: - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` - enum: - - file_search - - web_search_preview - - computer - - computer_use_preview - - computer_use - - web_search_preview_2025_03_11 - - image_generation - - code_interpreter - required: - - type - BetaToolChoiceAllowed: - type: object - title: Allowed tools - description: | - Constrains the tools available to the model to a pre-defined set. - properties: - type: - type: string - enum: - - allowed_tools - description: Allowed tool configuration type. Always `allowed_tools`. - x-stainless-const: true - mode: - type: string - enum: - - auto - - required - description: | - Constrains the tools available to the model to a pre-defined set. - - `auto` allows the model to pick from among the allowed tools and generate a - message. - - `required` requires the model to call one or more of the allowed tools. - tools: - type: array - description: | - A list of tool definitions that the model should be allowed to call. - - For the Responses API, the list of tool definitions might look like: - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` - items: - type: object - description: | - A tool definition that the model should be allowed to call. - additionalProperties: true - x-oaiExpandable: false - required: - - type - - mode - - tools - BetaToolChoiceOptions: - type: string - title: Tool choice mode - description: | - 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. - enum: - - none - - auto - - required - BetaConversationParam: - description: | - 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. - anyOf: - - type: string - title: Conversation ID - description: | - The unique ID of the conversation. - - $ref: '#/components/schemas/BetaConversationParam-2' - BetaConversationParam-2: - properties: - id: - type: string - description: The unique ID of the conversation. - example: conv_123 - type: object - required: - - id - title: Conversation object - description: The conversation that this response belongs to. - BetaPersonalityEnum: - anyOf: - - type: string - - type: string - enum: - - friendly - - pragmatic - BetaTruncationEnum: - type: string - enum: - - auto - - disabled - BetaReasoning: - type: object - description: | - Configuration options for - [reasoning models](https://developers.openai.com/api/docs/guides/reasoning). - title: Reasoning - properties: - mode: - $ref: '#/components/schemas/BetaReasoningModeEnum' - description: | - Controls the reasoning execution mode for the request. - - When returned on a response, this is the effective execution mode. - effort: - $ref: '#/components/schemas/BetaReasoningEffort' - summary: - anyOf: - - type: string - description: | - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. - - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - enum: - - auto - - concise - - detailed - - type: 'null' - context: - anyOf: - - type: string - description: | - Controls which reasoning items are rendered back to the model on later turns. - If omitted or set to `auto`, the model determines the context mode. The - `gpt-5.6` model family defaults to `all_turns`; earlier models default to - `current_turn`. - - When returned on a response, this is the effective reasoning context mode - used for the response. - enum: - - auto - - current_turn - - all_turns - - type: 'null' - generate_summary: - anyOf: - - type: string - deprecated: true - description: | - **Deprecated:** use `summary` instead. - - A summary of the reasoning performed by the model. This can be - useful for debugging and understanding the model's reasoning process. - One of `auto`, `concise`, or `detailed`. - enum: - - auto - - concise - - detailed - - type: 'null' - BetaReasoningEffort: - anyOf: - - type: string - enum: - - none - - minimal - - low - - medium - - high - - xhigh - - max - default: medium - description: | - Constrains effort on reasoning for reasoning models. Currently supported - values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. - Reducing reasoning effort can result in faster responses and fewer tokens - used on reasoning in a response. Not all reasoning models support every - value. See the - [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) - for model-specific support. - - type: 'null' - BetaReasoningModeEnum: - anyOf: - - type: string - - type: string - enum: - - standard - - pro - BetaResponseTextParam: - type: object - description: | - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: - - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) - - [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) - properties: - format: - $ref: '#/components/schemas/BetaTextResponseFormatConfiguration' - verbosity: - $ref: '#/components/schemas/BetaVerbosity' - BetaVerbosity: - anyOf: - - type: string - enum: - - low - - medium - - high - default: medium - description: | - Constrains the verbosity of the model's response. Lower values will result in - more concise responses, while higher values will result in more verbose responses. - Currently supported values are `low`, `medium`, and `high`. The default is - `medium`. - - type: 'null' - BetaTextResponseFormatConfiguration: - description: | - 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](https://developers.openai.com/api/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. - anyOf: - - $ref: '#/components/schemas/BetaResponseFormatText' - - $ref: '#/components/schemas/BetaTextResponseFormatJsonSchema' - - $ref: '#/components/schemas/BetaResponseFormatJsonObject' - discriminator: - propertyName: type - BetaResponseFormatJsonObject: - type: object - title: JSON object - description: | - 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. - properties: - type: - type: string - description: The type of response format being defined. Always `json_object`. - enum: - - json_object - x-stainless-const: true - required: - - type - BetaTextResponseFormatJsonSchema: - type: object - title: JSON schema - description: | - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs). - properties: - type: - type: string - description: The type of response format being defined. Always `json_schema`. - enum: - - json_schema - x-stainless-const: true - description: - type: string - description: | - A description of what the response format is for, used by the model to - determine how to respond in the format. - name: - type: string - description: | - The name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. - schema: - $ref: '#/components/schemas/BetaResponseFormatJsonSchemaSchema' - strict: - anyOf: - - type: boolean - default: false - description: | - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined - in the `schema` field. Only a subset of JSON Schema is supported when - `strict` is `true`. To learn more, read the [Structured Outputs - guide](https://developers.openai.com/api/docs/guides/structured-outputs). - - type: 'null' - required: - - type - - schema - - name - BetaResponseFormatJsonSchemaSchema: - type: object - title: JSON schema - description: | - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). - additionalProperties: true - BetaResponseFormatText: - type: object - title: Text - description: | - Default response format. Used to generate text responses. - properties: - type: - type: string - description: The type of response format being defined. Always `text`. - enum: - - text - x-stainless-const: true - required: - - type - BetaTool: - description: | - A tool that can be used to generate a response. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaFunctionTool' - - $ref: '#/components/schemas/BetaFileSearchTool' - - $ref: '#/components/schemas/BetaComputerTool' - - $ref: '#/components/schemas/BetaComputerUsePreviewTool' - - $ref: '#/components/schemas/BetaWebSearchTool' - - $ref: '#/components/schemas/BetaMCPTool' - - $ref: '#/components/schemas/BetaCodeInterpreterTool' - - $ref: '#/components/schemas/BetaProgrammaticToolCallingParam' - - $ref: '#/components/schemas/BetaImageGenTool' - - $ref: '#/components/schemas/BetaLocalShellToolParam' - - $ref: '#/components/schemas/BetaFunctionShellToolParam' - - $ref: '#/components/schemas/BetaCustomToolParam' - - $ref: '#/components/schemas/BetaNamespaceToolParam' - - $ref: '#/components/schemas/BetaToolSearchToolParam' - - $ref: '#/components/schemas/BetaWebSearchPreviewTool' - - $ref: '#/components/schemas/BetaApplyPatchToolParam' - BetaApplyPatchToolParam: - properties: - type: - type: string - enum: - - apply_patch - description: The type of the tool. Always `apply_patch`. - default: apply_patch - x-stainless-const: true - allowed_callers: - anyOf: - - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - type: array - minItems: 1 - description: The tool invocation context(s). - - type: 'null' - type: object - required: - - type - title: Apply patch tool - description: Allows the assistant to create, delete, or update files using unified diffs. - BetaCallableToolAllowedCaller: - type: string - enum: - - direct - - programmatic - BetaWebSearchPreviewTool: - properties: - type: - type: string - enum: - - web_search_preview - - web_search_preview_2025_03_11 - description: The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - default: web_search_preview - x-stainless-const: true - user_location: - anyOf: - - $ref: '#/components/schemas/BetaApproximateLocation' - description: The user's location. - - type: 'null' - search_context_size: - $ref: '#/components/schemas/BetaSearchContextSize' - description: 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. - search_content_types: - items: - $ref: '#/components/schemas/BetaSearchContentType' - type: array - type: object - required: - - type - title: Web search preview - description: This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search). - BetaSearchContentType: - type: string - enum: - - text - - image - BetaSearchContextSize: - type: string - enum: - - low - - medium - - high - BetaApproximateLocation: - properties: - type: - type: string - enum: - - approximate - description: The type of location approximation. Always `approximate`. - default: approximate - x-stainless-const: true - country: - anyOf: - - type: string - description: The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - type: 'null' - region: - anyOf: - - type: string - description: Free text input for the region of the user, e.g. `California`. - - type: 'null' - city: - anyOf: - - type: string - description: Free text input for the city of the user, e.g. `San Francisco`. - - type: 'null' - timezone: - anyOf: - - type: string - description: The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - type: 'null' - type: object - required: - - type - BetaToolSearchToolParam: - properties: - type: - type: string - enum: - - tool_search - description: The type of the tool. Always `tool_search`. - default: tool_search - x-stainless-const: true - execution: - $ref: '#/components/schemas/BetaToolSearchExecutionType' - description: Whether tool search is executed by the server or by the client. - description: - anyOf: - - type: string - description: Description shown to the model for a client-executed tool search tool. - - type: 'null' - parameters: - anyOf: - - $ref: '#/components/schemas/BetaEmptyModelParam' - description: Parameter schema for a client-executed tool search tool. - - type: 'null' - type: object - required: - - type - title: Tool search tool - description: Hosted or BYOT tool search configuration for deferred tools. - BetaEmptyModelParam: - properties: {} - type: object - required: [] - BetaToolSearchExecutionType: - type: string - enum: - - server - - client - BetaNamespaceToolParam: - properties: - type: - type: string - enum: - - namespace - description: The type of the tool. Always `namespace`. - default: namespace - x-stainless-const: true - name: - type: string - minLength: 1 - description: The namespace name used in tool calls (for example, `crm`). - description: - type: string - description: A description of the namespace shown to the model. - tools: - items: - discriminator: - propertyName: type - description: A function or custom tool that belongs to a namespace. - anyOf: - - $ref: '#/components/schemas/BetaFunctionToolParam' - - $ref: '#/components/schemas/BetaCustomToolParam' - type: array - minItems: 1 - description: The function/custom tools available inside this namespace. - type: object - required: - - type - - name - - description - - tools - title: Namespace - description: Groups function/custom tools under a shared namespace. - BetaCustomToolParam: - properties: - type: - type: string - enum: - - custom - description: The type of the custom tool. Always `custom`. - default: custom - x-stainless-const: true - name: - type: string - description: The name of the custom tool, used to identify it in tool calls. - async: - type: boolean - description: Whether the tool response can be returned asynchronously versus immediately returned on next response creation. - description: - type: string - description: Optional description of the custom tool, used to provide more context. - format: - discriminator: - propertyName: type - description: The input format for the custom tool. Default is unconstrained text. - anyOf: - - $ref: '#/components/schemas/BetaCustomTextFormatParam' - - $ref: '#/components/schemas/BetaCustomGrammarFormatParam' - defer_loading: - type: boolean - description: Whether this tool should be deferred and discovered via tool search. - allowed_callers: - anyOf: - - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - type: array - minItems: 1 - description: The tool invocation context(s). - - type: 'null' - type: object - required: - - type - - name - title: Custom tool - description: A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools) - BetaCustomGrammarFormatParam: - properties: - type: - type: string - enum: - - grammar - description: Grammar format. Always `grammar`. - default: grammar - x-stainless-const: true - syntax: - $ref: '#/components/schemas/BetaGrammarSyntax1' - description: The syntax of the grammar definition. One of `lark` or `regex`. - definition: - type: string - description: The grammar definition. - type: object - required: - - type - - syntax - - definition - title: Grammar format - description: A grammar defined by the user. - BetaGrammarSyntax1: - type: string - enum: - - lark - - regex - BetaCustomTextFormatParam: - properties: - type: - type: string - enum: - - text - description: Unconstrained text format. Always `text`. - default: text - x-stainless-const: true - type: object - required: - - type - title: Text format - description: Unconstrained free-form text. - BetaFunctionToolParam: - properties: - name: - type: string - maxLength: 128 - minLength: 1 - pattern: ^[a-zA-Z0-9_-]+$ - description: - anyOf: - - type: string - - type: 'null' - parameters: - anyOf: - - $ref: '#/components/schemas/BetaEmptyModelParam' - - type: 'null' - strict: - anyOf: - - type: boolean - description: Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - - type: 'null' - type: - type: string - enum: - - function - default: function - x-stainless-const: true - async: - type: boolean - description: Whether the tool response can be returned asynchronously versus immediately returned on next response creation. - output_schema: - anyOf: - - additionalProperties: {} - type: object - description: A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - x-oaiTypeLabel: map - - type: 'null' - defer_loading: - type: boolean - description: Whether this function should be deferred and discovered via tool search. - allowed_callers: - anyOf: - - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - type: array - minItems: 1 - description: The tool invocation context(s). - - type: 'null' - type: object - required: - - name - - type - BetaFunctionShellToolParam: - properties: - type: - type: string - enum: - - shell - description: The type of the shell tool. Always `shell`. - default: shell - x-stainless-const: true - environment: - anyOf: - - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaContainerAutoParam' - - $ref: '#/components/schemas/BetaLocalEnvironmentParam' - - $ref: '#/components/schemas/BetaContainerReferenceParam' - - type: 'null' - allowed_callers: - anyOf: - - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - type: array - minItems: 1 - description: The tool invocation context(s). - - type: 'null' - type: object - required: - - type - title: Shell tool - description: A tool that allows the model to execute shell commands. - BetaContainerReferenceParam: - properties: - type: - type: string - enum: - - container_reference - description: References a container created with the /v1/containers endpoint - default: container_reference - x-stainless-const: true - container_id: - type: string - description: The ID of the referenced container. - example: cntr_123 - type: object - required: - - type - - container_id - BetaLocalEnvironmentParam: - properties: - type: - type: string - enum: - - local - description: Use a local computer environment. - default: local - x-stainless-const: true - skills: - items: - $ref: '#/components/schemas/BetaLocalSkillParam' - type: array - maxItems: 200 - description: An optional list of skills. - type: object - required: - - type - BetaLocalSkillParam: - properties: - name: - type: string - description: The name of the skill. - description: - type: string - description: The description of the skill. - path: - type: string - description: The path to the directory containing the skill. - type: object - required: - - name - - description - - path - BetaContainerAutoParam: - properties: - type: - type: string - enum: - - container_auto - description: Automatically creates a container for this request - default: container_auto - x-stainless-const: true - file_ids: - items: - type: string - example: file-123 - type: array - maxItems: 50 - description: An optional list of uploaded files to make available to your code. - memory_limit: - anyOf: - - $ref: '#/components/schemas/BetaContainerMemoryLimit' - description: The memory limit for the container. - - type: 'null' - network_policy: - discriminator: - propertyName: type - description: Network access policy for the container. - anyOf: - - $ref: '#/components/schemas/BetaContainerNetworkPolicyDisabledParam' - - $ref: '#/components/schemas/BetaContainerNetworkPolicyAllowlistParam' - skills: - items: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaSkillReferenceParam' - - $ref: '#/components/schemas/BetaInlineSkillParam' - type: array - maxItems: 200 - description: An optional list of skills referenced by id or inline data. - type: object - required: - - type - BetaInlineSkillParam: - properties: - type: - type: string - enum: - - inline - description: Defines an inline skill for this request. - default: inline - x-stainless-const: true - name: - type: string - description: The name of the skill. - description: - type: string - description: The description of the skill. - source: - $ref: '#/components/schemas/BetaInlineSkillSourceParam' - description: Inline skill payload - type: object - required: - - type - - name - - description - - source - BetaInlineSkillSourceParam: - properties: - type: - type: string - enum: - - base64 - description: The type of the inline skill source. Must be `base64`. - default: base64 - x-stainless-const: true - media_type: - type: string - enum: - - application/zip - description: The media type of the inline skill payload. Must be `application/zip`. - default: application/zip - x-stainless-const: true - data: - type: string - maxLength: 70254592 - minLength: 1 - description: Base64-encoded skill zip bundle. - type: object - required: - - type - - media_type - - data - description: Inline skill payload - BetaSkillReferenceParam: - properties: - type: - type: string - enum: - - skill_reference - description: References a skill created with the /v1/skills endpoint. - default: skill_reference - x-stainless-const: true - skill_id: - type: string - maxLength: 64 - minLength: 1 - description: The ID of the referenced skill. - version: - type: string - description: Optional skill version. Use a positive integer or 'latest'. Omit for default. - type: object - required: - - type - - skill_id - BetaContainerNetworkPolicyAllowlistParam: - properties: - type: - type: string - enum: - - allowlist - description: Allow outbound network access only to specified domains. Always `allowlist`. - default: allowlist - x-stainless-const: true - allowed_domains: - items: - type: string - type: array - minItems: 1 - description: A list of allowed domains when type is `allowlist`. - domain_secrets: - items: - $ref: '#/components/schemas/BetaContainerNetworkPolicyDomainSecretParam' - type: array - minItems: 1 - description: Optional domain-scoped secrets for allowlisted domains. - type: object - required: - - type - - allowed_domains - BetaContainerNetworkPolicyDomainSecretParam: - properties: - domain: - type: string - minLength: 1 - description: The domain associated with the secret. - name: - type: string - minLength: 1 - description: The name of the secret to inject for the domain. - value: - type: string - maxLength: 10485760 - minLength: 1 - description: The secret value to inject for the domain. - type: object - required: - - domain - - name - - value - BetaContainerNetworkPolicyDisabledParam: - properties: - type: - type: string - enum: - - disabled - description: Disable outbound network access. Always `disabled`. - default: disabled - x-stainless-const: true - type: object - required: - - type - BetaContainerMemoryLimit: - type: string - enum: - - 1g - - 4g - - 16g - - 64g - BetaLocalShellToolParam: - properties: - type: - type: string - enum: - - local_shell - description: The type of the local shell tool. Always `local_shell`. - default: local_shell - x-stainless-const: true - type: object - required: - - type - title: Local shell tool - description: A tool that allows the model to execute shell commands in a local environment. - BetaImageGenTool: - type: object - title: Image generation tool - description: | - A tool that generates images using the GPT image models. - properties: - type: - type: string - enum: - - image_generation - description: | - The type of the image generation tool. Always `image_generation`. - x-stainless-const: true - model: - anyOf: - - type: string - - type: string - enum: - - gpt-image-1 - - gpt-image-1-mini - - gpt-image-2 - - gpt-image-2-2026-04-21 - - gpt-image-2.5-sunburst - - gpt-image-2.5-sunburst-2026-09-08 - - gpt-image-2.5-flare - - gpt-image-2.5-flare-2026-09-08 - - gpt-image-1.5 - - chatgpt-image-latest - description: | - The image generation model to use. One of `gpt-image-1`, - `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, - `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, - `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, - `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`. Default: - `gpt-image-1`. - default: gpt-image-1 - quality: - type: string - enum: - - low - - medium - - high - - xhigh - - max - - auto - description: | - The quality of the generated image. The GPT image models support `low`, - `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, - including their `2026-09-08` snapshots, also support `xhigh` and `max`. - Default: `auto`. - default: auto - size: - anyOf: - - type: string - - type: string - enum: - - 1024x1024 - - 1024x1536 - - 1536x1024 - - auto - description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - default: auto - output_format: - type: string - enum: - - png - - webp - - jpeg - description: | - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. - default: png - output_compression: - type: integer - minimum: 0 - maximum: 100 - description: | - Compression level for the output image. Default: 100. - default: 100 - moderation: - type: string - enum: - - auto - - low - description: | - Moderation level for the generated image. Default: `auto`. - default: auto - background: - type: string - enum: - - transparent - - opaque - - auto - description: | - Allows to set transparency for the background of the generated image(s). Must - be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is - used, the model will automatically determine the best background for the - image. - - `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their - `2026-09-08` snapshots, support `opaque` and `transparent` backgrounds. - Transparent backgrounds are available for supported GPT Image models. For - `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When - using `transparent`, set the output format to `png` or `webp`. - default: auto - input_fidelity: - anyOf: - - $ref: '#/components/schemas/BetaInputFidelity' - - type: 'null' - description: Controls fidelity to the original input image(s). This parameter is supported for GPT image models that support input fidelity. `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. - input_image_mask: - type: object - description: | - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). - properties: - image_url: - type: string - description: | - Base64-encoded mask image. - file_id: - type: string - description: | - File ID for the mask image. - required: [] - additionalProperties: false - partial_images: - type: integer - minimum: 0 - maximum: 3 - description: | - Number of partial images to generate in streaming mode, from 0 (default value) to 3. - default: 0 - action: - description: | - Whether to generate a new image or edit an existing image. Default: `auto`. - $ref: '#/components/schemas/BetaImageGenActionEnum' - required: - - type - BetaImageGenActionEnum: - type: string - enum: - - generate - - edit - - auto - BetaInputFidelity: - type: string - enum: - - high - - low - description: 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`. - BetaProgrammaticToolCallingParam: - properties: - type: - type: string - enum: - - programmatic_tool_calling - description: The type of the tool. Always `programmatic_tool_calling`. - default: programmatic_tool_calling - x-stainless-const: true - type: object - required: - - type - BetaCodeInterpreterTool: - type: object - title: Code interpreter - description: | - A tool that runs Python code to help generate a response to a prompt. - properties: - type: - type: string - enum: - - code_interpreter - description: | - The type of the code interpreter tool. Always `code_interpreter`. - x-stainless-const: true - container: - description: | - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. - anyOf: - - type: string - description: The container ID. - - $ref: '#/components/schemas/BetaAutoCodeInterpreterToolParam' - allowed_callers: - anyOf: - - type: array - minItems: 1 - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - description: The tool invocation context(s). - - type: 'null' - required: - - type - - container - BetaAutoCodeInterpreterToolParam: - properties: - type: - type: string - enum: - - auto - description: Always `auto`. - default: auto - x-stainless-const: true - file_ids: - items: - type: string - example: file-123 - type: array - maxItems: 50 - description: An optional list of uploaded files to make available to your code. - memory_limit: - anyOf: - - $ref: '#/components/schemas/BetaContainerMemoryLimit' - description: The memory limit for the code interpreter container. - - type: 'null' - network_policy: - discriminator: - propertyName: type - description: Network access policy for the container. - anyOf: - - $ref: '#/components/schemas/BetaContainerNetworkPolicyDisabledParam' - - $ref: '#/components/schemas/BetaContainerNetworkPolicyAllowlistParam' - type: object - required: - - type - title: CodeInterpreterToolAuto - description: Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - BetaMCPTool: - type: object - title: MCP tool - description: | - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp). - properties: - type: - type: string - enum: - - mcp - description: The type of the MCP tool. Always `mcp`. - x-stainless-const: true - server_label: - type: string - description: | - A label for this MCP server, used to identify it in tool calls. - server_url: - type: string - format: uri - description: | - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. - connector_id: - type: string - deprecated: true - enum: - - connector_dropbox - - connector_gmail - - connector_googlecalendar - - connector_googledrive - - connector_microsoftteams - - connector_outlookcalendar - - connector_outlookemail - - connector_sharepoint - description: | - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors). - - This field is deprecated for models released after September 1, 2026. - Use `server_url` to connect to a remote MCP server, or `tunnel_id` to - connect through a Secure MCP Tunnel. - - Currently supported `connector_id` values are: - - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` - tunnel_id: - type: string - pattern: ^tunnel_[a-z0-9]{32}$ - description: | - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. - authorization: - type: string - description: | - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. - server_description: - type: string - description: | - Optional description of the MCP server, used to provide more context. - headers: - anyOf: - - type: object - additionalProperties: - type: string - description: | - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. - - type: 'null' - allowed_tools: - anyOf: - - description: | - List of allowed tool names or a filter object. - anyOf: - - type: array - title: MCP allowed tools - description: A string array of allowed tool names - items: - type: string - - $ref: '#/components/schemas/BetaMCPToolFilter' - - type: 'null' - allowed_callers: - anyOf: - - type: array - minItems: 1 - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - description: The tool invocation context(s). - - type: 'null' - require_approval: - anyOf: - - description: Specify which of the MCP server's tools require approval. - default: always - anyOf: - - type: object - title: MCP tool approval filter - description: | - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. - properties: - always: - $ref: '#/components/schemas/BetaMCPToolFilter' - never: - $ref: '#/components/schemas/BetaMCPToolFilter' - additionalProperties: false - - type: string - title: MCP tool approval setting - description: | - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. - enum: - - always - - never - - type: 'null' - defer_loading: - type: boolean - description: | - Whether this MCP tool is deferred and discovered via tool search. - required: - - type - - server_label - BetaMCPToolFilter: - type: object - title: MCP tool filter - description: | - A filter object to specify which tools are allowed. - properties: - tool_names: - type: array - title: MCP allowed tools - items: - type: string - description: List of allowed tool names. - read_only: - type: boolean - description: | - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - required: [] - additionalProperties: false - BetaWebSearchTool: - type: object - title: Web search - description: | - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search). - properties: - type: - type: string - enum: - - web_search - - web_search_2025_08_26 - description: The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - default: web_search - external_web_access: - type: boolean - default: true - description: Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content. - filters: - anyOf: - - type: object - description: | - Filters for the search. - properties: - allowed_domains: - anyOf: - - type: array - title: Allowed domains for the search. - description: | - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. - - Example: `["pubmed.ncbi.nlm.nih.gov"]` - items: - type: string - description: Allowed domain for the search. - default: [] - - type: 'null' - - type: 'null' - user_location: - $ref: '#/components/schemas/BetaWebSearchApproximateLocation' - search_context_size: - type: string - enum: - - low - - medium - - high - default: medium - description: 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. - required: - - type - BetaWebSearchApproximateLocation: - anyOf: - - type: object - title: Web search approximate location - description: | - The approximate location of the user. - properties: - type: - type: string - enum: - - approximate - description: The type of location approximation. Always `approximate`. - default: approximate - x-stainless-const: true - country: - anyOf: - - type: string - description: The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - type: 'null' - region: - anyOf: - - type: string - description: Free text input for the region of the user, e.g. `California`. - - type: 'null' - city: - anyOf: - - type: string - description: Free text input for the city of the user, e.g. `San Francisco`. - - type: 'null' - timezone: - anyOf: - - type: string - description: The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - type: 'null' - - type: 'null' - BetaComputerUsePreviewTool: - properties: - type: - type: string - enum: - - computer_use_preview - description: The type of the computer use tool. Always `computer_use_preview`. - default: computer_use_preview - x-stainless-const: true - environment: - $ref: '#/components/schemas/BetaComputerEnvironment' - description: The type of computer environment to control. - display_width: - type: integer - description: The width of the computer display. - display_height: - type: integer - description: The height of the computer display. - type: object - required: - - type - - environment - - display_width - - display_height - title: Computer use preview - description: A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use). - BetaComputerEnvironment: - type: string - enum: - - windows - - mac - - linux - - ubuntu - - browser - BetaComputerTool: - properties: - type: - type: string - enum: - - computer - description: The type of the computer tool. Always `computer`. - default: computer - x-stainless-const: true - type: object - required: - - type - title: Computer - description: A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use). - BetaFileSearchTool: - properties: - type: - type: string - enum: - - file_search - description: The type of the file search tool. Always `file_search`. - default: file_search - x-stainless-const: true - vector_store_ids: - items: - type: string - type: array - description: The IDs of the vector stores to search. - max_num_results: - type: integer - description: The maximum number of results to return. This number should be between 1 and 50 inclusive. - ranking_options: - $ref: '#/components/schemas/BetaRankingOptions' - description: Ranking options for search. - filters: - anyOf: - - $ref: '#/components/schemas/BetaFilters' - description: A filter to apply. - - type: 'null' - type: object - required: - - type - - vector_store_ids - title: File search - description: A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://developers.openai.com/api/docs/guides/tools-file-search). - BetaFilters: - anyOf: - - $ref: '#/components/schemas/BetaComparisonFilter' - - $ref: '#/components/schemas/BetaCompoundFilter' - BetaCompoundFilter: - $recursiveAnchor: true - type: object - additionalProperties: false - title: Compound Filter - description: Combine multiple filters using `and` or `or`. - properties: - type: - type: string - description: 'Type of operation: `and` or `or`.' - enum: - - and - - or - filters: - type: array - description: Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - items: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaComparisonFilter' - - $recursiveRef: '#' - required: - - type - - filters - x-oaiMeta: - name: CompoundFilter - BetaComparisonFilter: - type: object - additionalProperties: false - title: Comparison Filter - description: | - A filter used to compare a specified attribute key to a given value using a defined comparison operation. - properties: - type: - type: string - default: eq - enum: - - eq - - ne - - gt - - gte - - lt - - lte - - in - - nin - description: | - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - key: - type: string - description: The key to compare against the value. - value: - description: The value to compare against the attribute key; supports string, number, or boolean types. - anyOf: - - type: string - - type: number - - type: boolean - - type: array - items: - $ref: '#/components/schemas/ComparisonFilterValueItems' - required: - - type - - key - - value - x-oaiMeta: - name: ComparisonFilter - BetaRankingOptions: - properties: - ranker: - $ref: '#/components/schemas/BetaRankerVersionType' - description: The ranker to use for the file search. - score_threshold: - type: number - description: The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - hybrid_search: - $ref: '#/components/schemas/BetaHybridSearchOptions' - description: Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - type: object - required: [] - BetaHybridSearchOptions: - properties: - embedding_weight: - type: number - description: The weight of the embedding in the reciprocal ranking fusion. - text_weight: - type: number - description: The weight of the text in the reciprocal ranking fusion. - type: object - required: - - embedding_weight - - text_weight - BetaRankerVersionType: - type: string - enum: - - auto - - default-2024-11-15 - BetaFunctionTool: - properties: - type: - type: string - enum: - - function - description: The type of the function tool. Always `function`. - default: function - x-stainless-const: true - name: - type: string - description: The name of the function to call. - async: - type: boolean - description: - anyOf: - - type: string - description: A description of the function. Used by the model to determine whether or not to call the function. - - type: 'null' - parameters: - anyOf: - - additionalProperties: {} - type: object - description: A JSON schema object describing the parameters of the function. - x-oaiTypeLabel: map - - type: 'null' - output_schema: - anyOf: - - additionalProperties: {} - type: object - description: A JSON schema object describing the JSON value encoded in string outputs for this function. - x-oaiTypeLabel: map - - type: 'null' - strict: - anyOf: - - type: boolean - description: Whether strict parameter validation is enforced for this function tool. - - type: 'null' - defer_loading: - type: boolean - description: Whether this function is deferred and loaded via tool search. - allowed_callers: - anyOf: - - items: - $ref: '#/components/schemas/BetaCallableToolAllowedCaller' - type: array - description: The tool invocation context(s). - - type: 'null' - type: object - required: - - type - - name - - strict - - parameters - title: Function - description: Defines a function in your own code the model can choose to call. Learn more about [function calling](https://developers.openai.com/api/docs/guides/function-calling). - BetaInputItem: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaEasyInputMessage' - - type: object - title: Item - description: | - An item representing part of the context for the response to be - generated by the model. Can contain text, images, and audio inputs, - as well as previous assistant responses and tool call outputs. - $ref: '#/components/schemas/BetaItem' - - $ref: '#/components/schemas/BetaCompactionTriggerItemParam' - - $ref: '#/components/schemas/BetaItemReferenceParam' - - $ref: '#/components/schemas/BetaProgramItemParam' - - $ref: '#/components/schemas/BetaProgramOutputItemParam' - BetaProgramOutputItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - type: string - description: The unique ID of this program output item. - example: cmo_123 - type: - type: string - enum: - - program_output - description: The item type. Always `program_output`. - default: program_output - x-stainless-const: true - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The call ID of the program item. - result: - type: string - maxLength: 10485760 - description: The result produced by the program item. - status: - $ref: '#/components/schemas/BetaProgramOutputItemStatus' - description: The terminal status of the program output. - type: object - required: - - id - - type - - call_id - - result - - status - BetaProgramOutputItemStatus: - type: string - enum: - - completed - - incomplete - Beta_AgentTagParam: - properties: - agent_name: - type: string - description: The canonical name of the agent that produced this item. - type: object - required: - - agent_name - description: The agent that produced this item. - x-oai-beta: responses_multi_agent=v1 - BetaProgramItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - type: string - description: The unique ID of this program item. - example: cm_123 - type: - type: string - enum: - - program - description: The item type. Always `program`. - default: program - x-stainless-const: true - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The stable call ID of the program item. - code: - type: string - maxLength: 10485760 - description: The JavaScript source executed by programmatic tool calling. - fingerprint: - type: string - maxLength: 10485760 - description: Opaque program replay fingerprint that must be round-tripped. - type: object - required: - - id - - type - - call_id - - code - - fingerprint - BetaItemReferenceParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - type: - anyOf: - - type: string - enum: - - item_reference - description: The type of item to reference. Always `item_reference`. - default: item_reference - x-stainless-const: true - - type: 'null' - id: - type: string - description: The ID of the item to reference. - type: object - required: - - id - title: Item reference - description: An internal identifier for an item to reference. - BetaCompactionTriggerItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - type: - type: string - enum: - - compaction_trigger - description: The type of the item. Always `compaction_trigger`. - default: compaction_trigger - x-stainless-const: true - type: object - required: - - type - title: Compaction trigger - description: Compacts the current context. Must be the final input item. - BetaItem: - type: object - description: | - Content item used to generate a response. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaInputMessage' - - $ref: '#/components/schemas/BetaOutputMessage' - - $ref: '#/components/schemas/BetaFileSearchToolCall' - - $ref: '#/components/schemas/BetaComputerToolCall' - - $ref: '#/components/schemas/BetaComputerCallOutputItemParam' - - $ref: '#/components/schemas/BetaWebSearchToolCall' - - $ref: '#/components/schemas/BetaFunctionToolCall' - - $ref: '#/components/schemas/BetaFunctionCallOutputItemParam' - - $ref: '#/components/schemas/BetaAgentMessageItemParam' - - $ref: '#/components/schemas/BetaMultiAgentCallItemParam' - - $ref: '#/components/schemas/BetaMultiAgentCallOutputItemParam' - - $ref: '#/components/schemas/BetaToolSearchCallItemParam' - - $ref: '#/components/schemas/BetaToolSearchOutputItemParam' - - $ref: '#/components/schemas/BetaAdditionalToolsItemParam' - - $ref: '#/components/schemas/BetaResponseConfigurationUpdateItemParam' - - $ref: '#/components/schemas/BetaReasoningItem' - - $ref: '#/components/schemas/BetaCompactionSummaryItemParam' - - $ref: '#/components/schemas/BetaImageGenToolCall' - - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' - - $ref: '#/components/schemas/BetaFunctionShellCallItemParam' - - $ref: '#/components/schemas/BetaFunctionShellCallOutputItemParam' - - $ref: '#/components/schemas/BetaApplyPatchToolCallItemParam' - - $ref: '#/components/schemas/BetaApplyPatchToolCallOutputItemParam' - - $ref: '#/components/schemas/BetaMCPListTools' - - $ref: '#/components/schemas/BetaMCPApprovalRequest' - - $ref: '#/components/schemas/BetaMCPApprovalResponse' - - $ref: '#/components/schemas/BetaMCPToolCall' - - $ref: '#/components/schemas/BetaCustomToolCallOutput' - - $ref: '#/components/schemas/BetaCustomToolCall' - BetaCustomToolCall: - type: object - title: Custom tool call - description: | - A call to a custom tool created by the model. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - enum: - - custom_tool_call - x-stainless-const: true - description: | - The type of the custom tool call. Always `custom_tool_call`. - id: - type: string - description: | - The unique ID of the custom tool call in the OpenAI platform. - call_id: - type: string - description: | - An identifier used to map this custom tool call to a tool call output. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCaller' - - type: 'null' - namespace: - type: string - description: | - The namespace of the custom tool being called. - name: - type: string - description: | - The name of the custom tool being called. - input: - type: string - description: | - The input for the custom tool call generated by the model. - async: - type: boolean - description: | - Whether the custom tool call runs asynchronously. - required: - - type - - call_id - - name - - input - BetaToolCallCaller: - discriminator: - propertyName: type - description: The execution context that produced this tool call. - anyOf: - - $ref: '#/components/schemas/BetaDirectToolCallCaller' - - $ref: '#/components/schemas/BetaProgramToolCallCaller' - BetaProgramToolCallCaller: - properties: - type: - type: string - enum: - - program - default: program - x-stainless-const: true - caller_id: - type: string - description: The call ID of the program item that produced this tool call. - type: object - required: - - type - - caller_id - BetaDirectToolCallCaller: - properties: - type: - type: string - enum: - - direct - default: direct - x-stainless-const: true - type: object - required: - - type - BetaAgentTag: - properties: - agent_name: - type: string - description: The canonical name of the agent that produced this item. - type: object - required: - - agent_name - x-oai-beta: responses_multi_agent=v1 - BetaCustomToolCallOutput: - type: object - title: Custom tool call output - description: | - The output of a custom tool call from your code, being sent back to the model. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - enum: - - custom_tool_call_output - x-stainless-const: true - description: | - The type of the custom tool call output. Always `custom_tool_call_output`. - id: - type: string - description: | - The unique ID of the custom tool call output in the OpenAI platform. - call_id: - type: string - description: | - The call ID, used to map this custom tool call output to a custom tool call. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - - type: 'null' - output: - description: | - The output from the custom tool call generated by your code. - Can be a string or an list of output content. - anyOf: - - type: string - description: | - A string of the output of the custom tool call. - title: string output - - type: array - items: - $ref: '#/components/schemas/BetaFunctionAndCustomToolCallOutput' - title: output content list - description: | - Text, image, or file output of the custom tool call. - required: - - type - - call_id - - output - BetaFunctionAndCustomToolCallOutput: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaInputTextContent' - - $ref: '#/components/schemas/BetaInputImageContent' - - $ref: '#/components/schemas/BetaInputFileContent' - BetaInputFileContent: - properties: - type: - type: string - enum: - - input_file - description: The type of the input item. Always `input_file`. - default: input_file - x-stainless-const: true - file_id: - anyOf: - - type: string - description: The ID of the file to be sent to the model. - - type: 'null' - filename: - type: string - description: The name of the file to be sent to the model. - file_data: - type: string - description: | - The content of the file to be sent to the model. - prompt_cache_breakpoint: - $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' - file_url: - type: string - format: uri - description: The URL of the file to be sent to the model. - detail: - $ref: '#/components/schemas/BetaFileInputDetail' - description: The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - type: object - required: - - type - title: Input file - description: A file input to the model. - BetaFileInputDetail: - type: string - enum: - - auto - - low - - high - BetaPromptCacheBreakpointConfig: - properties: - mode: - type: string - enum: - - explicit - description: The breakpoint mode. Always `explicit`. - default: explicit - x-stainless-const: true - type: object - required: - - mode - title: Prompt cache breakpoint - description: Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - BetaInputImageContent: - properties: - type: - type: string - enum: - - input_image - description: The type of the input item. Always `input_image`. - default: input_image - x-stainless-const: true - image_url: - anyOf: - - type: string - format: uri - description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - type: 'null' - file_id: - anyOf: - - type: string - description: The ID of the file to be sent to the model. - - type: 'null' - detail: - $ref: '#/components/schemas/BetaImageDetail' - description: The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - prompt_cache_breakpoint: - $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' - type: object - required: - - type - - detail - title: Input image - description: An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision). - BetaImageDetail: - type: string - enum: - - low - - high - - auto - - original - BetaInputTextContent: - properties: - type: - type: string - enum: - - input_text - description: The type of the input item. Always `input_text`. - default: input_text - x-stainless-const: true - text: - type: string - description: The text input to the model. - prompt_cache_breakpoint: - $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' - type: object - required: - - type - - text - title: Input text - description: A text input to the model. - BetaToolCallCallerParam: - discriminator: - propertyName: type - description: The execution context that produced this tool call. - anyOf: - - $ref: '#/components/schemas/BetaDirectToolCallCallerParam' - - $ref: '#/components/schemas/BetaProgramToolCallCallerParam' - BetaProgramToolCallCallerParam: - properties: - type: - type: string - enum: - - program - description: The caller type. Always `program`. - default: program - x-stainless-const: true - caller_id: - type: string - maxLength: 64 - minLength: 1 - description: The call ID of the program item that produced this tool call. - type: object - required: - - type - - caller_id - BetaDirectToolCallCallerParam: - properties: - type: - type: string - enum: - - direct - description: The caller type. Always `direct`. - default: direct - x-stainless-const: true - type: object - required: - - type - BetaMCPToolCall: - type: object - title: MCP tool call - description: | - An invocation of a tool on an MCP server. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - enum: - - mcp_call - description: | - The type of the item. Always `mcp_call`. - x-stainless-const: true - id: - type: string - description: | - The unique ID of the tool call. - server_label: - type: string - description: | - The label of the MCP server running the tool. - name: - type: string - description: | - The name of the tool that was run. - arguments: - type: string - description: | - A JSON string of the arguments passed to the tool. - output: - anyOf: - - type: string - description: | - The output from the tool call. - - type: 'null' - error: - description: The error from the tool call, if any. - anyOf: - - $ref: '#/components/schemas/BetaMCPToolCallError' - - type: 'null' - status: - $ref: '#/components/schemas/BetaMCPToolCallStatus' - description: | - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - approval_request_id: - anyOf: - - type: string - description: | - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - type: 'null' - required: - - type - - id - - server_label - - name - - arguments - BetaMCPToolCallStatus: - type: string - enum: - - in_progress - - completed - - incomplete - - calling - - failed - BetaMCPToolCallError: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaMCPProtocolError' - - $ref: '#/components/schemas/BetaMCPToolExecutionError' - - $ref: '#/components/schemas/BetaHTTPError' - BetaHTTPError: - properties: - type: - type: string - enum: - - http_error - default: http_error - x-stainless-const: true - code: - type: integer - message: - type: string - type: object - required: - - type - - code - - message - BetaMCPToolExecutionError: - properties: - type: - type: string - enum: - - mcp_tool_execution_error - default: mcp_tool_execution_error - x-stainless-const: true - content: {} - type: object - required: - - type - - content - BetaMCPProtocolError: - properties: - type: - type: string - enum: - - mcp_protocol_error - default: mcp_protocol_error - x-stainless-const: true - code: - type: integer - message: - type: string - type: object - required: - - type - - code - - message - BetaMCPApprovalResponse: - type: object - title: MCP approval response - description: | - A response to an MCP approval request. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - enum: - - mcp_approval_response - description: | - The type of the item. Always `mcp_approval_response`. - x-stainless-const: true - id: - anyOf: - - type: string - description: | - The unique ID of the approval response - - type: 'null' - approval_request_id: - type: string - description: | - The ID of the approval request being answered. - approve: - type: boolean - description: | - Whether the request was approved. - reason: - anyOf: - - type: string - description: | - Optional reason for the decision. - - type: 'null' - required: - - type - - request_id - - approve - - approval_request_id - BetaMCPApprovalRequest: - type: object - title: MCP approval request - description: | - A request for human approval of a tool invocation. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - enum: - - mcp_approval_request - description: | - The type of the item. Always `mcp_approval_request`. - x-stainless-const: true - id: - type: string - description: | - The unique ID of the approval request. - server_label: - type: string - description: | - The label of the MCP server making the request. - name: - type: string - description: | - The name of the tool to run. - arguments: - type: string - description: | - A JSON string of arguments for the tool. - required: - - type - - id - - server_label - - name - - arguments - BetaMCPListTools: - type: object - title: MCP list tools - description: | - A list of tools available on an MCP server. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - enum: - - mcp_list_tools - description: | - The type of the item. Always `mcp_list_tools`. - x-stainless-const: true - id: - type: string - description: | - The unique ID of the list. - server_label: - type: string - description: | - The label of the MCP server. - tools: - type: array - items: - $ref: '#/components/schemas/BetaMCPListToolsTool' - description: | - The tools available on the server. - error: - anyOf: - - type: string - description: | - Error message if the server could not list tools. - - type: 'null' - required: - - type - - id - - server_label - - tools - BetaMCPListToolsTool: - type: object - title: MCP list tools tool - description: | - A tool available on an MCP server. - properties: - name: - type: string - description: | - The name of the tool. - description: - anyOf: - - type: string - description: | - The description of the tool. - - type: 'null' - input_schema: - type: object - description: | - The JSON schema describing the tool's input. - annotations: - anyOf: - - type: object - description: | - Additional annotations about the tool. - - type: 'null' - required: - - name - - input_schema - BetaApplyPatchToolCallOutputItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - type: - type: string - enum: - - apply_patch_call_output - description: The type of the item. Always `apply_patch_call_output`. - default: apply_patch_call_output - x-stainless-const: true - id: - anyOf: - - type: string - description: The unique ID of the apply patch tool call output. Populated when this item is returned via API. - example: apco_123 - - type: 'null' - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the apply patch tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - description: The execution context that produced this tool call. - - type: 'null' - status: - $ref: '#/components/schemas/BetaApplyPatchCallOutputStatusParam' - description: The status of the apply patch tool call output. One of `completed` or `failed`. - output: - anyOf: - - type: string - maxLength: 10485760 - description: Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - type: 'null' - type: object - required: - - type - - call_id - - status - title: Apply patch tool call output - description: The streamed output emitted by an apply patch tool call. - BetaApplyPatchCallOutputStatusParam: - type: string - enum: - - completed - - failed - title: Apply patch call output status - description: Outcome values reported for apply_patch tool call outputs. - BetaApplyPatchToolCallItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - type: - type: string - enum: - - apply_patch_call - description: The type of the item. Always `apply_patch_call`. - default: apply_patch_call - x-stainless-const: true - id: - anyOf: - - type: string - description: The unique ID of the apply patch tool call. Populated when this item is returned via API. - example: apc_123 - - type: 'null' - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the apply patch tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - description: The execution context that produced this tool call. - - type: 'null' - status: - $ref: '#/components/schemas/BetaApplyPatchCallStatusParam' - description: The status of the apply patch tool call. One of `in_progress` or `completed`. - operation: - $ref: '#/components/schemas/BetaApplyPatchOperationParam' - description: The specific create, delete, or update instruction for the apply_patch tool call. - type: object - required: - - type - - call_id - - status - - operation - title: Apply patch tool call - description: A tool call representing a request to create, delete, or update files using diff patches. - BetaApplyPatchOperationParam: - discriminator: - propertyName: type - title: Apply patch operation - description: One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool. - anyOf: - - $ref: '#/components/schemas/BetaApplyPatchCreateFileOperationParam' - - $ref: '#/components/schemas/BetaApplyPatchDeleteFileOperationParam' - - $ref: '#/components/schemas/BetaApplyPatchUpdateFileOperationParam' - BetaApplyPatchUpdateFileOperationParam: - properties: - type: - type: string - enum: - - update_file - description: The operation type. Always `update_file`. - default: update_file - x-stainless-const: true - path: - type: string - minLength: 1 - description: Path of the file to update relative to the workspace root. - diff: - type: string - maxLength: 10485760 - description: Unified diff content to apply to the existing file. - type: object - required: - - type - - path - - diff - title: Apply patch update file operation - description: Instruction for updating an existing file via the apply_patch tool. - BetaApplyPatchDeleteFileOperationParam: - properties: - type: - type: string - enum: - - delete_file - description: The operation type. Always `delete_file`. - default: delete_file - x-stainless-const: true - path: - type: string - minLength: 1 - description: Path of the file to delete relative to the workspace root. - type: object - required: - - type - - path - title: Apply patch delete file operation - description: Instruction for deleting an existing file via the apply_patch tool. - BetaApplyPatchCreateFileOperationParam: - properties: - type: - type: string - enum: - - create_file - description: The operation type. Always `create_file`. - default: create_file - x-stainless-const: true - path: - type: string - minLength: 1 - description: Path of the file to create relative to the workspace root. - diff: - type: string - maxLength: 10485760 - description: Unified diff content to apply when creating the file. - type: object - required: - - type - - path - - diff - title: Apply patch create file operation - description: Instruction for creating a new file via the apply_patch tool. - BetaApplyPatchCallStatusParam: - type: string - enum: - - in_progress - - completed - title: Apply patch call status - description: Status values reported for apply_patch tool calls. - BetaFunctionShellCallOutputItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of the shell tool call output. Populated when this item is returned via API. - example: sho_123 - - type: 'null' - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the shell tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - description: The execution context that produced this tool call. - - type: 'null' - type: - type: string - enum: - - shell_call_output - description: The type of the item. Always `shell_call_output`. - default: shell_call_output - x-stainless-const: true - output: - items: - $ref: '#/components/schemas/BetaFunctionShellCallOutputContentParam' - type: array - description: Captured chunks of stdout and stderr output, along with their associated outcomes. - status: - anyOf: - - $ref: '#/components/schemas/BetaFunctionShellCallItemStatus' - description: The status of the shell call output. - - type: 'null' - max_output_length: - anyOf: - - type: integer - description: The maximum number of UTF-8 characters captured for this shell call's combined output. - - type: 'null' - type: object - required: - - call_id - - type - - output - title: Shell tool call output - description: The streamed output items emitted by a shell tool call. - BetaFunctionShellCallItemStatus: - type: string - enum: - - in_progress - - completed - - incomplete - title: Shell call status - description: Status values reported for shell tool calls. - BetaFunctionShellCallOutputContentParam: - properties: - stdout: - type: string - maxLength: 10485760 - description: Captured stdout output for the shell call. - stderr: - type: string - maxLength: 10485760 - description: Captured stderr output for the shell call. - outcome: - $ref: '#/components/schemas/BetaFunctionShellCallOutputOutcomeParam' - description: The exit or timeout outcome associated with this shell call. - type: object - required: - - stdout - - stderr - - outcome - title: Shell output content - description: Captured stdout and stderr for a portion of a shell tool call output. - BetaFunctionShellCallOutputOutcomeParam: - discriminator: - propertyName: type - title: Shell call outcome - description: The exit or timeout outcome associated with this shell call. - anyOf: - - $ref: '#/components/schemas/BetaFunctionShellCallOutputTimeoutOutcomeParam' - - $ref: '#/components/schemas/BetaFunctionShellCallOutputExitOutcomeParam' - BetaFunctionShellCallOutputExitOutcomeParam: - properties: - type: - type: string - enum: - - exit - description: The outcome type. Always `exit`. - default: exit - x-stainless-const: true - exit_code: - type: integer - description: The exit code returned by the shell process. - type: object - required: - - type - - exit_code - title: Shell call exit outcome - description: Indicates that the shell commands finished and returned an exit code. - BetaFunctionShellCallOutputTimeoutOutcomeParam: - properties: - type: - type: string - enum: - - timeout - description: The outcome type. Always `timeout`. - default: timeout - x-stainless-const: true - type: object - required: - - type - title: Shell call timeout outcome - description: Indicates that the shell call exceeded its configured time limit. - BetaFunctionShellCallItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of the shell tool call. Populated when this item is returned via API. - example: sh_123 - - type: 'null' - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the shell tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - description: The execution context that produced this tool call. - - type: 'null' - type: - type: string - enum: - - shell_call - description: The type of the item. Always `shell_call`. - default: shell_call - x-stainless-const: true - action: - $ref: '#/components/schemas/BetaFunctionShellActionParam' - description: The shell commands and limits that describe how to run the tool call. - status: - anyOf: - - $ref: '#/components/schemas/BetaFunctionShellCallItemStatus' - description: The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - type: 'null' - environment: - anyOf: - - discriminator: - propertyName: type - description: The environment to execute the shell commands in. - anyOf: - - $ref: '#/components/schemas/BetaLocalEnvironmentParam' - - $ref: '#/components/schemas/BetaContainerReferenceParam' - - type: 'null' - type: object - required: - - call_id - - type - - action - title: Shell tool call - description: A tool representing a request to execute one or more shell commands. - BetaFunctionShellActionParam: - properties: - commands: - items: - type: string - type: array - description: Ordered shell commands for the execution environment to run. - timeout_ms: - anyOf: - - type: integer - description: Maximum wall-clock time in milliseconds to allow the shell commands to run. - - type: 'null' - max_output_length: - anyOf: - - type: integer - description: Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - type: 'null' - type: object - required: - - commands - title: Shell action - description: Commands and limits describing how to run the shell tool call. - BetaLocalShellToolCallOutput: - type: object - title: Local shell call output - description: | - The output of a local shell tool call. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - enum: - - local_shell_call_output - description: | - The type of the local shell tool call output. Always `local_shell_call_output`. - x-stainless-const: true - id: - type: string - description: | - The unique ID of the local shell tool call generated by the model. - output: - type: string - description: | - A JSON string of the output of the local shell tool call. - status: - anyOf: - - type: string - enum: - - in_progress - - completed - - incomplete - description: | - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - type: 'null' - required: - - id - - type - - call_id - - output - BetaLocalShellToolCall: - type: object - title: Local shell call - description: | - A tool call to run a command on the local shell. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - enum: - - local_shell_call - description: | - The type of the local shell call. Always `local_shell_call`. - x-stainless-const: true - id: - type: string - description: | - The unique ID of the local shell call. - call_id: - type: string - description: | - The unique ID of the local shell tool call generated by the model. - action: - $ref: '#/components/schemas/BetaLocalShellExecAction' - status: - type: string - enum: - - in_progress - - completed - - incomplete - description: | - The status of the local shell call. - required: - - type - - id - - call_id - - action - - status - BetaLocalShellExecAction: - properties: - type: - type: string - enum: - - exec - description: The type of the local shell action. Always `exec`. - default: exec - x-stainless-const: true - command: - items: - type: string - type: array - description: The command to run. - timeout_ms: - anyOf: - - type: integer - description: Optional timeout in milliseconds for the command. - - type: 'null' - working_directory: - anyOf: - - type: string - description: Optional working directory to run the command in. - - type: 'null' - env: - additionalProperties: - type: string - type: object - description: Environment variables to set for the command. - x-oaiTypeLabel: map - user: - anyOf: - - type: string - description: Optional user to run the command as. - - type: 'null' - type: object - required: - - type - - command - - env - title: Local shell exec action - description: Execute a shell command on the server. - BetaCodeInterpreterToolCall: - type: object - title: Code interpreter tool call - description: | - A tool call to run code. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - enum: - - code_interpreter_call - default: code_interpreter_call - x-stainless-const: true - description: | - The type of the code interpreter tool call. Always `code_interpreter_call`. - id: - type: string - description: | - The unique ID of the code interpreter tool call. - status: - type: string - enum: - - in_progress - - completed - - incomplete - - interpreting - - failed - description: | - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - container_id: - type: string - description: | - The ID of the container used to run the code. - code: - anyOf: - - type: string - description: | - The code to run, or null if not available. - - type: 'null' - outputs: - anyOf: - - type: array - items: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaCodeInterpreterOutputLogs' - - $ref: '#/components/schemas/BetaCodeInterpreterOutputImage' - discriminator: - propertyName: type - description: | - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. - - type: 'null' - required: - - type - - id - - status - - container_id - - code - - outputs - BetaCodeInterpreterOutputImage: - properties: - type: - type: string - enum: - - image - description: The type of the output. Always `image`. - default: image - x-stainless-const: true - url: - type: string - format: uri - description: The URL of the image output from the code interpreter. - type: object - required: - - type - - url - title: Code interpreter output image - description: The image output from the code interpreter. - BetaCodeInterpreterOutputLogs: - properties: - type: - type: string - enum: - - logs - description: The type of the output. Always `logs`. - default: logs - x-stainless-const: true - logs: - type: string - description: The logs output from the code interpreter. - type: object - required: - - type - - logs - title: Code interpreter output logs - description: The logs output from the code interpreter. - BetaImageGenToolCall: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - - type: 'null' - type: - type: string - enum: - - image_generation_call - description: The type of the image generation call. Always `image_generation_call`. - x-stainless-const: true - id: - type: string - description: The unique ID of the image generation call. - status: - type: string - enum: - - in_progress - - completed - - generating - - failed - description: The status of the image generation call. - result: - anyOf: - - type: string - description: The generated image encoded in base64. - - type: 'null' - size: - anyOf: - - anyOf: - - type: string - - type: string - enum: - - 1024x1024 - - 1024x1536 - - 1536x1024 - description: The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`. - - type: 'null' - quality: - anyOf: - - type: string - enum: - - low - - medium - - high - - xhigh - - max - - auto - description: The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`. - - type: 'null' - action: - anyOf: - - $ref: '#/components/schemas/BetaImageGenActionEnum' - description: The action used for image generation. - - type: 'null' - x-openai-go-optional-enum: true - background: - anyOf: - - $ref: '#/components/schemas/BetaImageBackground' - description: The background setting used for generation. - - type: 'null' - x-openai-go-optional-enum: true - output_format: - anyOf: - - $ref: '#/components/schemas/BetaImageOutputFormat' - description: The output format used for generation. - - type: 'null' - x-openai-go-optional-enum: true - revised_prompt: - anyOf: - - type: string - description: The prompt that was used after any model prompt rewriting. - - type: 'null' - type: object - required: - - type - - id - - status - - result - title: Image generation call - description: An image generation request made by the model. - BetaImageOutputFormat: - type: string - enum: - - png - - webp - - jpeg - BetaImageBackground: - type: string - enum: - - transparent - - opaque - - auto - BetaCompactionSummaryItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The ID of the compaction item. - example: cmp_123 - - type: 'null' - type: - type: string - enum: - - compaction - description: The type of the item. Always `compaction`. - default: compaction - x-stainless-const: true - encrypted_content: - type: string - maxLength: 104857600 - description: The encrypted content of the compaction summary. - type: object - required: - - type - - encrypted_content - title: Compaction item - description: A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact). - BetaReasoningItem: - type: object - description: | - 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](https://developers.openai.com/api/docs/guides/conversation-state). - title: Reasoning - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - description: | - The type of the object. Always `reasoning`. - enum: - - reasoning - x-stainless-const: true - id: - type: string - description: | - The unique identifier of the reasoning content. - encrypted_content: - anyOf: - - type: string - description: | - The encrypted content of the reasoning item. This is populated by default - for reasoning items returned by `POST /v1/responses` and WebSocket - `response.create` requests. - - When streaming, use the completed reasoning item and its - `encrypted_content` from the `response.output_item.done` event in - subsequent requests. The `encrypted_content` in - `response.output_item.added` may be incomplete. This is especially - important when `store` is `false` or when using Zero Data Retention. - - type: 'null' - summary: - type: array - description: | - Reasoning summary content. - items: - $ref: '#/components/schemas/BetaSummaryTextContent' - content: - type: array - description: | - Reasoning text content. - items: - $ref: '#/components/schemas/BetaReasoningTextContent' - status: - type: string - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - enum: - - in_progress - - completed - - incomplete - required: - - id - - summary - - type - BetaReasoningTextContent: - properties: - type: - type: string - enum: - - reasoning_text - description: The type of the reasoning text. Always `reasoning_text`. - default: reasoning_text - x-stainless-const: true - text: - type: string - description: The reasoning text from the model. - type: object - required: - - type - - text - title: Reasoning text - description: Reasoning text from the model. - BetaSummaryTextContent: - properties: - type: - type: string - enum: - - summary_text - description: The type of the object. Always `summary_text`. - default: summary_text - x-stainless-const: true - text: - type: string - description: A summary of the reasoning output from the model so far. - type: object - required: - - type - - text - title: Summary text - description: A summary text from the model. - BetaResponseConfigurationUpdateItemParam: - type: object - description: | - An update to the conversation's response configuration. The configuration - remains in effect for subsequent responses until it is replaced by another - configuration update. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of the configuration update item. - example: cnfu_123 - - type: 'null' - type: - type: string - enum: - - configuration_update - description: The item type. Always `configuration_update`. - default: configuration_update - x-stainless-const: true - reasoning: - type: object - description: Updates to reasoning configuration. Only effort is supported. - properties: - effort: - $ref: '#/components/schemas/BetaReasoningEffort' - description: | - The reasoning effort to use for subsequent responses until another - configuration update replaces it. - required: - - type - BetaAdditionalToolsItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of this additional tools item. - example: at_123 - - type: 'null' - type: - type: string - enum: - - additional_tools - description: The item type. Always `additional_tools`. - default: additional_tools - x-stainless-const: true - role: - type: string - enum: - - developer - description: The role that provided the additional tools. Only `developer` is supported. - default: developer - x-stainless-const: true - tools: - items: - $ref: '#/components/schemas/BetaTool' - type: array - description: A list of additional tools made available at this item. - type: object - required: - - type - - role - - tools - BetaToolSearchOutputItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of this tool search output. - example: tso_123 - - type: 'null' - call_id: - anyOf: - - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the tool search call generated by the model. - - type: 'null' - type: - type: string - enum: - - tool_search_output - description: The item type. Always `tool_search_output`. - default: tool_search_output - x-stainless-const: true - execution: - $ref: '#/components/schemas/BetaToolSearchExecutionType' - description: Whether tool search was executed by the server or by the client. - tools: - items: - $ref: '#/components/schemas/BetaTool' - type: array - description: The loaded tool definitions returned by the tool search output. - status: - anyOf: - - $ref: '#/components/schemas/BetaFunctionCallItemStatus' - description: The status of the tool search output. - - type: 'null' - type: object - required: - - type - - tools - BetaFunctionCallItemStatus: - type: string - enum: - - in_progress - - completed - - incomplete - BetaToolSearchCallItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of this tool search call. - example: tsc_123 - - type: 'null' - call_id: - anyOf: - - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the tool search call generated by the model. - - type: 'null' - type: - type: string - enum: - - tool_search_call - description: The item type. Always `tool_search_call`. - default: tool_search_call - x-stainless-const: true - execution: - $ref: '#/components/schemas/BetaToolSearchExecutionType' - description: Whether tool search was executed by the server or by the client. - arguments: - $ref: '#/components/schemas/BetaEmptyModelParam' - description: The arguments supplied to the tool search call. - status: - anyOf: - - $ref: '#/components/schemas/BetaFunctionCallItemStatus' - description: The status of the tool search call. - - type: 'null' - type: object - required: - - type - - arguments - BetaMultiAgentCallOutputItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of this multi-agent call output. - example: maco_123 - - type: 'null' - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the multi-agent call. - type: - type: string - enum: - - multi_agent_call_output - description: The item type. Always `multi_agent_call_output`. - default: multi_agent_call_output - x-stainless-const: true - action: - $ref: '#/components/schemas/BetaMultiAgentAction1' - description: The multi-agent action that produced this result. - output: - items: - $ref: '#/components/schemas/BetaOutputTextContentParam' - type: array - description: Text output returned by the multi-agent action. - type: object - required: - - call_id - - type - - action - - output - x-oai-beta: responses_multi_agent=v1 - BetaOutputTextContentParam: - properties: - type: - type: string - enum: - - output_text - description: The content type. Always `output_text`. - default: output_text - x-stainless-const: true - text: - type: string - maxLength: 10485760 - description: The text content. - annotations: - items: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaFileCitationParam' - - $ref: '#/components/schemas/BetaUrlCitationParam' - - $ref: '#/components/schemas/BetaContainerFileCitationParam' - type: array - description: Citations associated with the text content. - type: object - required: - - type - - text - BetaContainerFileCitationParam: - properties: - type: - type: string - enum: - - container_file_citation - description: The citation type. Always `container_file_citation`. - default: container_file_citation - x-stainless-const: true - start_index: - type: integer - minimum: 0 - description: The index of the first character of the citation in the message. - end_index: - type: integer - minimum: 0 - description: The index of the last character of the citation in the message. - container_id: - type: string - description: The ID of the container. - example: cntr_123 - file_id: - type: string - description: The ID of the container file. - example: cfile_123 - filename: - type: string - description: The filename of the container file cited. - type: object - required: - - type - - start_index - - end_index - - container_id - - file_id - - filename - BetaUrlCitationParam: - properties: - type: - type: string - enum: - - url_citation - description: The citation type. Always `url_citation`. - default: url_citation - x-stainless-const: true - start_index: - type: integer - minimum: 0 - description: The index of the first character of the citation in the message. - end_index: - type: integer - minimum: 0 - description: The index of the last character of the citation in the message. - url: - type: string - format: uri - description: The URL of the cited resource. - title: - type: string - description: The title of the cited resource. - type: object - required: - - type - - start_index - - end_index - - url - - title - BetaFileCitationParam: - properties: - type: - type: string - enum: - - file_citation - description: The citation type. Always `file_citation`. - default: file_citation - x-stainless-const: true - index: - type: integer - minimum: 0 - description: The index of the file in the list of files. - file_id: - type: string - description: The ID of the file. - example: file-123 - filename: - type: string - description: The filename of the file cited. - type: object - required: - - type - - index - - file_id - - filename - BetaMultiAgentAction1: - type: string - enum: - - spawn_agent - - interrupt_agent - - list_agents - - send_message - - followup_task - - wait_agent - BetaMultiAgentCallItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of this multi-agent call. - example: mac_123 - - type: 'null' - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The unique ID linking this call to its output. - type: - type: string - enum: - - multi_agent_call - description: The item type. Always `multi_agent_call`. - default: multi_agent_call - x-stainless-const: true - action: - $ref: '#/components/schemas/BetaMultiAgentAction1' - description: The multi-agent action that was executed. - arguments: - type: string - description: The action arguments as a JSON string. - type: object - required: - - call_id - - type - - action - - arguments - x-oai-beta: responses_multi_agent=v1 - BetaAgentMessageItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of this agent message item. - example: amsg_123 - - type: 'null' - type: - type: string - enum: - - agent_message - description: The item type. Always `agent_message`. - default: agent_message - x-stainless-const: true - author: - type: string - description: The sending agent identity. - recipient: - type: string - description: The destination agent identity. - content: - items: - discriminator: - propertyName: type - description: A plaintext, image, or encrypted agent message content part. - anyOf: - - $ref: '#/components/schemas/BetaInputTextContentParam' - - $ref: '#/components/schemas/BetaInputImageContentParamAutoParam' - - $ref: '#/components/schemas/BetaEncryptedContentParam' - type: array - description: Plaintext, image, or encrypted content sent between agents. - type: object - required: - - type - - author - - recipient - - content - title: Agent message - description: A message routed between agents. - x-oai-beta: responses_multi_agent=v1 - BetaEncryptedContentParam: - properties: - type: - type: string - enum: - - encrypted_content - description: The type of the input item. Always `encrypted_content`. - default: encrypted_content - x-stainless-const: true - encrypted_content: - type: string - maxLength: 10485760 - description: Opaque encrypted content. - type: object - required: - - type - - encrypted_content - title: Encrypted content - description: Opaque encrypted content that Responses API decrypts inside trusted model execution. - x-oai-beta: responses_multi_agent=v1 - BetaInputImageContentParamAutoParam: - properties: - type: - type: string - enum: - - input_image - description: The type of the input item. Always `input_image`. - default: input_image - x-stainless-const: true - image_url: - anyOf: - - type: string - maxLength: 20971520 - format: uri - description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - type: 'null' - file_id: - anyOf: - - type: string - description: The ID of the file to be sent to the model. - example: file-123 - - type: 'null' - detail: - anyOf: - - $ref: '#/components/schemas/BetaDetailEnum' - description: The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - type: 'null' - prompt_cache_breakpoint: - anyOf: - - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' - - type: 'null' - type: object - required: - - type - title: Input image - description: An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision) - BetaPromptCacheBreakpointParam: - properties: - mode: - type: string - enum: - - explicit - description: The breakpoint mode. Always `explicit`. - default: explicit - x-stainless-const: true - type: object - required: - - mode - title: Prompt cache breakpoint - description: Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - BetaDetailEnum: - type: string - enum: - - low - - high - - auto - - original - BetaInputTextContentParam: - properties: - type: - type: string - enum: - - input_text - description: The type of the input item. Always `input_text`. - default: input_text - x-stainless-const: true - text: - type: string - maxLength: 10485760 - description: The text input to the model. - prompt_cache_breakpoint: - anyOf: - - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' - - type: 'null' - type: object - required: - - type - - text - title: Input text - description: A text input to the model. - BetaFunctionCallOutputItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The unique ID of the function tool call output. Populated when this item is returned via API. - example: fc_123 - - type: 'null' - call_id: - anyOf: - - type: string - maxLength: 64 - minLength: 1 - description: The unique ID of the function tool call generated by the model. - - type: 'null' - type: - type: string - enum: - - function_call_output - description: The type of the function tool call output. Always `function_call_output`. - default: function_call_output - x-stainless-const: true - output: - description: Text, image, or file output of the function tool call. - anyOf: - - type: string - maxLength: 10485760 - description: A JSON string of the output of the function tool call. - - items: - discriminator: - propertyName: type - description: A piece of message content, such as text, an image, or a file. - anyOf: - - $ref: '#/components/schemas/BetaInputTextContentParam' - - $ref: '#/components/schemas/BetaInputImageContentParamAutoParam' - - $ref: '#/components/schemas/BetaInputFileContentParam' - type: array - description: An array of content outputs (text, image, file) for the function tool call. - name: - anyOf: - - type: string - maxLength: 128 - minLength: 1 - description: The name of the tool that produced the output. - - type: 'null' - namespace: - anyOf: - - type: string - maxLength: 64 - minLength: 1 - pattern: ^[a-zA-Z0-9_-]+$ - description: The namespace of the tool that produced the output. - - type: 'null' - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - description: The execution context that produced this tool call. - - type: 'null' - status: - anyOf: - - $ref: '#/components/schemas/BetaFunctionCallItemStatus' - description: The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - type: 'null' - type: object - required: - - type - - output - title: Function tool call output - description: The output of a function tool call. - BetaInputFileContentParam: - properties: - type: - type: string - enum: - - input_file - description: The type of the input item. Always `input_file`. - default: input_file - x-stainless-const: true - file_id: - anyOf: - - type: string - description: The ID of the file to be sent to the model. - example: file-123 - - type: 'null' - filename: - anyOf: - - type: string - description: The name of the file to be sent to the model. - - type: 'null' - file_data: - anyOf: - - type: string - maxLength: 73400320 - description: The base64-encoded data of the file to be sent to the model. - - type: 'null' - file_url: - anyOf: - - type: string - format: uri - description: The URL of the file to be sent to the model. - - type: 'null' - detail: - $ref: '#/components/schemas/BetaFileDetailEnum' - description: The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. - prompt_cache_breakpoint: - anyOf: - - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' - - type: 'null' - type: object - required: - - type - title: Input file - description: A file input to the model. - BetaFileDetailEnum: - type: string - enum: - - auto - - low - - high - BetaFunctionToolCall: - type: object - title: Function tool call - description: | - A tool call to run a function. See the - [function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - id: - type: string - description: | - The unique ID of the function tool call. - type: - type: string - enum: - - function_call - description: | - The type of the function tool call. Always `function_call`. - x-stainless-const: true - call_id: - type: string - description: | - The unique ID of the function tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCaller' - - type: 'null' - namespace: - type: string - description: | - The namespace of the function to run. - name: - type: string - description: | - The name of the function to run. - arguments: - type: string - description: | - A JSON string of the arguments to pass to the function. - status: - type: string - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - enum: - - in_progress - - completed - - incomplete - async: - type: boolean - description: | - Whether the function tool call runs asynchronously. - required: - - type - - call_id - - name - - arguments - BetaWebSearchToolCall: - type: object - title: Web search tool call - description: | - The results of a web search tool call. See the - [web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - id: - type: string - description: | - The unique ID of the web search tool call. - type: - type: string - enum: - - web_search_call - description: | - The type of the web search tool call. Always `web_search_call`. - x-stainless-const: true - status: - description: | - The status of the web search tool call. - $ref: '#/components/schemas/BetaWebSearchCallStatus' - action: - type: object - description: | - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaWebSearchActionSearch' - - $ref: '#/components/schemas/BetaWebSearchActionOpenPage' - - $ref: '#/components/schemas/BetaWebSearchActionFind' - required: - - id - - type - - status - - action - BetaWebSearchActionFind: - type: object - title: Find action - description: | - Action type "find_in_page": Searches for a pattern within a loaded page. - properties: - type: - type: string - enum: - - find_in_page - description: | - The action type. - x-stainless-const: true - url: - type: string - format: uri - description: | - The URL of the page searched for the pattern. - pattern: - type: string - description: | - The pattern or text to search for within the page. - required: - - type - - url - - pattern - BetaWebSearchActionOpenPage: - type: object - title: Open page action - description: | - Action type "open_page" - Opens a specific URL from search results. - properties: - type: - type: string - enum: - - open_page - description: | - The action type. - x-stainless-const: true - url: - description: | - The URL opened by the model. - anyOf: - - type: string - format: uri - - type: 'null' - required: - - type - BetaWebSearchActionSearch: - type: object - title: Search action - description: | - Action type "search" - Performs a web search query. - properties: - type: - type: string - enum: - - search - description: | - The action type. - x-stainless-const: true - query: - type: string - deprecated: true - description: | - The search query. - queries: - type: array - title: Search queries - description: | - The search queries. - items: - type: string - description: | - A search query. - sources: - type: array - title: Web search sources - description: | - The sources used in the search. - items: - type: object - title: Web search source - description: | - A source used in the search. - properties: - type: - type: string - enum: - - url - description: | - The type of source. Always `url`. - x-stainless-const: true - url: - type: string - format: uri - description: | - The URL of the source. - required: - - type - - url - required: - - type - BetaWebSearchCallStatus: - type: string - enum: - - in_progress - - searching - - completed - - failed - - incomplete - BetaComputerCallOutputItemParam: - properties: - agent: - anyOf: - - $ref: '#/components/schemas/Beta_AgentTagParam' - description: The agent that produced this item. - - type: 'null' - id: - anyOf: - - type: string - description: The ID of the computer tool call output. - example: cuo_123 - - type: 'null' - call_id: - type: string - maxLength: 64 - minLength: 1 - description: The ID of the computer tool call that produced the output. - type: - type: string - enum: - - computer_call_output - description: The type of the computer tool call output. Always `computer_call_output`. - default: computer_call_output - x-stainless-const: true - output: - $ref: '#/components/schemas/BetaComputerScreenshotImage' - acknowledged_safety_checks: - anyOf: - - items: - $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' - type: array - description: The safety checks reported by the API that have been acknowledged by the developer. - - type: 'null' - status: - anyOf: - - $ref: '#/components/schemas/BetaFunctionCallItemStatus' - description: The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - type: 'null' - type: object - required: - - call_id - - type - - output - title: Computer tool call output - description: The output of a computer tool call. - BetaComputerCallSafetyCheckParam: - properties: - id: - type: string - description: The ID of the pending safety check. - code: - anyOf: - - type: string - description: The type of the pending safety check. - - type: 'null' - message: - anyOf: - - type: string - description: Details about the pending safety check. - - type: 'null' - type: object - required: - - id - description: A pending safety check for the computer call. - BetaComputerScreenshotImage: - type: object - description: | - A computer screenshot image used with the computer use tool. - properties: - type: - type: string - enum: - - computer_screenshot - default: computer_screenshot - description: "Specifies the event type. For a computer screenshot, this property is \nalways set to `computer_screenshot`.\n" - x-stainless-const: true - image_url: - type: string - format: uri - description: The URL of the screenshot image. - file_id: - type: string - description: The identifier of an uploaded file that contains the screenshot. - required: - - type - BetaComputerToolCall: - type: object - title: Computer tool call - description: | - A tool call to a computer use tool. See the - [computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for more information. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: - type: string - description: The type of the computer call. Always `computer_call`. - enum: - - computer_call - default: computer_call - id: - type: string - description: The unique ID of the computer call. - call_id: - type: string - description: | - An identifier used when responding to the tool call with output. - action: - $ref: '#/components/schemas/BetaComputerAction' - actions: - $ref: '#/components/schemas/BetaComputerActionList' - pending_safety_checks: - type: array - items: - $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' - description: | - The pending safety checks for the computer call. - status: - type: string - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - enum: - - in_progress - - completed - - incomplete - required: - - type - - id - - call_id - - pending_safety_checks - - status - BetaComputerActionList: - title: Computer Action List - type: array - description: | - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - items: - $ref: '#/components/schemas/BetaComputerAction' - BetaComputerAction: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaClickParam' - - $ref: '#/components/schemas/BetaDoubleClickAction' - - $ref: '#/components/schemas/BetaDragParam' - - $ref: '#/components/schemas/BetaKeyPressAction' - - $ref: '#/components/schemas/BetaMoveParam' - - $ref: '#/components/schemas/BetaScreenshotParam' - - $ref: '#/components/schemas/BetaScrollParam' - - $ref: '#/components/schemas/BetaTypeParam' - - $ref: '#/components/schemas/BetaWaitParam' - BetaWaitParam: - properties: - type: - type: string - enum: - - wait - description: Specifies the event type. For a wait action, this property is always set to `wait`. - default: wait - x-stainless-const: true - type: object - required: - - type - title: Wait - description: A wait action. - BetaTypeParam: - properties: - type: - type: string - enum: - - type - description: Specifies the event type. For a type action, this property is always set to `type`. - default: type - x-stainless-const: true - text: - type: string - description: The text to type. - type: object - required: - - type - - text - title: Type - description: An action to type in text. - BetaScrollParam: - properties: - type: - type: string - enum: - - scroll - description: Specifies the event type. For a scroll action, this property is always set to `scroll`. - default: scroll - x-stainless-const: true - x: - type: integer - description: The x-coordinate where the scroll occurred. - y: - type: integer - description: The y-coordinate where the scroll occurred. - scroll_x: - type: integer - description: The horizontal scroll distance. - scroll_y: - type: integer - description: The vertical scroll distance. - keys: - anyOf: - - items: + - title: BetaResponseAudioWsDelta + description: Emitted when there is a partial audio response. + allOf: + - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseAudioWsDone + description: Emitted when the audio response is complete. + allOf: + - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseAudioTranscriptWsDelta + description: Emitted when there is a partial transcript of audio. + allOf: + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseAudioTranscriptWsDone + description: Emitted when the full audio transcript is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCodeInterpreterCallCodeWsDelta + description: Emitted when a partial code snippet is streamed by the code interpreter. + allOf: + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCodeInterpreterCallCodeWsDone + description: Emitted when the code snippet is finalized by the code interpreter. + allOf: + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCodeInterpreterCallWsCompleted + description: Emitted when the code interpreter call is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCodeInterpreterCallInWsProgress + description: Emitted when a code interpreter call is in progress. + allOf: + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCodeInterpreterCallWsInterpreting + description: Emitted when the code interpreter is actively interpreting the code snippet. + allOf: + - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCompactionWsCompacting + description: Emitted when new summary content is sampled for a compaction trigger. Contains no summary content. + allOf: + - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWsCompleted + description: Emitted when the model response is complete. + allOf: + - $ref: '#/components/schemas/BetaResponseCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseContentPartWsAdded + description: Emitted when a new content part is added. + allOf: + - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseContentPartWsDone + description: Emitted when a content part is done. + allOf: + - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWsCreated + description: | + An event that is emitted when a response is created. + allOf: + - $ref: '#/components/schemas/BetaResponseCreatedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseFileSearchCallWsCompleted + description: Emitted when a file search call is completed (results found). + allOf: + - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseFileSearchCallInWsProgress + description: Emitted when a file search call is initiated. + allOf: + - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseFileSearchCallWsSearching + description: Emitted when a file search is currently searching. + allOf: + - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseFunctionCallArgumentsWsDelta + description: Emitted when there is a partial function-call arguments delta. + allOf: + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseFunctionCallArgumentsWsDone + description: Emitted when function-call arguments are finalized. + allOf: + - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseShellCallCommandWsAdded + description: A streaming event that indicated a shell command was added to a tool call. + allOf: + - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseShellCallCommandWsDelta + description: A streaming event that indicated a shell command was incrementally updated. + allOf: + - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseShellCallCommandWsDone + description: A streaming event that indicated a shell command was completed. + allOf: + - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseShellCallOutputContentWsDelta + description: A streaming event that indicated shell call output was incrementally added. + allOf: + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' + x-stainless-skip: + - go + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseShellCallOutputContentWsDone + description: A streaming event that indicated shell call output was completed. + allOf: + - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseInWsProgress + description: Emitted when the response is in progress. + allOf: + - $ref: '#/components/schemas/BetaResponseInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWsFailed + description: | + An event that is emitted when a response fails. + allOf: + - $ref: '#/components/schemas/BetaResponseFailedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWsIncomplete + description: | + An event that is emitted when a response finishes as incomplete. + + Over WebSocket, steering can finish a response with + `response.incomplete_details.reason` set to `steered`, followed automatically + by a successor `response.created` that commits the queued steering input. + allOf: + - $ref: '#/components/schemas/BetaResponseIncompleteEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseOutputItemWsAdded + description: Emitted when a new output item is added. + allOf: + - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseOutputItemWsDone + description: Emitted when an output item is marked done. + allOf: + - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningSummaryPartWsAdded + description: Emitted when a new reasoning summary part is added. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningSummaryPartWsDone + description: Emitted when a reasoning summary part is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningSummaryTextWsDelta + description: Emitted when a delta is added to a reasoning summary text. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningSummaryTextWsDone + description: Emitted when a reasoning summary text is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningTextWsDelta + description: Emitted when a delta is added to a reasoning text. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseReasoningTextWsDone + description: Emitted when a reasoning text is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseRefusalWsDelta + description: Emitted when there is a partial refusal text. + allOf: + - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseRefusalWsDone + description: Emitted when refusal text is finalized. + allOf: + - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseTextWsDelta + description: Emitted when there is an additional text delta. + allOf: + - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseTextWsDone + description: Emitted when text content is finalized. + allOf: + - $ref: '#/components/schemas/BetaResponseTextDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWebSearchCallWsCompleted + description: Emitted when a web search call is completed. + allOf: + - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWebSearchCallInWsProgress + description: Emitted when a web search call is initiated. + allOf: + - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWebSearchCallWsSearching + description: Emitted when a web search call is executing. + allOf: + - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseImageGenCallWsCompleted + description: | + Emitted when an image generation tool call has completed and the final image is available. + allOf: + - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseImageGenCallWsGenerating + description: | + Emitted when an image generation tool call is actively generating an image (intermediate state). + allOf: + - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseImageGenCallInWsProgress + description: | + Emitted when an image generation tool call is in progress. + allOf: + - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseImageGenCallPartialWsImage + description: | + Emitted when a partial image is available during image generation streaming. + allOf: + - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpCallArgumentsWsDelta + description: | + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpCallArgumentsWsDone + description: | + Emitted when the arguments for an MCP tool call are finalized. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' + - type: object + properties: + stream_id: type: string - type: array - description: The keys being held while scrolling. - - type: 'null' - type: object - required: - - type - - x - - y - - scroll_x - - scroll_y - title: Scroll - description: A scroll action. - BetaScreenshotParam: - properties: - type: - type: string - enum: - - screenshot - description: Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - default: screenshot - x-stainless-const: true - type: object - required: - - type - title: Screenshot - description: A screenshot action. - BetaMoveParam: - properties: - type: - type: string - enum: - - move - description: Specifies the event type. For a move action, this property is always set to `move`. - default: move - x-stainless-const: true - x: - type: integer - description: The x-coordinate to move to. - y: - type: integer - description: The y-coordinate to move to. - keys: - anyOf: - - items: + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpCallWsCompleted + description: | + Emitted when an MCP tool call has completed successfully. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' + - type: object + properties: + stream_id: type: string - type: array - description: The keys being held while moving the mouse. - - type: 'null' - type: object - required: - - type - - x - - y - title: Move - description: A mouse move action. - BetaKeyPressAction: - properties: - type: - type: string - enum: - - keypress - description: Specifies the event type. For a keypress action, this property is always set to `keypress`. - default: keypress - x-stainless-const: true - keys: - items: - type: string - description: One of the keys the model is requesting to be pressed. - type: array - description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - type: object - required: - - type - - keys - title: KeyPress - description: A collection of keypresses the model would like to perform. - BetaDragParam: - properties: - type: - type: string - enum: - - drag - description: Specifies the event type. For a drag action, this property is always set to `drag`. - default: drag - x-stainless-const: true - path: - items: - $ref: '#/components/schemas/BetaCoordParam' - type: array - description: |- - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` - keys: - anyOf: - - items: + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpCallWsFailed + description: | + Emitted when an MCP tool call has failed. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' + - type: object + properties: + stream_id: type: string - type: array - description: The keys being held while dragging the mouse. - - type: 'null' - type: object - required: - - type - - path - title: Drag - description: A drag action. - BetaCoordParam: - properties: - x: - type: integer - description: The x-coordinate. - y: - type: integer - description: The y-coordinate. - type: object - required: - - x - - y - title: Coordinate - description: 'An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.' - BetaDoubleClickAction: - properties: - type: - type: string - enum: - - double_click - description: Specifies the event type. For a double click action, this property is always set to `double_click`. - default: double_click - x-stainless-const: true - x: - type: integer - description: The x-coordinate where the double click occurred. - y: - type: integer - description: The y-coordinate where the double click occurred. - keys: - anyOf: - - items: + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpCallInWsProgress + description: | + Emitted when an MCP tool call is in progress. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' + - type: object + properties: + stream_id: type: string - type: array - description: The keys being held while double-clicking. - - type: 'null' - type: object - required: - - type - - x - - y - - keys - title: DoubleClick - description: A double click action. - BetaClickParam: - properties: - type: - type: string - enum: - - click - description: Specifies the event type. For a click action, this property is always `click`. - default: click - x-stainless-const: true - button: - $ref: '#/components/schemas/BetaClickButtonType' - description: Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - x: - type: integer - description: The x-coordinate where the click occurred. - y: - type: integer - description: The y-coordinate where the click occurred. - keys: - anyOf: - - items: + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpListToolsWsCompleted + description: | + Emitted when the list of available MCP tools has been successfully retrieved. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' + - type: object + properties: + stream_id: type: string - type: array - description: The keys being held while clicking. - - type: 'null' - type: object - required: - - type - - button - - x - - y - title: Click - description: A click action. - BetaClickButtonType: - type: string - enum: - - left - - right - - wheel - - back - - forward - BetaFileSearchToolCall: - type: object - title: File search tool call - description: | - The results of a file search tool call. See the - [file search guide](https://developers.openai.com/api/docs/guides/tools-file-search) for more information. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - id: - type: string - description: | - The unique ID of the file search tool call. - type: - type: string - enum: - - file_search_call - description: | - The type of the file search tool call. Always `file_search_call`. - x-stainless-const: true - status: - type: string - description: | - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, - enum: - - in_progress - - searching - - completed - - incomplete - - failed - queries: - type: array - items: - type: string - description: | - The queries used to search for files. - results: - anyOf: - - type: array - description: | - The results of the file search tool call. - items: - type: object - properties: - file_id: - type: string - description: | - The unique ID of the file. - text: - type: string - description: | - The text that was retrieved from the file. - filename: - type: string - description: | - The name of the file. - attributes: - $ref: '#/components/schemas/BetaVectorStoreFileAttributes' - score: - type: number - format: float - description: | - The relevance score of the file - a value between 0 and 1. - - type: 'null' - required: - - id - - type - - status - - queries - BetaVectorStoreFileAttributes: - anyOf: - - type: object + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpListToolsWsFailed description: | - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. - maxProperties: 16 - propertyNames: - type: string - maxLength: 64 - additionalProperties: - anyOf: - - type: string - maxLength: 512 - - type: number - - type: boolean - x-oaiTypeLabel: map - - type: 'null' - BetaOutputMessage: + Emitted when the attempt to list available MCP tools has failed. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseMcpListToolsInWsProgress + description: | + Emitted when the system is in the process of retrieving the list of available MCP tools. + allOf: + - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseOutputTextAnnotationWsAdded + description: | + Emitted when an annotation is added to output text content. + allOf: + - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseWsQueued + description: | + Emitted when a response is queued and waiting to be processed. + allOf: + - $ref: '#/components/schemas/BetaResponseQueuedEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCustomToolCallInputWsDelta + description: | + Event representing a delta (partial update) to the input of a custom tool call. + allOf: + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - title: BetaResponseCustomToolCallInputWsDone + description: | + Event indicating that input for a custom tool call is complete. + allOf: + - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' + - type: object + properties: + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present + when the originating `response.create` event supplied a + `stream_id`. + - $ref: '#/components/schemas/BetaResponseWsError' + - $ref: '#/components/schemas/BetaResponseSteerAcceptedEvent' + - $ref: '#/components/schemas/BetaResponseSteerPendingEvent' + - $ref: '#/components/schemas/BetaResponseSteerFailedEvent' + - $ref: '#/components/schemas/BetaResponseInjectCreatedEvent' + - $ref: '#/components/schemas/BetaResponseInjectFailedEvent' + BetaResponseInjectFailedEvent: type: object - title: Output message + title: ResponseInjectFailedEvent description: | - An output message from the model. + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - id: - type: string - description: | - The unique ID of the output message. - x-stainless-go-json: omitzero type: type: string - description: | - The type of the output message. Always `message`. enum: - - message + - response.inject.failed + description: The event discriminator. Always `response.inject.failed`. x-stainless-const: true - role: + response_id: type: string - description: | - The role of the output message. Always `assistant`. - enum: - - assistant - x-stainless-const: true - content: + description: The ID of the response that rejected the input. + input: type: array - description: | - The content of the output message. + description: The raw input items that were not committed. items: - $ref: '#/components/schemas/BetaOutputMessageContent' - phase: - anyOf: - - $ref: '#/components/schemas/BetaMessagePhase' - - type: 'null' - status: - type: string - description: | - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - enum: - - in_progress - - completed - - incomplete - required: - - id - - type - - role - - content - - status - BetaMessagePhase: - type: string - description: | - 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. - enum: - - commentary - - final_answer - BetaOutputMessageContent: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaOutputTextContent' - - $ref: '#/components/schemas/BetaRefusalContent' - BetaRefusalContent: - properties: - type: - type: string - enum: - - refusal - description: The type of the refusal. Always `refusal`. - default: refusal - x-stainless-const: true - refusal: + $ref: '#/components/schemas/BetaInputItem' + error: + type: object + description: Information about why the input was not committed. + properties: + code: + type: string + enum: + - response_already_completed + - response_not_found + description: A machine-readable error code. + message: + type: string + description: A human-readable description of the error. + required: + - code + - message + sequence_number: + type: integer + description: The sequence number for this event. + stream_id: type: string - description: The refusal explanation from the model. - type: object + description: | + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. required: - type - - refusal - title: Refusal - description: A refusal from the model. - BetaOutputTextContent: + - response_id + - input + - error + - sequence_number + x-oai-beta: responses_multi_agent=v1 + x-oaiMeta: + example: | + { + "type": "response.inject.failed", + "response_id": "resp_123", + "input": [ + { + "type": "function_call_output", + "call_id": "call_123", + "output": "{\"temperature\":72}" + } + ], + "error": { + "code": "response_already_completed", + "message": "Response 'resp_123' has already completed." + }, + "sequence_number": 9 + } + BetaResponseInjectCreatedEvent: + type: object + title: ResponseInjectCreatedEvent + description: | + Emitted when all injected input items were validated and committed to the + active response. properties: type: type: string enum: - - output_text - description: The type of the output text. Always `output_text`. - default: output_text + - response.inject.created + description: The event discriminator. Always `response.inject.created`. x-stainless-const: true - text: + response_id: type: string - description: The text output from the model. - annotations: - items: - $ref: '#/components/schemas/BetaAnnotation' - type: array - description: The annotations of the text output. - logprobs: - items: - $ref: '#/components/schemas/BetaLogProb' - type: array - type: object - required: - - type - - text - - annotations - title: Output text - description: A text output from the model. - BetaLogProb: - properties: - token: + description: The ID of the response that accepted the input. + sequence_number: + type: integer + description: The sequence number for this event. + stream_id: type: string - logprob: - type: number - bytes: - items: - type: integer - type: array - top_logprobs: - items: - $ref: '#/components/schemas/BetaTopLogProb' - type: array - type: object + description: | + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. required: - - token - - logprob - - bytes - - top_logprobs - title: Log probability - description: The log probability of a token. - BetaTopLogProb: + - type + - response_id + - sequence_number + x-oai-beta: responses_multi_agent=v1 + x-oaiMeta: + example: | + { + "type": "response.inject.created", + "response_id": "resp_123", + "sequence_number": 8 + } + BetaModerationPolicyParam: properties: - token: - type: string - logprob: - type: number - bytes: - items: - type: integer - type: array + input: + anyOf: + - $ref: '#/components/schemas/BetaModerationConfigParam' + description: The moderation policy for the response input. + - type: 'null' + output: + anyOf: + - $ref: '#/components/schemas/BetaModerationConfigParam' + description: The moderation policy for the response output. + - type: 'null' type: object - required: - - token - - logprob - - bytes - title: Top log probability - description: The top log probability of a token. - BetaAnnotation: + required: [] + description: The policy to apply to moderated response input and output. + CreateVaultCredentialAuthParam: + description: Authentication credentials for an MCP server used by agent tools. discriminator: propertyName: type - description: An annotation that applies to a span of output text. + mapping: + mcp_oauth: '#/components/schemas/CreateVaultCredentialAuthParamMcpOauth' + static_bearer: '#/components/schemas/CreateVaultCredentialAuthParamStaticBearer' + x-oai-discriminator-values: + - mcp_oauth + - static_bearer anyOf: - - $ref: '#/components/schemas/BetaFileCitationBody' - - $ref: '#/components/schemas/BetaUrlCitationBody' - - $ref: '#/components/schemas/BetaContainerFileCitationBody' - - $ref: '#/components/schemas/BetaFilePath' - BetaFilePath: + - $ref: '#/components/schemas/CreateVaultCredentialAuthParamMcpOauth' + - $ref: '#/components/schemas/CreateVaultCredentialAuthParamStaticBearer' + CreateVaultCredentialParams: type: object - title: File path - description: | - A path to a file. properties: - type: - type: string - description: | - The type of the file path. Always `file_path`. - enum: - - file_path - x-stainless-const: true - file_id: + name: type: string - description: | - The ID of the file. - index: - type: integer - description: | - The index of the file in the list of files. + minLength: 1 + maxLength: 1048576 + description: The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming. + auth: + $ref: '#/components/schemas/CreateVaultCredentialAuthParam' + description: The authentication method and secret values to store for the MCP server. required: - - type - - file_id - - index - BetaContainerFileCitationBody: + - auth + - name + additionalProperties: false + description: Parameters for storing a credential that authorizes access to an MCP server. + RotateMcpOauthTokenEndpointAuthParamClientSecretBasic: + type: object properties: type: type: string enum: - - container_file_citation - description: The type of the container file citation. Always `container_file_citation`. - default: container_file_citation + - client_secret_basic + default: client_secret_basic x-stainless-const: true - container_id: - type: string - description: The ID of the container file. - file_id: - type: string - description: The ID of the file. - start_index: - type: integer - description: The index of the first character of the container file citation in the message. - end_index: - type: integer - description: The index of the last character of the container file citation in the message. - filename: - type: string - description: The filename of the container file cited. - type: object + description: The type of the object. Always `client_secret_basic`. + client_secret: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. required: - type - - container_id - - file_id - - start_index - - end_index - - filename - title: Container file citation - description: A citation for a container file used to generate a model response. - BetaUrlCitationBody: + additionalProperties: false + description: Updates credentials sent using HTTP Basic authentication. + RotateMcpOauthTokenEndpointAuthParamClientSecretPost: + type: object properties: type: type: string enum: - - url_citation - description: The type of the URL citation. Always `url_citation`. - default: url_citation + - client_secret_post + default: client_secret_post x-stainless-const: true - url: - type: string - format: uri - description: The URL of the web resource. - start_index: - type: integer - description: The index of the first character of the URL citation in the message. - end_index: - type: integer - description: The index of the last character of the URL citation in the message. - title: - type: string - description: The title of the web resource. - type: object + description: The type of the object. Always `client_secret_post`. + client_secret: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources. required: - type - - url - - start_index - - end_index - - title - title: URL citation - description: A citation for a web resource used to generate a model response. - BetaFileCitationBody: + additionalProperties: false + description: Updates credentials sent in the token request body. + RotateMcpOauthTokenEndpointAuthParam: + description: Client-secret updates that preserve the credential's OAuth authentication method. + discriminator: + propertyName: type + mapping: + client_secret_basic: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretBasic' + client_secret_post: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretPost' + x-oai-discriminator-values: + - client_secret_basic + - client_secret_post + anyOf: + - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretBasic' + - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretPost' + RotateMcpOauthRefreshParam: + type: object + properties: + refresh_token: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The replacement refresh token. Omit or pass `null` to keep the stored token. This secret is never returned in resources. + scope: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: Replacement space-separated OAuth scopes for refresh requests. Omit to keep the scopes, or pass `null` to stop sending a scope parameter. + token_endpoint_auth: + anyOf: + - $ref: '#/components/schemas/RotateMcpOauthTokenEndpointAuthParam' + - type: 'null' + description: Client-secret updates for the existing token endpoint authentication method. + additionalProperties: false + description: Updates to an MCP credential's existing OAuth refresh configuration. + RotateVaultCredentialAuthParamMcpOauth: + type: object properties: type: type: string enum: - - file_citation - description: The type of the file citation. Always `file_citation`. - default: file_citation + - mcp_oauth + default: mcp_oauth x-stainless-const: true - file_id: - type: string - description: The ID of the file. - index: - type: integer - description: The index of the file in the list of files. - filename: - type: string - description: The filename of the file cited. - type: object + description: The type of the object. Always `mcp_oauth`. + access_token: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: A write-only replacement OAuth access token. + expires_at: + type: + - string + - 'null' + minLength: 0 + maxLength: 1048576 + description: The replacement expiry as an RFC 3339 timestamp, or `null` to clear it. Omitting this field preserves the expiry unless a new access token is supplied, in which case the expiry is cleared. + refresh: + anyOf: + - $ref: '#/components/schemas/RotateMcpOauthRefreshParam' + - type: 'null' + description: Optional write-only refresh-token and client-secret updates. required: - type - - file_id - - index - - filename - title: File citation - description: A citation to a file. - BetaInputMessage: + additionalProperties: false + description: Rotate an OAuth credential for an HTTPS MCP destination. + RotateVaultCredentialAuthParamStaticBearer: type: object - title: Input message - description: | - 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. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. type: type: string - description: | - The type of the message input. Always set to `message`. enum: - - message + - static_bearer + default: static_bearer x-stainless-const: true - role: - type: string - description: | - The role of the message input. One of `user`, `system`, or `developer`. - enum: - - user - - system - - developer - status: + description: The type of the object. Always `static_bearer`. + token: type: string - description: | - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - enum: - - in_progress - - completed - - incomplete - content: - $ref: '#/components/schemas/BetaInputMessageContentList' + minLength: 0 + maxLength: 1048576 + description: The replacement bearer token. This secret is never returned in credential resources. required: - - role - - content - BetaInputMessageContentList: - type: array - title: Input item content list - description: "A list of one or many input items to the model, containing different content \ntypes.\n" - items: - $ref: '#/components/schemas/BetaInputContent' - BetaInputContent: + - type + - token + additionalProperties: false + description: Replace the bearer token for the credential's MCP server. + BetaResponsesClientEventResponseCreate: + allOf: + - type: object + properties: + type: + type: string + enum: + - response.create + description: | + The type of the client event. Always `response.create`. + x-stainless-const: true + stream_id: + type: string + minLength: 1 + maxLength: 256 + pattern: ^[A-Za-z0-9_.-]+$ + description: | + The WebSocket lane for this response. Requests with the same + `stream_id` are processed FIFO, and events for the response echo the + same `stream_id`. + + `stream_id` controls routing; `previous_response_id` controls + conversation lineage, so a new lane can fork from a response created + on another lane. + required: + - type + - $ref: '#/components/schemas/BetaCreateResponse' + description: | + Client event for creating a response over a persistent WebSocket connection. + This payload uses the same top-level fields as `POST /v1/responses`, plus + WebSocket-only envelope metadata. + + Notes: + - `stream` is implicit over WebSocket and should not be sent. + - `background` is not supported over WebSocket. + - `stream_id` is WebSocket-only and is not part of `POST /v1/responses`. + x-oaiMeta: + example: | + { + "type": "response.create", + "stream_id": "agent_1", + "model": "gpt-6-astra", + "input": "Say hello." + } + RotateVaultCredentialAuthParam: + description: Updates to a vault credential without changing its authentication method or MCP server. discriminator: propertyName: type + mapping: + mcp_oauth: '#/components/schemas/RotateVaultCredentialAuthParamMcpOauth' + static_bearer: '#/components/schemas/RotateVaultCredentialAuthParamStaticBearer' + x-oai-discriminator-values: + - mcp_oauth + - static_bearer anyOf: - - $ref: '#/components/schemas/BetaInputTextContent' - - $ref: '#/components/schemas/BetaInputImageContent' - - $ref: '#/components/schemas/BetaInputFileContent' - BetaEasyInputMessage: + - $ref: '#/components/schemas/RotateVaultCredentialAuthParamMcpOauth' + - $ref: '#/components/schemas/RotateVaultCredentialAuthParamStaticBearer' + RotateVaultCredentialParams: type: object - title: Input message - description: | - 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. properties: - role: - type: string - description: | - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. - enum: - - user - - assistant - - system - - developer - content: - description: | - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. - anyOf: - - type: string - title: Text input - description: | - A text input to the model. - - $ref: '#/components/schemas/BetaInputMessageContentList' - phase: - anyOf: - - $ref: '#/components/schemas/BetaMessagePhase' - - type: 'null' - type: + auth: + $ref: '#/components/schemas/RotateVaultCredentialAuthParam' + description: Replacement values for the credential's existing authentication method. + required: + - auth + additionalProperties: false + description: Secret, expiry, and OAuth refresh scope updates for an existing vault credential. + DeletedVaultCredentialResource: + type: object + properties: + id: + type: string + minLength: 0 + description: The ID of the deleted credential. + object: type: string - description: | - The type of the message input. Always `message`. enum: - - message + - vault.credential.deleted + default: vault.credential.deleted x-stainless-const: true + description: The object type. Always `vault.credential.deleted`. + deleted: + type: boolean + description: Whether the resource was deleted. Always `true`. required: - - role - - content - BetaCompactResponseMethodPublicBody: + - id + - object + - deleted + additionalProperties: false + description: Confirmation that a vault credential was deleted. + WebhookEndpointBody: properties: - model: - $ref: '#/components/schemas/BetaModelIdsCompaction' - input: - anyOf: - - description: Text, image, or file inputs to the model, used to generate a response - anyOf: - - type: string - maxLength: 10485760 - description: A text input to the model, equivalent to a text input with the `user` role. - - items: - $ref: '#/components/schemas/BetaInputItem' - type: array - maxItems: 131072 - description: A list of one or many input items to the model, containing different content types. - - type: 'null' - previous_response_id: + id: + type: string + description: The unique ID of the webhook endpoint. + object: + type: string + enum: + - webhook_endpoint + description: The object type, which is always webhook_endpoint. + default: webhook_endpoint + x-stainless-const: true + created_at: + type: integer + format: unixtime + description: The Unix timestamp when the endpoint was created. + updated_at: + type: integer + format: unixtime + description: The Unix timestamp of the last endpoint configuration or signing-secret change. Initialized at creation; tests and unchanged updates do not advance it. + name: + type: string + description: The human-readable name of the endpoint. + url: + type: string + description: The HTTPS URL that receives webhook deliveries. + event_types: + items: + type: string + type: array + description: The event types that trigger deliveries to this endpoint. + signing_secret_hint: anyOf: - type: string - description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - example: resp_123 + description: A masked hint for the endpoint's signing secret. - type: 'null' - instructions: + type: object + required: + - id + - object + - created_at + - name + - url + - event_types + - signing_secret_hint + WebhookEndpointListResource: + properties: + object: + type: string + enum: + - list + description: The object type, which is always list. + default: list + x-stainless-const: true + data: + items: + $ref: '#/components/schemas/WebhookEndpointBody' + type: array + description: The webhook endpoints in this page. + first_id: anyOf: - type: string - description: |- - A system (or developer) message inserted into the model's context. - When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + description: The ID of the first endpoint in this page. - type: 'null' - prompt_cache_key: + last_id: anyOf: - type: string - maxLength: 64 - description: A key to use when reading from or writing to the prompt cache. - - type: 'null' - prompt_cache_retention: - anyOf: - - $ref: '#/components/schemas/BetaPromptCacheRetentionEnum' - description: How long to retain a prompt cache entry created by this request. - deprecated: true - - type: 'null' - prompt_cache_options: - anyOf: - - $ref: '#/components/schemas/BetaPromptCacheOptionsParam' - - type: 'null' - service_tier: - anyOf: - - $ref: '#/components/schemas/BetaServiceTierEnum' - description: |- - Specifies the processing type used for serving the request. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - If set to '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier. - To opt-in to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. For models with a dedicated Fast tier, either value resolves to `service_tier=fast`; for other models, either value resolves to `service_tier=priority`. - When not set, the default behavior is 'auto'. - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + description: The ID of the last endpoint in this page. - type: 'null' + has_more: + type: boolean + description: Whether more webhook endpoints are available. type: object required: - - model - BetaServiceTierEnum: + - object + - data + - first_id + - last_id + - has_more + ProjectEventTypeEnum: type: string enum: - - auto - - default - - fast - - flex - - priority - BetaPromptCacheOptionsParam: + - batch.completed + - batch.failed + - batch.expired + - batch.cancelled + - response.completed + - response.failed + - response.cancelled + - response.incomplete + - eval.run.succeeded + - eval.run.failed + - eval.run.canceled + - fine_tuning.job.succeeded + - fine_tuning.job.failed + - fine_tuning.job.cancelled + - realtime.call.incoming + - video.completed + - video.failed + - safety.alert.created + PublicCreateEndpointBody: properties: - ttl: - $ref: '#/components/schemas/BetaPromptCacheTTLEnum' - description: The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - mode: - $ref: '#/components/schemas/BetaPromptCacheModeEnum' - description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - type: object - required: [] - title: Prompt cache options - description: Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for current details. - BetaPromptCacheModeEnum: - type: string - enum: - - implicit - - explicit - BetaPromptCacheTTLEnum: - type: string - enum: - - 30m - BetaPromptCacheRetentionEnum: - type: string - enum: - - in_memory - - 24h - BetaModelIdsCompaction: - anyOf: - - $ref: '#/components/schemas/BetaModelIdsResponses' - - type: string - - type: 'null' - description: Model ID used to generate the response, like `gpt-6-astra`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models. - BetaModelIdsResponses: - example: gpt-6-astra - anyOf: - - $ref: '#/components/schemas/BetaModelIdsShared' - - type: string - title: ResponsesOnlyModel - enum: - - o1-pro - - o1-pro-2025-03-19 - - o3-pro - - o3-pro-2025-06-10 - - o3-deep-research - - o3-deep-research-2025-06-26 - - o4-mini-deep-research - - o4-mini-deep-research-2025-06-26 - - computer-use-preview - - computer-use-preview-2025-03-11 - - gpt-5.5-pro - - gpt-5.5-pro-2026-04-23 - - gpt-5-codex - - gpt-5-pro - - gpt-5-pro-2025-10-06 - - gpt-5.1-codex-max - - gpt-daybreak-blue-latest - - gpt-daybreak-red-latest - - gpt-5.6-cyber - BetaModelIdsShared: - example: gpt-6-astra - anyOf: - - type: string - - $ref: '#/components/schemas/ChatModel' - BetaError: + name: + type: string + maxLength: 256 + minLength: 1 + description: A human-readable name for the webhook endpoint. + url: + type: string + maxLength: 2048 + pattern: ^https:// + description: The HTTPS URL that receives webhook deliveries. + event_types: + items: + $ref: '#/components/schemas/ProjectEventTypeEnum' + type: array + minItems: 1 + description: The event types that trigger deliveries to this endpoint. type: object + required: + - name + - url + - event_types + WebhookEndpointWithSecretResource: properties: - code: - anyOf: - - type: string - - type: 'null' - message: + id: type: string - param: + description: The unique ID of the webhook endpoint. + object: + type: string + enum: + - webhook_endpoint + description: The object type, which is always webhook_endpoint. + default: webhook_endpoint + x-stainless-const: true + created_at: + type: integer + format: unixtime + description: The Unix timestamp when the endpoint was created. + updated_at: + type: integer + format: unixtime + description: The Unix timestamp of the last endpoint configuration or signing-secret change. Initialized at creation; tests and unchanged updates do not advance it. + name: + type: string + description: The human-readable name of the endpoint. + url: + type: string + description: The HTTPS URL that receives webhook deliveries. + event_types: + items: + type: string + type: array + description: The event types that trigger deliveries to this endpoint. + signing_secret_hint: anyOf: - type: string + description: A masked hint for the endpoint's signing secret. - type: 'null' - type: + signing_secret: type: string - misalignment: - $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' + description: The endpoint's signing secret. This is returned only when the endpoint is created or the secret is rotated. + type: object required: - - type - - message - - param - - code - BetaMisalignmentErrorDetailsResource: + - id + - object + - created_at + - name + - url + - event_types + - signing_secret_hint + - signing_secret + PublicUpdateEndpointBody: properties: - error_type: - $ref: '#/components/schemas/Beta_MisalignmentErrorType' - description: An optional classification; clients must accept additional values. - detailed_explanation: + name: type: string - description: The public explanation for this block. - steer: - $ref: '#/components/schemas/Beta_MisalignmentSteer' - description: An optional public continuation instruction. + maxLength: 256 + minLength: 1 + description: A new human-readable name for the webhook endpoint. + url: + type: string + maxLength: 2048 + pattern: ^https:// + description: A new HTTPS URL that receives webhook deliveries. + event_types: + items: + $ref: '#/components/schemas/ProjectEventTypeEnum' + type: array + minItems: 1 + description: The complete set of event types that should trigger deliveries. type: object required: [] - Beta_MisalignmentSteer: + DeletedWebhookEndpointResource: properties: - message: + id: type: string - description: The public continuation instruction. + description: The ID of the deleted webhook endpoint. + object: + type: string + enum: + - webhook_endpoint.deleted + description: The object type, which is always webhook_endpoint.deleted. + default: webhook_endpoint.deleted + x-stainless-const: true + deleted: + type: boolean + description: Whether the endpoint was deleted. type: object required: - - message - Beta_MisalignmentErrorType: - anyOf: - - type: string - - type: string - enum: - - potentially_unintended_data_transfer - - potentially_unintended_data_access - - potentially_unintended_destructive_activity - - other - BetaResponseItemList: + - id + - object + - deleted + PublicRotateSecretBody: + properties: + keep_old_secret_active_for_24_hours: + type: boolean + description: Whether to keep the previous signing secret valid for 24 hours after rotation. Defaults to false, which invalidates the previous secret immediately. type: object - description: A list of Response items. + required: [] + PublicTestEndpointBody: + properties: + event_type: + $ref: '#/components/schemas/ProjectEventTypeEnum' + description: The event type to send as a sample delivery. + type: object + required: + - event_type + WebhookEndpointTestResultResource: properties: object: + type: string + enum: + - webhook_endpoint.test + description: The object type, which is always webhook_endpoint.test. + default: webhook_endpoint.test x-stainless-const: true - description: The type of object returned, must be `list`. - const: list - data: - type: array - description: A list of items used to generate this response. - items: - $ref: '#/components/schemas/BetaItemResource' - has_more: - type: boolean - description: Whether there are more items available. - first_id: + webhook_endpoint_id: type: string - description: The ID of the first item in the list. - last_id: + description: The ID of the webhook endpoint that received the test. + event_type: type: string - description: The ID of the last item in the list. - required: - - object - - data - - has_more - - first_id - - last_id - x-oaiMeta: - name: The input item list - group: responses - example: | - { - "object": "list", - "data": [ - { - "id": "msg_abc123", - "type": "message", - "role": "user", - "content": [ - { - "type": "input_text", - "text": "Tell me a three sentence bedtime story about a unicorn." - } - ] - } - ], - "first_id": "msg_abc123", - "last_id": "msg_abc123", - "has_more": false - } - BetaItemResource: - description: | - Content item used to generate a response. - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaInputMessageResource' - - $ref: '#/components/schemas/BetaOutputMessage' - - $ref: '#/components/schemas/BetaFileSearchToolCall' - - $ref: '#/components/schemas/BetaComputerToolCall' - - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' - - $ref: '#/components/schemas/BetaWebSearchToolCall' - - $ref: '#/components/schemas/BetaFunctionToolCallResource' - - $ref: '#/components/schemas/BetaFunctionToolCallOutputResource' - - $ref: '#/components/schemas/BetaAgentMessage' - - $ref: '#/components/schemas/BetaMultiAgentCall' - - $ref: '#/components/schemas/BetaMultiAgentCallOutput' - - $ref: '#/components/schemas/BetaToolSearchCall' - - $ref: '#/components/schemas/BetaToolSearchOutput' - - $ref: '#/components/schemas/BetaAdditionalTools' - - $ref: '#/components/schemas/BetaResponseConfigurationUpdate' - - $ref: '#/components/schemas/BetaReasoningItem' - - $ref: '#/components/schemas/BetaProgram' - - $ref: '#/components/schemas/BetaProgramOutput' - - $ref: '#/components/schemas/BetaCompactionBody' - - $ref: '#/components/schemas/BetaImageGenToolCall' - - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' - - $ref: '#/components/schemas/BetaFunctionShellCall' - - $ref: '#/components/schemas/BetaFunctionShellCallOutput' - - $ref: '#/components/schemas/BetaApplyPatchToolCall' - - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' - - $ref: '#/components/schemas/BetaMCPListTools' - - $ref: '#/components/schemas/BetaMCPApprovalRequest' - - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' - - $ref: '#/components/schemas/BetaMCPToolCall' - - $ref: '#/components/schemas/BetaCustomToolCallResource' - - $ref: '#/components/schemas/BetaCustomToolCallOutputResource' - BetaCustomToolCallOutputResource: - title: ResponseCustomToolCallOutputItem - allOf: - - $ref: '#/components/schemas/BetaCustomToolCallOutput' - - type: object - properties: - id: - type: string - description: | - The unique ID of the custom tool call output item. - status: - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' - created_by: - type: string - description: | - The identifier of the actor that created the item. - required: - - id - - status - BetaFunctionCallOutputStatusEnum: - type: string - enum: - - in_progress - - completed - - incomplete - BetaCustomToolCallResource: - title: ResponseCustomToolCallItem - allOf: - - $ref: '#/components/schemas/BetaCustomToolCall' - - type: object - properties: - id: - type: string - description: | - The unique ID of the custom tool call item. - status: - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - $ref: '#/components/schemas/BetaFunctionCallStatus' - created_by: - type: string - description: | - The identifier of the actor that created the item. - required: - - id - - status - BetaFunctionCallStatus: - type: string - enum: - - in_progress - - completed - - incomplete - BetaMCPApprovalResponseResource: + description: The event type sent in the test. + status_code: + type: integer + description: The HTTP status code returned by the endpoint. + success: + type: boolean + enum: + - true + description: Whether the test request completed. Always true for returned results; use status_code to determine the endpoint response. + default: true + x-stainless-const: true type: object - title: MCP approval response - description: | - A response to an MCP approval request. + required: + - object + - webhook_endpoint_id + - event_type + - status_code + - success + WebhookEventTypeListResource: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - type: + object: type: string enum: - - mcp_approval_response - description: | - The type of the item. Always `mcp_approval_response`. + - list + description: The object type, which is always list. + default: list + x-stainless-const: true + data: + items: + type: string + type: array + description: The webhook event types available to the authenticated project. + type: object + required: + - object + - data + DragPoint: + properties: + x: + type: integer + description: The x-coordinate. + y: + type: integer + description: The y-coordinate. + type: object + required: + - x + - y + title: Coordinate + description: 'An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.' + LiveSessionAudioFormatPCMParam: + description: Raw, mono 16-bit little-endian PCM audio for a Live WebSocket connection. + type: object + properties: + type: + description: The audio encoding. Always `audio/pcm`. + default: audio/pcm x-stainless-const: true - id: - type: string - description: | - The unique ID of the approval response - approval_request_id: type: string - description: | - The ID of the approval request being answered. - approve: - type: boolean - description: | - Whether the request was approved. - reason: - anyOf: - - type: string - description: | - Optional reason for the decision. - - type: 'null' + enum: + - audio/pcm + rate: + description: Audio sample rate in hertz. Live WebSocket PCM audio supports 16000 or 24000 Hz. + type: integer + minimum: 16000 + maximum: 24000 + enum: + - 16000 + - 24000 required: - type - - id - - request_id - - approve - - approval_request_id - BetaApplyPatchToolCallOutput: + - rate + LiveSessionAudioFormatPCMUParam: + description: Raw, mono G.711 μ-law audio for a Live WebSocket connection. + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. type: + description: The audio encoding. Always `audio/pcmu`. + default: audio/pcmu + x-stainless-const: true type: string enum: - - apply_patch_call_output - description: The type of the item. Always `apply_patch_call_output`. - default: apply_patch_call_output + - audio/pcmu + rate: + description: Audio sample rate in hertz. G.711 audio uses 8000 Hz. + type: integer + minimum: 8000 + maximum: 8000 + required: + - type + - rate + LiveSessionAudioFormatPCMAParam: + description: Raw, mono G.711 A-law audio for a Live WebSocket connection. + type: object + properties: + type: + description: The audio encoding. Always `audio/pcma`. + default: audio/pcma x-stainless-const: true - id: - type: string - description: The unique ID of the apply patch tool call output. Populated when this item is returned via API. - call_id: type: string - description: The unique ID of the apply patch tool call generated by the model. - caller: + enum: + - audio/pcma + rate: + description: Audio sample rate in hertz. G.711 audio uses 8000 Hz. + type: integer + minimum: 8000 + maximum: 8000 + required: + - type + - rate + LiveAudioFormat: + description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/LiveSessionAudioFormatPCMParam' + - $ref: '#/components/schemas/LiveSessionAudioFormatPCMUParam' + - $ref: '#/components/schemas/LiveSessionAudioFormatPCMAParam' + LiveInitialSessionAudioParam: + description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. + type: object + properties: + format: + description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. + $ref: '#/components/schemas/LiveAudioFormat' + output: + description: The voice used for speech generated by the Live model. + $ref: '#/components/schemas/LiveInitialSessionAudioOutputParam' + required: [] + LiveSessionCreateParams: + description: Initial configuration for a Live session, including its model, conversation instructions, audio, and delegated task handling. + type: object + properties: + model: + $ref: '#/components/schemas/ModelIdsLive' + instructions: anyOf: - - $ref: '#/components/schemas/BetaToolCallCaller' - description: The execution context that produced this tool call. + - description: Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup. + type: string - type: 'null' - status: - $ref: '#/components/schemas/BetaApplyPatchCallOutputStatus' - description: The status of the apply patch tool call output. One of `completed` or `failed`. - output: + input: + description: Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total. + type: array + items: + $ref: '#/components/schemas/LiveInitialItem' + maxItems: 128 + audio: + description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. + $ref: '#/components/schemas/LiveInitialSessionAudioParam' + delegation: anyOf: - - type: string - description: Optional textual output returned by the apply patch tool. + - description: Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/LiveClientDelegationParam' + - $ref: '#/components/schemas/LiveResponsesDelegationParam' - type: 'null' - created_by: - type: string - description: The ID of the entity that created this tool call output. - type: object + store: + description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. + type: boolean + client: + description: Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. + $ref: '#/components/schemas/LiveClientConfigParam' required: - - type - - id - - call_id - - status - title: Apply patch tool call output - description: The output emitted by an apply patch tool call. - BetaApplyPatchCallOutputStatus: - type: string - enum: - - completed - - failed - BetaApplyPatchToolCall: + - model + LiveSessionStartEvent: + description: Start a Live session on a primary WebSocket. Send this event before other commands and wait for `session.started`. + example: + type: session.start + event_id: evt_start_001 + session: + model: gpt-live-1 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: - type: string - enum: - - apply_patch_call - description: The type of the item. Always `apply_patch_call`. - default: apply_patch_call + description: The Live client event type. Always `session.start`. + default: session.start x-stainless-const: true - id: - type: string - description: The unique ID of the apply patch tool call. Populated when this item is returned via API. - call_id: type: string - description: The unique ID of the apply patch tool call generated by the model. - caller: + enum: + - session.start + session: + description: Initial configuration for a primary WebSocket. Send session.start first and wait for session.started before application commands. WebRTC creation already starts the session; do not send this event again on its data channel. + $ref: '#/components/schemas/LiveSessionCreateParams' + required: + - type + - session + x-oaiMeta: + example: + type: session.start + event_id: evt_start_001 + session: + model: gpt-live-1 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + LiveSessionUpdateParams: + description: Changes to an active Live session. Only delegation backend settings can be updated after startup. + type: object + properties: + delegation: anyOf: - - $ref: '#/components/schemas/BetaToolCallCaller' - description: The execution context that produced this tool call. + - description: Delegation settings to update. The delegation type must match the current session; omitted settings retain their values. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/LiveClientDelegationParam' + - $ref: '#/components/schemas/LiveResponsesDelegationUpdateParam' - type: 'null' - status: - $ref: '#/components/schemas/BetaApplyPatchCallStatus' - description: The status of the apply patch tool call. One of `in_progress` or `completed`. - operation: - discriminator: - propertyName: type - title: Apply patch operation - description: One of the create_file, delete_file, or update_file operations applied via apply_patch. + required: [] + LiveSessionUpdateParam: + description: Update the delegation settings of an active Live session. The server acknowledges accepted changes with `session.updated`. + example: + type: session.update + event_id: evt_update_001 + session: + delegation: + type: responses + responses: + instructions: Check restaurant availability. Ask before confirming a booking. + max_output_tokens: 1024 + type: object + properties: + event_id: anyOf: - - $ref: '#/components/schemas/BetaApplyPatchCreateFileOperation' - - $ref: '#/components/schemas/BetaApplyPatchDeleteFileOperation' - - $ref: '#/components/schemas/BetaApplyPatchUpdateFileOperation' - created_by: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' + type: + description: The Live client event type. Always `session.update`. + default: session.update + x-stainless-const: true type: string - description: The ID of the entity that created this tool call. - type: object + enum: + - session.update + session: + description: Sparse delegation updates. Omitted settings retain their values. The delegation type cannot change, including resetting Responses delegation to null or client. Model, frontend instructions, audio, and startup input are immutable. + $ref: '#/components/schemas/LiveSessionUpdateParams' required: - type - - id - - call_id - - status - - operation - title: Apply patch tool call - description: A tool call that applies file diffs by creating, deleting, or updating files. - BetaApplyPatchUpdateFileOperation: + - session + x-oaiMeta: + example: + type: session.update + event_id: evt_update_001 + session: + delegation: + type: responses + responses: + instructions: Check restaurant availability. Ask before confirming a booking. + max_output_tokens: 1024 + LiveInputAudioAppendEvent: + description: Send audio to a Live session over its primary WebSocket. WebRTC and SIP sessions send audio over their media transport. + example: + type: session.input_audio.append + audio: AACAAIAAAIAAAP9/AIAAgA== + type: object properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: - type: string - enum: - - update_file - description: Update an existing file with the provided diff. - default: update_file + description: The Live client event type. Always `session.input_audio.append`. + default: session.input_audio.append x-stainless-const: true - path: type: string - description: Path of the file to update. - diff: + enum: + - session.input_audio.append + audio: + description: Base64-encoded raw audio in the startup-selected format, without a WAV or other container header. Primary WebSocket only; media transports use their audio track. Audio appends have no acknowledgment. Reflected sideband server events reuse this event type and audio key, with no timestamps or event_id; their audio is always mono PCM16LE at 24 kHz. type: string - description: Diff to apply. - type: object + minLength: 1 required: - type - - path - - diff - title: Apply patch update file operation - description: Instruction describing how to update a file via the apply_patch tool. - BetaApplyPatchDeleteFileOperation: + - audio + x-oaiMeta: + example: + type: session.input_audio.append + audio: AACAAIAAAIAAAP9/AIAAgA== + LiveInputAudioMuteParam: + description: Mute audio input to the Live model without closing the session. The server acknowledges with `session.input_audio.muted`. + example: + type: session.input_audio.mute + event_id: evt_mute_001 + type: object properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: + description: The Live client event type. Always `session.input_audio.mute`. + default: session.input_audio.mute + x-stainless-const: true type: string enum: - - delete_file - description: Delete the specified file. - default: delete_file + - session.input_audio.mute + required: + - type + x-oaiMeta: + example: + type: session.input_audio.mute + event_id: evt_mute_001 + LiveInputAudioUnmuteParam: + description: Resume audio input to a Live model after muting it. The server acknowledges with `session.input_audio.unmuted`. + example: + type: session.input_audio.unmute + event_id: evt_unmute_001 + type: object + properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' + type: + description: The Live client event type. Always `session.input_audio.unmute`. + default: session.input_audio.unmute x-stainless-const: true - path: type: string - description: Path of the file to delete. - type: object + enum: + - session.input_audio.unmute required: - type - - path - title: Apply patch delete file operation - description: Instruction describing how to delete a file via the apply_patch tool. - BetaApplyPatchCreateFileOperation: + x-oaiMeta: + example: + type: session.input_audio.unmute + event_id: evt_unmute_001 + LiveInstructionsAppendParam: + description: Append instructions to the Live conversation while it is running, optionally associating them with an existing client delegation. + example: + type: session.instructions.append + event_id: evt_instructions_001 + delegation_id: null + content: The caller prefers outdoor seating. + type: object properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: + description: The Live client event type. Always `session.instructions.append`. + default: session.instructions.append + x-stainless-const: true type: string enum: - - create_file - description: Create a new file with the provided diff. - default: create_file + - session.instructions.append + delegation_id: + anyOf: + - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. + type: string + minLength: 1 + - type: 'null' + content: + description: Instruction text to append, limited to 500 tokens. This is a plain string, not an array of content parts. + type: string + required: + - type + - delegation_id + - content + x-oaiMeta: + example: + type: session.instructions.append + event_id: evt_instructions_001 + delegation_id: null + content: The caller prefers outdoor seating. + LiveThinkingAppendParam: + description: Provide silent reasoning or progress context to the Live model, optionally for an existing client delegation. + example: + type: session.thinking.append + event_id: evt_thinking_001 + delegation_id: del_abc123 + content: Checking availability for two guests at 7 PM. + type: object + properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' + type: + description: The Live client event type. Always `session.thinking.append`. + default: session.thinking.append x-stainless-const: true - path: type: string - description: Path of the file to create. - diff: + enum: + - session.thinking.append + delegation_id: + anyOf: + - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. + type: string + minLength: 1 + - type: 'null' + content: + description: Silent reasoning or progress context, limited to 500 tokens. It does not directly request speech, but can influence later speech and is not a secrecy boundary. type: string - description: Diff to apply. - type: object required: - type - - path - - diff - title: Apply patch create file operation - description: Instruction describing how to create a file via the apply_patch tool. - BetaApplyPatchCallStatus: - type: string - enum: - - in_progress - - completed - BetaFunctionShellCallOutput: + - delegation_id + - content + x-oaiMeta: + example: + type: session.thinking.append + event_id: evt_thinking_001 + delegation_id: del_abc123 + content: Checking availability for two guests at 7 PM. + LiveCommentaryAppendParam: + description: Provide context the Live model can communicate to the user, optionally for an existing client delegation. + example: + type: session.commentary.append + event_id: evt_commentary_001 + delegation_id: del_abc123 + content: There is an outdoor table for two at 7 PM. Ask whether to reserve it. + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: - type: string - enum: - - shell_call_output - description: The type of the shell call output. Always `shell_call_output`. - default: shell_call_output + description: The Live client event type. Always `session.commentary.append`. + default: session.commentary.append x-stainless-const: true - id: - type: string - description: The unique ID of the shell call output. Populated when this item is returned via API. - call_id: type: string - description: The unique ID of the shell tool call generated by the model. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCaller' - description: The execution context that produced this tool call. - - type: 'null' - status: - $ref: '#/components/schemas/BetaFunctionShellCallOutputStatusEnum' - description: The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - output: - items: - $ref: '#/components/schemas/BetaFunctionShellCallOutputContent' - type: array - description: An array of shell call output contents - max_output_length: + enum: + - session.commentary.append + delegation_id: anyOf: - - type: integer - description: The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - description: Required, nullable. Set null for general session context, or use the ID from session.delegation.created for an existing client delegation. Non-null IDs are not accepted with Responses delegation. + type: string + minLength: 1 - type: 'null' - created_by: + content: + description: Speakable context for the Live model, limited to 500 tokens. Use this for a result the model should communicate; use session.thinking.append for silent context. type: string - description: The identifier of the actor that created the item. - type: object required: - type - - id - - call_id - - status - - output - - max_output_length - title: Shell call output - description: The output of a shell tool call that was emitted. - BetaFunctionShellCallOutputContent: + - delegation_id + - content + x-oaiMeta: + example: + type: session.commentary.append + event_id: evt_commentary_001 + delegation_id: del_abc123 + content: There is an outdoor table for two at 7 PM. Ask whether to reserve it. + LiveResponseItemCreateParam: + description: Add an input item to the Live session’s Responses backend. Requires Responses delegation; use `response.create` to request a response. + example: + type: response.item.create + event_id: evt_item_001 + item: + type: message + role: user + content: + - type: input_text + text: Please check for a table for two at 7 PM. + type: object properties: - stdout: - type: string - description: The standard output that was captured. - stderr: - type: string - description: The standard error output that was captured. - outcome: - discriminator: - propertyName: type - title: Shell call outcome - description: Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + event_id: anyOf: - - $ref: '#/components/schemas/BetaFunctionShellCallOutputTimeoutOutcome' - - $ref: '#/components/schemas/BetaFunctionShellCallOutputExitOutcome' - created_by: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' + type: + description: The Live client event type. Always `response.item.create`. + default: response.item.create + x-stainless-const: true type: string - description: The identifier of the actor that created the item. - type: object + enum: + - response.item.create + item: + description: An input item to append to the Responses backend conversation, such as a user message or a function tool result. + $ref: '#/components/schemas/InputItem' required: - - stdout - - stderr - - outcome - title: Shell call output content - description: The content of a shell tool call output that was emitted. - BetaFunctionShellCallOutputExitOutcome: + - type + - item + x-oaiMeta: + example: + type: response.item.create + event_id: evt_item_001 + item: + type: message + role: user + content: + - type: input_text + text: Please check for a table for two at 7 PM. + LiveResponseCreateParam: + description: Request a response from the Live session’s Responses backend, or continue a delegated response waiting for tool results. Requires Responses delegation. + example: + type: response.create + event_id: evt_response_001 + type: object properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: + description: The Live client event type. Always `response.create`. + default: response.create + x-stainless-const: true type: string enum: - - exit - description: The outcome type. Always `exit`. - default: exit - x-stainless-const: true - exit_code: - type: integer - description: Exit code from the shell process. - type: object + - response.create required: - type - - exit_code - title: Shell call exit outcome - description: Indicates that the shell commands finished and returned an exit code. - BetaFunctionShellCallOutputTimeoutOutcome: + x-oaiMeta: + example: + type: response.create + event_id: evt_response_001 + LiveSessionCloseParam: + description: Request that the Live session close. The terminal `session.closed` event contains the close reason and final usage. + example: + type: session.close + event_id: evt_close_001 + type: object properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: + description: The Live client event type. Always `session.close`. + default: session.close + x-stainless-const: true type: string enum: - - timeout - description: The outcome type. Always `timeout`. - default: timeout - x-stainless-const: true - type: object + - session.close required: - type - title: Shell call timeout outcome - description: Indicates that the shell call exceeded its configured time limit. - BetaFunctionShellCallOutputStatusEnum: - type: string - enum: - - in_progress - - completed - - incomplete - BetaFunctionShellCall: + x-oaiMeta: + example: + type: session.close + event_id: evt_close_001 + LiveForkAudioParam: + description: Audio format for the new WebSocket connection to a forked Live session. The stored voice is preserved. + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. + format: + description: Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately. + $ref: '#/components/schemas/LiveAudioFormat' + required: [] + LiveForkSessionConfigParam: + description: Overrides for a stored session after connecting to the fork WebSocket. An empty object inherits the stored configuration; do not supply a new model. audio.format applies only to the new WebSocket connection. client overrides are only supported for WebRTC forks. + type: object + properties: + audio: + description: Audio format for a WebSocket fork. WebRTC forks negotiate their audio format and must omit this field. + $ref: '#/components/schemas/LiveForkAudioParam' + delegation: + description: Overrides for the stored session’s Responses backend. Only supported when the stored session already uses Responses delegation; the delegation type cannot change. + $ref: '#/components/schemas/LiveResponsesDelegationUpdateParam' + store: + description: Whether to store the forked session. Omission inherits the stored session's setting. + type: boolean + client: + description: Frontend data-channel permissions for a WebRTC fork. Omitted permissions inherit the stored values. Not supported for WebSocket forks. + $ref: '#/components/schemas/LiveClientConfigParam' + required: [] + LiveForkSessionStartEvent: + description: Start a Live session after connecting to a stored session’s fork WebSocket. Send an empty `session` object to use the stored configuration. + example: + type: session.start + session: {} + type: object + properties: + event_id: + anyOf: + - description: Optional client identifier for correlating this command with a server event's client_event_id or error.client_event_id. + type: string + maxLength: 512 + - type: 'null' type: - type: string - enum: - - shell_call - description: The type of the item. Always `shell_call`. - default: shell_call + description: The Live client event type. Always `session.start`. + default: session.start x-stainless-const: true - id: - type: string - description: The unique ID of the shell tool call. Populated when this item is returned via API. - call_id: type: string - description: The unique ID of the shell tool call generated by the model. - caller: + enum: + - session.start + session: + description: Overrides for a stored session after connecting to the fork WebSocket. An empty object inherits the stored configuration; do not supply a new model. audio.format applies only to the new WebSocket connection. client overrides are only supported for WebRTC forks. + $ref: '#/components/schemas/LiveForkSessionConfigParam' + required: + - type + - session + x-oaiMeta: + example: + type: session.start + session: {} + LiveSessionResourceParam: + description: The resolved Live session configuration and server-assigned session metadata. + type: object + properties: + model: + $ref: '#/components/schemas/ModelIdsLive' + instructions: anyOf: - - $ref: '#/components/schemas/BetaToolCallCaller' - description: The execution context that produced this tool call. + - description: Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup. + type: string - type: 'null' - action: - $ref: '#/components/schemas/BetaFunctionShellAction' - description: The shell commands and limits that describe how to run the tool call. - status: - $ref: '#/components/schemas/BetaFunctionShellCallStatus' - description: The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - environment: + input: + description: Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total. + type: array + items: + $ref: '#/components/schemas/LiveInitialItem' + maxItems: 128 + audio: + description: Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup. + $ref: '#/components/schemas/LiveInitialSessionAudioParam' + delegation: anyOf: - - discriminator: + - description: Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend. + discriminator: propertyName: type anyOf: - - $ref: '#/components/schemas/BetaLocalEnvironmentResource' - - $ref: '#/components/schemas/BetaContainerReferenceResource' + - $ref: '#/components/schemas/LiveClientDelegationParam' + - $ref: '#/components/schemas/LiveResponsesDelegationParam' - type: 'null' - created_by: + store: + description: Whether to store the session for later forking and recording download. Defaults to false for new sessions. + type: boolean + client: + description: Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. + $ref: '#/components/schemas/LiveClientConfigParam' + id: + description: The unique ID of the Live session. Use this ID for sideband connections, forking, and recording download. type: string - description: The ID of the entity that created this tool call. - type: object + expires_at: + description: The Unix timestamp, in seconds, at which the Live session expires. + type: integer + status: + description: The status of the session snapshot. Always `active`, including the final snapshot in session.closed; use the event type to determine that the session has closed. + default: active + x-stainless-const: true + type: string + enum: + - active required: - - type + - model - id - - call_id - - action + - expires_at - status - - environment - title: Shell tool call - description: A tool call that executes one or more shell commands in a managed environment. - BetaContainerReferenceResource: + LiveSessionStarted: + description: Returned when a Live session has started. Contains the resolved session configuration, including server defaults. + example: + type: session.started + event_id: evt_started_001 + client_event_id: evt_start_001 + session: + id: live_abc123 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + type: object properties: type: + description: The event type, always `session.started`. + default: session.started + x-stainless-const: true type: string enum: - - container_reference - description: The environment type. Always `container_reference`. - default: container_reference - x-stainless-const: true - container_id: + - session.started + event_id: + description: The unique ID of the Live server event. type: string - type: object + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + session: + $ref: '#/components/schemas/LiveSessionResourceParam' required: - type - - container_id - title: Container Reference - description: Represents a container created with /v1/containers. - BetaLocalEnvironmentResource: + - event_id + - session + x-oaiMeta: + example: + type: session.started + event_id: evt_started_001 + client_event_id: evt_start_001 + session: + id: live_abc123 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + LiveSessionUpdated: + description: Returned when a Live session update is accepted. Contains the resolved session configuration after the update. + example: + type: session.updated + event_id: evt_updated_001 + client_event_id: evt_update_001 + session: + id: live_def456 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: responses + responses: + model: gpt-6-astra + instructions: Check restaurant availability. Ask before confirming a booking. + max_output_tokens: 1024 + tools: [] + type: object properties: type: + description: The event type, always `session.updated`. + default: session.updated + x-stainless-const: true type: string enum: - - local - description: The environment type. Always `local`. - default: local - x-stainless-const: true - type: object + - session.updated + event_id: + description: The unique ID of the Live server event. + type: string + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + session: + $ref: '#/components/schemas/LiveSessionResourceParam' required: - type - title: Local Environment - description: Represents the use of a local environment to perform shell actions. - BetaFunctionShellCallStatus: - type: string - enum: - - in_progress - - completed - - incomplete - BetaFunctionShellAction: - properties: - commands: - items: - type: string - description: A list of commands to run. - type: array - timeout_ms: - anyOf: - - type: integer - description: Optional timeout in milliseconds for the commands. - - type: 'null' - max_output_length: - anyOf: - - type: integer - description: Optional maximum number of characters to return from each command. - - type: 'null' + - event_id + - session + x-oaiMeta: + example: + type: session.updated + event_id: evt_updated_001 + client_event_id: evt_update_001 + session: + id: live_def456 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: responses + responses: + model: gpt-6-astra + instructions: Check restaurant availability. Ask before confirming a booking. + max_output_tokens: 1024 + tools: [] + LiveInputAudioMuted: + description: Returned when a session.input_audio.mute command is accepted. Input audio is no longer sent to the model; sideband audio reflection continues. + example: + type: session.input_audio.muted + event_id: evt_muted_001 + client_event_id: evt_mute_001 type: object - required: - - commands - - timeout_ms - - max_output_length - title: Shell exec action - description: Execute a shell command. - BetaCompactionBody: properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: - type: string - enum: - - compaction - description: The type of the item. Always `compaction`. - default: compaction - x-stainless-const: true - id: + event_id: + description: The unique ID of the Live server event. type: string - description: The unique ID of the compaction item. - encrypted_content: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The encrypted content that was produced by compaction. - created_by: + type: + description: The event type, always `session.input_audio.muted`. + default: session.input_audio.muted + x-stainless-const: true type: string - description: The identifier of the actor that created the item. - type: object + enum: + - session.input_audio.muted required: + - event_id - type - - id - - encrypted_content - title: Compaction item - description: A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact). - BetaProgramOutput: + x-oaiMeta: + example: + type: session.input_audio.muted + event_id: evt_muted_001 + client_event_id: evt_mute_001 + LiveInputAudioUnmuted: + description: Returned when a session.input_audio.unmute command is accepted. Input audio is sent to the model again. + example: + type: session.input_audio.unmuted + event_id: evt_unmuted_001 + client_event_id: evt_unmute_001 + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: - type: string - enum: - - program_output - description: The type of the item. Always `program_output`. - default: program_output - x-stainless-const: true - id: + event_id: + description: The unique ID of the Live server event. type: string - description: The unique ID of the program output item. - call_id: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The call ID of the program item. - result: + type: + description: The event type, always `session.input_audio.unmuted`. + default: session.input_audio.unmuted + x-stainless-const: true type: string - description: The result produced by the program item. - status: - $ref: '#/components/schemas/BetaProgramOutputStatus' - description: The terminal status of the program output item. - type: object + enum: + - session.input_audio.unmuted required: + - event_id - type - - id - - call_id - - result - - status - BetaProgramOutputStatus: - type: string - enum: - - completed - - incomplete - BetaProgram: + x-oaiMeta: + example: + type: session.input_audio.unmuted + event_id: evt_unmuted_001 + client_event_id: evt_unmute_001 + LiveInstructionsAppended: + description: Returned when a session.instructions.append command is accepted into the Live session timeline. Acknowledges the appended instructions without guaranteeing that the model has acted on them. + example: + type: session.instructions.appended + event_id: evt_instructions_002 + client_event_id: evt_instructions_001 + start_ms: 1200 + end_ms: 1400 + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: + event_id: + description: The unique ID of the Live server event. type: string - enum: - - program - description: The type of the item. Always `program`. - default: program + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + start_ms: + description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. + type: integer + end_ms: + description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. + type: integer + type: + description: The event type, always `session.instructions.appended`. + default: session.instructions.appended x-stainless-const: true - id: type: string - description: The unique ID of the program item. - call_id: + enum: + - session.instructions.appended + required: + - event_id + - start_ms + - end_ms + - type + x-oaiMeta: + example: + type: session.instructions.appended + event_id: evt_instructions_002 + client_event_id: evt_instructions_001 + start_ms: 1200 + end_ms: 1400 + LiveThinkingAppended: + description: Returned when a session.thinking.append command is accepted into the Live session timeline. Acknowledges the added reasoning context without guaranteeing any spoken output. + example: + type: session.thinking.appended + event_id: evt_thinking_002 + client_event_id: evt_thinking_001 + start_ms: 4600 + end_ms: 4800 + type: object + properties: + event_id: + description: The unique ID of the Live server event. type: string - description: The stable call ID of the program item. - code: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The JavaScript source executed by programmatic tool calling. - fingerprint: + start_ms: + description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. + type: integer + end_ms: + description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. + type: integer + type: + description: The event type, always `session.thinking.appended`. + default: session.thinking.appended + x-stainless-const: true type: string - description: Opaque program replay fingerprint that must be round-tripped. - type: object + enum: + - session.thinking.appended required: + - event_id + - start_ms + - end_ms - type - - id - - call_id - - code - - fingerprint - BetaResponseConfigurationUpdate: + x-oaiMeta: + example: + type: session.thinking.appended + event_id: evt_thinking_002 + client_event_id: evt_thinking_001 + start_ms: 4600 + end_ms: 4800 + LiveCommentaryAppended: + description: Returned when a session.commentary.append command is accepted into the Live session timeline. Acknowledges the added commentary without guaranteeing exact wording or completed audio playback. + example: + type: session.commentary.appended + event_id: evt_commentary_002 + client_event_id: evt_commentary_001 + start_ms: 5200 + end_ms: 5400 type: object - description: | - A configuration update that applies to subsequent responses until it is - replaced by another configuration update. properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - id: + event_id: + description: The unique ID of the Live server event. type: string - description: The unique ID of the configuration update item. - example: cnfu_123 + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + start_ms: + description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. + type: integer + end_ms: + description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. + type: integer type: + description: The event type, always `session.commentary.appended`. + default: session.commentary.appended + x-stainless-const: true type: string enum: - - configuration_update - description: The item type. Always `configuration_update`. - default: configuration_update - x-stainless-const: true - reasoning: - type: object - description: The reasoning configuration applied by this update. - properties: - effort: - $ref: '#/components/schemas/BetaReasoningEffort' - description: | - The reasoning effort used for subsequent responses until another - configuration update replaces it. + - session.commentary.appended required: - - id + - event_id + - start_ms + - end_ms - type - BetaAdditionalTools: + x-oaiMeta: + example: + type: session.commentary.appended + event_id: evt_commentary_002 + client_event_id: evt_commentary_001 + start_ms: 5200 + end_ms: 5400 + LiveInputAudioAppend: + description: Input audio received from the primary transport and reflected to a Live sideband connection before model-input muting. + example: + type: session.input_audio.append + audio: AACAAIAAAIAAAP9/AIAAgA== + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. type: + description: The event type, always `session.input_audio.append`. + default: session.input_audio.append + x-stainless-const: true type: string enum: - - additional_tools - description: The type of the item. Always `additional_tools`. - default: additional_tools - x-stainless-const: true - id: + - session.input_audio.append + audio: + description: Base64-encoded raw mono PCM16LE at 24 kHz received from the primary transport, reflected to the sideband before model-input muting. This server event uses the same audio key as the client command, but is not an acknowledgment of it. type: string - description: The unique ID of the additional tools item. - role: - $ref: '#/components/schemas/BetaMessageRole' - description: The role that provided the additional tools. - tools: - items: - $ref: '#/components/schemas/BetaTool' - type: array - description: The additional tool definitions made available at this item. - type: object required: - type - - id - - role - - tools - BetaMessageRole: - type: string - enum: - - unknown - - user - - assistant - - system - - critic - - discriminator - - developer - - tool - BetaToolSearchOutput: + - audio + x-oaiMeta: + example: + type: session.input_audio.append + audio: AACAAIAAAIAAAP9/AIAAgA== + LiveOutputAudioDelta: + description: An audio chunk generated by the Live model. Decode and play primary WebSocket chunks in delivery order using the configured session audio format. Sideband connections receive reflected output audio with timestamps. + example: + type: session.output_audio.delta + delta: AACAAIAAAIAAAP9/AIAAgA== + start_ms: 1000 + end_ms: 1200 + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. type: - type: string - enum: - - tool_search_output - description: The type of the item. Always `tool_search_output`. - default: tool_search_output + description: The event type, always `session.output_audio.delta`. + default: session.output_audio.delta x-stainless-const: true - id: type: string - description: The unique ID of the tool search output item. - call_id: - anyOf: - - type: string - description: The unique ID of the tool search call generated by the model. - - type: 'null' - execution: - $ref: '#/components/schemas/BetaToolSearchExecutionType' - description: Whether tool search was executed by the server or by the client. - tools: - items: - $ref: '#/components/schemas/BetaTool' - type: array - description: The loaded tool definitions returned by tool search. - status: - $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' - description: The status of the tool search output item that was recorded. - created_by: + enum: + - session.output_audio.delta + delta: + description: Base64-encoded raw audio. Primary WebSocket events use the session's configured format; reflected sideband events use mono PCM16LE at 24 kHz. type: string - description: The identifier of the actor that created the item. - type: object + start_ms: + description: Inclusive session-relative start in milliseconds. Required on reflected sideband events; omitted on the primary WebSocket. + type: integer + end_ms: + description: Exclusive session-relative end in milliseconds. Required on reflected sideband events; omitted on the primary WebSocket. Dropped output frames leave gaps between reflected ranges. + type: integer required: - type - - id - - call_id - - execution - - tools - - status - BetaToolSearchCall: + - delta + x-oaiMeta: + example: + type: session.output_audio.delta + delta: AACAAIAAAIAAAP9/AIAAgA== + start_ms: 1000 + end_ms: 1200 + LiveInputTranscriptDelta: + description: A transcript fragment for user input audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event. + example: + type: session.input_transcript.delta + event_id: evt_input_transcript_001 + delta: A table for two at seven, please. + start_ms: 1600 + end_ms: 3400 + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: + event_id: + description: The unique ID of the Live server event. type: string - enum: - - tool_search_call - description: The type of the item. Always `tool_search_call`. - default: tool_search_call - x-stainless-const: true - id: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The unique ID of the tool search call item. - call_id: - anyOf: - - type: string - description: The unique ID of the tool search call generated by the model. - - type: 'null' - execution: - $ref: '#/components/schemas/BetaToolSearchExecutionType' - description: Whether tool search was executed by the server or by the client. - arguments: - description: Arguments used for the tool search call. - status: - $ref: '#/components/schemas/BetaFunctionCallStatus' - description: The status of the tool search call item that was recorded. - created_by: + start_ms: + description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. + type: integer + end_ms: + description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. + type: integer + delta: + description: The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript. type: string - description: The identifier of the actor that created the item. - type: object + type: + description: The event type, always `session.input_transcript.delta`. + default: session.input_transcript.delta + x-stainless-const: true + type: string + enum: + - session.input_transcript.delta required: + - event_id + - start_ms + - end_ms + - delta - type - - id - - call_id - - execution - - arguments - - status - BetaMultiAgentCallOutput: + x-oaiMeta: + example: + type: session.input_transcript.delta + event_id: evt_input_transcript_001 + delta: A table for two at seven, please. + start_ms: 1600 + end_ms: 3400 + LiveOutputTranscriptDelta: + description: A transcript fragment for assistant output audio in the Live session. Accumulate fragments in delivery order; these events do not define complete turns or include a transcript-done event. + example: + type: session.output_transcript.delta + event_id: evt_output_transcript_001 + delta: Would you like me to reserve that table? + start_ms: 5400 + end_ms: 7200 + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: + event_id: + description: The unique ID of the Live server event. type: string - enum: - - multi_agent_call_output - description: The type of the multi-agent result. Always `multi_agent_call_output`. - default: multi_agent_call_output - x-stainless-const: true - id: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The unique ID of the multi-agent call output item. - call_id: + start_ms: + description: The start of this event on the Live session timeline, in milliseconds from the beginning of the session. + type: integer + end_ms: + description: The end of this event on the Live session timeline, in milliseconds from the beginning of the session. For appended context, this can equal start_ms. + type: integer + delta: + description: The transcript text fragment for the audio in this time range. Append fragments in delivery order to build the transcript. type: string - description: The unique ID of the multi-agent call. - action: - $ref: '#/components/schemas/BetaMultiAgentAction' - description: The multi-agent action that produced this result. - output: - items: - $ref: '#/components/schemas/BetaOutputTextContent' - type: array - description: Text output returned by the multi-agent action. - type: object + type: + description: The event type, always `session.output_transcript.delta`. + default: session.output_transcript.delta + x-stainless-const: true + type: string + enum: + - session.output_transcript.delta required: + - event_id + - start_ms + - end_ms + - delta - type - - id - - call_id - - action - - output - x-oai-beta: responses_multi_agent=v1 - BetaMultiAgentAction: - type: string - enum: - - spawn_agent - - interrupt_agent - - list_agents - - send_message - - followup_task - - wait_agent - BetaMultiAgentCall: + x-oaiMeta: + example: + type: session.output_transcript.delta + event_id: evt_output_transcript_001 + delta: Would you like me to reserve that table? + start_ms: 5400 + end_ms: 7200 + LiveDelegationItem: + description: Metadata for work delegated by the Live model. Client delegations are handled by your application; Responses delegations run on the configured backend. + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. - type: - type: string - enum: - - multi_agent_call - description: The type of the multi-agent call. Always `multi_agent_call`. - default: multi_agent_call - x-stainless-const: true id: + description: The unique ID of the delegation. Use this as delegation_id when replying to client-owned work or correlating Responses events. type: string - description: The unique ID of the multi-agent call item. - call_id: + type: + description: The object type, always `delegation`. + default: delegation + x-stainless-const: true type: string - description: The unique ID linking this call to its output. - action: - $ref: '#/components/schemas/BetaMultiAgentAction' - description: The multi-agent action to execute. - arguments: + enum: + - delegation + target: + description: 'Where the Live model delegated the work: `client` for your application, or `responses` for the configured Responses backend.' + anyOf: + - default: client + x-stainless-const: true + type: string + enum: + - client + - default: responses + x-stainless-const: true + type: string + enum: + - responses + response_id: + description: The ID of the Responses API response associated with a Responses delegation. Omitted for client delegations. type: string - description: The JSON string of arguments generated for the action. - type: object required: - - type - id - - call_id - - action - - arguments - x-oai-beta: responses_multi_agent=v1 - BetaAgentMessage: + - type + - target + LiveDelegationCreated: + description: Returned when the Live model delegates work to your application or a Responses backend. Contains delegation metadata and the position on the session timeline where the work was delegated. + example: + type: session.delegation.created + event_id: evt_delegation_001 + offset_ms: 3600 + delegation: + id: del_abc123 + type: delegation + target: client + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. + event_id: + description: The unique ID of the Live server event. + type: string + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string type: + description: The event type, always `session.delegation.created`. + default: session.delegation.created + x-stainless-const: true type: string enum: - - agent_message - description: The type of the item. Always `agent_message`. - default: agent_message - x-stainless-const: true - id: + - session.delegation.created + offset_ms: + description: The position on the Live session timeline where the delegation was created, in milliseconds from the beginning of the session. + type: integer + delegation: + description: The delegated work identifier and destination. This object contains metadata, not the task text. + $ref: '#/components/schemas/LiveDelegationItem' + required: + - event_id + - type + - offset_ms + - delegation + x-oaiMeta: + example: + type: session.delegation.created + event_id: evt_delegation_001 + offset_ms: 3600 + delegation: + id: del_abc123 + type: delegation + target: client + LiveResponseEvent: + description: A streaming Responses API event from a backend delegated to by the Live session. Use the outer delegation_id to associate the nested stream with its Live delegation. + example: + type: response.event + event_id: evt_response_002 + delegation_id: del_responses123 + event: + type: response.output_text.delta + item_id: msg_abc123 + output_index: 0 + content_index: 0 + delta: An outdoor table is available at 7 PM. + sequence_number: 3 + logprobs: [] + type: object + properties: + event_id: + description: The unique ID of the Live server event. type: string - description: The unique ID of the agent message. - author: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - description: The sending agent identity. - recipient: + type: + description: The event type, always `response.event`. + default: response.event + x-stainless-const: true type: string - description: The destination agent identity. - content: - items: - discriminator: - propertyName: type - description: A content part that makes up an input or output item. - anyOf: - - $ref: '#/components/schemas/BetaInputTextContent' - - $ref: '#/components/schemas/BetaOutputTextContent' - - $ref: '#/components/schemas/BetaTextContent' - - $ref: '#/components/schemas/BetaSummaryTextContent' - - $ref: '#/components/schemas/BetaReasoningTextContent' - - $ref: '#/components/schemas/BetaRefusalContent' - - $ref: '#/components/schemas/BetaInputImageContent' - - $ref: '#/components/schemas/BetaComputerScreenshotContent' - - $ref: '#/components/schemas/BetaInputFileContent' - - $ref: '#/components/schemas/BetaEncryptedContent' - type: array - description: Encrypted content sent between agents. - type: object + enum: + - response.event + delegation_id: + anyOf: + - description: The Live delegation associated with the nested Responses event. May be null or omitted when the event cannot be correlated with a delegation. + type: string + - type: 'null' + event: + description: The nested Responses streaming event. Dispatch on its type field. Response lifecycle snapshots omit input and clear instructions, tools, and output to keep messages small; consume granular output events for the generated content. + type: object + additionalProperties: {} required: + - event_id - type - - id - - author - - recipient - - content - x-oai-beta: responses_multi_agent=v1 - BetaEncryptedContent: + - event + x-oaiMeta: + example: + type: response.event + event_id: evt_response_002 + delegation_id: del_responses123 + event: + type: response.output_text.delta + item_id: msg_abc123 + output_index: 0 + content_index: 0 + delta: An outdoor table is available at 7 PM. + sequence_number: 3 + logprobs: [] + LiveSessionUsage: + description: Cumulative audio duration for a Live session. Values are totals for the session, not increments to sum across usage events. + type: object properties: - type: + seconds: + description: The cumulative Live audio duration in seconds. Do not sum this value across usage events. + type: number + required: + - seconds + LiveContextWindowUsage: + description: The latest measured context-window usage of the Live model. This is separate from billing usage and delegated Responses token usage. + type: object + properties: + usage_ratio: + description: The latest active context token count divided by the Live model context limit. Can decrease after compaction and may lag between measured audio frames. + type: number + required: + - usage_ratio + LiveSessionUsageUpdated: + description: Reports cumulative Live audio usage and, when available, the most recent context-window usage. Delegated Responses token usage is reported separately in response.event events. + example: + type: session.usage.updated + event_id: evt_usage_001 + usage: + seconds: 32.5 + context_window: + usage_ratio: 0.12 + type: object + properties: + event_id: + description: The unique ID of the Live server event. type: string - enum: - - encrypted_content - description: The type of the input item. Always `encrypted_content`. - default: encrypted_content + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + type: + description: The event type, always `session.usage.updated`. + default: session.usage.updated x-stainless-const: true - encrypted_content: type: string - description: Opaque encrypted content. - type: object + enum: + - session.usage.updated + usage: + description: The cumulative Live audio usage so far. + $ref: '#/components/schemas/LiveSessionUsage' + context_window: + description: The latest measured Live context-window usage. Omitted when the context limit is unknown. + $ref: '#/components/schemas/LiveContextWindowUsage' required: + - event_id - type - - encrypted_content - title: Encrypted content - description: Opaque encrypted content that Responses API decrypts inside trusted model execution. - x-oai-beta: responses_multi_agent=v1 - BetaComputerScreenshotContent: + - usage + x-oaiMeta: + example: + type: session.usage.updated + event_id: evt_usage_001 + usage: + seconds: 32.5 + context_window: + usage_ratio: 0.12 + LiveSessionClosed: + description: Returned after the Live session finishes finalizing, with the close reason, final session snapshot, and cumulative audio usage. A connection closing without this event does not confirm successful finalization. + example: + type: session.closed + event_id: evt_closed_001 + client_event_id: evt_close_001 + reason: close_requested + session: + id: live_abc123 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + usage: + seconds: 45.8 + type: object properties: + event_id: + description: The unique ID of the Live server event. + type: string + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string type: + description: The event type, always `session.closed`. + default: session.closed + x-stainless-const: true type: string enum: - - computer_screenshot - description: Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - default: computer_screenshot - x-stainless-const: true - image_url: - anyOf: - - type: string - format: uri - description: The URL of the screenshot image. - - type: 'null' - file_id: + - session.closed + reason: + description: 'Why the Live session ended: `close_requested` for an application close or hangup request, `expired` for the session duration limit, `content` for a safety filter, `remote_hangup` for a graceful remote disconnect, or `connection_lost` for an unexpected primary or upstream disconnection.' anyOf: - - type: string - description: The identifier of an uploaded file that contains the screenshot. - - type: 'null' - detail: - $ref: '#/components/schemas/BetaImageDetail' - description: The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - prompt_cache_breakpoint: - $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' - type: object + - default: close_requested + x-stainless-const: true + type: string + enum: + - close_requested + - default: expired + x-stainless-const: true + type: string + enum: + - expired + - default: content + x-stainless-const: true + type: string + enum: + - content + - default: remote_hangup + x-stainless-const: true + type: string + enum: + - remote_hangup + - default: connection_lost + x-stainless-const: true + type: string + enum: + - connection_lost + session: + $ref: '#/components/schemas/LiveSessionResourceParam' + usage: + description: The final cumulative Live audio usage after session finalization. + $ref: '#/components/schemas/LiveSessionUsage' required: + - event_id - type - - image_url - - file_id - - detail - title: Computer screenshot - description: A screenshot of a computer. - BetaTextContent: + - reason + - session + - usage + x-oaiMeta: + example: + type: session.closed + event_id: evt_closed_001 + client_event_id: evt_close_001 + reason: close_requested + session: + id: live_abc123 + model: gpt-live-1 + status: active + expires_at: 1788555600 + instructions: Help the caller plan a restaurant reservation. Confirm details before booking. + input: [] + audio: + format: + type: audio/pcm + rate: 24000 + output: + voice: marin + delegation: + type: client + usage: + seconds: 45.8 + LiveLiveError: + description: Details of an error encountered by the Live session, including the affected parameter or client command when available. + type: object properties: type: + description: The category of error, such as `invalid_request_error` for an invalid Live client command. type: string - enum: - - text - default: text - x-stainless-const: true - text: + code: + description: A machine-readable code identifying the Live error, such as `unknown_parameter`. + type: string + message: + description: A human-readable explanation of the Live error. + type: string + param: + description: The parameter that caused the error, when applicable, such as `session.voice`. + type: string + client_event_id: + description: The event_id of the client command that caused the error, when supplied. type: string - type: object required: - type - - text - title: Text Content - description: A text content. - BetaFunctionToolCallOutputResource: - allOf: - - $ref: '#/components/schemas/BetaFunctionToolCallOutput' - - type: object - properties: - id: - type: string - description: | - The unique ID of the function call tool output. - status: - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' - created_by: - type: string - description: | - The identifier of the actor that created the item. - required: - - id - - status - BetaFunctionToolCallOutput: + - code + - message + LiveErrorEvent: + description: Reports an error in the Live session, such as an invalid client command. Use error.client_event_id, when present, to identify the command that caused the error. + example: + type: error + event_id: evt_error_001 + error: + type: invalid_request_error + code: unknown_parameter + message: 'Unknown parameter: ''session.voice''.' + param: session.voice + client_event_id: evt_invalid_001 type: object - title: Function tool call output - description: | - The output of a function tool call. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. - id: + event_id: + description: The unique ID of the Live server event. type: string - description: | - The unique ID of the function tool call output. Populated when this item - is returned via API. - type: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. type: string - enum: - - function_call_output - description: | - The type of the function tool call output. Always `function_call_output`. + type: + description: The event type, always `error`. + default: error x-stainless-const: true - call_id: - type: string - description: | - The unique ID of the function tool call generated by the model. - name: type: string - description: | - The name of the tool that produced the output. - namespace: + enum: + - error + error: + description: Details of the Live error and the client command that caused it, when known. + $ref: '#/components/schemas/LiveLiveError' + required: + - event_id + - type + - error + x-oaiMeta: + example: + type: error + event_id: evt_error_001 + error: + type: invalid_request_error + code: unknown_parameter + message: 'Unknown parameter: ''session.voice''.' + param: session.voice + client_event_id: evt_invalid_001 + LiveInfoEvent: + description: An informational notice about the Live session, such as the event permissions applied to a frontend data channel. + example: + type: info + event_id: evt_info_001 + code: data_channel_permissions + message: The frontend data channel is configured with restricted event permissions. + type: object + properties: + event_id: + description: The unique ID of the Live server event. type: string - description: | - The namespace of the tool that produced the output. - caller: - anyOf: - - $ref: '#/components/schemas/BetaToolCallCallerParam' - - type: 'null' - output: - description: | - The output from the function call generated by your code. - Can be a string or an list of output content. - anyOf: - - type: string - description: | - A string of the output of the function call. - title: string output - - type: array - items: - $ref: '#/components/schemas/BetaFunctionAndCustomToolCallOutput' - title: output content list - description: | - Text, image, or file output of the function call. - status: + client_event_id: + description: The event_id of the client command associated with this server event, when supplied. + type: string + type: + description: The event type, always `info`. + default: info + x-stainless-const: true type: string - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. enum: - - in_progress - - completed - - incomplete + - info + code: + description: A machine-readable code for the notice, such as `data_channel_permissions`. + type: string + message: + description: A human-readable explanation of the Live session notice. + type: string required: + - event_id - type - - output - BetaFunctionToolCallResource: - allOf: - - $ref: '#/components/schemas/BetaFunctionToolCall' - - type: object - properties: - id: - type: string - description: | - The unique ID of the function tool call. - status: - description: | - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - $ref: '#/components/schemas/BetaFunctionCallStatus' - created_by: - type: string - description: | - The identifier of the actor that created the item. - required: - - id - - status - BetaComputerToolCallOutputResource: - allOf: - - $ref: '#/components/schemas/BetaComputerToolCallOutput' - - type: object - properties: - id: - type: string - description: | - The unique ID of the computer call tool output. - status: - description: | - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - $ref: '#/components/schemas/BetaComputerCallOutputStatus' - created_by: - type: string - description: | - The identifier of the actor that created the item. - required: - - id - - status - BetaComputerCallOutputStatus: - type: string - enum: - - completed - - incomplete - - failed - BetaComputerToolCallOutput: + - code + - message + x-oaiMeta: + example: + type: info + event_id: evt_info_001 + code: data_channel_permissions + message: The frontend data channel is configured with restricted event permissions. + LiveTransportDTMFReceived: + description: A SIP DTMF keypress received from the caller. Delivered only to sideband observers. + example: + type: transport.dtmf.received + event_id: event_dtmf_1 + event: '5' type: object - title: Computer tool call output - description: | - The output of a computer tool call. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that produced this item. type: + default: transport.dtmf.received + x-stainless-const: true type: string - description: | - The type of the computer tool call output. Always `computer_call_output`. enum: - - computer_call_output - default: computer_call_output - x-stainless-const: true - id: + - transport.dtmf.received + event_id: type: string - description: | - The ID of the computer tool call output. - call_id: + event: type: string - description: | - The ID of the computer tool call that produced the output. - acknowledged_safety_checks: - type: array - description: | - The safety checks reported by the API that have been acknowledged by the - developer. - items: - $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' - output: - $ref: '#/components/schemas/BetaComputerScreenshotImage' - status: + minLength: 1 + maxLength: 1 + pattern: ^[0-9A-D*#]$ + required: + - type + - event_id + - event + x-oaiMeta: + example: + type: transport.dtmf.received + event_id: event_dtmf_1 + event: '5' + LiveTransportDTMFSend: + description: A SIP DTMF keypress successfully sent by the hosted tool. Delivered only to sideband observers; this is not a client command. + example: + type: transport.dtmf.send + event_id: event_dtmf_2 + event: '#' + type: object + properties: + type: + default: transport.dtmf.send + x-stainless-const: true type: string - description: | - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. enum: - - in_progress - - completed - - incomplete + - transport.dtmf.send + event_id: + type: string + event: + type: string + minLength: 1 + maxLength: 1 + pattern: ^[0-9A-D*#]$ required: - type - - call_id - - output - BetaInputMessageResource: - allOf: - - $ref: '#/components/schemas/BetaInputMessage' - - type: object - properties: - id: - type: string - description: | - The unique ID of the message input. - required: - - id - - type - BetaCompactResource: + - event_id + - event + x-oaiMeta: + example: + type: transport.dtmf.send + event_id: event_dtmf_2 + event: '#' + LiveTransportRinging: + description: The outbound SIP provider leg is ringing or providing early media. Delivered only to sideband observers. + example: + type: transport.ringing + event_id: event_call_1 + session_id: live_u0_123 + type: object properties: - id: + event_id: type: string - description: The unique identifier for the compacted response. - object: + session_id: + description: The canonical Live session ID. type: string - enum: - - response.compaction - description: The object type. Always `response.compaction`. - default: response.compaction + type: + default: transport.ringing x-stainless-const: true - output: - type: array - description: The compacted list of output items. This is a list of all user messages, followed by a single compaction item. - items: - $ref: '#/components/schemas/BetaOutputItem' - created_at: - type: integer - format: unixtime - description: Unix timestamp (in seconds) when the compacted conversation was created. - usage: - $ref: '#/components/schemas/BetaResponseUsage' - description: Token accounting for the compaction pass, including cached, reasoning, and total tokens. - type: object + type: string + enum: + - transport.ringing required: - - id - - object - - output - - created_at - - usage - title: The compacted response object - BetaResponseUsage: + - event_id + - session_id + - type + x-oaiMeta: + example: + type: transport.ringing + event_id: event_call_1 + session_id: live_u0_123 + LiveTransportAnswered: + description: The outbound SIP provider leg answered and media is established. Delivered only to sideband observers. + example: + type: transport.answered + event_id: event_call_2 + session_id: live_u0_123 type: object - description: | - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. properties: - input_tokens: - type: integer - description: The number of input tokens. - input_tokens_details: - type: object - description: A detailed breakdown of the input tokens. - properties: - cached_tokens: - type: integer - description: | - The number of tokens that were retrieved from the cache. - [More on prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching). - cache_write_tokens: - type: integer - description: The number of input tokens that were written to the cache. - required: - - cached_tokens - - cache_write_tokens - output_tokens: - type: integer - description: The number of output tokens. - output_tokens_details: - type: object - description: A detailed breakdown of the output tokens. - properties: - reasoning_tokens: - type: integer - description: The number of reasoning tokens. - required: - - reasoning_tokens - total_tokens: - type: integer - description: The total number of tokens used. + event_id: + type: string + session_id: + description: The canonical Live session ID. + type: string + type: + default: transport.answered + x-stainless-const: true + type: string + enum: + - transport.answered required: - - input_tokens - - input_tokens_details - - output_tokens - - output_tokens_details - - total_tokens - BetaItemField: - discriminator: - propertyName: type - description: An item representing a message, tool call, tool output, reasoning, or other response element. - anyOf: - - $ref: '#/components/schemas/BetaMessage' - - $ref: '#/components/schemas/BetaProgram' - - $ref: '#/components/schemas/BetaProgramOutput' - - $ref: '#/components/schemas/BetaFunctionToolCall' - - $ref: '#/components/schemas/BetaMultiAgentCall' - - $ref: '#/components/schemas/BetaMultiAgentCallOutput' - - $ref: '#/components/schemas/BetaToolSearchCall' - - $ref: '#/components/schemas/BetaToolSearchOutput' - - $ref: '#/components/schemas/BetaAdditionalTools' - - $ref: '#/components/schemas/BetaAgentMessage' - - $ref: '#/components/schemas/BetaFunctionToolCallOutput' - - $ref: '#/components/schemas/BetaFileSearchToolCall' - - $ref: '#/components/schemas/BetaWebSearchToolCall' - - $ref: '#/components/schemas/BetaImageGenToolCall' - - $ref: '#/components/schemas/BetaComputerToolCall' - - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' - - $ref: '#/components/schemas/BetaReasoningItem' - - $ref: '#/components/schemas/BetaCompactionBody' - - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCall' - deprecated: true - - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' - deprecated: true - - $ref: '#/components/schemas/BetaFunctionShellCall' - - $ref: '#/components/schemas/BetaFunctionShellCallOutput' - - $ref: '#/components/schemas/BetaApplyPatchToolCall' - - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' - - $ref: '#/components/schemas/BetaMCPListTools' - - $ref: '#/components/schemas/BetaMCPApprovalRequest' - - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' - - $ref: '#/components/schemas/BetaMCPToolCall' - - $ref: '#/components/schemas/BetaCustomToolCall' - - $ref: '#/components/schemas/BetaCustomToolCallOutput' - BetaMessage: + - event_id + - session_id + - type + x-oaiMeta: + example: + type: transport.answered + event_id: event_call_2 + session_id: live_u0_123 + LiveTransportCallError: + type: object properties: - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that produced this item. type: + default: call_error + x-stainless-const: true type: string enum: - - message - description: The type of the message. Always set to `message`. - default: message - x-stainless-const: true - id: + - call_error + code: + description: The call setup failure code. + type: string + message: + type: string + param: + description: The parameter related to the error, if any. Empty when no parameter applies. type: string - description: The unique ID of the message. - status: - $ref: '#/components/schemas/BetaMessageStatus' - description: The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - role: - $ref: '#/components/schemas/BetaMessageRole' - description: The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - content: - items: - discriminator: - propertyName: type - description: A content part that makes up an input or output item. - anyOf: - - $ref: '#/components/schemas/BetaInputTextContent' - - $ref: '#/components/schemas/BetaOutputTextContent' - - $ref: '#/components/schemas/BetaTextContent' - - $ref: '#/components/schemas/BetaSummaryTextContent' - - $ref: '#/components/schemas/BetaReasoningTextContent' - - $ref: '#/components/schemas/BetaRefusalContent' - - $ref: '#/components/schemas/BetaInputImageContent' - - $ref: '#/components/schemas/BetaComputerScreenshotContent' - - $ref: '#/components/schemas/BetaInputFileContent' - - $ref: '#/components/schemas/BetaEncryptedContent' - type: array - description: The content of the message - phase: - anyOf: - - $ref: '#/components/schemas/BetaMessagePhase-2' - description: 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. - - type: 'null' - type: object required: - type - - id - - status - - role - - content - title: Message - description: A message to or from the model. - BetaMessagePhase-2: - type: string - enum: - - commentary - - final_answer - BetaMessageStatus: - type: string - enum: - - in_progress - - completed - - incomplete - BetaResponseCustomToolCallInputDoneEvent: - title: ResponseCustomToolCallInputDone + - code + - message + LiveTransportFailed: + description: An asynchronous outbound SIP setup failure. Delivered only to sideband observers. + example: + type: transport.failed + event_id: event_call_4 + session_id: live_u0_123 + error: + type: call_error + code: provider_invite_failed + message: provider rejected the call + param: '' type: object - description: | - Event indicating that input for a custom tool call is complete. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. - type: + event_id: type: string - enum: - - response.custom_tool_call_input.done - description: The event type identifier. - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of this event. - output_index: - type: integer - description: The index of the output this event applies to. - item_id: + session_id: + description: The canonical Live session ID. type: string - description: Unique identifier for the API item associated with this event. - input: + type: + default: transport.failed + x-stainless-const: true type: string - description: The complete input data for the custom tool call. + enum: + - transport.failed + error: + $ref: '#/components/schemas/LiveTransportCallError' required: + - event_id + - session_id - type - - output_index - - item_id - - input - - sequence_number + - error x-oaiMeta: - name: response.custom_tool_call_input.done - group: responses - example: | - { - "type": "response.custom_tool_call_input.done", - "output_index": 0, - "item_id": "ctc_1234567890abcdef", - "input": "final complete input text" - } - BetaResponseCustomToolCallInputDeltaEvent: - title: ResponseCustomToolCallInputDelta - type: object - description: | - Event representing a delta (partial update) to the input of a custom tool call. + example: + type: transport.failed + event_id: event_call_4 + session_id: live_u0_123 + error: + type: call_error + code: provider_invite_failed + message: provider rejected the call + param: '' + LiveServerEvent-2: + description: An event sent by the Live API on a primary WebSocket or sideband connection. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/LiveSessionStarted' + - $ref: '#/components/schemas/LiveSessionUpdated' + - $ref: '#/components/schemas/LiveInputAudioMuted' + - $ref: '#/components/schemas/LiveInputAudioUnmuted' + - $ref: '#/components/schemas/LiveInstructionsAppended' + - $ref: '#/components/schemas/LiveThinkingAppended' + - $ref: '#/components/schemas/LiveCommentaryAppended' + - $ref: '#/components/schemas/LiveInputAudioAppend' + - $ref: '#/components/schemas/LiveOutputAudioDelta' + - $ref: '#/components/schemas/LiveInputTranscriptDelta' + - $ref: '#/components/schemas/LiveOutputTranscriptDelta' + - $ref: '#/components/schemas/LiveDelegationCreated' + - $ref: '#/components/schemas/LiveResponseEvent' + - $ref: '#/components/schemas/LiveSessionUsageUpdated' + - $ref: '#/components/schemas/LiveSessionClosed' + - $ref: '#/components/schemas/LiveErrorEvent' + - $ref: '#/components/schemas/LiveInfoEvent' + - $ref: '#/components/schemas/LiveTransportDTMFReceived' + - $ref: '#/components/schemas/LiveTransportDTMFSend' + - $ref: '#/components/schemas/LiveTransportRinging' + - $ref: '#/components/schemas/LiveTransportAnswered' + - $ref: '#/components/schemas/LiveTransportFailed' + UserMessageItemParam: properties: - agent: + id: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - type: string + description: The unique ID of this message item. + example: msg_123 - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.custom_tool_call_input.delta - description: The event type identifier. + - message + description: The item type. Always `message`. + default: message x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of this event. - output_index: - type: integer - description: The index of the output this delta applies to. - item_id: - type: string - description: Unique identifier for the API item associated with this event. - delta: + role: type: string - description: The incremental input data (delta) for the custom tool call. + enum: + - user + description: The message role. Always `user`. + default: user + x-stainless-const: true + content: + description: The message content, as an array of content parts. + anyOf: + - items: + $ref: '#/components/schemas/ResponseSteerInputContent' + description: A piece of message content, such as text, an image, or a file. + type: array + - type: string + maxLength: 10485760 + description: The message content, as a single string. + status: + anyOf: + - type: string + description: The status of the message item. + - type: 'null' + type: object required: - type - - output_index - - item_id - - delta - - sequence_number - x-oaiMeta: - name: response.custom_tool_call_input.delta - group: responses - example: | - { - "type": "response.custom_tool_call_input.delta", - "output_index": 0, - "item_id": "ctc_1234567890abcdef", - "delta": "partial input text" - } - BetaResponseQueuedEvent: - type: object - title: ResponseQueuedEvent - description: | - Emitted when a response is queued and waiting to be processed. + - role + - content + ErrorPayload: properties: - agent: + type: + type: string + description: The error type that was emitted. + code: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - type: string + description: The error code that was emitted, if any. - type: 'null' - description: The agent that owns this multi-agent streaming event. - type: + message: + type: string + description: The human-readable error message that was emitted. + param: + anyOf: + - type: string + description: The parameter name that was associated with the error, if any. + - type: 'null' + headers: + additionalProperties: + type: string + description: The header value that was emitted. + type: object + description: The response headers that were emitted with the error, if any. + x-oaiTypeLabel: map + misalignment: + $ref: '#/components/schemas/MisalignmentErrorDetailsResource' + type: object + required: + - type + - code + - message + - param + title: Error payload + description: An error payload that was emitted for a streaming error event. + BetaTokenCountsResource: + properties: + object: type: string enum: - - response.queued - description: The type of the event. Always 'response.queued'. + - response.input_tokens + default: response.input_tokens x-stainless-const: true - response: - $ref: '#/components/schemas/BetaResponse' - description: The full response object that is queued. - sequence_number: + input_tokens: type: integer - description: The sequence number for this event. + type: object required: - - type - - response - - sequence_number - x-oaiMeta: - name: response.queued - group: responses - example: | - { - "type": "response.queued", - "response": { - "id": "res_123", - "status": "queued", - "created_at": "2021-01-01T00:00:00Z", - "updated_at": "2021-01-01T00:00:00Z" - }, - "sequence_number": 1 - } - BetaResponse: - title: The response object - allOf: - - $ref: '#/components/schemas/BetaModelResponseProperties' - - $ref: '#/components/schemas/BetaResponseProperties' - - type: object - properties: - service_tier: - $ref: '#/components/schemas/BetaServiceTierResponses' - truncation: + - object + - input_tokens + title: Token counts + example: + object: response.input_tokens + input_tokens: 123 + BetaTokenCountsBody: + properties: + model: + anyOf: + - type: string + description: Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models. + - type: 'null' + input: + anyOf: + - description: Text, image, or file inputs to the model, used to generate a response anyOf: - type: string - description: | - The truncation strategy to use for the model response. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. - enum: - - auto - - disabled - default: disabled - - type: 'null' - id: - type: string - description: | - Unique identifier for this Response. - object: - type: string - description: | - The object type of this resource - always set to `response`. - enum: - - response - x-stainless-const: true - status: - type: string - description: | - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. - enum: - - completed - - failed - - in_progress - - cancelled - - queued - - incomplete - created_at: - type: number - format: unixtime - description: | - Unix timestamp (in seconds) of when this Response was created. - completed_at: - anyOf: - - type: number - format: unixtime - description: | - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. - - type: 'null' - error: - $ref: '#/components/schemas/BetaResponseError' - incomplete_details: - anyOf: - - type: object - description: | - Details about why the response is incomplete. - properties: - reason: - type: string - description: | - The reason why the response is incomplete. `steered` means - the response stopped at a safe output boundary after a - WebSocket `response.steer` event. The server can then create - a successor response automatically with the queued input. - enum: - - max_output_tokens - - max_messages - - content_filter - - steered - - type: 'null' - output: + maxLength: 10485760 + description: A text input to the model, equivalent to a text input with the `user` role. + - items: + $ref: '#/components/schemas/BetaInputItem' + type: array + maxItems: 131072 + description: A list of one or many input items to the model, containing different content types. + - type: 'null' + previous_response_id: + anyOf: + - type: string + description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + example: resp_123 + - type: 'null' + tools: + anyOf: + - items: + $ref: '#/components/schemas/BetaTool' type: array - description: | - An array of content items generated by the model. - - - The length and order of items in the `output` array is dependent - on the model's response. - - Rather than accessing the first item in the `output` array and - assuming it's an `assistant` message with the content generated by - the model, you might consider using the `output_text` property where - supported in SDKs. - items: - $ref: '#/components/schemas/BetaOutputItem' - reasoning: - anyOf: - - $ref: '#/components/schemas/BetaReasoning' - - type: 'null' - instructions: - anyOf: - - description: | - A system (or developer) message inserted into the model's context. - - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. - anyOf: - - type: string - description: | - A text input to the model, equivalent to a text input with the - `developer` role. - - type: array - title: Input item list - description: | - A list of one or many input items to the model, containing - different content types. - items: - $ref: '#/components/schemas/BetaInputItem' - - type: 'null' - output_text: - anyOf: - - type: string - description: | - SDK-only convenience property that contains the aggregated text output - from all `output_text` items in the `output` array, if any are present. - Supported in the Python and JavaScript SDKs. - x-oaiSupportedSDKs: - - python - - javascript - - type: 'null' - x-stainless-skip: true - usage: - $ref: '#/components/schemas/BetaResponseUsage' - prompt_cache_options: - $ref: '#/components/schemas/BetaPromptCacheOptions' - prompt_cache_diagnostics: - $ref: '#/components/schemas/BetaPromptCacheDiagnostics' - moderation: - anyOf: - - $ref: '#/components/schemas/BetaModeration' - description: | - Moderation results for the response input and output, if moderated completions were requested. - - type: 'null' - parallel_tool_calls: - type: boolean - description: | - Whether to allow the model to run tool calls in parallel. - default: true - conversation: - anyOf: - - $ref: '#/components/schemas/BetaResponseConversation' - - type: 'null' - max_output_tokens: - anyOf: - - description: | - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning). - type: integer - - type: 'null' - required: - - id - - object - - created_at - - error - - incomplete_details - - instructions - - model - - tools - - output - - parallel_tool_calls - - metadata - - tool_choice - - temperature - - top_p - BetaResponseConversation: + description: 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. + - type: 'null' + text: + anyOf: + - $ref: '#/components/schemas/BetaResponseTextParam' + - type: 'null' + reasoning: + anyOf: + - $ref: '#/components/schemas/BetaReasoning' + description: '**gpt-5 and o-series models only** Configuration options for [reasoning models](https://developers.openai.com/api/docs/guides/reasoning).' + - type: 'null' + truncation: + $ref: '#/components/schemas/BetaTruncationEnum' + description: 'The truncation strategy to use for the model response. - `auto`: If the input to this Response exceeds the model''s context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation. - `disabled` (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.' + deprecated: true + instructions: + anyOf: + - type: string + description: |- + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + - type: 'null' + personality: + $ref: '#/components/schemas/BetaPersonalityEnum' + description: A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + conversation: + anyOf: + - $ref: '#/components/schemas/BetaConversationParam' + - type: 'null' + tool_choice: + anyOf: + - $ref: '#/components/schemas/BetaToolChoiceParam' + description: Controls which tool the model should use, if any. + - type: 'null' + parallel_tool_calls: + anyOf: + - type: boolean + description: Whether to allow the model to run tool calls in parallel. + - type: 'null' + type: object + required: [] + BetaToolChoiceParam: + description: | + 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. + anyOf: + - $ref: '#/components/schemas/BetaToolChoiceOptions' + - $ref: '#/components/schemas/BetaToolChoiceAllowed' + - $ref: '#/components/schemas/BetaToolChoiceTypes' + - $ref: '#/components/schemas/BetaToolChoiceFunction' + - $ref: '#/components/schemas/BetaToolChoiceMCP' + - $ref: '#/components/schemas/BetaToolChoiceCustom' + - $ref: '#/components/schemas/BetaSpecificProgrammaticToolCallingParam' + - $ref: '#/components/schemas/BetaSpecificApplyPatchParam' + - $ref: '#/components/schemas/BetaSpecificFunctionShellParam' + BetaSpecificFunctionShellParam: properties: - id: + type: type: string - description: The unique ID of the conversation that this response was associated with. + enum: + - shell + description: The tool to call. Always `shell`. + default: shell + x-stainless-const: true type: object required: - - id - title: Conversation - description: The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - BetaModeration: + - type + title: Specific shell tool choice + description: Forces the model to call the shell tool when a tool call is required. + BetaSpecificApplyPatchParam: properties: - input: - discriminator: - propertyName: type - description: Moderation for the response input. - anyOf: - - $ref: '#/components/schemas/BetaModerationResultBody' - - $ref: '#/components/schemas/BetaModerationErrorBody' - output: - discriminator: - propertyName: type - description: Moderation for the response output. - anyOf: - - $ref: '#/components/schemas/BetaModerationResultBody' - - $ref: '#/components/schemas/BetaModerationErrorBody' + type: + type: string + enum: + - apply_patch + description: The tool to call. Always `apply_patch`. + default: apply_patch + x-stainless-const: true type: object required: - - input - - output - title: Moderation - description: Moderation results or errors for the response input and output. - BetaModerationErrorBody: + - type + title: Specific apply patch tool choice + description: Forces the model to call the apply_patch tool when executing a tool call. + BetaSpecificProgrammaticToolCallingParam: properties: type: type: string enum: - - error - description: The object type, which was always `error` for moderation failures. - default: error + - programmatic_tool_calling + description: The tool to call. Always `programmatic_tool_calling`. + default: programmatic_tool_calling x-stainless-const: true - code: - type: string - description: The error code. - message: - type: string - description: The error message. type: object required: - type - - code - - message - title: Moderation error - description: An error produced while attempting moderation for the response input or output. - BetaModerationResultBody: + BetaToolChoiceCustom: + type: object + title: Custom tool + description: | + Use this option to force the model to call a specific custom tool. properties: type: type: string enum: - - moderation_result - description: The object type, which was always `moderation_result` for successful moderation results. - default: moderation_result + - custom + description: For custom tool calling, the type is always `custom`. x-stainless-const: true - model: + name: type: string - description: The moderation model that produced this result. - flagged: - type: boolean - description: A boolean indicating whether the content was flagged by any category. - categories: - additionalProperties: - type: boolean - type: object - description: A dictionary of moderation categories to booleans, True if the input is flagged under this category. - x-oaiTypeLabel: map - category_scores: - additionalProperties: - type: number - type: object - description: A dictionary of moderation categories to scores. - x-oaiTypeLabel: map - category_applied_input_types: - additionalProperties: - items: - $ref: '#/components/schemas/BetaModerationInputType' - type: array - type: object - description: Which modalities of input are reflected by the score for each category. - x-oaiTypeLabel: map - type: object + description: The name of the custom tool to call. required: - type - - model - - flagged - - categories - - category_scores - - category_applied_input_types - title: Moderation result - description: A moderation result produced for the response input or output. - BetaModerationInputType: - type: string - enum: - - text - - image - BetaPromptCacheDiagnostics: - discriminator: - propertyName: type - description: Prompt cache diagnostics requested for this response. - anyOf: - - $ref: '#/components/schemas/BetaPromptCacheMissDiagnosticsBody' - - $ref: '#/components/schemas/BetaPromptCacheHitDiagnosticsBody' - - $ref: '#/components/schemas/BetaPromptCacheComparisonResponseNotFoundDiagnosticsBody' - - $ref: '#/components/schemas/BetaPromptCacheUnavailableDiagnosticsBody' - BetaPromptCacheUnavailableDiagnosticsBody: + - name + BetaToolChoiceMCP: + type: object + title: MCP tool + description: | + Use this option to force the model to call a specific tool on a remote MCP server. properties: type: type: string enum: - - unavailable - default: unavailable + - mcp + description: For MCP tools, the type is always `mcp`. x-stainless-const: true - type: object + server_label: + type: string + description: | + The label of the MCP server to use. + name: + anyOf: + - type: string + description: | + The name of the tool to call on the server. + - type: 'null' required: - type - BetaPromptCacheComparisonResponseNotFoundDiagnosticsBody: + - server_label + BetaToolChoiceFunction: + type: object + title: Function tool + description: | + Use this option to force the model to call a specific function. properties: type: type: string enum: - - comparison_response_not_found - default: comparison_response_not_found + - function + description: For function calling, the type is always `function`. x-stainless-const: true - type: object + name: + type: string + description: The name of the function to call. required: - type - BetaPromptCacheHitDiagnosticsBody: + - name + BetaToolChoiceTypes: + type: object + title: Hosted tool + description: | + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](https://developers.openai.com/api/docs/guides/tools). properties: type: type: string + description: | + The type of hosted tool the model should to use. Learn more about + [built-in tools](https://developers.openai.com/api/docs/guides/tools). + + Allowed values are: + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` enum: - - cache_hit - default: cache_hit - x-stainless-const: true - type: object + - file_search + - web_search_preview + - computer + - computer_use_preview + - computer_use + - web_search_preview_2025_03_11 + - image_generation + - code_interpreter required: - type - BetaPromptCacheMissDiagnosticsBody: + BetaToolChoiceAllowed: + type: object + title: Allowed tools + description: | + Constrains the tools available to the model to a pre-defined set. properties: type: type: string enum: - - cache_miss - default: cache_miss + - allowed_tools + description: Allowed tool configuration type. Always `allowed_tools`. x-stainless-const: true - reason: - $ref: '#/components/schemas/BetaCacheMissReasonTypeEnum' - description: The reason prompt cache reuse did not occur. - cache_missed_tokens: - type: integer - description: The estimated number of input tokens affected after the first detected divergence. - comparison_reusable_tokens: - type: integer - description: The raw token count of the reusable prefix in the compared response. - type: object - required: - - type - - reason - - cache_missed_tokens - BetaCacheMissReasonTypeEnum: - type: string - enum: - - model_changed - - prompt_cache_key_changed - - tools_changed - - text_format_changed - - reasoning_effort_changed - - verbosity_changed - - context_compacted - - input_changed - - service_tier_changed - BetaPromptCacheOptions: - properties: - ttl: - $ref: '#/components/schemas/BetaPromptCacheTTLEnum' - description: The minimum lifetime applied to each cache breakpoint. mode: - $ref: '#/components/schemas/BetaPromptCacheModeEnum' - description: Whether implicit prompt-cache breakpoints were enabled. - comparison_response_id: - anyOf: - - type: string - description: The response ID supplied as the prompt cache diagnostics comparison. - - type: 'null' - type: object + type: string + enum: + - auto + - required + description: | + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + tools: + type: array + description: | + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + items: + type: object + description: | + A tool definition that the model should be allowed to call. + additionalProperties: true + x-oaiExpandable: false required: - - ttl + - type - mode - title: Prompt cache options - description: The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - BetaOutputItem: - discriminator: - propertyName: type - anyOf: - - $ref: '#/components/schemas/BetaOutputMessage' - - $ref: '#/components/schemas/BetaFileSearchToolCall' - - $ref: '#/components/schemas/BetaFunctionToolCall' - - $ref: '#/components/schemas/BetaFunctionToolCallOutputResource' - - $ref: '#/components/schemas/BetaAgentMessage' - - $ref: '#/components/schemas/BetaMultiAgentCall' - - $ref: '#/components/schemas/BetaMultiAgentCallOutput' - - $ref: '#/components/schemas/BetaWebSearchToolCall' - - $ref: '#/components/schemas/BetaComputerToolCall' - - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' - - $ref: '#/components/schemas/BetaReasoningItem' - - $ref: '#/components/schemas/BetaProgram' - - $ref: '#/components/schemas/BetaProgramOutput' - - $ref: '#/components/schemas/BetaToolSearchCall' - - $ref: '#/components/schemas/BetaToolSearchOutput' - - $ref: '#/components/schemas/BetaAdditionalTools' - - $ref: '#/components/schemas/BetaCompactionBody' - - $ref: '#/components/schemas/BetaImageGenToolCall' - - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCall' - - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' - - $ref: '#/components/schemas/BetaFunctionShellCall' - - $ref: '#/components/schemas/BetaFunctionShellCallOutput' - - $ref: '#/components/schemas/BetaApplyPatchToolCall' - - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' - - $ref: '#/components/schemas/BetaMCPToolCall' - - $ref: '#/components/schemas/BetaMCPListTools' - - $ref: '#/components/schemas/BetaMCPApprovalRequest' - - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' - - $ref: '#/components/schemas/BetaCustomToolCall' - - $ref: '#/components/schemas/BetaCustomToolCallOutputResource' - BetaResponseError: - anyOf: - - type: object - description: | - An error object returned when the model fails to generate a Response. - properties: - code: - $ref: '#/components/schemas/BetaResponseErrorCode' - message: - type: string - description: | - A human-readable description of the error. - misalignment: - $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' - required: - - code - - message - - type: 'null' - BetaResponseErrorCode: + - tools + BetaToolChoiceOptions: type: string + title: Tool choice mode description: | - The error code for the response. + 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. enum: - - server_error - - rate_limit_exceeded - - invalid_prompt - - data_residency_mismatch - - bio_policy - - misalignment_policy_violation - - 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 - BetaServiceTierResponses: + - none + - auto + - required + BetaConversationParam: + description: | + 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. anyOf: - type: string + title: Conversation ID description: | - Specifies the processing type used for serving the request. - - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - - If set to '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier. - - To opt-in to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. The response will show `service_tier=priority` regardless of if you specify `service_tier=fast` or `priority` in your request. - - If set to 'ultrafast', then the request will be processed with the access-controlled Ultrafast Processing service tier. This tier is currently available for `gpt-5.6-sol`; a response served through it will show `service_tier=ultrafast`. - - When not set, the default behavior is 'auto'. - - When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + The unique ID of the conversation. + - $ref: '#/components/schemas/BetaConversationParam-2' + BetaConversationParam-2: + properties: + id: + type: string + description: The unique ID of the conversation. + example: conv_123 + type: object + required: + - id + title: Conversation object + description: The conversation that this response belongs to. + BetaPersonalityEnum: + anyOf: + - type: string + - type: string enum: - - auto - - default - - flex - - scale - - priority - - fast - - ultrafast - default: auto - - type: 'null' - BetaResponseProperties: + - friendly + - pragmatic + BetaTruncationEnum: + type: string + enum: + - auto + - disabled + BetaReasoning: type: object + description: | + Configuration options for + [reasoning models](https://developers.openai.com/api/docs/guides/reasoning). + title: Reasoning properties: - previous_response_id: + mode: + $ref: '#/components/schemas/BetaReasoningModeEnum' + description: | + Controls the reasoning execution mode for the request. + + When returned on a response, this is the effective execution mode. + effort: + $ref: '#/components/schemas/BetaReasoningEffort' + summary: anyOf: - type: string description: | - The unique ID of the previous response to the model. Use this to - create multi-turn conversations. Learn more about - [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + enum: + - auto + - concise + - detailed - type: 'null' - model: - description: | - Model ID used to generate the response, like `gpt-6-astra`. OpenAI - offers a wide range of models with different capabilities, performance - characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) - to browse and compare available models. - $ref: '#/components/schemas/BetaModelIdsResponses' - background: + context: anyOf: - - type: boolean + - type: string description: | - Whether to run the model response in the background. - [Learn more](https://developers.openai.com/api/docs/guides/background). - default: false + Controls which reasoning items are rendered back to the model on later turns. + If omitted or set to `auto`, the model determines the context mode. The + `gpt-5.6` model family defaults to `all_turns`; earlier models default to + `current_turn`. + + When returned on a response, this is the effective reasoning context mode + used for the response. + enum: + - auto + - current_turn + - all_turns - type: 'null' - max_tool_calls: + generate_summary: anyOf: - - description: | - The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. - type: integer + - type: string + deprecated: true + description: | + **Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be + useful for debugging and understanding the model's reasoning process. + One of `auto`, `concise`, or `detailed`. + enum: + - auto + - concise + - detailed - type: 'null' - text: - $ref: '#/components/schemas/BetaResponseTextParam' - tools: - $ref: '#/components/schemas/BetaToolsArray' - tool_choice: - $ref: '#/components/schemas/BetaToolChoiceParam' - prompt: - $ref: '#/components/schemas/BetaPrompt' - BetaPrompt: + BetaReasoningEffort: anyOf: - - type: object + - type: string + enum: + - none + - minimal + - low + - medium + - high + - xhigh + - max + default: medium description: | - Reference to a prompt template and its variables. - [Learn more](https://developers.openai.com/api/docs/guides/text?api-mode=responses#version-prompts-in-code). - required: - - id - properties: - id: - type: string - description: The unique identifier of the prompt template to use. - version: - anyOf: - - type: string - description: Optional version of the prompt template. - - type: 'null' - variables: - $ref: '#/components/schemas/BetaResponsePromptVariables' + Constrains effort on reasoning for reasoning models. Currently supported + values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. + Reducing reasoning effort can result in faster responses and fewer tokens + used on reasoning in a response. Not all reasoning models support every + value. See the + [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) + for model-specific support. - type: 'null' - BetaResponsePromptVariables: + BetaReasoningModeEnum: anyOf: - - type: object - title: Prompt Variables + - type: string + - type: string + enum: + - standard + - pro + BetaResponseTextParam: + type: object + description: | + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: + - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) + - [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) + properties: + format: + $ref: '#/components/schemas/BetaTextResponseFormatConfiguration' + verbosity: + $ref: '#/components/schemas/BetaVerbosity' + BetaVerbosity: + anyOf: + - type: string + enum: + - low + - medium + - high + default: medium description: | - Optional map of values to substitute in for variables in your - prompt. The substitution values can either be strings, or other - Response input types like images or files. - x-oaiExpandable: true - x-oaiTypeLabel: map - additionalProperties: - x-oaiExpandable: true - x-oaiTypeLabel: map - anyOf: - - type: string - - $ref: '#/components/schemas/BetaInputTextContent' - - $ref: '#/components/schemas/BetaInputImageContent' - - $ref: '#/components/schemas/BetaInputFileContent' + Constrains the verbosity of the model's response. Lower values will result in + more concise responses, while higher values will result in more verbose responses. + Currently supported values are `low`, `medium`, and `high`. The default is + `medium`. - type: 'null' - BetaToolsArray: - type: array + BetaTextResponseFormatConfiguration: description: | - 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. + An object specifying the format that the model must output. - We support the following categories of tools: - - **Built-in tools**: Tools that are provided by OpenAI that extend the - model's capabilities, like [web search](https://developers.openai.com/api/docs/guides/tools-web-search) - or [file search](https://developers.openai.com/api/docs/guides/tools-file-search). Learn more about - [built-in tools](https://developers.openai.com/api/docs/guides/tools). - - **MCP Tools**: Integrations with third-party systems via custom MCP servers - or predefined connectors such as Google Drive and SharePoint. Built-in - connectors using `connector_id` are deprecated for models released after - September 1, 2026. Use `server_url` to connect to a remote MCP server, or - `tunnel_id` to connect through a Secure MCP Tunnel. Learn more about - [MCP Tools](https://developers.openai.com/api/docs/guides/tools-connectors-mcp). - - **Function calls (custom tools)**: Functions that are defined by you, - enabling the model to call your own code with strongly typed arguments - and outputs. Learn more about - [function calling](https://developers.openai.com/api/docs/guides/function-calling). You can also use - custom tools to call your own code. - items: - $ref: '#/components/schemas/BetaTool' - BetaModelResponseProperties: - type: object - properties: - metadata: - $ref: '#/components/schemas/BetaMetadata' - top_logprobs: - anyOf: - - description: | - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. - type: integer - minimum: 0 - maximum: 20 - - type: 'null' - temperature: - anyOf: - - type: number - minimum: 0 - maximum: 2 - default: 1 - example: 1 - description: | - What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. - - type: 'null' - top_p: - anyOf: - - type: number - minimum: 0 - maximum: 1 - default: 1 - example: 1 - description: | - An alternative to sampling with temperature, called nucleus sampling, - where the model considers the results of the tokens with top_p probability - mass. So 0.1 means only the tokens comprising the top 10% probability mass - are considered. + Configuring `{ "type": "json_schema" }` enables Structured Outputs, + which ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs). - We generally recommend altering this or `temperature` but not both. - - type: 'null' - user: - type: string - example: user-1234 - deprecated: true - description: | - This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. - A stable identifier for your end-users. - Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). - safety_identifier: - anyOf: - - type: string - maxLength: 64 - example: safety-identifier-1234 - description: | - A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. - The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). - - type: 'null' - prompt_cache_key: - anyOf: - - type: string - example: prompt-cache-key-1234 - description: | - Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching). - - type: 'null' - prompt_cache_retention: - deprecated: true - anyOf: - - type: string - enum: - - in_memory - - 24h - description: | - Deprecated. Use `prompt_cache_options.ttl` instead. + The default format is `{ "type": "text" }` with no additional options. - The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching#prompt-cache-retention). - This field expresses a maximum retention policy, while - `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two - fields are independent and do not interact. - For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + **Not recommended for gpt-4o and newer models:** - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - type: 'null' - BetaMetadata: + 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. anyOf: - - type: object - description: | - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - additionalProperties: + - $ref: '#/components/schemas/BetaResponseFormatText' + - $ref: '#/components/schemas/BetaTextResponseFormatJsonSchema' + - $ref: '#/components/schemas/BetaResponseFormatJsonObject' + discriminator: + propertyName: type + BetaResponseFormatJsonObject: + type: object + title: JSON object + description: | + 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. + properties: + type: type: string - x-oaiTypeLabel: map - - type: 'null' - BetaResponseOutputTextAnnotationAddedEvent: + description: The type of response format being defined. Always `json_object`. + enum: + - json_object + x-stainless-const: true + required: + - type + BetaTextResponseFormatJsonSchema: type: object - title: ResponseOutputTextAnnotationAddedEvent + title: JSON schema description: | - Emitted when an annotation is added to output text content. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs). properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string + description: The type of response format being defined. Always `json_schema`. enum: - - response.output_text.annotation.added - description: The type of the event. Always 'response.output_text.annotation.added'. + - json_schema x-stainless-const: true - item_id: + description: type: string - description: The unique identifier of the item to which the annotation is being added. - output_index: - type: integer - description: The index of the output item in the response's output array. - content_index: - type: integer - description: The index of the content part within the output item. - annotation_index: - type: integer - description: The index of the annotation within the content part. - sequence_number: - type: integer - description: The sequence number of this event. - annotation: + description: | + A description of what the response format is for, used by the model to + determine how to respond in the format. + name: + type: string + description: | + The name of the response format. Must be a-z, A-Z, 0-9, or contain + underscores and dashes, with a maximum length of 64. + schema: + $ref: '#/components/schemas/BetaResponseFormatJsonSchemaSchema' + strict: anyOf: - - $ref: '#/components/schemas/BetaAnnotation' + - type: boolean + default: false + description: | + Whether to enable strict schema adherence when generating the output. + If set to true, the model will always follow the exact schema defined + in the `schema` field. Only a subset of JSON Schema is supported when + `strict` is `true`. To learn more, read the [Structured Outputs + guide](https://developers.openai.com/api/docs/guides/structured-outputs). - type: 'null' - description: The annotation object being added. (See annotation schema for details.) required: - type - - item_id - - output_index - - content_index - - annotation_index - - annotation - - sequence_number - x-oaiMeta: - name: response.output_text.annotation.added - group: responses - example: | - { - "type": "response.output_text.annotation.added", - "item_id": "item-abc", - "output_index": 0, - "content_index": 0, - "annotation_index": 0, - "annotation": { - "type": "file_citation", - "file_id": "file-abc", - "index": 0, - "filename": "example.txt" - }, - "sequence_number": 1 - } - BetaResponseMCPListToolsInProgressEvent: + - schema + - name + BetaResponseFormatJsonSchemaSchema: type: object - title: ResponseMCPListToolsInProgressEvent + title: JSON schema description: | - Emitted when the system is in the process of retrieving the list of available MCP tools. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + additionalProperties: true + BetaResponseFormatText: + type: object + title: Text + description: | + Default response format. Used to generate text responses. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string + description: The type of response format being defined. Always `text`. enum: - - response.mcp_list_tools.in_progress - description: The type of the event. Always 'response.mcp_list_tools.in_progress'. + - text x-stainless-const: true - item_id: - type: string - description: The ID of the MCP tool call item that is being processed. - output_index: - type: integer - description: The index of the output item that is being processed. - sequence_number: - type: integer - description: The sequence number of this event. required: - type - - item_id - - output_index - - sequence_number - x-oaiMeta: - name: response.mcp_list_tools.in_progress - group: responses - example: | - { - "type": "response.mcp_list_tools.in_progress", - "sequence_number": 1, - "output_index": 0, - "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" - } - BetaResponseMCPListToolsFailedEvent: - type: object - title: ResponseMCPListToolsFailedEvent + BetaTool: description: | - Emitted when the attempt to list available MCP tools has failed. + A tool that can be used to generate a response. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaFunctionTool' + - $ref: '#/components/schemas/BetaFileSearchTool' + - $ref: '#/components/schemas/BetaComputerTool' + - $ref: '#/components/schemas/BetaComputerUsePreviewTool' + - $ref: '#/components/schemas/BetaWebSearchTool' + - $ref: '#/components/schemas/BetaMCPTool' + - $ref: '#/components/schemas/BetaCodeInterpreterTool' + - $ref: '#/components/schemas/BetaProgrammaticToolCallingParam' + - $ref: '#/components/schemas/BetaImageGenTool' + - $ref: '#/components/schemas/BetaLocalShellToolParam' + - $ref: '#/components/schemas/BetaFunctionShellToolParam' + - $ref: '#/components/schemas/BetaCustomToolParam' + - $ref: '#/components/schemas/BetaNamespaceToolParam' + - $ref: '#/components/schemas/BetaToolSearchToolParam' + - $ref: '#/components/schemas/BetaWebSearchPreviewTool' + - $ref: '#/components/schemas/BetaApplyPatchToolParam' + BetaApplyPatchToolParam: properties: - agent: + type: + type: string + enum: + - apply_patch + description: The type of the tool. Always `apply_patch`. + default: apply_patch + x-stainless-const: true + allowed_callers: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + type: array + minItems: 1 + description: The tool invocation context(s). - type: 'null' - description: The agent that owns this multi-agent streaming event. + type: object + required: + - type + title: Apply patch tool + description: Allows the assistant to create, delete, or update files using unified diffs. + BetaCallableToolAllowedCaller: + type: string + enum: + - direct + - programmatic + BetaWebSearchPreviewTool: + properties: type: type: string enum: - - response.mcp_list_tools.failed - description: The type of the event. Always 'response.mcp_list_tools.failed'. + - web_search_preview + - web_search_preview_2025_03_11 + description: The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + default: web_search_preview x-stainless-const: true - item_id: - type: string - description: The ID of the MCP tool call item that failed. - output_index: - type: integer - description: The index of the output item that failed. - sequence_number: - type: integer - description: The sequence number of this event. + user_location: + anyOf: + - $ref: '#/components/schemas/BetaApproximateLocation' + description: The user's location. + - type: 'null' + search_context_size: + $ref: '#/components/schemas/BetaSearchContextSize' + description: 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. + search_content_types: + items: + $ref: '#/components/schemas/BetaSearchContentType' + type: array + type: object required: - type - - item_id - - output_index - - sequence_number - x-oaiMeta: - name: response.mcp_list_tools.failed - group: responses - example: | - { - "type": "response.mcp_list_tools.failed", - "sequence_number": 1, - "output_index": 0, - "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" - } - BetaResponseMCPListToolsCompletedEvent: - type: object - title: ResponseMCPListToolsCompletedEvent - description: | - Emitted when the list of available MCP tools has been successfully retrieved. + title: Web search preview + description: This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search). + BetaSearchContentType: + type: string + enum: + - text + - image + BetaSearchContextSize: + type: string + enum: + - low + - medium + - high + BetaApproximateLocation: properties: - agent: + type: + type: string + enum: + - approximate + description: The type of location approximation. Always `approximate`. + default: approximate + x-stainless-const: true + country: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - type: string + description: The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - type: 'null' - description: The agent that owns this multi-agent streaming event. + region: + anyOf: + - type: string + description: Free text input for the region of the user, e.g. `California`. + - type: 'null' + city: + anyOf: + - type: string + description: Free text input for the city of the user, e.g. `San Francisco`. + - type: 'null' + timezone: + anyOf: + - type: string + description: The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - type: 'null' + type: object + required: + - type + BetaToolSearchToolParam: + properties: type: type: string enum: - - response.mcp_list_tools.completed - description: The type of the event. Always 'response.mcp_list_tools.completed'. + - tool_search + description: The type of the tool. Always `tool_search`. + default: tool_search x-stainless-const: true - item_id: - type: string - description: The ID of the MCP tool call item that produced this output. - output_index: - type: integer - description: The index of the output item that was processed. - sequence_number: - type: integer - description: The sequence number of this event. + execution: + $ref: '#/components/schemas/BetaToolSearchExecutionType' + description: Whether tool search is executed by the server or by the client. + description: + anyOf: + - type: string + description: Description shown to the model for a client-executed tool search tool. + - type: 'null' + parameters: + anyOf: + - $ref: '#/components/schemas/BetaEmptyModelParam' + description: Parameter schema for a client-executed tool search tool. + - type: 'null' + type: object required: - type - - item_id - - output_index - - sequence_number - x-oaiMeta: - name: response.mcp_list_tools.completed - group: responses - example: | - { - "type": "response.mcp_list_tools.completed", - "sequence_number": 1, - "output_index": 0, - "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" - } - BetaResponseMCPCallInProgressEvent: + title: Tool search tool + description: Hosted or BYOT tool search configuration for deferred tools. + BetaEmptyModelParam: + properties: {} type: object - title: ResponseMCPCallInProgressEvent - description: | - Emitted when an MCP tool call is in progress. + required: [] + BetaToolSearchExecutionType: + type: string + enum: + - server + - client + BetaNamespaceToolParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.mcp_call.in_progress - description: The type of the event. Always 'response.mcp_call.in_progress'. + - namespace + description: The type of the tool. Always `namespace`. + default: namespace x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of this event. - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: + name: type: string - description: The unique identifier of the MCP tool call item being processed. + minLength: 1 + description: The namespace name used in tool calls (for example, `crm`). + description: + type: string + description: A description of the namespace shown to the model. + tools: + items: + discriminator: + propertyName: type + description: A function or custom tool that belongs to a namespace. + anyOf: + - $ref: '#/components/schemas/BetaFunctionToolParam' + - $ref: '#/components/schemas/BetaCustomToolParam' + type: array + minItems: 1 + description: The function/custom tools available inside this namespace. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.mcp_call.in_progress - group: responses - example: | - { - "type": "response.mcp_call.in_progress", - "sequence_number": 1, - "output_index": 0, - "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90" - } - BetaResponseMCPCallFailedEvent: - type: object - title: ResponseMCPCallFailedEvent - description: | - Emitted when an MCP tool call has failed. + - name + - description + - tools + title: Namespace + description: Groups function/custom tools under a shared namespace. + BetaCustomToolParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.mcp_call.failed - description: The type of the event. Always 'response.mcp_call.failed'. + - custom + description: The type of the custom tool. Always `custom`. + default: custom x-stainless-const: true - item_id: + name: type: string - description: The ID of the MCP tool call item that failed. - output_index: - type: integer - description: The index of the output item that failed. - sequence_number: - type: integer - description: The sequence number of this event. + description: The name of the custom tool, used to identify it in tool calls. + async: + type: boolean + description: Whether the tool response can be returned asynchronously versus immediately returned on next response creation. + description: + type: string + description: Optional description of the custom tool, used to provide more context. + format: + discriminator: + propertyName: type + description: The input format for the custom tool. Default is unconstrained text. + anyOf: + - $ref: '#/components/schemas/BetaCustomTextFormatParam' + - $ref: '#/components/schemas/BetaCustomGrammarFormatParam' + defer_loading: + type: boolean + description: Whether this tool should be deferred and discovered via tool search. + allowed_callers: + anyOf: + - items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + type: array + minItems: 1 + description: The tool invocation context(s). + - type: 'null' + type: object required: - type - - item_id - - output_index - - sequence_number - x-oaiMeta: - name: response.mcp_call.failed - group: responses - example: | - { - "type": "response.mcp_call.failed", - "sequence_number": 1, - "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90", - "output_index": 0 - } - BetaResponseMCPCallCompletedEvent: - type: object - title: ResponseMCPCallCompletedEvent - description: | - Emitted when an MCP tool call has completed successfully. + - name + title: Custom tool + description: A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools) + BetaCustomGrammarFormatParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.mcp_call.completed - description: The type of the event. Always 'response.mcp_call.completed'. + - grammar + description: Grammar format. Always `grammar`. + default: grammar x-stainless-const: true - item_id: + syntax: + $ref: '#/components/schemas/BetaGrammarSyntax1' + description: The syntax of the grammar definition. One of `lark` or `regex`. + definition: type: string - description: The ID of the MCP tool call item that completed. - output_index: - type: integer - description: The index of the output item that completed. - sequence_number: - type: integer - description: The sequence number of this event. + description: The grammar definition. + type: object required: - type - - item_id - - output_index - - sequence_number - x-oaiMeta: - name: response.mcp_call.completed - group: responses - example: | - { - "type": "response.mcp_call.completed", - "sequence_number": 1, - "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90", - "output_index": 0 - } - BetaResponseMCPCallArgumentsDoneEvent: - type: object - title: ResponseMCPCallArgumentsDoneEvent - description: | - Emitted when the arguments for an MCP tool call are finalized. + - syntax + - definition + title: Grammar format + description: A grammar defined by the user. + BetaGrammarSyntax1: + type: string + enum: + - lark + - regex + BetaCustomTextFormatParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.mcp_call_arguments.done - description: The type of the event. Always 'response.mcp_call_arguments.done'. + - text + description: Unconstrained text format. Always `text`. + default: text x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: - type: string - description: The unique identifier of the MCP tool call item being processed. - arguments: - type: string - description: | - A JSON string containing the finalized arguments for the MCP tool call. - sequence_number: - type: integer - description: The sequence number of this event. + type: object required: - type - - output_index - - item_id - - arguments - - sequence_number - x-oaiMeta: - name: response.mcp_call_arguments.done - group: responses - example: | - { - "type": "response.mcp_call_arguments.done", - "output_index": 0, - "item_id": "item-abc", - "arguments": "{\"arg1\": \"value1\", \"arg2\": \"value2\"}", - "sequence_number": 1 - } - BetaResponseMCPCallArgumentsDeltaEvent: - type: object - title: ResponseMCPCallArgumentsDeltaEvent - description: | - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + title: Text format + description: Unconstrained free-form text. + BetaFunctionToolParam: properties: - agent: + name: + type: string + maxLength: 128 + minLength: 1 + pattern: ^[a-zA-Z0-9_-]+$ + description: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - type: string + - type: 'null' + parameters: + anyOf: + - $ref: '#/components/schemas/BetaEmptyModelParam' + - type: 'null' + strict: + anyOf: + - type: boolean + description: Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.mcp_call_arguments.delta - description: The type of the event. Always 'response.mcp_call_arguments.delta'. + - function + default: function x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: - type: string - description: The unique identifier of the MCP tool call item being processed. - delta: - type: string - description: | - A JSON string containing the partial update to the arguments for the MCP tool call. - sequence_number: - type: integer - description: The sequence number of this event. + async: + type: boolean + description: Whether the tool response can be returned asynchronously versus immediately returned on next response creation. + output_schema: + anyOf: + - additionalProperties: {} + type: object + description: A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + x-oaiTypeLabel: map + - type: 'null' + defer_loading: + type: boolean + description: Whether this function should be deferred and discovered via tool search. + allowed_callers: + anyOf: + - items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + type: array + minItems: 1 + description: The tool invocation context(s). + - type: 'null' + type: object required: + - name - type - - output_index - - item_id - - delta - - sequence_number - x-oaiMeta: - name: response.mcp_call_arguments.delta - group: responses - example: | - { - "type": "response.mcp_call_arguments.delta", - "output_index": 0, - "item_id": "item-abc", - "delta": "{", - "sequence_number": 1 - } - BetaResponseImageGenCallPartialImageEvent: - type: object - title: ResponseImageGenCallPartialImageEvent - description: | - Emitted when a partial image is available during image generation streaming. + BetaFunctionShellToolParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.image_generation_call.partial_image - description: The type of the event. Always 'response.image_generation_call.partial_image'. + - shell + description: The type of the shell tool. Always `shell`. + default: shell x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: - type: string - description: The unique identifier of the image generation item being processed. - sequence_number: - type: integer - description: The sequence number of the image generation item being processed. - partial_image_index: - type: integer - description: 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - partial_image_b64: - type: string - description: Base64-encoded partial image data, suitable for rendering as an image. - size: - type: string - description: The image size that was used. - quality: - type: string - description: The image quality that was used. - background: - type: string - description: The background setting that was used. - output_format: - type: string - description: The output format that was used. + environment: + anyOf: + - discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaContainerAutoParam' + - $ref: '#/components/schemas/BetaLocalEnvironmentParam' + - $ref: '#/components/schemas/BetaContainerReferenceParam' + - type: 'null' + allowed_callers: + anyOf: + - items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + type: array + minItems: 1 + description: The tool invocation context(s). + - type: 'null' + type: object required: - type - - output_index - - item_id - - sequence_number - - partial_image_index - - partial_image_b64 - x-oaiMeta: - name: response.image_generation_call.partial_image - group: responses - example: | - { - "type": "response.image_generation_call.partial_image", - "output_index": 0, - "item_id": "item-123", - "sequence_number": 0, - "partial_image_index": 0, - "partial_image_b64": "..." - } - BetaResponseImageGenCallInProgressEvent: - type: object - title: ResponseImageGenCallInProgressEvent - description: | - Emitted when an image generation tool call is in progress. + title: Shell tool + description: A tool that allows the model to execute shell commands. + BetaContainerReferenceParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.image_generation_call.in_progress - description: The type of the event. Always 'response.image_generation_call.in_progress'. + - container_reference + description: References a container created with the /v1/containers endpoint + default: container_reference x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: + container_id: type: string - description: The unique identifier of the image generation item being processed. - sequence_number: - type: integer - description: The sequence number of the image generation item being processed. + description: The ID of the referenced container. + example: cntr_123 + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.image_generation_call.in_progress - group: responses - example: | - { - "type": "response.image_generation_call.in_progress", - "output_index": 0, - "item_id": "item-123", - "sequence_number": 0 - } - BetaResponseImageGenCallGeneratingEvent: - type: object - title: ResponseImageGenCallGeneratingEvent - description: | - Emitted when an image generation tool call is actively generating an image (intermediate state). + - container_id + BetaLocalEnvironmentParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.image_generation_call.generating - description: The type of the event. Always 'response.image_generation_call.generating'. + - local + description: Use a local computer environment. + default: local x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - item_id: - type: string - description: The unique identifier of the image generation item being processed. - sequence_number: - type: integer - description: The sequence number of the image generation item being processed. + skills: + items: + $ref: '#/components/schemas/BetaLocalSkillParam' + type: array + maxItems: 200 + description: An optional list of skills. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.image_generation_call.generating - group: responses - example: | - { - "type": "response.image_generation_call.generating", - "output_index": 0, - "item_id": "item-123", - "sequence_number": 0 - } - BetaResponseImageGenCallCompletedEvent: + BetaLocalSkillParam: + properties: + name: + type: string + description: The name of the skill. + description: + type: string + description: The description of the skill. + path: + type: string + description: The path to the directory containing the skill. type: object - title: ResponseImageGenCallCompletedEvent - description: | - Emitted when an image generation tool call has completed and the final image is available. + required: + - name + - description + - path + BetaContainerAutoParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string enum: - - response.image_generation_call.completed - description: The type of the event. Always 'response.image_generation_call.completed'. + - container_auto + description: Automatically creates a container for this request + default: container_auto x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response's output array. - sequence_number: - type: integer - description: The sequence number of this event. - item_id: - type: string - description: The unique identifier of the image generation item being processed. + file_ids: + items: + type: string + example: file-123 + type: array + maxItems: 50 + description: An optional list of uploaded files to make available to your code. + memory_limit: + anyOf: + - $ref: '#/components/schemas/BetaContainerMemoryLimit' + description: The memory limit for the container. + - type: 'null' + network_policy: + discriminator: + propertyName: type + description: Network access policy for the container. + anyOf: + - $ref: '#/components/schemas/BetaContainerNetworkPolicyDisabledParam' + - $ref: '#/components/schemas/BetaContainerNetworkPolicyAllowlistParam' + skills: + items: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaSkillReferenceParam' + - $ref: '#/components/schemas/BetaInlineSkillParam' + type: array + maxItems: 200 + description: An optional list of skills referenced by id or inline data. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.image_generation_call.completed - group: responses - example: | - { - "type": "response.image_generation_call.completed", - "output_index": 0, - "item_id": "item-123", - "sequence_number": 1 - } - BetaResponseReasoningTextDoneEvent: - type: object - description: Emitted when a reasoning text is completed. + BetaInlineSkillParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_text.done`. enum: - - response.reasoning_text.done + - inline + description: Defines an inline skill for this request. + default: inline x-stainless-const: true - item_id: + name: type: string - description: | - The ID of the item this reasoning text is associated with. - output_index: - type: integer - description: | - The index of the output item this reasoning text is associated with. - content_index: - type: integer - description: | - The index of the reasoning content part. - text: + description: The name of the skill. + description: type: string - description: | - The full text of the completed reasoning content. - sequence_number: - type: integer - description: | - The sequence number of this event. + description: The description of the skill. + source: + $ref: '#/components/schemas/BetaInlineSkillSourceParam' + description: Inline skill payload + type: object required: - type - - item_id - - output_index - - content_index - - text - - sequence_number - x-oaiMeta: - name: response.reasoning_text.done - group: responses - example: | - { - "type": "response.reasoning_text.done", - "item_id": "rs_123", - "output_index": 0, - "content_index": 0, - "text": "The user is asking...", - "sequence_number": 4 - } - BetaResponseReasoningTextDeltaEvent: - type: object - description: Emitted when a delta is added to a reasoning text. + - name + - description + - source + BetaInlineSkillSourceParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_text.delta`. enum: - - response.reasoning_text.delta + - base64 + description: The type of the inline skill source. Must be `base64`. + default: base64 x-stainless-const: true - item_id: + media_type: type: string - description: | - The ID of the item this reasoning text delta is associated with. - output_index: - type: integer - description: | - The index of the output item this reasoning text delta is associated with. - content_index: - type: integer - description: | - The index of the reasoning content part this delta is associated with. - delta: + enum: + - application/zip + description: The media type of the inline skill payload. Must be `application/zip`. + default: application/zip + x-stainless-const: true + data: type: string - description: | - The text delta that was added to the reasoning content. - sequence_number: - type: integer - description: | - The sequence number of this event. + maxLength: 70254592 + minLength: 1 + description: Base64-encoded skill zip bundle. + type: object required: - type - - item_id - - output_index - - content_index - - delta - - sequence_number - x-oaiMeta: - name: response.reasoning_text.delta - group: responses - example: | - { - "type": "response.reasoning_text.delta", - "item_id": "rs_123", - "output_index": 0, - "content_index": 0, - "delta": "The", - "sequence_number": 1 - } - BetaResponseReasoningSummaryTextDoneEvent: - type: object - description: Emitted when a reasoning summary text is completed. + - media_type + - data + description: Inline skill payload + BetaSkillReferenceParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_summary_text.done`. enum: - - response.reasoning_summary_text.done + - skill_reference + description: References a skill created with the /v1/skills endpoint. + default: skill_reference x-stainless-const: true - item_id: + skill_id: type: string - description: | - The ID of the item this summary text is associated with. - output_index: - type: integer - description: | - The index of the output item this summary text is associated with. - summary_index: - type: integer - description: | - The index of the summary part within the reasoning summary. - text: + maxLength: 64 + minLength: 1 + description: The ID of the referenced skill. + version: type: string - description: | - The full text of the completed reasoning summary. - sequence_number: - type: integer - description: | - The sequence number of this event. + description: Optional skill version. Use a positive integer or 'latest'. Omit for default. + type: object required: - type - - item_id - - output_index - - summary_index - - text - - sequence_number - x-oaiMeta: - name: response.reasoning_summary_text.done - group: responses - example: | - { - "type": "response.reasoning_summary_text.done", - "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", - "output_index": 0, - "summary_index": 0, - "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!", - "sequence_number": 1 - } - BetaResponseReasoningSummaryTextDeltaEvent: - type: object - description: Emitted when a delta is added to a reasoning summary text. + - skill_id + BetaContainerNetworkPolicyAllowlistParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_summary_text.delta`. enum: - - response.reasoning_summary_text.delta + - allowlist + description: Allow outbound network access only to specified domains. Always `allowlist`. + default: allowlist x-stainless-const: true - item_id: - type: string - description: | - The ID of the item this summary text delta is associated with. - output_index: - type: integer - description: | - The index of the output item this summary text delta is associated with. - summary_index: - type: integer - description: | - The index of the summary part within the reasoning summary. - delta: - type: string - description: | - The text delta that was added to the summary. - sequence_number: - type: integer - description: | - The sequence number of this event. + allowed_domains: + items: + type: string + type: array + minItems: 1 + description: A list of allowed domains when type is `allowlist`. + domain_secrets: + items: + $ref: '#/components/schemas/BetaContainerNetworkPolicyDomainSecretParam' + type: array + minItems: 1 + description: Optional domain-scoped secrets for allowlisted domains. + type: object required: - type - - item_id - - output_index - - summary_index - - delta - - sequence_number - x-oaiMeta: - name: response.reasoning_summary_text.delta - group: responses - example: | - { - "type": "response.reasoning_summary_text.delta", - "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", - "output_index": 0, - "summary_index": 0, - "delta": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!", - "sequence_number": 1 - } - BetaResponseReasoningSummaryPartDoneEvent: + - allowed_domains + BetaContainerNetworkPolicyDomainSecretParam: + properties: + domain: + type: string + minLength: 1 + description: The domain associated with the secret. + name: + type: string + minLength: 1 + description: The name of the secret to inject for the domain. + value: + type: string + maxLength: 10485760 + minLength: 1 + description: The secret value to inject for the domain. type: object - description: Emitted when a reasoning summary part is completed. + required: + - domain + - name + - value + BetaContainerNetworkPolicyDisabledParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_summary_part.done`. enum: - - response.reasoning_summary_part.done + - disabled + description: Disable outbound network access. Always `disabled`. + default: disabled x-stainless-const: true - item_id: - type: string - description: | - The ID of the item this summary part is associated with. - output_index: - type: integer - description: | - The index of the output item this summary part is associated with. - summary_index: - type: integer - description: | - The index of the summary part within the reasoning summary. - status: - type: string - description: | - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. - enum: - - incomplete - sequence_number: - type: integer - description: | - The sequence number of this event. - part: - type: object - description: | - The completed summary part. - properties: - type: - type: string - description: The type of the summary part. Always `summary_text`. - enum: - - summary_text - x-stainless-const: true - text: - type: string - description: The text of the summary part. - required: - - type - - text + type: object required: - type - - item_id - - output_index - - summary_index - - part - - sequence_number - x-oaiMeta: - name: response.reasoning_summary_part.done - group: responses - example: | - { - "type": "response.reasoning_summary_part.done", - "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", - "output_index": 0, - "summary_index": 0, - "part": { - "type": "summary_text", - "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!" - }, - "sequence_number": 1 - } - BetaResponseReasoningSummaryPartAddedEvent: - type: object - description: Emitted when a new reasoning summary part is added. + BetaContainerMemoryLimit: + type: string + enum: + - 1g + - 4g + - 16g + - 64g + BetaLocalShellToolParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.reasoning_summary_part.added`. enum: - - response.reasoning_summary_part.added + - local_shell + description: The type of the local shell tool. Always `local_shell`. + default: local_shell x-stainless-const: true - item_id: - type: string - description: | - The ID of the item this summary part is associated with. - output_index: - type: integer - description: | - The index of the output item this summary part is associated with. - summary_index: - type: integer - description: | - The index of the summary part within the reasoning summary. - sequence_number: - type: integer - description: | - The sequence number of this event. - part: - type: object - description: | - The summary part that was added. - properties: - type: - type: string - description: The type of the summary part. Always `summary_text`. - enum: - - summary_text - x-stainless-const: true - text: - type: string - description: The text of the summary part. - required: - - type - - text + type: object required: - type - - item_id - - output_index - - summary_index - - part - - sequence_number - x-oaiMeta: - name: response.reasoning_summary_part.added - group: responses - example: | - { - "type": "response.reasoning_summary_part.added", - "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", - "output_index": 0, - "summary_index": 0, - "part": { - "type": "summary_text", - "text": "" - }, - "sequence_number": 1 - } - BetaResponseTextDoneEvent: + title: Local shell tool + description: A tool that allows the model to execute shell commands in a local environment. + BetaImageGenTool: type: object - description: Emitted when text content is finalized. + title: Image generation tool + description: | + A tool that generates images using the GPT image models. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.output_text.done`. enum: - - response.output_text.done + - image_generation + description: | + The type of the image generation tool. Always `image_generation`. x-stainless-const: true - item_id: + model: + anyOf: + - type: string + - type: string + enum: + - gpt-image-1 + - gpt-image-1-mini + - gpt-image-2 + - gpt-image-2-2026-04-21 + - gpt-image-2.5-sunburst + - gpt-image-2.5-sunburst-2026-09-08 + - gpt-image-2.5-flare + - gpt-image-2.5-flare-2026-09-08 + - gpt-image-1.5 + - chatgpt-image-latest + description: | + The image generation model to use. One of `gpt-image-1`, + `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, + `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, + `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, + `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`. Default: + `gpt-image-1`. + default: gpt-image-1 + quality: type: string + enum: + - low + - medium + - high + - xhigh + - max + - auto description: | - The ID of the output item that the text content is finalized. - output_index: - type: integer - description: | - The index of the output item that the text content is finalized. - content_index: - type: integer - description: | - The index of the content part that the text content is finalized. - text: + The quality of the generated image. The GPT image models support `low`, + `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, + including their `2026-09-08` snapshots, also support `xhigh` and `max`. + Default: `auto`. + default: auto + size: + anyOf: + - type: string + - type: string + enum: + - 1024x1024 + - 1024x1536 + - 1536x1024 + - auto + description: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + default: auto + output_format: type: string + enum: + - png + - webp + - jpeg description: | - The text content that is finalized. - sequence_number: + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. + default: png + output_compression: type: integer - description: The sequence number for this event. - logprobs: - type: array + minimum: 0 + maximum: 100 description: | - The log probabilities of the tokens in the delta. - items: - $ref: '#/components/schemas/BetaResponseLogProb' - required: - - type - - item_id - - output_index - - content_index - - text - - sequence_number - - logprobs - x-oaiMeta: - name: response.output_text.done - group: responses - example: | - { - "type": "response.output_text.done", - "item_id": "msg_123", - "output_index": 0, - "content_index": 0, - "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", - "sequence_number": 1 - } - BetaResponseLogProb: - type: object - description: "A logprob is the logarithmic probability that the model assigns to producing \na particular token at a given position in the sequence. Less-negative (higher) \nlogprob values indicate greater model confidence in that token choice.\n" - properties: - token: - description: A possible text token. + Compression level for the output image. Default: 100. + default: 100 + moderation: type: string - logprob: - description: | - The log probability of this token. - type: number - top_logprobs: + enum: + - auto + - low description: | - The log probabilities of up to 20 of the most likely tokens. - type: array - items: - type: object - properties: - token: - description: A possible text token. - type: string - logprob: - description: The log probability of this token. - type: number - required: - - token - - logprob - BetaResponseTextDeltaEvent: - type: object - description: Emitted when there is an additional text delta. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. - type: + Moderation level for the generated image. Default: `auto`. + default: auto + background: type: string - description: | - The type of the event. Always `response.output_text.delta`. enum: - - response.output_text.delta - x-stainless-const: true - item_id: - type: string + - transparent + - opaque + - auto description: | - The ID of the output item that the text delta was added to. - output_index: - type: integer + Allows to set transparency for the background of the generated image(s). Must + be one of `transparent`, `opaque`, or `auto` (default value). When `auto` is + used, the model will automatically determine the best background for the + image. + + `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their + `2026-09-08` snapshots, support `opaque` and `transparent` backgrounds. + Transparent backgrounds are available for supported GPT Image models. For + `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When + using `transparent`, set the output format to `png` or `webp`. + default: auto + input_fidelity: + anyOf: + - $ref: '#/components/schemas/BetaInputFidelity' + - type: 'null' + description: Controls fidelity to the original input image(s). This parameter is supported for GPT image models that support input fidelity. `gpt-image-2` and `gpt-image-2-2026-04-21` ignore this parameter. + input_image_mask: + type: object description: | - The index of the output item that the text delta was added to. - content_index: + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). + properties: + image_url: + type: string + description: | + Base64-encoded mask image. + file_id: + type: string + description: | + File ID for the mask image. + required: [] + additionalProperties: false + partial_images: type: integer + minimum: 0 + maximum: 3 description: | - The index of the content part that the text delta was added to. - delta: - type: string - description: | - The text delta that was added. - sequence_number: - type: integer - description: The sequence number for this event. - logprobs: - type: array + Number of partial images to generate in streaming mode, from 0 (default value) to 3. + default: 0 + action: description: | - The log probabilities of the tokens in the delta. - items: - $ref: '#/components/schemas/BetaResponseLogProb' + Whether to generate a new image or edit an existing image. Default: `auto`. + $ref: '#/components/schemas/BetaImageGenActionEnum' required: - type - - item_id - - output_index - - content_index - - delta - - sequence_number - - logprobs - x-oaiMeta: - name: response.output_text.delta - group: responses - example: | - { - "type": "response.output_text.delta", - "item_id": "msg_123", - "output_index": 0, - "content_index": 0, - "delta": "In", - "sequence_number": 1 - } - BetaResponseRefusalDoneEvent: - type: object - description: Emitted when refusal text is finalized. + BetaImageGenActionEnum: + type: string + enum: + - generate + - edit + - auto + BetaInputFidelity: + type: string + enum: + - high + - low + description: 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`. + BetaProgrammaticToolCallingParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.refusal.done`. enum: - - response.refusal.done + - programmatic_tool_calling + description: The type of the tool. Always `programmatic_tool_calling`. + default: programmatic_tool_calling x-stainless-const: true - item_id: - type: string - description: | - The ID of the output item that the refusal text is finalized. - output_index: - type: integer - description: | - The index of the output item that the refusal text is finalized. - content_index: - type: integer - description: | - The index of the content part that the refusal text is finalized. - refusal: - type: string - description: | - The refusal text that is finalized. - sequence_number: - type: integer - description: | - The sequence number of this event. + type: object required: - type - - item_id - - output_index - - content_index - - refusal - - sequence_number - x-oaiMeta: - name: response.refusal.done - group: responses - example: | - { - "type": "response.refusal.done", - "item_id": "item-abc", - "output_index": 1, - "content_index": 2, - "refusal": "final refusal text", - "sequence_number": 1 - } - BetaResponseRefusalDeltaEvent: + BetaCodeInterpreterTool: type: object - description: Emitted when there is a partial refusal text. + title: Code interpreter + description: | + A tool that runs Python code to help generate a response to a prompt. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.refusal.delta`. enum: - - response.refusal.delta - x-stainless-const: true - item_id: - type: string - description: | - The ID of the output item that the refusal text is added to. - output_index: - type: integer - description: | - The index of the output item that the refusal text is added to. - content_index: - type: integer - description: | - The index of the content part that the refusal text is added to. - delta: - type: string + - code_interpreter description: | - The refusal text that is added. - sequence_number: - type: integer + The type of the code interpreter tool. Always `code_interpreter`. + x-stainless-const: true + container: description: | - The sequence number of this event. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + anyOf: + - type: string + description: The container ID. + - $ref: '#/components/schemas/BetaAutoCodeInterpreterToolParam' + allowed_callers: + anyOf: + - type: array + minItems: 1 + items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + description: The tool invocation context(s). + - type: 'null' required: - type - - item_id - - output_index - - content_index - - delta - - sequence_number - x-oaiMeta: - name: response.refusal.delta - group: responses - example: | - { - "type": "response.refusal.delta", - "item_id": "msg_123", - "output_index": 0, - "content_index": 0, - "delta": "refusal text so far", - "sequence_number": 1 - } - BetaResponseOutputItemDoneEvent: - type: object - description: Emitted when an output item is marked done. + - container + BetaAutoCodeInterpreterToolParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.output_item.done`. enum: - - response.output_item.done + - auto + description: Always `auto`. + default: auto x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that was marked done. - sequence_number: - type: integer - description: | - The sequence number of this event. - item: - $ref: '#/components/schemas/BetaOutputItem' - description: | - The output item that was marked done. + file_ids: + items: + type: string + example: file-123 + type: array + maxItems: 50 + description: An optional list of uploaded files to make available to your code. + memory_limit: + anyOf: + - $ref: '#/components/schemas/BetaContainerMemoryLimit' + description: The memory limit for the code interpreter container. + - type: 'null' + network_policy: + discriminator: + propertyName: type + description: Network access policy for the container. + anyOf: + - $ref: '#/components/schemas/BetaContainerNetworkPolicyDisabledParam' + - $ref: '#/components/schemas/BetaContainerNetworkPolicyAllowlistParam' + type: object required: - type - - output_index - - item - - sequence_number - x-oaiMeta: - name: response.output_item.done - group: responses - example: | - { - "type": "response.output_item.done", - "output_index": 0, - "item": { - "id": "msg_123", - "status": "completed", - "type": "message", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", - "annotations": [] - } - ] - }, - "sequence_number": 1 - } - BetaResponseOutputItemAddedEvent: + title: CodeInterpreterToolAuto + description: Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + BetaMCPTool: type: object - description: Emitted when a new output item is added. + title: MCP tool + description: | + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp). properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.output_item.added`. enum: - - response.output_item.added + - mcp + description: The type of the MCP tool. Always `mcp`. x-stainless-const: true - output_index: - type: integer + server_label: + type: string description: | - The index of the output item that was added. - sequence_number: - type: integer + A label for this MCP server, used to identify it in tool calls. + server_url: + type: string + format: uri description: | - The sequence number of this event. - item: - $ref: '#/components/schemas/BetaOutputItem' + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + connector_id: + type: string + deprecated: true + enum: + - connector_dropbox + - connector_gmail + - connector_googlecalendar + - connector_googledrive + - connector_microsoftteams + - connector_outlookcalendar + - connector_outlookemail + - connector_sharepoint description: | - The output item that was added. For reasoning items, `encrypted_content` - may be incomplete while the item is in progress. Use the reasoning item - from the corresponding `response.output_item.done` event when passing it - as input to a subsequent request. - required: - - type - - output_index - - item - - sequence_number - x-oaiMeta: - name: response.output_item.added - group: responses - example: | - { - "type": "response.output_item.added", - "output_index": 0, - "item": { - "id": "msg_123", - "status": "in_progress", - "type": "message", - "role": "assistant", - "content": [] - }, - "sequence_number": 1 - } - BetaResponseInProgressEvent: - type: object - description: Emitted when the response is in progress. - properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. - type: + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors). + + This field is deprecated for models released after September 1, 2026. + Use `server_url` to connect to a remote MCP server, or `tunnel_id` to + connect through a Secure MCP Tunnel. + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + tunnel_id: type: string + pattern: ^tunnel_[a-z0-9]{32}$ description: | - The type of the event. Always `response.in_progress`. - enum: - - response.in_progress - x-stainless-const: true - response: - $ref: '#/components/schemas/BetaResponse' + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + authorization: + type: string description: | - The response that is in progress. - sequence_number: - type: integer - description: The sequence number of this event. - required: - - type - - response - - sequence_number - x-oaiMeta: - name: response.in_progress - group: responses - example: | - { - "type": "response.in_progress", - "response": { - "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", - "object": "response", - "created_at": 1741487325, - "status": "in_progress", - "completed_at": null, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} - }, - "sequence_number": 1 - } - BetaResponseShellCallOutputContentDoneStreamingEvent: + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + server_description: + type: string + description: | + Optional description of the MCP server, used to provide more context. + headers: + anyOf: + - type: object + additionalProperties: + type: string + description: | + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + - type: 'null' + allowed_tools: + anyOf: + - description: | + List of allowed tool names or a filter object. + anyOf: + - type: array + title: MCP allowed tools + description: A string array of allowed tool names + items: + type: string + - $ref: '#/components/schemas/BetaMCPToolFilter' + - type: 'null' + allowed_callers: + anyOf: + - type: array + minItems: 1 + items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + description: The tool invocation context(s). + - type: 'null' + require_approval: + anyOf: + - description: Specify which of the MCP server's tools require approval. + default: always + anyOf: + - type: object + title: MCP tool approval filter + description: | + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + properties: + always: + $ref: '#/components/schemas/BetaMCPToolFilter' + never: + $ref: '#/components/schemas/BetaMCPToolFilter' + additionalProperties: false + - type: string + title: MCP tool approval setting + description: | + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + enum: + - always + - never + - type: 'null' + defer_loading: + type: boolean + description: | + Whether this MCP tool is deferred and discovered via tool search. + required: + - type + - server_label + BetaMCPToolFilter: + type: object + title: MCP tool filter + description: | + A filter object to specify which tools are allowed. properties: - type: - type: string - enum: - - response.shell_call_output_content.done - description: The type of the event, always `response.shell_call_output_content.done`. - default: response.shell_call_output_content.done - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - item_id: - type: string - description: The ID of the output item that was updated. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: - type: integer - description: The index of the shell command that produced output. - output: - items: - $ref: '#/components/schemas/BetaFunctionShellCallOutputContent' + tool_names: type: array - description: The output contents emitted for the shell command. + title: MCP allowed tools + items: + type: string + description: List of allowed tool names. + read_only: + type: boolean + description: | + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + required: [] + additionalProperties: false + BetaWebSearchTool: type: object - required: - - type - - sequence_number - - item_id - - output_index - - command_index - - output - title: Response shell call output content done event - description: A streaming event that indicated shell call output was completed. - BetaResponseShellCallOutputContentDeltaStreamingEvent: + title: Web search + description: | + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search). properties: type: type: string enum: - - response.shell_call_output_content.delta - description: The type of the event, always `response.shell_call_output_content.delta`. - default: response.shell_call_output_content.delta - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - item_id: + - web_search + - web_search_2025_08_26 + description: The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + default: web_search + external_web_access: + type: boolean + default: true + description: Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content. + filters: + anyOf: + - type: object + description: | + Filters for the search. + properties: + allowed_domains: + anyOf: + - type: array + title: Allowed domains for the search. + description: | + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + items: + type: string + description: Allowed domain for the search. + default: [] + - type: 'null' + - type: 'null' + user_location: + $ref: '#/components/schemas/BetaWebSearchApproximateLocation' + search_context_size: type: string - description: The ID of the output item that was updated. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: - type: integer - description: The index of the shell command that produced output. - delta: - $ref: '#/components/schemas/BetaShellCallOutputDelta' - description: The stdout/stderr delta that was emitted. - type: object + enum: + - low + - medium + - high + default: medium + description: 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. required: - type - - sequence_number - - item_id - - output_index - - command_index - - delta - title: Response shell call output content delta event - description: A streaming event that indicated shell call output was incrementally added. - BetaShellCallOutputDelta: - properties: - stdout: - type: string - description: The stdout delta that was emitted. - stderr: - type: string - description: The stderr delta that was emitted. - type: object - required: [] - title: Shell call output delta - description: A delta of stdout/stderr emitted while a shell call was running. - BetaResponseShellCallCommandDoneStreamingEvent: + BetaWebSearchApproximateLocation: + anyOf: + - type: object + title: Web search approximate location + description: | + The approximate location of the user. + properties: + type: + type: string + enum: + - approximate + description: The type of location approximation. Always `approximate`. + default: approximate + x-stainless-const: true + country: + anyOf: + - type: string + description: The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - type: 'null' + region: + anyOf: + - type: string + description: Free text input for the region of the user, e.g. `California`. + - type: 'null' + city: + anyOf: + - type: string + description: Free text input for the city of the user, e.g. `San Francisco`. + - type: 'null' + timezone: + anyOf: + - type: string + description: The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - type: 'null' + - type: 'null' + BetaComputerUsePreviewTool: properties: type: type: string enum: - - response.shell_call_command.done - description: The type of the event, always `response.shell_call_command.done`. - default: response.shell_call_command.done + - computer_use_preview + description: The type of the computer use tool. Always `computer_use_preview`. + default: computer_use_preview x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - output_index: + environment: + $ref: '#/components/schemas/BetaComputerEnvironment' + description: The type of computer environment to control. + display_width: type: integer - description: The index of the output item that was updated. - command_index: + description: The width of the computer display. + display_height: type: integer - description: The index of the shell command that was completed. - command: - type: string - description: The final shell command that was emitted. + description: The height of the computer display. type: object required: - type - - sequence_number - - output_index - - command_index - - command - title: Response shell command done event - description: A streaming event that indicated a shell command was completed. - BetaResponseShellCallCommandDeltaStreamingEvent: + - environment + - display_width + - display_height + title: Computer use preview + description: A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use). + BetaComputerEnvironment: + type: string + enum: + - windows + - mac + - linux + - ubuntu + - browser + BetaComputerTool: properties: type: type: string enum: - - response.shell_call_command.delta - description: The type of the event, always `response.shell_call_command.delta`. - default: response.shell_call_command.delta + - computer + description: The type of the computer tool. Always `computer`. + default: computer x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: - type: integer - description: The index of the shell command that was updated. - delta: - type: string - description: The shell command delta that was appended. - obfuscation: - type: string - description: An obfuscation string that was added to pad the event payload. type: object required: - type - - sequence_number - - output_index - - command_index - - delta - title: Response shell command delta event - description: A streaming event that indicated a shell command was incrementally updated. - BetaResponseShellCallCommandAddedStreamingEvent: + title: Computer + description: A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use). + BetaFileSearchTool: properties: type: type: string enum: - - response.shell_call_command.added - description: The type of the event, always `response.shell_call_command.added`. - default: response.shell_call_command.added + - file_search + description: The type of the file search tool. Always `file_search`. + default: file_search x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - output_index: - type: integer - description: The index of the output item that was updated. - command_index: + vector_store_ids: + items: + type: string + type: array + description: The IDs of the vector stores to search. + max_num_results: type: integer - description: The index of the shell command that was added. - command: - type: string - description: The shell command that was added. + description: The maximum number of results to return. This number should be between 1 and 50 inclusive. + ranking_options: + $ref: '#/components/schemas/BetaRankingOptions' + description: Ranking options for search. + filters: + anyOf: + - $ref: '#/components/schemas/BetaFilters' + description: A filter to apply. + - type: 'null' type: object required: - type - - sequence_number - - output_index - - command_index - - command - title: Response shell command added event - description: A streaming event that indicated a shell command was added to a tool call. - BetaResponseFunctionCallArgumentsDoneEvent: + - vector_store_ids + title: File search + description: A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://developers.openai.com/api/docs/guides/tools-file-search). + BetaFilters: + anyOf: + - $ref: '#/components/schemas/BetaComparisonFilter' + - $ref: '#/components/schemas/BetaCompoundFilter' + BetaCompoundFilter: + $recursiveAnchor: true type: object - description: Emitted when function-call arguments are finalized. + additionalProperties: false + title: Compound Filter + description: Combine multiple filters using `and` or `or`. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string + description: 'Type of operation: `and` or `or`.' enum: - - response.function_call_arguments.done - x-stainless-const: true - item_id: - type: string - description: The ID of the item. - output_index: - type: integer - description: The index of the output item. - sequence_number: - type: integer - description: The sequence number of this event. - arguments: - type: string - description: The function-call arguments. + - and + - or + filters: + type: array + description: Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + items: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaComparisonFilter' + - $recursiveRef: '#' required: - type - - item_id - - output_index - - arguments - - sequence_number + - filters x-oaiMeta: - name: response.function_call_arguments.done - group: responses - example: | - { - "type": "response.function_call_arguments.done", - "item_id": "item-abc", - "output_index": 1, - "arguments": "{ \"arg\": 123 }", - "sequence_number": 1 - } - BetaResponseFunctionCallArgumentsDeltaEvent: + name: CompoundFilter + BetaComparisonFilter: type: object - description: Emitted when there is a partial function-call arguments delta. + additionalProperties: false + title: Comparison Filter + description: | + A filter used to compare a specified attribute key to a given value using a defined comparison operation. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.function_call_arguments.delta`. + default: eq enum: - - response.function_call_arguments.delta - x-stainless-const: true - item_id: - type: string - description: | - The ID of the output item that the function-call arguments delta is added to. - output_index: - type: integer + - eq + - ne + - gt + - gte + - lt + - lte + - in + - nin description: | - The index of the output item that the function-call arguments delta is added to. - sequence_number: - type: integer - description: The sequence number of this event. - delta: + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in + key: type: string - description: | - The function-call arguments delta that is added. + description: The key to compare against the value. + value: + description: The value to compare against the attribute key; supports string, number, or boolean types. + anyOf: + - type: string + - type: number + - type: boolean + - type: array + items: + $ref: '#/components/schemas/ComparisonFilterValueItems' required: - type - - item_id - - output_index - - delta - - sequence_number + - key + - value x-oaiMeta: - name: response.function_call_arguments.delta - group: responses - example: | - { - "type": "response.function_call_arguments.delta", - "item_id": "item-abc", - "output_index": 0, - "delta": "{ \"arg\":" - "sequence_number": 1 - } - BetaResponseFileSearchCallSearchingEvent: + name: ComparisonFilter + BetaRankingOptions: + properties: + ranker: + $ref: '#/components/schemas/BetaRankerVersionType' + description: The ranker to use for the file search. + score_threshold: + type: number + description: The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + hybrid_search: + $ref: '#/components/schemas/BetaHybridSearchOptions' + description: Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. type: object - description: Emitted when a file search is currently searching. + required: [] + BetaHybridSearchOptions: properties: - agent: + embedding_weight: + type: number + description: The weight of the embedding in the reciprocal ranking fusion. + text_weight: + type: number + description: The weight of the text in the reciprocal ranking fusion. + type: object + required: + - embedding_weight + - text_weight + BetaRankerVersionType: + type: string + enum: + - auto + - default-2024-11-15 + BetaFunctionTool: + properties: + type: + type: string + enum: + - function + description: The type of the function tool. Always `function`. + default: function + x-stainless-const: true + name: + type: string + description: The name of the function to call. + async: + type: boolean + description: + anyOf: + - type: string + description: A description of the function. Used by the model to determine whether or not to call the function. + - type: 'null' + parameters: + anyOf: + - additionalProperties: {} + type: object + description: A JSON schema object describing the parameters of the function. + x-oaiTypeLabel: map + - type: 'null' + output_schema: + anyOf: + - additionalProperties: {} + type: object + description: A JSON schema object describing the JSON value encoded in string outputs for this function. + x-oaiTypeLabel: map + - type: 'null' + strict: + anyOf: + - type: boolean + description: Whether strict parameter validation is enforced for this function tool. + - type: 'null' + defer_loading: + type: boolean + description: Whether this function is deferred and loaded via tool search. + allowed_callers: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - items: + $ref: '#/components/schemas/BetaCallableToolAllowedCaller' + type: array + description: The tool invocation context(s). - type: 'null' - description: The agent that owns this multi-agent streaming event. - type: - type: string - description: | - The type of the event. Always `response.file_search_call.searching`. - enum: - - response.file_search_call.searching - x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the file search call is searching. - item_id: - type: string - description: | - The ID of the output item that the file search call is initiated. - sequence_number: - type: integer - description: The sequence number of this event. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.file_search_call.searching - group: responses - example: | - { - "type": "response.file_search_call.searching", - "output_index": 0, - "item_id": "fs_123", - "sequence_number": 1 - } - BetaResponseFileSearchCallInProgressEvent: - type: object - description: Emitted when a file search call is initiated. + - name + - strict + - parameters + title: Function + description: Defines a function in your own code the model can choose to call. Learn more about [function calling](https://developers.openai.com/api/docs/guides/function-calling). + BetaInputItem: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaEasyInputMessage' + - type: object + title: Item + description: | + An item representing part of the context for the response to be + generated by the model. Can contain text, images, and audio inputs, + as well as previous assistant responses and tool call outputs. + $ref: '#/components/schemas/BetaItem' + - $ref: '#/components/schemas/BetaCompactionTriggerItemParam' + - $ref: '#/components/schemas/BetaItemReferenceParam' + - $ref: '#/components/schemas/BetaProgramItemParam' + - $ref: '#/components/schemas/BetaProgramOutputItemParam' + BetaProgramOutputItemParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. + id: + type: string + description: The unique ID of this program output item. + example: cmo_123 type: type: string - description: | - The type of the event. Always `response.file_search_call.in_progress`. enum: - - response.file_search_call.in_progress + - program_output + description: The item type. Always `program_output`. + default: program_output x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the file search call is initiated. - item_id: + call_id: type: string - description: | - The ID of the output item that the file search call is initiated. - sequence_number: - type: integer - description: The sequence number of this event. + maxLength: 64 + minLength: 1 + description: The call ID of the program item. + result: + type: string + maxLength: 10485760 + description: The result produced by the program item. + status: + $ref: '#/components/schemas/BetaProgramOutputItemStatus' + description: The terminal status of the program output. + type: object required: + - id - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.file_search_call.in_progress - group: responses - example: | - { - "type": "response.file_search_call.in_progress", - "output_index": 0, - "item_id": "fs_123", - "sequence_number": 1 - } - BetaResponseFileSearchCallCompletedEvent: + - call_id + - result + - status + BetaProgramOutputItemStatus: + type: string + enum: + - completed + - incomplete + Beta_AgentTagParam: + properties: + agent_name: + type: string + description: The canonical name of the agent that produced this item. type: object - description: Emitted when a file search call is completed (results found). + required: + - agent_name + description: The agent that produced this item. + x-oai-beta: responses_multi_agent=v1 + BetaProgramItemParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. + id: + type: string + description: The unique ID of this program item. + example: cm_123 type: type: string - description: | - The type of the event. Always `response.file_search_call.completed`. enum: - - response.file_search_call.completed + - program + description: The item type. Always `program`. + default: program x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the file search call is initiated. - item_id: + call_id: type: string - description: | - The ID of the output item that the file search call is initiated. - sequence_number: - type: integer - description: The sequence number of this event. + maxLength: 64 + minLength: 1 + description: The stable call ID of the program item. + code: + type: string + maxLength: 10485760 + description: The JavaScript source executed by programmatic tool calling. + fingerprint: + type: string + maxLength: 10485760 + description: Opaque program replay fingerprint that must be round-tripped. + type: object required: + - id - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.file_search_call.completed - group: responses - example: | - { - "type": "response.file_search_call.completed", - "output_index": 0, - "item_id": "fs_123", - "sequence_number": 1 - } - BetaResponseErrorEvent: - type: object - description: Emitted when an error occurs. + - call_id + - code + - fingerprint + BetaItemReferenceParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. type: - type: string - description: | - The type of the event. Always `error`. - enum: - - error - x-stainless-const: true - code: anyOf: - type: string - description: | - The error code. + enum: + - item_reference + description: The type of item to reference. Always `item_reference`. + default: item_reference + x-stainless-const: true - type: 'null' - message: + id: type: string - description: | - The error message. - param: - anyOf: - - type: string - description: | - The error parameter. - - type: 'null' - sequence_number: - type: integer - description: The sequence number of this event. - required: - - type - - code - - message - - param - - sequence_number - x-oaiMeta: - name: error - group: responses - example: | - { - "type": "error", - "code": "ERR_SOMETHING", - "message": "Something went wrong", - "param": null, - "sequence_number": 1 - } - BetaResponseCreatedEvent: + description: The ID of the item to reference. type: object - description: | - An event that is emitted when a response is created. + required: + - id + title: Item reference + description: An internal identifier for an item to reference. + BetaCompactionTriggerItemParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.created`. enum: - - response.created + - compaction_trigger + description: The type of the item. Always `compaction_trigger`. + default: compaction_trigger x-stainless-const: true - response: - $ref: '#/components/schemas/BetaResponse' - description: | - The response that was created. - sequence_number: - type: integer - description: The sequence number for this event. + type: object required: - type - - response - - sequence_number - x-oaiMeta: - name: response.created - group: responses - example: | - { - "type": "response.created", - "response": { - "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", - "object": "response", - "created_at": 1741487325, - "status": "in_progress", - "completed_at": null, - "error": null, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [], - "parallel_tool_calls": true, - "previous_response_id": null, - "reasoning": { - "effort": null, - "summary": null - }, - "store": true, - "temperature": 1, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} - }, - "sequence_number": 1 - } - BetaResponseContentPartDoneEvent: + title: Compaction trigger + description: Compacts the current context. Must be the final input item. + BetaItem: type: object - description: Emitted when a content part is done. + description: | + Content item used to generate a response. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaInputMessage' + - $ref: '#/components/schemas/BetaOutputMessage' + - $ref: '#/components/schemas/BetaFileSearchToolCall' + - $ref: '#/components/schemas/BetaComputerToolCall' + - $ref: '#/components/schemas/BetaComputerCallOutputItemParam' + - $ref: '#/components/schemas/BetaWebSearchToolCall' + - $ref: '#/components/schemas/BetaFunctionToolCall' + - $ref: '#/components/schemas/BetaFunctionCallOutputItemParam' + - $ref: '#/components/schemas/BetaAgentMessageItemParam' + - $ref: '#/components/schemas/BetaMultiAgentCallItemParam' + - $ref: '#/components/schemas/BetaMultiAgentCallOutputItemParam' + - $ref: '#/components/schemas/BetaToolSearchCallItemParam' + - $ref: '#/components/schemas/BetaToolSearchOutputItemParam' + - $ref: '#/components/schemas/BetaAdditionalToolsItemParam' + - $ref: '#/components/schemas/BetaResponseConfigurationUpdateItemParam' + - $ref: '#/components/schemas/BetaReasoningItem' + - $ref: '#/components/schemas/BetaCompactionSummaryItemParam' + - $ref: '#/components/schemas/BetaImageGenToolCall' + - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' + - $ref: '#/components/schemas/BetaFunctionShellCallItemParam' + - $ref: '#/components/schemas/BetaFunctionShellCallOutputItemParam' + - $ref: '#/components/schemas/BetaApplyPatchToolCallItemParam' + - $ref: '#/components/schemas/BetaApplyPatchToolCallOutputItemParam' + - $ref: '#/components/schemas/BetaMCPListTools' + - $ref: '#/components/schemas/BetaMCPApprovalRequest' + - $ref: '#/components/schemas/BetaMCPApprovalResponse' + - $ref: '#/components/schemas/BetaMCPToolCall' + - $ref: '#/components/schemas/BetaCustomToolCallOutput' + - $ref: '#/components/schemas/BetaCustomToolCall' + BetaCustomToolCall: + type: object + title: Custom tool call + description: | + A call to a custom tool created by the model. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: | - The type of the event. Always `response.content_part.done`. enum: - - response.content_part.done + - custom_tool_call x-stainless-const: true - item_id: + description: | + The type of the custom tool call. Always `custom_tool_call`. + id: type: string description: | - The ID of the output item that the content part was added to. - output_index: - type: integer + The unique ID of the custom tool call in the OpenAI platform. + call_id: + type: string description: | - The index of the output item that the content part was added to. - content_index: - type: integer + An identifier used to map this custom tool call to a tool call output. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + - type: 'null' + namespace: + type: string description: | - The index of the content part that is done. - sequence_number: - type: integer - description: The sequence number of this event. - part: - $ref: '#/components/schemas/BetaOutputContent' + The namespace of the custom tool being called. + name: + type: string description: | - The content part that is done. + The name of the custom tool being called. + input: + type: string + description: | + The input for the custom tool call generated by the model. + async: + type: boolean + description: | + Whether the custom tool call runs asynchronously. required: - type - - item_id - - output_index - - content_index - - part - - sequence_number - x-oaiMeta: - name: response.content_part.done - group: responses - example: | - { - "type": "response.content_part.done", - "item_id": "msg_123", - "output_index": 0, - "content_index": 0, - "sequence_number": 1, - "part": { - "type": "output_text", - "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", - "annotations": [] - } - } - BetaOutputContent: + - call_id + - name + - input + BetaToolCallCaller: discriminator: propertyName: type + description: The execution context that produced this tool call. anyOf: - - $ref: '#/components/schemas/BetaOutputTextContent' - - $ref: '#/components/schemas/BetaRefusalContent' - - $ref: '#/components/schemas/BetaReasoningTextContent' - BetaResponseContentPartAddedEvent: - type: object - description: Emitted when a new content part is added. + - $ref: '#/components/schemas/BetaDirectToolCallCaller' + - $ref: '#/components/schemas/BetaProgramToolCallCaller' + BetaProgramToolCallCaller: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.content_part.added`. enum: - - response.content_part.added + - program + default: program x-stainless-const: true - item_id: + caller_id: type: string - description: | - The ID of the output item that the content part was added to. - output_index: - type: integer - description: | - The index of the output item that the content part was added to. - content_index: - type: integer - description: | - The index of the content part that was added. - part: - $ref: '#/components/schemas/BetaOutputContent' - description: | - The content part that was added. - sequence_number: - type: integer - description: The sequence number of this event. + description: The call ID of the program item that produced this tool call. + type: object required: - type - - item_id - - output_index - - content_index - - part - - sequence_number - x-oaiMeta: - name: response.content_part.added - group: responses - example: | - { - "type": "response.content_part.added", - "item_id": "msg_123", - "output_index": 0, - "content_index": 0, - "part": { - "type": "output_text", - "text": "", - "annotations": [] - }, - "sequence_number": 1 - } - BetaResponseCompletedEvent: + - caller_id + BetaDirectToolCallCaller: + properties: + type: + type: string + enum: + - direct + default: direct + x-stainless-const: true + type: object + required: + - type + BetaAgentTag: + properties: + agent_name: + type: string + description: The canonical name of the agent that produced this item. type: object - description: Emitted when the model response is complete. + required: + - agent_name + x-oai-beta: responses_multi_agent=v1 + BetaCustomToolCallOutput: + type: object + title: Custom tool call output + description: | + The output of a custom tool call from your code, being sent back to the model. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: | - The type of the event. Always `response.completed`. enum: - - response.completed + - custom_tool_call_output x-stainless-const: true - response: - $ref: '#/components/schemas/BetaResponse' description: | - Properties of the completed response. - sequence_number: - type: integer - description: The sequence number for this event. + The type of the custom tool call output. Always `custom_tool_call_output`. + id: + type: string + description: | + The unique ID of the custom tool call output in the OpenAI platform. + call_id: + type: string + description: | + The call ID, used to map this custom tool call output to a custom tool call. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + - type: 'null' + output: + description: | + The output from the custom tool call generated by your code. + Can be a string or an list of output content. + anyOf: + - type: string + description: | + A string of the output of the custom tool call. + title: string output + - type: array + items: + $ref: '#/components/schemas/BetaFunctionAndCustomToolCallOutput' + title: output content list + description: | + Text, image, or file output of the custom tool call. required: - type - - response - - sequence_number - x-oaiMeta: - name: response.completed - group: responses - example: | - { - "type": "response.completed", - "response": { - "id": "resp_123", - "object": "response", - "created_at": 1740855869, - "status": "completed", - "completed_at": 1740855870, - "error": null, - "incomplete_details": null, - "input": [], - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [ - { - "id": "msg_123", - "type": "message", - "role": "assistant", - "content": [ - { - "type": "output_text", - "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", - "annotations": [] - } - ] - } - ], - "previous_response_id": null, - "reasoning_effort": null, - "store": false, - "temperature": 1, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1, - "truncation": "disabled", - "usage": { - "input_tokens": 0, - "output_tokens": 0, - "output_tokens_details": { - "reasoning_tokens": 0 - }, - "total_tokens": 0 - }, - "user": null, - "metadata": {} - }, - "sequence_number": 1 - } - BetaResponseCompactionCompactingStreamingEvent: + - call_id + - output + BetaFunctionAndCustomToolCallOutput: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaInputTextContent' + - $ref: '#/components/schemas/BetaInputImageContent' + - $ref: '#/components/schemas/BetaInputFileContent' + BetaInputFileContent: properties: type: type: string enum: - - response.compaction.compacting - description: The type of the event, always `response.compaction.compacting`. - default: response.compaction.compacting + - input_file + description: The type of the input item. Always `input_file`. + default: input_file x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of the event that was emitted. - agent: - $ref: '#/components/schemas/BetaAgentTag' - description: The agent that owns this multi-agent streaming event. - output_index: - type: integer - description: The index of the compaction output item. - item_id: + file_id: + anyOf: + - type: string + description: The ID of the file to be sent to the model. + - type: 'null' + filename: type: string - description: The ID of the compaction output item. + description: The name of the file to be sent to the model. + file_data: + type: string + description: | + The content of the file to be sent to the model. + prompt_cache_breakpoint: + $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' + file_url: + type: string + format: uri + description: The URL of the file to be sent to the model. + detail: + $ref: '#/components/schemas/BetaFileInputDetail' + description: The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. type: object required: - type - - sequence_number - - output_index - - item_id - title: Response compaction compacting event - description: Emitted when new summary content is sampled for a compaction trigger. Contains no summary content. - BetaResponseCodeInterpreterCallInterpretingEvent: + title: Input file + description: A file input to the model. + BetaFileInputDetail: + type: string + enum: + - auto + - low + - high + BetaPromptCacheBreakpointConfig: + properties: + mode: + type: string + enum: + - explicit + description: The breakpoint mode. Always `explicit`. + default: explicit + x-stainless-const: true type: object - description: Emitted when the code interpreter is actively interpreting the code snippet. + required: + - mode + title: Prompt cache breakpoint + description: Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + BetaInputImageContent: properties: - agent: + type: + type: string + enum: + - input_image + description: The type of the input item. Always `input_image`. + default: input_image + x-stainless-const: true + image_url: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - type: string + format: uri + description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - type: 'null' - description: The agent that owns this multi-agent streaming event. + file_id: + anyOf: + - type: string + description: The ID of the file to be sent to the model. + - type: 'null' + detail: + $ref: '#/components/schemas/BetaImageDetail' + description: The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + prompt_cache_breakpoint: + $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' + type: object + required: + - type + - detail + title: Input image + description: An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision). + BetaImageDetail: + type: string + enum: + - low + - high + - auto + - original + BetaInputTextContent: + properties: type: type: string - description: The type of the event. Always `response.code_interpreter_call.interpreting`. enum: - - response.code_interpreter_call.interpreting + - input_text + description: The type of the input item. Always `input_text`. + default: input_text x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response for which the code interpreter is interpreting code. - item_id: + text: type: string - description: The unique identifier of the code interpreter tool call item. - sequence_number: - type: integer - description: The sequence number of this event, used to order streaming events. + description: The text input to the model. + prompt_cache_breakpoint: + $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.code_interpreter_call.interpreting - group: responses - example: | - { - "type": "response.code_interpreter_call.interpreting", - "output_index": 4, - "item_id": "ci_12345", - "sequence_number": 1 - } - BetaResponseCodeInterpreterCallInProgressEvent: - type: object - description: Emitted when a code interpreter call is in progress. + - text + title: Input text + description: A text input to the model. + BetaToolCallCallerParam: + discriminator: + propertyName: type + description: The execution context that produced this tool call. + anyOf: + - $ref: '#/components/schemas/BetaDirectToolCallCallerParam' + - $ref: '#/components/schemas/BetaProgramToolCallCallerParam' + BetaProgramToolCallCallerParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: The type of the event. Always `response.code_interpreter_call.in_progress`. enum: - - response.code_interpreter_call.in_progress + - program + description: The caller type. Always `program`. + default: program x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response for which the code interpreter call is in progress. - item_id: + caller_id: type: string - description: The unique identifier of the code interpreter tool call item. - sequence_number: - type: integer - description: The sequence number of this event, used to order streaming events. + maxLength: 64 + minLength: 1 + description: The call ID of the program item that produced this tool call. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.code_interpreter_call.in_progress - group: responses - example: | - { - "type": "response.code_interpreter_call.in_progress", - "output_index": 0, - "item_id": "ci_12345", - "sequence_number": 1 - } - BetaResponseCodeInterpreterCallCompletedEvent: - type: object - description: Emitted when the code interpreter call is completed. + - caller_id + BetaDirectToolCallCallerParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: The type of the event. Always `response.code_interpreter_call.completed`. enum: - - response.code_interpreter_call.completed + - direct + description: The caller type. Always `direct`. + default: direct x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response for which the code interpreter call is completed. - item_id: - type: string - description: The unique identifier of the code interpreter tool call item. - sequence_number: - type: integer - description: The sequence number of this event, used to order streaming events. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.code_interpreter_call.completed - group: responses - example: | - { - "type": "response.code_interpreter_call.completed", - "output_index": 5, - "item_id": "ci_12345", - "sequence_number": 1 - } - BetaResponseCodeInterpreterCallCodeDoneEvent: + BetaMCPToolCall: type: object - description: Emitted when the code snippet is finalized by the code interpreter. + title: MCP tool call + description: | + An invocation of a tool on an MCP server. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: The type of the event. Always `response.code_interpreter_call_code.done`. enum: - - response.code_interpreter_call_code.done + - mcp_call + description: | + The type of the item. Always `mcp_call`. x-stainless-const: true - output_index: - type: integer - description: The index of the output item in the response for which the code is finalized. - item_id: + id: type: string - description: The unique identifier of the code interpreter tool call item. - code: + description: | + The unique ID of the tool call. + server_label: type: string - description: The final code snippet output by the code interpreter. - sequence_number: - type: integer - description: The sequence number of this event, used to order streaming events. + description: | + The label of the MCP server running the tool. + name: + type: string + description: | + The name of the tool that was run. + arguments: + type: string + description: | + A JSON string of the arguments passed to the tool. + output: + anyOf: + - type: string + description: | + The output from the tool call. + - type: 'null' + error: + description: The error from the tool call, if any. + anyOf: + - $ref: '#/components/schemas/BetaMCPToolCallError' + - type: 'null' + status: + $ref: '#/components/schemas/BetaMCPToolCallStatus' + description: | + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + approval_request_id: + anyOf: + - type: string + description: | + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - type: 'null' required: - type - - output_index - - item_id - - code - - sequence_number - x-oaiMeta: - name: response.code_interpreter_call_code.done - group: responses - example: | - { - "type": "response.code_interpreter_call_code.done", - "output_index": 3, - "item_id": "ci_12345", - "code": "print('done')", - "sequence_number": 1 - } - BetaResponseCodeInterpreterCallCodeDeltaEvent: - type: object - description: Emitted when a partial code snippet is streamed by the code interpreter. + - id + - server_label + - name + - arguments + BetaMCPToolCallStatus: + type: string + enum: + - in_progress + - completed + - incomplete + - calling + - failed + BetaMCPToolCallError: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaMCPProtocolError' + - $ref: '#/components/schemas/BetaMCPToolExecutionError' + - $ref: '#/components/schemas/BetaHTTPError' + BetaHTTPError: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: The type of the event. Always `response.code_interpreter_call_code.delta`. enum: - - response.code_interpreter_call_code.delta + - http_error + default: http_error x-stainless-const: true - output_index: + code: type: integer - description: The index of the output item in the response for which the code is being streamed. - item_id: - type: string - description: The unique identifier of the code interpreter tool call item. - delta: + message: type: string - description: The partial code snippet being streamed by the code interpreter. - sequence_number: - type: integer - description: The sequence number of this event, used to order streaming events. + type: object required: - type - - output_index - - item_id - - delta - - sequence_number - x-oaiMeta: - name: response.code_interpreter_call_code.delta - group: responses - example: | - { - "type": "response.code_interpreter_call_code.delta", - "output_index": 0, - "item_id": "ci_12345", - "delta": "print('Hello, world')", - "sequence_number": 1 - } - BetaResponseAudioTranscriptDoneEvent: - type: object - description: Emitted when the full audio transcript is completed. + - code + - message + BetaMCPToolExecutionError: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.audio.transcript.done`. enum: - - response.audio.transcript.done + - mcp_tool_execution_error + default: mcp_tool_execution_error x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of this event. - required: - - type - - response_id - - sequence_number - x-oaiMeta: - name: response.audio.transcript.done - group: responses - example: | - { - "type": "response.audio.transcript.done", - "response_id": "resp_123", - "sequence_number": 1 - } - BetaResponseAudioTranscriptDeltaEvent: + content: {} type: object - description: Emitted when there is a partial transcript of audio. + required: + - type + - content + BetaMCPProtocolError: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.audio.transcript.delta`. enum: - - response.audio.transcript.delta + - mcp_protocol_error + default: mcp_protocol_error x-stainless-const: true - delta: - type: string - description: | - The partial transcript of the audio response. - sequence_number: + code: type: integer - description: The sequence number of this event. + message: + type: string + type: object required: - type - - response_id - - delta - - sequence_number - x-oaiMeta: - name: response.audio.transcript.delta - group: responses - example: | - { - "type": "response.audio.transcript.delta", - "response_id": "resp_123", - "delta": " ... partial transcript ... ", - "sequence_number": 1 - } - BetaResponseAudioDoneEvent: + - code + - message + BetaMCPApprovalResponse: type: object - description: Emitted when the audio response is complete. + title: MCP approval response + description: | + A response to an MCP approval request. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: | - The type of the event. Always `response.audio.done`. enum: - - response.audio.done + - mcp_approval_response + description: | + The type of the item. Always `mcp_approval_response`. x-stainless-const: true - sequence_number: - type: integer + id: + anyOf: + - type: string + description: | + The unique ID of the approval response + - type: 'null' + approval_request_id: + type: string description: | - The sequence number of the delta. + The ID of the approval request being answered. + approve: + type: boolean + description: | + Whether the request was approved. + reason: + anyOf: + - type: string + description: | + Optional reason for the decision. + - type: 'null' required: - type - - sequence_number - - response_id - x-oaiMeta: - name: response.audio.done - group: responses - example: | - { - "type": "response.audio.done", - "response_id": "resp-123", - "sequence_number": 1 - } - BetaResponseAudioDeltaEvent: + - request_id + - approve + - approval_request_id + BetaMCPApprovalRequest: type: object - description: Emitted when there is a partial audio response. + title: MCP approval request + description: | + A request for human approval of a tool invocation. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: | - The type of the event. Always `response.audio.delta`. enum: - - response.audio.delta + - mcp_approval_request + description: | + The type of the item. Always `mcp_approval_request`. x-stainless-const: true - sequence_number: - type: integer + id: + type: string description: | - A sequence number for this chunk of the stream response. - delta: + The unique ID of the approval request. + server_label: type: string description: | - A chunk of Base64 encoded response audio bytes. + The label of the MCP server making the request. + name: + type: string + description: | + The name of the tool to run. + arguments: + type: string + description: | + A JSON string of arguments for the tool. required: - type - - delta - - sequence_number - x-oaiMeta: - name: response.audio.delta - group: responses - example: | - { - "type": "response.audio.delta", - "response_id": "resp_123", - "delta": "base64encoded...", - "sequence_number": 1 - } - BetaResponseIncompleteEvent: + - id + - server_label + - name + - arguments + BetaMCPListTools: type: object + title: MCP list tools description: | - An event that is emitted when a response finishes as incomplete. - - Over WebSocket, steering can finish a response with - `response.incomplete_details.reason` set to `steered`, followed automatically - by a successor `response.created` that commits the queued steering input. + A list of tools available on an MCP server. properties: agent: anyOf: - $ref: '#/components/schemas/BetaAgentTag' - type: 'null' - description: The agent that owns this multi-agent streaming event. + description: The agent that produced this item. type: type: string - description: | - The type of the event. Always `response.incomplete`. enum: - - response.incomplete + - mcp_list_tools + description: | + The type of the item. Always `mcp_list_tools`. x-stainless-const: true - response: - $ref: '#/components/schemas/BetaResponse' + id: + type: string description: | - The response that was incomplete. - sequence_number: - type: integer - description: The sequence number of this event. + The unique ID of the list. + server_label: + type: string + description: | + The label of the MCP server. + tools: + type: array + items: + $ref: '#/components/schemas/BetaMCPListToolsTool' + description: | + The tools available on the server. + error: + anyOf: + - type: string + description: | + Error message if the server could not list tools. + - type: 'null' required: - type - - response - - sequence_number - x-oaiMeta: - name: response.incomplete - group: responses - example: | - { - "type": "response.incomplete", - "response": { - "id": "resp_123", - "object": "response", - "created_at": 1740855869, - "status": "incomplete", - "completed_at": null, - "error": null, - "incomplete_details": { - "reason": "max_tokens" - }, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [], - "previous_response_id": null, - "reasoning_effort": null, - "store": false, - "temperature": 1, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} - }, - "sequence_number": 1 - } - BetaResponseFailedEvent: + - id + - server_label + - tools + BetaMCPListToolsTool: type: object + title: MCP list tools tool description: | - An event that is emitted when a response fails. + A tool available on an MCP server. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. - type: + name: type: string description: | - The type of the event. Always `response.failed`. - enum: - - response.failed - x-stainless-const: true - sequence_number: - type: integer - description: The sequence number of this event. - response: - $ref: '#/components/schemas/BetaResponse' + The name of the tool. + description: + anyOf: + - type: string + description: | + The description of the tool. + - type: 'null' + input_schema: + type: object description: | - The response that failed. + The JSON schema describing the tool's input. + annotations: + anyOf: + - type: object + description: | + Additional annotations about the tool. + - type: 'null' required: - - type - - response - - sequence_number - x-oaiMeta: - name: response.failed - group: responses - example: | - { - "type": "response.failed", - "response": { - "id": "resp_123", - "object": "response", - "created_at": 1740855869, - "status": "failed", - "completed_at": null, - "error": { - "code": "server_error", - "message": "The model failed to generate a response." - }, - "incomplete_details": null, - "instructions": null, - "max_output_tokens": null, - "model": "gpt-6-astra", - "output": [], - "previous_response_id": null, - "reasoning_effort": null, - "store": false, - "temperature": 1, - "text": { - "format": { - "type": "text" - } - }, - "tool_choice": "auto", - "tools": [], - "top_p": 1, - "truncation": "disabled", - "usage": null, - "user": null, - "metadata": {} - } - } - BetaResponseWebSearchCallCompletedEvent: - type: object - description: Emitted when a web search call is completed. + - name + - input_schema + BetaApplyPatchToolCallOutputItemParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.web_search_call.completed`. enum: - - response.web_search_call.completed + - apply_patch_call_output + description: The type of the item. Always `apply_patch_call_output`. + default: apply_patch_call_output x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the web search call is associated with. - item_id: + id: + anyOf: + - type: string + description: The unique ID of the apply patch tool call output. Populated when this item is returned via API. + example: apco_123 + - type: 'null' + call_id: type: string - description: | - Unique ID for the output item associated with the web search call. - sequence_number: - type: integer - description: The sequence number of the web search call being processed. + maxLength: 64 + minLength: 1 + description: The unique ID of the apply patch tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + description: The execution context that produced this tool call. + - type: 'null' + status: + $ref: '#/components/schemas/BetaApplyPatchCallOutputStatusParam' + description: The status of the apply patch tool call output. One of `completed` or `failed`. + output: + anyOf: + - type: string + maxLength: 10485760 + description: Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - type: 'null' + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.web_search_call.completed - group: responses - example: | - { - "type": "response.web_search_call.completed", - "output_index": 0, - "item_id": "ws_123", - "sequence_number": 0 - } - BetaResponseWebSearchCallSearchingEvent: - type: object - description: Emitted when a web search call is executing. + - call_id + - status + title: Apply patch tool call output + description: The streamed output emitted by an apply patch tool call. + BetaApplyPatchCallOutputStatusParam: + type: string + enum: + - completed + - failed + title: Apply patch call output status + description: Outcome values reported for apply_patch tool call outputs. + BetaApplyPatchToolCallItemParam: properties: agent: anyOf: - - $ref: '#/components/schemas/BetaAgentTag' + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.web_search_call.searching`. enum: - - response.web_search_call.searching + - apply_patch_call + description: The type of the item. Always `apply_patch_call`. + default: apply_patch_call x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the web search call is associated with. - item_id: + id: + anyOf: + - type: string + description: The unique ID of the apply patch tool call. Populated when this item is returned via API. + example: apc_123 + - type: 'null' + call_id: type: string - description: | - Unique ID for the output item associated with the web search call. - sequence_number: - type: integer - description: The sequence number of the web search call being processed. + maxLength: 64 + minLength: 1 + description: The unique ID of the apply patch tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + description: The execution context that produced this tool call. + - type: 'null' + status: + $ref: '#/components/schemas/BetaApplyPatchCallStatusParam' + description: The status of the apply patch tool call. One of `in_progress` or `completed`. + operation: + $ref: '#/components/schemas/BetaApplyPatchOperationParam' + description: The specific create, delete, or update instruction for the apply_patch tool call. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.web_search_call.searching - group: responses - example: | - { - "type": "response.web_search_call.searching", - "output_index": 0, - "item_id": "ws_123", - "sequence_number": 0 - } - BetaResponseWebSearchCallInProgressEvent: - type: object - description: Emitted when a web search call is initiated. + - call_id + - status + - operation + title: Apply patch tool call + description: A tool call representing a request to create, delete, or update files using diff patches. + BetaApplyPatchOperationParam: + discriminator: + propertyName: type + title: Apply patch operation + description: One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool. + anyOf: + - $ref: '#/components/schemas/BetaApplyPatchCreateFileOperationParam' + - $ref: '#/components/schemas/BetaApplyPatchDeleteFileOperationParam' + - $ref: '#/components/schemas/BetaApplyPatchUpdateFileOperationParam' + BetaApplyPatchUpdateFileOperationParam: properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: | - The type of the event. Always `response.web_search_call.in_progress`. enum: - - response.web_search_call.in_progress + - update_file + description: The operation type. Always `update_file`. + default: update_file x-stainless-const: true - output_index: - type: integer - description: | - The index of the output item that the web search call is associated with. - item_id: + path: type: string - description: | - Unique ID for the output item associated with the web search call. - sequence_number: - type: integer - description: The sequence number of the web search call being processed. + minLength: 1 + description: Path of the file to update relative to the workspace root. + diff: + type: string + maxLength: 10485760 + description: Unified diff content to apply to the existing file. + type: object required: - type - - output_index - - item_id - - sequence_number - x-oaiMeta: - name: response.web_search_call.in_progress - group: responses - example: | - { - "type": "response.web_search_call.in_progress", - "output_index": 0, - "item_id": "ws_123", - "sequence_number": 0 - } - BetaResponseSteerFailedEvent: + - path + - diff + title: Apply patch update file operation + description: Instruction for updating an existing file via the apply_patch tool. + BetaApplyPatchDeleteFileOperationParam: + properties: + type: + type: string + enum: + - delete_file + description: The operation type. Always `delete_file`. + default: delete_file + x-stainless-const: true + path: + type: string + minLength: 1 + description: Path of the file to delete relative to the workspace root. type: object - title: ResponseSteerFailedEvent - description: | - Emitted when steering input is rejected or cannot be committed to a - successor response. Returns the original, uncommitted input so the client - can carry it into `response.create` when appropriate. Invalid input must - be corrected before retrying. - - Failures after acceptance include the same steering ID. Failures before an - ID is allocated omit `steer.id`. A lost connection or missing acknowledgement - leaves the outcome unknown; it is not proof that the input was rejected. + required: + - type + - path + title: Apply patch delete file operation + description: Instruction for deleting an existing file via the apply_patch tool. + BetaApplyPatchCreateFileOperationParam: properties: type: type: string enum: - - response.steer.failed - description: The event discriminator. Always `response.steer.failed`. + - create_file + description: The operation type. Always `create_file`. + default: create_file x-stainless-const: true - sequence_number: - type: integer - description: The sequence number for this event. - steer: - type: object - description: The steering submission that could not be committed. - properties: - id: - type: string - description: | - The ID assigned to the steering submission, if one was allocated. - previous_response_id: - type: string - description: The ID of the response that was targeted for steering. - input: - $ref: '#/components/schemas/BetaResponseSteerInput' - required: - - previous_response_id - - input - error: - type: object - description: Information about why the input could not be committed. - properties: - type: - type: string - enum: - - invalid_request_error - description: The error type. Always `invalid_request_error`. - x-stainless-const: true - code: - $ref: '#/components/schemas/BetaResponseSteerErrorCode' - message: - type: string - description: A human-readable description of the error. - required: - - type - - code - - message - stream_id: + path: type: string - description: | - The WebSocket lane that emitted this event, when the target response is - available and its `response.create` event supplied a `stream_id`. + minLength: 1 + description: Path of the file to create relative to the workspace root. + diff: + type: string + maxLength: 10485760 + description: Unified diff content to apply when creating the file. + type: object required: - type - - sequence_number - - steer - - error - x-oaiMeta: - name: response.steer.failed - group: responses - example: | - { - "type": "response.steer.failed", - "sequence_number": 5, - "steer": { - "id": "steer_456", - "previous_response_id": "resp_123", - "input": [ - { - "type": "message", - "role": "user", - "content": [ - { - "type": "input_text", - "text": "Prioritize the database rollout." - } - ] - } - ] - }, - "error": { - "type": "invalid_request_error", - "code": "successor_creation_failed", - "message": "We couldn't start the next response. Send this steering input again with response.create." - } - } - BetaResponseSteerErrorCode: - title: ResponseSteerErrorCode - description: | - A machine-readable steering error code. Clients should handle unknown - values because additional codes may be introduced. Known values include: - - `response_not_found`: The target response is not available on this connection. - - `invalid_input`: The event or input failed validation. - - `steering_not_supported`: The model or response execution mode does not support steering. - - `too_many_pending_steers`: Too much steering input is pending for the response. - - `response_already_completed`: The response completed and is no longer accepting steering input. - - `response_not_active`: The response is no longer accepting steering input. - - `successor_creation_failed`: The successor response could not be created. - anyOf: - - type: string - enum: - - response_not_found - - invalid_input - - steering_not_supported - - too_many_pending_steers - - response_already_completed - - response_not_active - - successor_creation_failed - - type: string - BetaResponseSteerInput: - title: ResponseSteerInput - description: | - Input to queue for a continuation of the response. Uses the same string or - input-item shape as `response.create.input`, with a non-empty array when - supplying input items. - - Steering accepts only messages with the `user` role. Each message may - contain only `type`, `role`, and `content`, with `content` as a string or an - array of `input_text`, `input_image`, and `input_file` parts. The optional - `type` must be `message`. Other roles, tool outputs, and item types are not - supported for steering. - anyOf: - - type: string - title: Text input - description: A text input, equivalent to a message with the `user` role. - - $ref: '#/components/schemas/BetaResponseSteerInputItemList' - BetaResponseSteerInputItemList: - type: array - title: Response steer input item list - description: A non-empty list of message inputs to queue for the response. - minItems: 1 - items: - $ref: '#/components/schemas/BetaResponseSteerInputItem' - BetaResponseSteerInputItem: - title: Response steer input item - anyOf: - - $ref: '#/components/schemas/BetaUserMessageItemParam' - - $ref: '#/components/schemas/BetaFunctionCallOutputItemParam' - discriminator: - propertyName: type - BetaUserMessageItemParam: + - path + - diff + title: Apply patch create file operation + description: Instruction for creating a new file via the apply_patch tool. + BetaApplyPatchCallStatusParam: + type: string + enum: + - in_progress + - completed + title: Apply patch call status + description: Status values reported for apply_patch tool calls. + BetaFunctionShellCallOutputItemParam: properties: agent: anyOf: @@ -93284,1917 +87218,8014 @@ components: id: anyOf: - type: string - description: The unique ID of this message item. - example: msg_123 + description: The unique ID of the shell tool call output. Populated when this item is returned via API. + example: sho_123 - type: 'null' - type: + call_id: type: string - enum: - - message - description: The item type. Always `message`. - default: message - x-stainless-const: true - role: + maxLength: 64 + minLength: 1 + description: The unique ID of the shell tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + description: The execution context that produced this tool call. + - type: 'null' + type: type: string enum: - - user - description: The message role. Always `user`. - default: user + - shell_call_output + description: The type of the item. Always `shell_call_output`. + default: shell_call_output x-stainless-const: true - content: - description: The message content, as an array of content parts. - anyOf: - - items: - $ref: '#/components/schemas/BetaResponseSteerInputContent' - description: A piece of message content, such as text, an image, or a file. - type: array - - type: string - maxLength: 10485760 - description: The message content, as a single string. + output: + items: + $ref: '#/components/schemas/BetaFunctionShellCallOutputContentParam' + type: array + description: Captured chunks of stdout and stderr output, along with their associated outcomes. status: anyOf: - - type: string - description: The status of the message item. + - $ref: '#/components/schemas/BetaFunctionShellCallItemStatus' + description: The status of the shell call output. + - type: 'null' + max_output_length: + anyOf: + - type: integer + description: The maximum number of UTF-8 characters captured for this shell call's combined output. - type: 'null' type: object required: + - call_id - type - - role - - content - BetaResponseSteerPendingEvent: + - output + title: Shell tool call output + description: The streamed output items emitted by a shell tool call. + BetaFunctionShellCallItemStatus: + type: string + enum: + - in_progress + - completed + - incomplete + title: Shell call status + description: Status values reported for shell tool calls. + BetaFunctionShellCallOutputContentParam: + properties: + stdout: + type: string + maxLength: 10485760 + description: Captured stdout output for the shell call. + stderr: + type: string + maxLength: 10485760 + description: Captured stderr output for the shell call. + outcome: + $ref: '#/components/schemas/BetaFunctionShellCallOutputOutcomeParam' + description: The exit or timeout outcome associated with this shell call. type: object - title: ResponseSteerPendingEvent - description: | - Emitted when accepted steering input remains queued after the target - response completes. The server still owns the input. Do not resend it. - The successor's `response.created` event is the commit point. - - When `reason` is `waiting_for_required_input`, this event follows - `response.completed` while the response waits for the tool results or - approval decisions identified by `required_input`. Copy those stubs, fill - their result fields using the ordinary `response.create` input schemas, - and submit one continuation per parent with the same `previous_response_id` - and WebSocket lane. Use saved results without rerunning tools. The queued - steering input is prepended in submission order to the continuation's - input. That explicit request retains its own settings. - - This notification is emitted at most once per steering submission. Multiple - submissions for the same parent can report the same required inputs; they - do not each require a separate continuation. + required: + - stdout + - stderr + - outcome + title: Shell output content + description: Captured stdout and stderr for a portion of a shell tool call output. + BetaFunctionShellCallOutputOutcomeParam: + discriminator: + propertyName: type + title: Shell call outcome + description: The exit or timeout outcome associated with this shell call. + anyOf: + - $ref: '#/components/schemas/BetaFunctionShellCallOutputTimeoutOutcomeParam' + - $ref: '#/components/schemas/BetaFunctionShellCallOutputExitOutcomeParam' + BetaFunctionShellCallOutputExitOutcomeParam: properties: type: type: string enum: - - response.steer.pending - description: The event discriminator. Always `response.steer.pending`. + - exit + description: The outcome type. Always `exit`. + default: exit x-stainless-const: true - sequence_number: + exit_code: type: integer - description: The sequence number for this event. - steer: - type: object - description: The steering submission that remains queued. - properties: - id: - type: string - description: The ID assigned to the steering submission. - previous_response_id: - type: string - description: The ID of the response being steered. - required: - - id - - previous_response_id - reason: - $ref: '#/components/schemas/BetaResponseSteerPendingReason' - required_input: - type: array - minItems: 1 - description: | - Input stubs identifying outstanding client-owned tool results or - approval decisions. Each stub contains identifying fields only; the - client supplies the result before including it in `response.create`. - items: - $ref: '#/components/schemas/BetaResponseSteerRequiredInput' - stream_id: + description: The exit code returned by the shell process. + type: object + required: + - type + - exit_code + title: Shell call exit outcome + description: Indicates that the shell commands finished and returned an exit code. + BetaFunctionShellCallOutputTimeoutOutcomeParam: + properties: + type: type: string - description: | - The WebSocket lane that emitted this event. This field is present when - the target response's `response.create` event supplied a `stream_id`. + enum: + - timeout + description: The outcome type. Always `timeout`. + default: timeout + x-stainless-const: true + type: object required: - type - - sequence_number - - steer - - reason - - required_input - x-oaiMeta: - name: response.steer.pending - group: responses - example: | - { - "type": "response.steer.pending", - "sequence_number": 10, - "steer": { - "id": "steer_456", - "previous_response_id": "resp_123" - }, - "reason": "waiting_for_required_input", - "required_input": [ - { - "type": "function_call_output", - "call_id": "call_789", - "name": "lookup" - } - ] - } - BetaResponseSteerRequiredInput: - title: ResponseSteerRequiredInput - description: | - An input stub identifying an outstanding client-owned tool result or - approval decision. Copy the stub and fill the result fields using the - corresponding `response.create` input schema. Use saved results without - rerunning the tool. The server does not supply results, approval decisions, - or safety acknowledgements in these stubs. - discriminator: - propertyName: type - anyOf: - - type: object - title: Required function tool call output - additionalProperties: false - description: | - Supply `output` using the function tool call output input schema. - properties: - type: - type: string - enum: - - function_call_output - x-stainless-const: true - call_id: - type: string - name: - type: string - required: - - type - - call_id - - name - - type: object - title: Required custom tool call output - additionalProperties: false - description: | - Supply `output` using the custom tool call output input schema. The - original custom tool call supplies the tool's name. - properties: - type: - type: string - enum: - - custom_tool_call_output - x-stainless-const: true - call_id: - type: string - required: - - type - - call_id - - type: object - title: Required computer tool call output - additionalProperties: false - description: | - Supply `output` using the computer tool call output input schema, - including any required `acknowledged_safety_checks`. - properties: - type: - type: string - enum: - - computer_call_output - x-stainless-const: true - call_id: - type: string - required: - - type - - call_id - - type: object - title: Required shell tool call output - additionalProperties: false - description: | - Supply `output` using the shell tool call output input schema. Each - output entry includes `stdout`, `stderr`, and `outcome`. - properties: - type: - type: string - enum: - - shell_call_output - x-stainless-const: true - call_id: - type: string - required: - - type - - call_id - - type: object - title: Required apply patch tool call output - additionalProperties: false - description: | - Supply `status` and optional `output` using the apply patch tool call - output input schema. - properties: - type: - type: string - enum: - - apply_patch_call_output - x-stainless-const: true - call_id: - type: string - required: - - type - - call_id - - type: object - title: Required tool search output - additionalProperties: false - description: | - Supply `tools` using the tool search output input schema, retaining - `execution: "client"`. - properties: - type: - type: string - enum: - - tool_search_output - x-stainless-const: true - call_id: - type: string - execution: - type: string - enum: - - client - x-stainless-const: true - required: - - type - - call_id - - execution - - type: object - title: Required MCP approval response - additionalProperties: false - description: | - Supply `approve` using the MCP approval response input schema. An - optional `reason` can be supplied when denying the request. The original - approval request identifies the tool and server. - properties: - type: - type: string - enum: - - mcp_approval_response - x-stainless-const: true - approval_request_id: + title: Shell call timeout outcome + description: Indicates that the shell call exceeded its configured time limit. + BetaFunctionShellCallItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of the shell tool call. Populated when this item is returned via API. + example: sh_123 + - type: 'null' + call_id: + type: string + maxLength: 64 + minLength: 1 + description: The unique ID of the shell tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + description: The execution context that produced this tool call. + - type: 'null' + type: + type: string + enum: + - shell_call + description: The type of the item. Always `shell_call`. + default: shell_call + x-stainless-const: true + action: + $ref: '#/components/schemas/BetaFunctionShellActionParam' + description: The shell commands and limits that describe how to run the tool call. + status: + anyOf: + - $ref: '#/components/schemas/BetaFunctionShellCallItemStatus' + description: The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - type: 'null' + environment: + anyOf: + - discriminator: + propertyName: type + description: The environment to execute the shell commands in. + anyOf: + - $ref: '#/components/schemas/BetaLocalEnvironmentParam' + - $ref: '#/components/schemas/BetaContainerReferenceParam' + - type: 'null' + type: object + required: + - call_id + - type + - action + title: Shell tool call + description: A tool representing a request to execute one or more shell commands. + BetaFunctionShellActionParam: + properties: + commands: + items: type: string - required: - - type - - approval_request_id - BetaResponseSteerPendingReason: - title: ResponseSteerPendingReason - description: | - An extensible enum describing why accepted steering input is still queued. - Clients should handle unknown values because additional reasons may be - introduced. Known values include: - - `waiting_for_required_input`: The response is waiting for the tool results or approval decisions identified by `required_input`. - anyOf: - - type: string - enum: - - waiting_for_required_input - - type: string - BetaResponseSteerAcceptedEvent: + type: array + description: Ordered shell commands for the execution environment to run. + timeout_ms: + anyOf: + - type: integer + description: Maximum wall-clock time in milliseconds to allow the shell commands to run. + - type: 'null' + max_output_length: + anyOf: + - type: integer + description: Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - type: 'null' type: object - title: ResponseSteerAcceptedEvent + required: + - commands + title: Shell action + description: Commands and limits describing how to run the shell tool call. + BetaLocalShellToolCallOutput: + type: object + title: Local shell call output description: | - Emitted when steering input has been validated and queued. Acceptance means - the server owns the input, not that it has been applied. The successor's - `response.created` event is the commit point. If accepted input cannot be - committed, `response.steer.failed` returns it with the same steering ID. - - When the response stops for client-owned tool output or approval, the input - remains queued and `response.steer.pending` is emitted after - `response.completed`. Fill the pending event's `required_input` stubs with - saved results and send one matching explicit `response.create` per parent. - Do not resend accepted input while it is still queued. + The output of a local shell tool call. properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. type: type: string enum: - - response.steer.accepted - description: The event discriminator. Always `response.steer.accepted`. + - local_shell_call_output + description: | + The type of the local shell tool call output. Always `local_shell_call_output`. x-stainless-const: true - sequence_number: - type: integer - description: The sequence number for this event. - steer: - type: object - description: The accepted steering submission. - properties: - id: - type: string - description: The ID assigned to the steering submission. - previous_response_id: - type: string - description: The ID of the response being steered. - required: - - id - - previous_response_id - stream_id: + id: type: string description: | - The WebSocket lane that emitted this event. This field is present when - the target response's `response.create` event supplied a `stream_id`. + The unique ID of the local shell tool call generated by the model. + output: + type: string + description: | + A JSON string of the output of the local shell tool call. + status: + anyOf: + - type: string + enum: + - in_progress + - completed + - incomplete + description: | + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - type: 'null' required: + - id - type - - sequence_number - - steer - x-oaiMeta: - name: response.steer.accepted - group: responses - example: | - { - "type": "response.steer.accepted", - "sequence_number": 2, - "steer": { - "id": "steer_456", - "previous_response_id": "resp_123" - } - } - BetaResponseSteerEvent: + - call_id + - output + BetaLocalShellToolCall: type: object - title: ResponseSteerEvent - additionalProperties: false + title: Local shell call description: | - Queues user input to steer a response on this WebSocket connection. Input - can contain text, images, and files. Steering is supported only for - single-agent responses on models and execution modes that support steering. - Responses bound to a conversation or using automatic compaction do not - support steering. - - A `response.steer.accepted` event acknowledges that the server owns the - queued input, not that it has been applied. The successor's `response.created` - event is the commit point. Input that cannot be committed is returned in - `response.steer.failed`. - - Steering may cause the active response to finish at a safe output boundary - with `response.incomplete` and `incomplete_details.reason` set to `steered`, - followed automatically by a successor `response.created`. Normal completion - can also be followed by an automatic successor. Automatic successors inherit - the previous response's settings and continue from it with the queued input. - - If the response stops for client-owned tool output or approval, accepted - steering input remains queued and `response.steer.pending` is emitted after - `response.completed`. Fill the `required_input` stubs from that event with - saved tool results or approval decisions, and send one explicit - `response.create` per parent with the same `previous_response_id` and - WebSocket lane. Do not rerun tools or resend accepted steering input. The - queued input is prepended in submission order to that request's input, and - the explicit request retains its own settings. - - This event accepts only `type`, `previous_response_id`, and `input`. Do not - send `stream_id`; the target response determines the WebSocket lane. + A tool call to run a command on the local shell. properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. type: type: string enum: - - response.steer - description: The event discriminator. Always `response.steer`. + - local_shell_call + description: | + The type of the local shell call. Always `local_shell_call`. x-stainless-const: true - previous_response_id: + id: type: string - description: The ID of the response to steer on this WebSocket connection. - input: - $ref: '#/components/schemas/BetaResponseSteerInput' + description: | + The unique ID of the local shell call. + call_id: + type: string + description: | + The unique ID of the local shell tool call generated by the model. + action: + $ref: '#/components/schemas/BetaLocalShellExecAction' + status: + type: string + enum: + - in_progress + - completed + - incomplete + description: | + The status of the local shell call. required: - type - - previous_response_id - - input - x-oaiMeta: - name: response.steer - group: responses - example: | - { - "type": "response.steer", - "previous_response_id": "resp_123", - "input": [ - { - "type": "message", - "role": "user", - "content": [ - { - "type": "input_text", - "text": "Prioritize the database rollout." - } - ] - } - ] - } - BetaOutputAudio: + - id + - call_id + - action + - status + BetaLocalShellExecAction: + properties: + type: + type: string + enum: + - exec + description: The type of the local shell action. Always `exec`. + default: exec + x-stainless-const: true + command: + items: + type: string + type: array + description: The command to run. + timeout_ms: + anyOf: + - type: integer + description: Optional timeout in milliseconds for the command. + - type: 'null' + working_directory: + anyOf: + - type: string + description: Optional working directory to run the command in. + - type: 'null' + env: + additionalProperties: + type: string + type: object + description: Environment variables to set for the command. + x-oaiTypeLabel: map + user: + anyOf: + - type: string + description: Optional user to run the command as. + - type: 'null' type: object - title: Output audio + required: + - type + - command + - env + title: Local shell exec action + description: Execute a shell command on the server. + BetaCodeInterpreterToolCall: + type: object + title: Code interpreter tool call description: | - An audio output from the model. + A tool call to run code. properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. type: type: string - description: | - The type of the output audio. Always `output_audio`. enum: - - output_audio + - code_interpreter_call + default: code_interpreter_call x-stainless-const: true - data: + description: | + The type of the code interpreter tool call. Always `code_interpreter_call`. + id: type: string description: | - Base64-encoded audio data from the model. - transcript: + The unique ID of the code interpreter tool call. + status: type: string + enum: + - in_progress + - completed + - incomplete + - interpreting + - failed description: | - The transcript of the audio data from the model. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + container_id: + type: string + description: | + The ID of the container used to run the code. + code: + anyOf: + - type: string + description: | + The code to run, or null if not available. + - type: 'null' + outputs: + anyOf: + - type: array + items: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaCodeInterpreterOutputLogs' + - $ref: '#/components/schemas/BetaCodeInterpreterOutputImage' + discriminator: + propertyName: type + description: | + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + - type: 'null' required: - type - - data - - transcript - BetaInputAudio: + - id + - status + - container_id + - code + - outputs + BetaCodeInterpreterOutputImage: + properties: + type: + type: string + enum: + - image + description: The type of the output. Always `image`. + default: image + x-stainless-const: true + url: + type: string + format: uri + description: The URL of the image output from the code interpreter. type: object - title: Input audio - description: | - An audio input to the model. + required: + - type + - url + title: Code interpreter output image + description: The image output from the code interpreter. + BetaCodeInterpreterOutputLogs: properties: type: type: string - description: | - The type of the input item. Always `input_audio`. enum: - - input_audio + - logs + description: The type of the output. Always `logs`. + default: logs x-stainless-const: true - input_audio: - type: object - properties: - data: - type: string - description: | - Base64-encoded audio data. - format: - type: string - description: | - The format of the audio data. Currently supported formats are `mp3` and - `wav`. - enum: - - mp3 - - wav - required: - - data - - format + logs: + type: string + description: The logs output from the code interpreter. + type: object required: - type - - input_audio - BetaInputParam: - description: | - Text, image, or file inputs to the model, used to generate a response. - - Learn more: - - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) - - [Image inputs](https://developers.openai.com/api/docs/guides/images-vision) - - [File inputs](https://developers.openai.com/api/docs/guides/file-inputs) - - [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state) - - [Function calling](https://developers.openai.com/api/docs/guides/function-calling) - anyOf: - - type: string - title: Text input - description: | - A text input to the model, equivalent to a text input with the - `user` role. - - type: array - title: Input item list - description: | - A list of one or many input items to the model, containing - different content types. - items: - $ref: '#/components/schemas/BetaInputItem' - BetaContent: - description: | - Multi-modal input and output contents. - anyOf: - - title: Input content types - $ref: '#/components/schemas/BetaInputContent' - - title: Output content types - $ref: '#/components/schemas/BetaOutputContent' - BetaIncludeEnum: + - logs + title: Code interpreter output logs + description: The logs output from the code interpreter. + BetaImageGenToolCall: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + - type: 'null' + type: + type: string + enum: + - image_generation_call + description: The type of the image generation call. Always `image_generation_call`. + x-stainless-const: true + id: + type: string + description: The unique ID of the image generation call. + status: + type: string + enum: + - in_progress + - completed + - generating + - failed + description: The status of the image generation call. + result: + anyOf: + - type: string + description: The generated image encoded in base64. + - type: 'null' + size: + anyOf: + - anyOf: + - type: string + - type: string + enum: + - 1024x1024 + - 1024x1536 + - 1536x1024 + description: The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`. + - type: 'null' + quality: + anyOf: + - type: string + enum: + - low + - medium + - high + - xhigh + - max + - auto + description: The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`. + - type: 'null' + action: + anyOf: + - $ref: '#/components/schemas/BetaImageGenActionEnum' + description: The action used for image generation. + - type: 'null' + x-openai-go-optional-enum: true + background: + anyOf: + - $ref: '#/components/schemas/BetaImageBackground' + description: The background setting used for generation. + - type: 'null' + x-openai-go-optional-enum: true + output_format: + anyOf: + - $ref: '#/components/schemas/BetaImageOutputFormat' + description: The output format used for generation. + - type: 'null' + x-openai-go-optional-enum: true + revised_prompt: + anyOf: + - type: string + description: The prompt that was used after any model prompt rewriting. + - type: 'null' + type: object + required: + - type + - id + - status + - result + title: Image generation call + description: An image generation request made by the model. + BetaImageOutputFormat: type: string enum: - - 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 - description: |- - 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). - BetaResponsesServerEvent: - discriminator: - propertyName: type - description: | - Server events emitted by the Responses WebSocket server. - anyOf: - - title: BetaResponseAudioWsDelta - description: Emitted when there is a partial audio response. - allOf: - - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseAudioWsDone - description: Emitted when the audio response is complete. - allOf: - - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseAudioTranscriptWsDelta - description: Emitted when there is a partial transcript of audio. - allOf: - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseAudioTranscriptWsDone - description: Emitted when the full audio transcript is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCodeInterpreterCallCodeWsDelta - description: Emitted when a partial code snippet is streamed by the code interpreter. - allOf: - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCodeInterpreterCallCodeWsDone - description: Emitted when the code snippet is finalized by the code interpreter. - allOf: - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCodeInterpreterCallWsCompleted - description: Emitted when the code interpreter call is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCodeInterpreterCallInWsProgress - description: Emitted when a code interpreter call is in progress. - allOf: - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCodeInterpreterCallWsInterpreting - description: Emitted when the code interpreter is actively interpreting the code snippet. - allOf: - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCompactionWsCompacting - description: Emitted when new summary content is sampled for a compaction trigger. Contains no summary content. - allOf: - - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWsCompleted - description: Emitted when the model response is complete. - allOf: - - $ref: '#/components/schemas/BetaResponseCompletedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseContentPartWsAdded - description: Emitted when a new content part is added. - allOf: - - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseContentPartWsDone - description: Emitted when a content part is done. - allOf: - - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWsCreated - description: | - An event that is emitted when a response is created. - allOf: - - $ref: '#/components/schemas/BetaResponseCreatedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseFileSearchCallWsCompleted - description: Emitted when a file search call is completed (results found). - allOf: - - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseFileSearchCallInWsProgress - description: Emitted when a file search call is initiated. - allOf: - - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseFileSearchCallWsSearching - description: Emitted when a file search is currently searching. - allOf: - - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseFunctionCallArgumentsWsDelta - description: Emitted when there is a partial function-call arguments delta. - allOf: - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseFunctionCallArgumentsWsDone - description: Emitted when function-call arguments are finalized. - allOf: - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseShellCallCommandWsAdded - description: A streaming event that indicated a shell command was added to a tool call. - allOf: - - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseShellCallCommandWsDelta - description: A streaming event that indicated a shell command was incrementally updated. - allOf: - - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseShellCallCommandWsDone - description: A streaming event that indicated a shell command was completed. - allOf: - - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseShellCallOutputContentWsDelta - description: A streaming event that indicated shell call output was incrementally added. - allOf: - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' - x-stainless-skip: - - go - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseShellCallOutputContentWsDone - description: A streaming event that indicated shell call output was completed. - allOf: - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseInWsProgress - description: Emitted when the response is in progress. - allOf: - - $ref: '#/components/schemas/BetaResponseInProgressEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWsFailed - description: | - An event that is emitted when a response fails. - allOf: - - $ref: '#/components/schemas/BetaResponseFailedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWsIncomplete - description: | - An event that is emitted when a response finishes as incomplete. - - Over WebSocket, steering can finish a response with - `response.incomplete_details.reason` set to `steered`, followed automatically - by a successor `response.created` that commits the queued steering input. - allOf: - - $ref: '#/components/schemas/BetaResponseIncompleteEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseOutputItemWsAdded - description: Emitted when a new output item is added. - allOf: - - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseOutputItemWsDone - description: Emitted when an output item is marked done. - allOf: - - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningSummaryPartWsAdded - description: Emitted when a new reasoning summary part is added. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningSummaryPartWsDone - description: Emitted when a reasoning summary part is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningSummaryTextWsDelta - description: Emitted when a delta is added to a reasoning summary text. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningSummaryTextWsDone - description: Emitted when a reasoning summary text is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningTextWsDelta - description: Emitted when a delta is added to a reasoning text. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseReasoningTextWsDone - description: Emitted when a reasoning text is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseRefusalWsDelta - description: Emitted when there is a partial refusal text. - allOf: - - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseRefusalWsDone - description: Emitted when refusal text is finalized. - allOf: - - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseTextWsDelta - description: Emitted when there is an additional text delta. - allOf: - - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseTextWsDone - description: Emitted when text content is finalized. - allOf: - - $ref: '#/components/schemas/BetaResponseTextDoneEvent' - - type: object + - png + - webp + - jpeg + BetaImageBackground: + type: string + enum: + - transparent + - opaque + - auto + BetaCompactionSummaryItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The ID of the compaction item. + example: cmp_123 + - type: 'null' + type: + type: string + enum: + - compaction + description: The type of the item. Always `compaction`. + default: compaction + x-stainless-const: true + encrypted_content: + type: string + maxLength: 104857600 + description: The encrypted content of the compaction summary. + type: object + required: + - type + - encrypted_content + title: Compaction item + description: A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact). + BetaReasoningItem: + type: object + description: | + 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](https://developers.openai.com/api/docs/guides/conversation-state). + title: Reasoning + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + type: + type: string + description: | + The type of the object. Always `reasoning`. + enum: + - reasoning + x-stainless-const: true + id: + type: string + description: | + The unique identifier of the reasoning content. + encrypted_content: + anyOf: + - type: string + description: | + The encrypted content of the reasoning item. This is populated by default + for reasoning items returned by `POST /v1/responses` and WebSocket + `response.create` requests. + + When streaming, use the completed reasoning item and its + `encrypted_content` from the `response.output_item.done` event in + subsequent requests. The `encrypted_content` in + `response.output_item.added` may be incomplete. This is especially + important when `store` is `false` or when using Zero Data Retention. + - type: 'null' + summary: + type: array + description: | + Reasoning summary content. + items: + $ref: '#/components/schemas/BetaSummaryTextContent' + content: + type: array + description: | + Reasoning text content. + items: + $ref: '#/components/schemas/BetaReasoningTextContent' + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - id + - summary + - type + BetaReasoningTextContent: + properties: + type: + type: string + enum: + - reasoning_text + description: The type of the reasoning text. Always `reasoning_text`. + default: reasoning_text + x-stainless-const: true + text: + type: string + description: The reasoning text from the model. + type: object + required: + - type + - text + title: Reasoning text + description: Reasoning text from the model. + BetaSummaryTextContent: + properties: + type: + type: string + enum: + - summary_text + description: The type of the object. Always `summary_text`. + default: summary_text + x-stainless-const: true + text: + type: string + description: A summary of the reasoning output from the model so far. + type: object + required: + - type + - text + title: Summary text + description: A summary text from the model. + BetaResponseConfigurationUpdateItemParam: + type: object + description: | + An update to the conversation's response configuration. The configuration + remains in effect for subsequent responses until it is replaced by another + configuration update. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of the configuration update item. + example: cnfu_123 + - type: 'null' + type: + type: string + enum: + - configuration_update + description: The item type. Always `configuration_update`. + default: configuration_update + x-stainless-const: true + reasoning: + type: object + description: Updates to reasoning configuration. Only effort is supported. properties: - stream_id: - type: string + effort: + $ref: '#/components/schemas/BetaReasoningEffort' description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWebSearchCallWsCompleted - description: Emitted when a web search call is completed. - allOf: - - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' - - type: object - properties: - stream_id: + The reasoning effort to use for subsequent responses until another + configuration update replaces it. + required: + - type + BetaAdditionalToolsItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this additional tools item. + example: at_123 + - type: 'null' + type: + type: string + enum: + - additional_tools + description: The item type. Always `additional_tools`. + default: additional_tools + x-stainless-const: true + role: + type: string + enum: + - developer + description: The role that provided the additional tools. Only `developer` is supported. + default: developer + x-stainless-const: true + tools: + items: + $ref: '#/components/schemas/BetaTool' + type: array + description: A list of additional tools made available at this item. + type: object + required: + - type + - role + - tools + BetaToolSearchOutputItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this tool search output. + example: tso_123 + - type: 'null' + call_id: + anyOf: + - type: string + maxLength: 64 + minLength: 1 + description: The unique ID of the tool search call generated by the model. + - type: 'null' + type: + type: string + enum: + - tool_search_output + description: The item type. Always `tool_search_output`. + default: tool_search_output + x-stainless-const: true + execution: + $ref: '#/components/schemas/BetaToolSearchExecutionType' + description: Whether tool search was executed by the server or by the client. + tools: + items: + $ref: '#/components/schemas/BetaTool' + type: array + description: The loaded tool definitions returned by the tool search output. + status: + anyOf: + - $ref: '#/components/schemas/BetaFunctionCallItemStatus' + description: The status of the tool search output. + - type: 'null' + type: object + required: + - type + - tools + BetaFunctionCallItemStatus: + type: string + enum: + - in_progress + - completed + - incomplete + BetaToolSearchCallItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this tool search call. + example: tsc_123 + - type: 'null' + call_id: + anyOf: + - type: string + maxLength: 64 + minLength: 1 + description: The unique ID of the tool search call generated by the model. + - type: 'null' + type: + type: string + enum: + - tool_search_call + description: The item type. Always `tool_search_call`. + default: tool_search_call + x-stainless-const: true + execution: + $ref: '#/components/schemas/BetaToolSearchExecutionType' + description: Whether tool search was executed by the server or by the client. + arguments: + $ref: '#/components/schemas/BetaEmptyModelParam' + description: The arguments supplied to the tool search call. + status: + anyOf: + - $ref: '#/components/schemas/BetaFunctionCallItemStatus' + description: The status of the tool search call. + - type: 'null' + type: object + required: + - type + - arguments + BetaMultiAgentCallOutputItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this multi-agent call output. + example: maco_123 + - type: 'null' + call_id: + type: string + maxLength: 64 + minLength: 1 + description: The unique ID of the multi-agent call. + type: + type: string + enum: + - multi_agent_call_output + description: The item type. Always `multi_agent_call_output`. + default: multi_agent_call_output + x-stainless-const: true + action: + $ref: '#/components/schemas/BetaMultiAgentAction1' + description: The multi-agent action that produced this result. + output: + items: + $ref: '#/components/schemas/BetaOutputTextContentParam' + type: array + description: Text output returned by the multi-agent action. + type: object + required: + - call_id + - type + - action + - output + x-oai-beta: responses_multi_agent=v1 + BetaOutputTextContentParam: + properties: + type: + type: string + enum: + - output_text + description: The content type. Always `output_text`. + default: output_text + x-stainless-const: true + text: + type: string + maxLength: 10485760 + description: The text content. + annotations: + items: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaFileCitationParam' + - $ref: '#/components/schemas/BetaUrlCitationParam' + - $ref: '#/components/schemas/BetaContainerFileCitationParam' + type: array + description: Citations associated with the text content. + type: object + required: + - type + - text + BetaContainerFileCitationParam: + properties: + type: + type: string + enum: + - container_file_citation + description: The citation type. Always `container_file_citation`. + default: container_file_citation + x-stainless-const: true + start_index: + type: integer + minimum: 0 + description: The index of the first character of the citation in the message. + end_index: + type: integer + minimum: 0 + description: The index of the last character of the citation in the message. + container_id: + type: string + description: The ID of the container. + example: cntr_123 + file_id: + type: string + description: The ID of the container file. + example: cfile_123 + filename: + type: string + description: The filename of the container file cited. + type: object + required: + - type + - start_index + - end_index + - container_id + - file_id + - filename + BetaUrlCitationParam: + properties: + type: + type: string + enum: + - url_citation + description: The citation type. Always `url_citation`. + default: url_citation + x-stainless-const: true + start_index: + type: integer + minimum: 0 + description: The index of the first character of the citation in the message. + end_index: + type: integer + minimum: 0 + description: The index of the last character of the citation in the message. + url: + type: string + format: uri + description: The URL of the cited resource. + title: + type: string + description: The title of the cited resource. + type: object + required: + - type + - start_index + - end_index + - url + - title + BetaFileCitationParam: + properties: + type: + type: string + enum: + - file_citation + description: The citation type. Always `file_citation`. + default: file_citation + x-stainless-const: true + index: + type: integer + minimum: 0 + description: The index of the file in the list of files. + file_id: + type: string + description: The ID of the file. + example: file-123 + filename: + type: string + description: The filename of the file cited. + type: object + required: + - type + - index + - file_id + - filename + BetaMultiAgentAction1: + type: string + enum: + - spawn_agent + - interrupt_agent + - list_agents + - send_message + - followup_task + - wait_agent + BetaMultiAgentCallItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this multi-agent call. + example: mac_123 + - type: 'null' + call_id: + type: string + maxLength: 64 + minLength: 1 + description: The unique ID linking this call to its output. + type: + type: string + enum: + - multi_agent_call + description: The item type. Always `multi_agent_call`. + default: multi_agent_call + x-stainless-const: true + action: + $ref: '#/components/schemas/BetaMultiAgentAction1' + description: The multi-agent action that was executed. + arguments: + type: string + description: The action arguments as a JSON string. + type: object + required: + - call_id + - type + - action + - arguments + x-oai-beta: responses_multi_agent=v1 + BetaAgentMessageItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of this agent message item. + example: amsg_123 + - type: 'null' + type: + type: string + enum: + - agent_message + description: The item type. Always `agent_message`. + default: agent_message + x-stainless-const: true + author: + type: string + description: The sending agent identity. + recipient: + type: string + description: The destination agent identity. + content: + items: + discriminator: + propertyName: type + description: A plaintext, image, or encrypted agent message content part. + anyOf: + - $ref: '#/components/schemas/BetaInputTextContentParam' + - $ref: '#/components/schemas/BetaInputImageContentParamAutoParam' + - $ref: '#/components/schemas/BetaEncryptedContentParam' + type: array + description: Plaintext, image, or encrypted content sent between agents. + type: object + required: + - type + - author + - recipient + - content + title: Agent message + description: A message routed between agents. + x-oai-beta: responses_multi_agent=v1 + BetaEncryptedContentParam: + properties: + type: + type: string + enum: + - encrypted_content + description: The type of the input item. Always `encrypted_content`. + default: encrypted_content + x-stainless-const: true + encrypted_content: + type: string + maxLength: 10485760 + description: Opaque encrypted content. + type: object + required: + - type + - encrypted_content + title: Encrypted content + description: Opaque encrypted content that Responses API decrypts inside trusted model execution. + x-oai-beta: responses_multi_agent=v1 + BetaInputImageContentParamAutoParam: + properties: + type: + type: string + enum: + - input_image + description: The type of the input item. Always `input_image`. + default: input_image + x-stainless-const: true + image_url: + anyOf: + - type: string + maxLength: 20971520 + format: uri + description: The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - type: 'null' + file_id: + anyOf: + - type: string + description: The ID of the file to be sent to the model. + example: file-123 + - type: 'null' + detail: + anyOf: + - $ref: '#/components/schemas/BetaDetailEnum' + description: The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - type: 'null' + prompt_cache_breakpoint: + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' + - type: 'null' + type: object + required: + - type + title: Input image + description: An image input to the model. Learn about [image inputs](https://developers.openai.com/api/docs/guides/images-vision) + BetaPromptCacheBreakpointParam: + properties: + mode: + type: string + enum: + - explicit + description: The breakpoint mode. Always `explicit`. + default: explicit + x-stainless-const: true + type: object + required: + - mode + title: Prompt cache breakpoint + description: Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + BetaDetailEnum: + type: string + enum: + - low + - high + - auto + - original + BetaInputTextContentParam: + properties: + type: + type: string + enum: + - input_text + description: The type of the input item. Always `input_text`. + default: input_text + x-stainless-const: true + text: + type: string + maxLength: 10485760 + description: The text input to the model. + prompt_cache_breakpoint: + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' + - type: 'null' + type: object + required: + - type + - text + title: Input text + description: A text input to the model. + BetaFunctionCallOutputItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The unique ID of the function tool call output. Populated when this item is returned via API. + example: fc_123 + - type: 'null' + call_id: + anyOf: + - type: string + maxLength: 64 + minLength: 1 + description: The unique ID of the function tool call generated by the model. + - type: 'null' + type: + type: string + enum: + - function_call_output + description: The type of the function tool call output. Always `function_call_output`. + default: function_call_output + x-stainless-const: true + output: + description: Text, image, or file output of the function tool call. + anyOf: + - type: string + maxLength: 10485760 + description: A JSON string of the output of the function tool call. + - items: + discriminator: + propertyName: type + description: A piece of message content, such as text, an image, or a file. + anyOf: + - $ref: '#/components/schemas/BetaInputTextContentParam' + - $ref: '#/components/schemas/BetaInputImageContentParamAutoParam' + - $ref: '#/components/schemas/BetaInputFileContentParam' + type: array + description: An array of content outputs (text, image, file) for the function tool call. + name: + anyOf: + - type: string + maxLength: 128 + minLength: 1 + description: The name of the tool that produced the output. + - type: 'null' + namespace: + anyOf: + - type: string + maxLength: 64 + minLength: 1 + pattern: ^[a-zA-Z0-9_-]+$ + description: The namespace of the tool that produced the output. + - type: 'null' + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + description: The execution context that produced this tool call. + - type: 'null' + status: + anyOf: + - $ref: '#/components/schemas/BetaFunctionCallItemStatus' + description: The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - type: 'null' + type: object + required: + - type + - output + title: Function tool call output + description: The output of a function tool call. + BetaInputFileContentParam: + properties: + type: + type: string + enum: + - input_file + description: The type of the input item. Always `input_file`. + default: input_file + x-stainless-const: true + file_id: + anyOf: + - type: string + description: The ID of the file to be sent to the model. + example: file-123 + - type: 'null' + filename: + anyOf: + - type: string + description: The name of the file to be sent to the model. + - type: 'null' + file_data: + anyOf: + - type: string + maxLength: 73400320 + description: The base64-encoded data of the file to be sent to the model. + - type: 'null' + file_url: + anyOf: + - type: string + format: uri + description: The URL of the file to be sent to the model. + - type: 'null' + detail: + $ref: '#/components/schemas/BetaFileDetailEnum' + description: The detail level of the file to be sent to the model. Use `auto` to let the system select the detail level; for GPT-5.6 and later models, `auto` uses high-quality rendering, which may increase input token usage. Use `low` for lower-cost rendering, or `high` to render the file at higher quality. Defaults to `auto`. + prompt_cache_breakpoint: + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheBreakpointParam' + - type: 'null' + type: object + required: + - type + title: Input file + description: A file input to the model. + BetaFileDetailEnum: + type: string + enum: + - auto + - low + - high + BetaFunctionToolCall: + type: object + title: Function tool call + description: | + A tool call to run a function. See the + [function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + id: + type: string + description: | + The unique ID of the function tool call. + type: + type: string + enum: + - function_call + description: | + The type of the function tool call. Always `function_call`. + x-stainless-const: true + call_id: + type: string + description: | + The unique ID of the function tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + - type: 'null' + namespace: + type: string + description: | + The namespace of the function to run. + name: + type: string + description: | + The name of the function to run. + arguments: + type: string + description: | + A JSON string of the arguments to pass to the function. + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + async: + type: boolean + description: | + Whether the function tool call runs asynchronously. + required: + - type + - call_id + - name + - arguments + BetaWebSearchToolCall: + type: object + title: Web search tool call + description: | + The results of a web search tool call. See the + [web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + id: + type: string + description: | + The unique ID of the web search tool call. + type: + type: string + enum: + - web_search_call + description: | + The type of the web search tool call. Always `web_search_call`. + x-stainless-const: true + status: + description: | + The status of the web search tool call. + $ref: '#/components/schemas/BetaWebSearchCallStatus' + action: + type: object + description: | + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaWebSearchActionSearch' + - $ref: '#/components/schemas/BetaWebSearchActionOpenPage' + - $ref: '#/components/schemas/BetaWebSearchActionFind' + required: + - id + - type + - status + - action + BetaWebSearchActionFind: + type: object + title: Find action + description: | + Action type "find_in_page": Searches for a pattern within a loaded page. + properties: + type: + type: string + enum: + - find_in_page + description: | + The action type. + x-stainless-const: true + url: + type: string + format: uri + description: | + The URL of the page searched for the pattern. + pattern: + type: string + description: | + The pattern or text to search for within the page. + required: + - type + - url + - pattern + BetaWebSearchActionOpenPage: + type: object + title: Open page action + description: | + Action type "open_page" - Opens a specific URL from search results. + properties: + type: + type: string + enum: + - open_page + description: | + The action type. + x-stainless-const: true + url: + description: | + The URL opened by the model. + anyOf: + - type: string + format: uri + - type: 'null' + required: + - type + BetaWebSearchActionSearch: + type: object + title: Search action + description: | + Action type "search" - Performs a web search query. + properties: + type: + type: string + enum: + - search + description: | + The action type. + x-stainless-const: true + query: + type: string + deprecated: true + description: | + The search query. + queries: + type: array + title: Search queries + description: | + The search queries. + items: + type: string + description: | + A search query. + sources: + type: array + title: Web search sources + description: | + The sources used in the search. + items: + type: object + title: Web search source + description: | + A source used in the search. + properties: + type: + type: string + enum: + - url + description: | + The type of source. Always `url`. + x-stainless-const: true + url: + type: string + format: uri + description: | + The URL of the source. + required: + - type + - url + required: + - type + BetaWebSearchCallStatus: + type: string + enum: + - in_progress + - searching + - completed + - failed + - incomplete + BetaComputerCallOutputItemParam: + properties: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: + anyOf: + - type: string + description: The ID of the computer tool call output. + example: cuo_123 + - type: 'null' + call_id: + type: string + maxLength: 64 + minLength: 1 + description: The ID of the computer tool call that produced the output. + type: + type: string + enum: + - computer_call_output + description: The type of the computer tool call output. Always `computer_call_output`. + default: computer_call_output + x-stainless-const: true + output: + $ref: '#/components/schemas/BetaComputerScreenshotImage' + acknowledged_safety_checks: + anyOf: + - items: + $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' + type: array + description: The safety checks reported by the API that have been acknowledged by the developer. + - type: 'null' + status: + anyOf: + - $ref: '#/components/schemas/BetaFunctionCallItemStatus' + description: The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - type: 'null' + type: object + required: + - call_id + - type + - output + title: Computer tool call output + description: The output of a computer tool call. + BetaComputerCallSafetyCheckParam: + properties: + id: + type: string + description: The ID of the pending safety check. + code: + anyOf: + - type: string + description: The type of the pending safety check. + - type: 'null' + message: + anyOf: + - type: string + description: Details about the pending safety check. + - type: 'null' + type: object + required: + - id + description: A pending safety check for the computer call. + BetaComputerScreenshotImage: + type: object + description: | + A computer screenshot image used with the computer use tool. + properties: + type: + type: string + enum: + - computer_screenshot + default: computer_screenshot + description: "Specifies the event type. For a computer screenshot, this property is \nalways set to `computer_screenshot`.\n" + x-stainless-const: true + image_url: + type: string + format: uri + description: The URL of the screenshot image. + file_id: + type: string + description: The identifier of an uploaded file that contains the screenshot. + required: + - type + BetaComputerToolCall: + type: object + title: Computer tool call + description: | + A tool call to a computer use tool. See the + [computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for more information. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + type: + type: string + description: The type of the computer call. Always `computer_call`. + enum: + - computer_call + default: computer_call + id: + type: string + description: The unique ID of the computer call. + call_id: + type: string + description: | + An identifier used when responding to the tool call with output. + action: + $ref: '#/components/schemas/BetaComputerAction' + actions: + $ref: '#/components/schemas/BetaComputerActionList' + pending_safety_checks: + type: array + items: + $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' + description: | + The pending safety checks for the computer call. + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - type + - id + - call_id + - pending_safety_checks + - status + BetaComputerActionList: + title: Computer Action List + type: array + description: | + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + items: + $ref: '#/components/schemas/BetaComputerAction' + BetaComputerAction: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaClickParam' + - $ref: '#/components/schemas/BetaDoubleClickAction' + - $ref: '#/components/schemas/BetaDragParam' + - $ref: '#/components/schemas/BetaKeyPressAction' + - $ref: '#/components/schemas/BetaMoveParam' + - $ref: '#/components/schemas/BetaScreenshotParam' + - $ref: '#/components/schemas/BetaScrollParam' + - $ref: '#/components/schemas/BetaTypeParam' + - $ref: '#/components/schemas/BetaWaitParam' + BetaWaitParam: + properties: + type: + type: string + enum: + - wait + description: Specifies the event type. For a wait action, this property is always set to `wait`. + default: wait + x-stainless-const: true + type: object + required: + - type + title: Wait + description: A wait action. + BetaTypeParam: + properties: + type: + type: string + enum: + - type + description: Specifies the event type. For a type action, this property is always set to `type`. + default: type + x-stainless-const: true + text: + type: string + description: The text to type. + type: object + required: + - type + - text + title: Type + description: An action to type in text. + BetaScrollParam: + properties: + type: + type: string + enum: + - scroll + description: Specifies the event type. For a scroll action, this property is always set to `scroll`. + default: scroll + x-stainless-const: true + x: + type: integer + description: The x-coordinate where the scroll occurred. + y: + type: integer + description: The y-coordinate where the scroll occurred. + scroll_x: + type: integer + description: The horizontal scroll distance. + scroll_y: + type: integer + description: The vertical scroll distance. + keys: + anyOf: + - items: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWebSearchCallInWsProgress - description: Emitted when a web search call is initiated. - allOf: - - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' - - type: object - properties: - stream_id: + type: array + description: The keys being held while scrolling. + - type: 'null' + type: object + required: + - type + - x + - y + - scroll_x + - scroll_y + title: Scroll + description: A scroll action. + BetaScreenshotParam: + properties: + type: + type: string + enum: + - screenshot + description: Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + default: screenshot + x-stainless-const: true + type: object + required: + - type + title: Screenshot + description: A screenshot action. + BetaMoveParam: + properties: + type: + type: string + enum: + - move + description: Specifies the event type. For a move action, this property is always set to `move`. + default: move + x-stainless-const: true + x: + type: integer + description: The x-coordinate to move to. + y: + type: integer + description: The y-coordinate to move to. + keys: + anyOf: + - items: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWebSearchCallWsSearching - description: Emitted when a web search call is executing. - allOf: - - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' - - type: object - properties: - stream_id: + type: array + description: The keys being held while moving the mouse. + - type: 'null' + type: object + required: + - type + - x + - y + title: Move + description: A mouse move action. + BetaKeyPressAction: + properties: + type: + type: string + enum: + - keypress + description: Specifies the event type. For a keypress action, this property is always set to `keypress`. + default: keypress + x-stainless-const: true + keys: + items: + type: string + description: One of the keys the model is requesting to be pressed. + type: array + description: The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + type: object + required: + - type + - keys + title: KeyPress + description: A collection of keypresses the model would like to perform. + BetaDragParam: + properties: + type: + type: string + enum: + - drag + description: Specifies the event type. For a drag action, this property is always set to `drag`. + default: drag + x-stainless-const: true + path: + items: + $ref: '#/components/schemas/BetaCoordParam' + type: array + description: |- + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + keys: + anyOf: + - items: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseImageGenCallWsCompleted - description: | - Emitted when an image generation tool call has completed and the final image is available. - allOf: - - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' - - type: object - properties: - stream_id: + type: array + description: The keys being held while dragging the mouse. + - type: 'null' + type: object + required: + - type + - path + title: Drag + description: A drag action. + BetaCoordParam: + properties: + x: + type: integer + description: The x-coordinate. + y: + type: integer + description: The y-coordinate. + type: object + required: + - x + - y + title: Coordinate + description: 'An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.' + BetaDoubleClickAction: + properties: + type: + type: string + enum: + - double_click + description: Specifies the event type. For a double click action, this property is always set to `double_click`. + default: double_click + x-stainless-const: true + x: + type: integer + description: The x-coordinate where the double click occurred. + y: + type: integer + description: The y-coordinate where the double click occurred. + keys: + anyOf: + - items: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseImageGenCallWsGenerating - description: | - Emitted when an image generation tool call is actively generating an image (intermediate state). - allOf: - - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' - - type: object - properties: - stream_id: + type: array + description: The keys being held while double-clicking. + - type: 'null' + type: object + required: + - type + - x + - y + - keys + title: DoubleClick + description: A double click action. + BetaClickParam: + properties: + type: + type: string + enum: + - click + description: Specifies the event type. For a click action, this property is always `click`. + default: click + x-stainless-const: true + button: + $ref: '#/components/schemas/BetaClickButtonType' + description: Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + x: + type: integer + description: The x-coordinate where the click occurred. + y: + type: integer + description: The y-coordinate where the click occurred. + keys: + anyOf: + - items: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseImageGenCallInWsProgress + type: array + description: The keys being held while clicking. + - type: 'null' + type: object + required: + - type + - button + - x + - y + title: Click + description: A click action. + BetaClickButtonType: + type: string + enum: + - left + - right + - wheel + - back + - forward + BetaFileSearchToolCall: + type: object + title: File search tool call + description: | + The results of a file search tool call. See the + [file search guide](https://developers.openai.com/api/docs/guides/tools-file-search) for more information. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + id: + type: string + description: | + The unique ID of the file search tool call. + type: + type: string + enum: + - file_search_call + description: | + The type of the file search tool call. Always `file_search_call`. + x-stainless-const: true + status: + type: string + description: | + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, + enum: + - in_progress + - searching + - completed + - incomplete + - failed + queries: + type: array + items: + type: string + description: | + The queries used to search for files. + results: + anyOf: + - type: array + description: | + The results of the file search tool call. + items: + type: object + properties: + file_id: + type: string + description: | + The unique ID of the file. + text: + type: string + description: | + The text that was retrieved from the file. + filename: + type: string + description: | + The name of the file. + attributes: + $ref: '#/components/schemas/BetaVectorStoreFileAttributes' + score: + type: number + format: float + description: | + The relevance score of the file - a value between 0 and 1. + - type: 'null' + required: + - id + - type + - status + - queries + BetaVectorStoreFileAttributes: + anyOf: + - type: object description: | - Emitted when an image generation tool call is in progress. - allOf: - - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' - - type: object + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. + maxProperties: 16 + propertyNames: + type: string + maxLength: 64 + additionalProperties: + anyOf: + - type: string + maxLength: 512 + - type: number + - type: boolean + x-oaiTypeLabel: map + - type: 'null' + BetaOutputMessage: + type: object + title: Output message + description: | + An output message from the model. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + id: + type: string + description: | + The unique ID of the output message. + x-stainless-go-json: omitzero + type: + type: string + description: | + The type of the output message. Always `message`. + enum: + - message + x-stainless-const: true + role: + type: string + description: | + The role of the output message. Always `assistant`. + enum: + - assistant + x-stainless-const: true + content: + type: array + description: | + The content of the output message. + items: + $ref: '#/components/schemas/BetaOutputMessageContent' + phase: + anyOf: + - $ref: '#/components/schemas/BetaMessagePhase' + - type: 'null' + status: + type: string + description: | + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - id + - type + - role + - content + - status + BetaMessagePhase: + type: string + description: | + 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. + enum: + - commentary + - final_answer + BetaOutputMessageContent: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaOutputTextContent' + - $ref: '#/components/schemas/BetaRefusalContent' + BetaRefusalContent: + properties: + type: + type: string + enum: + - refusal + description: The type of the refusal. Always `refusal`. + default: refusal + x-stainless-const: true + refusal: + type: string + description: The refusal explanation from the model. + type: object + required: + - type + - refusal + title: Refusal + description: A refusal from the model. + BetaOutputTextContent: + properties: + type: + type: string + enum: + - output_text + description: The type of the output text. Always `output_text`. + default: output_text + x-stainless-const: true + text: + type: string + description: The text output from the model. + annotations: + items: + $ref: '#/components/schemas/BetaAnnotation' + type: array + description: The annotations of the text output. + logprobs: + items: + $ref: '#/components/schemas/BetaLogProb' + type: array + type: object + required: + - type + - text + - annotations + title: Output text + description: A text output from the model. + BetaLogProb: + properties: + token: + type: string + logprob: + type: number + bytes: + items: + type: integer + type: array + top_logprobs: + items: + $ref: '#/components/schemas/BetaTopLogProb' + type: array + type: object + required: + - token + - logprob + - bytes + - top_logprobs + title: Log probability + description: The log probability of a token. + BetaTopLogProb: + properties: + token: + type: string + logprob: + type: number + bytes: + items: + type: integer + type: array + type: object + required: + - token + - logprob + - bytes + title: Top log probability + description: The top log probability of a token. + BetaAnnotation: + discriminator: + propertyName: type + description: An annotation that applies to a span of output text. + anyOf: + - $ref: '#/components/schemas/BetaFileCitationBody' + - $ref: '#/components/schemas/BetaUrlCitationBody' + - $ref: '#/components/schemas/BetaContainerFileCitationBody' + - $ref: '#/components/schemas/BetaFilePath' + BetaFilePath: + type: object + title: File path + description: | + A path to a file. + properties: + type: + type: string + description: | + The type of the file path. Always `file_path`. + enum: + - file_path + x-stainless-const: true + file_id: + type: string + description: | + The ID of the file. + index: + type: integer + description: | + The index of the file in the list of files. + required: + - type + - file_id + - index + BetaContainerFileCitationBody: + properties: + type: + type: string + enum: + - container_file_citation + description: The type of the container file citation. Always `container_file_citation`. + default: container_file_citation + x-stainless-const: true + container_id: + type: string + description: The ID of the container file. + file_id: + type: string + description: The ID of the file. + start_index: + type: integer + description: The index of the first character of the container file citation in the message. + end_index: + type: integer + description: The index of the last character of the container file citation in the message. + filename: + type: string + description: The filename of the container file cited. + type: object + required: + - type + - container_id + - file_id + - start_index + - end_index + - filename + title: Container file citation + description: A citation for a container file used to generate a model response. + BetaUrlCitationBody: + properties: + type: + type: string + enum: + - url_citation + description: The type of the URL citation. Always `url_citation`. + default: url_citation + x-stainless-const: true + url: + type: string + format: uri + description: The URL of the web resource. + start_index: + type: integer + description: The index of the first character of the URL citation in the message. + end_index: + type: integer + description: The index of the last character of the URL citation in the message. + title: + type: string + description: The title of the web resource. + type: object + required: + - type + - url + - start_index + - end_index + - title + title: URL citation + description: A citation for a web resource used to generate a model response. + BetaFileCitationBody: + properties: + type: + type: string + enum: + - file_citation + description: The type of the file citation. Always `file_citation`. + default: file_citation + x-stainless-const: true + file_id: + type: string + description: The ID of the file. + index: + type: integer + description: The index of the file in the list of files. + filename: + type: string + description: The filename of the file cited. + type: object + required: + - type + - file_id + - index + - filename + title: File citation + description: A citation to a file. + BetaInputMessage: + type: object + title: Input message + description: | + 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. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + type: + type: string + description: | + The type of the message input. Always set to `message`. + enum: + - message + x-stainless-const: true + role: + type: string + description: | + The role of the message input. One of `user`, `system`, or `developer`. + enum: + - user + - system + - developer + status: + type: string + description: | + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + content: + $ref: '#/components/schemas/BetaInputMessageContentList' + required: + - role + - content + BetaInputMessageContentList: + type: array + title: Input item content list + description: "A list of one or many input items to the model, containing different content \ntypes.\n" + items: + $ref: '#/components/schemas/BetaInputContent' + BetaInputContent: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaInputTextContent' + - $ref: '#/components/schemas/BetaInputImageContent' + - $ref: '#/components/schemas/BetaInputFileContent' + BetaEasyInputMessage: + type: object + title: Input message + description: | + 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. + properties: + role: + type: string + description: | + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. + enum: + - user + - assistant + - system + - developer + content: + description: | + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + anyOf: + - type: string + title: Text input + description: | + A text input to the model. + - $ref: '#/components/schemas/BetaInputMessageContentList' + phase: + anyOf: + - $ref: '#/components/schemas/BetaMessagePhase' + - type: 'null' + type: + type: string + description: | + The type of the message input. Always `message`. + enum: + - message + x-stainless-const: true + required: + - role + - content + BetaCompactResponseMethodPublicBody: + properties: + model: + $ref: '#/components/schemas/BetaModelIdsCompaction' + input: + anyOf: + - description: Text, image, or file inputs to the model, used to generate a response + anyOf: + - type: string + maxLength: 10485760 + description: A text input to the model, equivalent to a text input with the `user` role. + - items: + $ref: '#/components/schemas/BetaInputItem' + type: array + maxItems: 131072 + description: A list of one or many input items to the model, containing different content types. + - type: 'null' + previous_response_id: + anyOf: + - type: string + description: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + example: resp_123 + - type: 'null' + instructions: + anyOf: + - type: string + description: |- + A system (or developer) message inserted into the model's context. + When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. + - type: 'null' + prompt_cache_key: + anyOf: + - type: string + maxLength: 64 + description: A key to use when reading from or writing to the prompt cache. + - type: 'null' + prompt_cache_retention: + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheRetentionEnum' + description: How long to retain a prompt cache entry created by this request. + deprecated: true + - type: 'null' + prompt_cache_options: + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheOptionsParam' + - type: 'null' + service_tier: + anyOf: + - $ref: '#/components/schemas/BetaServiceTierEnum' + description: |- + Specifies the processing type used for serving the request. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - If set to '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier. - To opt-in to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. For models with a dedicated Fast tier, either value resolves to `service_tier=fast`; for other models, either value resolves to `service_tier=priority`. - When not set, the default behavior is 'auto'. + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + - type: 'null' + type: object + required: + - model + BetaServiceTierEnum: + type: string + enum: + - auto + - default + - fast + - flex + - priority + BetaPromptCacheOptionsParam: + properties: + ttl: + $ref: '#/components/schemas/BetaPromptCacheTTLEnum' + description: The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. + mode: + $ref: '#/components/schemas/BetaPromptCacheModeEnum' + description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. + type: object + required: [] + title: Prompt cache options + description: Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for current details. + BetaPromptCacheModeEnum: + type: string + enum: + - implicit + - explicit + BetaPromptCacheTTLEnum: + type: string + enum: + - 30m + BetaPromptCacheRetentionEnum: + type: string + enum: + - in_memory + - 24h + BetaModelIdsCompaction: + anyOf: + - $ref: '#/components/schemas/BetaModelIdsResponses' + - type: string + - type: 'null' + description: Model ID used to generate the response, like `gpt-6-astra`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models. + BetaModelIdsResponses: + example: gpt-6-astra + anyOf: + - $ref: '#/components/schemas/BetaModelIdsShared' + - type: string + title: ResponsesOnlyModel + enum: + - o1-pro + - o1-pro-2025-03-19 + - o3-pro + - o3-pro-2025-06-10 + - o3-deep-research + - o3-deep-research-2025-06-26 + - o4-mini-deep-research + - o4-mini-deep-research-2025-06-26 + - computer-use-preview + - computer-use-preview-2025-03-11 + - gpt-5.5-pro + - gpt-5.5-pro-2026-04-23 + - gpt-5-codex + - gpt-5-pro + - gpt-5-pro-2025-10-06 + - gpt-5.1-codex-max + - gpt-daybreak-blue-latest + - gpt-daybreak-red-latest + - gpt-5.6-cyber + BetaModelIdsShared: + example: gpt-6-astra + anyOf: + - type: string + - $ref: '#/components/schemas/ChatModel' + BetaError: + type: object + properties: + code: + anyOf: + - type: string + - type: 'null' + message: + type: string + param: + anyOf: + - type: string + - type: 'null' + type: + type: string + misalignment: + $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' + required: + - type + - message + - param + - code + BetaMisalignmentErrorDetailsResource: + properties: + error_type: + $ref: '#/components/schemas/Beta_MisalignmentErrorType' + description: An optional classification; clients must accept additional values. + detailed_explanation: + type: string + description: The public explanation for this block. + steer: + $ref: '#/components/schemas/Beta_MisalignmentSteer' + description: An optional public continuation instruction. + type: object + required: [] + Beta_MisalignmentSteer: + properties: + message: + type: string + description: The public continuation instruction. + type: object + required: + - message + Beta_MisalignmentErrorType: + anyOf: + - type: string + - type: string + enum: + - potentially_unintended_data_transfer + - potentially_unintended_data_access + - potentially_unintended_destructive_activity + - other + BetaResponseItemList: + type: object + description: A list of Response items. + properties: + object: + x-stainless-const: true + description: The type of object returned, must be `list`. + const: list + data: + type: array + description: A list of items used to generate this response. + items: + $ref: '#/components/schemas/BetaItemResource' + has_more: + type: boolean + description: Whether there are more items available. + first_id: + type: string + description: The ID of the first item in the list. + last_id: + type: string + description: The ID of the last item in the list. + required: + - object + - data + - has_more + - first_id + - last_id + x-oaiMeta: + name: The input item list + group: responses + example: | + { + "object": "list", + "data": [ + { + "id": "msg_abc123", + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Tell me a three sentence bedtime story about a unicorn." + } + ] + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc123", + "has_more": false + } + BetaItemResource: + description: | + Content item used to generate a response. + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaInputMessageResource' + - $ref: '#/components/schemas/BetaOutputMessage' + - $ref: '#/components/schemas/BetaFileSearchToolCall' + - $ref: '#/components/schemas/BetaComputerToolCall' + - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' + - $ref: '#/components/schemas/BetaWebSearchToolCall' + - $ref: '#/components/schemas/BetaFunctionToolCallResource' + - $ref: '#/components/schemas/BetaFunctionToolCallOutputResource' + - $ref: '#/components/schemas/BetaAgentMessage' + - $ref: '#/components/schemas/BetaMultiAgentCall' + - $ref: '#/components/schemas/BetaMultiAgentCallOutput' + - $ref: '#/components/schemas/BetaToolSearchCall' + - $ref: '#/components/schemas/BetaToolSearchOutput' + - $ref: '#/components/schemas/BetaAdditionalTools' + - $ref: '#/components/schemas/BetaResponseConfigurationUpdate' + - $ref: '#/components/schemas/BetaReasoningItem' + - $ref: '#/components/schemas/BetaProgram' + - $ref: '#/components/schemas/BetaProgramOutput' + - $ref: '#/components/schemas/BetaCompactionBody' + - $ref: '#/components/schemas/BetaImageGenToolCall' + - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' + - $ref: '#/components/schemas/BetaFunctionShellCall' + - $ref: '#/components/schemas/BetaFunctionShellCallOutput' + - $ref: '#/components/schemas/BetaApplyPatchToolCall' + - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' + - $ref: '#/components/schemas/BetaMCPListTools' + - $ref: '#/components/schemas/BetaMCPApprovalRequest' + - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' + - $ref: '#/components/schemas/BetaMCPToolCall' + - $ref: '#/components/schemas/BetaCustomToolCallResource' + - $ref: '#/components/schemas/BetaCustomToolCallOutputResource' + BetaCustomToolCallOutputResource: + title: ResponseCustomToolCallOutputItem + allOf: + - $ref: '#/components/schemas/BetaCustomToolCallOutput' + - type: object + properties: + id: + type: string + description: | + The unique ID of the custom tool call output item. + status: + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' + created_by: + type: string + description: | + The identifier of the actor that created the item. + required: + - id + - status + BetaFunctionCallOutputStatusEnum: + type: string + enum: + - in_progress + - completed + - incomplete + BetaCustomToolCallResource: + title: ResponseCustomToolCallItem + allOf: + - $ref: '#/components/schemas/BetaCustomToolCall' + - type: object + properties: + id: + type: string + description: | + The unique ID of the custom tool call item. + status: + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + $ref: '#/components/schemas/BetaFunctionCallStatus' + created_by: + type: string + description: | + The identifier of the actor that created the item. + required: + - id + - status + BetaFunctionCallStatus: + type: string + enum: + - in_progress + - completed + - incomplete + BetaMCPApprovalResponseResource: + type: object + title: MCP approval response + description: | + A response to an MCP approval request. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + type: + type: string + enum: + - mcp_approval_response + description: | + The type of the item. Always `mcp_approval_response`. + x-stainless-const: true + id: + type: string + description: | + The unique ID of the approval response + approval_request_id: + type: string + description: | + The ID of the approval request being answered. + approve: + type: boolean + description: | + Whether the request was approved. + reason: + anyOf: + - type: string + description: | + Optional reason for the decision. + - type: 'null' + required: + - type + - id + - request_id + - approve + - approval_request_id + BetaApplyPatchToolCallOutput: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - apply_patch_call_output + description: The type of the item. Always `apply_patch_call_output`. + default: apply_patch_call_output + x-stainless-const: true + id: + type: string + description: The unique ID of the apply patch tool call output. Populated when this item is returned via API. + call_id: + type: string + description: The unique ID of the apply patch tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + description: The execution context that produced this tool call. + - type: 'null' + status: + $ref: '#/components/schemas/BetaApplyPatchCallOutputStatus' + description: The status of the apply patch tool call output. One of `completed` or `failed`. + output: + anyOf: + - type: string + description: Optional textual output returned by the apply patch tool. + - type: 'null' + created_by: + type: string + description: The ID of the entity that created this tool call output. + type: object + required: + - type + - id + - call_id + - status + title: Apply patch tool call output + description: The output emitted by an apply patch tool call. + BetaApplyPatchCallOutputStatus: + type: string + enum: + - completed + - failed + BetaApplyPatchToolCall: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - apply_patch_call + description: The type of the item. Always `apply_patch_call`. + default: apply_patch_call + x-stainless-const: true + id: + type: string + description: The unique ID of the apply patch tool call. Populated when this item is returned via API. + call_id: + type: string + description: The unique ID of the apply patch tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + description: The execution context that produced this tool call. + - type: 'null' + status: + $ref: '#/components/schemas/BetaApplyPatchCallStatus' + description: The status of the apply patch tool call. One of `in_progress` or `completed`. + operation: + discriminator: + propertyName: type + title: Apply patch operation + description: One of the create_file, delete_file, or update_file operations applied via apply_patch. + anyOf: + - $ref: '#/components/schemas/BetaApplyPatchCreateFileOperation' + - $ref: '#/components/schemas/BetaApplyPatchDeleteFileOperation' + - $ref: '#/components/schemas/BetaApplyPatchUpdateFileOperation' + created_by: + type: string + description: The ID of the entity that created this tool call. + type: object + required: + - type + - id + - call_id + - status + - operation + title: Apply patch tool call + description: A tool call that applies file diffs by creating, deleting, or updating files. + BetaApplyPatchUpdateFileOperation: + properties: + type: + type: string + enum: + - update_file + description: Update an existing file with the provided diff. + default: update_file + x-stainless-const: true + path: + type: string + description: Path of the file to update. + diff: + type: string + description: Diff to apply. + type: object + required: + - type + - path + - diff + title: Apply patch update file operation + description: Instruction describing how to update a file via the apply_patch tool. + BetaApplyPatchDeleteFileOperation: + properties: + type: + type: string + enum: + - delete_file + description: Delete the specified file. + default: delete_file + x-stainless-const: true + path: + type: string + description: Path of the file to delete. + type: object + required: + - type + - path + title: Apply patch delete file operation + description: Instruction describing how to delete a file via the apply_patch tool. + BetaApplyPatchCreateFileOperation: + properties: + type: + type: string + enum: + - create_file + description: Create a new file with the provided diff. + default: create_file + x-stainless-const: true + path: + type: string + description: Path of the file to create. + diff: + type: string + description: Diff to apply. + type: object + required: + - type + - path + - diff + title: Apply patch create file operation + description: Instruction describing how to create a file via the apply_patch tool. + BetaApplyPatchCallStatus: + type: string + enum: + - in_progress + - completed + BetaFunctionShellCallOutput: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - shell_call_output + description: The type of the shell call output. Always `shell_call_output`. + default: shell_call_output + x-stainless-const: true + id: + type: string + description: The unique ID of the shell call output. Populated when this item is returned via API. + call_id: + type: string + description: The unique ID of the shell tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + description: The execution context that produced this tool call. + - type: 'null' + status: + $ref: '#/components/schemas/BetaFunctionShellCallOutputStatusEnum' + description: The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + output: + items: + $ref: '#/components/schemas/BetaFunctionShellCallOutputContent' + type: array + description: An array of shell call output contents + max_output_length: + anyOf: + - type: integer + description: The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - type: 'null' + created_by: + type: string + description: The identifier of the actor that created the item. + type: object + required: + - type + - id + - call_id + - status + - output + - max_output_length + title: Shell call output + description: The output of a shell tool call that was emitted. + BetaFunctionShellCallOutputContent: + properties: + stdout: + type: string + description: The standard output that was captured. + stderr: + type: string + description: The standard error output that was captured. + outcome: + discriminator: + propertyName: type + title: Shell call outcome + description: Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + anyOf: + - $ref: '#/components/schemas/BetaFunctionShellCallOutputTimeoutOutcome' + - $ref: '#/components/schemas/BetaFunctionShellCallOutputExitOutcome' + created_by: + type: string + description: The identifier of the actor that created the item. + type: object + required: + - stdout + - stderr + - outcome + title: Shell call output content + description: The content of a shell tool call output that was emitted. + BetaFunctionShellCallOutputExitOutcome: + properties: + type: + type: string + enum: + - exit + description: The outcome type. Always `exit`. + default: exit + x-stainless-const: true + exit_code: + type: integer + description: Exit code from the shell process. + type: object + required: + - type + - exit_code + title: Shell call exit outcome + description: Indicates that the shell commands finished and returned an exit code. + BetaFunctionShellCallOutputTimeoutOutcome: + properties: + type: + type: string + enum: + - timeout + description: The outcome type. Always `timeout`. + default: timeout + x-stainless-const: true + type: object + required: + - type + title: Shell call timeout outcome + description: Indicates that the shell call exceeded its configured time limit. + BetaFunctionShellCallOutputStatusEnum: + type: string + enum: + - in_progress + - completed + - incomplete + BetaFunctionShellCall: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - shell_call + description: The type of the item. Always `shell_call`. + default: shell_call + x-stainless-const: true + id: + type: string + description: The unique ID of the shell tool call. Populated when this item is returned via API. + call_id: + type: string + description: The unique ID of the shell tool call generated by the model. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCaller' + description: The execution context that produced this tool call. + - type: 'null' + action: + $ref: '#/components/schemas/BetaFunctionShellAction' + description: The shell commands and limits that describe how to run the tool call. + status: + $ref: '#/components/schemas/BetaFunctionShellCallStatus' + description: The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + environment: + anyOf: + - discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaLocalEnvironmentResource' + - $ref: '#/components/schemas/BetaContainerReferenceResource' + - type: 'null' + created_by: + type: string + description: The ID of the entity that created this tool call. + type: object + required: + - type + - id + - call_id + - action + - status + - environment + title: Shell tool call + description: A tool call that executes one or more shell commands in a managed environment. + BetaContainerReferenceResource: + properties: + type: + type: string + enum: + - container_reference + description: The environment type. Always `container_reference`. + default: container_reference + x-stainless-const: true + container_id: + type: string + type: object + required: + - type + - container_id + title: Container Reference + description: Represents a container created with /v1/containers. + BetaLocalEnvironmentResource: + properties: + type: + type: string + enum: + - local + description: The environment type. Always `local`. + default: local + x-stainless-const: true + type: object + required: + - type + title: Local Environment + description: Represents the use of a local environment to perform shell actions. + BetaFunctionShellCallStatus: + type: string + enum: + - in_progress + - completed + - incomplete + BetaFunctionShellAction: + properties: + commands: + items: + type: string + description: A list of commands to run. + type: array + timeout_ms: + anyOf: + - type: integer + description: Optional timeout in milliseconds for the commands. + - type: 'null' + max_output_length: + anyOf: + - type: integer + description: Optional maximum number of characters to return from each command. + - type: 'null' + type: object + required: + - commands + - timeout_ms + - max_output_length + title: Shell exec action + description: Execute a shell command. + BetaCompactionBody: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - compaction + description: The type of the item. Always `compaction`. + default: compaction + x-stainless-const: true + id: + type: string + description: The unique ID of the compaction item. + encrypted_content: + type: string + description: The encrypted content that was produced by compaction. + created_by: + type: string + description: The identifier of the actor that created the item. + type: object + required: + - type + - id + - encrypted_content + title: Compaction item + description: A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact). + BetaProgramOutput: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - program_output + description: The type of the item. Always `program_output`. + default: program_output + x-stainless-const: true + id: + type: string + description: The unique ID of the program output item. + call_id: + type: string + description: The call ID of the program item. + result: + type: string + description: The result produced by the program item. + status: + $ref: '#/components/schemas/BetaProgramOutputStatus' + description: The terminal status of the program output item. + type: object + required: + - type + - id + - call_id + - result + - status + BetaProgramOutputStatus: + type: string + enum: + - completed + - incomplete + BetaProgram: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - program + description: The type of the item. Always `program`. + default: program + x-stainless-const: true + id: + type: string + description: The unique ID of the program item. + call_id: + type: string + description: The stable call ID of the program item. + code: + type: string + description: The JavaScript source executed by programmatic tool calling. + fingerprint: + type: string + description: Opaque program replay fingerprint that must be round-tripped. + type: object + required: + - type + - id + - call_id + - code + - fingerprint + BetaResponseConfigurationUpdate: + type: object + description: | + A configuration update that applies to subsequent responses until it is + replaced by another configuration update. + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + id: + type: string + description: The unique ID of the configuration update item. + example: cnfu_123 + type: + type: string + enum: + - configuration_update + description: The item type. Always `configuration_update`. + default: configuration_update + x-stainless-const: true + reasoning: + type: object + description: The reasoning configuration applied by this update. properties: - stream_id: - type: string + effort: + $ref: '#/components/schemas/BetaReasoningEffort' description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseImageGenCallPartialWsImage - description: | - Emitted when a partial image is available during image generation streaming. - allOf: - - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' - - type: object + The reasoning effort used for subsequent responses until another + configuration update replaces it. + required: + - id + - type + BetaAdditionalTools: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - additional_tools + description: The type of the item. Always `additional_tools`. + default: additional_tools + x-stainless-const: true + id: + type: string + description: The unique ID of the additional tools item. + role: + $ref: '#/components/schemas/BetaMessageRole' + description: The role that provided the additional tools. + tools: + items: + $ref: '#/components/schemas/BetaTool' + type: array + description: The additional tool definitions made available at this item. + type: object + required: + - type + - id + - role + - tools + BetaMessageRole: + type: string + enum: + - unknown + - user + - assistant + - system + - critic + - discriminator + - developer + - tool + BetaToolSearchOutput: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - tool_search_output + description: The type of the item. Always `tool_search_output`. + default: tool_search_output + x-stainless-const: true + id: + type: string + description: The unique ID of the tool search output item. + call_id: + anyOf: + - type: string + description: The unique ID of the tool search call generated by the model. + - type: 'null' + execution: + $ref: '#/components/schemas/BetaToolSearchExecutionType' + description: Whether tool search was executed by the server or by the client. + tools: + items: + $ref: '#/components/schemas/BetaTool' + type: array + description: The loaded tool definitions returned by tool search. + status: + $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' + description: The status of the tool search output item that was recorded. + created_by: + type: string + description: The identifier of the actor that created the item. + type: object + required: + - type + - id + - call_id + - execution + - tools + - status + BetaToolSearchCall: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - tool_search_call + description: The type of the item. Always `tool_search_call`. + default: tool_search_call + x-stainless-const: true + id: + type: string + description: The unique ID of the tool search call item. + call_id: + anyOf: + - type: string + description: The unique ID of the tool search call generated by the model. + - type: 'null' + execution: + $ref: '#/components/schemas/BetaToolSearchExecutionType' + description: Whether tool search was executed by the server or by the client. + arguments: + description: Arguments used for the tool search call. + status: + $ref: '#/components/schemas/BetaFunctionCallStatus' + description: The status of the tool search call item that was recorded. + created_by: + type: string + description: The identifier of the actor that created the item. + type: object + required: + - type + - id + - call_id + - execution + - arguments + - status + BetaMultiAgentCallOutput: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - multi_agent_call_output + description: The type of the multi-agent result. Always `multi_agent_call_output`. + default: multi_agent_call_output + x-stainless-const: true + id: + type: string + description: The unique ID of the multi-agent call output item. + call_id: + type: string + description: The unique ID of the multi-agent call. + action: + $ref: '#/components/schemas/BetaMultiAgentAction' + description: The multi-agent action that produced this result. + output: + items: + $ref: '#/components/schemas/BetaOutputTextContent' + type: array + description: Text output returned by the multi-agent action. + type: object + required: + - type + - id + - call_id + - action + - output + x-oai-beta: responses_multi_agent=v1 + BetaMultiAgentAction: + type: string + enum: + - spawn_agent + - interrupt_agent + - list_agents + - send_message + - followup_task + - wait_agent + BetaMultiAgentCall: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - multi_agent_call + description: The type of the multi-agent call. Always `multi_agent_call`. + default: multi_agent_call + x-stainless-const: true + id: + type: string + description: The unique ID of the multi-agent call item. + call_id: + type: string + description: The unique ID linking this call to its output. + action: + $ref: '#/components/schemas/BetaMultiAgentAction' + description: The multi-agent action to execute. + arguments: + type: string + description: The JSON string of arguments generated for the action. + type: object + required: + - type + - id + - call_id + - action + - arguments + x-oai-beta: responses_multi_agent=v1 + BetaAgentMessage: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - agent_message + description: The type of the item. Always `agent_message`. + default: agent_message + x-stainless-const: true + id: + type: string + description: The unique ID of the agent message. + author: + type: string + description: The sending agent identity. + recipient: + type: string + description: The destination agent identity. + content: + items: + discriminator: + propertyName: type + description: A content part that makes up an input or output item. + anyOf: + - $ref: '#/components/schemas/BetaInputTextContent' + - $ref: '#/components/schemas/BetaOutputTextContent' + - $ref: '#/components/schemas/BetaTextContent' + - $ref: '#/components/schemas/BetaSummaryTextContent' + - $ref: '#/components/schemas/BetaReasoningTextContent' + - $ref: '#/components/schemas/BetaRefusalContent' + - $ref: '#/components/schemas/BetaInputImageContent' + - $ref: '#/components/schemas/BetaComputerScreenshotContent' + - $ref: '#/components/schemas/BetaInputFileContent' + - $ref: '#/components/schemas/BetaEncryptedContent' + type: array + description: Encrypted content sent between agents. + type: object + required: + - type + - id + - author + - recipient + - content + x-oai-beta: responses_multi_agent=v1 + BetaEncryptedContent: + properties: + type: + type: string + enum: + - encrypted_content + description: The type of the input item. Always `encrypted_content`. + default: encrypted_content + x-stainless-const: true + encrypted_content: + type: string + description: Opaque encrypted content. + type: object + required: + - type + - encrypted_content + title: Encrypted content + description: Opaque encrypted content that Responses API decrypts inside trusted model execution. + x-oai-beta: responses_multi_agent=v1 + BetaComputerScreenshotContent: + properties: + type: + type: string + enum: + - computer_screenshot + description: Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + default: computer_screenshot + x-stainless-const: true + image_url: + anyOf: + - type: string + format: uri + description: The URL of the screenshot image. + - type: 'null' + file_id: + anyOf: + - type: string + description: The identifier of an uploaded file that contains the screenshot. + - type: 'null' + detail: + $ref: '#/components/schemas/BetaImageDetail' + description: The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + prompt_cache_breakpoint: + $ref: '#/components/schemas/BetaPromptCacheBreakpointConfig' + type: object + required: + - type + - image_url + - file_id + - detail + title: Computer screenshot + description: A screenshot of a computer. + BetaTextContent: + properties: + type: + type: string + enum: + - text + default: text + x-stainless-const: true + text: + type: string + type: object + required: + - type + - text + title: Text Content + description: A text content. + BetaFunctionToolCallOutputResource: + allOf: + - $ref: '#/components/schemas/BetaFunctionToolCallOutput' + - type: object + properties: + id: + type: string + description: | + The unique ID of the function call tool output. + status: + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + $ref: '#/components/schemas/BetaFunctionCallOutputStatusEnum' + created_by: + type: string + description: | + The identifier of the actor that created the item. + required: + - id + - status + BetaFunctionToolCallOutput: + type: object + title: Function tool call output + description: | + The output of a function tool call. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + id: + type: string + description: | + The unique ID of the function tool call output. Populated when this item + is returned via API. + type: + type: string + enum: + - function_call_output + description: | + The type of the function tool call output. Always `function_call_output`. + x-stainless-const: true + call_id: + type: string + description: | + The unique ID of the function tool call generated by the model. + name: + type: string + description: | + The name of the tool that produced the output. + namespace: + type: string + description: | + The namespace of the tool that produced the output. + caller: + anyOf: + - $ref: '#/components/schemas/BetaToolCallCallerParam' + - type: 'null' + output: + description: | + The output from the function call generated by your code. + Can be a string or an list of output content. + anyOf: + - type: string + description: | + A string of the output of the function call. + title: string output + - type: array + items: + $ref: '#/components/schemas/BetaFunctionAndCustomToolCallOutput' + title: output content list + description: | + Text, image, or file output of the function call. + status: + type: string + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - type + - output + BetaFunctionToolCallResource: + allOf: + - $ref: '#/components/schemas/BetaFunctionToolCall' + - type: object + properties: + id: + type: string + description: | + The unique ID of the function tool call. + status: + description: | + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + $ref: '#/components/schemas/BetaFunctionCallStatus' + created_by: + type: string + description: | + The identifier of the actor that created the item. + required: + - id + - status + BetaComputerToolCallOutputResource: + allOf: + - $ref: '#/components/schemas/BetaComputerToolCallOutput' + - type: object + properties: + id: + type: string + description: | + The unique ID of the computer call tool output. + status: + description: | + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + $ref: '#/components/schemas/BetaComputerCallOutputStatus' + created_by: + type: string + description: | + The identifier of the actor that created the item. + required: + - id + - status + BetaComputerCallOutputStatus: + type: string + enum: + - completed + - incomplete + - failed + BetaComputerToolCallOutput: + type: object + title: Computer tool call output + description: | + The output of a computer tool call. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that produced this item. + type: + type: string + description: | + The type of the computer tool call output. Always `computer_call_output`. + enum: + - computer_call_output + default: computer_call_output + x-stainless-const: true + id: + type: string + description: | + The ID of the computer tool call output. + call_id: + type: string + description: | + The ID of the computer tool call that produced the output. + acknowledged_safety_checks: + type: array + description: | + The safety checks reported by the API that have been acknowledged by the + developer. + items: + $ref: '#/components/schemas/BetaComputerCallSafetyCheckParam' + output: + $ref: '#/components/schemas/BetaComputerScreenshotImage' + status: + type: string + description: | + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + enum: + - in_progress + - completed + - incomplete + required: + - type + - call_id + - output + BetaInputMessageResource: + allOf: + - $ref: '#/components/schemas/BetaInputMessage' + - type: object + properties: + id: + type: string + description: | + The unique ID of the message input. + required: + - id + - type + BetaCompactResource: + properties: + id: + type: string + description: The unique identifier for the compacted response. + object: + type: string + enum: + - response.compaction + description: The object type. Always `response.compaction`. + default: response.compaction + x-stainless-const: true + output: + type: array + description: The compacted list of output items. This is a list of all user messages, followed by a single compaction item. + items: + $ref: '#/components/schemas/BetaOutputItem' + created_at: + type: integer + format: unixtime + description: Unix timestamp (in seconds) when the compacted conversation was created. + usage: + $ref: '#/components/schemas/BetaResponseUsage' + description: Token accounting for the compaction pass, including cached, reasoning, and total tokens. + type: object + required: + - id + - object + - output + - created_at + - usage + title: The compacted response object + BetaResponseUsage: + type: object + description: | + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. + properties: + input_tokens: + type: integer + description: The number of input tokens. + input_tokens_details: + type: object + description: A detailed breakdown of the input tokens. properties: - stream_id: - type: string + cached_tokens: + type: integer description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpCallArgumentsWsDelta - description: | - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' - - type: object + The number of tokens that were retrieved from the cache. + [More on prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching). + cache_write_tokens: + type: integer + description: The number of input tokens that were written to the cache. + required: + - cached_tokens + - cache_write_tokens + output_tokens: + type: integer + description: The number of output tokens. + output_tokens_details: + type: object + description: A detailed breakdown of the output tokens. properties: - stream_id: - type: string + reasoning_tokens: + type: integer + description: The number of reasoning tokens. + required: + - reasoning_tokens + total_tokens: + type: integer + description: The total number of tokens used. + required: + - input_tokens + - input_tokens_details + - output_tokens + - output_tokens_details + - total_tokens + BetaItemField: + discriminator: + propertyName: type + description: An item representing a message, tool call, tool output, reasoning, or other response element. + anyOf: + - $ref: '#/components/schemas/BetaMessage' + - $ref: '#/components/schemas/BetaProgram' + - $ref: '#/components/schemas/BetaProgramOutput' + - $ref: '#/components/schemas/BetaFunctionToolCall' + - $ref: '#/components/schemas/BetaMultiAgentCall' + - $ref: '#/components/schemas/BetaMultiAgentCallOutput' + - $ref: '#/components/schemas/BetaToolSearchCall' + - $ref: '#/components/schemas/BetaToolSearchOutput' + - $ref: '#/components/schemas/BetaAdditionalTools' + - $ref: '#/components/schemas/BetaAgentMessage' + - $ref: '#/components/schemas/BetaFunctionToolCallOutput' + - $ref: '#/components/schemas/BetaFileSearchToolCall' + - $ref: '#/components/schemas/BetaWebSearchToolCall' + - $ref: '#/components/schemas/BetaImageGenToolCall' + - $ref: '#/components/schemas/BetaComputerToolCall' + - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' + - $ref: '#/components/schemas/BetaReasoningItem' + - $ref: '#/components/schemas/BetaCompactionBody' + - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCall' + deprecated: true + - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' + deprecated: true + - $ref: '#/components/schemas/BetaFunctionShellCall' + - $ref: '#/components/schemas/BetaFunctionShellCallOutput' + - $ref: '#/components/schemas/BetaApplyPatchToolCall' + - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' + - $ref: '#/components/schemas/BetaMCPListTools' + - $ref: '#/components/schemas/BetaMCPApprovalRequest' + - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' + - $ref: '#/components/schemas/BetaMCPToolCall' + - $ref: '#/components/schemas/BetaCustomToolCall' + - $ref: '#/components/schemas/BetaCustomToolCallOutput' + BetaMessage: + properties: + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that produced this item. + type: + type: string + enum: + - message + description: The type of the message. Always set to `message`. + default: message + x-stainless-const: true + id: + type: string + description: The unique ID of the message. + status: + $ref: '#/components/schemas/BetaMessageStatus' + description: The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + role: + $ref: '#/components/schemas/BetaMessageRole' + description: The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. + content: + items: + discriminator: + propertyName: type + description: A content part that makes up an input or output item. + anyOf: + - $ref: '#/components/schemas/BetaInputTextContent' + - $ref: '#/components/schemas/BetaOutputTextContent' + - $ref: '#/components/schemas/BetaTextContent' + - $ref: '#/components/schemas/BetaSummaryTextContent' + - $ref: '#/components/schemas/BetaReasoningTextContent' + - $ref: '#/components/schemas/BetaRefusalContent' + - $ref: '#/components/schemas/BetaInputImageContent' + - $ref: '#/components/schemas/BetaComputerScreenshotContent' + - $ref: '#/components/schemas/BetaInputFileContent' + - $ref: '#/components/schemas/BetaEncryptedContent' + type: array + description: The content of the message + phase: + anyOf: + - $ref: '#/components/schemas/BetaMessagePhase-2' + description: 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. + - type: 'null' + type: object + required: + - type + - id + - status + - role + - content + title: Message + description: A message to or from the model. + BetaMessagePhase-2: + type: string + enum: + - commentary + - final_answer + BetaMessageStatus: + type: string + enum: + - in_progress + - completed + - incomplete + BetaResponseCustomToolCallInputDoneEvent: + title: ResponseCustomToolCallInputDone + type: object + description: | + Event indicating that input for a custom tool call is complete. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.custom_tool_call_input.done + description: The event type identifier. + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of this event. + output_index: + type: integer + description: The index of the output this event applies to. + item_id: + type: string + description: Unique identifier for the API item associated with this event. + input: + type: string + description: The complete input data for the custom tool call. + required: + - type + - output_index + - item_id + - input + - sequence_number + x-oaiMeta: + name: response.custom_tool_call_input.done + group: responses + example: | + { + "type": "response.custom_tool_call_input.done", + "output_index": 0, + "item_id": "ctc_1234567890abcdef", + "input": "final complete input text" + } + BetaResponseCustomToolCallInputDeltaEvent: + title: ResponseCustomToolCallInputDelta + type: object + description: | + Event representing a delta (partial update) to the input of a custom tool call. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.custom_tool_call_input.delta + description: The event type identifier. + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of this event. + output_index: + type: integer + description: The index of the output this delta applies to. + item_id: + type: string + description: Unique identifier for the API item associated with this event. + delta: + type: string + description: The incremental input data (delta) for the custom tool call. + required: + - type + - output_index + - item_id + - delta + - sequence_number + x-oaiMeta: + name: response.custom_tool_call_input.delta + group: responses + example: | + { + "type": "response.custom_tool_call_input.delta", + "output_index": 0, + "item_id": "ctc_1234567890abcdef", + "delta": "partial input text" + } + BetaResponseQueuedEvent: + type: object + title: ResponseQueuedEvent + description: | + Emitted when a response is queued and waiting to be processed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.queued + description: The type of the event. Always 'response.queued'. + x-stainless-const: true + response: + $ref: '#/components/schemas/BetaResponse' + description: The full response object that is queued. + sequence_number: + type: integer + description: The sequence number for this event. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.queued + group: responses + example: | + { + "type": "response.queued", + "response": { + "id": "res_123", + "status": "queued", + "created_at": "2021-01-01T00:00:00Z", + "updated_at": "2021-01-01T00:00:00Z" + }, + "sequence_number": 1 + } + BetaResponse: + title: The response object + allOf: + - $ref: '#/components/schemas/BetaModelResponseProperties' + - $ref: '#/components/schemas/BetaResponseProperties' + - type: object + properties: + service_tier: + $ref: '#/components/schemas/BetaServiceTierResponses' + truncation: + anyOf: + - type: string description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpCallArgumentsWsDone - description: | - Emitted when the arguments for an MCP tool call are finalized. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' - - type: object - properties: - stream_id: - type: string + The truncation strategy to use for the model response. + - `auto`: If the input to this Response exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window + size for a model, the request will fail with a 400 error. + enum: + - auto + - disabled + default: disabled + - type: 'null' + id: + type: string + description: | + Unique identifier for this Response. + object: + type: string + description: | + The object type of this resource - always set to `response`. + enum: + - response + x-stainless-const: true + status: + type: string + description: | + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + enum: + - completed + - failed + - in_progress + - cancelled + - queued + - incomplete + created_at: + type: number + format: unixtime + description: | + Unix timestamp (in seconds) of when this Response was created. + completed_at: + anyOf: + - type: number + format: unixtime description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpCallWsCompleted - description: | - Emitted when an MCP tool call has completed successfully. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' - - type: object - properties: - stream_id: - type: string + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. + - type: 'null' + error: + $ref: '#/components/schemas/BetaResponseError' + incomplete_details: + anyOf: + - type: object description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpCallWsFailed - description: | - Emitted when an MCP tool call has failed. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' - - type: object - properties: - stream_id: - type: string + Details about why the response is incomplete. + properties: + reason: + type: string + description: | + The reason why the response is incomplete. `steered` means + the response stopped at a safe output boundary after a + WebSocket `response.steer` event. The server can then create + a successor response automatically with the queued input. + enum: + - max_output_tokens + - max_messages + - content_filter + - steered + - type: 'null' + output: + type: array + description: | + An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent + on the model's response. + - Rather than accessing the first item in the `output` array and + assuming it's an `assistant` message with the content generated by + the model, you might consider using the `output_text` property where + supported in SDKs. + items: + $ref: '#/components/schemas/BetaOutputItem' + reasoning: + anyOf: + - $ref: '#/components/schemas/BetaReasoning' + - type: 'null' + instructions: + anyOf: + - description: | + A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple + to swap out system (or developer) messages in new responses. + anyOf: + - type: string + description: | + A text input to the model, equivalent to a text input with the + `developer` role. + - type: array + title: Input item list + description: | + A list of one or many input items to the model, containing + different content types. + items: + $ref: '#/components/schemas/BetaInputItem' + - type: 'null' + output_text: + anyOf: + - type: string description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpCallInWsProgress - description: | - Emitted when an MCP tool call is in progress. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' - - type: object - properties: - stream_id: - type: string + SDK-only convenience property that contains the aggregated text output + from all `output_text` items in the `output` array, if any are present. + Supported in the Python and JavaScript SDKs. + x-oaiSupportedSDKs: + - python + - javascript + - type: 'null' + x-stainless-skip: true + usage: + $ref: '#/components/schemas/BetaResponseUsage' + prompt_cache_options: + $ref: '#/components/schemas/BetaPromptCacheOptions' + prompt_cache_diagnostics: + $ref: '#/components/schemas/BetaPromptCacheDiagnostics' + moderation: + anyOf: + - $ref: '#/components/schemas/BetaModeration' description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpListToolsWsCompleted + Moderation results for the response input and output, if moderated completions were requested. + - type: 'null' + parallel_tool_calls: + type: boolean + description: | + Whether to allow the model to run tool calls in parallel. + default: true + conversation: + anyOf: + - $ref: '#/components/schemas/BetaResponseConversation' + - type: 'null' + max_output_tokens: + anyOf: + - description: | + An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning). + type: integer + - type: 'null' + required: + - id + - object + - created_at + - error + - incomplete_details + - instructions + - model + - tools + - output + - parallel_tool_calls + - metadata + - tool_choice + - temperature + - top_p + BetaResponseConversation: + properties: + id: + type: string + description: The unique ID of the conversation that this response was associated with. + type: object + required: + - id + title: Conversation + description: The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + BetaModeration: + properties: + input: + discriminator: + propertyName: type + description: Moderation for the response input. + anyOf: + - $ref: '#/components/schemas/BetaModerationResultBody' + - $ref: '#/components/schemas/BetaModerationErrorBody' + output: + discriminator: + propertyName: type + description: Moderation for the response output. + anyOf: + - $ref: '#/components/schemas/BetaModerationResultBody' + - $ref: '#/components/schemas/BetaModerationErrorBody' + type: object + required: + - input + - output + title: Moderation + description: Moderation results or errors for the response input and output. + BetaModerationErrorBody: + properties: + type: + type: string + enum: + - error + description: The object type, which was always `error` for moderation failures. + default: error + x-stainless-const: true + code: + type: string + description: The error code. + message: + type: string + description: The error message. + type: object + required: + - type + - code + - message + title: Moderation error + description: An error produced while attempting moderation for the response input or output. + BetaModerationResultBody: + properties: + type: + type: string + enum: + - moderation_result + description: The object type, which was always `moderation_result` for successful moderation results. + default: moderation_result + x-stainless-const: true + model: + type: string + description: The moderation model that produced this result. + flagged: + type: boolean + description: A boolean indicating whether the content was flagged by any category. + categories: + additionalProperties: + type: boolean + type: object + description: A dictionary of moderation categories to booleans, True if the input is flagged under this category. + x-oaiTypeLabel: map + category_scores: + additionalProperties: + type: number + type: object + description: A dictionary of moderation categories to scores. + x-oaiTypeLabel: map + category_applied_input_types: + additionalProperties: + items: + $ref: '#/components/schemas/BetaModerationInputType' + type: array + type: object + description: Which modalities of input are reflected by the score for each category. + x-oaiTypeLabel: map + type: object + required: + - type + - model + - flagged + - categories + - category_scores + - category_applied_input_types + title: Moderation result + description: A moderation result produced for the response input or output. + BetaModerationInputType: + type: string + enum: + - text + - image + BetaPromptCacheDiagnostics: + discriminator: + propertyName: type + description: Prompt cache diagnostics requested for this response. + anyOf: + - $ref: '#/components/schemas/BetaPromptCacheMissDiagnosticsBody' + - $ref: '#/components/schemas/BetaPromptCacheHitDiagnosticsBody' + - $ref: '#/components/schemas/BetaPromptCacheComparisonResponseNotFoundDiagnosticsBody' + - $ref: '#/components/schemas/BetaPromptCacheUnavailableDiagnosticsBody' + BetaPromptCacheUnavailableDiagnosticsBody: + properties: + type: + type: string + enum: + - unavailable + default: unavailable + x-stainless-const: true + type: object + required: + - type + BetaPromptCacheComparisonResponseNotFoundDiagnosticsBody: + properties: + type: + type: string + enum: + - comparison_response_not_found + default: comparison_response_not_found + x-stainless-const: true + type: object + required: + - type + BetaPromptCacheHitDiagnosticsBody: + properties: + type: + type: string + enum: + - cache_hit + default: cache_hit + x-stainless-const: true + type: object + required: + - type + BetaPromptCacheMissDiagnosticsBody: + properties: + type: + type: string + enum: + - cache_miss + default: cache_miss + x-stainless-const: true + reason: + $ref: '#/components/schemas/BetaCacheMissReasonTypeEnum' + description: The reason prompt cache reuse did not occur. + cache_missed_tokens: + type: integer + description: The estimated number of input tokens affected after the first detected divergence. + comparison_reusable_tokens: + type: integer + description: The raw token count of the reusable prefix in the compared response. + type: object + required: + - type + - reason + - cache_missed_tokens + BetaCacheMissReasonTypeEnum: + type: string + enum: + - model_changed + - prompt_cache_key_changed + - tools_changed + - text_format_changed + - reasoning_effort_changed + - verbosity_changed + - context_compacted + - input_changed + - service_tier_changed + BetaPromptCacheOptions: + properties: + ttl: + $ref: '#/components/schemas/BetaPromptCacheTTLEnum' + description: The minimum lifetime applied to each cache breakpoint. + mode: + $ref: '#/components/schemas/BetaPromptCacheModeEnum' + description: Whether implicit prompt-cache breakpoints were enabled. + comparison_response_id: + anyOf: + - type: string + description: The response ID supplied as the prompt cache diagnostics comparison. + - type: 'null' + type: object + required: + - ttl + - mode + title: Prompt cache options + description: The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + BetaOutputItem: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaOutputMessage' + - $ref: '#/components/schemas/BetaFileSearchToolCall' + - $ref: '#/components/schemas/BetaFunctionToolCall' + - $ref: '#/components/schemas/BetaFunctionToolCallOutputResource' + - $ref: '#/components/schemas/BetaAgentMessage' + - $ref: '#/components/schemas/BetaMultiAgentCall' + - $ref: '#/components/schemas/BetaMultiAgentCallOutput' + - $ref: '#/components/schemas/BetaWebSearchToolCall' + - $ref: '#/components/schemas/BetaComputerToolCall' + - $ref: '#/components/schemas/BetaComputerToolCallOutputResource' + - $ref: '#/components/schemas/BetaReasoningItem' + - $ref: '#/components/schemas/BetaProgram' + - $ref: '#/components/schemas/BetaProgramOutput' + - $ref: '#/components/schemas/BetaToolSearchCall' + - $ref: '#/components/schemas/BetaToolSearchOutput' + - $ref: '#/components/schemas/BetaAdditionalTools' + - $ref: '#/components/schemas/BetaCompactionBody' + - $ref: '#/components/schemas/BetaImageGenToolCall' + - $ref: '#/components/schemas/BetaCodeInterpreterToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCall' + - $ref: '#/components/schemas/BetaLocalShellToolCallOutput' + - $ref: '#/components/schemas/BetaFunctionShellCall' + - $ref: '#/components/schemas/BetaFunctionShellCallOutput' + - $ref: '#/components/schemas/BetaApplyPatchToolCall' + - $ref: '#/components/schemas/BetaApplyPatchToolCallOutput' + - $ref: '#/components/schemas/BetaMCPToolCall' + - $ref: '#/components/schemas/BetaMCPListTools' + - $ref: '#/components/schemas/BetaMCPApprovalRequest' + - $ref: '#/components/schemas/BetaMCPApprovalResponseResource' + - $ref: '#/components/schemas/BetaCustomToolCall' + - $ref: '#/components/schemas/BetaCustomToolCallOutputResource' + BetaResponseError: + anyOf: + - type: object description: | - Emitted when the list of available MCP tools has been successfully retrieved. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpListToolsWsFailed + An error object returned when the model fails to generate a Response. + properties: + code: + $ref: '#/components/schemas/BetaResponseErrorCode' + message: + type: string + description: | + A human-readable description of the error. + misalignment: + $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' + required: + - code + - message + - type: 'null' + BetaResponseErrorCode: + type: string + description: | + The error code for the response. + enum: + - server_error + - rate_limit_exceeded + - invalid_prompt + - data_residency_mismatch + - bio_policy + - misalignment_policy_violation + - 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 + BetaServiceTierResponses: + anyOf: + - type: string description: | - Emitted when the attempt to list available MCP tools has failed. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseMcpListToolsInWsProgress + Specifies the processing type used for serving the request. + - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. + - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. + - If set to '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then the request will be processed with the Flex Processing service tier. + - To opt-in to [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat Completions. The response will show `service_tier=priority` regardless of if you specify `service_tier=fast` or `priority` in your request. + - If set to 'ultrafast', then the request will be processed with the access-controlled Ultrafast Processing service tier. This tier is currently available for `gpt-5.6-sol`; a response served through it will show `service_tier=ultrafast`. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. + enum: + - auto + - default + - flex + - scale + - priority + - fast + - ultrafast + default: auto + - type: 'null' + BetaResponseProperties: + type: object + properties: + previous_response_id: + anyOf: + - type: string + description: | + The unique ID of the previous response to the model. Use this to + create multi-turn conversations. Learn more about + [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. + - type: 'null' + model: + description: | + Model ID used to generate the response, like `gpt-6-astra`. OpenAI + offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) + to browse and compare available models. + $ref: '#/components/schemas/BetaModelIdsResponses' + background: + anyOf: + - type: boolean + description: | + Whether to run the model response in the background. + [Learn more](https://developers.openai.com/api/docs/guides/background). + default: false + - type: 'null' + max_tool_calls: + anyOf: + - description: | + The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. + type: integer + - type: 'null' + text: + $ref: '#/components/schemas/BetaResponseTextParam' + tools: + $ref: '#/components/schemas/BetaToolsArray' + tool_choice: + $ref: '#/components/schemas/BetaToolChoiceParam' + prompt: + $ref: '#/components/schemas/BetaPrompt' + BetaPrompt: + anyOf: + - type: object description: | - Emitted when the system is in the process of retrieving the list of available MCP tools. - allOf: - - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' - - type: object - properties: - stream_id: - type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseOutputTextAnnotationWsAdded + Reference to a prompt template and its variables. + [Learn more](https://developers.openai.com/api/docs/guides/text?api-mode=responses#version-prompts-in-code). + required: + - id + properties: + id: + type: string + description: The unique identifier of the prompt template to use. + version: + anyOf: + - type: string + description: Optional version of the prompt template. + - type: 'null' + variables: + $ref: '#/components/schemas/BetaResponsePromptVariables' + - type: 'null' + BetaResponsePromptVariables: + anyOf: + - type: object + title: Prompt Variables description: | - Emitted when an annotation is added to output text content. - allOf: - - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' - - type: object + Optional map of values to substitute in for variables in your + prompt. The substitution values can either be strings, or other + Response input types like images or files. + x-oaiExpandable: true + x-oaiTypeLabel: map + additionalProperties: + x-oaiExpandable: true + x-oaiTypeLabel: map + anyOf: + - type: string + - $ref: '#/components/schemas/BetaInputTextContent' + - $ref: '#/components/schemas/BetaInputImageContent' + - $ref: '#/components/schemas/BetaInputFileContent' + - type: 'null' + BetaToolsArray: + type: array + description: | + An array of tools the model may call while generating a response. You + can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + - **Built-in tools**: Tools that are provided by OpenAI that extend the + model's capabilities, like [web search](https://developers.openai.com/api/docs/guides/tools-web-search) + or [file search](https://developers.openai.com/api/docs/guides/tools-file-search). Learn more about + [built-in tools](https://developers.openai.com/api/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers + or predefined connectors such as Google Drive and SharePoint. Built-in + connectors using `connector_id` are deprecated for models released after + September 1, 2026. Use `server_url` to connect to a remote MCP server, or + `tunnel_id` to connect through a Secure MCP Tunnel. Learn more about + [MCP Tools](https://developers.openai.com/api/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, + enabling the model to call your own code with strongly typed arguments + and outputs. Learn more about + [function calling](https://developers.openai.com/api/docs/guides/function-calling). You can also use + custom tools to call your own code. + items: + $ref: '#/components/schemas/BetaTool' + BetaModelResponseProperties: + type: object + properties: + metadata: + $ref: '#/components/schemas/BetaMetadata' + top_logprobs: + anyOf: + - description: | + An integer between 0 and 20 specifying the maximum number of most likely + tokens to return at each token position, each with an associated log + probability. In some cases, the number of returned tokens may be fewer than + requested. + type: integer + minimum: 0 + maximum: 20 + - type: 'null' + temperature: + anyOf: + - type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + description: | + What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. + We generally recommend altering this or `top_p` but not both. + - type: 'null' + top_p: + anyOf: + - type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + description: | + An alternative to sampling with temperature, called nucleus sampling, + where the model considers the results of the tokens with top_p probability + mass. So 0.1 means only the tokens comprising the top 10% probability mass + are considered. + + We generally recommend altering this or `temperature` but not both. + - type: 'null' + user: + type: string + example: user-1234 + deprecated: true + description: | + This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. + A stable identifier for your end-users. + Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). + safety_identifier: + anyOf: + - type: string + maxLength: 64 + example: safety-identifier-1234 + description: | + A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. + The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers). + - type: 'null' + prompt_cache_key: + anyOf: + - type: string + example: prompt-cache-key-1234 + description: | + Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching). + - type: 'null' + prompt_cache_retention: + deprecated: true + anyOf: + - type: string + enum: + - in_memory + - 24h + description: | + Deprecated. Use `prompt_cache_options.ttl` instead. + + The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching#prompt-cache-retention). + This field expresses a maximum retention policy, while + `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two + fields are independent and do not interact. + For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported. + + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - type: 'null' + BetaMetadata: + anyOf: + - type: object + description: | + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. + additionalProperties: + type: string + x-oaiTypeLabel: map + - type: 'null' + BetaResponseOutputTextAnnotationAddedEvent: + type: object + title: ResponseOutputTextAnnotationAddedEvent + description: | + Emitted when an annotation is added to output text content. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.output_text.annotation.added + description: The type of the event. Always 'response.output_text.annotation.added'. + x-stainless-const: true + item_id: + type: string + description: The unique identifier of the item to which the annotation is being added. + output_index: + type: integer + description: The index of the output item in the response's output array. + content_index: + type: integer + description: The index of the content part within the output item. + annotation_index: + type: integer + description: The index of the annotation within the content part. + sequence_number: + type: integer + description: The sequence number of this event. + annotation: + anyOf: + - $ref: '#/components/schemas/BetaAnnotation' + - type: 'null' + description: The annotation object being added. (See annotation schema for details.) + required: + - type + - item_id + - output_index + - content_index + - annotation_index + - annotation + - sequence_number + x-oaiMeta: + name: response.output_text.annotation.added + group: responses + example: | + { + "type": "response.output_text.annotation.added", + "item_id": "item-abc", + "output_index": 0, + "content_index": 0, + "annotation_index": 0, + "annotation": { + "type": "file_citation", + "file_id": "file-abc", + "index": 0, + "filename": "example.txt" + }, + "sequence_number": 1 + } + BetaResponseMCPListToolsInProgressEvent: + type: object + title: ResponseMCPListToolsInProgressEvent + description: | + Emitted when the system is in the process of retrieving the list of available MCP tools. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_list_tools.in_progress + description: The type of the event. Always 'response.mcp_list_tools.in_progress'. + x-stainless-const: true + item_id: + type: string + description: The ID of the MCP tool call item that is being processed. + output_index: + type: integer + description: The index of the output item that is being processed. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - sequence_number + x-oaiMeta: + name: response.mcp_list_tools.in_progress + group: responses + example: | + { + "type": "response.mcp_list_tools.in_progress", + "sequence_number": 1, + "output_index": 0, + "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" + } + BetaResponseMCPListToolsFailedEvent: + type: object + title: ResponseMCPListToolsFailedEvent + description: | + Emitted when the attempt to list available MCP tools has failed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_list_tools.failed + description: The type of the event. Always 'response.mcp_list_tools.failed'. + x-stainless-const: true + item_id: + type: string + description: The ID of the MCP tool call item that failed. + output_index: + type: integer + description: The index of the output item that failed. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - sequence_number + x-oaiMeta: + name: response.mcp_list_tools.failed + group: responses + example: | + { + "type": "response.mcp_list_tools.failed", + "sequence_number": 1, + "output_index": 0, + "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" + } + BetaResponseMCPListToolsCompletedEvent: + type: object + title: ResponseMCPListToolsCompletedEvent + description: | + Emitted when the list of available MCP tools has been successfully retrieved. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_list_tools.completed + description: The type of the event. Always 'response.mcp_list_tools.completed'. + x-stainless-const: true + item_id: + type: string + description: The ID of the MCP tool call item that produced this output. + output_index: + type: integer + description: The index of the output item that was processed. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - sequence_number + x-oaiMeta: + name: response.mcp_list_tools.completed + group: responses + example: | + { + "type": "response.mcp_list_tools.completed", + "sequence_number": 1, + "output_index": 0, + "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" + } + BetaResponseMCPCallInProgressEvent: + type: object + title: ResponseMCPCallInProgressEvent + description: | + Emitted when an MCP tool call is in progress. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_call.in_progress + description: The type of the event. Always 'response.mcp_call.in_progress'. + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of this event. + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the MCP tool call item being processed. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.mcp_call.in_progress + group: responses + example: | + { + "type": "response.mcp_call.in_progress", + "sequence_number": 1, + "output_index": 0, + "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90" + } + BetaResponseMCPCallFailedEvent: + type: object + title: ResponseMCPCallFailedEvent + description: | + Emitted when an MCP tool call has failed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_call.failed + description: The type of the event. Always 'response.mcp_call.failed'. + x-stainless-const: true + item_id: + type: string + description: The ID of the MCP tool call item that failed. + output_index: + type: integer + description: The index of the output item that failed. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - sequence_number + x-oaiMeta: + name: response.mcp_call.failed + group: responses + example: | + { + "type": "response.mcp_call.failed", + "sequence_number": 1, + "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90", + "output_index": 0 + } + BetaResponseMCPCallCompletedEvent: + type: object + title: ResponseMCPCallCompletedEvent + description: | + Emitted when an MCP tool call has completed successfully. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_call.completed + description: The type of the event. Always 'response.mcp_call.completed'. + x-stainless-const: true + item_id: + type: string + description: The ID of the MCP tool call item that completed. + output_index: + type: integer + description: The index of the output item that completed. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - sequence_number + x-oaiMeta: + name: response.mcp_call.completed + group: responses + example: | + { + "type": "response.mcp_call.completed", + "sequence_number": 1, + "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90", + "output_index": 0 + } + BetaResponseMCPCallArgumentsDoneEvent: + type: object + title: ResponseMCPCallArgumentsDoneEvent + description: | + Emitted when the arguments for an MCP tool call are finalized. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_call_arguments.done + description: The type of the event. Always 'response.mcp_call_arguments.done'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the MCP tool call item being processed. + arguments: + type: string + description: | + A JSON string containing the finalized arguments for the MCP tool call. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - output_index + - item_id + - arguments + - sequence_number + x-oaiMeta: + name: response.mcp_call_arguments.done + group: responses + example: | + { + "type": "response.mcp_call_arguments.done", + "output_index": 0, + "item_id": "item-abc", + "arguments": "{\"arg1\": \"value1\", \"arg2\": \"value2\"}", + "sequence_number": 1 + } + BetaResponseMCPCallArgumentsDeltaEvent: + type: object + title: ResponseMCPCallArgumentsDeltaEvent + description: | + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.mcp_call_arguments.delta + description: The type of the event. Always 'response.mcp_call_arguments.delta'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the MCP tool call item being processed. + delta: + type: string + description: | + A JSON string containing the partial update to the arguments for the MCP tool call. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - output_index + - item_id + - delta + - sequence_number + x-oaiMeta: + name: response.mcp_call_arguments.delta + group: responses + example: | + { + "type": "response.mcp_call_arguments.delta", + "output_index": 0, + "item_id": "item-abc", + "delta": "{", + "sequence_number": 1 + } + BetaResponseImageGenCallPartialImageEvent: + type: object + title: ResponseImageGenCallPartialImageEvent + description: | + Emitted when a partial image is available during image generation streaming. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.image_generation_call.partial_image + description: The type of the event. Always 'response.image_generation_call.partial_image'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the image generation item being processed. + sequence_number: + type: integer + description: The sequence number of the image generation item being processed. + partial_image_index: + type: integer + description: 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + partial_image_b64: + type: string + description: Base64-encoded partial image data, suitable for rendering as an image. + size: + type: string + description: The image size that was used. + quality: + type: string + description: The image quality that was used. + background: + type: string + description: The background setting that was used. + output_format: + type: string + description: The output format that was used. + required: + - type + - output_index + - item_id + - sequence_number + - partial_image_index + - partial_image_b64 + x-oaiMeta: + name: response.image_generation_call.partial_image + group: responses + example: | + { + "type": "response.image_generation_call.partial_image", + "output_index": 0, + "item_id": "item-123", + "sequence_number": 0, + "partial_image_index": 0, + "partial_image_b64": "..." + } + BetaResponseImageGenCallInProgressEvent: + type: object + title: ResponseImageGenCallInProgressEvent + description: | + Emitted when an image generation tool call is in progress. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.image_generation_call.in_progress + description: The type of the event. Always 'response.image_generation_call.in_progress'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the image generation item being processed. + sequence_number: + type: integer + description: The sequence number of the image generation item being processed. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.image_generation_call.in_progress + group: responses + example: | + { + "type": "response.image_generation_call.in_progress", + "output_index": 0, + "item_id": "item-123", + "sequence_number": 0 + } + BetaResponseImageGenCallGeneratingEvent: + type: object + title: ResponseImageGenCallGeneratingEvent + description: | + Emitted when an image generation tool call is actively generating an image (intermediate state). + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.image_generation_call.generating + description: The type of the event. Always 'response.image_generation_call.generating'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + item_id: + type: string + description: The unique identifier of the image generation item being processed. + sequence_number: + type: integer + description: The sequence number of the image generation item being processed. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.image_generation_call.generating + group: responses + example: | + { + "type": "response.image_generation_call.generating", + "output_index": 0, + "item_id": "item-123", + "sequence_number": 0 + } + BetaResponseImageGenCallCompletedEvent: + type: object + title: ResponseImageGenCallCompletedEvent + description: | + Emitted when an image generation tool call has completed and the final image is available. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.image_generation_call.completed + description: The type of the event. Always 'response.image_generation_call.completed'. + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response's output array. + sequence_number: + type: integer + description: The sequence number of this event. + item_id: + type: string + description: The unique identifier of the image generation item being processed. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.image_generation_call.completed + group: responses + example: | + { + "type": "response.image_generation_call.completed", + "output_index": 0, + "item_id": "item-123", + "sequence_number": 1 + } + BetaResponseReasoningTextDoneEvent: + type: object + description: Emitted when a reasoning text is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_text.done`. + enum: + - response.reasoning_text.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this reasoning text is associated with. + output_index: + type: integer + description: | + The index of the output item this reasoning text is associated with. + content_index: + type: integer + description: | + The index of the reasoning content part. + text: + type: string + description: | + The full text of the completed reasoning content. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - content_index + - text + - sequence_number + x-oaiMeta: + name: response.reasoning_text.done + group: responses + example: | + { + "type": "response.reasoning_text.done", + "item_id": "rs_123", + "output_index": 0, + "content_index": 0, + "text": "The user is asking...", + "sequence_number": 4 + } + BetaResponseReasoningTextDeltaEvent: + type: object + description: Emitted when a delta is added to a reasoning text. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_text.delta`. + enum: + - response.reasoning_text.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this reasoning text delta is associated with. + output_index: + type: integer + description: | + The index of the output item this reasoning text delta is associated with. + content_index: + type: integer + description: | + The index of the reasoning content part this delta is associated with. + delta: + type: string + description: | + The text delta that was added to the reasoning content. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - content_index + - delta + - sequence_number + x-oaiMeta: + name: response.reasoning_text.delta + group: responses + example: | + { + "type": "response.reasoning_text.delta", + "item_id": "rs_123", + "output_index": 0, + "content_index": 0, + "delta": "The", + "sequence_number": 1 + } + BetaResponseReasoningSummaryTextDoneEvent: + type: object + description: Emitted when a reasoning summary text is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_summary_text.done`. + enum: + - response.reasoning_summary_text.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary text is associated with. + output_index: + type: integer + description: | + The index of the output item this summary text is associated with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + text: + type: string + description: | + The full text of the completed reasoning summary. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - summary_index + - text + - sequence_number + x-oaiMeta: + name: response.reasoning_summary_text.done + group: responses + example: | + { + "type": "response.reasoning_summary_text.done", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!", + "sequence_number": 1 + } + BetaResponseReasoningSummaryTextDeltaEvent: + type: object + description: Emitted when a delta is added to a reasoning summary text. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_summary_text.delta`. + enum: + - response.reasoning_summary_text.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary text delta is associated with. + output_index: + type: integer + description: | + The index of the output item this summary text delta is associated with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + delta: + type: string + description: | + The text delta that was added to the summary. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - summary_index + - delta + - sequence_number + x-oaiMeta: + name: response.reasoning_summary_text.delta + group: responses + example: | + { + "type": "response.reasoning_summary_text.delta", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "delta": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!", + "sequence_number": 1 + } + BetaResponseReasoningSummaryPartDoneEvent: + type: object + description: Emitted when a reasoning summary part is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_summary_part.done`. + enum: + - response.reasoning_summary_part.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary part is associated with. + output_index: + type: integer + description: | + The index of the output item this summary part is associated with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + status: + type: string + description: | + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. + enum: + - incomplete + sequence_number: + type: integer + description: | + The sequence number of this event. + part: + type: object + description: | + The completed summary part. properties: - stream_id: + type: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseWsQueued - description: | - Emitted when a response is queued and waiting to be processed. - allOf: - - $ref: '#/components/schemas/BetaResponseQueuedEvent' - - type: object - properties: - stream_id: + description: The type of the summary part. Always `summary_text`. + enum: + - summary_text + x-stainless-const: true + text: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCustomToolCallInputWsDelta - description: | - Event representing a delta (partial update) to the input of a custom tool call. - allOf: - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' - - type: object + description: The text of the summary part. + required: + - type + - text + required: + - type + - item_id + - output_index + - summary_index + - part + - sequence_number + x-oaiMeta: + name: response.reasoning_summary_part.done + group: responses + example: | + { + "type": "response.reasoning_summary_part.done", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "part": { + "type": "summary_text", + "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!" + }, + "sequence_number": 1 + } + BetaResponseReasoningSummaryPartAddedEvent: + type: object + description: Emitted when a new reasoning summary part is added. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.reasoning_summary_part.added`. + enum: + - response.reasoning_summary_part.added + x-stainless-const: true + item_id: + type: string + description: | + The ID of the item this summary part is associated with. + output_index: + type: integer + description: | + The index of the output item this summary part is associated with. + summary_index: + type: integer + description: | + The index of the summary part within the reasoning summary. + sequence_number: + type: integer + description: | + The sequence number of this event. + part: + type: object + description: | + The summary part that was added. properties: - stream_id: + type: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - title: BetaResponseCustomToolCallInputWsDone - description: | - Event indicating that input for a custom tool call is complete. - allOf: - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' - - type: object - properties: - stream_id: + description: The type of the summary part. Always `summary_text`. + enum: + - summary_text + x-stainless-const: true + text: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - - $ref: '#/components/schemas/BetaResponseWsError' - - $ref: '#/components/schemas/BetaResponseSteerAcceptedEvent' - - $ref: '#/components/schemas/BetaResponseSteerPendingEvent' - - $ref: '#/components/schemas/BetaResponseSteerFailedEvent' - - $ref: '#/components/schemas/BetaResponseInjectCreatedEvent' - - $ref: '#/components/schemas/BetaResponseInjectFailedEvent' - BetaResponseInjectFailedEvent: + description: The text of the summary part. + required: + - type + - text + required: + - type + - item_id + - output_index + - summary_index + - part + - sequence_number + x-oaiMeta: + name: response.reasoning_summary_part.added + group: responses + example: | + { + "type": "response.reasoning_summary_part.added", + "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", + "output_index": 0, + "summary_index": 0, + "part": { + "type": "summary_text", + "text": "" + }, + "sequence_number": 1 + } + BetaResponseTextDoneEvent: + type: object + description: Emitted when text content is finalized. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.output_text.done`. + enum: + - response.output_text.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the text content is finalized. + output_index: + type: integer + description: | + The index of the output item that the text content is finalized. + content_index: + type: integer + description: | + The index of the content part that the text content is finalized. + text: + type: string + description: | + The text content that is finalized. + sequence_number: + type: integer + description: The sequence number for this event. + logprobs: + type: array + description: | + The log probabilities of the tokens in the delta. + items: + $ref: '#/components/schemas/BetaResponseLogProb' + required: + - type + - item_id + - output_index + - content_index + - text + - sequence_number + - logprobs + x-oaiMeta: + name: response.output_text.done + group: responses + example: | + { + "type": "response.output_text.done", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", + "sequence_number": 1 + } + BetaResponseLogProb: + type: object + description: "A logprob is the logarithmic probability that the model assigns to producing \na particular token at a given position in the sequence. Less-negative (higher) \nlogprob values indicate greater model confidence in that token choice.\n" + properties: + token: + description: A possible text token. + type: string + logprob: + description: | + The log probability of this token. + type: number + top_logprobs: + description: | + The log probabilities of up to 20 of the most likely tokens. + type: array + items: + type: object + properties: + token: + description: A possible text token. + type: string + logprob: + description: The log probability of this token. + type: number + required: + - token + - logprob + BetaResponseTextDeltaEvent: + type: object + description: Emitted when there is an additional text delta. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.output_text.delta`. + enum: + - response.output_text.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the text delta was added to. + output_index: + type: integer + description: | + The index of the output item that the text delta was added to. + content_index: + type: integer + description: | + The index of the content part that the text delta was added to. + delta: + type: string + description: | + The text delta that was added. + sequence_number: + type: integer + description: The sequence number for this event. + logprobs: + type: array + description: | + The log probabilities of the tokens in the delta. + items: + $ref: '#/components/schemas/BetaResponseLogProb' + required: + - type + - item_id + - output_index + - content_index + - delta + - sequence_number + - logprobs + x-oaiMeta: + name: response.output_text.delta + group: responses + example: | + { + "type": "response.output_text.delta", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "delta": "In", + "sequence_number": 1 + } + BetaResponseRefusalDoneEvent: + type: object + description: Emitted when refusal text is finalized. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.refusal.done`. + enum: + - response.refusal.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the refusal text is finalized. + output_index: + type: integer + description: | + The index of the output item that the refusal text is finalized. + content_index: + type: integer + description: | + The index of the content part that the refusal text is finalized. + refusal: + type: string + description: | + The refusal text that is finalized. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - content_index + - refusal + - sequence_number + x-oaiMeta: + name: response.refusal.done + group: responses + example: | + { + "type": "response.refusal.done", + "item_id": "item-abc", + "output_index": 1, + "content_index": 2, + "refusal": "final refusal text", + "sequence_number": 1 + } + BetaResponseRefusalDeltaEvent: + type: object + description: Emitted when there is a partial refusal text. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.refusal.delta`. + enum: + - response.refusal.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the refusal text is added to. + output_index: + type: integer + description: | + The index of the output item that the refusal text is added to. + content_index: + type: integer + description: | + The index of the content part that the refusal text is added to. + delta: + type: string + description: | + The refusal text that is added. + sequence_number: + type: integer + description: | + The sequence number of this event. + required: + - type + - item_id + - output_index + - content_index + - delta + - sequence_number + x-oaiMeta: + name: response.refusal.delta + group: responses + example: | + { + "type": "response.refusal.delta", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "delta": "refusal text so far", + "sequence_number": 1 + } + BetaResponseOutputItemDoneEvent: + type: object + description: Emitted when an output item is marked done. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.output_item.done`. + enum: + - response.output_item.done + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that was marked done. + sequence_number: + type: integer + description: | + The sequence number of this event. + item: + $ref: '#/components/schemas/BetaOutputItem' + description: | + The output item that was marked done. + required: + - type + - output_index + - item + - sequence_number + x-oaiMeta: + name: response.output_item.done + group: responses + example: | + { + "type": "response.output_item.done", + "output_index": 0, + "item": { + "id": "msg_123", + "status": "completed", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", + "annotations": [] + } + ] + }, + "sequence_number": 1 + } + BetaResponseOutputItemAddedEvent: + type: object + description: Emitted when a new output item is added. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.output_item.added`. + enum: + - response.output_item.added + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that was added. + sequence_number: + type: integer + description: | + The sequence number of this event. + item: + $ref: '#/components/schemas/BetaOutputItem' + description: | + The output item that was added. For reasoning items, `encrypted_content` + may be incomplete while the item is in progress. Use the reasoning item + from the corresponding `response.output_item.done` event when passing it + as input to a subsequent request. + required: + - type + - output_index + - item + - sequence_number + x-oaiMeta: + name: response.output_item.added + group: responses + example: | + { + "type": "response.output_item.added", + "output_index": 0, + "item": { + "id": "msg_123", + "status": "in_progress", + "type": "message", + "role": "assistant", + "content": [] + }, + "sequence_number": 1 + } + BetaResponseInProgressEvent: + type: object + description: Emitted when the response is in progress. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.in_progress`. + enum: + - response.in_progress + x-stainless-const: true + response: + $ref: '#/components/schemas/BetaResponse' + description: | + The response that is in progress. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.in_progress + group: responses + example: | + { + "type": "response.in_progress", + "response": { + "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", + "object": "response", + "created_at": 1741487325, + "status": "in_progress", + "completed_at": null, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + }, + "sequence_number": 1 + } + BetaResponseShellCallOutputContentDoneStreamingEvent: + properties: + type: + type: string + enum: + - response.shell_call_output_content.done + description: The type of the event, always `response.shell_call_output_content.done`. + default: response.shell_call_output_content.done + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + item_id: + type: string + description: The ID of the output item that was updated. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that produced output. + output: + items: + $ref: '#/components/schemas/BetaFunctionShellCallOutputContent' + type: array + description: The output contents emitted for the shell command. + type: object + required: + - type + - sequence_number + - item_id + - output_index + - command_index + - output + title: Response shell call output content done event + description: A streaming event that indicated shell call output was completed. + BetaResponseShellCallOutputContentDeltaStreamingEvent: + properties: + type: + type: string + enum: + - response.shell_call_output_content.delta + description: The type of the event, always `response.shell_call_output_content.delta`. + default: response.shell_call_output_content.delta + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + item_id: + type: string + description: The ID of the output item that was updated. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that produced output. + delta: + $ref: '#/components/schemas/BetaShellCallOutputDelta' + description: The stdout/stderr delta that was emitted. + type: object + required: + - type + - sequence_number + - item_id + - output_index + - command_index + - delta + title: Response shell call output content delta event + description: A streaming event that indicated shell call output was incrementally added. + BetaShellCallOutputDelta: + properties: + stdout: + type: string + description: The stdout delta that was emitted. + stderr: + type: string + description: The stderr delta that was emitted. + type: object + required: [] + title: Shell call output delta + description: A delta of stdout/stderr emitted while a shell call was running. + BetaResponseShellCallCommandDoneStreamingEvent: + properties: + type: + type: string + enum: + - response.shell_call_command.done + description: The type of the event, always `response.shell_call_command.done`. + default: response.shell_call_command.done + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that was completed. + command: + type: string + description: The final shell command that was emitted. + type: object + required: + - type + - sequence_number + - output_index + - command_index + - command + title: Response shell command done event + description: A streaming event that indicated a shell command was completed. + BetaResponseShellCallCommandDeltaStreamingEvent: + properties: + type: + type: string + enum: + - response.shell_call_command.delta + description: The type of the event, always `response.shell_call_command.delta`. + default: response.shell_call_command.delta + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that was updated. + delta: + type: string + description: The shell command delta that was appended. + obfuscation: + type: string + description: An obfuscation string that was added to pad the event payload. + type: object + required: + - type + - sequence_number + - output_index + - command_index + - delta + title: Response shell command delta event + description: A streaming event that indicated a shell command was incrementally updated. + BetaResponseShellCallCommandAddedStreamingEvent: + properties: + type: + type: string + enum: + - response.shell_call_command.added + description: The type of the event, always `response.shell_call_command.added`. + default: response.shell_call_command.added + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + output_index: + type: integer + description: The index of the output item that was updated. + command_index: + type: integer + description: The index of the shell command that was added. + command: + type: string + description: The shell command that was added. + type: object + required: + - type + - sequence_number + - output_index + - command_index + - command + title: Response shell command added event + description: A streaming event that indicated a shell command was added to a tool call. + BetaResponseFunctionCallArgumentsDoneEvent: + type: object + description: Emitted when function-call arguments are finalized. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + enum: + - response.function_call_arguments.done + x-stainless-const: true + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item. + sequence_number: + type: integer + description: The sequence number of this event. + arguments: + type: string + description: The function-call arguments. + required: + - type + - item_id + - output_index + - arguments + - sequence_number + x-oaiMeta: + name: response.function_call_arguments.done + group: responses + example: | + { + "type": "response.function_call_arguments.done", + "item_id": "item-abc", + "output_index": 1, + "arguments": "{ \"arg\": 123 }", + "sequence_number": 1 + } + BetaResponseFunctionCallArgumentsDeltaEvent: + type: object + description: Emitted when there is a partial function-call arguments delta. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.function_call_arguments.delta`. + enum: + - response.function_call_arguments.delta + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the function-call arguments delta is added to. + output_index: + type: integer + description: | + The index of the output item that the function-call arguments delta is added to. + sequence_number: + type: integer + description: The sequence number of this event. + delta: + type: string + description: | + The function-call arguments delta that is added. + required: + - type + - item_id + - output_index + - delta + - sequence_number + x-oaiMeta: + name: response.function_call_arguments.delta + group: responses + example: | + { + "type": "response.function_call_arguments.delta", + "item_id": "item-abc", + "output_index": 0, + "delta": "{ \"arg\":" + "sequence_number": 1 + } + BetaResponseFileSearchCallSearchingEvent: + type: object + description: Emitted when a file search is currently searching. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.file_search_call.searching`. + enum: + - response.file_search_call.searching + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the file search call is searching. + item_id: + type: string + description: | + The ID of the output item that the file search call is initiated. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.file_search_call.searching + group: responses + example: | + { + "type": "response.file_search_call.searching", + "output_index": 0, + "item_id": "fs_123", + "sequence_number": 1 + } + BetaResponseFileSearchCallInProgressEvent: + type: object + description: Emitted when a file search call is initiated. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.file_search_call.in_progress`. + enum: + - response.file_search_call.in_progress + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the file search call is initiated. + item_id: + type: string + description: | + The ID of the output item that the file search call is initiated. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.file_search_call.in_progress + group: responses + example: | + { + "type": "response.file_search_call.in_progress", + "output_index": 0, + "item_id": "fs_123", + "sequence_number": 1 + } + BetaResponseFileSearchCallCompletedEvent: + type: object + description: Emitted when a file search call is completed (results found). + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.file_search_call.completed`. + enum: + - response.file_search_call.completed + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the file search call is initiated. + item_id: + type: string + description: | + The ID of the output item that the file search call is initiated. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.file_search_call.completed + group: responses + example: | + { + "type": "response.file_search_call.completed", + "output_index": 0, + "item_id": "fs_123", + "sequence_number": 1 + } + BetaResponseErrorEvent: + type: object + description: Emitted when an error occurs. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `error`. + enum: + - error + x-stainless-const: true + code: + anyOf: + - type: string + description: | + The error code. + - type: 'null' + message: + type: string + description: | + The error message. + param: + anyOf: + - type: string + description: | + The error parameter. + - type: 'null' + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - code + - message + - param + - sequence_number + x-oaiMeta: + name: error + group: responses + example: | + { + "type": "error", + "code": "ERR_SOMETHING", + "message": "Something went wrong", + "param": null, + "sequence_number": 1 + } + BetaResponseCreatedEvent: + type: object + description: | + An event that is emitted when a response is created. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.created`. + enum: + - response.created + x-stainless-const: true + response: + $ref: '#/components/schemas/BetaResponse' + description: | + The response that was created. + sequence_number: + type: integer + description: The sequence number for this event. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.created + group: responses + example: | + { + "type": "response.created", + "response": { + "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", + "object": "response", + "created_at": 1741487325, + "status": "in_progress", + "completed_at": null, + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": null, + "summary": null + }, + "store": true, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + }, + "sequence_number": 1 + } + BetaResponseContentPartDoneEvent: + type: object + description: Emitted when a content part is done. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.content_part.done`. + enum: + - response.content_part.done + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the content part was added to. + output_index: + type: integer + description: | + The index of the output item that the content part was added to. + content_index: + type: integer + description: | + The index of the content part that is done. + sequence_number: + type: integer + description: The sequence number of this event. + part: + $ref: '#/components/schemas/BetaOutputContent' + description: | + The content part that is done. + required: + - type + - item_id + - output_index + - content_index + - part + - sequence_number + x-oaiMeta: + name: response.content_part.done + group: responses + example: | + { + "type": "response.content_part.done", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "sequence_number": 1, + "part": { + "type": "output_text", + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", + "annotations": [] + } + } + BetaOutputContent: + discriminator: + propertyName: type + anyOf: + - $ref: '#/components/schemas/BetaOutputTextContent' + - $ref: '#/components/schemas/BetaRefusalContent' + - $ref: '#/components/schemas/BetaReasoningTextContent' + BetaResponseContentPartAddedEvent: + type: object + description: Emitted when a new content part is added. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.content_part.added`. + enum: + - response.content_part.added + x-stainless-const: true + item_id: + type: string + description: | + The ID of the output item that the content part was added to. + output_index: + type: integer + description: | + The index of the output item that the content part was added to. + content_index: + type: integer + description: | + The index of the content part that was added. + part: + $ref: '#/components/schemas/BetaOutputContent' + description: | + The content part that was added. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - item_id + - output_index + - content_index + - part + - sequence_number + x-oaiMeta: + name: response.content_part.added + group: responses + example: | + { + "type": "response.content_part.added", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "part": { + "type": "output_text", + "text": "", + "annotations": [] + }, + "sequence_number": 1 + } + BetaResponseCompletedEvent: + type: object + description: Emitted when the model response is complete. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.completed`. + enum: + - response.completed + x-stainless-const: true + response: + $ref: '#/components/schemas/BetaResponse' + description: | + Properties of the completed response. + sequence_number: + type: integer + description: The sequence number for this event. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.completed + group: responses + example: | + { + "type": "response.completed", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "completed", + "completed_at": 1740855870, + "error": null, + "incomplete_details": null, + "input": [], + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [ + { + "id": "msg_123", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", + "annotations": [] + } + ] + } + ], + "previous_response_id": null, + "reasoning_effort": null, + "store": false, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": { + "input_tokens": 0, + "output_tokens": 0, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 0 + }, + "user": null, + "metadata": {} + }, + "sequence_number": 1 + } + BetaResponseCompactionCompactingStreamingEvent: + properties: + type: + type: string + enum: + - response.compaction.compacting + description: The type of the event, always `response.compaction.compacting`. + default: response.compaction.compacting + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of the event that was emitted. + agent: + $ref: '#/components/schemas/BetaAgentTag' + description: The agent that owns this multi-agent streaming event. + output_index: + type: integer + description: The index of the compaction output item. + item_id: + type: string + description: The ID of the compaction output item. + type: object + required: + - type + - sequence_number + - output_index + - item_id + title: Response compaction compacting event + description: Emitted when new summary content is sampled for a compaction trigger. Contains no summary content. + BetaResponseCodeInterpreterCallInterpretingEvent: + type: object + description: Emitted when the code interpreter is actively interpreting the code snippet. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: The type of the event. Always `response.code_interpreter_call.interpreting`. + enum: + - response.code_interpreter_call.interpreting + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response for which the code interpreter is interpreting code. + item_id: + type: string + description: The unique identifier of the code interpreter tool call item. + sequence_number: + type: integer + description: The sequence number of this event, used to order streaming events. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.code_interpreter_call.interpreting + group: responses + example: | + { + "type": "response.code_interpreter_call.interpreting", + "output_index": 4, + "item_id": "ci_12345", + "sequence_number": 1 + } + BetaResponseCodeInterpreterCallInProgressEvent: + type: object + description: Emitted when a code interpreter call is in progress. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: The type of the event. Always `response.code_interpreter_call.in_progress`. + enum: + - response.code_interpreter_call.in_progress + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response for which the code interpreter call is in progress. + item_id: + type: string + description: The unique identifier of the code interpreter tool call item. + sequence_number: + type: integer + description: The sequence number of this event, used to order streaming events. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.code_interpreter_call.in_progress + group: responses + example: | + { + "type": "response.code_interpreter_call.in_progress", + "output_index": 0, + "item_id": "ci_12345", + "sequence_number": 1 + } + BetaResponseCodeInterpreterCallCompletedEvent: + type: object + description: Emitted when the code interpreter call is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: The type of the event. Always `response.code_interpreter_call.completed`. + enum: + - response.code_interpreter_call.completed + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response for which the code interpreter call is completed. + item_id: + type: string + description: The unique identifier of the code interpreter tool call item. + sequence_number: + type: integer + description: The sequence number of this event, used to order streaming events. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.code_interpreter_call.completed + group: responses + example: | + { + "type": "response.code_interpreter_call.completed", + "output_index": 5, + "item_id": "ci_12345", + "sequence_number": 1 + } + BetaResponseCodeInterpreterCallCodeDoneEvent: + type: object + description: Emitted when the code snippet is finalized by the code interpreter. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: The type of the event. Always `response.code_interpreter_call_code.done`. + enum: + - response.code_interpreter_call_code.done + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response for which the code is finalized. + item_id: + type: string + description: The unique identifier of the code interpreter tool call item. + code: + type: string + description: The final code snippet output by the code interpreter. + sequence_number: + type: integer + description: The sequence number of this event, used to order streaming events. + required: + - type + - output_index + - item_id + - code + - sequence_number + x-oaiMeta: + name: response.code_interpreter_call_code.done + group: responses + example: | + { + "type": "response.code_interpreter_call_code.done", + "output_index": 3, + "item_id": "ci_12345", + "code": "print('done')", + "sequence_number": 1 + } + BetaResponseCodeInterpreterCallCodeDeltaEvent: + type: object + description: Emitted when a partial code snippet is streamed by the code interpreter. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: The type of the event. Always `response.code_interpreter_call_code.delta`. + enum: + - response.code_interpreter_call_code.delta + x-stainless-const: true + output_index: + type: integer + description: The index of the output item in the response for which the code is being streamed. + item_id: + type: string + description: The unique identifier of the code interpreter tool call item. + delta: + type: string + description: The partial code snippet being streamed by the code interpreter. + sequence_number: + type: integer + description: The sequence number of this event, used to order streaming events. + required: + - type + - output_index + - item_id + - delta + - sequence_number + x-oaiMeta: + name: response.code_interpreter_call_code.delta + group: responses + example: | + { + "type": "response.code_interpreter_call_code.delta", + "output_index": 0, + "item_id": "ci_12345", + "delta": "print('Hello, world')", + "sequence_number": 1 + } + BetaResponseAudioTranscriptDoneEvent: + type: object + description: Emitted when the full audio transcript is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.audio.transcript.done`. + enum: + - response.audio.transcript.done + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - response_id + - sequence_number + x-oaiMeta: + name: response.audio.transcript.done + group: responses + example: | + { + "type": "response.audio.transcript.done", + "response_id": "resp_123", + "sequence_number": 1 + } + BetaResponseAudioTranscriptDeltaEvent: + type: object + description: Emitted when there is a partial transcript of audio. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.audio.transcript.delta`. + enum: + - response.audio.transcript.delta + x-stainless-const: true + delta: + type: string + description: | + The partial transcript of the audio response. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - response_id + - delta + - sequence_number + x-oaiMeta: + name: response.audio.transcript.delta + group: responses + example: | + { + "type": "response.audio.transcript.delta", + "response_id": "resp_123", + "delta": " ... partial transcript ... ", + "sequence_number": 1 + } + BetaResponseAudioDoneEvent: + type: object + description: Emitted when the audio response is complete. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.audio.done`. + enum: + - response.audio.done + x-stainless-const: true + sequence_number: + type: integer + description: | + The sequence number of the delta. + required: + - type + - sequence_number + - response_id + x-oaiMeta: + name: response.audio.done + group: responses + example: | + { + "type": "response.audio.done", + "response_id": "resp-123", + "sequence_number": 1 + } + BetaResponseAudioDeltaEvent: + type: object + description: Emitted when there is a partial audio response. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.audio.delta`. + enum: + - response.audio.delta + x-stainless-const: true + sequence_number: + type: integer + description: | + A sequence number for this chunk of the stream response. + delta: + type: string + description: | + A chunk of Base64 encoded response audio bytes. + required: + - type + - delta + - sequence_number + x-oaiMeta: + name: response.audio.delta + group: responses + example: | + { + "type": "response.audio.delta", + "response_id": "resp_123", + "delta": "base64encoded...", + "sequence_number": 1 + } + BetaResponseIncompleteEvent: type: object - title: ResponseInjectFailedEvent description: | - Emitted when injected input could not be committed to a response. The event - returns the uncommitted raw input so the client can retry it in another - response when appropriate. + An event that is emitted when a response finishes as incomplete. + + Over WebSocket, steering can finish a response with + `response.incomplete_details.reason` set to `steered`, followed automatically + by a successor `response.created` that commits the queued steering input. properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. type: type: string + description: | + The type of the event. Always `response.incomplete`. enum: - - response.inject.failed - description: The event discriminator. Always `response.inject.failed`. + - response.incomplete x-stainless-const: true - response_id: + response: + $ref: '#/components/schemas/BetaResponse' + description: | + The response that was incomplete. + sequence_number: + type: integer + description: The sequence number of this event. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.incomplete + group: responses + example: | + { + "type": "response.incomplete", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "incomplete", + "completed_at": null, + "error": null, + "incomplete_details": { + "reason": "max_tokens" + }, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [], + "previous_response_id": null, + "reasoning_effort": null, + "store": false, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + }, + "sequence_number": 1 + } + BetaResponseFailedEvent: + type: object + description: | + An event that is emitted when a response fails. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: type: string - description: The ID of the response that rejected the input. - input: - type: array - description: The raw input items that were not committed. - items: - $ref: '#/components/schemas/BetaInputItem' - error: - type: object - description: Information about why the input was not committed. - properties: - code: - type: string - enum: - - response_already_completed - - response_not_found - description: A machine-readable error code. - message: - type: string - description: A human-readable description of the error. - required: - - code - - message + description: | + The type of the event. Always `response.failed`. + enum: + - response.failed + x-stainless-const: true sequence_number: type: integer - description: The sequence number for this event. - stream_id: + description: The sequence number of this event. + response: + $ref: '#/components/schemas/BetaResponse' + description: | + The response that failed. + required: + - type + - response + - sequence_number + x-oaiMeta: + name: response.failed + group: responses + example: | + { + "type": "response.failed", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "failed", + "completed_at": null, + "error": { + "code": "server_error", + "message": "The model failed to generate a response." + }, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-6-astra", + "output": [], + "previous_response_id": null, + "reasoning_effort": null, + "store": false, + "temperature": 1, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1, + "truncation": "disabled", + "usage": null, + "user": null, + "metadata": {} + } + } + BetaResponseWebSearchCallCompletedEvent: + type: object + description: Emitted when a web search call is completed. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.web_search_call.completed`. + enum: + - response.web_search_call.completed + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the web search call is associated with. + item_id: + type: string + description: | + Unique ID for the output item associated with the web search call. + sequence_number: + type: integer + description: The sequence number of the web search call being processed. + required: + - type + - output_index + - item_id + - sequence_number + x-oaiMeta: + name: response.web_search_call.completed + group: responses + example: | + { + "type": "response.web_search_call.completed", + "output_index": 0, + "item_id": "ws_123", + "sequence_number": 0 + } + BetaResponseWebSearchCallSearchingEvent: + type: object + description: Emitted when a web search call is executing. + properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. + type: + type: string + description: | + The type of the event. Always `response.web_search_call.searching`. + enum: + - response.web_search_call.searching + x-stainless-const: true + output_index: + type: integer + description: | + The index of the output item that the web search call is associated with. + item_id: type: string description: | - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + Unique ID for the output item associated with the web search call. + sequence_number: + type: integer + description: The sequence number of the web search call being processed. required: - type - - response_id - - input - - error + - output_index + - item_id - sequence_number - x-oai-beta: responses_multi_agent=v1 x-oaiMeta: + name: response.web_search_call.searching + group: responses example: | { - "type": "response.inject.failed", - "response_id": "resp_123", - "input": [ - { - "type": "function_call_output", - "call_id": "call_123", - "output": "{\"temperature\":72}" - } - ], - "error": { - "code": "response_already_completed", - "message": "Response 'resp_123' has already completed." - }, - "sequence_number": 9 + "type": "response.web_search_call.searching", + "output_index": 0, + "item_id": "ws_123", + "sequence_number": 0 } - BetaResponseInjectCreatedEvent: + BetaResponseWebSearchCallInProgressEvent: type: object - title: ResponseInjectCreatedEvent - description: | - Emitted when all injected input items were validated and committed to the - active response. + description: Emitted when a web search call is initiated. properties: + agent: + anyOf: + - $ref: '#/components/schemas/BetaAgentTag' + - type: 'null' + description: The agent that owns this multi-agent streaming event. type: type: string + description: | + The type of the event. Always `response.web_search_call.in_progress`. enum: - - response.inject.created - description: The event discriminator. Always `response.inject.created`. + - response.web_search_call.in_progress x-stainless-const: true - response_id: - type: string - description: The ID of the response that accepted the input. - sequence_number: + output_index: type: integer - description: The sequence number for this event. - stream_id: + description: | + The index of the output item that the web search call is associated with. + item_id: type: string description: | - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + Unique ID for the output item associated with the web search call. + sequence_number: + type: integer + description: The sequence number of the web search call being processed. required: - type - - response_id + - output_index + - item_id - sequence_number - x-oai-beta: responses_multi_agent=v1 x-oaiMeta: + name: response.web_search_call.in_progress + group: responses example: | { - "type": "response.inject.created", - "response_id": "resp_123", - "sequence_number": 8 + "type": "response.web_search_call.in_progress", + "output_index": 0, + "item_id": "ws_123", + "sequence_number": 0 } - BetaResponseWsError: + BetaResponseSteerFailedEvent: type: object - title: ResponseWsError - description: Emitted when an error occurs while processing a Responses WebSocket request. + title: ResponseSteerFailedEvent + description: | + Emitted when steering input is rejected or cannot be committed to a + successor response. Returns the original, uncommitted input so the client + can carry it into `response.create` when appropriate. Invalid input must + be corrected before retrying. + + Failures after acceptance include the same steering ID. Failures before an + ID is allocated omit `steer.id`. A lost connection or missing acknowledgement + leaves the outcome unknown; it is not proof that the input was rejected. properties: - agent: - anyOf: - - $ref: '#/components/schemas/BetaAgentTag' - - type: 'null' - description: The agent that owns this multi-agent streaming event. type: type: string - description: The type of the event. Always `error`. enum: - - error + - response.steer.failed + description: The event discriminator. Always `response.steer.failed`. x-stainless-const: true - status: - type: integer - description: The HTTP status code associated with a WebSocket protocol error. sequence_number: type: integer - description: The sequence number of an error emitted by the response stream. + description: The sequence number for this event. + steer: + type: object + description: The steering submission that could not be committed. + properties: + id: + type: string + description: | + The ID assigned to the steering submission, if one was allocated. + previous_response_id: + type: string + description: The ID of the response that was targeted for steering. + input: + $ref: '#/components/schemas/BetaResponseSteerInput' + required: + - previous_response_id + - input error: - $ref: '#/components/schemas/BetaErrorPayload' - description: Details about the error. + type: object + description: Information about why the input could not be committed. + properties: + type: + type: string + enum: + - invalid_request_error + description: The error type. Always `invalid_request_error`. + x-stainless-const: true + code: + $ref: '#/components/schemas/BetaResponseSteerErrorCode' + message: + type: string + description: A human-readable description of the error. + required: + - type + - code + - message stream_id: type: string description: | - The WebSocket lane that emitted this event. This field is present when the - originating `response.create` event supplied a `stream_id`. + The WebSocket lane that emitted this event, when the target response is + available and its `response.create` event supplied a `stream_id`. required: - type + - sequence_number + - steer - error x-oaiMeta: - name: error + name: response.steer.failed group: responses example: | { - "type": "error", - "status": 400, - "stream_id": "agent_1", + "type": "response.steer.failed", + "sequence_number": 5, + "steer": { + "id": "steer_456", + "previous_response_id": "resp_123", + "input": [ + { + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Prioritize the database rollout." + } + ] + } + ] + }, "error": { "type": "invalid_request_error", - "code": "websocket_stream_limit_reached", - "message": "This WebSocket connection has reached its stream limit.", - "param": "stream_id" + "code": "successor_creation_failed", + "message": "We couldn't start the next response. Send this steering input again with response.create." } } - BetaErrorPayload: + BetaResponseSteerErrorCode: + title: ResponseSteerErrorCode + description: | + A machine-readable steering error code. Clients should handle unknown + values because additional codes may be introduced. Known values include: + - `response_not_found`: The target response is not available on this connection. + - `invalid_input`: The event or input failed validation. + - `steering_not_supported`: The model or response execution mode does not support steering. + - `too_many_pending_steers`: Too much steering input is pending for the response. + - `response_already_completed`: The response completed and is no longer accepting steering input. + - `response_not_active`: The response is no longer accepting steering input. + - `successor_creation_failed`: The successor response could not be created. + anyOf: + - type: string + enum: + - response_not_found + - invalid_input + - steering_not_supported + - too_many_pending_steers + - response_already_completed + - response_not_active + - successor_creation_failed + - type: string + BetaResponseSteerInput: + title: ResponseSteerInput + description: | + Input to queue for a continuation of the response. Uses the same string or + input-item shape as `response.create.input`, with a non-empty array when + supplying input items. + + Steering accepts only messages with the `user` role. Each message may + contain only `type`, `role`, and `content`, with `content` as a string or an + array of `input_text`, `input_image`, and `input_file` parts. The optional + `type` must be `message`. Other roles, tool outputs, and item types are not + supported for steering. + anyOf: + - type: string + title: Text input + description: A text input, equivalent to a message with the `user` role. + - $ref: '#/components/schemas/BetaResponseSteerInputItemList' + BetaResponseSteerInputItemList: + type: array + title: Response steer input item list + description: A non-empty list of message inputs to queue for the response. + minItems: 1 + items: + $ref: '#/components/schemas/BetaResponseSteerInputItem' + BetaResponseSteerInputItem: + title: Response steer input item + anyOf: + - $ref: '#/components/schemas/BetaUserMessageItemParam' + - $ref: '#/components/schemas/BetaFunctionCallOutputItemParam' + discriminator: + propertyName: type + BetaUserMessageItemParam: properties: - type: - type: string - description: The error type that was emitted. - code: + agent: + anyOf: + - $ref: '#/components/schemas/Beta_AgentTagParam' + description: The agent that produced this item. + - type: 'null' + id: anyOf: - type: string - description: The error code that was emitted, if any. + description: The unique ID of this message item. + example: msg_123 - type: 'null' - message: + type: type: string - description: The human-readable error message that was emitted. - param: + enum: + - message + description: The item type. Always `message`. + default: message + x-stainless-const: true + role: + type: string + enum: + - user + description: The message role. Always `user`. + default: user + x-stainless-const: true + content: + description: The message content, as an array of content parts. anyOf: + - items: + $ref: '#/components/schemas/BetaResponseSteerInputContent' + description: A piece of message content, such as text, an image, or a file. + type: array - type: string - description: The parameter name that was associated with the error, if any. + maxLength: 10485760 + description: The message content, as a single string. + status: + anyOf: + - type: string + description: The status of the message item. - type: 'null' - headers: - additionalProperties: - type: string - description: The header value that was emitted. - type: object - description: The response headers that were emitted with the error, if any. - x-oaiTypeLabel: map - misalignment: - $ref: '#/components/schemas/BetaMisalignmentErrorDetailsResource' type: object required: - type - - code - - message - - param - title: Error payload - description: An error payload that was emitted for a streaming error event. - BetaResponsesWebSocketStreamEvent: - allOf: - - anyOf: - - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' - - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' - - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' - - $ref: '#/components/schemas/BetaResponseCompletedEvent' - - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' - - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' - - $ref: '#/components/schemas/BetaResponseCreatedEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' - x-stainless-skip: - - go - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' - - $ref: '#/components/schemas/BetaResponseInProgressEvent' - - $ref: '#/components/schemas/BetaResponseFailedEvent' - - $ref: '#/components/schemas/BetaResponseIncompleteEvent' - - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' - - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' - - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' - - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' - - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' - - $ref: '#/components/schemas/BetaResponseQueuedEvent' - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' + - role + - content + BetaResponseSteerPendingEvent: + type: object + title: ResponseSteerPendingEvent + description: | + Emitted when accepted steering input remains queued after the target + response completes. The server still owns the input. Do not resend it. + The successor's `response.created` event is the commit point. + + When `reason` is `waiting_for_required_input`, this event follows + `response.completed` while the response waits for the tool results or + approval decisions identified by `required_input`. Copy those stubs, fill + their result fields using the ordinary `response.create` input schemas, + and submit one continuation per parent with the same `previous_response_id` + and WebSocket lane. Use saved results without rerunning tools. The queued + steering input is prepended in submission order to the continuation's + input. That explicit request retains its own settings. + + This notification is emitted at most once per steering submission. Multiple + submissions for the same parent can report the same required inputs; they + do not each require a separate continuation. + properties: + type: + type: string + enum: + - response.steer.pending + description: The event discriminator. Always `response.steer.pending`. + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number for this event. + steer: + type: object + description: The steering submission that remains queued. + properties: + id: + type: string + description: The ID assigned to the steering submission. + previous_response_id: + type: string + description: The ID of the response being steered. + required: + - id + - previous_response_id + reason: + $ref: '#/components/schemas/BetaResponseSteerPendingReason' + required_input: + type: array + minItems: 1 + description: | + Input stubs identifying outstanding client-owned tool results or + approval decisions. Each stub contains identifying fields only; the + client supplies the result before including it in `response.create`. + items: + $ref: '#/components/schemas/BetaResponseSteerRequiredInput' + stream_id: + type: string + description: | + The WebSocket lane that emitted this event. This field is present when + the target response's `response.create` event supplied a `stream_id`. + required: + - type + - sequence_number + - steer + - reason + - required_input + x-oaiMeta: + name: response.steer.pending + group: responses + example: | + { + "type": "response.steer.pending", + "sequence_number": 10, + "steer": { + "id": "steer_456", + "previous_response_id": "resp_123" + }, + "reason": "waiting_for_required_input", + "required_input": [ + { + "type": "function_call_output", + "call_id": "call_789", + "name": "lookup" + } + ] + } + BetaResponseSteerRequiredInput: + title: ResponseSteerRequiredInput + description: | + An input stub identifying an outstanding client-owned tool result or + approval decision. Copy the stub and fill the result fields using the + corresponding `response.create` input schema. Use saved results without + rerunning the tool. The server does not supply results, approval decisions, + or safety acknowledgements in these stubs. + discriminator: + propertyName: type + anyOf: + - type: object + title: Required function tool call output + additionalProperties: false + description: | + Supply `output` using the function tool call output input schema. + properties: + type: + type: string + enum: + - function_call_output + x-stainless-const: true + call_id: + type: string + name: + type: string + required: + - type + - call_id + - name + - type: object + title: Required custom tool call output + additionalProperties: false + description: | + Supply `output` using the custom tool call output input schema. The + original custom tool call supplies the tool's name. + properties: + type: + type: string + enum: + - custom_tool_call_output + x-stainless-const: true + call_id: + type: string + required: + - type + - call_id + - type: object + title: Required computer tool call output + additionalProperties: false + description: | + Supply `output` using the computer tool call output input schema, + including any required `acknowledged_safety_checks`. + properties: + type: + type: string + enum: + - computer_call_output + x-stainless-const: true + call_id: + type: string + required: + - type + - call_id + - type: object + title: Required shell tool call output + additionalProperties: false + description: | + Supply `output` using the shell tool call output input schema. Each + output entry includes `stdout`, `stderr`, and `outcome`. + properties: + type: + type: string + enum: + - shell_call_output + x-stainless-const: true + call_id: + type: string + required: + - type + - call_id - type: object + title: Required apply patch tool call output + additionalProperties: false + description: | + Supply `status` and optional `output` using the apply patch tool call + output input schema. properties: - stream_id: + type: type: string - description: | - The WebSocket lane that emitted this event. This field is present - when the originating `response.create` event supplied a - `stream_id`. - BetaResponsesClientEvent: - discriminator: - propertyName: type - description: | - Client events accepted by the Responses WebSocket server. - anyOf: - - $ref: '#/components/schemas/BetaResponsesClientEventResponseCreate' - - $ref: '#/components/schemas/BetaResponseSteerEvent' - - $ref: '#/components/schemas/BetaResponseInjectEvent' - BetaResponseInjectEvent: - type: object - title: ResponseInjectEvent - description: | - Injects input items into an active response over a WebSocket connection. - The items are validated and committed atomically. Currently, the server - accepts client-owned tool outputs that resume a waiting agent. - properties: - type: - type: string - enum: - - response.inject - description: The event discriminator. Always `response.inject`. - x-stainless-const: true - response_id: - type: string - description: The ID of the active response that should receive the input. - input: - type: array - maxItems: 16384 - description: Input items to inject into the active response. - items: - $ref: '#/components/schemas/BetaInputItem' - required: - - type - - response_id - - input - x-oai-beta: responses_multi_agent=v1 - x-oaiMeta: - example: | - { - "type": "response.inject", - "response_id": "resp_123", - "input": [ - { - "type": "function_call_output", - "call_id": "call_123", - "output": "{\"temperature\":72}" - } - ] - } - BetaResponsesClientEventResponseCreate: - allOf: + enum: + - apply_patch_call_output + x-stainless-const: true + call_id: + type: string + required: + - type + - call_id - type: object + title: Required tool search output + additionalProperties: false + description: | + Supply `tools` using the tool search output input schema, retaining + `execution: "client"`. properties: type: type: string enum: - - response.create - description: | - The type of the client event. Always `response.create`. + - tool_search_output x-stainless-const: true - stream_id: + call_id: type: string - minLength: 1 - maxLength: 256 - pattern: ^[A-Za-z0-9_.-]+$ - description: | - The WebSocket lane for this response. Requests with the same - `stream_id` are processed FIFO, and events for the response echo the - same `stream_id`. - - `stream_id` controls routing; `previous_response_id` controls - conversation lineage, so a new lane can fork from a response created - on another lane. + execution: + type: string + enum: + - client + x-stainless-const: true required: - type - - $ref: '#/components/schemas/BetaCreateResponse' - description: | - Client event for creating a response over a persistent WebSocket connection. - This payload uses the same top-level fields as `POST /v1/responses`, plus - WebSocket-only envelope metadata. - - Notes: - - `stream` is implicit over WebSocket and should not be sent. - - `background` is not supported over WebSocket. - - `stream_id` is WebSocket-only and is not part of `POST /v1/responses`. - x-oaiMeta: - example: | - { - "type": "response.create", - "stream_id": "agent_1", - "model": "gpt-6-astra", - "input": "Say hello." - } - BetaCreateResponse: - allOf: - - $ref: '#/components/schemas/BetaCreateModelResponseProperties' - - $ref: '#/components/schemas/BetaResponseProperties' + - call_id + - execution - type: object + title: Required MCP approval response + additionalProperties: false + description: | + Supply `approve` using the MCP approval response input schema. An + optional `reason` can be supplied when denying the request. The original + approval request identifies the tool and server. properties: - prompt_cache_options: - $ref: '#/components/schemas/BetaResponsePromptCacheOptionsParam' - service_tier: - $ref: '#/components/schemas/BetaServiceTierResponses' - truncation: - deprecated: true - anyOf: - - type: string - description: | - The truncation strategy to use for the model response. - - `auto`: If the input to this Response exceeds - the model's context window size, the model will truncate the - response to fit the context window by dropping items from the beginning of the conversation. - - `disabled` (default): If the input size will exceed the context window - size for a model, the request will fail with a 400 error. - enum: - - auto - - disabled - default: disabled - - type: 'null' - reasoning: - anyOf: - - $ref: '#/components/schemas/BetaReasoning' - - type: 'null' - input: - $ref: '#/components/schemas/BetaInputParam' - include: - anyOf: - - type: array - description: |- - Specify additional output data to include in the model response. Currently supported values are: - - `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). - items: - $ref: '#/components/schemas/BetaIncludeEnum' - - type: 'null' - parallel_tool_calls: - anyOf: - - type: boolean - description: | - Whether to allow the model to run tool calls in parallel. - default: true - - type: 'null' - store: - anyOf: - - type: boolean - description: | - Whether to store the generated model response for later retrieval via - API. - Defaults to true when omitted. - If set to true, response data will be stored for at least 30 days, subject to the [data retention exceptions](https://developers.openai.com/api/docs/guides/your-data#v1responses). - default: true - - type: 'null' - instructions: - anyOf: - - type: string - description: | - A system (or developer) message inserted into the model's context. - - When using along with `previous_response_id`, the instructions from a previous - response will not be carried over to the next response. This makes it simple - to swap out system (or developer) messages in new responses. - - type: 'null' - moderation: - anyOf: - - $ref: '#/components/schemas/BetaModerationParam' - description: | - Configuration for running moderation on the input and output of this response. - - type: 'null' - stream: - anyOf: - - description: | - If set to true, the model response data will be streamed to the client - as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). - See the [Streaming section below](https://developers.openai.com/api/reference/resources/responses/streaming-events) - for more information. - type: boolean - default: false - - type: 'null' - stream_options: - $ref: '#/components/schemas/BetaResponseStreamOptions' - conversation: - anyOf: - - $ref: '#/components/schemas/BetaConversationParam' - - type: 'null' - context_management: - anyOf: - - type: array - example: - - type: compaction - compact_threshold: 1000 - description: | - Context management configuration for this request. - minItems: 1 - items: - $ref: '#/components/schemas/BetaContextManagementParam' - - type: 'null' - max_output_tokens: - anyOf: - - description: | - An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning). - type: integer - minimum: 16 - - type: 'null' - multi_agent: - anyOf: - - $ref: '#/components/schemas/BetaMultiAgentParam' - description: Configuration for server-hosted multi-agent execution. - - type: 'null' - BetaMultiAgentParam: - properties: - enabled: - type: boolean - description: Whether to enable server-hosted multi-agent execution for this response. - max_concurrent_subagents: - type: integer - minimum: 1 - description: |- - `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. - The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + type: + type: string + enum: + - mcp_approval_response + x-stainless-const: true + approval_request_id: + type: string + required: + - type + - approval_request_id + BetaResponseSteerPendingReason: + title: ResponseSteerPendingReason + description: | + An extensible enum describing why accepted steering input is still queued. + Clients should handle unknown values because additional reasons may be + introduced. Known values include: + - `waiting_for_required_input`: The response is waiting for the tool results or approval decisions identified by `required_input`. + anyOf: + - type: string + enum: + - waiting_for_required_input + - type: string + BetaResponseSteerAcceptedEvent: type: object - required: - - enabled - description: Configuration for server-hosted multi-agent execution. - x-oai-beta: responses_multi_agent=v1 - BetaContextManagementParam: + title: ResponseSteerAcceptedEvent + description: | + Emitted when steering input has been validated and queued. Acceptance means + the server owns the input, not that it has been applied. The successor's + `response.created` event is the commit point. If accepted input cannot be + committed, `response.steer.failed` returns it with the same steering ID. + + When the response stops for client-owned tool output or approval, the input + remains queued and `response.steer.pending` is emitted after + `response.completed`. Fill the pending event's `required_input` stubs with + saved results and send one matching explicit `response.create` per parent. + Do not resend accepted input while it is still queued. properties: type: type: string - description: The context management entry type. Currently only 'compaction' is supported. - compact_threshold: - anyOf: - - type: integer - minimum: 1000 - description: Token threshold at which compaction should be triggered for this entry. - - type: 'null' - type: object - required: - - type - BetaResponseStreamOptions: - anyOf: - - description: | - Options for streaming responses. Only set this when you set `stream: true`. - type: object - properties: - include_obfuscation: - type: boolean - description: | - When true, stream obfuscation will be enabled. Stream obfuscation adds - random characters to an `obfuscation` field on streaming delta events to - normalize payload sizes as a mitigation to certain side-channel attacks. - These obfuscation fields are included by default, but add a small amount - of overhead to the data stream. You can set `include_obfuscation` to - false to optimize for bandwidth if you trust the network links between - your application and the OpenAI API. - - type: 'null' - BetaModerationParam: - properties: - model: + enum: + - response.steer.accepted + description: The event discriminator. Always `response.steer.accepted`. + x-stainless-const: true + sequence_number: + type: integer + description: The sequence number for this event. + steer: + type: object + description: The accepted steering submission. + properties: + id: + type: string + description: The ID assigned to the steering submission. + previous_response_id: + type: string + description: The ID of the response being steered. + required: + - id + - previous_response_id + stream_id: type: string - description: The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - policy: - anyOf: - - $ref: '#/components/schemas/BetaModerationPolicyParam' - description: The policy to apply to moderated response input and output. - - type: 'null' - type: object - required: - - model - description: Configuration for running moderation on the input and output of this response. - BetaModerationPolicyParam: - properties: - input: - anyOf: - - $ref: '#/components/schemas/BetaModerationConfigParam' - description: The moderation policy for the response input. - - type: 'null' - output: - anyOf: - - $ref: '#/components/schemas/BetaModerationConfigParam' - description: The moderation policy for the response output. - - type: 'null' - type: object - required: [] - description: The policy to apply to moderated response input and output. - BetaModerationConfigParam: - properties: - mode: - $ref: '#/components/schemas/BetaModerationMode' - type: object + description: | + The WebSocket lane that emitted this event. This field is present when + the target response's `response.create` event supplied a `stream_id`. required: - - mode - description: The moderation policy for the response input. - BetaModerationMode: - type: string - enum: - - score - - block - BetaResponsePromptCacheOptionsParam: - properties: - ttl: - $ref: '#/components/schemas/BetaPromptCacheTTLEnum' - description: The minimum lifetime applied to every implicit and explicit cache breakpoint written by the request. Defaults to `30m`, which is currently the only supported value. The backend may retain cache entries for longer. - mode: - $ref: '#/components/schemas/BetaPromptCacheModeEnum' - description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching. - prewarm: - type: boolean - description: Prepares the prompt cache without generating output. Defaults to `false`. When set to `true`, overrides the `generate` field to `false`. - comparison_response_id: - anyOf: - - type: string - description: The ID of a response to compare when diagnosing prompt cache reuse. Supplying this field requests prompt cache diagnostics when the feature is enabled. - example: resp_123 - - type: 'null' - type: object - required: [] - title: Prompt cache options - description: Options for prompt caching. Supported for `gpt-5.6` and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The `ttl` defaults to `30m`, which is currently the only supported value. See the [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) for current details. - BetaCreateModelResponseProperties: - allOf: - - $ref: '#/components/schemas/BetaModelResponseProperties' - - type: object - properties: - prompt_cache_options: - $ref: '#/components/schemas/BetaPromptCacheOptionsParam' - top_logprobs: - description: | - An integer between 0 and 20 specifying the maximum number of most likely - tokens to return at each token position, each with an associated log - probability. In some cases, the number of returned tokens may be fewer than - requested. - type: integer - minimum: 0 - maximum: 20 - BetaResponseStreamEvent: - description: Event emitted while a response is streamed. - anyOf: - - $ref: '#/components/schemas/BetaResponseAudioDeltaEvent' - - $ref: '#/components/schemas/BetaResponseAudioDoneEvent' - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDeltaEvent' - - $ref: '#/components/schemas/BetaResponseAudioTranscriptDoneEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDeltaEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCodeDoneEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseCodeInterpreterCallInterpretingEvent' - - $ref: '#/components/schemas/BetaResponseCompactionCompactingStreamingEvent' - - $ref: '#/components/schemas/BetaResponseCompletedEvent' - - $ref: '#/components/schemas/BetaResponseContentPartAddedEvent' - - $ref: '#/components/schemas/BetaResponseContentPartDoneEvent' - - $ref: '#/components/schemas/BetaResponseCreatedEvent' - - $ref: '#/components/schemas/BetaResponseErrorEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseFileSearchCallSearchingEvent' - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDeltaEvent' - - $ref: '#/components/schemas/BetaResponseFunctionCallArgumentsDoneEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandAddedStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandDeltaStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallCommandDoneStreamingEvent' - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDeltaStreamingEvent' - x-stainless-skip: - - go - - $ref: '#/components/schemas/BetaResponseShellCallOutputContentDoneStreamingEvent' - - $ref: '#/components/schemas/BetaResponseInProgressEvent' - - $ref: '#/components/schemas/BetaResponseFailedEvent' - - $ref: '#/components/schemas/BetaResponseIncompleteEvent' - - $ref: '#/components/schemas/BetaResponseOutputItemAddedEvent' - - $ref: '#/components/schemas/BetaResponseOutputItemDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartAddedEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryPartDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseReasoningSummaryTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseReasoningTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseReasoningTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseRefusalDeltaEvent' - - $ref: '#/components/schemas/BetaResponseRefusalDoneEvent' - - $ref: '#/components/schemas/BetaResponseTextDeltaEvent' - - $ref: '#/components/schemas/BetaResponseTextDoneEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseWebSearchCallSearchingEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallGeneratingEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseImageGenCallPartialImageEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDeltaEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallArgumentsDoneEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallCompletedEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallFailedEvent' - - $ref: '#/components/schemas/BetaResponseMCPCallInProgressEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsCompletedEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsFailedEvent' - - $ref: '#/components/schemas/BetaResponseMCPListToolsInProgressEvent' - - $ref: '#/components/schemas/BetaResponseOutputTextAnnotationAddedEvent' - - $ref: '#/components/schemas/BetaResponseQueuedEvent' - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDeltaEvent' - - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent' - discriminator: - propertyName: type + - type + - sequence_number + - steer + x-oaiMeta: + name: response.steer.accepted + group: responses + example: | + { + "type": "response.steer.accepted", + "sequence_number": 2, + "steer": { + "id": "steer_456", + "previous_response_id": "resp_123" + } + } OAuthErrorCode: anyOf: - enum: diff --git a/pkg/cmd/audioresponse_test.go b/pkg/cmd/audioresponse_test.go new file mode 100644 index 00000000..23db0168 --- /dev/null +++ b/pkg/cmd/audioresponse_test.go @@ -0,0 +1,120 @@ +package cmd + +import ( + "encoding/json" + "io" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "testing" + + "github.com/urfave/cli/v3" +) + +func TestAudioResponsesPreserveCompletePlaintext(t *testing.T) { + for _, endpoint := range []string{"transcriptions", "translations"} { + for _, test := range []struct { + name string + format string + body string + }{ + {name: "text", format: "text", body: "first line\n世界 👋\n"}, + {name: "srt", format: "srt", body: "1\n00:00:00,000 --> 00:00:01,000\nhello\n\n"}, + {name: "vtt", format: "vtt", body: "WEBVTT\n\n00:00.000 --> 00:01.000\nhello\n"}, + {name: "empty", format: "text", body: ""}, + {name: "json_object", format: "text", body: `{"text":"still a transcript"}`}, + {name: "json_number", format: "text", body: "123\n"}, + } { + t.Run(endpoint+"/"+test.name, func(t *testing.T) { + output := runAudioResponseCommand(t, endpoint, test.format, "text/plain; charset=utf-8", test.body, "--format", "json") + var got string + if err := json.Unmarshal([]byte(output), &got); err != nil { + t.Fatalf("%s create(%q) output = %q, want JSON string: %v", endpoint, test.format, output, err) + } + if got != test.body { + t.Errorf("%s create(%q) text = %q, want %q", endpoint, test.format, got, test.body) + } + }) + } + } +} + +func TestAudioResponsesPreserveRawPlaintext(t *testing.T) { + const body = "first line\n\x1b[31m世界\r\n" + for _, endpoint := range []string{"transcriptions", "translations"} { + t.Run(endpoint, func(t *testing.T) { + got := runAudioResponseCommand(t, endpoint, "text", "text/plain", body, "--raw-output") + if want := body + "\n"; got != want { + t.Errorf("%s create(--raw-output) = %q, want %q", endpoint, got, want) + } + }) + } +} + +func TestAudioResponsesPreserveOtherMedia(t *testing.T) { + const body = `{ "text": "whole response", "segments": [{"speaker": "speaker_0"}], "extra": null }` + for _, endpoint := range []string{"transcriptions", "translations"} { + for _, media := range []string{"application/json", "", "application/octet-stream", "text/plain; charset", "text/plain; charset=utf-8; charset=ascii"} { + t.Run(endpoint+"/"+media, func(t *testing.T) { + got := runAudioResponseCommand(t, endpoint, "json", media, body, "--format", "raw") + if want := body + "\n"; got != want { + t.Errorf("%s create(Content-Type %q) = %q, want %q", endpoint, media, got, want) + } + }) + } + } +} + +func runAudioResponseCommand(t *testing.T, endpoint, format, media, body string, flags ...string) string { + t.Helper() + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if want := "/audio/" + endpoint; r.URL.Path != want { + t.Errorf("audio request path = %q, want %q", r.URL.Path, want) + } + w.Header()["Content-Type"] = []string{media} + _, _ = io.WriteString(w, body) + })) + t.Cleanup(server.Close) + dir := t.TempDir() + input := filepath.Join(dir, "audio.wav") + if err := os.WriteFile(input, []byte("synthetic audio"), 0o600); err != nil { + t.Fatal(err) + } + output, err := os.Create(filepath.Join(dir, "output")) + if err != nil { + t.Fatal(err) + } + previousStdout := os.Stdout + os.Stdout = output + t.Cleanup(func() { + os.Stdout = previousStdout + output.Close() + }) + t.Setenv("FORCE_COLOR", "0") + audio := audioTranscriptionsCreate + if endpoint == "translations" { + audio = audioTranslationsCreate + } + command := &cli.Command{ + Name: "openai", + Flags: []cli.Flag{ + &cli.BoolFlag{Name: "debug"}, + &cli.StringFlag{Name: "base-url"}, + &cli.StringFlag{Name: "api-key"}, + &cli.StringFlag{Name: "format", Value: "auto"}, + &cli.BoolFlag{Name: "raw-output"}, + }, + Commands: []*cli.Command{{Name: "audio:" + endpoint, Commands: []*cli.Command{&audio}}}, + } + args := append([]string{"openai", "--base-url", server.URL + "/", "--api-key", "synthetic-test-key"}, flags...) + args = append(args, "audio:"+endpoint, "create", "--file", input, "--model", "whisper-1", "--response-format", format) + if err := command.Run(t.Context(), args); err != nil { + t.Fatalf("%s create(%q) error = %v, want success", endpoint, format, err) + } + got, err := os.ReadFile(output.Name()) + if err != nil { + t.Fatal(err) + } + return string(got) +} diff --git a/pkg/cmd/audiotranscription.go b/pkg/cmd/audiotranscription.go index 10d079d1..478e2f79 100644 --- a/pkg/cmd/audiotranscription.go +++ b/pkg/cmd/audiotranscription.go @@ -4,7 +4,10 @@ package cmd import ( "context" + "encoding/json" "fmt" + "mime" + "net/http" "github.com/openai/openai-cli/internal/apiquery" "github.com/openai/openai-cli/internal/requestflag" @@ -144,12 +147,16 @@ func handleAudioTranscriptionsCreate(ctx context.Context, cmd *cli.Command) erro }) } else { var res []byte - options = append(options, option.WithResponseBodyInto(&res)) + var response *http.Response + options = append(options, option.WithResponseBodyInto(&res), option.WithResponseInto(&response)) _, err = client.Audio.Transcriptions.New(ctx, params, options...) if err != nil { return err } + if mediaType, _, err := mime.ParseMediaType(response.Header.Get("Content-Type")); err == nil && mediaType == "text/plain" { + res, _ = json.Marshal(string(res)) + } obj := gjson.ParseBytes(res) return ShowJSON(obj, ShowJSONOpts{ ExplicitFormat: explicitFormat, diff --git a/pkg/cmd/audiotranslation.go b/pkg/cmd/audiotranslation.go index 997954d3..5ae5a9b5 100644 --- a/pkg/cmd/audiotranslation.go +++ b/pkg/cmd/audiotranslation.go @@ -4,7 +4,10 @@ package cmd import ( "context" + "encoding/json" "fmt" + "mime" + "net/http" "github.com/openai/openai-cli/internal/apiquery" "github.com/openai/openai-cli/internal/requestflag" @@ -76,12 +79,16 @@ func handleAudioTranslationsCreate(ctx context.Context, cmd *cli.Command) error params := openai.AudioTranslationNewParams{} var res []byte - options = append(options, option.WithResponseBodyInto(&res)) + var response *http.Response + options = append(options, option.WithResponseBodyInto(&res), option.WithResponseInto(&response)) _, err = client.Audio.Translations.New(ctx, params, options...) if err != nil { return err } + if mediaType, _, err := mime.ParseMediaType(response.Header.Get("Content-Type")); err == nil && mediaType == "text/plain" { + res, _ = json.Marshal(string(res)) + } obj := gjson.ParseBytes(res) format := cmd.Root().String("format") explicitFormat := cmd.Root().IsSet("format")