From 085bababf94525ed0c8f9e000c956d0fc740a457 Mon Sep 17 00:00:00 2001 From: Kevin Whinnery Date: Tue, 11 Mar 2025 11:50:51 -0500 Subject: [PATCH] Update openapi.yaml --- openapi.yaml | 30811 ++++++++++++++++++++++++++++++------------------- 1 file changed, 18861 insertions(+), 11950 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 96ad028d..4794d451 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -673,6 +673,24 @@ paths: } main(); + csharp: | + using System; + using System.IO; + + using OpenAI.Audio; + + AudioClient client = new( + model: "tts-1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + BinaryData speech = client.GenerateSpeech( + text: "The quick brown fox jumped over the lazy dog.", + voice: GeneratedSpeechVoice.Alloy + ); + + using FileStream stream = File.OpenWrite("speech.mp3"); + speech.ToStream().CopyTo(stream); /audio/transcriptions: post: operationId: createTranscription @@ -737,6 +755,26 @@ paths: } main(); + csharp: > + using System; + + + using OpenAI.Audio; + + string audioFilePath = "audio.mp3"; + + + AudioClient client = new( + model: "whisper-1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + AudioTranscription transcription = + client.TranscribeAudio(audioFilePath); + + + Console.WriteLine($"{transcription.Text}"); response: > { "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that." @@ -785,6 +823,35 @@ paths: } main(); + csharp: > + using System; + + + using OpenAI.Audio; + + + string audioFilePath = "audio.mp3"; + + + AudioClient client = new( + model: "whisper-1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + AudioTranscriptionOptions options = new() + + { + ResponseFormat = AudioTranscriptionFormat.Verbose, + TimestampGranularities = AudioTimestampGranularities.Word, + }; + + + AudioTranscription transcription = + client.TranscribeAudio(audioFilePath, options); + + + Console.WriteLine($"{transcription.Text}"); response: > { "task": "transcribe", @@ -849,6 +916,35 @@ paths: } main(); + csharp: > + using System; + + + using OpenAI.Audio; + + + string audioFilePath = "audio.mp3"; + + + AudioClient client = new( + model: "whisper-1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + AudioTranscriptionOptions options = new() + + { + ResponseFormat = AudioTranscriptionFormat.Verbose, + TimestampGranularities = AudioTimestampGranularities.Segment, + }; + + + AudioTranscription transcription = + client.TranscribeAudio(audioFilePath, options); + + + Console.WriteLine($"{transcription.Text}"); response: > { "task": "transcribe", @@ -930,6 +1026,27 @@ paths: console.log(translation.text); } main(); + csharp: > + using System; + + + using OpenAI.Audio; + + + string audioFilePath = "audio.mp3"; + + + AudioClient client = new( + model: "whisper-1", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + AudioTranscription transcription = + client.TranscribeAudio(audioFilePath); + + + Console.WriteLine($"{transcription.Text}"); response: > { "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?" @@ -1322,11 +1439,144 @@ paths: } } /chat/completions: + get: + operationId: listChatCompletions + tags: + - Chat + summary: > + List stored Chat Completions. Only Chat Completions that have been + stored + + with the `store` parameter set to `true` will be returned. + parameters: + - name: model + in: query + description: The model used to generate the Chat Completions. + required: false + schema: + type: string + - name: metadata + in: query + description: | + A list of metadata keys to filter the Chat Completions by. Example: + + `metadata[key1]=value1&metadata[key2]=value2` + required: false + schema: + $ref: "#/components/schemas/Metadata" + - name: after + in: query + description: Identifier for the last chat completion from the previous + pagination request. + required: false + schema: + type: string + - name: limit + in: query + description: Number of Chat Completions to retrieve. + required: false + schema: + type: integer + default: 20 + - name: order + in: query + description: Sort order for Chat Completions by timestamp. Use `asc` for + ascending order or `desc` for descending order. Defaults to `asc`. + required: false + schema: + type: string + enum: + - asc + - desc + default: asc + responses: + "200": + description: A list of Chat Completions + content: + application/json: + schema: + $ref: "#/components/schemas/ChatCompletionList" + x-oaiMeta: + name: List Chat Completions + group: chat + returns: A list of [Chat Completions](/docs/api-reference/chat/list-object) + matching the specified filters. + path: list + examples: + request: + curl: | + curl https://api.openai.com/v1/chat/completions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + python: | + from openai import OpenAI + client = OpenAI() + + completions = client.chat.completions.list() + print(completions) + response: > + { + "object": "list", + "data": [ + { + "object": "chat.completion", + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "model": "gpt-4o-2024-08-06", + "created": 1738960610, + "request_id": "req_ded8ab984ec4bf840f37566c1011c417", + "tool_choice": null, + "usage": { + "total_tokens": 31, + "completion_tokens": 18, + "prompt_tokens": 13 + }, + "seed": 4944116822809979520, + "top_p": 1.0, + "temperature": 1.0, + "presence_penalty": 0.0, + "frequency_penalty": 0.0, + "system_fingerprint": "fp_50cad350e4", + "input_user": null, + "service_tier": "default", + "tools": null, + "metadata": {}, + "choices": [ + { + "index": 0, + "message": { + "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.", + "role": "assistant", + "tool_calls": null, + "function_call": null + }, + "finish_reason": "stop", + "logprobs": null + } + ], + "response_format": null + } + ], + "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "has_more": false + } post: operationId: createChatCompletion tags: - Chat summary: > + **Starting a new project?** We recommend trying + [Responses](/docs/api-reference/responses) + + to take advantage of the latest OpenAI platform features. Compare + + [Chat Completions with + Responses](/docs/guides/responses-vs-chat-completions?api-mode=responses). + + + --- + + Creates a model response for the given chat conversation. Learn more in the @@ -1408,7 +1658,7 @@ paths: print(completion.choices[0].message) - node.js: >- + node.js: > import OpenAI from "openai"; @@ -1427,33 +1677,61 @@ paths: main(); + csharp: | + using System; + using System.Collections.Generic; + + using OpenAI.Chat; + + ChatClient client = new( + model: "gpt-4o", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + List messages = + [ + new SystemChatMessage("You are a helpful assistant."), + new UserChatMessage("Hello!") + ]; + + ChatCompletion completion = client.CompleteChat(messages); + + Console.WriteLine(completion.Content[0].Text); response: | { - "id": "chatcmpl-123", + "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT", "object": "chat.completion", - "created": 1677652288, - "model": "gpt-4o-mini", - "system_fingerprint": "fp_44709d6fcb", - "choices": [{ - "index": 0, - "message": { - "role": "assistant", - "content": "\n\nHello there, how may I assist you today?", - }, - "logprobs": null, - "finish_reason": "stop" - }], - "service_tier": "default", + "created": 1741569952, + "model": "gpt-4o-2024-08-06", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "Hello! How can I assist you today?", + "refusal": null, + "annotations": [] + }, + "logprobs": null, + "finish_reason": "stop" + } + ], "usage": { - "prompt_tokens": 9, - "completion_tokens": 12, - "total_tokens": 21, + "prompt_tokens": 19, + "completion_tokens": 10, + "total_tokens": 29, + "prompt_tokens_details": { + "cached_tokens": 0, + "audio_tokens": 0 + }, "completion_tokens_details": { "reasoning_tokens": 0, + "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } - } + }, + "service_tier": "default" } - title: Image input request: @@ -1469,7 +1747,7 @@ paths: "content": [ { "type": "text", - "text": "What'\''s in this image?" + "text": "What is in this image?" }, { "type": "image_url", @@ -1510,7 +1788,7 @@ paths: print(response.choices[0]) - node.js: >- + node.js: > import OpenAI from "openai"; @@ -1534,38 +1812,76 @@ paths: ], }, ], - store: true, }); console.log(response.choices[0]); } main(); + csharp: > + using System; + + using System.Collections.Generic; + + + using OpenAI.Chat; + + + ChatClient client = new( + model: "gpt-4o", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + List messages = + + [ + new UserChatMessage( + [ + ChatMessageContentPart.CreateTextPart("What's in this image?"), + ChatMessageContentPart.CreateImagePart(new Uri("https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg")) + ]) + ]; + + + ChatCompletion completion = client.CompleteChat(messages); + + + Console.WriteLine(completion.Content[0].Text); response: > { - "id": "chatcmpl-123", + "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG", "object": "chat.completion", - "created": 1677652288, - "model": "gpt-4o-mini", - "system_fingerprint": "fp_44709d6fcb", - "choices": [{ - "index": 0, - "message": { - "role": "assistant", - "content": "\n\nThis image shows a wooden boardwalk extending through a lush green marshland.", - }, - "logprobs": null, - "finish_reason": "stop" - }], + "created": 1741570283, + "model": "gpt-4o-2024-08-06", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.", + "refusal": null, + "annotations": [] + }, + "logprobs": null, + "finish_reason": "stop" + } + ], "usage": { - "prompt_tokens": 9, - "completion_tokens": 12, - "total_tokens": 21, + "prompt_tokens": 1117, + "completion_tokens": 46, + "total_tokens": 1163, + "prompt_tokens_details": { + "cached_tokens": 0, + "audio_tokens": 0 + }, "completion_tokens_details": { "reasoning_tokens": 0, + "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } - } + }, + "service_tier": "default" } - title: Streaming request: @@ -1605,7 +1921,7 @@ paths: for chunk in completion: print(chunk.choices[0].delta) - node.js: >- + node.js: > import OpenAI from "openai"; @@ -1619,7 +1935,6 @@ paths: {"role": "developer", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ], - store: true, stream: true, }); @@ -1630,6 +1945,46 @@ paths: main(); + csharp: > + using System; + + using System.ClientModel; + + using System.Collections.Generic; + + using System.Threading.Tasks; + + + using OpenAI.Chat; + + + ChatClient client = new( + model: "gpt-4o", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + List messages = + + [ + new SystemChatMessage("You are a helpful assistant."), + new UserChatMessage("Hello!") + ]; + + + AsyncCollectionResult + completionUpdates = client.CompleteChatStreamingAsync(messages); + + + await foreach (StreamingChatCompletionUpdate completionUpdate in + completionUpdates) + + { + if (completionUpdate.ContentUpdate.Count > 0) + { + Console.Write(completionUpdate.ContentUpdate[0].Text); + } + } response: > {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", @@ -1661,7 +2016,7 @@ paths: "messages": [ { "role": "user", - "content": "What'\''s the weather like in Boston today?" + "content": "What is the weather like in Boston today?" } ], "tools": [ @@ -1728,7 +2083,7 @@ paths: print(completion) - node.js: >- + node.js: > import OpenAI from "openai"; @@ -1763,7 +2118,6 @@ paths: messages: messages, tools: tools, tool_choice: "auto", - store: true, }); console.log(response); @@ -1771,22 +2125,79 @@ paths: main(); - response: | - { - "id": "chatcmpl-abc123", - "object": "chat.completion", - "created": 1699896916, - "model": "gpt-4o-mini", - "choices": [ - { - "index": 0, - "message": { - "role": "assistant", - "content": null, - "tool_calls": [ + csharp: > + using System; + + using System.Collections.Generic; + + + using OpenAI.Chat; + + + ChatClient client = new( + model: "gpt-4o", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + ChatTool getCurrentWeatherTool = ChatTool.CreateFunctionTool( + functionName: "get_current_weather", + functionDescription: "Get the current weather in a given location", + functionParameters: BinaryData.FromString(""" { - "id": "call_abc123", - "type": "function", + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": [ "celsius", "fahrenheit" ] + } + }, + "required": [ "location" ] + } + """) + ); + + + List messages = + + [ + new UserChatMessage("What's the weather like in Boston today?"), + ]; + + + ChatCompletionOptions options = new() + + { + Tools = + { + getCurrentWeatherTool + }, + ToolChoice = ChatToolChoice.CreateAutoChoice(), + }; + + + ChatCompletion completion = client.CompleteChat(messages, + options); + response: | + { + "id": "chatcmpl-abc123", + "object": "chat.completion", + "created": 1699896916, + "model": "gpt-4o-mini", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": null, + "tool_calls": [ + { + "id": "call_abc123", + "type": "function", "function": { "name": "get_current_weather", "arguments": "{\n\"location\": \"Boston, MA\"\n}" @@ -1841,7 +2252,7 @@ paths: print(completion.choices[0].message) print(completion.choices[0].logprobs) - node.js: |- + node.js: | import OpenAI from "openai"; const openai = new OpenAI(); @@ -1850,7 +2261,6 @@ paths: const completion = await openai.chat.completions.create({ messages: [{ role: "user", content: "Hello!" }], model: "VAR_chat_model_id", - store: true, logprobs: true, top_logprobs: 2, }); @@ -1859,6 +2269,41 @@ paths: } main(); + csharp: > + using System; + + using System.Collections.Generic; + + + using OpenAI.Chat; + + + ChatClient client = new( + model: "gpt-4o", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + List messages = + + [ + new UserChatMessage("Hello!") + ]; + + + ChatCompletionOptions options = new() + + { + IncludeLogProbabilities = true, + TopLogProbabilityCount = 2 + }; + + + ChatCompletion completion = client.CompleteChat(messages, + options); + + + Console.WriteLine(completion.Content[0].Text); response: | { "id": "chatcmpl-123", @@ -2049,523 +2494,882 @@ paths: }, "system_fingerprint": null } - /completions: - post: - operationId: createCompletion + /chat/completions/{completion_id}: + get: + operationId: getChatCompletion tags: - - Completions - summary: Creates a completion for the provided prompt and parameters. - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateCompletionRequest" + - Chat + summary: > + Get a stored chat completion. Only Chat Completions that have been + created + + with the `store` parameter set to `true` will be returned. + parameters: + - in: path + name: completion_id + required: true + schema: + type: string + description: The ID of the chat completion to retrieve. responses: "200": - description: OK + description: A chat completion content: application/json: schema: - $ref: "#/components/schemas/CreateCompletionResponse" + $ref: "#/components/schemas/CreateChatCompletionResponse" x-oaiMeta: - name: Create completion - group: completions - returns: > - Returns a [completion](/docs/api-reference/completions/object) object, - or a sequence of completion objects if the request is streamed. - legacy: true + name: Get chat completion + group: chat + returns: The [ChatCompletion](/docs/api-reference/chat/object) object matching + the specified ID. examples: - - title: No streaming - request: - curl: | - curl https://api.openai.com/v1/completions \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "VAR_completion_model_id", - "prompt": "Say this is a test", - "max_tokens": 7, - "temperature": 0 - }' - python: | - from openai import OpenAI - client = OpenAI() - - client.completions.create( - model="VAR_completion_model_id", - prompt="Say this is a test", - max_tokens=7, - temperature=0 - ) - node.js: |- - import OpenAI from "openai"; - - const openai = new OpenAI(); + request: + curl: | + curl https://api.openai.com/v1/chat/completions/chatcmpl-abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + python: > + from openai import OpenAI - async function main() { - const completion = await openai.completions.create({ - model: "VAR_completion_model_id", - prompt: "Say this is a test.", - max_tokens: 7, - temperature: 0, - }); + client = OpenAI() - console.log(completion); - } - main(); - response: | - { - "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", - "object": "text_completion", - "created": 1589478378, - "model": "VAR_completion_model_id", - "system_fingerprint": "fp_44709d6fcb", - "choices": [ - { - "text": "\n\nThis is indeed a test", - "index": 0, - "logprobs": null, - "finish_reason": "length" - } - ], - "usage": { - "prompt_tokens": 5, - "completion_tokens": 7, - "total_tokens": 12 - } - } - - title: Streaming - request: - curl: | - curl https://api.openai.com/v1/completions \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "VAR_completion_model_id", - "prompt": "Say this is a test", - "max_tokens": 7, - "temperature": 0, - "stream": true - }' - python: | - from openai import OpenAI - client = OpenAI() - for chunk in client.completions.create( - model="VAR_completion_model_id", - prompt="Say this is a test", - max_tokens=7, - temperature=0, - stream=True - ): - print(chunk.choices[0].text) - node.js: |- - import OpenAI from "openai"; + completions = client.chat.completions.list() - const openai = new OpenAI(); + first_id = completions[0].id - async function main() { - const stream = await openai.completions.create({ - model: "VAR_completion_model_id", - prompt: "Say this is a test.", - stream: true, - }); + first_completion = + client.chat.completions.retrieve(completion_id=first_id) - for await (const chunk of stream) { - console.log(chunk.choices[0].text) - } + print(first_completion) + response: > + { + "object": "chat.completion", + "id": "chatcmpl-abc123", + "model": "gpt-4o-2024-08-06", + "created": 1738960610, + "request_id": "req_ded8ab984ec4bf840f37566c1011c417", + "tool_choice": null, + "usage": { + "total_tokens": 31, + "completion_tokens": 18, + "prompt_tokens": 13 + }, + "seed": 4944116822809979520, + "top_p": 1.0, + "temperature": 1.0, + "presence_penalty": 0.0, + "frequency_penalty": 0.0, + "system_fingerprint": "fp_50cad350e4", + "input_user": null, + "service_tier": "default", + "tools": null, + "metadata": {}, + "choices": [ + { + "index": 0, + "message": { + "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.", + "role": "assistant", + "tool_calls": null, + "function_call": null + }, + "finish_reason": "stop", + "logprobs": null } - main(); - response: | - { - "id": "cmpl-7iA7iJjj8V2zOkCGvWF2hAkDWBQZe", - "object": "text_completion", - "created": 1690759702, - "choices": [ - { - "text": "This", - "index": 0, - "logprobs": null, - "finish_reason": null - } - ], - "model": "gpt-3.5-turbo-instruct" - "system_fingerprint": "fp_44709d6fcb", - } - /embeddings: + ], + "response_format": null + } post: - operationId: createEmbedding + operationId: updateChatCompletion tags: - - Embeddings - summary: Creates an embedding vector representing the input text. + - Chat + summary: > + Modify a stored chat completion. Only Chat Completions that have been + + created with the `store` parameter set to `true` can be modified. + Currently, + + the only supported modification is to update the `metadata` field. + parameters: + - in: path + name: completion_id + required: true + schema: + type: string + description: The ID of the chat completion to update. requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/CreateEmbeddingRequest" + type: object + required: + - metadata + properties: + metadata: + $ref: "#/components/schemas/Metadata" responses: "200": - description: OK + description: A chat completion content: application/json: schema: - $ref: "#/components/schemas/CreateEmbeddingResponse" + $ref: "#/components/schemas/CreateChatCompletionResponse" x-oaiMeta: - name: Create embeddings - group: embeddings - returns: A list of [embedding](/docs/api-reference/embeddings/object) objects. + name: Update chat completion + group: chat + returns: The [ChatCompletion](/docs/api-reference/chat/object) object matching + the specified ID. examples: request: - curl: | - curl https://api.openai.com/v1/embeddings \ + curl: > + curl -X POST + https://api.openai.com/v1/chat/completions/chat_abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ - -d '{ - "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", - "encoding_format": "float" - }' - python: | + -d '{"metadata": {"foo": "bar"}}' + python: > from openai import OpenAI + client = OpenAI() - client.embeddings.create( - model="text-embedding-ada-002", - input="The food was delicious and the waiter...", - encoding_format="float" - ) - node.js: |- - import OpenAI from "openai"; - const openai = new OpenAI(); + completions = client.chat.completions.list() - async function main() { - const embedding = await openai.embeddings.create({ - model: "text-embedding-ada-002", - input: "The quick brown fox jumped over the lazy dog", - encoding_format: "float", - }); + first_id = completions[0].id - console.log(embedding); - } + updated_completion = + client.chat.completions.update(completion_id=first_id, + request_body={"metadata": {"foo": "bar"}}) - main(); - response: | + print(updated_completion) + response: > { - "object": "list", - "data": [ + "object": "chat.completion", + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "model": "gpt-4o-2024-08-06", + "created": 1738960610, + "request_id": "req_ded8ab984ec4bf840f37566c1011c417", + "tool_choice": null, + "usage": { + "total_tokens": 31, + "completion_tokens": 18, + "prompt_tokens": 13 + }, + "seed": 4944116822809979520, + "top_p": 1.0, + "temperature": 1.0, + "presence_penalty": 0.0, + "frequency_penalty": 0.0, + "system_fingerprint": "fp_50cad350e4", + "input_user": null, + "service_tier": "default", + "tools": null, + "metadata": { + "foo": "bar" + }, + "choices": [ { - "object": "embedding", - "embedding": [ - 0.0023064255, - -0.009327292, - .... (1536 floats total for ada-002) - -0.0028842222, - ], - "index": 0 + "index": 0, + "message": { + "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.", + "role": "assistant", + "tool_calls": null, + "function_call": null + }, + "finish_reason": "stop", + "logprobs": null } ], - "model": "text-embedding-ada-002", - "usage": { - "prompt_tokens": 8, - "total_tokens": 8 - } + "response_format": null } - /files: + delete: + operationId: deleteChatCompletion + tags: + - Chat + summary: | + Delete a stored chat completion. Only Chat Completions that have been + created with the `store` parameter set to `true` can be deleted. + parameters: + - in: path + name: completion_id + required: true + schema: + type: string + description: The ID of the chat completion to delete. + responses: + "200": + description: The chat completion was deleted successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ChatCompletionDeleted" + x-oaiMeta: + name: Delete chat completion + group: chat + returns: A deletion confirmation object. + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/chat/completions/chat_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + python: > + from openai import OpenAI + + client = OpenAI() + + + completions = client.chat.completions.list() + + first_id = completions[0].id + + delete_response = + client.chat.completions.delete(completion_id=first_id) + + print(delete_response) + response: | + { + "object": "chat.completion.deleted", + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "deleted": true + } + /chat/completions/{completion_id}/messages: get: - operationId: listFiles + operationId: getChatCompletionMessages tags: - - Files - summary: Returns a list of files. + - Chat + summary: | + Get the messages in a stored chat completion. Only Chat Completions that + have been created with the `store` parameter set to `true` will be + returned. parameters: - - in: query - name: purpose + - in: path + name: completion_id + required: true + schema: + type: string + description: The ID of the chat completion to retrieve messages from. + - name: after + in: query + description: Identifier for the last message from the previous pagination request. required: false schema: type: string - description: Only return files with the given purpose. - name: limit in: query - description: > - A limit on the number of objects to be returned. Limit can range - between 1 and 10,000, and the default is 10,000. + description: Number of messages to retrieve. required: false schema: type: integer - default: 10000 + default: 20 - name: order in: query - description: > - Sort order by the `created_at` timestamp of the objects. `asc` for - ascending order and `desc` for descending order. + description: Sort order for messages by timestamp. Use `asc` for ascending order + or `desc` for descending order. Defaults to `asc`. + required: false schema: type: string - default: desc enum: - asc - desc - - name: after - in: query - description: > - A cursor for use in pagination. `after` is an object ID that defines - your place in the list. For instance, if you make a list request and - receive 100 objects, ending with obj_foo, your subsequent call can - include after=obj_foo in order to fetch the next page of the list. - schema: - type: string + default: asc responses: "200": - description: OK + description: A list of messages content: application/json: schema: - $ref: "#/components/schemas/ListFilesResponse" + $ref: "#/components/schemas/ChatCompletionMessageList" x-oaiMeta: - name: List files - group: files - returns: A list of [File](/docs/api-reference/files/object) objects. + name: Get chat messages + group: chat + returns: A list of [messages](/docs/api-reference/chat/message-list) for the + specified chat completion. examples: request: - curl: | - curl https://api.openai.com/v1/files \ - -H "Authorization: Bearer $OPENAI_API_KEY" - python: | + curl: > + curl + https://api.openai.com/v1/chat/completions/chat_abc123/messages \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" + python: > from openai import OpenAI + client = OpenAI() - client.files.list() - node.js: |- - import OpenAI from "openai"; - const openai = new OpenAI(); + completions = client.chat.completions.list() - async function main() { - const list = await openai.files.list(); + first_id = completions[0].id - for await (const file of list) { - console.log(file); - } - } + first_completion = + client.chat.completions.retrieve(completion_id=first_id) - main(); + messages = + client.chat.completions.messages.list(completion_id=first_id) + + print(messages) response: | { + "object": "list", "data": [ { - "id": "file-abc123", - "object": "file", - "bytes": 175, - "created_at": 1613677385, - "filename": "salesOverview.pdf", - "purpose": "assistants", - }, - { - "id": "file-abc123", - "object": "file", - "bytes": 140, - "created_at": 1613779121, - "filename": "puppy.jsonl", - "purpose": "fine-tune", + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "role": "user", + "content": "write a haiku about ai", + "name": null, + "content_parts": null } ], - "object": "list" + "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "has_more": false } + /completions: post: - operationId: createFile + operationId: createCompletion tags: - - Files - summary: > - Upload a file that can be used across various endpoints. Individual - files can be up to 512 MB, and the size of all files uploaded by one - organization can be up to 100 GB. - - - The Assistants API supports files up to 2 million tokens and of specific - file types. See the [Assistants Tools guide](/docs/assistants/tools) for - details. - - - The Fine-tuning API only supports `.jsonl` files. The input also has - certain required formats for fine-tuning - [chat](/docs/api-reference/fine-tuning/chat-input) or - [completions](/docs/api-reference/fine-tuning/completions-input) models. - - - The Batch API only supports `.jsonl` files up to 200 MB in size. The - input also has a specific required - [format](/docs/api-reference/batch/request-input). - - - Please [contact us](https://help.openai.com/) if you need to increase - these storage limits. + - Completions + summary: Creates a completion for the provided prompt and parameters. requestBody: required: true content: - multipart/form-data: + application/json: schema: - $ref: "#/components/schemas/CreateFileRequest" + $ref: "#/components/schemas/CreateCompletionRequest" responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/OpenAIFile" + $ref: "#/components/schemas/CreateCompletionResponse" x-oaiMeta: - name: Upload file - group: files - returns: The uploaded [File](/docs/api-reference/files/object) object. + name: Create completion + group: completions + returns: > + Returns a [completion](/docs/api-reference/completions/object) object, + or a sequence of completion objects if the request is streamed. + legacy: true examples: - request: - curl: | - curl https://api.openai.com/v1/files \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -F purpose="fine-tune" \ - -F file="@mydata.jsonl" - python: | - from openai import OpenAI - client = OpenAI() - - client.files.create( - file=open("mydata.jsonl", "rb"), - purpose="fine-tune" - ) - node.js: |- - import fs from "fs"; - import OpenAI from "openai"; + - title: No streaming + request: + curl: | + curl https://api.openai.com/v1/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "VAR_completion_model_id", + "prompt": "Say this is a test", + "max_tokens": 7, + "temperature": 0 + }' + python: | + from openai import OpenAI + client = OpenAI() - const openai = new OpenAI(); + client.completions.create( + model="VAR_completion_model_id", + prompt="Say this is a test", + max_tokens=7, + temperature=0 + ) + node.js: |- + import OpenAI from "openai"; - async function main() { - const file = await openai.files.create({ - file: fs.createReadStream("mydata.jsonl"), - purpose: "fine-tune", - }); + const openai = new OpenAI(); - console.log(file); + async function main() { + const completion = await openai.completions.create({ + model: "VAR_completion_model_id", + prompt: "Say this is a test.", + max_tokens: 7, + temperature: 0, + }); + + console.log(completion); + } + main(); + response: | + { + "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", + "object": "text_completion", + "created": 1589478378, + "model": "VAR_completion_model_id", + "system_fingerprint": "fp_44709d6fcb", + "choices": [ + { + "text": "\n\nThis is indeed a test", + "index": 0, + "logprobs": null, + "finish_reason": "length" + } + ], + "usage": { + "prompt_tokens": 5, + "completion_tokens": 7, + "total_tokens": 12 + } } + - title: Streaming + request: + curl: | + curl https://api.openai.com/v1/completions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "VAR_completion_model_id", + "prompt": "Say this is a test", + "max_tokens": 7, + "temperature": 0, + "stream": true + }' + python: | + from openai import OpenAI + client = OpenAI() - main(); - response: | - { - "id": "file-abc123", - "object": "file", - "bytes": 120000, - "created_at": 1677610602, - "filename": "mydata.jsonl", - "purpose": "fine-tune", - } - /files/{file_id}: - delete: - operationId: deleteFile + for chunk in client.completions.create( + model="VAR_completion_model_id", + prompt="Say this is a test", + max_tokens=7, + temperature=0, + stream=True + ): + print(chunk.choices[0].text) + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const stream = await openai.completions.create({ + model: "VAR_completion_model_id", + prompt: "Say this is a test.", + stream: true, + }); + + for await (const chunk of stream) { + console.log(chunk.choices[0].text) + } + } + main(); + response: | + { + "id": "cmpl-7iA7iJjj8V2zOkCGvWF2hAkDWBQZe", + "object": "text_completion", + "created": 1690759702, + "choices": [ + { + "text": "This", + "index": 0, + "logprobs": null, + "finish_reason": null + } + ], + "model": "gpt-3.5-turbo-instruct" + "system_fingerprint": "fp_44709d6fcb", + } + /embeddings: + post: + operationId: createEmbedding tags: - - Files - summary: Delete a file. - parameters: - - in: path - name: file_id - required: true - schema: - type: string - description: The ID of the file to use for this request. + - Embeddings + summary: Creates an embedding vector representing the input text. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateEmbeddingRequest" responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/DeleteFileResponse" + $ref: "#/components/schemas/CreateEmbeddingResponse" x-oaiMeta: - name: Delete file - group: files - returns: Deletion status. + name: Create embeddings + group: embeddings + returns: A list of [embedding](/docs/api-reference/embeddings/object) objects. examples: request: curl: | - curl https://api.openai.com/v1/files/file-abc123 \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_API_KEY" + curl https://api.openai.com/v1/embeddings \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "input": "The food was delicious and the waiter...", + "model": "text-embedding-ada-002", + "encoding_format": "float" + }' python: | from openai import OpenAI client = OpenAI() - client.files.delete("file-abc123") - node.js: |- + client.embeddings.create( + model="text-embedding-ada-002", + input="The food was delicious and the waiter...", + encoding_format="float" + ) + node.js: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { - const file = await openai.files.del("file-abc123"); + const embedding = await openai.embeddings.create({ + model: "text-embedding-ada-002", + input: "The quick brown fox jumped over the lazy dog", + encoding_format: "float", + }); - console.log(file); + console.log(embedding); } main(); + csharp: > + using System; + + + using OpenAI.Embeddings; + + + EmbeddingClient client = new( + model: "text-embedding-3-small", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + OpenAIEmbedding embedding = client.GenerateEmbedding(input: "The + quick brown fox jumped over the lazy dog"); + + ReadOnlyMemory vector = embedding.ToFloats(); + + + for (int i = 0; i < vector.Length; i++) + + { + Console.WriteLine($" [{i,4}] = {vector.Span[i]}"); + } response: | { - "id": "file-abc123", - "object": "file", - "deleted": true + "object": "list", + "data": [ + { + "object": "embedding", + "embedding": [ + 0.0023064255, + -0.009327292, + .... (1536 floats total for ada-002) + -0.0028842222, + ], + "index": 0 + } + ], + "model": "text-embedding-ada-002", + "usage": { + "prompt_tokens": 8, + "total_tokens": 8 + } } + /files: get: - operationId: retrieveFile + operationId: listFiles tags: - Files - summary: Returns information about a specific file. + summary: Returns a list of files. parameters: - - in: path - name: file_id - required: true + - in: query + name: purpose + required: false + schema: + type: string + description: Only return files with the given purpose. + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 10,000, and the default is 10,000. + required: false + schema: + type: integer + default: 10000 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. schema: type: string - description: The ID of the file to use for this request. responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/OpenAIFile" + $ref: "#/components/schemas/ListFilesResponse" x-oaiMeta: - name: Retrieve file + name: List files group: files - returns: The [File](/docs/api-reference/files/object) object matching the - specified ID. + returns: A list of [File](/docs/api-reference/files/object) objects. examples: request: curl: | - curl https://api.openai.com/v1/files/file-abc123 \ + curl https://api.openai.com/v1/files \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() - client.files.retrieve("file-abc123") + client.files.list() node.js: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { - const file = await openai.files.retrieve("file-abc123"); + const list = await openai.files.list(); - console.log(file); + for await (const file of list) { + console.log(file); + } } main(); response: | { - "id": "file-abc123", - "object": "file", - "bytes": 120000, - "created_at": 1677610602, - "filename": "mydata.jsonl", - "purpose": "fine-tune", - } - /files/{file_id}/content: + "data": [ + { + "id": "file-abc123", + "object": "file", + "bytes": 175, + "created_at": 1613677385, + "filename": "salesOverview.pdf", + "purpose": "assistants", + }, + { + "id": "file-abc123", + "object": "file", + "bytes": 140, + "created_at": 1613779121, + "filename": "puppy.jsonl", + "purpose": "fine-tune", + } + ], + "object": "list" + } + post: + operationId: createFile + tags: + - Files + summary: > + Upload a file that can be used across various endpoints. Individual + files can be up to 512 MB, and the size of all files uploaded by one + organization can be up to 100 GB. + + + The Assistants API supports files up to 2 million tokens and of specific + file types. See the [Assistants Tools guide](/docs/assistants/tools) for + details. + + + The Fine-tuning API only supports `.jsonl` files. The input also has + certain required formats for fine-tuning + [chat](/docs/api-reference/fine-tuning/chat-input) or + [completions](/docs/api-reference/fine-tuning/completions-input) models. + + + The Batch API only supports `.jsonl` files up to 200 MB in size. The + input also has a specific required + [format](/docs/api-reference/batch/request-input). + + + Please [contact us](https://help.openai.com/) if you need to increase + these storage limits. + requestBody: + required: true + content: + multipart/form-data: + schema: + $ref: "#/components/schemas/CreateFileRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/OpenAIFile" + x-oaiMeta: + name: Upload file + group: files + returns: The uploaded [File](/docs/api-reference/files/object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/files \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -F purpose="fine-tune" \ + -F file="@mydata.jsonl" + python: | + from openai import OpenAI + client = OpenAI() + + client.files.create( + file=open("mydata.jsonl", "rb"), + purpose="fine-tune" + ) + node.js: |- + import fs from "fs"; + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const file = await openai.files.create({ + file: fs.createReadStream("mydata.jsonl"), + purpose: "fine-tune", + }); + + console.log(file); + } + + main(); + response: | + { + "id": "file-abc123", + "object": "file", + "bytes": 120000, + "created_at": 1677610602, + "filename": "mydata.jsonl", + "purpose": "fine-tune", + } + /files/{file_id}: + delete: + operationId: deleteFile + tags: + - Files + summary: Delete a file. + parameters: + - in: path + name: file_id + required: true + schema: + type: string + description: The ID of the file to use for this request. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteFileResponse" + x-oaiMeta: + name: Delete file + group: files + returns: Deletion status. + examples: + request: + curl: | + curl https://api.openai.com/v1/files/file-abc123 \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.files.delete("file-abc123") + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const file = await openai.files.del("file-abc123"); + + console.log(file); + } + + main(); + response: | + { + "id": "file-abc123", + "object": "file", + "deleted": true + } + get: + operationId: retrieveFile + tags: + - Files + summary: Returns information about a specific file. + parameters: + - in: path + name: file_id + required: true + schema: + type: string + description: The ID of the file to use for this request. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/OpenAIFile" + x-oaiMeta: + name: Retrieve file + group: files + returns: The [File](/docs/api-reference/files/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/files/file-abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" + python: | + from openai import OpenAI + client = OpenAI() + + client.files.retrieve("file-abc123") + node.js: |- + import OpenAI from "openai"; + + const openai = new OpenAI(); + + async function main() { + const file = await openai.files.retrieve("file-abc123"); + + console.log(file); + } + + main(); + response: | + { + "id": "file-abc123", + "object": "file", + "bytes": 120000, + "created_at": 1677610602, + "filename": "mydata.jsonl", + "purpose": "fine-tune", + } + /files/{file_id}/content: get: operationId: downloadFile tags: @@ -2697,7 +3501,8 @@ paths: "n_epochs": "auto", } } - } + }, + "metadata": null } - title: Epochs request: @@ -2778,7 +3583,8 @@ paths: "n_epochs": 2, } } - } + }, + "metadata": null } - title: Validation file request: @@ -2836,7 +3642,8 @@ paths: "n_epochs": "auto", } } - } + }, + "metadata": null } - title: DPO request: @@ -2879,7 +3686,8 @@ paths: "n_epochs": "auto", } } - } + }, + "metadata": null } - title: W&B Integration request: @@ -2935,7 +3743,8 @@ paths: "n_epochs": "auto", } } - } + }, + "metadata": null } get: operationId: listPaginatedFineTuningJobs @@ -2957,6 +3766,19 @@ paths: schema: type: integer default: 20 + - in: query + name: metadata + required: false + schema: + type: object + nullable: true + additionalProperties: + type: string + style: deepObject + explode: true + description: > + Optional metadata filter. To filter, use the syntax `metadata[k]=v`. + Alternatively, set `metadata=null` to indicate no metadata. responses: "200": description: OK @@ -2971,8 +3793,10 @@ paths: job](/docs/api-reference/fine-tuning/object) objects. examples: request: - curl: | - curl https://api.openai.com/v1/fine_tuning/jobs?limit=2 \ + curl: > + curl + https://api.openai.com/v1/fine_tuning/jobs?limit=2&metadata[key]=value + \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI @@ -3007,7 +3831,10 @@ paths: "result_files": [], "status": "queued", "validation_file": null, - "training_file": "file-abc123" + "training_file": "file-abc123", + "metadata": { + "key": "value" + } }, { ... }, { ... } @@ -3410,6 +4237,23 @@ paths: console.log(image.data); } main(); + csharp: | + using System; + + using OpenAI.Images; + + ImageClient client = new( + model: "dall-e-2", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + GeneratedImage image = client.GenerateImageEdit( + imageFilePath: "otter.png", + prompt: "A cute baby sea otter wearing a beret", + maskFilePath: "mask.png" + ); + + Console.WriteLine(image.ImageUri); response: | { "created": 1589478378, @@ -3481,6 +4325,24 @@ paths: } main(); + csharp: > + using System; + + + using OpenAI.Images; + + + ImageClient client = new( + model: "dall-e-3", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + GeneratedImage image = client.GenerateImage(prompt: "A cute baby + sea otter."); + + + Console.WriteLine(image.ImageUri); response: | { "created": 1589478378, @@ -3547,12 +4409,30 @@ paths: console.log(image.data); } main(); - response: | - { - "created": 1589478378, - "data": [ - { - "url": "https://..." + csharp: > + using System; + + + using OpenAI.Images; + + + ImageClient client = new( + model: "dall-e-2", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + GeneratedImage image = + client.GenerateImageVariation(imageFilePath: "otter.png"); + + + Console.WriteLine(image.ImageUri); + response: | + { + "created": 1589478378, + "data": [ + { + "url": "https://..." }, { "url": "https://..." @@ -3600,6 +4480,19 @@ paths: } } main(); + csharp: | + using System; + + using OpenAI.Models; + + OpenAIModelClient client = new( + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + foreach (var model in client.GetModels().Value) + { + Console.WriteLine(model.Id); + } response: | { "object": "list", @@ -3674,6 +4567,18 @@ paths: } main(); + csharp: | + using System; + using System.ClientModel; + + using OpenAI.Models; + + OpenAIModelClient client = new( + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + ClientResult model = client.GetModel("babbage-002"); + Console.WriteLine(model.Value.Id); response: | { "id": "VAR_chat_model_id", @@ -3733,6 +4638,24 @@ paths: } main(); + csharp: > + using System; + + using System.ClientModel; + + + using OpenAI.Models; + + + OpenAIModelClient client = new( + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + ClientResult success = + client.DeleteModel("ft:gpt-4o-mini:acemeco:suffix:abc123"); + + Console.WriteLine(success); response: | { "id": "ft:gpt-4o-mini:acemeco:suffix:abc123", @@ -3798,6 +4721,23 @@ paths: } main(); + csharp: > + using System; + + using System.ClientModel; + + + using OpenAI.Moderations; + + + ModerationClient client = new( + model: "omni-moderation-latest", + apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") + ); + + + ClientResult moderation = + client.ClassifyText("I want to kill them."); response: | { "id": "modr-AB8CjOTu2jiq12hp1AQPfeqFWaORR", @@ -7183,475 +8123,761 @@ paths: "expires_at": 1234567890 } } - /threads: + /responses: post: - operationId: createThread + operationId: createResponse tags: - - Assistants - summary: Create a thread. + - Responses + summary: > + Creates a model response. Provide [text](/docs/guides/text) or + + [image](/docs/guides/images) inputs to generate + [text](/docs/guides/text) + + or [JSON](/docs/guides/structured-outputs) outputs. Have the model call + + your own [custom code](/docs/guides/function-calling) or use built-in + + [tools](/docs/guides/tools) like [web + search](/docs/guides/tools-web-search) + + or [file search](/docs/guides/tools-file-search) to use your own data + + as input for the model's response. requestBody: + required: true content: application/json: schema: - $ref: "#/components/schemas/CreateThreadRequest" + $ref: "#/components/schemas/CreateResponse" responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/ThreadObject" + $ref: "#/components/schemas/Response" + text/event-stream: + schema: + $ref: "#/components/schemas/ResponseStreamEvent" x-oaiMeta: - name: Create thread - group: threads - beta: true - returns: A [thread](/docs/api-reference/threads) object. + name: Create a model response + group: responses + returns: | + Returns a [Response](/docs/api-reference/responses/object) object. + path: create examples: - - title: Empty + - title: Text input request: - curl: | - curl https://api.openai.com/v1/threads \ + curl: > + curl https://api.openai.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '' - python: | - from openai import OpenAI - client = OpenAI() - - empty_thread = client.beta.threads.create() - print(empty_thread) - node.js: |- + -d '{ + "model": "gpt-4o", + "input": "Tell me a three sentence bedtime story about a unicorn." + }' + javascript: > import OpenAI from "openai"; - const openai = new OpenAI(); - - async function main() { - const emptyThread = await openai.beta.threads.create(); - console.log(emptyThread); - } + const openai = new OpenAI(); - main(); - response: | - { - "id": "thread_abc123", - "object": "thread", - "created_at": 1699012949, - "metadata": {}, - "tool_resources": {} - } - - title: Messages - request: - curl: | - curl https://api.openai.com/v1/threads \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "messages": [{ - "role": "user", - "content": "Hello, what is AI?" - }, { - "role": "user", - "content": "How does AI work? Explain it in simple terms." - }] - }' - python: | - from openai import OpenAI - client = OpenAI() - message_thread = client.beta.threads.create( - messages=[ - { - "role": "user", - "content": "Hello, what is AI?" - }, - { - "role": "user", - "content": "How does AI work? Explain it in simple terms." - }, - ] - ) + const response = await openai.responses.create({ + model: "gpt-4o", + input: "Tell me a three sentence bedtime story about a unicorn." + }); - print(message_thread) - node.js: >- - import OpenAI from "openai"; + console.log(response); + python: > + from openai import OpenAI - const openai = new OpenAI(); + client = OpenAI() - async function main() { - const messageThread = await openai.beta.threads.create({ - messages: [ - { - role: "user", - content: "Hello, what is AI?" - }, - { - role: "user", - content: "How does AI work? Explain it in simple terms.", - }, - ], - }); - console.log(messageThread); - } + response = client.responses.create( + model="gpt-4o", + input="Tell me a three sentence bedtime story about a unicorn." + ) - main(); - response: | + print(response) + response: > { - "id": "thread_abc123", - "object": "thread", - "created_at": 1699014083, - "metadata": {}, - "tool_resources": {} + "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b", + "object": "response", + "created_at": 1741476542, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "message", + "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "In a peaceful grove beneath a silver moon, a unicorn named Lumina discovered a hidden pool that reflected the stars. As she dipped her horn into the water, the pool began to shimmer, revealing a pathway to a magical realm of endless night skies. Filled with wonder, Lumina whispered a wish for all who dream to find their own hidden magic, and as she glanced back, her hoofprints sparkled like stardust.", + "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": { + "input_tokens": 36, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 87, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 123 + }, + "user": null, + "metadata": {} } - /threads/runs: - post: - operationId: createThreadAndRun - tags: - - Assistants - summary: Create a thread and run it in one request. - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateThreadAndRunRequest" - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/RunObject" - x-oaiMeta: - name: Create thread and run - group: threads - beta: true - returns: A [run](/docs/api-reference/runs/object) object. - examples: - - title: Default + - title: Image input request: curl: > - curl https://api.openai.com/v1/threads/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ + curl https://api.openai.com/v1/responses \ -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ - "assistant_id": "asst_abc123", - "thread": { - "messages": [ - {"role": "user", "content": "Explain deep learning to a 5 year old."} + "model": "gpt-4o", + "input": [ + { + "role": "user", + "content": [ + {"type": "input_text", "text": "what is in this image?"}, + { + "type": "input_image", + "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" + } ] } - }' - python: > - from openai import OpenAI + ] + }' + javascript: > + import OpenAI from "openai"; - client = OpenAI() + const openai = new OpenAI(); - run = client.beta.threads.create_and_run( - assistant_id="asst_abc123", - thread={ - "messages": [ - {"role": "user", "content": "Explain deep learning to a 5 year old."} - ] - } - ) + const response = await openai.responses.create({ + model: "gpt-4o", + input: [ + { + role: "user", + content: [ + { type: "input_text", text: "what is in this image?" }, + { + type: "input_image", + image_url: + "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg", + }, + ], + }, + ], + }); - print(run) - node.js: > - import OpenAI from "openai"; + console.log(response); + python: > + from openai import OpenAI - const openai = new OpenAI(); + client = OpenAI() - async function main() { - const run = await openai.beta.threads.createAndRun({ - assistant_id: "asst_abc123", - thread: { - messages: [ - { role: "user", content: "Explain deep learning to a 5 year old." }, - ], - }, - }); - console.log(run); - } + response = client.responses.create( + model="gpt-4o", + input=[ + { + "role": "user", + "content": [ + { "type": "input_text", "text": "what is in this image?" }, + { + "type": "input_image", + "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" + } + ] + } + ] + ) - main(); - response: | + print(response) + response: > { - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699076792, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "queued", - "started_at": null, - "expires_at": 1699077392, - "cancelled_at": null, - "failed_at": null, - "completed_at": null, - "required_action": null, - "last_error": null, - "model": "gpt-4o", - "instructions": "You are a helpful assistant.", - "tools": [], - "tool_resources": {}, - "metadata": {}, + "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", + "object": "response", + "created_at": 1741476777, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "message", + "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.", + "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, - "max_completion_tokens": null, - "max_prompt_tokens": null, - "truncation_strategy": { - "type": "auto", - "last_messages": null + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 52, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 380 }, + "user": null, + "metadata": {} + } + - title: Web search + request: + curl: | + curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4o", + "tools": [{ "type": "web_search_preview" }], + "input": "What was a positive news story from today?" + }' + javascript: | + import OpenAI from "openai"; + + const openai = new OpenAI(); + + const response = await openai.responses.create({ + model: "gpt-4o", + tools: [{ type: "web_search_preview" }], + input: "What was a positive news story from today?", + }); + + console.log(response); + python: | + from openai import OpenAI + + client = OpenAI() + + response = client.responses.create( + model="gpt-4o", + tools=[{ "type": "web_search_preview" }], + input="What was a positive news story from today?", + ) + + print(response) + response: > + { + "id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c", + "object": "response", + "created_at": 1741484430, + "status": "completed", + "error": null, "incomplete_details": null, - "usage": null, - "response_format": "auto", + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "web_search_call", + "id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c", + "status": "completed" + }, + { + "type": "message", + "id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "As of today, March 9, 2025, one notable positive news story...", + "annotations": [ + { + "type": "url_citation", + "start_index": 442, + "end_index": 557, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + }, + { + "type": "url_citation", + "start_index": 962, + "end_index": 1077, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + }, + { + "type": "url_citation", + "start_index": 1336, + "end_index": 1451, + "url": "https://.../?utm_source=chatgpt.com", + "title": "..." + } + ] + } + ] + } + ], + "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", - "parallel_tool_calls": true + "tools": [ + { + "type": "web_search_preview", + "domains": [], + "search_context_size": "medium", + "user_location": { + "type": "approximate", + "city": null, + "country": "US", + "region": null, + "timezone": null + } + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 356, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 684 + }, + "user": null, + "metadata": {} } + - title: File search + request: + curl: > + curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4o", + "tools": [{ + "type": "file_search", + "vector_store_ids": ["vs_1234567890"], + "max_num_results": 20 + }], + "input": "What are the attributes of an ancient brown dragon?" + }' + javascript: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + const response = await openai.responses.create({ + model: "gpt-4o", + tools: [{ + type: "file_search", + vector_store_ids: ["vs_1234567890"], + max_num_results: 20 + }], + input: "What are the attributes of an ancient brown dragon?", + }); + + + console.log(response); + python: | + from openai import OpenAI + + client = OpenAI() + + response = client.responses.create( + model="gpt-4o", + tools=[{ + "type": "file_search", + "vector_store_ids": ["vs_1234567890"], + "max_num_results": 20 + }], + input="What are the attributes of an ancient brown dragon?", + ) + + print(response) + response: > + { + "id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7", + "object": "response", + "created_at": 1741485253, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "file_search_call", + "id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7", + "status": "completed", + "queries": [ + "attributes of an ancient brown dragon" + ], + "results": null + }, + { + "type": "message", + "id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The attributes of an ancient brown dragon include...", + "annotations": [ + { + "type": "file_citation", + "index": 320, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 576, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 815, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1030, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1156, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + }, + { + "type": "file_citation", + "index": 1225, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" + } + ] + } + ] + } + ], + "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": [ + { + "type": "file_search", + "filters": null, + "max_num_results": 20, + "ranking_options": { + "ranker": "auto", + "score_threshold": 0.0 + }, + "vector_store_ids": [ + "vs_1234567890" + ] + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 18307, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 348, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 18655 + }, + "user": null, + "metadata": {} + } - title: Streaming request: curl: | - curl https://api.openai.com/v1/threads/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ + curl https://api.openai.com/v1/responses \ -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ - "assistant_id": "asst_123", - "thread": { - "messages": [ - {"role": "user", "content": "Hello"} - ] - }, + "model": "gpt-4o", + "instructions": "You are a helpful assistant.", + "input": "Hello!", "stream": true }' python: | from openai import OpenAI + client = OpenAI() - stream = client.beta.threads.create_and_run( - assistant_id="asst_123", - thread={ - "messages": [ - {"role": "user", "content": "Hello"} - ] - }, + response = client.responses.create( + model="gpt-4o", + instructions="You are a helpful assistant.", + input="Hello!", stream=True ) - for event in stream: + for event in response: print(event) - node.js: | + javascript: | import OpenAI from "openai"; const openai = new OpenAI(); - async function main() { - const stream = await openai.beta.threads.createAndRun({ - assistant_id: "asst_123", - thread: { - messages: [ - { role: "user", content: "Hello" }, - ], - }, - stream: true - }); + const response = await openai.responses.create({ + model: "gpt-4o", + instructions: "You are a helpful assistant.", + input: "Hello!", + stream: true, + }); - for await (const event of stream) { + for await (const event of response) { console.log(event); - } } - - main(); response: > - event: thread.created + event: response.created data: - {"id":"thread_123","object":"thread","created_at":1710348075,"metadata":{}} + {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You + are a helpful + assistant.","max_output_tokens":null,"model":"gpt-4o-2024-08-06","output":[],"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":{}}} - event: thread.run.created + event: response.in_progress data: - {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You + are a helpful + assistant.","max_output_tokens":null,"model":"gpt-4o-2024-08-06","output":[],"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":{}}} - event: thread.run.queued + event: response.output_item.added data: - {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}} - event: thread.run.in_progress + event: response.content_part.added data: - {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} + {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}} - event: thread.run.step.created + event: response.output_text.delta data: - {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi"} - event: thread.run.step.in_progress + ... + + + event: response.output_text.done data: - {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"Hi + there! How can I assist you today?"} - event: thread.message.created - - data: - {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[], - "metadata":{}} - - - event: thread.message.in_progress - - data: - {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[], - "metadata":{}} - - - event: thread.message.delta - - data: - {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} - - - ... - - - event: thread.message.delta + event: response.content_part.done data: - {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" - today"}}]}} - - - event: thread.message.delta - - data: - {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hi + there! How can I assist you today?","annotations":[]}} - event: thread.message.completed + event: response.output_item.done data: - {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! - How can I assist you today?","annotations":[]}}], "metadata":{}} + {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi + there! How can I assist you today?","annotations":[]}]}} - event: thread.run.step.completed + event: response.completed data: - {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} - - - event: thread.run.completed - - {"id":"run_123","object":"thread.run","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1713226836,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1713226837,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} - - - event: done - - data: [DONE] - - title: Streaming with Functions + {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"You + are a helpful + assistant.","max_output_tokens":null,"model":"gpt-4o-2024-08-06","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi + there! How can I assist you + today?","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":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}} + - title: Functions request: curl: > - curl https://api.openai.com/v1/threads/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ + curl https://api.openai.com/v1/responses \ -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ - "assistant_id": "asst_abc123", - "thread": { - "messages": [ - {"role": "user", "content": "What is the weather like in San Francisco?"} - ] - }, + "model": "gpt-4o", + "input": "What is the weather like in Boston today?", "tools": [ { "type": "function", - "function": { - "name": "get_current_weather", - "description": "Get the current weather in a given location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA" - }, - "unit": { - "type": "string", - "enum": ["celsius", "fahrenheit"] - } + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" }, - "required": ["location"] - } + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location", "unit"] } } ], - "stream": true + "tool_choice": "auto" }' python: > from openai import OpenAI + client = OpenAI() tools = [ - { - "type": "function", - "function": { - "name": "get_current_weather", - "description": "Get the current weather in a given location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA", + { + "type": "function", + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, }, - "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, - }, - "required": ["location"], - }, + "required": ["location", "unit"], + } } - } ] - stream = client.beta.threads.create_and_run( - thread={ - "messages": [ - {"role": "user", "content": "What is the weather like in San Francisco?"} - ] - }, - assistant_id="asst_abc123", + response = client.responses.create( + model="gpt-4o", tools=tools, - stream=True + input="What is the weather like in Boston today?", + tool_choice="auto" ) - for event in stream: - print(event) - node.js: > + print(response) + javascript: > import OpenAI from "openai"; @@ -7660,1181 +8886,737 @@ paths: const tools = [ { - "type": "function", - "function": { - "name": "get_current_weather", - "description": "Get the current weather in a given location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA", + type: "function", + name: "get_current_weather", + description: "Get the current weather in a given location", + parameters: { + type: "object", + properties: { + location: { + type: "string", + description: "The city and state, e.g. San Francisco, CA", + }, + unit: { type: "string", enum: ["celsius", "fahrenheit"] }, }, - "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, - }, - "required": ["location"], + required: ["location", "unit"], }, - } - } + }, ]; - async function main() { - const stream = await openai.beta.threads.createAndRun({ - assistant_id: "asst_123", - thread: { - messages: [ - { role: "user", content: "What is the weather like in San Francisco?" }, - ], - }, + const response = await openai.responses.create({ + model: "gpt-4o", tools: tools, - stream: true - }); - - for await (const event of stream) { - console.log(event); - } - } + input: "What is the weather like in Boston today?", + tool_choice: "auto", + }); - main(); + console.log(response); response: > - event: thread.created - - data: - {"id":"thread_123","object":"thread","created_at":1710351818,"metadata":{}} - - - event: thread.run.created - - data: - {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get - the current weather in a given - location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The - city and state, e.g. San Francisco, - CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - - event: thread.run.queued - - data: - {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get - the current weather in a given - location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The - city and state, e.g. San Francisco, - CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - - event: thread.run.in_progress - - data: - {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get - the current weather in a given - location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The - city and state, e.g. San Francisco, - CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - - event: thread.run.step.created + { + "id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0", + "object": "response", + "created_at": 1741294021, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "function_call", + "id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0", + "call_id": "call_unLAR8MvFNptuiZK6K6HCy5k", + "name": "get_current_weather", + "arguments": "{\"location\":\"Boston, MA\",\"unit\":\"celsius\"}", + "status": "completed" + } + ], + "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": [ + { + "type": "function", + "description": "Get the current weather in a given location", + "name": "get_current_weather", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": [ + "celsius", + "fahrenheit" + ] + } + }, + "required": [ + "location", + "unit" + ] + }, + "strict": true + } + ], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 291, + "output_tokens": 23, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 314 + }, + "user": null, + "metadata": {} + } + - title: Reasoning + request: + curl: | + curl https://api.openai.com/v1/responses \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "o3-mini", + "input": "How much wood would a woodchuck chuck?", + "reasoning": { + "effort": "high" + } + }' + javascript: | + import OpenAI from "openai"; + const openai = new OpenAI(); - data: - {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} + const response = await openai.responses.create({ + model: "o3-mini", + input: "How much wood would a woodchuck chuck?", + reasoning: { + effort: "high" + } + }); + console.log(response); + python: | + from openai import OpenAI + client = OpenAI() - event: thread.run.step.in_progress + response = client.responses.create( + model="o3-mini", + input="How much wood would a woodchuck chuck?", + reasoning={ + "effort": "high" + } + ) - data: - {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} - - - event: thread.run.step.delta - - data: - {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"","output":null}}]}}} - - - event: thread.run.step.delta - - data: - {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"{\""}}]}}} - - - event: thread.run.step.delta - - data: - {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"location"}}]}}} - - - ... - - - event: thread.run.step.delta - - data: - {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"ahrenheit"}}]}}} - - - event: thread.run.step.delta - - data: - {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"\"}"}}]}}} - - - event: thread.run.requires_action - - data: - {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"requires_action","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":{"type":"submit_tool_outputs","submit_tool_outputs":{"tool_calls":[{"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San - Francisco, - CA\",\"unit\":\"fahrenheit\"}"}}]}},"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get - the current weather in a given - location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The - city and state, e.g. San Francisco, - CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - - event: done - - data: [DONE] - /threads/{thread_id}: + print(response) + response: > + { + "id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808", + "object": "response", + "created_at": 1741477868, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "o1-2024-12-17", + "output": [ + { + "type": "message", + "id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The classic tongue twister...", + "annotations": [] + } + ] + } + ], + "parallel_tool_calls": true, + "previous_response_id": null, + "reasoning": { + "effort": "high", + "summary": null + }, + "store": true, + "temperature": 1.0, + "text": { + "format": { + "type": "text" + } + }, + "tool_choice": "auto", + "tools": [], + "top_p": 1.0, + "truncation": "disabled", + "usage": { + "input_tokens": 81, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 1035, + "output_tokens_details": { + "reasoning_tokens": 832 + }, + "total_tokens": 1116 + }, + "user": null, + "metadata": {} + } + /responses/{response_id}: get: - operationId: getThread + operationId: getResponse tags: - - Assistants - summary: Retrieves a thread. + - Responses + summary: | + Retrieves a model response with the given ID. parameters: - in: path - name: thread_id + name: response_id required: true schema: type: string - description: The ID of the thread to retrieve. + example: resp_677efb5139a88190b512bc3fef8e535d + description: The ID of the response to retrieve. + - in: query + name: include + schema: + type: array + items: + $ref: "#/components/schemas/Includable" + description: | + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/ThreadObject" + $ref: "#/components/schemas/Response" x-oaiMeta: - name: Retrieve thread - group: threads - beta: true - returns: The [thread](/docs/api-reference/threads/object) object matching the + name: Get a model response + group: responses + returns: > + The [Response](/docs/api-reference/responses/object) object matching + the + specified ID. examples: request: curl: | - curl https://api.openai.com/v1/threads/thread_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" + curl https://api.openai.com/v1/responses/resp_123 \ + -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.retrieve("resp_123"); + console.log(response); python: | from openai import OpenAI client = OpenAI() - my_thread = client.beta.threads.retrieve("thread_abc123") - print(my_thread) - node.js: |- - import OpenAI from "openai"; - - const openai = new OpenAI(); - - async function main() { - const myThread = await openai.beta.threads.retrieve( - "thread_abc123" - ); - - console.log(myThread); - } - - main(); - response: | + response = client.responses.retrieve("resp_123") + print(response) + response: > { - "id": "thread_abc123", - "object": "thread", - "created_at": 1699014083, - "metadata": {}, - "tool_resources": { - "code_interpreter": { - "file_ids": [] + "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", + "object": "response", + "created_at": 1741386163, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "message", + "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", + "status": "completed", + "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": { + "input_tokens": 32, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 18, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 50 + }, + "user": null, + "metadata": {} } - post: - operationId: modifyThread + delete: + operationId: deleteResponse tags: - - Assistants - summary: Modifies a thread. + - Responses + summary: | + Deletes a model response with the given ID. parameters: - in: path - name: thread_id + name: response_id required: true schema: type: string - description: The ID of the thread to modify. Only the `metadata` can be modified. - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ModifyThreadRequest" + example: resp_677efb5139a88190b512bc3fef8e535d + description: The ID of the response to delete. responses: "200": description: OK + "404": + description: Not Found content: application/json: schema: - $ref: "#/components/schemas/ThreadObject" + $ref: "#/components/schemas/Error" x-oaiMeta: - name: Modify thread - group: threads - beta: true - returns: The modified [thread](/docs/api-reference/threads/object) object - matching the specified ID. + name: Delete a model response + group: responses + returns: | + A success message. examples: request: curl: | - curl https://api.openai.com/v1/threads/thread_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "metadata": { - "modified": "true", - "user": "abc123" - } - }' + curl -X DELETE https://api.openai.com/v1/responses/resp_123 \ + -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.del("resp_123"); + console.log(response); python: | from openai import OpenAI client = OpenAI() - my_updated_thread = client.beta.threads.update( - "thread_abc123", - metadata={ - "modified": "true", - "user": "abc123" - } - ) - print(my_updated_thread) - node.js: |- - import OpenAI from "openai"; - - const openai = new OpenAI(); - - async function main() { - const updatedThread = await openai.beta.threads.update( - "thread_abc123", - { - metadata: { modified: "true", user: "abc123" }, - } - ); - - console.log(updatedThread); - } - - main(); + response = client.responses.del("resp_123") + print(response) response: | { - "id": "thread_abc123", - "object": "thread", - "created_at": 1699014083, - "metadata": { - "modified": "true", - "user": "abc123" - }, - "tool_resources": {} + "id": "resp_6786a1bec27481909a17d673315b29f6", + "object": "response", + "deleted": true } - delete: - operationId: deleteThread + /responses/{response_id}/input_items: + get: + operationId: listInputItems tags: - - Assistants - summary: Delete a thread. + - Responses + summary: Returns a list of input items for a given response. parameters: - in: path - name: thread_id + name: response_id required: true schema: type: string - description: The ID of the thread to delete. + 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 `asc`. + - `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: before + schema: + type: string + description: | + An item ID to list items before, used in pagination. responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/DeleteThreadResponse" + $ref: "#/components/schemas/ResponseItemList" x-oaiMeta: - name: Delete thread - group: threads - beta: true - returns: Deletion status + name: List input items + group: responses + returns: A list of input item objects. examples: request: curl: | - curl https://api.openai.com/v1/threads/thread_abc123 \ + curl https://api.openai.com/v1/responses/resp_abc123/input_items \ -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -X DELETE - python: | - from openai import OpenAI - client = OpenAI() - - response = client.beta.threads.delete("thread_abc123") - print(response) - node.js: |- + -H "Authorization: Bearer $OPENAI_API_KEY" + javascript: > import OpenAI from "openai"; - const openai = new OpenAI(); + const client = new OpenAI(); - async function main() { - const response = await openai.beta.threads.del("thread_abc123"); - console.log(response); - } - main(); - response: | - { - "id": "thread_abc123", - "object": "thread.deleted", - "deleted": true - } - /threads/{thread_id}/messages: - get: - operationId: listMessages - tags: - - Assistants - summary: Returns a list of messages for a given thread. - parameters: - - in: path - name: thread_id - required: true - schema: - type: string - description: The ID of the [thread](/docs/api-reference/threads) the messages - belong to. - - 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 - - name: order - in: query - description: > - Sort order by the `created_at` timestamp of the objects. `asc` for - ascending order and `desc` for descending order. - schema: - type: string - default: desc - enum: - - asc - - desc - - name: after - in: query - description: > - A cursor for use in pagination. `after` is an object ID that defines - your place in the list. For instance, if you make a list request and - receive 100 objects, ending with obj_foo, your subsequent call can - include after=obj_foo in order to fetch the next page of the list. - schema: - type: string - - name: before - in: query - description: > - A cursor for use in pagination. `before` is an object ID that - defines your place in the list. For instance, if you make a list - request and receive 100 objects, starting with obj_foo, your - subsequent call can include before=obj_foo in order to fetch the - previous page of the list. - schema: - type: string - - name: run_id - in: query - description: | - Filter messages by the run ID that generated them. - schema: - type: string - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ListMessagesResponse" - x-oaiMeta: - name: List messages - group: threads - beta: true - returns: A list of [message](/docs/api-reference/messages) objects. - examples: - request: - curl: | - curl https://api.openai.com/v1/threads/thread_abc123/messages \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" - python: > - from openai import OpenAI + const response = await + client.responses.inputItems.list("resp_123"); + console.log(response.data); + python: | + from openai import OpenAI client = OpenAI() - - thread_messages = - client.beta.threads.messages.list("thread_abc123") - - print(thread_messages.data) - node.js: |- - import OpenAI from "openai"; - - const openai = new OpenAI(); - - async function main() { - const threadMessages = await openai.beta.threads.messages.list( - "thread_abc123" - ); - - console.log(threadMessages.data); - } - - main(); + response = client.responses.input_items.list("resp_123") + print(response.data) response: > { "object": "list", "data": [ { "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699016383, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} - }, - { - "id": "msg_abc456", - "object": "thread.message", - "created_at": 1699016383, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, + "type": "message", "role": "user", "content": [ { - "type": "text", - "text": { - "value": "Hello, what is AI?", - "annotations": [] - } + "type": "input_text", + "text": "Tell me a three sentence bedtime story about a unicorn." } - ], - "attachments": [], - "metadata": {} + ] } ], "first_id": "msg_abc123", - "last_id": "msg_abc456", + "last_id": "msg_abc123", "has_more": false } + /threads: post: - operationId: createMessage + operationId: createThread tags: - Assistants - summary: Create a message. - parameters: - - in: path - name: thread_id - required: true - schema: - type: string - description: The ID of the [thread](/docs/api-reference/threads) to create a - message for. + summary: Create a thread. requestBody: - required: true content: application/json: schema: - $ref: "#/components/schemas/CreateMessageRequest" + $ref: "#/components/schemas/CreateThreadRequest" responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/MessageObject" + $ref: "#/components/schemas/ThreadObject" x-oaiMeta: - name: Create message + name: Create thread group: threads beta: true - returns: A [message](/docs/api-reference/messages/object) object. + returns: A [thread](/docs/api-reference/threads) object. examples: - request: - curl: | - curl https://api.openai.com/v1/threads/thread_abc123/messages \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "role": "user", - "content": "How does AI work? Explain it in simple terms." - }' - python: | - from openai import OpenAI - client = OpenAI() - - thread_message = client.beta.threads.messages.create( - "thread_abc123", - role="user", - content="How does AI work? Explain it in simple terms.", - ) - print(thread_message) - node.js: >- - import OpenAI from "openai"; + - title: Empty + request: + curl: | + curl https://api.openai.com/v1/threads \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '' + python: | + from openai import OpenAI + client = OpenAI() + empty_thread = client.beta.threads.create() + print(empty_thread) + node.js: |- + import OpenAI from "openai"; - const openai = new OpenAI(); + const openai = new OpenAI(); + async function main() { + const emptyThread = await openai.beta.threads.create(); - async function main() { - const threadMessages = await openai.beta.threads.messages.create( - "thread_abc123", - { role: "user", content: "How does AI work? Explain it in simple terms." } - ); + console.log(emptyThread); + } - console.log(threadMessages); + main(); + response: | + { + "id": "thread_abc123", + "object": "thread", + "created_at": 1699012949, + "metadata": {}, + "tool_resources": {} } - - - main(); - response: | - { - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1713226573, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} - } - /threads/{thread_id}/messages/{message_id}: - get: - operationId: getMessage - tags: - - Assistants - summary: Retrieve a message. - parameters: - - in: path - name: thread_id - required: true - schema: - type: string - description: The ID of the [thread](/docs/api-reference/threads) to which this - message belongs. - - in: path - name: message_id - required: true - schema: - type: string - description: The ID of the message to retrieve. - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/MessageObject" - x-oaiMeta: - name: Retrieve message - group: threads - beta: true - returns: The [message](/docs/api-reference/messages/object) object matching the - specified ID. - examples: - request: - curl: > - curl - https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 - \ + - title: Messages + request: + curl: | + curl https://api.openai.com/v1/threads \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" - python: | - from openai import OpenAI - client = OpenAI() + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "messages": [{ + "role": "user", + "content": "Hello, what is AI?" + }, { + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }] + }' + python: | + from openai import OpenAI + client = OpenAI() - message = client.beta.threads.messages.retrieve( - message_id="msg_abc123", - thread_id="thread_abc123", - ) - print(message) - node.js: |- - import OpenAI from "openai"; + message_thread = client.beta.threads.create( + messages=[ + { + "role": "user", + "content": "Hello, what is AI?" + }, + { + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }, + ] + ) - const openai = new OpenAI(); + print(message_thread) + node.js: >- + import OpenAI from "openai"; - async function main() { - const message = await openai.beta.threads.messages.retrieve( - "thread_abc123", - "msg_abc123" - ); - console.log(message); - } + const openai = new OpenAI(); - main(); - response: | - { - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } + + async function main() { + const messageThread = await openai.beta.threads.create({ + messages: [ + { + role: "user", + content: "Hello, what is AI?" + }, + { + role: "user", + content: "How does AI work? Explain it in simple terms.", + }, + ], + }); + + console.log(messageThread); } - ], - "attachments": [], - "metadata": {} - } + + + main(); + response: | + { + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, + "metadata": {}, + "tool_resources": {} + } + /threads/runs: post: - operationId: modifyMessage + operationId: createThreadAndRun tags: - Assistants - summary: Modifies a message. - parameters: - - in: path - name: thread_id - required: true - schema: - type: string - description: The ID of the thread to which this message belongs. - - in: path - name: message_id - required: true - schema: - type: string - description: The ID of the message to modify. + summary: Create a thread and run it in one request. requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/ModifyMessageRequest" + $ref: "#/components/schemas/CreateThreadAndRunRequest" responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/MessageObject" + $ref: "#/components/schemas/RunObject" x-oaiMeta: - name: Modify message + name: Create thread and run group: threads beta: true - returns: The modified [message](/docs/api-reference/messages/object) object. + returns: A [run](/docs/api-reference/runs/object) object. examples: - request: - curl: > - curl - https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 - \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "metadata": { - "modified": "true", - "user": "abc123" - } - }' - python: | - from openai import OpenAI - client = OpenAI() + - title: Default + request: + curl: > + curl https://api.openai.com/v1/threads/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123", + "thread": { + "messages": [ + {"role": "user", "content": "Explain deep learning to a 5 year old."} + ] + } + }' + python: > + from openai import OpenAI - message = client.beta.threads.messages.update( - message_id="msg_abc12", - thread_id="thread_abc123", - metadata={ - "modified": "true", - "user": "abc123", - }, - ) - print(message) - node.js: |- - import OpenAI from "openai"; + client = OpenAI() - const openai = new OpenAI(); - async function main() { - const message = await openai.beta.threads.messages.update( - "thread_abc123", - "msg_abc123", - { - metadata: { - modified: "true", - user: "abc123", - }, - } - }' - response: | - { - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] + run = client.beta.threads.create_and_run( + assistant_id="asst_abc123", + thread={ + "messages": [ + {"role": "user", "content": "Explain deep learning to a 5 year old."} + ] } - } - ], - "file_ids": [], - "metadata": { - "modified": "true", - "user": "abc123" - } - } - delete: - operationId: deleteMessage - tags: - - Assistants - summary: Deletes a message. - parameters: - - in: path - name: thread_id - required: true - schema: - type: string - description: The ID of the thread to which this message belongs. - - in: path - name: message_id - required: true - schema: - type: string - description: The ID of the message to delete. - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/DeleteMessageResponse" - x-oaiMeta: - name: Delete message - group: threads - beta: true - returns: Deletion status - examples: - request: - curl: > - curl -X DELETE - https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 - \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" - python: | - from openai import OpenAI - client = OpenAI() + ) - deleted_message = client.beta.threads.messages.delete( - message_id="msg_abc12", - thread_id="thread_abc123", - ) - print(deleted_message) - node.js: |- - import OpenAI from "openai"; - const openai = new OpenAI(); + print(run) + node.js: > + import OpenAI from "openai"; - async function main() { - const deletedMessage = await openai.beta.threads.messages.del( - "thread_abc123", - "msg_abc123" - ); - console.log(deletedMessage); - } - response: | - { - "id": "msg_abc123", - "object": "thread.message.deleted", - "deleted": true - } - /threads/{thread_id}/runs: - get: - operationId: listRuns - tags: - - Assistants - summary: Returns a list of runs belonging to a thread. - parameters: - - name: thread_id - in: path - required: true - schema: - type: string - description: The ID of the thread the run belongs to. - - 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 - - name: order - in: query - description: > - Sort order by the `created_at` timestamp of the objects. `asc` for - ascending order and `desc` for descending order. - schema: - type: string - default: desc - enum: - - asc - - desc - - name: after - in: query - description: > - A cursor for use in pagination. `after` is an object ID that defines - your place in the list. For instance, if you make a list request and - receive 100 objects, ending with obj_foo, your subsequent call can - include after=obj_foo in order to fetch the next page of the list. - schema: - type: string - - name: before - in: query - description: > - A cursor for use in pagination. `before` is an object ID that - defines your place in the list. For instance, if you make a list - request and receive 100 objects, starting with obj_foo, your - subsequent call can include before=obj_foo in order to fetch the - previous page of the list. - schema: - type: string - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ListRunsResponse" - x-oaiMeta: - name: List runs - group: threads - beta: true - returns: A list of [run](/docs/api-reference/runs/object) objects. - examples: - request: - curl: | - curl https://api.openai.com/v1/threads/thread_abc123/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" - python: | - from openai import OpenAI - client = OpenAI() + const openai = new OpenAI(); - runs = client.beta.threads.runs.list( - "thread_abc123" - ) - print(runs) - node.js: | - import OpenAI from "openai"; + async function main() { + const run = await openai.beta.threads.createAndRun({ + assistant_id: "asst_abc123", + thread: { + messages: [ + { role: "user", content: "Explain deep learning to a 5 year old." }, + ], + }, + }); - const openai = new OpenAI(); + console.log(run); + } - async function main() { - const runs = await openai.beta.threads.runs.list( - "thread_abc123" - ); - console.log(runs); + main(); + response: | + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699076792, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "queued", + "started_at": null, + "expires_at": 1699077392, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "required_action": null, + "last_error": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant.", + "tools": [], + "tool_resources": {}, + "metadata": {}, + "temperature": 1.0, + "top_p": 1.0, + "max_completion_tokens": null, + "max_prompt_tokens": null, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "incomplete_details": null, + "usage": null, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true } - - main(); - response: | - { - "object": "list", - "data": [ - { - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" + - title: Streaming + request: + curl: | + curl https://api.openai.com/v1/threads/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_123", + "thread": { + "messages": [ + {"role": "user", "content": "Hello"} ] - } - }, - "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true - }, - { - "id": "run_abc456", - "object": "thread.run", - "created_at": 1699063290, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699063290, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699063291, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" - ] - } - }, - "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true - } - ], - "first_id": "run_abc123", - "last_id": "run_abc456", - "has_more": false - } - post: - operationId: createRun - tags: - - Assistants - summary: Create a run. - parameters: - - in: path - name: thread_id - required: true - schema: - type: string - description: The ID of the thread to run. - - name: include[] - in: query - description: > - A list of additional fields to include in the response. Currently - the only supported value is - `step_details.tool_calls[*].file_search.results[*].content` to fetch - the file search result content. - - - See the [file search tool - documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) - for more information. - schema: - type: array - items: - type: string - enum: - - step_details.tool_calls[*].file_search.results[*].content - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateRunRequest" - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/RunObject" - x-oaiMeta: - name: Create run - group: threads - beta: true - returns: A [run](/docs/api-reference/runs/object) object. - examples: - - title: Default - request: - curl: | - curl https://api.openai.com/v1/threads/thread_abc123/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "assistant_id": "asst_abc123" - }' - python: | - from openai import OpenAI - client = OpenAI() - - run = client.beta.threads.runs.create( - thread_id="thread_abc123", - assistant_id="asst_abc123" - ) - - print(run) - node.js: | - import OpenAI from "openai"; - - const openai = new OpenAI(); - - async function main() { - const run = await openai.beta.threads.runs.create( - "thread_abc123", - { assistant_id: "asst_abc123" } - ); - - console.log(run); - } - - main(); - response: | - { - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699063290, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "queued", - "started_at": 1699063290, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699063291, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "metadata": {}, - "usage": null, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true - } - - title: Streaming - request: - curl: | - curl https://api.openai.com/v1/threads/thread_123/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "assistant_id": "asst_123", + }, "stream": true }' python: | from openai import OpenAI client = OpenAI() - stream = client.beta.threads.runs.create( - thread_id="thread_123", + stream = client.beta.threads.create_and_run( assistant_id="asst_123", + thread={ + "messages": [ + {"role": "user", "content": "Hello"} + ] + }, stream=True ) @@ -8846,10 +9628,15 @@ paths: const openai = new OpenAI(); async function main() { - const stream = await openai.beta.threads.runs.create( - "thread_123", - { assistant_id: "asst_123", stream: true } - ); + const stream = await openai.beta.threads.createAndRun({ + assistant_id: "asst_123", + thread: { + messages: [ + { role: "user", content: "Hello" }, + ], + }, + stream: true + }); for await (const event of stream) { console.log(event); @@ -8858,46 +9645,54 @@ paths: main(); response: > + event: thread.created + + data: + {"id":"thread_123","object":"thread","created_at":1710348075,"metadata":{}} + + event: thread.run.created data: - {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} event: thread.run.queued data: - {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} event: thread.run.in_progress data: - {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710330641,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} event: thread.run.step.created data: - {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} event: thread.run.step.in_progress data: - {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} event: thread.message.created data: - {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[], + "metadata":{}} event: thread.message.in_progress data: - {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[], + "metadata":{}} event: thread.message.delta @@ -8925,20 +9720,19 @@ paths: event: thread.message.completed data: - {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710330642,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! - How can I assist you today?","annotations":[]}}],"metadata":{}} + {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! + How can I assist you today?","annotations":[]}}], "metadata":{}} event: thread.run.step.completed data: - {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710330642,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} event: thread.run.completed - data: - {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710330641,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710330642,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + {"id":"run_123","object":"thread.run","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1713226836,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1713226837,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true} event: done @@ -8947,12 +9741,17 @@ paths: - title: Streaming with Functions request: curl: > - curl https://api.openai.com/v1/threads/thread_abc123/runs \ + curl https://api.openai.com/v1/threads/runs \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v2" \ -d '{ "assistant_id": "asst_abc123", + "thread": { + "messages": [ + {"role": "user", "content": "What is the weather like in San Francisco?"} + ] + }, "tools": [ { "type": "function", @@ -9006,8 +9805,12 @@ paths: ] - stream = client.beta.threads.runs.create( - thread_id="thread_abc123", + stream = client.beta.threads.create_and_run( + thread={ + "messages": [ + {"role": "user", "content": "What is the weather like in San Francisco?"} + ] + }, assistant_id="asst_abc123", tools=tools, stream=True @@ -9046,14 +9849,16 @@ paths: async function main() { - const stream = await openai.beta.threads.runs.create( - "thread_abc123", - { - assistant_id: "asst_abc123", - tools: tools, - stream: true - } - ); + const stream = await openai.beta.threads.createAndRun({ + assistant_id: "asst_123", + thread: { + messages: [ + { role: "user", content: "What is the weather like in San Francisco?" }, + ], + }, + tools: tools, + stream: true + }); for await (const event of stream) { console.log(event); @@ -9063,446 +9868,320 @@ paths: main(); response: > + event: thread.created + + data: + {"id":"thread_123","object":"thread","created_at":1710351818,"metadata":{}} + + event: thread.run.created data: - {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get + the current weather in a given + location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The + city and state, e.g. San Francisco, + CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} event: thread.run.queued data: - {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get + the current weather in a given + location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The + city and state, e.g. San Francisco, + CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} event: thread.run.in_progress data: - {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710348075,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get + the current weather in a given + location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The + city and state, e.g. San Francisco, + CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} event: thread.run.step.created data: - {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} event: thread.run.step.in_progress data: - {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null} - event: thread.message.created + event: thread.run.step.delta data: - {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"","output":null}}]}}} - event: thread.message.in_progress + event: thread.run.step.delta data: - {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"{\""}}]}}} - event: thread.message.delta + event: thread.run.step.delta data: - {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"location"}}]}}} ... - event: thread.message.delta - - data: - {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" - today"}}]}} - - - event: thread.message.delta - - data: - {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} - - - event: thread.message.completed + event: thread.run.step.delta data: - {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! - How can I assist you today?","annotations":[]}}],"metadata":{}} + {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"ahrenheit"}}]}}} - event: thread.run.step.completed + event: thread.run.step.delta data: - {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"\"}"}}]}}} - event: thread.run.completed + event: thread.run.requires_action data: - {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710348075,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710348077,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"requires_action","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":{"type":"submit_tool_outputs","submit_tool_outputs":{"tool_calls":[{"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San + Francisco, + CA\",\"unit\":\"fahrenheit\"}"}}]}},"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get + the current weather in a given + location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The + city and state, e.g. San Francisco, + CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} event: done data: [DONE] - /threads/{thread_id}/runs/{run_id}: + /threads/{thread_id}: get: - operationId: getRun + operationId: getThread tags: - Assistants - summary: Retrieves a run. + summary: Retrieves a thread. parameters: - in: path name: thread_id required: true schema: type: string - description: The ID of the [thread](/docs/api-reference/threads) that was run. - - in: path - name: run_id - required: true - schema: - type: string - description: The ID of the run to retrieve. + description: The ID of the thread to retrieve. responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/RunObject" + $ref: "#/components/schemas/ThreadObject" x-oaiMeta: - name: Retrieve run + name: Retrieve thread group: threads beta: true - returns: The [run](/docs/api-reference/runs/object) object matching the + returns: The [thread](/docs/api-reference/threads/object) object matching the specified ID. examples: request: - curl: > - curl - https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ + curl: | + curl https://api.openai.com/v1/threads/thread_abc123 \ + -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" python: | from openai import OpenAI client = OpenAI() - run = client.beta.threads.runs.retrieve( - thread_id="thread_abc123", - run_id="run_abc123" - ) - - print(run) - node.js: | + my_thread = client.beta.threads.retrieve("thread_abc123") + print(my_thread) + node.js: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { - const run = await openai.beta.threads.runs.retrieve( - "thread_abc123", - "run_abc123" + const myThread = await openai.beta.threads.retrieve( + "thread_abc123" ); - console.log(run); + console.log(myThread); } main(); response: | { - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true + "tool_resources": { + "code_interpreter": { + "file_ids": [] + } + } } post: - operationId: modifyRun + operationId: modifyThread tags: - Assistants - summary: Modifies a run. + summary: Modifies a thread. parameters: - in: path name: thread_id required: true schema: type: string - description: The ID of the [thread](/docs/api-reference/threads) that was run. - - in: path - name: run_id - required: true - schema: - type: string - description: The ID of the run to modify. + description: The ID of the thread to modify. Only the `metadata` can be modified. requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/ModifyRunRequest" + $ref: "#/components/schemas/ModifyThreadRequest" responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/RunObject" + $ref: "#/components/schemas/ThreadObject" x-oaiMeta: - name: Modify run + name: Modify thread group: threads beta: true - returns: The modified [run](/docs/api-reference/runs/object) object matching the - specified ID. + returns: The modified [thread](/docs/api-reference/threads/object) object + matching the specified ID. examples: request: - curl: > - curl - https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ + curl: | + curl https://api.openai.com/v1/threads/thread_abc123 \ -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -d '{ - "metadata": { - "user_id": "user_abc123" - } - }' + "metadata": { + "modified": "true", + "user": "abc123" + } + }' python: | from openai import OpenAI client = OpenAI() - run = client.beta.threads.runs.update( - thread_id="thread_abc123", - run_id="run_abc123", - metadata={"user_id": "user_abc123"}, + my_updated_thread = client.beta.threads.update( + "thread_abc123", + metadata={ + "modified": "true", + "user": "abc123" + } ) - - print(run) - node.js: | + print(my_updated_thread) + node.js: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { - const run = await openai.beta.threads.runs.update( + const updatedThread = await openai.beta.threads.update( "thread_abc123", - "run_abc123", { - metadata: { - user_id: "user_abc123", - }, + metadata: { modified: "true", user: "abc123" }, } ); - console.log(run); + console.log(updatedThread); } main(); response: | { - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" - ] - } - }, + "id": "thread_abc123", + "object": "thread", + "created_at": 1699014083, "metadata": { - "user_id": "user_abc123" - }, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null + "modified": "true", + "user": "abc123" }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true + "tool_resources": {} } - /threads/{thread_id}/runs/{run_id}/cancel: - post: - operationId: cancelRun + delete: + operationId: deleteThread tags: - Assistants - summary: Cancels a run that is `in_progress`. + summary: Delete a thread. parameters: - in: path name: thread_id required: true schema: type: string - description: The ID of the thread to which this run belongs. - - in: path - name: run_id - required: true - schema: - type: string - description: The ID of the run to cancel. + description: The ID of the thread to delete. responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/RunObject" + $ref: "#/components/schemas/DeleteThreadResponse" x-oaiMeta: - name: Cancel a run + name: Delete thread group: threads beta: true - returns: The modified [run](/docs/api-reference/runs/object) object matching the - specified ID. + returns: Deletion status examples: request: - curl: > - curl - https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel - \ + curl: | + curl https://api.openai.com/v1/threads/thread_abc123 \ + -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ - -X POST + -X DELETE python: | from openai import OpenAI client = OpenAI() - run = client.beta.threads.runs.cancel( - thread_id="thread_abc123", - run_id="run_abc123" - ) - - print(run) - node.js: | + response = client.beta.threads.delete("thread_abc123") + print(response) + node.js: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { - const run = await openai.beta.threads.runs.cancel( - "thread_abc123", - "run_abc123" - ); + const response = await openai.beta.threads.del("thread_abc123"); - console.log(run); + console.log(response); } - main(); response: | { - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699076126, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "cancelling", - "started_at": 1699076126, - "expires_at": 1699076726, - "cancelled_at": null, - "failed_at": null, - "completed_at": null, - "last_error": null, - "model": "gpt-4o", - "instructions": "You summarize books.", - "tools": [ - { - "type": "file_search" - } - ], - "tool_resources": { - "file_search": { - "vector_store_ids": ["vs_123"] - } - }, - "metadata": {}, - "usage": null, - "temperature": 1.0, - "top_p": 1.0, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true + "id": "thread_abc123", + "object": "thread.deleted", + "deleted": true } - /threads/{thread_id}/runs/{run_id}/steps: + /threads/{thread_id}/messages: get: - operationId: listRunSteps + operationId: listMessages tags: - Assistants - summary: Returns a list of run steps belonging to a run. + summary: Returns a list of messages for a given thread. parameters: - - name: thread_id - in: path - required: true - schema: - type: string - description: The ID of the thread the run and run steps belong to. - - name: run_id - in: path + - in: path + name: thread_id required: true schema: type: string - description: The ID of the run the run steps belong to. + description: The ID of the [thread](/docs/api-reference/threads) the messages + belong to. - name: limit in: query description: > @@ -9542,2401 +10221,4075 @@ paths: previous page of the list. schema: type: string - - name: include[] + - name: run_id in: query - description: > - A list of additional fields to include in the response. Currently - the only supported value is - `step_details.tool_calls[*].file_search.results[*].content` to fetch - the file search result content. - - - See the [file search tool - documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) - for more information. + description: | + Filter messages by the run ID that generated them. schema: - type: array - items: - type: string - enum: - - step_details.tool_calls[*].file_search.results[*].content + type: string responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/ListRunStepsResponse" + $ref: "#/components/schemas/ListMessagesResponse" x-oaiMeta: - name: List run steps + name: List messages group: threads beta: true - returns: A list of [run step](/docs/api-reference/run-steps/step-object) - objects. + returns: A list of [message](/docs/api-reference/messages) objects. examples: request: - curl: > - curl - https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps - \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/messages \ -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" - python: | + python: > from openai import OpenAI + client = OpenAI() - run_steps = client.beta.threads.runs.steps.list( - thread_id="thread_abc123", - run_id="run_abc123" - ) - print(run_steps) - node.js: | + thread_messages = + client.beta.threads.messages.list("thread_abc123") + + print(thread_messages.data) + node.js: |- import OpenAI from "openai"; + const openai = new OpenAI(); async function main() { - const runStep = await openai.beta.threads.runs.steps.list( - "thread_abc123", - "run_abc123" + const threadMessages = await openai.beta.threads.messages.list( + "thread_abc123" ); - console.log(runStep); + + console.log(threadMessages.data); } main(); - response: | + response: > { "object": "list", "data": [ { - "id": "step_abc123", - "object": "thread.run.step", - "created_at": 1699063291, - "run_id": "run_abc123", - "assistant_id": "asst_abc123", + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, "thread_id": "thread_abc123", - "type": "message_creation", - "status": "completed", - "cancelled_at": null, - "completed_at": 1699063291, - "expired_at": null, - "failed_at": null, - "last_error": null, - "step_details": { - "type": "message_creation", - "message_creation": { - "message_id": "msg_abc123" + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } } - }, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - } - } - ], - "first_id": "step_abc123", - "last_id": "step_abc456", - "has_more": false - } - /threads/{thread_id}/runs/{run_id}/steps/{step_id}: - get: - operationId: getRunStep - tags: - - Assistants - summary: Retrieves a run step. - parameters: - - in: path - name: thread_id - required: true - schema: - type: string - description: The ID of the thread to which the run and run step belongs. + ], + "attachments": [], + "metadata": {} + }, + { + "id": "msg_abc456", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "Hello, what is AI?", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc456", + "has_more": false + } + post: + operationId: createMessage + tags: + - Assistants + summary: Create a message. + parameters: - in: path - name: run_id + name: thread_id required: true schema: type: string - description: The ID of the run to which the run step belongs. + description: The ID of the [thread](/docs/api-reference/threads) to create a + message for. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateMessageRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/MessageObject" + x-oaiMeta: + name: Create message + group: threads + beta: true + returns: A [message](/docs/api-reference/messages/object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/messages \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }' + python: | + from openai import OpenAI + client = OpenAI() + + thread_message = client.beta.threads.messages.create( + "thread_abc123", + role="user", + content="How does AI work? Explain it in simple terms.", + ) + print(thread_message) + node.js: >- + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const threadMessages = await openai.beta.threads.messages.create( + "thread_abc123", + { role: "user", content: "How does AI work? Explain it in simple terms." } + ); + + console.log(threadMessages); + } + + + main(); + response: | + { + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1713226573, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + } + /threads/{thread_id}/messages/{message_id}: + get: + operationId: getMessage + tags: + - Assistants + summary: Retrieve a message. + parameters: - in: path - name: step_id + name: thread_id required: true schema: type: string - description: The ID of the run step to retrieve. - - name: include[] - in: query - description: > - A list of additional fields to include in the response. Currently - the only supported value is - `step_details.tool_calls[*].file_search.results[*].content` to fetch - the file search result content. - - - See the [file search tool - documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) - for more information. + description: The ID of the [thread](/docs/api-reference/threads) to which this + message belongs. + - in: path + name: message_id + required: true schema: - type: array - items: - type: string - enum: - - step_details.tool_calls[*].file_search.results[*].content + type: string + description: The ID of the message to retrieve. responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/RunStepObject" + $ref: "#/components/schemas/MessageObject" x-oaiMeta: - name: Retrieve run step + name: Retrieve message group: threads beta: true - returns: The [run step](/docs/api-reference/run-steps/step-object) object - matching the specified ID. + returns: The [message](/docs/api-reference/messages/object) object matching the + specified ID. examples: request: curl: > curl - https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123 + https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" python: | from openai import OpenAI client = OpenAI() - run_step = client.beta.threads.runs.steps.retrieve( - thread_id="thread_abc123", - run_id="run_abc123", - step_id="step_abc123" + message = client.beta.threads.messages.retrieve( + message_id="msg_abc123", + thread_id="thread_abc123", ) - - print(run_step) - node.js: | + print(message) + node.js: |- import OpenAI from "openai"; + const openai = new OpenAI(); async function main() { - const runStep = await openai.beta.threads.runs.steps.retrieve( + const message = await openai.beta.threads.messages.retrieve( "thread_abc123", - "run_abc123", - "step_abc123" + "msg_abc123" ); - console.log(runStep); + + console.log(message); } main(); response: | { - "id": "step_abc123", - "object": "thread.run.step", - "created_at": 1699063291, - "run_id": "run_abc123", - "assistant_id": "asst_abc123", + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "assistant_id": null, "thread_id": "thread_abc123", - "type": "message_creation", - "status": "completed", - "cancelled_at": null, - "completed_at": 1699063291, - "expired_at": null, - "failed_at": null, - "last_error": null, - "step_details": { - "type": "message_creation", - "message_creation": { - "message_id": "msg_abc123" + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } } - }, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - } + ], + "attachments": [], + "metadata": {} } - /threads/{thread_id}/runs/{run_id}/submit_tool_outputs: post: - operationId: submitToolOuputsToRun + operationId: modifyMessage tags: - Assistants - summary: > - When a run has the `status: "requires_action"` and - `required_action.type` is `submit_tool_outputs`, this endpoint can be - used to submit the outputs from the tool calls once they're all - completed. All outputs must be submitted in a single request. + summary: Modifies a message. parameters: - in: path name: thread_id required: true schema: type: string - description: The ID of the [thread](/docs/api-reference/threads) to which this - run belongs. + description: The ID of the thread to which this message belongs. - in: path - name: run_id + name: message_id required: true schema: type: string - description: The ID of the run that requires the tool output submission. + description: The ID of the message to modify. requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/SubmitToolOutputsRunRequest" + $ref: "#/components/schemas/ModifyMessageRequest" responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/RunObject" + $ref: "#/components/schemas/MessageObject" x-oaiMeta: - name: Submit tool outputs to run + name: Modify message group: threads beta: true - returns: The modified [run](/docs/api-reference/runs/object) object matching the - specified ID. + returns: The modified [message](/docs/api-reference/messages/object) object. examples: - - title: Default - request: - curl: > - curl - https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs - \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "tool_outputs": [ - { - "tool_call_id": "call_001", - "output": "70 degrees and sunny." - } - ] - }' - python: | - from openai import OpenAI - client = OpenAI() - - run = client.beta.threads.runs.submit_tool_outputs( - thread_id="thread_123", - run_id="run_123", - tool_outputs=[ - { - "tool_call_id": "call_001", - "output": "70 degrees and sunny." + request: + curl: > + curl + https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "metadata": { + "modified": "true", + "user": "abc123" } - ] - ) - - print(run) - node.js: | - import OpenAI from "openai"; - - const openai = new OpenAI(); + }' + python: | + from openai import OpenAI + client = OpenAI() - async function main() { - const run = await openai.beta.threads.runs.submitToolOutputs( - "thread_123", - "run_123", - { - tool_outputs: [ - { - tool_call_id: "call_001", - output: "70 degrees and sunny.", - }, - ], - } - ); + message = client.beta.threads.messages.update( + message_id="msg_abc12", + thread_id="thread_abc123", + metadata={ + "modified": "true", + "user": "abc123", + }, + ) + print(message) + node.js: |- + import OpenAI from "openai"; - console.log(run); - } + const openai = new OpenAI(); - main(); - response: > - { - "id": "run_123", - "object": "thread.run", - "created_at": 1699075592, - "assistant_id": "asst_123", - "thread_id": "thread_123", - "status": "queued", - "started_at": 1699075592, - "expires_at": 1699076192, - "cancelled_at": null, - "failed_at": null, - "completed_at": null, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "tools": [ + async function main() { + const message = await openai.beta.threads.messages.update( + "thread_abc123", + "msg_abc123", { - "type": "function", - "function": { - "name": "get_current_weather", - "description": "Get the current weather in a given location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and state, e.g. San Francisco, CA" - }, - "unit": { - "type": "string", - "enum": ["celsius", "fahrenheit"] - } - }, - "required": ["location"] - } - } + metadata: { + modified: "true", + user: "abc123", + }, } - ], - "metadata": {}, - "usage": null, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true + }' + response: | + { + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "file_ids": [], + "metadata": { + "modified": "true", + "user": "abc123" } - - title: Streaming - request: - curl: > - curl - https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs - \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "tool_outputs": [ - { - "tool_call_id": "call_001", - "output": "70 degrees and sunny." - } - ], - "stream": true - }' - python: | - from openai import OpenAI - client = OpenAI() - - stream = client.beta.threads.runs.submit_tool_outputs( - thread_id="thread_123", - run_id="run_123", - tool_outputs=[ - { - "tool_call_id": "call_001", - "output": "70 degrees and sunny." - } - ], - stream=True - ) - - for event in stream: - print(event) - node.js: > - import OpenAI from "openai"; + } + delete: + operationId: deleteMessage + tags: + - Assistants + summary: Deletes a message. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the thread to which this message belongs. + - in: path + name: message_id + required: true + schema: + type: string + description: The ID of the message to delete. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteMessageResponse" + x-oaiMeta: + name: Delete message + group: threads + beta: true + returns: Deletion status + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 + \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + deleted_message = client.beta.threads.messages.delete( + message_id="msg_abc12", + thread_id="thread_abc123", + ) + print(deleted_message) + node.js: |- + import OpenAI from "openai"; - const openai = new OpenAI(); + const openai = new OpenAI(); + async function main() { + const deletedMessage = await openai.beta.threads.messages.del( + "thread_abc123", + "msg_abc123" + ); - async function main() { - const stream = await openai.beta.threads.runs.submitToolOutputs( - "thread_123", - "run_123", - { - tool_outputs: [ - { - tool_call_id: "call_001", - output: "70 degrees and sunny.", - }, - ], - } - ); - - for await (const event of stream) { - console.log(event); - } - } - - - main(); - response: > - event: thread.run.step.completed - - data: - {"id":"step_001","object":"thread.run.step","created_at":1710352449,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"completed","cancelled_at":null,"completed_at":1710352475,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[{"id":"call_iWr0kQ2EaYMaxNdl0v3KYkx7","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San - Francisco, CA\",\"unit\":\"fahrenheit\"}","output":"70 degrees and - sunny."}}]},"usage":{"prompt_tokens":291,"completion_tokens":24,"total_tokens":315}} - - - event: thread.run.queued - - data: - {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":1710352448,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get - the current weather in a given - location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The - city and state, e.g. San Francisco, - CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - - event: thread.run.in_progress - - data: - {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710352475,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get - the current weather in a given - location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The - city and state, e.g. San Francisco, - CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - - event: thread.run.step.created - - data: - {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} - - - event: thread.run.step.in_progress - - data: - {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} - - - event: thread.message.created - - data: - {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - - - event: thread.message.in_progress - - data: - {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - - - event: thread.message.delta - - data: - {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"The","annotations":[]}}]}} - - - event: thread.message.delta - - data: - {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" - current"}}]}} - - - event: thread.message.delta - - data: - {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" - weather"}}]}} - - - ... - - - event: thread.message.delta - - data: - {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" - sunny"}}]}} - - - event: thread.message.delta - - data: - {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"."}}]}} - - - event: thread.message.completed - - data: - {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710352477,"role":"assistant","content":[{"type":"text","text":{"value":"The - current weather in San Francisco, CA is 70 degrees Fahrenheit and - sunny.","annotations":[]}}],"metadata":{}} - - - event: thread.run.step.completed - - data: - {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710352477,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":{"prompt_tokens":329,"completion_tokens":18,"total_tokens":347}} - - - event: thread.run.completed - - data: - {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710352475,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710352477,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get - the current weather in a given - location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The - city and state, e.g. San Francisco, - CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - - event: done - - data: [DONE] - /uploads: - post: - operationId: createUpload - tags: - - Uploads - summary: > - Creates an intermediate [Upload](/docs/api-reference/uploads/object) - object that you can add [Parts](/docs/api-reference/uploads/part-object) - to. Currently, an Upload can accept at most 8 GB in total and expires - after an hour after you create it. - - - Once you complete the Upload, we will create a - [File](/docs/api-reference/files/object) object that contains all the - parts you uploaded. This File is usable in the rest of our platform as a - regular File object. - - - For certain `purpose`s, the correct `mime_type` must be specified. - Please refer to documentation for the supported MIME types for your use - case: - - - [Assistants](/docs/assistants/tools/file-search#supported-files) - - - For guidance on the proper filename extensions for each purpose, please - follow the documentation on [creating a - File](/docs/api-reference/files/create). - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateUploadRequest" - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Upload" - x-oaiMeta: - name: Create upload - group: uploads - returns: The [Upload](/docs/api-reference/uploads/object) object with status - `pending`. - examples: - request: - curl: | - curl https://api.openai.com/v1/uploads \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "purpose": "fine-tune", - "filename": "training_examples.jsonl", - "bytes": 2147483648, - "mime_type": "text/jsonl" - }' + console.log(deletedMessage); + } response: | { - "id": "upload_abc123", - "object": "upload", - "bytes": 2147483648, - "created_at": 1719184911, - "filename": "training_examples.jsonl", - "purpose": "fine-tune", - "status": "pending", - "expires_at": 1719127296 + "id": "msg_abc123", + "object": "thread.message.deleted", + "deleted": true } - /uploads/{upload_id}/cancel: - post: - operationId: cancelUpload + /threads/{thread_id}/runs: + get: + operationId: listRuns tags: - - Uploads - summary: | - Cancels the Upload. No Parts may be added after an Upload is cancelled. + - Assistants + summary: Returns a list of runs belonging to a thread. parameters: - - in: path - name: upload_id + - name: thread_id + in: path required: true schema: type: string - example: upload_abc123 - description: | - The ID of the Upload. + description: The ID of the thread the run belongs to. + - 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 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/Upload" + $ref: "#/components/schemas/ListRunsResponse" x-oaiMeta: - name: Cancel upload - group: uploads - returns: The [Upload](/docs/api-reference/uploads/object) object with status - `cancelled`. + name: List runs + group: threads + beta: true + returns: A list of [run](/docs/api-reference/runs/object) objects. examples: request: curl: | - curl https://api.openai.com/v1/uploads/upload_abc123/cancel - response: | - { - "id": "upload_abc123", - "object": "upload", - "bytes": 2147483648, - "created_at": 1719184911, - "filename": "training_examples.jsonl", - "purpose": "fine-tune", - "status": "cancelled", - "expires_at": 1719127296 - } - /uploads/{upload_id}/complete: - post: - operationId: completeUpload - tags: - - Uploads - summary: > - Completes the [Upload](/docs/api-reference/uploads/object). + curl https://api.openai.com/v1/threads/thread_abc123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + runs = client.beta.threads.runs.list( + "thread_abc123" + ) - Within the returned Upload object, there is a nested - [File](/docs/api-reference/files/object) object that is ready to use in - the rest of the platform. + print(runs) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); - You can specify the order of the Parts by passing in an ordered list of - the Part IDs. + async function main() { + const runs = await openai.beta.threads.runs.list( + "thread_abc123" + ); + console.log(runs); + } - The number of bytes uploaded upon completion must match the number of - bytes initially specified when creating the Upload object. No Parts may - be added after an Upload is completed. + main(); + response: | + { + "object": "list", + "data": [ + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + }, + { + "id": "run_abc456", + "object": "thread.run", + "created_at": 1699063290, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699063290, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699063291, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + ], + "first_id": "run_abc123", + "last_id": "run_abc456", + "has_more": false + } + post: + operationId: createRun + tags: + - Assistants + summary: Create a run. parameters: - in: path - name: upload_id + name: thread_id required: true schema: type: string - example: upload_abc123 - description: | - The ID of the Upload. + description: The ID of the thread to run. + - name: include[] + in: query + description: > + A list of additional fields to include in the response. Currently + the only supported value is + `step_details.tool_calls[*].file_search.results[*].content` to fetch + the file search result content. + + + See the [file search tool + documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) + for more information. + schema: + type: array + items: + type: string + enum: + - step_details.tool_calls[*].file_search.results[*].content requestBody: required: true content: application/json: schema: - $ref: "#/components/schemas/CompleteUploadRequest" + $ref: "#/components/schemas/CreateRunRequest" responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/Upload" + $ref: "#/components/schemas/RunObject" x-oaiMeta: - name: Complete upload - group: uploads - returns: The [Upload](/docs/api-reference/uploads/object) object with status - `completed` with an additional `file` property containing the created - usable File object. + name: Create run + group: threads + beta: true + returns: A [run](/docs/api-reference/runs/object) object. examples: - request: - curl: | - curl https://api.openai.com/v1/uploads/upload_abc123/complete - -d '{ - "part_ids": ["part_def456", "part_ghi789"] - }' - response: | - { - "id": "upload_abc123", - "object": "upload", - "bytes": 2147483648, - "created_at": 1719184911, - "filename": "training_examples.jsonl", - "purpose": "fine-tune", - "status": "completed", - "expires_at": 1719127296, - "file": { - "id": "file-xyz321", - "object": "file", - "bytes": 2147483648, - "created_at": 1719186911, - "filename": "training_examples.jsonl", - "purpose": "fine-tune", - } - } - /uploads/{upload_id}/parts: - post: - operationId: addUploadPart - tags: - - Uploads - summary: > - Adds a [Part](/docs/api-reference/uploads/part-object) to an - [Upload](/docs/api-reference/uploads/object) object. A Part represents a - chunk of bytes from the file you are trying to upload. + - title: Default + request: + curl: | + curl https://api.openai.com/v1/threads/thread_abc123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123" + }' + python: | + from openai import OpenAI + client = OpenAI() + run = client.beta.threads.runs.create( + thread_id="thread_abc123", + assistant_id="asst_abc123" + ) - Each Part can be at most 64 MB, and you can add Parts until you hit the - Upload maximum of 8 GB. + print(run) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); - It is possible to add multiple Parts in parallel. You can decide the - intended order of the Parts when you [complete the - Upload](/docs/api-reference/uploads/complete). - parameters: - - in: path - name: upload_id - required: true - schema: - type: string - example: upload_abc123 - description: | - The ID of the Upload. - requestBody: - required: true - content: - multipart/form-data: - schema: - $ref: "#/components/schemas/AddUploadPartRequest" - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/UploadPart" - x-oaiMeta: - name: Add upload part - group: uploads - returns: The upload [Part](/docs/api-reference/uploads/part-object) object. - examples: - request: - curl: | - curl https://api.openai.com/v1/uploads/upload_abc123/parts - -F data="aHR0cHM6Ly9hcGkub3BlbmFpLmNvbS92MS91cGxvYWRz..." - response: | - { - "id": "part_def456", - "object": "upload.part", - "created_at": 1719185911, - "upload_id": "upload_abc123" - } - /vector_stores: - get: - operationId: listVectorStores - tags: - - Vector stores - summary: Returns a list of vector stores. - parameters: - - 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 - - name: order - in: query - description: > - Sort order by the `created_at` timestamp of the objects. `asc` for - ascending order and `desc` for descending order. - schema: - type: string - default: desc - enum: - - asc - - desc - - name: after - in: query - description: > - A cursor for use in pagination. `after` is an object ID that defines - your place in the list. For instance, if you make a list request and - receive 100 objects, ending with obj_foo, your subsequent call can - include after=obj_foo in order to fetch the next page of the list. - schema: - type: string - - name: before - in: query - description: > - A cursor for use in pagination. `before` is an object ID that - defines your place in the list. For instance, if you make a list - request and receive 100 objects, starting with obj_foo, your - subsequent call can include before=obj_foo in order to fetch the - previous page of the list. - schema: - type: string - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ListVectorStoresResponse" - x-oaiMeta: - name: List vector stores - group: vector_stores - beta: true - returns: A list of [vector store](/docs/api-reference/vector-stores/object) - objects. - examples: - request: - curl: | - curl https://api.openai.com/v1/vector_stores \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" - python: | - from openai import OpenAI - client = OpenAI() - - vector_stores = client.beta.vector_stores.list() - print(vector_stores) - node.js: | - import OpenAI from "openai"; - const openai = new OpenAI(); + async function main() { + const run = await openai.beta.threads.runs.create( + "thread_abc123", + { assistant_id: "asst_abc123" } + ); - async function main() { - const vectorStores = await openai.beta.vectorStores.list(); - console.log(vectorStores); - } + console.log(run); + } - main(); - response: | - { - "object": "list", - "data": [ - { - "id": "vs_abc123", - "object": "vector_store", - "created_at": 1699061776, - "name": "Support FAQ", - "bytes": 139920, - "file_counts": { - "in_progress": 0, - "completed": 3, - "failed": 0, - "cancelled": 0, - "total": 3 + main(); + response: | + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699063290, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "queued", + "started_at": 1699063290, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699063291, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" } + ], + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null }, - { - "id": "vs_abc456", - "object": "vector_store", - "created_at": 1699061776, - "name": "Support FAQ v2", - "bytes": 139920, - "file_counts": { - "in_progress": 0, - "completed": 3, - "failed": 0, - "cancelled": 0, - "total": 3 - } - } - ], - "first_id": "vs_abc123", - "last_id": "vs_abc456", - "has_more": false - } - post: - operationId: createVectorStore - tags: - - Vector stores - summary: Create a vector store. - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateVectorStoreRequest" - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/VectorStoreObject" - x-oaiMeta: - name: Create vector store - group: vector_stores - beta: true - returns: A [vector store](/docs/api-reference/vector-stores/object) object. - examples: - request: - curl: | - curl https://api.openai.com/v1/vector_stores \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" - -d '{ - "name": "Support FAQ" - }' - python: | - from openai import OpenAI - client = OpenAI() - - vector_store = client.beta.vector_stores.create( - name="Support FAQ" - ) - print(vector_store) - node.js: | - import OpenAI from "openai"; - const openai = new OpenAI(); - - async function main() { - const vectorStore = await openai.beta.vectorStores.create({ - name: "Support FAQ" - }); - console.log(vectorStore); + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true } + - title: Streaming + request: + curl: | + curl https://api.openai.com/v1/threads/thread_123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_123", + "stream": true + }' + python: | + from openai import OpenAI + client = OpenAI() - main(); - response: | - { - "id": "vs_abc123", - "object": "vector_store", - "created_at": 1699061776, - "name": "Support FAQ", - "bytes": 139920, - "file_counts": { - "in_progress": 0, - "completed": 3, - "failed": 0, - "cancelled": 0, - "total": 3 - } - } - /vector_stores/{vector_store_id}: - get: - operationId: getVectorStore - tags: - - Vector stores - summary: Retrieves a vector store. - parameters: - - in: path - name: vector_store_id - required: true - schema: - type: string - description: The ID of the vector store to retrieve. - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/VectorStoreObject" - x-oaiMeta: - name: Retrieve vector store - group: vector_stores - beta: true - returns: The [vector store](/docs/api-reference/vector-stores/object) object - matching the specified ID. - examples: - request: - curl: | - curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" - python: | - from openai import OpenAI - client = OpenAI() - - vector_store = client.beta.vector_stores.retrieve( - vector_store_id="vs_abc123" - ) - print(vector_store) - node.js: | - import OpenAI from "openai"; - const openai = new OpenAI(); + stream = client.beta.threads.runs.create( + thread_id="thread_123", + assistant_id="asst_123", + stream=True + ) - async function main() { - const vectorStore = await openai.beta.vectorStores.retrieve( - "vs_abc123" - ); - console.log(vectorStore); - } + for event in stream: + print(event) + node.js: | + import OpenAI from "openai"; - main(); - response: | - { - "id": "vs_abc123", - "object": "vector_store", - "created_at": 1699061776 - } - post: - operationId: modifyVectorStore - tags: - - Vector stores - summary: Modifies a vector store. - parameters: - - in: path - name: vector_store_id - required: true - schema: - type: string - description: The ID of the vector store to modify. - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UpdateVectorStoreRequest" - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/VectorStoreObject" - x-oaiMeta: - name: Modify vector store - group: vector_stores - beta: true - returns: The modified [vector store](/docs/api-reference/vector-stores/object) - object. - examples: - request: - curl: | - curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" - -d '{ - "name": "Support FAQ" - }' - python: | - from openai import OpenAI - client = OpenAI() + const openai = new OpenAI(); - vector_store = client.beta.vector_stores.update( - vector_store_id="vs_abc123", - name="Support FAQ" - ) - print(vector_store) - node.js: | - import OpenAI from "openai"; - const openai = new OpenAI(); + async function main() { + const stream = await openai.beta.threads.runs.create( + "thread_123", + { assistant_id: "asst_123", stream: true } + ); - async function main() { - const vectorStore = await openai.beta.vectorStores.update( - "vs_abc123", - { - name: "Support FAQ" + for await (const event of stream) { + console.log(event); } - ); - console.log(vectorStore); - } + } - main(); - response: | - { - "id": "vs_abc123", - "object": "vector_store", - "created_at": 1699061776, - "name": "Support FAQ", - "bytes": 139920, - "file_counts": { - "in_progress": 0, - "completed": 3, - "failed": 0, - "cancelled": 0, - "total": 3 - } - } - delete: - operationId: deleteVectorStore - tags: - - Vector stores - summary: Delete a vector store. - parameters: - - in: path - name: vector_store_id - required: true - schema: - type: string - description: The ID of the vector store to delete. - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/DeleteVectorStoreResponse" - x-oaiMeta: - name: Delete vector store - group: vector_stores - beta: true - returns: Deletion status - examples: - request: - curl: | - curl https://api.openai.com/v1/vector_stores/vs_abc123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -X DELETE - python: | - from openai import OpenAI - client = OpenAI() + main(); + response: > + event: thread.run.created - deleted_vector_store = client.beta.vector_stores.delete( - vector_store_id="vs_abc123" - ) - print(deleted_vector_store) - node.js: | - import OpenAI from "openai"; - const openai = new OpenAI(); + data: + {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - async function main() { - const deletedVectorStore = await openai.beta.vectorStores.del( - "vs_abc123" - ); - console.log(deletedVectorStore); - } - main(); - response: | - { - id: "vs_abc123", - object: "vector_store.deleted", - deleted: true - } - /vector_stores/{vector_store_id}/file_batches: - post: - operationId: createVectorStoreFileBatch - tags: - - Vector stores - summary: Create a vector store file batch. - parameters: - - in: path - name: vector_store_id - required: true - schema: - type: string - example: vs_abc123 - description: | - The ID of the vector store for which to create a File Batch. - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateVectorStoreFileBatchRequest" - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/VectorStoreFileBatchObject" - x-oaiMeta: - name: Create vector store file batch - group: vector_stores - beta: true - returns: A [vector store file - batch](/docs/api-reference/vector-stores-file-batches/batch-object) - object. - examples: - request: - curl: > - curl - https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "file_ids": ["file-abc123", "file-abc456"] - }' - python: > - from openai import OpenAI + event: thread.run.queued - client = OpenAI() + data: + {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - vector_store_file_batch = - client.beta.vector_stores.file_batches.create( - vector_store_id="vs_abc123", - file_ids=["file-abc123", "file-abc456"] - ) + event: thread.run.in_progress - print(vector_store_file_batch) - node.js: > - import OpenAI from "openai"; + data: + {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710330641,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - const openai = new OpenAI(); + event: thread.run.step.created - async function main() { - const myVectorStoreFileBatch = await openai.beta.vectorStores.fileBatches.create( - "vs_abc123", - { - file_ids: ["file-abc123", "file-abc456"] - } - ); - console.log(myVectorStoreFileBatch); - } + data: + {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} - main(); - response: | - { - "id": "vsfb_abc123", - "object": "vector_store.file_batch", - "created_at": 1699061776, - "vector_store_id": "vs_abc123", - "status": "in_progress", - "file_counts": { - "in_progress": 1, - "completed": 1, - "failed": 0, - "cancelled": 0, - "total": 0, - } - } - /vector_stores/{vector_store_id}/file_batches/{batch_id}: - get: - operationId: getVectorStoreFileBatch - tags: - - Vector stores - summary: Retrieves a vector store file batch. - parameters: - - in: path - name: vector_store_id - required: true - schema: - type: string - example: vs_abc123 - description: The ID of the vector store that the file batch belongs to. - - in: path - name: batch_id - required: true - schema: - type: string - example: vsfb_abc123 - description: The ID of the file batch being retrieved. - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/VectorStoreFileBatchObject" - x-oaiMeta: - name: Retrieve vector store file batch - group: vector_stores - beta: true - returns: The [vector store file - batch](/docs/api-reference/vector-stores-file-batches/batch-object) - object. - examples: - request: - curl: > - curl - https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 - \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" - python: > - from openai import OpenAI + event: thread.run.step.in_progress - client = OpenAI() + data: + {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} - vector_store_file_batch = - client.beta.vector_stores.file_batches.retrieve( - vector_store_id="vs_abc123", - batch_id="vsfb_abc123" - ) + event: thread.message.created - print(vector_store_file_batch) - node.js: > - import OpenAI from "openai"; + data: + {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - const openai = new OpenAI(); + event: thread.message.in_progress - async function main() { - const vectorStoreFileBatch = await openai.beta.vectorStores.fileBatches.retrieve( - "vs_abc123", - "vsfb_abc123" - ); - console.log(vectorStoreFileBatch); - } + data: + {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - main(); - response: | - { - "id": "vsfb_abc123", - "object": "vector_store.file_batch", - "created_at": 1699061776, - "vector_store_id": "vs_abc123", - "status": "in_progress", - "file_counts": { - "in_progress": 1, - "completed": 1, - "failed": 0, - "cancelled": 0, - "total": 0, - } - } - /vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel: - post: - operationId: cancelVectorStoreFileBatch - tags: - - Vector stores - summary: Cancel a vector store file batch. This attempts to cancel the - processing of files in this batch as soon as possible. - parameters: - - in: path - name: vector_store_id - required: true - schema: - type: string - description: The ID of the vector store that the file batch belongs to. - - in: path - name: batch_id - required: true - schema: - type: string - description: The ID of the file batch to cancel. - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/VectorStoreFileBatchObject" - x-oaiMeta: - name: Cancel vector store file batch - group: vector_stores - beta: true - returns: The modified vector store file batch object. - examples: - request: - curl: > - curl - https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/cancel - \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -X POST - python: > - from openai import OpenAI + event: thread.message.delta - client = OpenAI() + data: + {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} - deleted_vector_store_file_batch = - client.beta.vector_stores.file_batches.cancel( - vector_store_id="vs_abc123", - file_batch_id="vsfb_abc123" - ) + ... - print(deleted_vector_store_file_batch) - node.js: > - import OpenAI from "openai"; - const openai = new OpenAI(); + event: thread.message.delta + data: + {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" + today"}}]}} - async function main() { - const deletedVectorStoreFileBatch = await openai.vector_stores.fileBatches.cancel( - "vs_abc123", - "vsfb_abc123" - ); - console.log(deletedVectorStoreFileBatch); - } + event: thread.message.delta - main(); - response: | - { - "id": "vsfb_abc123", - "object": "vector_store.file_batch", - "created_at": 1699061776, - "vector_store_id": "vs_abc123", - "status": "in_progress", - "file_counts": { - "in_progress": 12, - "completed": 3, - "failed": 0, - "cancelled": 0, - "total": 15, - } - } - /vector_stores/{vector_store_id}/file_batches/{batch_id}/files: - get: - operationId: listFilesInVectorStoreBatch - tags: - - Vector stores - summary: Returns a list of vector store files in a batch. - parameters: - - name: vector_store_id - in: path - description: The ID of the vector store that the files belong to. - required: true - schema: - type: string - - name: batch_id - in: path - description: The ID of the file batch that the files belong to. - required: true - schema: - type: string - - 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 - - name: order - in: query - description: > - Sort order by the `created_at` timestamp of the objects. `asc` for - ascending order and `desc` for descending order. - schema: - type: string - default: desc - enum: - - asc - - desc - - name: after - in: query - description: > - A cursor for use in pagination. `after` is an object ID that defines - your place in the list. For instance, if you make a list request and - receive 100 objects, ending with obj_foo, your subsequent call can - include after=obj_foo in order to fetch the next page of the list. - schema: - type: string - - name: before - in: query - description: > - A cursor for use in pagination. `before` is an object ID that - defines your place in the list. For instance, if you make a list - request and receive 100 objects, starting with obj_foo, your - subsequent call can include before=obj_foo in order to fetch the - previous page of the list. - schema: - type: string - - name: filter - in: query - description: Filter by file status. One of `in_progress`, `completed`, `failed`, - `cancelled`. - schema: - type: string - enum: - - in_progress - - completed - - failed - - cancelled - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ListVectorStoreFilesResponse" - x-oaiMeta: - name: List vector store files in a batch - group: vector_stores - beta: true - returns: A list of [vector store - file](/docs/api-reference/vector-stores-files/file-object) objects. - examples: - request: - curl: > - curl - https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/files - \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" - python: > - from openai import OpenAI + data: + {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} - client = OpenAI() + event: thread.message.completed - vector_store_files = - client.beta.vector_stores.file_batches.list_files( - vector_store_id="vs_abc123", - batch_id="vsfb_abc123" - ) + data: + {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710330642,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! + How can I assist you today?","annotations":[]}}],"metadata":{}} - print(vector_store_files) - node.js: > - import OpenAI from "openai"; - const openai = new OpenAI(); + event: thread.run.step.completed + data: + {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710330642,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} - async function main() { - const vectorStoreFiles = await openai.beta.vectorStores.fileBatches.listFiles( - "vs_abc123", - "vsfb_abc123" - ); - console.log(vectorStoreFiles); - } + event: thread.run.completed - main(); - response: | - { - "object": "list", - "data": [ - { - "id": "file-abc123", - "object": "vector_store.file", - "created_at": 1699061776, - "vector_store_id": "vs_abc123" - }, - { - "id": "file-abc456", - "object": "vector_store.file", - "created_at": 1699061776, - "vector_store_id": "vs_abc123" - } - ], - "first_id": "file-abc123", - "last_id": "file-abc456", - "has_more": false - } - /vector_stores/{vector_store_id}/files: - get: - operationId: listVectorStoreFiles - tags: - - Vector stores - summary: Returns a list of vector store files. - parameters: - - name: vector_store_id - in: path - description: The ID of the vector store that the files belong to. - required: true - schema: - type: string - - 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 - - name: order - in: query - description: > - Sort order by the `created_at` timestamp of the objects. `asc` for - ascending order and `desc` for descending order. - schema: - type: string - default: desc - enum: - - asc - - desc - - name: after - in: query - description: > - A cursor for use in pagination. `after` is an object ID that defines - your place in the list. For instance, if you make a list request and - receive 100 objects, ending with obj_foo, your subsequent call can - include after=obj_foo in order to fetch the next page of the list. - schema: - type: string - - name: before - in: query - description: > - A cursor for use in pagination. `before` is an object ID that - defines your place in the list. For instance, if you make a list - request and receive 100 objects, starting with obj_foo, your - subsequent call can include before=obj_foo in order to fetch the - previous page of the list. - schema: - type: string - - name: filter - in: query - description: Filter by file status. One of `in_progress`, `completed`, `failed`, - `cancelled`. - schema: - type: string - enum: - - in_progress - - completed - - failed - - cancelled - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ListVectorStoreFilesResponse" - x-oaiMeta: - name: List vector store files - group: vector_stores - beta: true - returns: A list of [vector store - file](/docs/api-reference/vector-stores-files/file-object) objects. - examples: - request: - curl: | - curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" - python: | - from openai import OpenAI - client = OpenAI() + data: + {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710330641,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710330642,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - vector_store_files = client.beta.vector_stores.files.list( - vector_store_id="vs_abc123" - ) - print(vector_store_files) - node.js: > - import OpenAI from "openai"; - const openai = new OpenAI(); + event: done + data: [DONE] + - title: Streaming with Functions + request: + curl: > + curl https://api.openai.com/v1/threads/thread_abc123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123", + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location"] + } + } + } + ], + "stream": true + }' + python: > + from openai import OpenAI - async function main() { - const vectorStoreFiles = await openai.beta.vectorStores.files.list( - "vs_abc123" - ); - console.log(vectorStoreFiles); - } + client = OpenAI() - main(); - response: | - { - "object": "list", - "data": [ - { - "id": "file-abc123", - "object": "vector_store.file", - "created_at": 1699061776, - "vector_store_id": "vs_abc123" - }, - { - "id": "file-abc456", - "object": "vector_store.file", - "created_at": 1699061776, - "vector_store_id": "vs_abc123" + tools = [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location"], + }, + } + } + ] + + + stream = client.beta.threads.runs.create( + thread_id="thread_abc123", + assistant_id="asst_abc123", + tools=tools, + stream=True + ) + + + for event in stream: + print(event) + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + const tools = [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA", + }, + "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, + }, + "required": ["location"], + }, + } + } + ]; + + + async function main() { + const stream = await openai.beta.threads.runs.create( + "thread_abc123", + { + assistant_id: "asst_abc123", + tools: tools, + stream: true + } + ); + + for await (const event of stream) { + console.log(event); + } } - ], - "first_id": "file-abc123", - "last_id": "file-abc456", - "has_more": false - } - post: - operationId: createVectorStoreFile + + + main(); + response: > + event: thread.run.created + + data: + {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + + event: thread.run.queued + + data: + {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + + event: thread.run.in_progress + + data: + {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710348075,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + + event: thread.run.step.created + + data: + {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + + + event: thread.run.step.in_progress + + data: + {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + + + event: thread.message.created + + data: + {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + + + event: thread.message.in_progress + + data: + {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + + + event: thread.message.delta + + data: + {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + + + ... + + + event: thread.message.delta + + data: + {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" + today"}}]}} + + + event: thread.message.delta + + data: + {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + + + event: thread.message.completed + + data: + {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! + How can I assist you today?","annotations":[]}}],"metadata":{}} + + + event: thread.run.step.completed + + data: + {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + + + event: thread.run.completed + + data: + {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710348075,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710348077,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + + event: done + + data: [DONE] + /threads/{thread_id}/runs/{run_id}: + get: + operationId: getRun tags: - - Vector stores - summary: Create a vector store file by attaching a - [File](/docs/api-reference/files) to a [vector - store](/docs/api-reference/vector-stores/object). + - Assistants + summary: Retrieves a run. parameters: - in: path - name: vector_store_id + name: thread_id required: true schema: type: string - example: vs_abc123 - description: | - The ID of the vector store for which to create a File. - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CreateVectorStoreFileRequest" + description: The ID of the [thread](/docs/api-reference/threads) that was run. + - in: path + name: run_id + required: true + schema: + type: string + description: The ID of the run to retrieve. responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/VectorStoreFileObject" + $ref: "#/components/schemas/RunObject" x-oaiMeta: - name: Create vector store file - group: vector_stores + name: Retrieve run + group: threads beta: true - returns: A [vector store - file](/docs/api-reference/vector-stores-files/file-object) object. + returns: The [run](/docs/api-reference/runs/object) object matching the + specified ID. examples: request: - curl: | - curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "file_id": "file-abc123" - }' + curl: > + curl + https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" python: | from openai import OpenAI client = OpenAI() - vector_store_file = client.beta.vector_stores.files.create( - vector_store_id="vs_abc123", - file_id="file-abc123" + run = client.beta.threads.runs.retrieve( + thread_id="thread_abc123", + run_id="run_abc123" ) - print(vector_store_file) - node.js: > + + print(run) + node.js: | import OpenAI from "openai"; const openai = new OpenAI(); - async function main() { - const myVectorStoreFile = await openai.beta.vectorStores.files.create( - "vs_abc123", - { - file_id: "file-abc123" - } + const run = await openai.beta.threads.runs.retrieve( + "thread_abc123", + "run_abc123" ); - console.log(myVectorStoreFile); - } + console.log(run); + } main(); response: | { - "id": "file-abc123", - "object": "vector_store.file", - "created_at": 1699061776, - "usage_bytes": 1234, - "vector_store_id": "vs_abcd", - "status": "completed", - "last_error": null - } - /vector_stores/{vector_store_id}/files/{file_id}: - get: - operationId: getVectorStoreFile + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + post: + operationId: modifyRun tags: - - Vector stores - summary: Retrieves a vector store file. + - Assistants + summary: Modifies a run. parameters: - in: path - name: vector_store_id + name: thread_id required: true schema: type: string - example: vs_abc123 - description: The ID of the vector store that the file belongs to. + description: The ID of the [thread](/docs/api-reference/threads) that was run. - in: path - name: file_id + name: run_id required: true schema: type: string - example: file-abc123 - description: The ID of the file being retrieved. + description: The ID of the run to modify. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ModifyRunRequest" responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/VectorStoreFileObject" + $ref: "#/components/schemas/RunObject" x-oaiMeta: - name: Retrieve vector store file - group: vector_stores + name: Modify run + group: threads beta: true - returns: The [vector store - file](/docs/api-reference/vector-stores-files/file-object) object. + returns: The modified [run](/docs/api-reference/runs/object) object matching the + specified ID. examples: request: curl: > curl - https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 - \ + https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "metadata": { + "user_id": "user_abc123" + } + }' python: | from openai import OpenAI client = OpenAI() - vector_store_file = client.beta.vector_stores.files.retrieve( - vector_store_id="vs_abc123", - file_id="file-abc123" + run = client.beta.threads.runs.update( + thread_id="thread_abc123", + run_id="run_abc123", + metadata={"user_id": "user_abc123"}, ) - print(vector_store_file) - node.js: > + + print(run) + node.js: | import OpenAI from "openai"; const openai = new OpenAI(); - async function main() { - const vectorStoreFile = await openai.beta.vectorStores.files.retrieve( - "vs_abc123", - "file-abc123" + const run = await openai.beta.threads.runs.update( + "thread_abc123", + "run_abc123", + { + metadata: { + user_id: "user_abc123", + }, + } ); - console.log(vectorStoreFile); - } + console.log(run); + } main(); response: | { - "id": "file-abc123", - "object": "vector_store.file", - "created_at": 1699061776, - "vector_store_id": "vs_abcd", + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", "status": "completed", - "last_error": null + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": { + "user_id": "user_abc123" + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true } - delete: - operationId: deleteVectorStoreFile + /threads/{thread_id}/runs/{run_id}/cancel: + post: + operationId: cancelRun tags: - - Vector stores - summary: Delete a vector store file. This will remove the file from the vector - store but the file itself will not be deleted. To delete the file, use - the [delete file](/docs/api-reference/files/delete) endpoint. + - Assistants + summary: Cancels a run that is `in_progress`. parameters: - in: path - name: vector_store_id + name: thread_id required: true schema: type: string - description: The ID of the vector store that the file belongs to. + description: The ID of the thread to which this run belongs. - in: path - name: file_id + name: run_id required: true schema: type: string - description: The ID of the file to delete. + description: The ID of the run to cancel. responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/DeleteVectorStoreFileResponse" + $ref: "#/components/schemas/RunObject" x-oaiMeta: - name: Delete vector store file - group: vector_stores + name: Cancel a run + group: threads beta: true - returns: Deletion status + returns: The modified [run](/docs/api-reference/runs/object) object matching the + specified ID. examples: request: curl: > curl - https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 + https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v2" \ - -X DELETE - python: > + -X POST + python: | from openai import OpenAI - client = OpenAI() - - deleted_vector_store_file = - client.beta.vector_stores.files.delete( - vector_store_id="vs_abc123", - file_id="file-abc123" + run = client.beta.threads.runs.cancel( + thread_id="thread_abc123", + run_id="run_abc123" ) - print(deleted_vector_store_file) - node.js: > + print(run) + node.js: | import OpenAI from "openai"; const openai = new OpenAI(); - async function main() { - const deletedVectorStoreFile = await openai.beta.vectorStores.files.del( - "vs_abc123", - "file-abc123" + const run = await openai.beta.threads.runs.cancel( + "thread_abc123", + "run_abc123" ); - console.log(deletedVectorStoreFile); - } + console.log(run); + } main(); response: | { - id: "file-abc123", - object: "vector_store.file.deleted", - deleted: true + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699076126, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "cancelling", + "started_at": 1699076126, + "expires_at": 1699076726, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "last_error": null, + "model": "gpt-4o", + "instructions": "You summarize books.", + "tools": [ + { + "type": "file_search" + } + ], + "tool_resources": { + "file_search": { + "vector_store_ids": ["vs_123"] + } + }, + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true } -components: - schemas: - AddUploadPartRequest: - type: object - additionalProperties: false - properties: - data: - description: | - The chunk of bytes for this Part. - type: string - format: binary - required: - - data - AdminApiKey: - type: object - properties: - object: - type: string - example: organization.admin_api_key - id: - type: string - example: key_abc - name: - type: string - example: Administration Key - redacted_value: - type: string - example: sk-admin...def - value: - type: string - example: sk-admin-1234abcd - created_at: - type: integer - format: int64 - example: 1711471533 - owner: - type: object - properties: - type: - type: string - example: service_account - id: - type: string - example: sa_456 - name: - type: string - example: My Service Account - created_at: - type: integer - format: int64 - example: 1711471533 - role: - type: string - example: member - ApiKeyList: - type: object - properties: - object: - type: string - example: list - data: - type: array - items: - $ref: "#/components/schemas/AdminApiKey" - has_more: - type: boolean - example: false - first_id: - type: string - example: key_abc - last_id: - type: string - example: key_xyz - AssistantObject: - type: object - title: Assistant - description: Represents an `assistant` that can call the model and use tools. - properties: - id: - description: The identifier, which can be referenced in API endpoints. - type: string - object: - description: The object type, which is always `assistant`. - type: string - enum: - - assistant - x-stainless-const: true - created_at: - description: The Unix timestamp (in seconds) for when the assistant was created. - type: integer - name: - description: | - The name of the assistant. The maximum length is 256 characters. - type: string - maxLength: 256 - nullable: true - description: - description: > - The description of the assistant. The maximum length is 512 - characters. - type: string - maxLength: 512 - nullable: true - model: - description: > - ID of the model to use. You can use the [List - models](/docs/api-reference/models/list) API to see all of your - available models, or see our [Model overview](/docs/models) for - descriptions of them. - type: string - instructions: + /threads/{thread_id}/runs/{run_id}/steps: + get: + operationId: listRunSteps + tags: + - Assistants + summary: Returns a list of run steps belonging to a run. + parameters: + - name: thread_id + in: path + required: true + schema: + type: string + description: The ID of the thread the run and run steps belong to. + - name: run_id + in: path + required: true + schema: + type: string + description: The ID of the run the run steps belong to. + - name: limit + in: query description: > - The system instructions that the assistant uses. The maximum length - is 256,000 characters. - type: string - maxLength: 256000 - nullable: true - tools: + 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 + - name: order + in: query description: > - A list of tool enabled on the assistant. There can be a maximum of - 128 tools per assistant. Tools can be of types `code_interpreter`, - `file_search`, or `function`. - default: [] - type: array - maxItems: 128 - items: - oneOf: - - $ref: "#/components/schemas/AssistantToolsCode" - - $ref: "#/components/schemas/AssistantToolsFileSearch" - - $ref: "#/components/schemas/AssistantToolsFunction" - x-oaiExpandable: true - tool_resources: - type: object + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query description: > - A set of resources that are used by the assistant's tools. The - resources are specific to the type of tool. For example, the - `code_interpreter` tool requires a list of file IDs, while the - `file_search` tool requires a list of vector store IDs. - properties: - code_interpreter: - type: object - properties: - file_ids: - type: array - description: > - A list of [file](/docs/api-reference/files) IDs made - available to the `code_interpreter`` tool. There can be a - maximum of 20 files associated with the tool. - default: [] - maxItems: 20 - items: - type: string - file_search: - type: object - properties: - vector_store_ids: - type: array - description: > - The ID of the [vector - store](/docs/api-reference/vector-stores/object) attached to - this assistant. There can be a maximum of 1 vector store - attached to the assistant. - maxItems: 1 - items: - type: string - nullable: true - metadata: - $ref: "#/components/schemas/Metadata" - temperature: + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query 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. - type: number - minimum: 0 - maximum: 2 - default: 1 - example: 1 - nullable: true - top_p: - type: number - minimum: 0 - maximum: 1 - default: 1 - example: 1 - nullable: true + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + - name: include[] + in: query 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. + A list of additional fields to include in the response. Currently + the only supported value is + `step_details.tool_calls[*].file_search.results[*].content` to fetch + the file search result content. - We generally recommend altering this or temperature but not both. - response_format: - allOf: - - $ref: "#/components/schemas/AssistantsApiResponseFormatOption" - - nullable: true - required: - - id - - object - - created_at - - name - - description - - model - - instructions - - tools - - metadata - x-oaiMeta: - name: The assistant object + See the [file search tool + documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) + for more information. + schema: + type: array + items: + type: string + enum: + - step_details.tool_calls[*].file_search.results[*].content + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListRunStepsResponse" + x-oaiMeta: + name: List run steps + group: threads beta: true - example: > - { - "id": "asst_abc123", - "object": "assistant", - "created_at": 1698984975, - "name": "Math Tutor", - "description": null, - "model": "gpt-4o", - "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", - "tools": [ - { - "type": "code_interpreter" - } - ], - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" - } - AssistantStreamEvent: - description: > - Represents an event emitted when streaming a Run. - - - Each event in a server-sent events stream has an `event` and `data` - property: - - - ``` - - event: thread.created - - data: {"id": "thread_123", "object": "thread", ...} - - ``` - + returns: A list of [run step](/docs/api-reference/run-steps/step-object) + objects. + examples: + request: + curl: > + curl + https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps + \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() - We emit events whenever a new object is created, transitions to a new - state, or is being + run_steps = client.beta.threads.runs.steps.list( + thread_id="thread_abc123", + run_id="run_abc123" + ) - streamed in parts (deltas). For example, we emit `thread.run.created` - when a new run + print(run_steps) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); - is created, `thread.run.completed` when a run completes, and so on. When - an Assistant chooses + async function main() { + const runStep = await openai.beta.threads.runs.steps.list( + "thread_abc123", + "run_abc123" + ); + console.log(runStep); + } - to create a message during a run, we emit a `thread.message.created - event`, a + main(); + response: | + { + "object": "list", + "data": [ + { + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", + "status": "completed", + "cancelled_at": null, + "completed_at": 1699063291, + "expired_at": null, + "failed_at": null, + "last_error": null, + "step_details": { + "type": "message_creation", + "message_creation": { + "message_id": "msg_abc123" + } + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + } + } + ], + "first_id": "step_abc123", + "last_id": "step_abc456", + "has_more": false + } + /threads/{thread_id}/runs/{run_id}/steps/{step_id}: + get: + operationId: getRunStep + tags: + - Assistants + summary: Retrieves a run step. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the thread to which the run and run step belongs. + - in: path + name: run_id + required: true + schema: + type: string + description: The ID of the run to which the run step belongs. + - in: path + name: step_id + required: true + schema: + type: string + description: The ID of the run step to retrieve. + - name: include[] + in: query + description: > + A list of additional fields to include in the response. Currently + the only supported value is + `step_details.tool_calls[*].file_search.results[*].content` to fetch + the file search result content. - `thread.message.in_progress` event, many `thread.message.delta` events, - and finally a - `thread.message.completed` event. + See the [file search tool + documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) + for more information. + schema: + type: array + items: + type: string + enum: + - step_details.tool_calls[*].file_search.results[*].content + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/RunStepObject" + x-oaiMeta: + name: Retrieve run step + group: threads + beta: true + returns: The [run step](/docs/api-reference/run-steps/step-object) object + matching the specified ID. + examples: + request: + curl: > + curl + https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123 + \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + run_step = client.beta.threads.runs.steps.retrieve( + thread_id="thread_abc123", + run_id="run_abc123", + step_id="step_abc123" + ) - We may add additional events over time, so we recommend handling unknown - events gracefully + print(run_step) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); - in your code. See the [Assistants API - quickstart](/docs/assistants/overview) to learn how to + async function main() { + const runStep = await openai.beta.threads.runs.steps.retrieve( + "thread_abc123", + "run_abc123", + "step_abc123" + ); + console.log(runStep); + } - integrate the Assistants API with streaming. - oneOf: - - $ref: "#/components/schemas/ThreadStreamEvent" - - $ref: "#/components/schemas/RunStreamEvent" - - $ref: "#/components/schemas/RunStepStreamEvent" - - $ref: "#/components/schemas/MessageStreamEvent" - - $ref: "#/components/schemas/ErrorEvent" - - $ref: "#/components/schemas/DoneEvent" - x-oaiMeta: - name: Assistant stream events - beta: true - AssistantSupportedModels: - type: string - enum: - - o3-mini - - o3-mini-2025-01-31 - - o1 - - o1-2024-12-17 - - gpt-4o - - gpt-4o-2024-11-20 - - gpt-4o-2024-08-06 - - gpt-4o-2024-05-13 - - gpt-4o-mini - - gpt-4o-mini-2024-07-18 - - gpt-4-turbo - - gpt-4-turbo-2024-04-09 - - gpt-4-0125-preview - - gpt-4-turbo-preview - - gpt-4-1106-preview - - gpt-4-vision-preview - - gpt-4 - - gpt-4-0314 - - gpt-4-0613 - - gpt-4-32k - - gpt-4-32k-0314 - - gpt-4-32k-0613 - - gpt-3.5-turbo - - gpt-3.5-turbo-16k - - gpt-3.5-turbo-0613 - - gpt-3.5-turbo-1106 - - gpt-3.5-turbo-0125 - - gpt-3.5-turbo-16k-0613 - AssistantToolsCode: - type: object - title: Code interpreter tool - properties: - type: - type: string - description: "The type of tool being defined: `code_interpreter`" - enum: - - code_interpreter - x-stainless-const: true - required: - - type - AssistantToolsFileSearch: - type: object - title: FileSearch tool - properties: - type: - type: string - description: "The type of tool being defined: `file_search`" - enum: - - file_search - x-stainless-const: true - file_search: - type: object - description: Overrides for the file search tool. - properties: - max_num_results: - type: integer - minimum: 1 - maximum: 50 - description: > - The maximum number of results the file search tool should - output. The default is 20 for `gpt-4*` models and 5 for - `gpt-3.5-turbo`. This number should be between 1 and 50 - inclusive. - - - Note that the file search tool may output fewer than - `max_num_results` results. See the [file search tool - documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) - for more information. - ranking_options: - $ref: "#/components/schemas/FileSearchRankingOptions" - required: - - type - AssistantToolsFileSearchTypeOnly: - type: object - title: FileSearch tool - properties: - type: - type: string - description: "The type of tool being defined: `file_search`" - enum: - - file_search - x-stainless-const: true - required: - - type - AssistantToolsFunction: - type: object - title: Function tool - properties: - type: - type: string - description: "The type of tool being defined: `function`" - enum: - - function - x-stainless-const: true - function: - $ref: "#/components/schemas/FunctionObject" - required: - - type - - function - AssistantsApiResponseFormatOption: - description: > - Specifies the format that the model must output. Compatible with - [GPT-4o](/docs/models#gpt-4o), [GPT-4 - Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models - since `gpt-3.5-turbo-1106`. - - - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables - Structured Outputs which ensures the model will match your supplied JSON - schema. Learn more in the [Structured Outputs - guide](/docs/guides/structured-outputs). - - - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures - the message the model generates is valid JSON. + main(); + response: | + { + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", + "status": "completed", + "cancelled_at": null, + "completed_at": 1699063291, + "expired_at": null, + "failed_at": null, + "last_error": null, + "step_details": { + "type": "message_creation", + "message_creation": { + "message_id": "msg_abc123" + } + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + } + } + /threads/{thread_id}/runs/{run_id}/submit_tool_outputs: + post: + operationId: submitToolOuputsToRun + tags: + - Assistants + summary: > + When a run has the `status: "requires_action"` and + `required_action.type` is `submit_tool_outputs`, this endpoint can be + used to submit the outputs from the tool calls once they're all + completed. All outputs must be submitted in a single request. + parameters: + - in: path + name: thread_id + required: true + schema: + type: string + description: The ID of the [thread](/docs/api-reference/threads) to which this + run belongs. + - in: path + name: run_id + required: true + schema: + type: string + description: The ID of the run that requires the tool output submission. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/SubmitToolOutputsRunRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/RunObject" + x-oaiMeta: + name: Submit tool outputs to run + group: threads + beta: true + returns: The modified [run](/docs/api-reference/runs/object) object matching the + specified ID. + examples: + - title: Default + request: + curl: > + curl + https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs + \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "tool_outputs": [ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ] + }' + python: | + from openai import OpenAI + client = OpenAI() + run = client.beta.threads.runs.submit_tool_outputs( + thread_id="thread_123", + run_id="run_123", + tool_outputs=[ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ] + ) - **Important:** when using JSON mode, you **must** also instruct the - model to produce JSON yourself via a system or user message. Without - this, the model may generate an unending stream of whitespace until the - generation reaches the token limit, resulting in a long-running and - seemingly "stuck" request. Also note that the message content may be - partially cut off if `finish_reason="length"`, which indicates the - generation exceeded `max_tokens` or the conversation exceeded the max - context length. - oneOf: - - type: string - description: | - `auto` is the default value - enum: - - auto - x-stainless-const: true - - $ref: "#/components/schemas/ResponseFormatText" - - $ref: "#/components/schemas/ResponseFormatJsonObject" - - $ref: "#/components/schemas/ResponseFormatJsonSchema" - x-oaiExpandable: true - AssistantsApiToolChoiceOption: - description: > - Controls which (if any) tool is called by the model. + print(run) + node.js: | + import OpenAI from "openai"; - `none` means the model will not call any tools and instead generates a - message. + const openai = new OpenAI(); - `auto` is the default value and means the model can pick between - generating a message or calling one or more tools. + async function main() { + const run = await openai.beta.threads.runs.submitToolOutputs( + "thread_123", + "run_123", + { + tool_outputs: [ + { + tool_call_id: "call_001", + output: "70 degrees and sunny.", + }, + ], + } + ); - `required` means the model must call one or more tools before responding - to the user. + console.log(run); + } - Specifying a particular tool like `{"type": "file_search"}` or `{"type": - "function", "function": {"name": "my_function"}}` forces the model to - call that tool. - oneOf: - - type: string - description: > - `none` means the model will not call any tools 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 before responding to the user. - enum: - - none - - auto - - required - - $ref: "#/components/schemas/AssistantsNamedToolChoice" + main(); + response: > + { + "id": "run_123", + "object": "thread.run", + "created_at": 1699075592, + "assistant_id": "asst_123", + "thread_id": "thread_123", + "status": "queued", + "started_at": 1699075592, + "expires_at": 1699076192, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather in a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and state, e.g. San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"] + } + }, + "required": ["location"] + } + } + } + ], + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + } + - title: Streaming + request: + curl: > + curl + https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs + \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "tool_outputs": [ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ], + "stream": true + }' + python: | + from openai import OpenAI + client = OpenAI() + + stream = client.beta.threads.runs.submit_tool_outputs( + thread_id="thread_123", + run_id="run_123", + tool_outputs=[ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ], + stream=True + ) + + for event in stream: + print(event) + node.js: > + import OpenAI from "openai"; + + + const openai = new OpenAI(); + + + async function main() { + const stream = await openai.beta.threads.runs.submitToolOutputs( + "thread_123", + "run_123", + { + tool_outputs: [ + { + tool_call_id: "call_001", + output: "70 degrees and sunny.", + }, + ], + } + ); + + for await (const event of stream) { + console.log(event); + } + } + + + main(); + response: > + event: thread.run.step.completed + + data: + {"id":"step_001","object":"thread.run.step","created_at":1710352449,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"completed","cancelled_at":null,"completed_at":1710352475,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[{"id":"call_iWr0kQ2EaYMaxNdl0v3KYkx7","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San + Francisco, CA\",\"unit\":\"fahrenheit\"}","output":"70 degrees and + sunny."}}]},"usage":{"prompt_tokens":291,"completion_tokens":24,"total_tokens":315}} + + + event: thread.run.queued + + data: + {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":1710352448,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get + the current weather in a given + location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The + city and state, e.g. San Francisco, + CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + + event: thread.run.in_progress + + data: + {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710352475,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get + the current weather in a given + location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The + city and state, e.g. San Francisco, + CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + + event: thread.run.step.created + + data: + {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} + + + event: thread.run.step.in_progress + + data: + {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} + + + event: thread.message.created + + data: + {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + + + event: thread.message.in_progress + + data: + {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + + + event: thread.message.delta + + data: + {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"The","annotations":[]}}]}} + + + event: thread.message.delta + + data: + {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" + current"}}]}} + + + event: thread.message.delta + + data: + {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" + weather"}}]}} + + + ... + + + event: thread.message.delta + + data: + {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" + sunny"}}]}} + + + event: thread.message.delta + + data: + {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"."}}]}} + + + event: thread.message.completed + + data: + {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710352477,"role":"assistant","content":[{"type":"text","text":{"value":"The + current weather in San Francisco, CA is 70 degrees Fahrenheit and + sunny.","annotations":[]}}],"metadata":{}} + + + event: thread.run.step.completed + + data: + {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710352477,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":{"prompt_tokens":329,"completion_tokens":18,"total_tokens":347}} + + + event: thread.run.completed + + data: + {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710352475,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710352477,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get + the current weather in a given + location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The + city and state, e.g. San Francisco, + CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + + + event: done + + data: [DONE] + /uploads: + post: + operationId: createUpload + tags: + - Uploads + summary: > + Creates an intermediate [Upload](/docs/api-reference/uploads/object) + object + + that you can add [Parts](/docs/api-reference/uploads/part-object) to. + + Currently, an Upload can accept at most 8 GB in total and expires after + an + + hour after you create it. + + + Once you complete the Upload, we will create a + + [File](/docs/api-reference/files/object) object that contains all the + parts + + you uploaded. This File is usable in the rest of our platform as a + regular + + File object. + + + For certain `purpose` values, the correct `mime_type` must be + specified. + + Please refer to documentation for the + + [supported MIME types for your use + case](/docs/assistants/tools/file-search#supported-files). + + + For guidance on the proper filename extensions for each purpose, please + + follow the documentation on [creating a + + File](/docs/api-reference/files/create). + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateUploadRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/Upload" + x-oaiMeta: + name: Create upload + group: uploads + returns: The [Upload](/docs/api-reference/uploads/object) object with status + `pending`. + examples: + request: + curl: | + curl https://api.openai.com/v1/uploads \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "purpose": "fine-tune", + "filename": "training_examples.jsonl", + "bytes": 2147483648, + "mime_type": "text/jsonl" + }' + response: | + { + "id": "upload_abc123", + "object": "upload", + "bytes": 2147483648, + "created_at": 1719184911, + "filename": "training_examples.jsonl", + "purpose": "fine-tune", + "status": "pending", + "expires_at": 1719127296 + } + /uploads/{upload_id}/cancel: + post: + operationId: cancelUpload + tags: + - Uploads + summary: | + Cancels the Upload. No Parts may be added after an Upload is cancelled. + parameters: + - in: path + name: upload_id + required: true + schema: + type: string + example: upload_abc123 + description: | + The ID of the Upload. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/Upload" + x-oaiMeta: + name: Cancel upload + group: uploads + returns: The [Upload](/docs/api-reference/uploads/object) object with status + `cancelled`. + examples: + request: + curl: | + curl https://api.openai.com/v1/uploads/upload_abc123/cancel + response: | + { + "id": "upload_abc123", + "object": "upload", + "bytes": 2147483648, + "created_at": 1719184911, + "filename": "training_examples.jsonl", + "purpose": "fine-tune", + "status": "cancelled", + "expires_at": 1719127296 + } + /uploads/{upload_id}/complete: + post: + operationId: completeUpload + tags: + - Uploads + summary: > + Completes the [Upload](/docs/api-reference/uploads/object). + + + Within the returned Upload object, there is a nested + [File](/docs/api-reference/files/object) object that is ready to use in + the rest of the platform. + + + You can specify the order of the Parts by passing in an ordered list of + the Part IDs. + + + The number of bytes uploaded upon completion must match the number of + bytes initially specified when creating the Upload object. No Parts may + be added after an Upload is completed. + parameters: + - in: path + name: upload_id + required: true + schema: + type: string + example: upload_abc123 + description: | + The ID of the Upload. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CompleteUploadRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/Upload" + x-oaiMeta: + name: Complete upload + group: uploads + returns: The [Upload](/docs/api-reference/uploads/object) object with status + `completed` with an additional `file` property containing the created + usable File object. + examples: + request: + curl: | + curl https://api.openai.com/v1/uploads/upload_abc123/complete + -d '{ + "part_ids": ["part_def456", "part_ghi789"] + }' + response: | + { + "id": "upload_abc123", + "object": "upload", + "bytes": 2147483648, + "created_at": 1719184911, + "filename": "training_examples.jsonl", + "purpose": "fine-tune", + "status": "completed", + "expires_at": 1719127296, + "file": { + "id": "file-xyz321", + "object": "file", + "bytes": 2147483648, + "created_at": 1719186911, + "filename": "training_examples.jsonl", + "purpose": "fine-tune", + } + } + /uploads/{upload_id}/parts: + post: + operationId: addUploadPart + tags: + - Uploads + summary: > + Adds a [Part](/docs/api-reference/uploads/part-object) to an + [Upload](/docs/api-reference/uploads/object) object. A Part represents a + chunk of bytes from the file you are trying to upload. + + + Each Part can be at most 64 MB, and you can add Parts until you hit the + Upload maximum of 8 GB. + + + It is possible to add multiple Parts in parallel. You can decide the + intended order of the Parts when you [complete the + Upload](/docs/api-reference/uploads/complete). + parameters: + - in: path + name: upload_id + required: true + schema: + type: string + example: upload_abc123 + description: | + The ID of the Upload. + requestBody: + required: true + content: + multipart/form-data: + schema: + $ref: "#/components/schemas/AddUploadPartRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/UploadPart" + x-oaiMeta: + name: Add upload part + group: uploads + returns: The upload [Part](/docs/api-reference/uploads/part-object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/uploads/upload_abc123/parts + -F data="aHR0cHM6Ly9hcGkub3BlbmFpLmNvbS92MS91cGxvYWRz..." + response: | + { + "id": "part_def456", + "object": "upload.part", + "created_at": 1719185911, + "upload_id": "upload_abc123" + } + /vector_stores: + get: + operationId: listVectorStores + tags: + - Vector stores + summary: Returns a list of vector stores. + parameters: + - 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 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListVectorStoresResponse" + x-oaiMeta: + name: List vector stores + group: vector_stores + returns: A list of [vector store](/docs/api-reference/vector-stores/object) + objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + vector_stores = client.vector_stores.list() + print(vector_stores) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const vectorStores = await openai.vectorStores.list(); + console.log(vectorStores); + } + + main(); + response: | + { + "object": "list", + "data": [ + { + "id": "vs_abc123", + "object": "vector_store", + "created_at": 1699061776, + "name": "Support FAQ", + "bytes": 139920, + "file_counts": { + "in_progress": 0, + "completed": 3, + "failed": 0, + "cancelled": 0, + "total": 3 + } + }, + { + "id": "vs_abc456", + "object": "vector_store", + "created_at": 1699061776, + "name": "Support FAQ v2", + "bytes": 139920, + "file_counts": { + "in_progress": 0, + "completed": 3, + "failed": 0, + "cancelled": 0, + "total": 3 + } + } + ], + "first_id": "vs_abc123", + "last_id": "vs_abc456", + "has_more": false + } + post: + operationId: createVectorStore + tags: + - Vector stores + summary: Create a vector store. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateVectorStoreRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreObject" + x-oaiMeta: + name: Create vector store + group: vector_stores + returns: A [vector store](/docs/api-reference/vector-stores/object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "name": "Support FAQ" + }' + python: | + from openai import OpenAI + client = OpenAI() + + vector_store = client.vector_stores.create( + name="Support FAQ" + ) + print(vector_store) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const vectorStore = await openai.vectorStores.create({ + name: "Support FAQ" + }); + console.log(vectorStore); + } + + main(); + response: | + { + "id": "vs_abc123", + "object": "vector_store", + "created_at": 1699061776, + "name": "Support FAQ", + "bytes": 139920, + "file_counts": { + "in_progress": 0, + "completed": 3, + "failed": 0, + "cancelled": 0, + "total": 3 + } + } + /vector_stores/{vector_store_id}: + get: + operationId: getVectorStore + tags: + - Vector stores + summary: Retrieves a vector store. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + description: The ID of the vector store to retrieve. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreObject" + x-oaiMeta: + name: Retrieve vector store + group: vector_stores + returns: The [vector store](/docs/api-reference/vector-stores/object) object + matching the specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + vector_store = client.vector_stores.retrieve( + vector_store_id="vs_abc123" + ) + print(vector_store) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const vectorStore = await openai.vectorStores.retrieve( + "vs_abc123" + ); + console.log(vectorStore); + } + + main(); + response: | + { + "id": "vs_abc123", + "object": "vector_store", + "created_at": 1699061776 + } + post: + operationId: modifyVectorStore + tags: + - Vector stores + summary: Modifies a vector store. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + description: The ID of the vector store to modify. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateVectorStoreRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreObject" + x-oaiMeta: + name: Modify vector store + group: vector_stores + returns: The modified [vector store](/docs/api-reference/vector-stores/object) + object. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + -d '{ + "name": "Support FAQ" + }' + python: | + from openai import OpenAI + client = OpenAI() + + vector_store = client.vector_stores.update( + vector_store_id="vs_abc123", + name="Support FAQ" + ) + print(vector_store) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const vectorStore = await openai.vectorStores.update( + "vs_abc123", + { + name: "Support FAQ" + } + ); + console.log(vectorStore); + } + + main(); + response: | + { + "id": "vs_abc123", + "object": "vector_store", + "created_at": 1699061776, + "name": "Support FAQ", + "bytes": 139920, + "file_counts": { + "in_progress": 0, + "completed": 3, + "failed": 0, + "cancelled": 0, + "total": 3 + } + } + delete: + operationId: deleteVectorStore + tags: + - Vector stores + summary: Delete a vector store. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + description: The ID of the vector store to delete. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteVectorStoreResponse" + x-oaiMeta: + name: Delete vector store + group: vector_stores + returns: Deletion status + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -X DELETE + python: | + from openai import OpenAI + client = OpenAI() + + deleted_vector_store = client.vector_stores.delete( + vector_store_id="vs_abc123" + ) + print(deleted_vector_store) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const deletedVectorStore = await openai.vectorStores.del( + "vs_abc123" + ); + console.log(deletedVectorStore); + } + + main(); + response: | + { + id: "vs_abc123", + object: "vector_store.deleted", + deleted: true + } + /vector_stores/{vector_store_id}/file_batches: + post: + operationId: createVectorStoreFileBatch + tags: + - Vector stores + summary: Create a vector store file batch. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: | + The ID of the vector store for which to create a File Batch. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateVectorStoreFileBatchRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileBatchObject" + x-oaiMeta: + name: Create vector store file batch + group: vector_stores + returns: A [vector store file + batch](/docs/api-reference/vector-stores-file-batches/batch-object) + object. + examples: + request: + curl: > + curl + https://api.openai.com/v1/vector_stores/vs_abc123/file_batches \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "file_ids": ["file-abc123", "file-abc456"] + }' + python: > + from openai import OpenAI + + client = OpenAI() + + + vector_store_file_batch = + client.vector_stores.file_batches.create( + vector_store_id="vs_abc123", + file_ids=["file-abc123", "file-abc456"] + ) + + print(vector_store_file_batch) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const myVectorStoreFileBatch = await openai.vectorStores.fileBatches.create( + "vs_abc123", + { + file_ids: ["file-abc123", "file-abc456"] + } + ); + console.log(myVectorStoreFileBatch); + } + + + main(); + response: | + { + "id": "vsfb_abc123", + "object": "vector_store.file_batch", + "created_at": 1699061776, + "vector_store_id": "vs_abc123", + "status": "in_progress", + "file_counts": { + "in_progress": 1, + "completed": 1, + "failed": 0, + "cancelled": 0, + "total": 0, + } + } + /vector_stores/{vector_store_id}/file_batches/{batch_id}: + get: + operationId: getVectorStoreFileBatch + tags: + - Vector stores + summary: Retrieves a vector store file batch. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: The ID of the vector store that the file batch belongs to. + - in: path + name: batch_id + required: true + schema: + type: string + example: vsfb_abc123 + description: The ID of the file batch being retrieved. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileBatchObject" + x-oaiMeta: + name: Retrieve vector store file batch + group: vector_stores + returns: The [vector store file + batch](/docs/api-reference/vector-stores-file-batches/batch-object) + object. + examples: + request: + curl: > + curl + https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123 + \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: > + from openai import OpenAI + + client = OpenAI() + + + vector_store_file_batch = + client.vector_stores.file_batches.retrieve( + vector_store_id="vs_abc123", + batch_id="vsfb_abc123" + ) + + print(vector_store_file_batch) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const vectorStoreFileBatch = await openai.vectorStores.fileBatches.retrieve( + "vs_abc123", + "vsfb_abc123" + ); + console.log(vectorStoreFileBatch); + } + + + main(); + response: | + { + "id": "vsfb_abc123", + "object": "vector_store.file_batch", + "created_at": 1699061776, + "vector_store_id": "vs_abc123", + "status": "in_progress", + "file_counts": { + "in_progress": 1, + "completed": 1, + "failed": 0, + "cancelled": 0, + "total": 0, + } + } + /vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel: + post: + operationId: cancelVectorStoreFileBatch + tags: + - Vector stores + summary: Cancel a vector store file batch. This attempts to cancel the + processing of files in this batch as soon as possible. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + description: The ID of the vector store that the file batch belongs to. + - in: path + name: batch_id + required: true + schema: + type: string + description: The ID of the file batch to cancel. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileBatchObject" + x-oaiMeta: + name: Cancel vector store file batch + group: vector_stores + returns: The modified vector store file batch object. + examples: + request: + curl: > + curl + https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/cancel + \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -X POST + python: > + from openai import OpenAI + + client = OpenAI() + + + deleted_vector_store_file_batch = + client.vector_stores.file_batches.cancel( + vector_store_id="vs_abc123", + file_batch_id="vsfb_abc123" + ) + + print(deleted_vector_store_file_batch) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const deletedVectorStoreFileBatch = await openai.vectorStores.fileBatches.cancel( + "vs_abc123", + "vsfb_abc123" + ); + console.log(deletedVectorStoreFileBatch); + } + + + main(); + response: | + { + "id": "vsfb_abc123", + "object": "vector_store.file_batch", + "created_at": 1699061776, + "vector_store_id": "vs_abc123", + "status": "in_progress", + "file_counts": { + "in_progress": 12, + "completed": 3, + "failed": 0, + "cancelled": 0, + "total": 15, + } + } + /vector_stores/{vector_store_id}/file_batches/{batch_id}/files: + get: + operationId: listFilesInVectorStoreBatch + tags: + - Vector stores + summary: Returns a list of vector store files in a batch. + parameters: + - name: vector_store_id + in: path + description: The ID of the vector store that the files belong to. + required: true + schema: + type: string + - name: batch_id + in: path + description: The ID of the file batch that the files belong to. + required: true + schema: + type: string + - 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 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + - name: filter + in: query + description: Filter by file status. One of `in_progress`, `completed`, `failed`, + `cancelled`. + schema: + type: string + enum: + - in_progress + - completed + - failed + - cancelled + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListVectorStoreFilesResponse" + x-oaiMeta: + name: List vector store files in a batch + group: vector_stores + returns: A list of [vector store + file](/docs/api-reference/vector-stores-files/file-object) objects. + examples: + request: + curl: > + curl + https://api.openai.com/v1/vector_stores/vs_abc123/files_batches/vsfb_abc123/files + \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + vector_store_files = client.vector_stores.file_batches.list_files( + vector_store_id="vs_abc123", + batch_id="vsfb_abc123" + ) + print(vector_store_files) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const vectorStoreFiles = await openai.vectorStores.fileBatches.listFiles( + "vs_abc123", + "vsfb_abc123" + ); + console.log(vectorStoreFiles); + } + + + main(); + response: | + { + "object": "list", + "data": [ + { + "id": "file-abc123", + "object": "vector_store.file", + "created_at": 1699061776, + "vector_store_id": "vs_abc123" + }, + { + "id": "file-abc456", + "object": "vector_store.file", + "created_at": 1699061776, + "vector_store_id": "vs_abc123" + } + ], + "first_id": "file-abc123", + "last_id": "file-abc456", + "has_more": false + } + /vector_stores/{vector_store_id}/files: + get: + operationId: listVectorStoreFiles + tags: + - Vector stores + summary: Returns a list of vector store files. + parameters: + - name: vector_store_id + in: path + description: The ID of the vector store that the files belong to. + required: true + schema: + type: string + - 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 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + schema: + type: string + - name: filter + in: query + description: Filter by file status. One of `in_progress`, `completed`, `failed`, + `cancelled`. + schema: + type: string + enum: + - in_progress + - completed + - failed + - cancelled + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/ListVectorStoreFilesResponse" + x-oaiMeta: + name: List vector store files + group: vector_stores + returns: A list of [vector store + file](/docs/api-reference/vector-stores-files/file-object) objects. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + vector_store_files = client.vector_stores.files.list( + vector_store_id="vs_abc123" + ) + print(vector_store_files) + node.js: | + import OpenAI from "openai"; + const openai = new OpenAI(); + + async function main() { + const vectorStoreFiles = await openai.vectorStores.files.list( + "vs_abc123" + ); + console.log(vectorStoreFiles); + } + + main(); + response: | + { + "object": "list", + "data": [ + { + "id": "file-abc123", + "object": "vector_store.file", + "created_at": 1699061776, + "vector_store_id": "vs_abc123" + }, + { + "id": "file-abc456", + "object": "vector_store.file", + "created_at": 1699061776, + "vector_store_id": "vs_abc123" + } + ], + "first_id": "file-abc123", + "last_id": "file-abc456", + "has_more": false + } + post: + operationId: createVectorStoreFile + tags: + - Vector stores + summary: Create a vector store file by attaching a + [File](/docs/api-reference/files) to a [vector + store](/docs/api-reference/vector-stores/object). + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: | + The ID of the vector store for which to create a File. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateVectorStoreFileRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileObject" + x-oaiMeta: + name: Create vector store file + group: vector_stores + returns: A [vector store + file](/docs/api-reference/vector-stores-files/file-object) object. + examples: + request: + curl: | + curl https://api.openai.com/v1/vector_stores/vs_abc123/files \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "file_id": "file-abc123" + }' + python: | + from openai import OpenAI + client = OpenAI() + + vector_store_file = client.vector_stores.files.create( + vector_store_id="vs_abc123", + file_id="file-abc123" + ) + print(vector_store_file) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const myVectorStoreFile = await openai.vectorStores.files.create( + "vs_abc123", + { + file_id: "file-abc123" + } + ); + console.log(myVectorStoreFile); + } + + + main(); + response: | + { + "id": "file-abc123", + "object": "vector_store.file", + "created_at": 1699061776, + "usage_bytes": 1234, + "vector_store_id": "vs_abcd", + "status": "completed", + "last_error": null + } + /vector_stores/{vector_store_id}/files/{file_id}: + get: + operationId: getVectorStoreFile + tags: + - Vector stores + summary: Retrieves a vector store file. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: The ID of the vector store that the file belongs to. + - in: path + name: file_id + required: true + schema: + type: string + example: file-abc123 + description: The ID of the file being retrieved. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileObject" + x-oaiMeta: + name: Retrieve vector store file + group: vector_stores + returns: The [vector store + file](/docs/api-reference/vector-stores-files/file-object) object. + examples: + request: + curl: > + curl + https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 + \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" + python: | + from openai import OpenAI + client = OpenAI() + + vector_store_file = client.vector_stores.files.retrieve( + vector_store_id="vs_abc123", + file_id="file-abc123" + ) + print(vector_store_file) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const vectorStoreFile = await openai.vectorStores.files.retrieve( + "vs_abc123", + "file-abc123" + ); + console.log(vectorStoreFile); + } + + + main(); + response: | + { + "id": "file-abc123", + "object": "vector_store.file", + "created_at": 1699061776, + "vector_store_id": "vs_abcd", + "status": "completed", + "last_error": null + } + delete: + operationId: deleteVectorStoreFile + tags: + - Vector stores + summary: Delete a vector store file. This will remove the file from the vector + store but the file itself will not be deleted. To delete the file, use + the [delete file](/docs/api-reference/files/delete) endpoint. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + description: The ID of the vector store that the file belongs to. + - in: path + name: file_id + required: true + schema: + type: string + description: The ID of the file to delete. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/DeleteVectorStoreFileResponse" + x-oaiMeta: + name: Delete vector store file + group: vector_stores + returns: Deletion status + examples: + request: + curl: > + curl + https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123 + \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -X DELETE + python: | + from openai import OpenAI + client = OpenAI() + + deleted_vector_store_file = client.vector_stores.files.delete( + vector_store_id="vs_abc123", + file_id="file-abc123" + ) + print(deleted_vector_store_file) + node.js: > + import OpenAI from "openai"; + + const openai = new OpenAI(); + + + async function main() { + const deletedVectorStoreFile = await openai.vectorStores.files.del( + "vs_abc123", + "file-abc123" + ); + console.log(deletedVectorStoreFile); + } + + + main(); + response: | + { + id: "file-abc123", + object: "vector_store.file.deleted", + deleted: true + } + post: + operationId: updateVectorStoreFileAttributes + tags: + - Vector stores + summary: Update attributes on a vector store file. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: The ID of the vector store the file belongs to. + - in: path + name: file_id + required: true + schema: + type: string + example: file-abc123 + description: The ID of the file to update attributes. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateVectorStoreFileAttributesRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileObject" + x-oaiMeta: + name: Update vector store file attributes + group: vector_stores + returns: The updated [vector store + file](/docs/api-reference/vector-stores-files/file-object) object. + examples: + request: + curl: > + curl + https://api.openai.com/v1/vector_stores/{vector_store_id}/files/{file_id} + \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"attributes": {"key1": "value1", "key2": 2}}' + response: | + { + "id": "file-abc123", + "object": "vector_store.file", + "usage_bytes": 1234, + "created_at": 1699061776, + "vector_store_id": "vs_abcd", + "status": "completed", + "last_error": null, + "chunking_strategy": {...}, + "attributes": {"key1": "value1", "key2": 2} + } + /vector_stores/{vector_store_id}/files/{file_id}/content: + get: + operationId: retrieveVectorStoreFileContent + tags: + - Vector stores + summary: Retrieve the parsed contents of a vector store file. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: The ID of the vector store. + - in: path + name: file_id + required: true + schema: + type: string + example: file-abc123 + description: The ID of the file within the vector store. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreFileContentResponse" + x-oaiMeta: + name: Retrieve vector store file content + group: vector_stores + returns: The parsed contents of the specified vector store file. + examples: + request: + curl: > + curl \ + + https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content + \ + + -H "Authorization: Bearer $OPENAI_API_KEY" + response: | + { + "file_id": "file-abc123", + "filename": "example.txt", + "attributes": {"key": "value"}, + "content": [ + {"type": "text", "text": "..."}, + ... + ] + } + /vector_stores/{vector_store_id}/search: + post: + operationId: searchVectorStore + tags: + - Vector stores + summary: Search a vector store for relevant chunks based on a query and file + attributes filter. + parameters: + - in: path + name: vector_store_id + required: true + schema: + type: string + example: vs_abc123 + description: The ID of the vector store to search. + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreSearchRequest" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/VectorStoreSearchResultsPage" + x-oaiMeta: + name: Search vector store + group: vector_stores + returns: A page of search results from the vector store. + examples: + request: + curl: | + curl -X POST \ + https://api.openai.com/v1/vector_stores/vs_abc123/search \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"query": "What is the return policy?", "filters": {...}}' + response: | + { + "object": "vector_store.search_results.page", + "search_query": "What is the return policy?", + "data": [ + { + "file_id": "file_123", + "filename": "document.pdf", + "score": 0.95, + "attributes": { + "author": "John Doe", + "date": "2023-01-01" + }, + "content": [ + { + "type": "text", + "text": "Relevant chunk" + } + ] + }, + { + "file_id": "file_456", + "filename": "notes.txt", + "score": 0.89, + "attributes": { + "author": "Jane Smith", + "date": "2023-01-02" + }, + "content": [ + { + "type": "text", + "text": "Sample text content from the vector store." + } + ] + } + ], + "has_more": false, + "next_page": null + } +components: + schemas: + AddUploadPartRequest: + type: object + additionalProperties: false + properties: + data: + description: | + The chunk of bytes for this Part. + type: string + format: binary + required: + - data + AdminApiKey: + type: object + properties: + object: + type: string + example: organization.admin_api_key + id: + type: string + example: key_abc + name: + type: string + example: Administration Key + redacted_value: + type: string + example: sk-admin...def + value: + type: string + example: sk-admin-1234abcd + created_at: + type: integer + format: int64 + example: 1711471533 + owner: + type: object + properties: + type: + type: string + example: service_account + id: + type: string + example: sa_456 + name: + type: string + example: My Service Account + created_at: + type: integer + format: int64 + example: 1711471533 + role: + type: string + example: member + Annotation: + oneOf: + - $ref: "#/components/schemas/FileCitation" + - $ref: "#/components/schemas/UrlCitation" + - $ref: "#/components/schemas/FilePath" + ApiKeyList: + type: object + properties: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/AdminApiKey" + has_more: + type: boolean + example: false + first_id: + type: string + example: key_abc + last_id: + type: string + example: key_xyz + AssistantObject: + type: object + title: Assistant + description: Represents an `assistant` that can call the model and use tools. + properties: + id: + description: The identifier, which can be referenced in API endpoints. + type: string + object: + description: The object type, which is always `assistant`. + type: string + enum: + - assistant + x-stainless-const: true + created_at: + description: The Unix timestamp (in seconds) for when the assistant was created. + type: integer + name: + description: | + The name of the assistant. The maximum length is 256 characters. + type: string + maxLength: 256 + nullable: true + description: + description: > + The description of the assistant. The maximum length is 512 + characters. + type: string + maxLength: 512 + nullable: true + model: + description: > + ID of the model to use. You can use the [List + models](/docs/api-reference/models/list) API to see all of your + available models, or see our [Model overview](/docs/models) for + descriptions of them. + type: string + instructions: + description: > + The system instructions that the assistant uses. The maximum length + is 256,000 characters. + type: string + maxLength: 256000 + nullable: true + tools: + description: > + A list of tool enabled on the assistant. There can be a maximum of + 128 tools per assistant. Tools can be of types `code_interpreter`, + `file_search`, or `function`. + default: [] + type: array + maxItems: 128 + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearch" + - $ref: "#/components/schemas/AssistantToolsFunction" + x-oaiExpandable: true + tool_resources: + type: object + description: > + A set of resources that are used by the assistant's tools. The + resources are specific to the type of tool. For example, the + `code_interpreter` tool requires a list of file IDs, while the + `file_search` tool requires a list of vector store IDs. + properties: + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs made + available to the `code_interpreter`` tool. There can be a + maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + The ID of the [vector + store](/docs/api-reference/vector-stores/object) attached to + this assistant. There can be a maximum of 1 vector store + attached to the assistant. + maxItems: 1 + items: + type: string + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + temperature: + 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. + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + 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. + response_format: + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true + required: + - id + - object + - created_at + - name + - description + - model + - instructions + - tools + - metadata + x-oaiMeta: + name: The assistant object + beta: true + example: > + { + "id": "asst_abc123", + "object": "assistant", + "created_at": 1698984975, + "name": "Math Tutor", + "description": null, + "model": "gpt-4o", + "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", + "tools": [ + { + "type": "code_interpreter" + } + ], + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + } + AssistantStreamEvent: + description: > + Represents an event emitted when streaming a Run. + + + Each event in a server-sent events stream has an `event` and `data` + property: + + + ``` + + event: thread.created + + data: {"id": "thread_123", "object": "thread", ...} + + ``` + + + We emit events whenever a new object is created, transitions to a new + state, or is being + + streamed in parts (deltas). For example, we emit `thread.run.created` + when a new run + + is created, `thread.run.completed` when a run completes, and so on. When + an Assistant chooses + + to create a message during a run, we emit a `thread.message.created + event`, a + + `thread.message.in_progress` event, many `thread.message.delta` events, + and finally a + + `thread.message.completed` event. + + + We may add additional events over time, so we recommend handling unknown + events gracefully + + in your code. See the [Assistants API + quickstart](/docs/assistants/overview) to learn how to + + integrate the Assistants API with streaming. + oneOf: + - $ref: "#/components/schemas/ThreadStreamEvent" + - $ref: "#/components/schemas/RunStreamEvent" + - $ref: "#/components/schemas/RunStepStreamEvent" + - $ref: "#/components/schemas/MessageStreamEvent" + - $ref: "#/components/schemas/ErrorEvent" + - $ref: "#/components/schemas/DoneEvent" + x-oaiMeta: + name: Assistant stream events + beta: true + AssistantSupportedModels: + type: string + enum: + - o3-mini + - o3-mini-2025-01-31 + - o1 + - o1-2024-12-17 + - gpt-4o + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o-mini + - gpt-4o-mini-2024-07-18 + - gpt-4.5-preview + - gpt-4.5-preview-2025-02-27 + - gpt-4-turbo + - gpt-4-turbo-2024-04-09 + - gpt-4-0125-preview + - gpt-4-turbo-preview + - gpt-4-1106-preview + - gpt-4-vision-preview + - gpt-4 + - gpt-4-0314 + - gpt-4-0613 + - gpt-4-32k + - gpt-4-32k-0314 + - gpt-4-32k-0613 + - gpt-3.5-turbo + - gpt-3.5-turbo-16k + - gpt-3.5-turbo-0613 + - gpt-3.5-turbo-1106 + - gpt-3.5-turbo-0125 + - gpt-3.5-turbo-16k-0613 + AssistantToolsCode: + type: object + title: Code interpreter tool + properties: + type: + type: string + description: "The type of tool being defined: `code_interpreter`" + enum: + - code_interpreter + x-stainless-const: true + required: + - type + AssistantToolsFileSearch: + type: object + title: FileSearch tool + properties: + type: + type: string + description: "The type of tool being defined: `file_search`" + enum: + - file_search + x-stainless-const: true + file_search: + type: object + description: Overrides for the file search tool. + properties: + max_num_results: + type: integer + minimum: 1 + maximum: 50 + description: > + The maximum number of results the file search tool should + output. The default is 20 for `gpt-4*` models and 5 for + `gpt-3.5-turbo`. This number should be between 1 and 50 + inclusive. + + + Note that the file search tool may output fewer than + `max_num_results` results. See the [file search tool + documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) + for more information. + ranking_options: + $ref: "#/components/schemas/FileSearchRankingOptions" + required: + - type + AssistantToolsFileSearchTypeOnly: + type: object + title: FileSearch tool + properties: + type: + type: string + description: "The type of tool being defined: `file_search`" + enum: + - file_search + x-stainless-const: true + required: + - type + AssistantToolsFunction: + type: object + title: Function tool + properties: + type: + type: string + description: "The type of tool being defined: `function`" + enum: + - function + x-stainless-const: true + function: + $ref: "#/components/schemas/FunctionObject" + required: + - type + - function + AssistantsApiResponseFormatOption: + description: > + Specifies the format that the model must output. Compatible with + [GPT-4o](/docs/models#gpt-4o), [GPT-4 + Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models + since `gpt-3.5-turbo-1106`. + + + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables + Structured Outputs which ensures the model will match your supplied JSON + schema. Learn more in the [Structured Outputs + guide](/docs/guides/structured-outputs). + + + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures + the message the model generates is valid JSON. + + + **Important:** when using JSON mode, you **must** also instruct the + model to produce JSON yourself via a system or user message. Without + this, the model may generate an unending stream of whitespace until the + generation reaches the token limit, resulting in a long-running and + seemingly "stuck" request. Also note that the message content may be + partially cut off if `finish_reason="length"`, which indicates the + generation exceeded `max_tokens` or the conversation exceeded the max + context length. + oneOf: + - type: string + description: | + `auto` is the default value + enum: + - auto + x-stainless-const: true + - $ref: "#/components/schemas/ResponseFormatText" + - $ref: "#/components/schemas/ResponseFormatJsonObject" + - $ref: "#/components/schemas/ResponseFormatJsonSchema" + x-oaiExpandable: true + AssistantsApiToolChoiceOption: + description: > + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tools and instead generates a + message. + + `auto` is the default value and means the model can pick between + generating a message or calling one or more tools. + + `required` means the model must call one or more tools before responding + to the user. + + Specifying a particular tool like `{"type": "file_search"}` or `{"type": + "function", "function": {"name": "my_function"}}` forces the model to + call that tool. + oneOf: + - type: string + description: > + `none` means the model will not call any tools 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 before responding to the user. + enum: + - none + - auto + - required + - $ref: "#/components/schemas/AssistantsNamedToolChoice" x-oaiExpandable: true AssistantsNamedToolChoice: type: object @@ -12229,452 +14582,1183 @@ components: description: The role of the service account. Is either `owner` or `member`. service_account.deleted: type: object - description: The details for events with this `type`. + description: The details for events with this `type`. + properties: + id: + type: string + description: The service account ID. + user.added: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The user ID. + data: + type: object + description: The payload used to add the user to the project. + properties: + role: + type: string + description: The role of the user. Is either `owner` or `member`. + user.updated: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The project ID. + changes_requested: + type: object + description: The payload used to update the user. + properties: + role: + type: string + description: The role of the user. Is either `owner` or `member`. + user.deleted: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The user ID. + required: + - id + - type + - effective_at + - actor + x-oaiMeta: + name: The audit log object + example: > + { + "id": "req_xxx_20240101", + "type": "api_key.created", + "effective_at": 1720804090, + "actor": { + "type": "session", + "session": { + "user": { + "id": "user-xxx", + "email": "user@example.com" + }, + "ip_address": "127.0.0.1", + "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" + } + }, + "api_key.created": { + "id": "key_xxxx", + "data": { + "scopes": ["resource.operation"] + } + } + } + AuditLogActor: + type: object + description: The actor who performed the audit logged action. + properties: + type: + type: string + description: The type of actor. Is either `session` or `api_key`. + enum: + - session + - api_key + session: + $ref: "#/components/schemas/AuditLogActorSession" + api_key: + $ref: "#/components/schemas/AuditLogActorApiKey" + AuditLogActorApiKey: + type: object + description: The API Key used to perform the audit logged action. + properties: + id: + type: string + description: The tracking id of the API key. + type: + type: string + description: The type of API key. Can be either `user` or `service_account`. + enum: + - user + - service_account + user: + $ref: "#/components/schemas/AuditLogActorUser" + service_account: + $ref: "#/components/schemas/AuditLogActorServiceAccount" + AuditLogActorServiceAccount: + type: object + description: The service account that performed the audit logged action. + properties: + id: + type: string + description: The service account id. + AuditLogActorSession: + type: object + description: The session in which the audit logged action was performed. + properties: + user: + $ref: "#/components/schemas/AuditLogActorUser" + ip_address: + type: string + description: The IP address from which the action was performed. + AuditLogActorUser: + type: object + description: The user who performed the audit logged action. + properties: + id: + type: string + description: The user id. + email: + type: string + description: The user email. + AuditLogEventType: + type: string + description: The event type. + x-oaiExpandable: true + enum: + - api_key.created + - api_key.updated + - api_key.deleted + - invite.sent + - invite.accepted + - invite.deleted + - login.succeeded + - login.failed + - logout.succeeded + - logout.failed + - organization.updated + - project.created + - project.updated + - project.archived + - service_account.created + - service_account.updated + - service_account.deleted + - rate_limit.updated + - rate_limit.deleted + - user.added + - user.updated + - user.deleted + AutoChunkingStrategyRequestParam: + type: object + title: Auto Chunking Strategy + description: The default strategy. This strategy currently uses a + `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + additionalProperties: false + properties: + type: + type: string + description: Always `auto`. + enum: + - auto + x-stainless-const: true + required: + - type + Batch: + type: object + properties: + id: + type: string + object: + type: string + enum: + - batch + description: The object type, which is always `batch`. + x-stainless-const: true + endpoint: + type: string + description: The OpenAI API endpoint used by the batch. + errors: + type: object + properties: + object: + type: string + description: The object type, which is always `list`. + data: + type: array + items: + type: object + properties: + code: + type: string + description: An error code identifying the error type. + message: + type: string + description: A human-readable message providing more details about the error. + param: + type: string + description: The name of the parameter that caused the error, if applicable. + nullable: true + line: + type: integer + description: The line number of the input file where the error occurred, if + applicable. + nullable: true + input_file_id: + type: string + description: The ID of the input file for the batch. + completion_window: + type: string + description: The time frame within which the batch should be processed. + status: + type: string + description: The current status of the batch. + enum: + - validating + - failed + - in_progress + - finalizing + - completed + - expired + - cancelling + - cancelled + output_file_id: + type: string + description: The ID of the file containing the outputs of successfully executed + requests. + error_file_id: + type: string + description: The ID of the file containing the outputs of requests with errors. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch was created. + in_progress_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch started + processing. + expires_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch will expire. + finalizing_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch started + finalizing. + completed_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch was completed. + failed_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch failed. + expired_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch expired. + cancelling_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch started + cancelling. + cancelled_at: + type: integer + description: The Unix timestamp (in seconds) for when the batch was cancelled. + request_counts: + type: object properties: - id: - type: string - description: The service account ID. - user.added: + total: + type: integer + description: Total number of requests in the batch. + completed: + type: integer + description: Number of requests that have been completed successfully. + failed: + type: integer + description: Number of requests that have failed. + required: + - total + - completed + - failed + description: The request counts for different statuses within the batch. + metadata: + $ref: "#/components/schemas/Metadata" + required: + - id + - object + - endpoint + - input_file_id + - completion_window + - status + - created_at + x-oaiMeta: + name: The batch object + example: | + { + "id": "batch_abc123", + "object": "batch", + "endpoint": "/v1/completions", + "errors": null, + "input_file_id": "file-abc123", + "completion_window": "24h", + "status": "completed", + "output_file_id": "file-cvaTdG", + "error_file_id": "file-HOWS94", + "created_at": 1711471533, + "in_progress_at": 1711471538, + "expires_at": 1711557933, + "finalizing_at": 1711493133, + "completed_at": 1711493163, + "failed_at": null, + "expired_at": null, + "cancelling_at": null, + "cancelled_at": null, + "request_counts": { + "total": 100, + "completed": 95, + "failed": 5 + }, + "metadata": { + "customer_id": "user_123456789", + "batch_description": "Nightly eval job", + } + } + BatchRequestInput: + type: object + description: The per-line object of the batch input file + properties: + custom_id: + type: string + description: A developer-provided per-request id that will be used to match + outputs to inputs. Must be unique for each request in a batch. + method: + type: string + enum: + - POST + description: The HTTP method to be used for the request. Currently only `POST` + is supported. + x-stainless-const: true + url: + type: string + description: The OpenAI API relative URL to be used for the request. Currently + `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are + supported. + x-oaiMeta: + name: The request input object + example: > + {"custom_id": "request-1", "method": "POST", "url": + "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": + [{"role": "system", "content": "You are a helpful assistant."}, + {"role": "user", "content": "What is 2+2?"}]}} + BatchRequestOutput: + type: object + description: The per-line object of the batch output and error files + properties: + id: + type: string + custom_id: + type: string + description: A developer-provided per-request id that will be used to match + outputs to inputs. + response: type: object - description: The details for events with this `type`. + nullable: true properties: - id: + status_code: + type: integer + description: The HTTP status code of the response + request_id: type: string - description: The user ID. - data: + description: An unique identifier for the OpenAI API request. Please include + this request ID when contacting support. + body: type: object - description: The payload used to add the user to the project. - properties: - role: - type: string - description: The role of the user. Is either `owner` or `member`. - user.updated: + x-oaiTypeLabel: map + description: The JSON body of the response + error: type: object - description: The details for events with this `type`. + nullable: true + description: For requests that failed with a non-HTTP error, this will contain + more information on the cause of the failure. properties: - id: + code: type: string - description: The project ID. - changes_requested: - type: object - description: The payload used to update the user. - properties: - role: - type: string - description: The role of the user. Is either `owner` or `member`. - user.deleted: - type: object - description: The details for events with this `type`. - properties: - id: + description: A machine-readable error code. + message: type: string - description: The user ID. + description: A human-readable error message. + x-oaiMeta: + name: The request output object + example: > + {"id": "batch_req_wnaDys", "custom_id": "request-2", "response": + {"status_code": 200, "request_id": "req_c187b3", "body": {"id": + "chatcmpl-9758Iw", "object": "chat.completion", "created": 1711475054, + "model": "gpt-4o-mini", "choices": [{"index": 0, "message": {"role": + "assistant", "content": "2 + 2 equals 4."}, "finish_reason": "stop"}], + "usage": {"prompt_tokens": 24, "completion_tokens": 15, + "total_tokens": 39}, "system_fingerprint": null}}, "error": null} + CancelUploadRequest: + type: object + additionalProperties: false + ChatCompletionDeleted: + type: object + properties: + object: + type: string + description: The type of object being deleted. + enum: + - chat.completion.deleted + x-stainless-const: true + id: + type: string + description: The ID of the chat completion that was deleted. + deleted: + type: boolean + description: Whether the chat completion was deleted. + required: + - object + - id + - deleted + ChatCompletionFunctionCallOption: + type: object + description: > + Specifying a particular function via `{"name": "my_function"}` forces + the model to call that function. + properties: + name: + type: string + description: The name of the function to call. + required: + - name + ChatCompletionFunctions: + type: object + deprecated: true + properties: + description: + type: string + description: A description of what the function does, used by the model to + choose when and how to call the function. + name: + type: string + description: The name of the function to be called. Must be a-z, A-Z, 0-9, or + contain underscores and dashes, with a maximum length of 64. + parameters: + $ref: "#/components/schemas/FunctionParameters" + required: + - name + ChatCompletionList: + type: object + title: ChatCompletionList + description: | + An object representing a list of Chat Completions. + properties: + object: + type: string + enum: + - list + default: list + description: | + The type of this object. It is always set to "list". + x-stainless-const: true + data: + type: array + description: | + An array of chat completion objects. + items: + $ref: "#/components/schemas/CreateChatCompletionResponse" + first_id: + type: string + description: The identifier of the first chat completion in the data array. + last_id: + type: string + description: The identifier of the last chat completion in the data array. + has_more: + type: boolean + description: Indicates whether there are more Chat Completions available. required: - - id - - type - - effective_at - - actor + - object + - data + - first_id + - last_id + - has_more x-oaiMeta: - name: The audit log object + name: The chat completion list object + group: chat example: > { - "id": "req_xxx_20240101", - "type": "api_key.created", - "effective_at": 1720804090, - "actor": { - "type": "session", - "session": { - "user": { - "id": "user-xxx", - "email": "user@example.com" - }, - "ip_address": "127.0.0.1", - "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" - } - }, - "api_key.created": { - "id": "key_xxxx", - "data": { - "scopes": ["resource.operation"] + "object": "list", + "data": [ + { + "object": "chat.completion", + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "model": "gpt-4o-2024-08-06", + "created": 1738960610, + "request_id": "req_ded8ab984ec4bf840f37566c1011c417", + "tool_choice": null, + "usage": { + "total_tokens": 31, + "completion_tokens": 18, + "prompt_tokens": 13 + }, + "seed": 4944116822809979520, + "top_p": 1.0, + "temperature": 1.0, + "presence_penalty": 0.0, + "frequency_penalty": 0.0, + "system_fingerprint": "fp_50cad350e4", + "input_user": null, + "service_tier": "default", + "tools": null, + "metadata": {}, + "choices": [ + { + "index": 0, + "message": { + "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.", + "role": "assistant", + "tool_calls": null, + "function_call": null + }, + "finish_reason": "stop", + "logprobs": null } + ], + "response_format": null } + ], + "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", + "has_more": false } - AuditLogActor: + ChatCompletionMessageList: type: object - description: The actor who performed the audit logged action. + title: ChatCompletionMessageList + description: | + An object representing a list of chat completion messages. properties: - type: + object: type: string - description: The type of actor. Is either `session` or `api_key`. enum: - - session - - api_key - session: - $ref: "#/components/schemas/AuditLogActorSession" - api_key: - $ref: "#/components/schemas/AuditLogActorApiKey" - AuditLogActorApiKey: - type: object - description: The API Key used to perform the audit logged action. - properties: - id: + - list + default: list + description: | + The type of this object. It is always set to "list". + x-stainless-const: true + data: + type: array + description: | + An array of chat completion message objects. + items: + allOf: + - $ref: "#/components/schemas/ChatCompletionResponseMessage" + - type: object + required: + - id + properties: + id: + type: string + description: The identifier of the chat message. + first_id: type: string - description: The tracking id of the API key. - type: + description: The identifier of the first chat message in the data array. + last_id: type: string - description: The type of API key. Can be either `user` or `service_account`. - enum: - - user - - service_account - user: - $ref: "#/components/schemas/AuditLogActorUser" - service_account: - $ref: "#/components/schemas/AuditLogActorServiceAccount" - AuditLogActorServiceAccount: + description: The identifier of the last chat message in the data array. + has_more: + type: boolean + description: Indicates whether there are more chat messages available. + required: + - object + - data + - first_id + - last_id + - has_more + x-oaiMeta: + name: The chat completion message list object + group: chat + example: | + { + "object": "list", + "data": [ + { + "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "role": "user", + "content": "write a haiku about ai", + "name": null, + "content_parts": null + } + ], + "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", + "has_more": false + } + ChatCompletionMessageToolCall: type: object - description: The service account that performed the audit logged action. properties: id: type: string - description: The service account id. - AuditLogActorSession: - type: object - description: The session in which the audit logged action was performed. - properties: - user: - $ref: "#/components/schemas/AuditLogActorUser" - ip_address: + description: The ID of the tool call. + type: type: string - description: The IP address from which the action was performed. - AuditLogActorUser: + enum: + - function + description: The type of the tool. Currently, only `function` is supported. + x-stainless-const: true + function: + type: object + description: The function that the model called. + properties: + name: + type: string + description: The name of the function to call. + arguments: + type: string + description: The arguments to call the function with, as generated by the model + in JSON format. Note that the model does not always generate + valid JSON, and may hallucinate parameters not defined by your + function schema. Validate the arguments in your code before + calling your function. + required: + - name + - arguments + required: + - id + - type + - function + ChatCompletionMessageToolCallChunk: type: object - description: The user who performed the audit logged action. properties: + index: + type: integer id: type: string - description: The user id. - email: + description: The ID of the tool call. + type: type: string - description: The user email. - AuditLogEventType: - type: string - description: The event type. - x-oaiExpandable: true - enum: - - api_key.created - - api_key.updated - - api_key.deleted - - invite.sent - - invite.accepted - - invite.deleted - - login.succeeded - - login.failed - - logout.succeeded - - logout.failed - - organization.updated - - project.created - - project.updated - - project.archived - - service_account.created - - service_account.updated - - service_account.deleted - - rate_limit.updated - - rate_limit.deleted - - user.added - - user.updated - - user.deleted - AutoChunkingStrategyRequestParam: + enum: + - function + description: The type of the tool. Currently, only `function` is supported. + x-stainless-const: true + function: + type: object + properties: + name: + type: string + description: The name of the function to call. + arguments: + type: string + description: The arguments to call the function with, as generated by the model + in JSON format. Note that the model does not always generate + valid JSON, and may hallucinate parameters not defined by your + function schema. Validate the arguments in your code before + calling your function. + required: + - index + ChatCompletionMessageToolCalls: + type: array + description: The tool calls generated by the model, such as function calls. + items: + $ref: "#/components/schemas/ChatCompletionMessageToolCall" + ChatCompletionModalities: + type: array + nullable: true + description: > + Output types that you would like the model to generate for this request. + + Most models are capable of generating text, which is the default: + + + `["text"]` + + + The `gpt-4o-audio-preview` model can also be used to [generate + audio](/docs/guides/audio). To + + request that this model generate both text and audio responses, you can + + use: + + + `["text", "audio"]` + items: + type: string + enum: + - text + - audio + ChatCompletionNamedToolChoice: type: object - title: Auto Chunking Strategy - description: The default strategy. This strategy currently uses a - `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - additionalProperties: false + description: Specifies a tool the model should use. Use to force the model to + call a specific function. properties: type: type: string - description: Always `auto`. enum: - - auto + - function + description: The type of the tool. Currently, only `function` is supported. x-stainless-const: true + function: + type: object + properties: + name: + type: string + description: The name of the function to call. + required: + - name required: - type - Batch: + - function + ChatCompletionRequestAssistantMessage: type: object + title: Assistant message + description: | + Messages sent by the model in response to user messages. properties: - id: + content: + x-oaiExpandable: true + nullable: true + oneOf: + - type: string + description: The contents of the assistant message. + title: Text content + - type: array + description: An array of content parts with a defined type. Can be one or more + of type `text`, or exactly one of type `refusal`. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestAssistantMessageContentPart" + minItems: 1 + description: > + The contents of the assistant message. Required unless `tool_calls` + or `function_call` is specified. + refusal: + nullable: true type: string - object: + description: The refusal message by the assistant. + role: type: string enum: - - batch - description: The object type, which is always `batch`. + - assistant + description: The role of the messages author, in this case `assistant`. x-stainless-const: true - endpoint: + name: type: string - description: The OpenAI API endpoint used by the batch. - errors: + description: An optional name for the participant. Provides the model + information to differentiate between participants of the same role. + audio: type: object + nullable: true + x-oaiExpandable: true + description: | + Data about a previous audio response from the model. + [Learn more](/docs/guides/audio). + required: + - id properties: - object: + id: type: string - description: The object type, which is always `list`. - data: - type: array - items: - type: object - properties: - code: - type: string - description: An error code identifying the error type. - message: - type: string - description: A human-readable message providing more details about the error. - param: - type: string - description: The name of the parameter that caused the error, if applicable. - nullable: true - line: - type: integer - description: The line number of the input file where the error occurred, if - applicable. - nullable: true - input_file_id: - type: string - description: The ID of the input file for the batch. - completion_window: - type: string - description: The time frame within which the batch should be processed. - status: - type: string - description: The current status of the batch. - enum: - - validating - - failed - - in_progress - - finalizing - - completed - - expired - - cancelling - - cancelled - output_file_id: - type: string - description: The ID of the file containing the outputs of successfully executed - requests. - error_file_id: - type: string - description: The ID of the file containing the outputs of requests with errors. - created_at: - type: integer - description: The Unix timestamp (in seconds) for when the batch was created. - in_progress_at: - type: integer - description: The Unix timestamp (in seconds) for when the batch started - processing. - expires_at: - type: integer - description: The Unix timestamp (in seconds) for when the batch will expire. - finalizing_at: - type: integer - description: The Unix timestamp (in seconds) for when the batch started - finalizing. - completed_at: - type: integer - description: The Unix timestamp (in seconds) for when the batch was completed. - failed_at: - type: integer - description: The Unix timestamp (in seconds) for when the batch failed. - expired_at: - type: integer - description: The Unix timestamp (in seconds) for when the batch expired. - cancelling_at: - type: integer - description: The Unix timestamp (in seconds) for when the batch started - cancelling. - cancelled_at: - type: integer - description: The Unix timestamp (in seconds) for when the batch was cancelled. - request_counts: + description: | + Unique identifier for a previous audio response from the model. + tool_calls: + $ref: "#/components/schemas/ChatCompletionMessageToolCalls" + function_call: type: object + deprecated: true + description: Deprecated and replaced by `tool_calls`. The name and arguments of + a function that should be called, as generated by the model. + nullable: true properties: - total: - type: integer - description: Total number of requests in the batch. - completed: - type: integer - description: Number of requests that have been completed successfully. - failed: - type: integer - description: Number of requests that have failed. + arguments: + type: string + description: The arguments to call the function with, as generated by the model + in JSON format. Note that the model does not always generate + valid JSON, and may hallucinate parameters not defined by your + function schema. Validate the arguments in your code before + calling your function. + name: + type: string + description: The name of the function to call. required: - - total - - completed - - failed - description: The request counts for different statuses within the batch. - metadata: - $ref: "#/components/schemas/Metadata" + - arguments + - name required: - - id - - object - - endpoint - - input_file_id - - completion_window - - status - - created_at - x-oaiMeta: - name: The batch object - example: | - { - "id": "batch_abc123", - "object": "batch", - "endpoint": "/v1/completions", - "errors": null, - "input_file_id": "file-abc123", - "completion_window": "24h", - "status": "completed", - "output_file_id": "file-cvaTdG", - "error_file_id": "file-HOWS94", - "created_at": 1711471533, - "in_progress_at": 1711471538, - "expires_at": 1711557933, - "finalizing_at": 1711493133, - "completed_at": 1711493163, - "failed_at": null, - "expired_at": null, - "cancelling_at": null, - "cancelled_at": null, - "request_counts": { - "total": 100, - "completed": 95, - "failed": 5 - }, - "metadata": { - "customer_id": "user_123456789", - "batch_description": "Nightly eval job", - } - } - BatchRequestInput: + - role + ChatCompletionRequestAssistantMessageContentPart: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartRefusal" + x-oaiExpandable: true + ChatCompletionRequestDeveloperMessage: type: object - description: The per-line object of the batch input file + title: Developer message + description: > + Developer-provided instructions that the model should follow, regardless + of + + messages sent by the user. With o1 models and newer, `developer` + messages + + replace the previous `system` messages. properties: - custom_id: + content: + description: The contents of the developer message. + oneOf: + - type: string + description: The contents of the developer message. + title: Text content + - type: array + description: An array of content parts with a defined type. For developer + messages, only type `text` is supported. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + minItems: 1 + role: type: string - description: A developer-provided per-request id that will be used to match - outputs to inputs. Must be unique for each request in a batch. - method: + enum: + - developer + description: The role of the messages author, in this case `developer`. + x-stainless-const: true + name: + type: string + description: An optional name for the participant. Provides the model + information to differentiate between participants of the same role. + required: + - content + - role + ChatCompletionRequestFunctionMessage: + type: object + title: Function message + deprecated: true + properties: + role: type: string enum: - - POST - description: The HTTP method to be used for the request. Currently only `POST` - is supported. + - function + description: The role of the messages author, in this case `function`. x-stainless-const: true - url: + content: + nullable: true type: string - description: The OpenAI API relative URL to be used for the request. Currently - `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are - supported. - x-oaiMeta: - name: The request input object - example: > - {"custom_id": "request-1", "method": "POST", "url": - "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": - [{"role": "system", "content": "You are a helpful assistant."}, - {"role": "user", "content": "What is 2+2?"}]}} - BatchRequestOutput: + description: The contents of the function message. + name: + type: string + description: The name of the function to call. + required: + - role + - content + - name + ChatCompletionRequestMessage: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestDeveloperMessage" + - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" + - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" + - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" + - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" + - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" + x-oaiExpandable: true + ChatCompletionRequestMessageContentPartAudio: type: object - description: The per-line object of the batch output and error files + title: Audio content part + description: | + Learn about [audio inputs](/docs/guides/audio). properties: - id: + type: type: string - custom_id: + enum: + - input_audio + description: The type of the content part. Always `input_audio`. + x-stainless-const: true + input_audio: + type: object + properties: + data: + type: string + description: Base64 encoded audio data. + format: + type: string + enum: + - wav + - mp3 + description: > + The format of the encoded audio data. Currently supports "wav" + and "mp3". + required: + - data + - format + required: + - type + - input_audio + ChatCompletionRequestMessageContentPartFile: + type: object + title: File content part + description: | + Learn about [file inputs](/docs/guides/text) for text generation. + properties: + type: type: string - description: A developer-provided per-request id that will be used to match - outputs to inputs. - response: + enum: + - file + description: The type of the content part. Always `file`. + x-stainless-const: true + file: type: object - nullable: true properties: - status_code: - type: integer - description: The HTTP status code of the response - request_id: + file_name: type: string - description: An unique identifier for the OpenAI API request. Please include - this request ID when contacting support. - body: - type: object - x-oaiTypeLabel: map - description: The JSON body of the response - error: + description: > + The name of the file, used when passing the file to the model as + a + + string. + file_data: + type: string + description: > + The base64 encoded file data, used when passing the file to the + model + + as a string. + file_id: + type: string + description: | + The ID of an uploaded file to use as input. + required: + - type + - file + ChatCompletionRequestMessageContentPartImage: + type: object + title: Image content part + description: | + Learn about [image inputs](/docs/guides/vision). + properties: + type: + type: string + enum: + - image_url + description: The type of the content part. + x-stainless-const: true + image_url: type: object - nullable: true - description: For requests that failed with a non-HTTP error, this will contain - more information on the cause of the failure. properties: - code: + url: type: string - description: A machine-readable error code. - message: + description: Either a URL of the image or the base64 encoded image data. + format: uri + detail: type: string - description: A human-readable error message. - x-oaiMeta: - name: The request output object - example: > - {"id": "batch_req_wnaDys", "custom_id": "request-2", "response": - {"status_code": 200, "request_id": "req_c187b3", "body": {"id": - "chatcmpl-9758Iw", "object": "chat.completion", "created": 1711475054, - "model": "gpt-4o-mini", "choices": [{"index": 0, "message": {"role": - "assistant", "content": "2 + 2 equals 4."}, "finish_reason": "stop"}], - "usage": {"prompt_tokens": 24, "completion_tokens": 15, - "total_tokens": 39}, "system_fingerprint": null}}, "error": null} - CancelUploadRequest: + description: Specifies the detail level of the image. Learn more in the [Vision + guide](/docs/guides/vision#low-or-high-fidelity-image-understanding). + enum: + - auto + - low + - high + default: auto + required: + - url + required: + - type + - image_url + ChatCompletionRequestMessageContentPartRefusal: type: object - additionalProperties: false - ChatCompletionFunctionCallOption: + title: Refusal content part + properties: + type: + type: string + enum: + - refusal + description: The type of the content part. + x-stainless-const: true + refusal: + type: string + description: The refusal message generated by the model. + required: + - type + - refusal + ChatCompletionRequestMessageContentPartText: + type: object + title: Text content part + description: | + Learn about [text inputs](/docs/guides/text-generation). + properties: + type: + type: string + enum: + - text + description: The type of the content part. + x-stainless-const: true + text: + type: string + description: The text content. + required: + - type + - text + ChatCompletionRequestSystemMessage: type: object + title: System message description: > - Specifying a particular function via `{"name": "my_function"}` forces - the model to call that function. + Developer-provided instructions that the model should follow, regardless + of + + messages sent by the user. With o1 models and newer, use `developer` + messages + + for this purpose instead. properties: + content: + description: The contents of the system message. + oneOf: + - type: string + description: The contents of the system message. + title: Text content + - type: array + description: An array of content parts with a defined type. For system messages, + only type `text` is supported. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestSystemMessageContentPart" + minItems: 1 + role: + type: string + enum: + - system + description: The role of the messages author, in this case `system`. + x-stainless-const: true name: type: string - description: The name of the function to call. + description: An optional name for the participant. Provides the model + information to differentiate between participants of the same role. required: - - name - ChatCompletionFunctions: + - content + - role + ChatCompletionRequestSystemMessageContentPart: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + x-oaiExpandable: true + ChatCompletionRequestToolMessage: + type: object + title: Tool message + properties: + role: + type: string + enum: + - tool + description: The role of the messages author, in this case `tool`. + x-stainless-const: true + content: + oneOf: + - type: string + description: The contents of the tool message. + title: Text content + - type: array + description: An array of content parts with a defined type. For tool messages, + only type `text` is supported. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestToolMessageContentPart" + minItems: 1 + description: The contents of the tool message. + tool_call_id: + type: string + description: Tool call that this message is responding to. + required: + - role + - content + - tool_call_id + ChatCompletionRequestToolMessageContentPart: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + x-oaiExpandable: true + ChatCompletionRequestUserMessage: type: object - deprecated: true + title: User message + description: | + Messages sent by an end user, containing prompts or additional context + information. properties: - description: + content: + description: | + The contents of the user message. + oneOf: + - type: string + description: The text contents of the message. + title: Text content + - type: array + description: An array of content parts with a defined type. Supported options + differ based on the [model](/docs/models) being used to generate + the response. Can contain text, image, or audio inputs. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestUserMessageContentPart" + minItems: 1 + x-oaiExpandable: true + role: type: string - description: A description of what the function does, used by the model to - choose when and how to call the function. + enum: + - user + description: The role of the messages author, in this case `user`. + x-stainless-const: true name: type: string - description: The name of the function to be called. Must be a-z, A-Z, 0-9, or - contain underscores and dashes, with a maximum length of 64. - parameters: - $ref: "#/components/schemas/FunctionParameters" + description: An optional name for the participant. Provides the model + information to differentiate between participants of the same role. required: - - name - ChatCompletionMessageToolCall: + - content + - role + ChatCompletionRequestUserMessageContentPart: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartImage" + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartAudio" + - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartFile" + x-oaiExpandable: true + ChatCompletionResponseMessage: type: object + description: A chat completion message generated by the model. properties: - id: + content: type: string - description: The ID of the tool call. - type: + description: The contents of the message. + nullable: true + refusal: + type: string + description: The refusal message generated by the model. + nullable: true + tool_calls: + $ref: "#/components/schemas/ChatCompletionMessageToolCalls" + annotations: + type: array + description: | + Annotations for the message, when applicable, as when using the + [web search tool](/docs/guides/tools-web-search?api-mode=chat). + items: + type: object + description: | + A URL citation when using web search. + required: + - type + - url_citation + properties: + type: + type: string + description: The type of the URL citation. Always `url_citation`. + enum: + - url_citation + x-stainless-const: true + url_citation: + type: object + description: A URL citation when using web search. + required: + - end_index + - start_index + - url + - title + properties: + end_index: + type: integer + description: The index of the last character of the URL citation in the message. + start_index: + type: integer + description: The index of the first character of the URL citation in the + message. + url: + type: string + description: The URL of the web resource. + title: + type: string + description: The title of the web resource. + role: type: string enum: - - function - description: The type of the tool. Currently, only `function` is supported. + - assistant + description: The role of the author of this message. x-stainless-const: true - function: + function_call: type: object - description: The function that the model called. + deprecated: true + description: Deprecated and replaced by `tool_calls`. The name and arguments of + a function that should be called, as generated by the model. properties: - name: - type: string - description: The name of the function to call. arguments: type: string description: The arguments to call the function with, as generated by the model @@ -12682,154 +15766,90 @@ components: valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. + name: + type: string + description: The name of the function to call. required: - name - arguments - required: - - id - - type - - function - ChatCompletionMessageToolCallChunk: - type: object - properties: - index: - type: integer - id: - type: string - description: The ID of the tool call. - type: - type: string - enum: - - function - description: The type of the tool. Currently, only `function` is supported. - x-stainless-const: true - function: + audio: type: object + nullable: true + description: > + If the audio output modality is requested, this object contains data + + about the audio response from the model. [Learn + more](/docs/guides/audio). + x-oaiExpandable: true + required: + - id + - expires_at + - data + - transcript properties: - name: - type: string - description: The name of the function to call. - arguments: + id: type: string - description: The arguments to call the function with, as generated by the model - in JSON format. Note that the model does not always generate - valid JSON, and may hallucinate parameters not defined by your - function schema. Validate the arguments in your code before - calling your function. - required: - - index - ChatCompletionMessageToolCalls: - type: array - description: The tool calls generated by the model, such as function calls. - items: - $ref: "#/components/schemas/ChatCompletionMessageToolCall" - ChatCompletionModalities: - type: array - nullable: true - description: > - Output types that you would like the model to generate for this request. - - Most models are capable of generating text, which is the default: - - - `["text"]` - - - The `gpt-4o-audio-preview` model can also be used to [generate - audio](/docs/guides/audio). To - - request that this model generate both text and audio responses, you can - - use: + description: Unique identifier for this audio response. + expires_at: + type: integer + description: > + The Unix timestamp (in seconds) for when this audio response + will + no longer be accessible on the server for use in multi-turn - `["text", "audio"]` - items: - type: string - enum: - - text - - audio - ChatCompletionNamedToolChoice: - type: object - description: Specifies a tool the model should use. Use to force the model to - call a specific function. - properties: - type: - type: string - enum: - - function - description: The type of the tool. Currently, only `function` is supported. - x-stainless-const: true - function: - type: object - properties: - name: + conversations. + data: type: string - description: The name of the function to call. - required: - - name + description: | + Base64 encoded audio bytes generated by the model, in the format + specified in the request. + transcript: + type: string + description: Transcript of the audio generated by the model. required: - - type + - role + - content + - refusal + ChatCompletionRole: + type: string + description: The role of the author of a message + enum: + - developer + - system + - user + - assistant + - tool - function - ChatCompletionRequestAssistantMessage: - type: object - title: Assistant message - description: | - Messages sent by the model in response to user messages. - properties: - content: - x-oaiExpandable: true - nullable: true - oneOf: - - type: string - description: The contents of the assistant message. - title: Text content - - type: array - description: An array of content parts with a defined type. Can be one or more - of type `text`, or exactly one of type `refusal`. - title: Array of content parts - items: - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessageContentPart" - minItems: 1 - description: > - The contents of the assistant message. Required unless `tool_calls` - or `function_call` is specified. - refusal: - nullable: true - type: string - description: The refusal message by the assistant. - role: - type: string - enum: - - assistant - description: The role of the messages author, in this case `assistant`. - x-stainless-const: true - name: + ChatCompletionStreamOptions: + description: > + Options for streaming response. Only set this when you set `stream: + true`. + type: object + nullable: true + default: null + properties: + include_usage: + type: boolean + description: > + If set, an additional chunk will be streamed before the `data: + [DONE]` message. The `usage` field on this chunk shows the token + usage statistics for the entire request, and the `choices` field + will always be an empty array. All other chunks will also include a + `usage` field, but with a null value. + ChatCompletionStreamResponseDelta: + type: object + description: A chat completion delta generated by streamed model responses. + properties: + content: type: string - description: An optional name for the participant. Provides the model - information to differentiate between participants of the same role. - audio: - type: object + description: The contents of the chunk message. nullable: true - x-oaiExpandable: true - description: | - Data about a previous audio response from the model. - [Learn more](/docs/guides/audio). - required: - - id - properties: - id: - type: string - description: | - Unique identifier for a previous audio response from the model. - tool_calls: - $ref: "#/components/schemas/ChatCompletionMessageToolCalls" function_call: - type: object deprecated: true + type: object description: Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model. - nullable: true properties: arguments: type: string @@ -12841,622 +15861,658 @@ components: name: type: string description: The name of the function to call. - required: - - arguments - - name - required: - - role - ChatCompletionRequestAssistantMessageContentPart: - oneOf: - - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" - - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartRefusal" - x-oaiExpandable: true - ChatCompletionRequestDeveloperMessage: - type: object - title: Developer message - description: > - Developer-provided instructions that the model should follow, regardless - of - - messages sent by the user. With o1 models and newer, `developer` - messages - - replace the previous `system` messages. - properties: - content: - description: The contents of the developer message. - oneOf: - - type: string - description: The contents of the developer message. - title: Text content - - type: array - description: An array of content parts with a defined type. For developer - messages, only type `text` is supported. - title: Array of content parts - items: - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" - minItems: 1 + tool_calls: + type: array + items: + $ref: "#/components/schemas/ChatCompletionMessageToolCallChunk" role: type: string enum: - developer - description: The role of the messages author, in this case `developer`. - x-stainless-const: true - name: + - system + - user + - assistant + - tool + description: The role of the author of this message. + refusal: type: string - description: An optional name for the participant. Provides the model - information to differentiate between participants of the same role. + description: The refusal message generated by the model. + nullable: true + ChatCompletionTokenLogprob: + type: object + properties: + token: &a1 + description: The token. + type: string + logprob: &a2 + description: The log probability of this token, if it is within the top 20 most + likely tokens. Otherwise, the value `-9999.0` is used to signify + that the token is very unlikely. + type: number + bytes: &a3 + description: A list of integers representing the UTF-8 bytes representation of + the token. Useful in instances where characters are represented by + multiple tokens and their byte representations must be combined to + generate the correct text representation. Can be `null` if there is + no bytes representation for the token. + type: array + items: + type: integer + nullable: true + top_logprobs: + description: List of the most likely tokens and their log probability, at this + token position. In rare cases, there may be fewer than the number of + requested `top_logprobs` returned. + type: array + items: + type: object + properties: + token: *a1 + logprob: *a2 + bytes: *a3 + required: + - token + - logprob + - bytes required: - - content - - role - ChatCompletionRequestFunctionMessage: + - token + - logprob + - bytes + - top_logprobs + ChatCompletionTool: type: object - title: Function message - deprecated: true properties: - role: + type: type: string enum: - function - description: The role of the messages author, in this case `function`. + description: The type of the tool. Currently, only `function` is supported. x-stainless-const: true - content: - nullable: true - type: string - description: The contents of the function message. - name: - type: string - description: The name of the function to call. + function: + $ref: "#/components/schemas/FunctionObject" required: - - role - - content - - name - ChatCompletionRequestMessage: + - type + - function + ChatCompletionToolChoiceOption: + 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. + + Specifying a particular tool via `{"type": "function", "function": + {"name": "my_function"}}` forces the model to call that tool. + + + `none` is the default when no tools are present. `auto` is the default + if tools are present. oneOf: - - $ref: "#/components/schemas/ChatCompletionRequestDeveloperMessage" - - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" - - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" - - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" - - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" - - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" + - type: string + description: > + `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 + - $ref: "#/components/schemas/ChatCompletionNamedToolChoice" x-oaiExpandable: true - ChatCompletionRequestMessageContentPartAudio: + ChunkingStrategyRequestParam: type: object - title: Audio content part + description: The chunking strategy used to chunk the file(s). If not set, will + use the `auto` strategy. + oneOf: + - $ref: "#/components/schemas/AutoChunkingStrategyRequestParam" + - $ref: "#/components/schemas/StaticChunkingStrategyRequestParam" + x-oaiExpandable: true + Click: + type: object + title: Click description: | - Learn about [audio inputs](/docs/guides/audio). + A click action. properties: type: type: string enum: - - input_audio - description: The type of the content part. Always `input_audio`. + - click + default: click + description: | + Specifies the event type. For a click action, this property is + always set to `click`. x-stainless-const: true - input_audio: - type: object - properties: - data: - type: string - description: Base64 encoded audio data. - format: - type: string - enum: - - wav - - mp3 - description: > - The format of the encoded audio data. Currently supports "wav" - and "mp3". - required: - - data - - format + button: + type: string + enum: + - left + - right + - wheel + - back + - forward + 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. required: - type - - input_audio - ChatCompletionRequestMessageContentPartImage: + - button + - x + - y + CodeInterpreterFileOutput: type: object - title: Image content part + title: Code interpreter file output description: | - Learn about [image inputs](/docs/guides/vision). + The output of a code interpreter tool call that is a file. properties: type: type: string enum: - - image_url - description: The type of the content part. - x-stainless-const: true - image_url: - type: object - properties: - url: - type: string - description: Either a URL of the image or the base64 encoded image data. - format: uri - detail: - type: string - description: Specifies the detail level of the image. Learn more in the [Vision - guide](/docs/guides/vision#low-or-high-fidelity-image-understanding). - enum: - - auto - - low - - high - default: auto - required: - - url + - files + description: | + The type of the code interpreter file output. Always `files`. + x-stainless-const: true + files: + type: array + items: + type: object + properties: + mime_type: + type: string + description: | + The MIME type of the file. + file_id: + type: string + description: | + The ID of the file. + required: + - mime_type + - file_id required: - type - - image_url - ChatCompletionRequestMessageContentPartRefusal: + - files + CodeInterpreterTextOutput: type: object - title: Refusal content part + title: Code interpreter text output + description: | + The output of a code interpreter tool call that is text. properties: type: type: string enum: - - refusal - description: The type of the content part. + - logs + description: | + The type of the code interpreter text output. Always `logs`. x-stainless-const: true - refusal: + logs: type: string - description: The refusal message generated by the model. + description: | + The logs of the code interpreter tool call. required: - type - - refusal - ChatCompletionRequestMessageContentPartText: + - logs + CodeInterpreterTool: type: object - title: Text content part + title: Code interpreter description: | - Learn about [text inputs](/docs/guides/text-generation). + A tool that runs code. properties: type: type: string enum: - - text - description: The type of the content part. + - code_interpreter + description: | + The type of the code interpreter tool. Always `code_interpreter`. x-stainless-const: true - text: - type: string - description: The text content. + file_ids: + type: array + items: + type: string + description: | + The IDs of the files to run the code on. required: - type - - text - ChatCompletionRequestSystemMessage: + - file_ids + CodeInterpreterToolCall: type: object - title: System message - description: > - Developer-provided instructions that the model should follow, regardless - of - - messages sent by the user. With o1 models and newer, use `developer` - messages - - for this purpose instead. + title: Code interpreter tool call + description: | + A tool call to run code. properties: - content: - description: The contents of the system message. - oneOf: - - type: string - description: The contents of the system message. - title: Text content - - type: array - description: An array of content parts with a defined type. For system messages, - only type `text` is supported. - title: Array of content parts - items: - $ref: "#/components/schemas/ChatCompletionRequestSystemMessageContentPart" - minItems: 1 - role: + id: + type: string + description: | + The unique ID of the code interpreter tool call. + type: type: string enum: - - system - description: The role of the messages author, in this case `system`. + - code_interpreter_call + description: > + The type of the code interpreter tool call. Always + `code_interpreter_call`. x-stainless-const: true - name: + code: type: string - description: An optional name for the participant. Provides the model - information to differentiate between participants of the same role. + description: | + The code to run. + status: + type: string + enum: + - in_progress + - interpreting + - completed + description: | + The status of the code interpreter tool call. + results: + type: array + items: + x-oaiExpandable: true + $ref: "#/components/schemas/CodeInterpreterToolOutput" + description: | + The results of the code interpreter tool call. required: - - content - - role - ChatCompletionRequestSystemMessageContentPart: + - id + - type + - code + - status + - results + CodeInterpreterToolOutput: oneOf: - - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" - x-oaiExpandable: true - ChatCompletionRequestToolMessage: + - $ref: "#/components/schemas/CodeInterpreterTextOutput" + - $ref: "#/components/schemas/CodeInterpreterFileOutput" + ComparisonFilter: type: object - title: Tool message + 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: - role: + type: type: string + default: eq enum: - - tool - description: The role of the messages author, in this case `tool`. - x-stainless-const: true - content: + - eq + - ne + - gt + - gte + - lt + - lte + description: > + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, + `lte`. + + - `eq`: equals + + - `ne`: not equal + + - `gt`: greater than + + - `gte`: greater than or equal + + - `lt`: less than + + - `lte`: less than or equal + key: + type: string + description: The key to compare against the value. + value: oneOf: - type: string - description: The contents of the tool message. - title: Text content - - type: array - description: An array of content parts with a defined type. For tool messages, - only type `text` is supported. - title: Array of content parts - items: - $ref: "#/components/schemas/ChatCompletionRequestToolMessageContentPart" - minItems: 1 - description: The contents of the tool message. - tool_call_id: - type: string - description: Tool call that this message is responding to. + - type: number + - type: boolean + description: The value to compare against the attribute key; supports string, + number, or boolean types. required: - - role - - content - - tool_call_id - ChatCompletionRequestToolMessageContentPart: - oneOf: - - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" - x-oaiExpandable: true - ChatCompletionRequestUserMessage: + - type + - key + - value + x-oaiMeta: + name: ComparisonFilter + CompleteUploadRequest: type: object - title: User message - description: | - Messages sent by an end user, containing prompts or additional context - information. + additionalProperties: false properties: - content: + part_ids: + type: array description: | - The contents of the user message. - oneOf: - - type: string - description: The text contents of the message. - title: Text content - - type: array - description: An array of content parts with a defined type. Supported options - differ based on the [model](/docs/models) being used to generate - the response. Can contain text, image, or audio inputs. - title: Array of content parts - items: - $ref: "#/components/schemas/ChatCompletionRequestUserMessageContentPart" - minItems: 1 - x-oaiExpandable: true - role: - type: string - enum: - - user - description: The role of the messages author, in this case `user`. - x-stainless-const: true - name: + The ordered list of Part IDs. + items: + type: string + md5: + description: > + The optional md5 checksum for the file contents to verify if the + bytes uploaded matches what you expect. type: string - description: An optional name for the participant. Provides the model - information to differentiate between participants of the same role. required: - - content - - role - ChatCompletionRequestUserMessageContentPart: - oneOf: - - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" - - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartImage" - - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartAudio" - x-oaiExpandable: true - ChatCompletionResponseMessage: + - part_ids + CompletionUsage: type: object - description: A chat completion message generated by the model. + description: Usage statistics for the completion request. properties: - content: - type: string - description: The contents of the message. - nullable: true - refusal: - type: string - description: The refusal message generated by the model. - nullable: true - tool_calls: - $ref: "#/components/schemas/ChatCompletionMessageToolCalls" - role: - type: string - enum: - - assistant - description: The role of the author of this message. - x-stainless-const: true - function_call: - type: object - deprecated: true - description: Deprecated and replaced by `tool_calls`. The name and arguments of - a function that should be called, as generated by the model. - properties: - arguments: - type: string - description: The arguments to call the function with, as generated by the model - in JSON format. Note that the model does not always generate - valid JSON, and may hallucinate parameters not defined by your - function schema. Validate the arguments in your code before - calling your function. - name: - type: string - description: The name of the function to call. - required: - - name - - arguments - audio: - type: object - nullable: true - description: > - If the audio output modality is requested, this object contains data - - about the audio response from the model. [Learn - more](/docs/guides/audio). - x-oaiExpandable: true - required: - - id - - expires_at - - data - - transcript + completion_tokens: + type: integer + default: 0 + description: Number of tokens in the generated completion. + prompt_tokens: + type: integer + default: 0 + description: Number of tokens in the prompt. + total_tokens: + type: integer + default: 0 + description: Total number of tokens used in the request (prompt + completion). + completion_tokens_details: + type: object + description: Breakdown of tokens used in a completion. properties: - id: - type: string - description: Unique identifier for this audio response. - expires_at: + accepted_prediction_tokens: + type: integer + default: 0 + description: | + When using Predicted Outputs, the number of tokens in the + prediction that appeared in the completion. + audio_tokens: type: integer + default: 0 + description: Audio input tokens generated by the model. + reasoning_tokens: + type: integer + default: 0 + description: Tokens generated by the model for reasoning. + rejected_prediction_tokens: + type: integer + default: 0 description: > - The Unix timestamp (in seconds) for when this audio response - will + When using Predicted Outputs, the number of tokens in the - no longer be accessible on the server for use in multi-turn + prediction that did not appear in the completion. However, like - conversations. - data: - type: string - description: | - Base64 encoded audio bytes generated by the model, in the format - specified in the request. - transcript: - type: string - description: Transcript of the audio generated by the model. + reasoning tokens, these tokens are still counted in the total + + completion tokens for purposes of billing, output, and context + window + + limits. + prompt_tokens_details: + type: object + description: Breakdown of tokens used in the prompt. + properties: + audio_tokens: + type: integer + default: 0 + description: Audio input tokens present in the prompt. + cached_tokens: + type: integer + default: 0 + description: Cached tokens present in the prompt. required: - - role - - content - - refusal - ChatCompletionRole: - type: string - description: The role of the author of a message - enum: - - developer - - system - - user - - assistant - - tool - - function - ChatCompletionStreamOptions: - description: > - Options for streaming response. Only set this when you set `stream: - true`. - type: object - nullable: true - default: null - properties: - include_usage: - type: boolean - description: > - If set, an additional chunk will be streamed before the `data: - [DONE]` message. The `usage` field on this chunk shows the token - usage statistics for the entire request, and the `choices` field - will always be an empty array. All other chunks will also include a - `usage` field, but with a null value. - ChatCompletionStreamResponseDelta: + - prompt_tokens + - completion_tokens + - total_tokens + CompoundFilter: + $recursiveAnchor: true type: object - description: A chat completion delta generated by streamed model responses. + additionalProperties: false + title: Compound Filter + description: Combine multiple filters using `and` or `or`. properties: - content: + type: type: string - description: The contents of the chunk message. - nullable: true - function_call: - deprecated: true - type: object - description: Deprecated and replaced by `tool_calls`. The name and arguments of - a function that should be called, as generated by the model. - properties: - arguments: - type: string - description: The arguments to call the function with, as generated by the model - in JSON format. Note that the model does not always generate - valid JSON, and may hallucinate parameters not defined by your - function schema. Validate the arguments in your code before - calling your function. - name: - type: string - description: The name of the function to call. - tool_calls: + 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: - $ref: "#/components/schemas/ChatCompletionMessageToolCallChunk" - role: + oneOf: + - $ref: "#/components/schemas/ComparisonFilter" + - $recursiveRef: "#" + required: + - type + - filters + x-oaiMeta: + name: CompoundFilter + ComputerAction: + oneOf: + - $ref: "#/components/schemas/Click" + - $ref: "#/components/schemas/DoubleClick" + - $ref: "#/components/schemas/Drag" + - $ref: "#/components/schemas/KeyPress" + - $ref: "#/components/schemas/Move" + - $ref: "#/components/schemas/Screenshot" + - $ref: "#/components/schemas/Scroll" + - $ref: "#/components/schemas/Type" + - $ref: "#/components/schemas/Wait" + ComputerScreenshotImage: + type: object + description: | + A computer screenshot image used with the computer use tool. + properties: + type: type: string enum: - - developer - - system - - user - - assistant - - tool - description: The role of the author of this message. - refusal: + - computer_screenshot + default: computer_screenshot + description: > + Specifies the event type. For a computer screenshot, this property + is + + always set to `computer_screenshot`. + x-stainless-const: true + image_url: type: string - description: The refusal message generated by the model. - nullable: true - ChatCompletionTokenLogprob: - type: object - properties: - token: &a1 - description: The token. + description: The URL of the screenshot image. + file_id: type: string - logprob: &a2 - description: The log probability of this token, if it is within the top 20 most - likely tokens. Otherwise, the value `-9999.0` is used to signify - that the token is very unlikely. - type: number - bytes: &a3 - description: A list of integers representing the UTF-8 bytes representation of - the token. Useful in instances where characters are represented by - multiple tokens and their byte representations must be combined to - generate the correct text representation. Can be `null` if there is - no bytes representation for the token. - type: array - items: - type: integer - nullable: true - top_logprobs: - description: List of the most likely tokens and their log probability, at this - token position. In rare cases, there may be fewer than the number of - requested `top_logprobs` returned. - type: array - items: - type: object - properties: - token: *a1 - logprob: *a2 - bytes: *a3 - required: - - token - - logprob - - bytes + description: The identifier of an uploaded file that contains the screenshot. required: - - token - - logprob - - bytes - - top_logprobs - ChatCompletionTool: + - type + ComputerTool: type: object + title: Computer use + description: | + A tool that controls a virtual computer. Learn more about the + [computer tool](/docs/guides/tools-computer-use). properties: type: type: string enum: - - function - description: The type of the tool. Currently, only `function` is supported. + - computer-preview + description: | + The type of the computer use tool. Always `computer_use_preview`. x-stainless-const: true - function: - $ref: "#/components/schemas/FunctionObject" + display_width: + type: number + description: | + The width of the computer display. + display_height: + type: number + description: | + The height of the computer display. + environment: + type: string + description: | + The type of computer environment to control. + enum: + - mac + - windows + - ubuntu + - browser required: - type - - function - ChatCompletionToolChoiceOption: + - display_width + - display_height + - environment + ComputerToolCall: + type: object + title: Computer tool call 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. - - Specifying a particular tool via `{"type": "function", "function": - {"name": "my_function"}}` forces the model to call that tool. + A tool call to a computer use tool. See the - - `none` is the default when no tools are present. `auto` is the default - if tools are present. - oneOf: - - type: string - description: > - `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. + [computer use guide](/docs/guides/tools-computer-use) for more + information. + properties: + type: + type: string + description: The type of the computer call. Always `computer_call`. enum: - - none - - auto - - required - - $ref: "#/components/schemas/ChatCompletionNamedToolChoice" - x-oaiExpandable: true - ChunkingStrategyRequestParam: - type: object - description: The chunking strategy used to chunk the file(s). If not set, will - use the `auto` strategy. - oneOf: - - $ref: "#/components/schemas/AutoChunkingStrategyRequestParam" - - $ref: "#/components/schemas/StaticChunkingStrategyRequestParam" - x-oaiExpandable: true - CompleteUploadRequest: + - 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/ComputerAction" + x-oaiExpandable: true + pending_safety_checks: + type: array + x-oaiExpandable: true + items: + $ref: "#/components/schemas/ComputerToolCallSafetyCheck" + 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 + - action + - call_id + - pending_safety_checks + - status + ComputerToolCallOutput: type: object - additionalProperties: false + title: Computer tool call output + description: | + The output of a computer tool call. properties: - part_ids: - type: array + 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 ordered list of Part IDs. + 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 + x-oaiExpandable: true + description: > + The safety checks reported by the API that have been acknowledged by + the + + developer. items: - type: string - md5: + $ref: "#/components/schemas/ComputerToolCallSafetyCheck" + output: + $ref: "#/components/schemas/ComputerScreenshotImage" + status: + type: string description: > - The optional md5 checksum for the file contents to verify if the - bytes uploaded matches what you expect. + 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 + ComputerToolCallOutputResource: + allOf: + - $ref: "#/components/schemas/ComputerToolCallOutput" + - type: object + properties: + id: + type: string + description: | + The unique ID of the computer call tool output. + required: + - id + ComputerToolCallSafetyCheck: + type: object + description: | + A pending safety check for the computer call. + properties: + id: + type: string + description: The ID of the pending safety check. + code: + type: string + description: The type of the pending safety check. + message: type: string + description: Details about the pending safety check. required: - - part_ids - CompletionUsage: + - id + - code + - message + Content: + description: | + Multi-modal input and output contents. + oneOf: + - title: Input content types + x-oaiExpandable: true + $ref: "#/components/schemas/InputContent" + - title: Output content types + x-oaiExpandable: true + $ref: "#/components/schemas/OutputContent" + Coordinate: type: object - description: Usage statistics for the completion request. + title: Coordinate + description: | + An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`. properties: - completion_tokens: - type: integer - default: 0 - description: Number of tokens in the generated completion. - prompt_tokens: + x: type: integer - default: 0 - description: Number of tokens in the prompt. - total_tokens: + description: | + The x-coordinate. + y: type: integer - default: 0 - description: Total number of tokens used in the request (prompt + completion). - completion_tokens_details: - type: object - description: Breakdown of tokens used in a completion. - properties: - accepted_prediction_tokens: - type: integer - default: 0 - description: | - When using Predicted Outputs, the number of tokens in the - prediction that appeared in the completion. - audio_tokens: - type: integer - default: 0 - description: Audio input tokens generated by the model. - reasoning_tokens: - type: integer - default: 0 - description: Tokens generated by the model for reasoning. - rejected_prediction_tokens: - type: integer - default: 0 - description: > - When using Predicted Outputs, the number of tokens in the - - prediction that did not appear in the completion. However, like - - reasoning tokens, these tokens are still counted in the total - - completion tokens for purposes of billing, output, and context - window - - limits. - prompt_tokens_details: - type: object - description: Breakdown of tokens used in the prompt. - properties: - audio_tokens: - type: integer - default: 0 - description: Audio input tokens present in the prompt. - cached_tokens: - type: integer - default: 0 - description: Cached tokens present in the prompt. + description: | + The y-coordinate. required: - - prompt_tokens - - completion_tokens - - total_tokens + - x + - y CostsResult: type: object description: The aggregated costs details of the specific time bucket. @@ -13698,9 +16754,8 @@ components: We generally recommend altering this or temperature but not both. response_format: - allOf: - - $ref: "#/components/schemas/AssistantsApiResponseFormatOption" - - nullable: true + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true required: - model CreateChatCompletionFunctionResponse: @@ -13816,7 +16871,8 @@ components: CreateChatCompletionImageResponse: type: object description: Represents a streamed chunk of a chat completion response returned - by model, based on the provided input. + by model, based on the provided input. [Learn + more](/docs/guides/streaming-responses). x-oaiMeta: name: The chat completion chunk object group: chat @@ -13848,470 +16904,402 @@ components: } } CreateChatCompletionRequest: - type: object - properties: - messages: - description: > - A list of messages comprising the conversation so far. Depending on - the - - [model](/docs/models) you use, different message types (modalities) - are - - supported, like [text](/docs/guides/text-generation), - - [images](/docs/guides/vision), and [audio](/docs/guides/audio). - type: array - minItems: 1 - items: - $ref: "#/components/schemas/ChatCompletionRequestMessage" - model: - description: ID of the model to use. See the [model endpoint - compatibility](/docs/models#model-endpoint-compatibility) table for - details on which models work with the Chat API. - example: gpt-4o - anyOf: - - type: string - - type: string - enum: - - o3-mini - - o3-mini-2025-01-31 - - o1 - - o1-2024-12-17 - - o1-preview - - o1-preview-2024-09-12 - - o1-mini - - o1-mini-2024-09-12 - - gpt-4o - - gpt-4o-2024-11-20 - - gpt-4o-2024-08-06 - - gpt-4o-2024-05-13 - - gpt-4o-audio-preview - - gpt-4o-audio-preview-2024-10-01 - - gpt-4o-audio-preview-2024-12-17 - - gpt-4o-mini-audio-preview - - gpt-4o-mini-audio-preview-2024-12-17 - - chatgpt-4o-latest - - gpt-4o-mini - - gpt-4o-mini-2024-07-18 - - gpt-4-turbo - - gpt-4-turbo-2024-04-09 - - gpt-4-0125-preview - - gpt-4-turbo-preview - - gpt-4-1106-preview - - gpt-4-vision-preview - - gpt-4 - - gpt-4-0314 - - gpt-4-0613 - - gpt-4-32k - - gpt-4-32k-0314 - - gpt-4-32k-0613 - - gpt-3.5-turbo - - gpt-3.5-turbo-16k - - gpt-3.5-turbo-0301 - - gpt-3.5-turbo-0613 - - gpt-3.5-turbo-1106 - - gpt-3.5-turbo-0125 - - gpt-3.5-turbo-16k-0613 - x-oaiTypeLabel: string - store: - type: boolean - default: false - nullable: true - description: > - Whether or not to store the output of this chat completion request - for - - use in our [model distillation](/docs/guides/distillation) or - - [evals](/docs/guides/evals) products. - reasoning_effort: - $ref: "#/components/schemas/ReasoningEffort" - metadata: - $ref: "#/components/schemas/Metadata" - frequency_penalty: - type: number - default: 0 - minimum: -2 - maximum: 2 - nullable: true - description: > - Number between -2.0 and 2.0. Positive values penalize new tokens - based on - - their existing frequency in the text so far, decreasing the model's - - likelihood to repeat the same line verbatim. - logit_bias: - type: object - x-oaiTypeLabel: map - default: null - nullable: true - additionalProperties: - type: integer - description: > - Modify the likelihood of specified tokens appearing in the - completion. - - - Accepts a JSON object that maps tokens (specified by their token ID - in the - - tokenizer) to an associated bias value from -100 to 100. - Mathematically, + allOf: + - $ref: "#/components/schemas/CreateModelResponseProperties" + - type: object + properties: + messages: + description: > + A list of messages comprising the conversation so far. Depending + on the - the bias is added to the logits generated by the model prior to - sampling. + [model](/docs/models) you use, different message types + (modalities) are - The exact effect will vary per model, but values between -1 and 1 - should + supported, like [text](/docs/guides/text-generation), - decrease or increase likelihood of selection; values like -100 or - 100 + [images](/docs/guides/vision), and [audio](/docs/guides/audio). + type: array + minItems: 1 + items: + $ref: "#/components/schemas/ChatCompletionRequestMessage" + modalities: + $ref: "#/components/schemas/ResponseModalities" + reasoning_effort: + $ref: "#/components/schemas/ReasoningEffort" + max_completion_tokens: + description: > + An upper bound for the number of tokens that can be generated + for a completion, including visible output tokens and [reasoning + tokens](/docs/guides/reasoning). + type: integer + nullable: true + frequency_penalty: + type: number + default: 0 + minimum: -2 + maximum: 2 + nullable: true + description: > + Number between -2.0 and 2.0. Positive values penalize new tokens + based on - should result in a ban or exclusive selection of the relevant token. - logprobs: - description: > - Whether to return log probabilities of the output tokens or not. If - true, + their existing frequency in the text so far, decreasing the + model's - returns the log probabilities of each output token returned in the + likelihood to repeat the same line verbatim. + presence_penalty: + type: number + default: 0 + minimum: -2 + maximum: 2 + nullable: true + description: > + Number between -2.0 and 2.0. Positive values penalize new tokens + based on - `content` of `message`. - type: boolean - default: false - nullable: true - top_logprobs: - description: > - An integer between 0 and 20 specifying the number of most likely - tokens to + whether they appear in the text so far, increasing the model's + likelihood - return at each token position, each with an associated log - probability. + to talk about new topics. + web_search_options: + type: object + title: Web search + description: > + This tool searches the web for relevant results to use in a + response. - `logprobs` must be set to `true` if this parameter is used. - type: integer - minimum: 0 - maximum: 20 - nullable: true - max_tokens: - description: > - The maximum number of [tokens](/tokenizer) that can be generated in - the + Learn more about the [web search + tool](/docs/guides/tools-web-search?api-mode=chat). + properties: + user_location: + type: object + nullable: true + required: + - type + - approximate + description: | + Approximate location parameters for the search. + properties: + type: + type: string + description: > + The type of location approximation. Always `approximate`. + enum: + - approximate + x-stainless-const: true + approximate: + $ref: "#/components/schemas/WebSearchLocation" + search_context_size: + $ref: "#/components/schemas/WebSearchContextSize" + top_logprobs: + description: > + An integer between 0 and 20 specifying the number of most likely + tokens to - chat completion. This value can be used to control + return at each token position, each with an associated log + probability. - [costs](https://openai.com/api/pricing/) for text generated via API. + `logprobs` must be set to `true` if this parameter is used. + type: integer + minimum: 0 + maximum: 20 + nullable: true + response_format: + description: > + An object specifying the format that the model must output. - This value is now deprecated in favor of `max_completion_tokens`, - and is + Setting to `{ "type": "json_schema", "json_schema": {...} }` + enables - not compatible with [o1 series models](/docs/guides/reasoning). - type: integer - nullable: true - deprecated: true - max_completion_tokens: - description: > - An upper bound for the number of tokens that can be generated for a - completion, including visible output tokens and [reasoning - tokens](/docs/guides/reasoning). - type: integer - nullable: true - n: - type: integer - minimum: 1 - maximum: 128 - default: 1 - example: 1 - nullable: true - description: How many chat completion choices to generate for each input - message. Note that you will be charged based on the number of - generated tokens across all of the choices. Keep `n` as `1` to - minimize costs. - modalities: - $ref: "#/components/schemas/ChatCompletionModalities" - prediction: - nullable: true - x-oaiExpandable: true - description: > - Configuration for a [Predicted - Output](/docs/guides/predicted-outputs), + Structured Outputs which ensures the model will match your + supplied JSON - which can greatly improve response times when large parts of the - model + schema. Learn more in the [Structured Outputs - response are known ahead of time. This is most common when you are + guide](/docs/guides/structured-outputs). - regenerating a file with only minor changes to most of the content. - oneOf: - - $ref: "#/components/schemas/PredictionContent" - audio: - type: object - nullable: true - description: > - Parameters for audio output. Required when audio output is requested - with - `modalities: ["audio"]`. [Learn more](/docs/guides/audio). - required: - - voice - - format - x-oaiExpandable: true - properties: - voice: - type: string - enum: - - alloy - - ash - - ballad - - coral - - echo - - sage - - shimmer - - verse + 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. + oneOf: + - $ref: "#/components/schemas/ResponseFormatText" + - $ref: "#/components/schemas/ResponseFormatJsonSchema" + - $ref: "#/components/schemas/ResponseFormatJsonObject" + x-oaiExpandable: true + service_tier: description: > - The voice the model uses to respond. Supported voices are `ash`, - `ballad`, `coral`, `sage`, and `verse` (also supported but not - recommended are `alloy`, `echo`, and `shimmer`; these voices are - less expressive). - format: + Specifies the latency tier to use for processing the request. + This parameter is relevant for customers subscribed to the scale + tier service: + - If set to 'auto', and the Project is Scale tier enabled, the system + will utilize scale tier credits until they are exhausted. + - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. + - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. + - When not set, the default behavior is 'auto'. + + When this parameter is set, the response body will include the `service_tier` utilized. type: string enum: - - wav - - mp3 - - flac - - opus - - pcm16 + - auto + - default + nullable: true + default: auto + audio: + type: object + nullable: true description: > - Specifies the output audio format. Must be one of `wav`, `mp3`, - `flac`, - - `opus`, or `pcm16`. - presence_penalty: - type: number - default: 0 - minimum: -2 - maximum: 2 - nullable: true - description: > - Number between -2.0 and 2.0. Positive values penalize new tokens - based on + Parameters for audio output. Required when audio output is + requested with - whether they appear in the text so far, increasing the model's - likelihood + `modalities: ["audio"]`. [Learn more](/docs/guides/audio). + required: + - voice + - format + x-oaiExpandable: true + properties: + voice: + type: string + enum: + - alloy + - ash + - ballad + - coral + - echo + - sage + - shimmer + - verse + description: > + The voice the model uses to respond. Supported voices are - to talk about new topics. - response_format: - description: > - An object specifying the format that the model must output. + `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, and + `shimmer`. + format: + type: string + enum: + - wav + - mp3 + - flac + - opus + - pcm16 + description: > + Specifies the output audio format. Must be one of `wav`, + `mp3`, `flac`, + `opus`, or `pcm16`. + store: + type: boolean + default: false + nullable: true + description: > + Whether or not to store the output of this chat completion + request for - Setting to `{ "type": "json_schema", "json_schema": {...} }` enables + use in our [model distillation](/docs/guides/distillation) or - Structured Outputs which ensures the model will match your supplied - JSON + [evals](/docs/guides/evals) products. + stream: + description: > + If set to true, the model response data will be streamed to the + client - schema. Learn more in the [Structured Outputs + 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). - guide](/docs/guides/structured-outputs). + See the [Streaming section + below](/docs/api-reference/chat/streaming) + for more information, along with the [streaming + responses](/docs/guides/streaming-responses) - Setting to `{ "type": "json_object" }` enables JSON mode, which - ensures + guide for more information on how to handle the streaming + events. + type: boolean + nullable: true + default: false + stop: + $ref: "#/components/schemas/StopConfiguration" + logit_bias: + type: object + x-oaiTypeLabel: map + default: null + nullable: true + additionalProperties: + type: integer + description: > + Modify the likelihood of specified tokens appearing in the + completion. - the message the model generates is valid JSON. + Accepts a JSON object that maps tokens (specified by their token + ID in the - **Important:** when using JSON mode, you **must** also instruct the - model + tokenizer) to an associated bias value from -100 to 100. + Mathematically, - to produce JSON yourself via a system or user message. Without this, - the + the bias is added to the logits generated by the model prior to + sampling. - model may generate an unending stream of whitespace until the - generation + The exact effect will vary per model, but values between -1 and + 1 should - reaches the token limit, resulting in a long-running and seemingly - "stuck" + decrease or increase likelihood of selection; values like -100 + or 100 - request. Also note that the message content may be partially cut off - if + should result in a ban or exclusive selection of the relevant + token. + logprobs: + description: > + Whether to return log probabilities of the output tokens or not. + If true, - `finish_reason="length"`, which indicates the generation exceeded + returns the log probabilities of each output token returned in + the - `max_tokens` or the conversation exceeded the max context length. - oneOf: - - $ref: "#/components/schemas/ResponseFormatText" - - $ref: "#/components/schemas/ResponseFormatJsonObject" - - $ref: "#/components/schemas/ResponseFormatJsonSchema" - x-oaiExpandable: true - seed: - type: integer - format: int64 - nullable: true - description: > - This feature is in Beta. + `content` of `message`. + type: boolean + default: false + nullable: true + max_tokens: + description: > + The maximum number of [tokens](/tokenizer) that can be generated + in the - If specified, our system will make a best effort to sample - deterministically, such that repeated requests with the same `seed` - and parameters should return the same result. + chat completion. This value can be used to control - Determinism is not guaranteed, and you should refer to the - `system_fingerprint` response parameter to monitor changes in the - backend. - x-oaiMeta: - beta: true - service_tier: - description: > - Specifies the latency tier to use for processing the request. This - parameter is relevant for customers subscribed to the scale tier - service: - - If set to 'auto', and the Project is Scale tier enabled, the system will utilize scale tier credits until they are exhausted. - - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarantee. - - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarantee. - - When not set, the default behavior is 'auto'. - type: string - enum: - - auto - - default - nullable: true - default: auto - stop: - description: | - Up to 4 sequences where the API will stop generating further tokens. - default: null - oneOf: - - type: string - nullable: true - - type: array - minItems: 1 - maxItems: 4 - items: - type: string - stream: - description: > - If set, partial message deltas will be sent, like in ChatGPT. Tokens - will be sent as data-only [server-sent - events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) - as they become available, with the stream terminated by a `data: - [DONE]` message. [Example Python - code](https://cookbook.openai.com/examples/how_to_stream_completions). - type: boolean - nullable: true - default: false - stream_options: - $ref: "#/components/schemas/ChatCompletionStreamOptions" - temperature: - type: number - minimum: 0 - maximum: 2 - default: 1 - example: 1 - nullable: true - 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. + [costs](https://openai.com/api/pricing/) for text generated via + API. - We generally recommend altering this or `top_p` but not both. - top_p: - type: number - minimum: 0 - maximum: 1 - default: 1 - example: 1 - nullable: true - description: > - An alternative to sampling with temperature, called nucleus - sampling, - where the model considers the results of the tokens with top_p - probability + This value is now deprecated in favor of + `max_completion_tokens`, and is - mass. So 0.1 means only the tokens comprising the top 10% - probability mass + not compatible with [o1 series models](/docs/guides/reasoning). + type: integer + nullable: true + deprecated: true + n: + type: integer + minimum: 1 + maximum: 128 + default: 1 + example: 1 + nullable: true + description: How many chat completion choices to generate for each input + message. Note that you will be charged based on the number of + generated tokens across all of the choices. Keep `n` as `1` to + minimize costs. + prediction: + nullable: true + x-oaiExpandable: true + description: > + Configuration for a [Predicted + Output](/docs/guides/predicted-outputs), - are considered. + which can greatly improve response times when large parts of the + model + response are known ahead of time. This is most common when you + are - We generally recommend altering this or `temperature` but not both. - tools: - type: array - description: > - A list of tools the model may call. Currently, only functions are - supported as a tool. Use this to provide a list of functions the - model may generate JSON inputs for. A max of 128 functions are - supported. - items: - $ref: "#/components/schemas/ChatCompletionTool" - tool_choice: - $ref: "#/components/schemas/ChatCompletionToolChoiceOption" - parallel_tool_calls: - $ref: "#/components/schemas/ParallelToolCalls" - user: - type: string - example: user-1234 - description: > - A unique identifier representing your end-user, which can help - OpenAI to monitor and detect abuse. [Learn - more](/docs/guides/safety-best-practices#end-user-ids). - function_call: - deprecated: true - description: > - Deprecated in favor of `tool_choice`. + regenerating a file with only minor changes to most of the + content. + oneOf: + - $ref: "#/components/schemas/PredictionContent" + seed: + type: integer + minimum: -9223372036854776000 + maximum: 9223372036854776000 + nullable: true + description: > + This feature is in Beta. + + If specified, our system will make a best effort to sample + deterministically, such that repeated requests with the same + `seed` and parameters should return the same result. + + Determinism is not guaranteed, and you should refer to the + `system_fingerprint` response parameter to monitor changes in + the backend. + x-oaiMeta: + beta: true + stream_options: + $ref: "#/components/schemas/ChatCompletionStreamOptions" + tools: + type: array + description: > + A list of tools the model may call. Currently, only functions + are supported as a tool. Use this to provide a list of functions + the model may generate JSON inputs for. A max of 128 functions + are supported. + items: + $ref: "#/components/schemas/ChatCompletionTool" + tool_choice: + $ref: "#/components/schemas/ChatCompletionToolChoiceOption" + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + function_call: + deprecated: true + description: > + Deprecated in favor of `tool_choice`. - Controls which (if any) function is called by the model. + Controls which (if any) function is called by the model. - `none` means the model will not call a function and instead - generates a + `none` means the model will not call a function and instead + generates a - message. + message. - `auto` means the model can pick between generating a message or - calling a + `auto` means the model can pick between generating a message or + calling a - function. + function. - Specifying a particular function via `{"name": "my_function"}` - forces the + Specifying a particular function via `{"name": "my_function"}` + forces the - model to call that function. + model to call that function. - `none` is the default when no functions are present. `auto` is the - default + `none` is the default when no functions are present. `auto` is + the default - if functions are present. - oneOf: - - type: string - description: > - `none` means the model will not call a function and instead - generates a message. `auto` means the model can pick between - generating a message or calling a function. - enum: - - none - - auto - - $ref: "#/components/schemas/ChatCompletionFunctionCallOption" - x-oaiExpandable: true - functions: - deprecated: true - description: | - Deprecated in favor of `tools`. + if functions are present. + oneOf: + - type: string + description: > + `none` means the model will not call a function and instead + generates a message. `auto` means the model can pick between + generating a message or calling a function. + enum: + - none + - auto + - $ref: "#/components/schemas/ChatCompletionFunctionCallOption" + x-oaiExpandable: true + functions: + deprecated: true + description: | + Deprecated in favor of `tools`. - A list of functions the model may generate JSON inputs for. - type: array - minItems: 1 - maxItems: 128 - items: - $ref: "#/components/schemas/ChatCompletionFunctions" - required: - - model - - messages + A list of functions the model may generate JSON inputs for. + type: array + minItems: 1 + maxItems: 128 + items: + $ref: "#/components/schemas/ChatCompletionFunctions" + required: + - model + - messages CreateChatCompletionResponse: type: object description: Represents a chat completion response returned by model, based on @@ -14420,43 +17408,49 @@ components: x-oaiMeta: name: The chat completion object group: chat - example: | + example: > { - "id": "chatcmpl-123456", + "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG", "object": "chat.completion", - "created": 1728933352, + "created": 1741570283, "model": "gpt-4o-2024-08-06", "choices": [ { "index": 0, "message": { "role": "assistant", - "content": "Hi there! How can I assist you today?", - "refusal": null + "content": "The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.", + "refusal": null, + "annotations": [] }, "logprobs": null, "finish_reason": "stop" } ], "usage": { - "prompt_tokens": 19, - "completion_tokens": 10, - "total_tokens": 29, + "prompt_tokens": 1117, + "completion_tokens": 46, + "total_tokens": 1163, "prompt_tokens_details": { - "cached_tokens": 0 + "cached_tokens": 0, + "audio_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0, + "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } }, - "system_fingerprint": "fp_6b68a8204b" + "service_tier": "default", + "system_fingerprint": "fp_fc9f1d7035" } CreateChatCompletionStreamResponse: type: object - description: Represents a streamed chunk of a chat completion response returned - by model, based on the provided input. + description: | + Represents a streamed chunk of a chat completion response returned + by the model, based on the provided input. + [Learn more](/docs/guides/streaming-responses). properties: id: type: string @@ -14780,30 +17774,15 @@ components: nullable: true description: > If specified, our system will make a best effort to sample - deterministically, such that repeated requests with the same `seed` - and parameters should return the same result. - - - Determinism is not guaranteed, and you should refer to the - `system_fingerprint` response parameter to monitor changes in the - backend. - stop: - description: > - Up to 4 sequences where the API will stop generating further tokens. - The returned text will not contain the stop sequence. - default: null - nullable: true - oneOf: - - type: string - default: <|endoftext|> - example: "\n" - nullable: true - - type: array - minItems: 1 - maxItems: 4 - items: - type: string - example: '["\n"]' + deterministically, such that repeated requests with the same `seed` + and parameters should return the same result. + + + Determinism is not guaranteed, and you should refer to the + `system_fingerprint` response parameter to monitor changes in the + backend. + stop: + $ref: "#/components/schemas/StopConfiguration" stream: description: > Whether to stream back partial progress. If set, tokens will be sent @@ -15120,20 +18099,19 @@ components: format: binary purpose: description: > - The intended purpose of the uploaded file. - - - Use "assistants" for [Assistants](/docs/api-reference/assistants) - and [Message](/docs/api-reference/messages) files, "vision" for - Assistants image file inputs, "batch" for [Batch - API](/docs/guides/batch), and "fine-tune" for - [Fine-tuning](/docs/api-reference/fine-tuning). + The intended purpose of the uploaded file. One of: - `assistants`: + Used in the Assistants API - `batch`: Used in the Batch API - + `fine-tune`: Used for fine-tuning - `vision`: Images used for vision + fine-tuning - `user_data`: Flexible file type for any purpose - + `evals`: Used for eval data sets type: string enum: - assistants - batch - fine-tune - vision + - user_data + - evals required: - file - purpose @@ -15352,6 +18330,8 @@ components: example: 42 method: $ref: "#/components/schemas/FineTuneMethod" + metadata: + $ref: "#/components/schemas/Metadata" required: - model - training_file @@ -15640,6 +18620,9 @@ components: nullable: true metadata: $ref: "#/components/schemas/Metadata" + CreateModelResponseProperties: + allOf: + - $ref: "#/components/schemas/ModelResponseProperties" CreateModerationRequest: type: object properties: @@ -16017,2150 +19000,4777 @@ components: - category_applied_input_types required: - id - - model - - results + - model + - results + x-oaiMeta: + name: The moderation object + example: | + { + "id": "modr-0d9740456c391e43c445bf0f010940c7", + "model": "omni-moderation-latest", + "results": [ + { + "flagged": true, + "categories": { + "harassment": true, + "harassment/threatening": true, + "sexual": false, + "hate": false, + "hate/threatening": false, + "illicit": false, + "illicit/violent": false, + "self-harm/intent": false, + "self-harm/instructions": false, + "self-harm": false, + "sexual/minors": false, + "violence": true, + "violence/graphic": true + }, + "category_scores": { + "harassment": 0.8189693396524255, + "harassment/threatening": 0.804985420696006, + "sexual": 1.573112165348997e-6, + "hate": 0.007562942636942845, + "hate/threatening": 0.004208854591835476, + "illicit": 0.030535955153511665, + "illicit/violent": 0.008925306722380033, + "self-harm/intent": 0.00023023930975076432, + "self-harm/instructions": 0.0002293869201073356, + "self-harm": 0.012598046106750154, + "sexual/minors": 2.212566909570261e-8, + "violence": 0.9999992735124786, + "violence/graphic": 0.843064871157054 + }, + "category_applied_input_types": { + "harassment": [ + "text" + ], + "harassment/threatening": [ + "text" + ], + "sexual": [ + "text", + "image" + ], + "hate": [ + "text" + ], + "hate/threatening": [ + "text" + ], + "illicit": [ + "text" + ], + "illicit/violent": [ + "text" + ], + "self-harm/intent": [ + "text", + "image" + ], + "self-harm/instructions": [ + "text", + "image" + ], + "self-harm": [ + "text", + "image" + ], + "sexual/minors": [ + "text" + ], + "violence": [ + "text", + "image" + ], + "violence/graphic": [ + "text", + "image" + ] + } + } + ] + } + CreateResponse: + allOf: + - $ref: "#/components/schemas/CreateModelResponseProperties" + - $ref: "#/components/schemas/ResponseProperties" + - type: object + properties: + input: + description: > + Text, image, or file inputs to the model, used to generate a + response. + + + Learn more: + + - [Text inputs and outputs](/docs/guides/text) + + - [Image inputs](/docs/guides/images) + + - [File inputs](/docs/guides/pdf-files) + + - [Conversation state](/docs/guides/conversation-state) + + - [Function calling](/docs/guides/function-calling) + x-oaiExpandable: true + oneOf: + - 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: + x-oaiExpandable: true + $ref: "#/components/schemas/InputItem" + include: + type: array + description: + $ref: "#/components/schemas/Includable/description" + items: + x-oaiExpandable: true + $ref: "#/components/schemas/Includable" + nullable: true + parallel_tool_calls: + type: boolean + description: | + Whether to allow the model to run tool calls in parallel. + default: true + nullable: true + store: + type: boolean + description: > + Whether to store the generated model response for later + retrieval via + + API. + default: true + nullable: true + stream: + 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](/docs/api-reference/responses-streaming) + + for more information. + type: boolean + nullable: true + default: false + required: + - model + - input + CreateRunRequest: + type: object + additionalProperties: false + properties: + assistant_id: + description: The ID of the [assistant](/docs/api-reference/assistants) to use to + execute this run. + type: string + model: + description: The ID of the [Model](/docs/api-reference/models) to be used to + execute this run. If a value is provided here, it will override the + model associated with the assistant. If not, the model associated + with the assistant will be used. + example: gpt-4o + anyOf: + - type: string + - $ref: "#/components/schemas/AssistantSupportedModels" + x-oaiTypeLabel: string + nullable: true + reasoning_effort: + $ref: "#/components/schemas/ReasoningEffort" + instructions: + description: Overrides the + [instructions](/docs/api-reference/assistants/createAssistant) of + the assistant. This is useful for modifying the behavior on a + per-run basis. + type: string + nullable: true + additional_instructions: + description: Appends additional instructions at the end of the instructions for + the run. This is useful for modifying the behavior on a per-run + basis without overriding other instructions. + type: string + nullable: true + additional_messages: + description: Adds additional messages to the thread before creating the run. + type: array + items: + $ref: "#/components/schemas/CreateMessageRequest" + nullable: true + tools: + description: Override the tools the assistant can use for this run. This is + useful for modifying the behavior on a per-run basis. + nullable: true + type: array + maxItems: 20 + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearch" + - $ref: "#/components/schemas/AssistantToolsFunction" + x-oaiExpandable: true + metadata: + $ref: "#/components/schemas/Metadata" + temperature: + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + 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. + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + 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. + stream: + type: boolean + nullable: true + description: > + If `true`, returns a stream of events that happen during the Run as + server-sent events, terminating when the Run enters a terminal state + with a `data: [DONE]` message. + max_prompt_tokens: + type: integer + nullable: true + description: > + The maximum number of prompt tokens that may be used over the course + of the run. The run will make a best effort to use only the number + of prompt tokens specified, across multiple turns of the run. If the + run exceeds the number of prompt tokens specified, the run will end + with status `incomplete`. See `incomplete_details` for more info. + minimum: 256 + max_completion_tokens: + type: integer + nullable: true + description: > + The maximum number of completion tokens that may be used over the + course of the run. The run will make a best effort to use only the + number of completion tokens specified, across multiple turns of the + run. If the run exceeds the number of completion tokens specified, + the run will end with status `incomplete`. See `incomplete_details` + for more info. + minimum: 256 + truncation_strategy: + allOf: + - $ref: "#/components/schemas/TruncationObject" + - nullable: true + tool_choice: + allOf: + - $ref: "#/components/schemas/AssistantsApiToolChoiceOption" + - nullable: true + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + response_format: + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true + required: + - assistant_id + CreateSpeechRequest: + type: object + additionalProperties: false + properties: + model: + description: > + One of the available [TTS models](/docs/models#tts): `tts-1` or + `tts-1-hd` + anyOf: + - type: string + - type: string + enum: + - tts-1 + - tts-1-hd + x-oaiTypeLabel: string + input: + type: string + description: The text to generate audio for. The maximum length is 4096 + characters. + maxLength: 4096 + voice: + description: The voice to use when generating the audio. Supported voices are + `alloy`, `ash`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage` and + `shimmer`. Previews of the voices are available in the [Text to + speech guide](/docs/guides/text-to-speech#voice-options). + type: string + enum: + - alloy + - ash + - coral + - echo + - fable + - onyx + - nova + - sage + - shimmer + response_format: + description: The format to audio in. Supported formats are `mp3`, `opus`, `aac`, + `flac`, `wav`, and `pcm`. + default: mp3 + type: string + enum: + - mp3 + - opus + - aac + - flac + - wav + - pcm + speed: + description: The speed of the generated audio. Select a value from `0.25` to + `4.0`. `1.0` is the default. + type: number + default: 1 + minimum: 0.25 + maximum: 4 + required: + - model + - input + - voice + CreateThreadAndRunRequest: + type: object + additionalProperties: false + properties: + assistant_id: + description: The ID of the [assistant](/docs/api-reference/assistants) to use to + execute this run. + type: string + thread: + $ref: "#/components/schemas/CreateThreadRequest" + model: + description: The ID of the [Model](/docs/api-reference/models) to be used to + execute this run. If a value is provided here, it will override the + model associated with the assistant. If not, the model associated + with the assistant will be used. + example: gpt-4o + anyOf: + - type: string + - type: string + enum: + - gpt-4o + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o-mini + - gpt-4o-mini-2024-07-18 + - gpt-4.5-preview + - gpt-4.5-preview-2025-02-27 + - gpt-4-turbo + - gpt-4-turbo-2024-04-09 + - gpt-4-0125-preview + - gpt-4-turbo-preview + - gpt-4-1106-preview + - gpt-4-vision-preview + - gpt-4 + - gpt-4-0314 + - gpt-4-0613 + - gpt-4-32k + - gpt-4-32k-0314 + - gpt-4-32k-0613 + - gpt-3.5-turbo + - gpt-3.5-turbo-16k + - gpt-3.5-turbo-0613 + - gpt-3.5-turbo-1106 + - gpt-3.5-turbo-0125 + - gpt-3.5-turbo-16k-0613 + x-oaiTypeLabel: string + nullable: true + instructions: + description: Override the default system message of the assistant. This is + useful for modifying the behavior on a per-run basis. + type: string + nullable: true + tools: + description: Override the tools the assistant can use for this run. This is + useful for modifying the behavior on a per-run basis. + nullable: true + type: array + maxItems: 20 + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearch" + - $ref: "#/components/schemas/AssistantToolsFunction" + tool_resources: + type: object + description: > + A set of resources that are used by the assistant's tools. The + resources are specific to the type of tool. For example, the + `code_interpreter` tool requires a list of file IDs, while the + `file_search` tool requires a list of vector store IDs. + properties: + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs made + available to the `code_interpreter` tool. There can be a + maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + The ID of the [vector + store](/docs/api-reference/vector-stores/object) attached to + this assistant. There can be a maximum of 1 vector store + attached to the assistant. + maxItems: 1 + items: + type: string + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + temperature: + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + 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. + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + 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. + stream: + type: boolean + nullable: true + description: > + If `true`, returns a stream of events that happen during the Run as + server-sent events, terminating when the Run enters a terminal state + with a `data: [DONE]` message. + max_prompt_tokens: + type: integer + nullable: true + description: > + The maximum number of prompt tokens that may be used over the course + of the run. The run will make a best effort to use only the number + of prompt tokens specified, across multiple turns of the run. If the + run exceeds the number of prompt tokens specified, the run will end + with status `incomplete`. See `incomplete_details` for more info. + minimum: 256 + max_completion_tokens: + type: integer + nullable: true + description: > + The maximum number of completion tokens that may be used over the + course of the run. The run will make a best effort to use only the + number of completion tokens specified, across multiple turns of the + run. If the run exceeds the number of completion tokens specified, + the run will end with status `incomplete`. See `incomplete_details` + for more info. + minimum: 256 + truncation_strategy: + allOf: + - $ref: "#/components/schemas/TruncationObject" + - nullable: true + tool_choice: + allOf: + - $ref: "#/components/schemas/AssistantsApiToolChoiceOption" + - nullable: true + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + response_format: + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true + required: + - assistant_id + CreateThreadRequest: + type: object + description: | + Options to create a new thread. If no thread is provided when running a + request, an empty thread will be created. + additionalProperties: false + properties: + messages: + description: A list of [messages](/docs/api-reference/messages) to start the + thread with. + type: array + items: + $ref: "#/components/schemas/CreateMessageRequest" + tool_resources: + type: object + description: > + A set of resources that are made available to the assistant's tools + in this thread. The resources are specific to the type of tool. For + example, the `code_interpreter` tool requires a list of file IDs, + while the `file_search` tool requires a list of vector store IDs. + properties: + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs made + available to the `code_interpreter` tool. There can be a + maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + The [vector store](/docs/api-reference/vector-stores/object) + attached to this thread. There can be a maximum of 1 vector + store attached to the thread. + maxItems: 1 + items: + type: string + vector_stores: + type: array + description: > + A helper to create a [vector + store](/docs/api-reference/vector-stores/object) with + file_ids and attach it to this thread. There can be a + maximum of 1 vector store attached to the thread. + maxItems: 1 + items: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs to add + to the vector store. There can be a maximum of 10000 + files in a vector store. + maxItems: 10000 + items: + type: string + chunking_strategy: + type: object + description: The chunking strategy used to chunk the file(s). If not set, will + use the `auto` strategy. + oneOf: + - type: object + title: Auto Chunking Strategy + description: The default strategy. This strategy currently uses a + `max_chunk_size_tokens` of `800` and + `chunk_overlap_tokens` of `400`. + additionalProperties: false + properties: + type: + type: string + description: Always `auto`. + enum: + - auto + x-stainless-const: true + required: + - type + - type: object + title: Static Chunking Strategy + additionalProperties: false + properties: + type: + type: string + description: Always `static`. + enum: + - static + x-stainless-const: true + static: + type: object + additionalProperties: false + properties: + max_chunk_size_tokens: + type: integer + minimum: 100 + maximum: 4096 + description: The maximum number of tokens in each chunk. The default value is + `800`. The minimum value is `100` and the + maximum value is `4096`. + chunk_overlap_tokens: + type: integer + description: > + The number of tokens that overlap between + chunks. The default value is `400`. + + + Note that the overlap must not exceed half + of `max_chunk_size_tokens`. + required: + - max_chunk_size_tokens + - chunk_overlap_tokens + required: + - type + - static + x-oaiExpandable: true + metadata: + $ref: "#/components/schemas/Metadata" + x-oaiExpandable: true + oneOf: + - required: + - vector_store_ids + - required: + - vector_stores + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + CreateTranscriptionRequest: + type: object + additionalProperties: false + properties: + file: + description: > + The audio file object (not file name) to transcribe, in one of these + formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. + type: string + x-oaiTypeLabel: file + format: binary + model: + description: > + ID of the model to use. Only `whisper-1` (which is powered by our + open source Whisper V2 model) is currently available. + example: whisper-1 + anyOf: + - type: string + - type: string + enum: + - whisper-1 + x-stainless-const: true + x-oaiTypeLabel: string + language: + description: > + The language of the input audio. Supplying the input language in + [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) + (e.g. `en`) format will improve accuracy and latency. + type: string + prompt: + description: > + An optional text to guide the model's style or continue a previous + audio segment. The [prompt](/docs/guides/speech-to-text#prompting) + should match the audio language. + type: string + response_format: + $ref: "#/components/schemas/AudioResponseFormat" + temperature: + description: > + The sampling temperature, between 0 and 1. Higher values like 0.8 + will make the output more random, while lower values like 0.2 will + make it more focused and deterministic. If set to 0, the model will + use [log probability](https://en.wikipedia.org/wiki/Log_probability) + to automatically increase the temperature until certain thresholds + are hit. + type: number + default: 0 + timestamp_granularities[]: + description: > + The timestamp granularities to populate for this transcription. + `response_format` must be set `verbose_json` to use timestamp + granularities. Either or both of these options are supported: + `word`, or `segment`. Note: There is no additional latency for + segment timestamps, but generating word timestamps incurs additional + latency. + type: array + items: + type: string + enum: + - word + - segment + default: + - segment + required: + - file + - model + CreateTranscriptionResponseJson: + type: object + description: Represents a transcription response returned by model, based on the + provided input. + properties: + text: + type: string + description: The transcribed text. + required: + - text + x-oaiMeta: + name: The transcription object (JSON) + group: audio + example: > + { + "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that." + } + CreateTranscriptionResponseVerboseJson: + type: object + description: Represents a verbose json transcription response returned by model, + based on the provided input. + properties: + language: + type: string + description: The language of the input audio. + duration: + type: number + description: The duration of the input audio. + text: + type: string + description: The transcribed text. + words: + type: array + description: Extracted words and their corresponding timestamps. + items: + $ref: "#/components/schemas/TranscriptionWord" + segments: + type: array + description: Segments of the transcribed text and their corresponding details. + items: + $ref: "#/components/schemas/TranscriptionSegment" + required: + - language + - duration + - text + x-oaiMeta: + name: The transcription object (Verbose JSON) + group: audio + example: > + { + "task": "transcribe", + "language": "english", + "duration": 8.470000267028809, + "text": "The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.", + "segments": [ + { + "id": 0, + "seek": 0, + "start": 0.0, + "end": 3.319999933242798, + "text": " The beach was a popular spot on a hot summer day.", + "tokens": [ + 50364, 440, 7534, 390, 257, 3743, 4008, 322, 257, 2368, 4266, 786, 13, 50530 + ], + "temperature": 0.0, + "avg_logprob": -0.2860786020755768, + "compression_ratio": 1.2363636493682861, + "no_speech_prob": 0.00985979475080967 + }, + ... + ] + } + CreateTranslationRequest: + type: object + additionalProperties: false + properties: + file: + description: > + The audio file object (not file name) translate, in one of these + formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. + type: string + x-oaiTypeLabel: file + format: binary + model: + description: > + ID of the model to use. Only `whisper-1` (which is powered by our + open source Whisper V2 model) is currently available. + example: whisper-1 + anyOf: + - type: string + - type: string + enum: + - whisper-1 + x-stainless-const: true + x-oaiTypeLabel: string + prompt: + description: > + An optional text to guide the model's style or continue a previous + audio segment. The [prompt](/docs/guides/speech-to-text#prompting) + should be in English. + type: string + response_format: + $ref: "#/components/schemas/AudioResponseFormat" + temperature: + description: > + The sampling temperature, between 0 and 1. Higher values like 0.8 + will make the output more random, while lower values like 0.2 will + make it more focused and deterministic. If set to 0, the model will + use [log probability](https://en.wikipedia.org/wiki/Log_probability) + to automatically increase the temperature until certain thresholds + are hit. + type: number + default: 0 + required: + - file + - model + CreateTranslationResponseJson: + type: object + properties: + text: + type: string + required: + - text + CreateTranslationResponseVerboseJson: + type: object + properties: + language: + type: string + description: The language of the output translation (always `english`). + duration: + type: number + description: The duration of the input audio. + text: + type: string + description: The translated text. + segments: + type: array + description: Segments of the translated text and their corresponding details. + items: + $ref: "#/components/schemas/TranscriptionSegment" + required: + - language + - duration + - text + CreateUploadRequest: + type: object + additionalProperties: false + properties: + filename: + description: | + The name of the file to upload. + type: string + purpose: + description: > + The intended purpose of the uploaded file. + + + See the [documentation on File + purposes](/docs/api-reference/files/create#files-create-purpose). + type: string + enum: + - assistants + - batch + - fine-tune + - vision + bytes: + description: | + The number of bytes in the file you are uploading. + type: integer + mime_type: + description: > + The MIME type of the file. + + + This must fall within the supported MIME types for your file + purpose. See the supported MIME types for assistants and vision. + type: string + required: + - filename + - purpose + - bytes + - mime_type + CreateVectorStoreFileBatchRequest: + type: object + additionalProperties: false + properties: + file_ids: + description: A list of [File](/docs/api-reference/files) IDs that the vector + store should use. Useful for tools like `file_search` that can + access files. + type: array + minItems: 1 + maxItems: 500 + items: + type: string + chunking_strategy: + $ref: "#/components/schemas/ChunkingStrategyRequestParam" + attributes: + $ref: "#/components/schemas/VectorStoreFileAttributes" + required: + - file_ids + CreateVectorStoreFileRequest: + type: object + additionalProperties: false + properties: + file_id: + description: A [File](/docs/api-reference/files) ID that the vector store should + use. Useful for tools like `file_search` that can access files. + type: string + chunking_strategy: + $ref: "#/components/schemas/ChunkingStrategyRequestParam" + attributes: + $ref: "#/components/schemas/VectorStoreFileAttributes" + required: + - file_id + CreateVectorStoreRequest: + type: object + additionalProperties: false + properties: + file_ids: + description: A list of [File](/docs/api-reference/files) IDs that the vector + store should use. Useful for tools like `file_search` that can + access files. + type: array + maxItems: 500 + items: + type: string + name: + description: The name of the vector store. + type: string + expires_after: + $ref: "#/components/schemas/VectorStoreExpirationAfter" + chunking_strategy: + type: object + description: The chunking strategy used to chunk the file(s). If not set, will + use the `auto` strategy. Only applicable if `file_ids` is non-empty. + oneOf: + - $ref: "#/components/schemas/AutoChunkingStrategyRequestParam" + - $ref: "#/components/schemas/StaticChunkingStrategyRequestParam" + x-oaiExpandable: true + metadata: + $ref: "#/components/schemas/Metadata" + DefaultProjectErrorResponse: + type: object + properties: + code: + type: integer + message: + type: string + required: + - code + - message + DeleteAssistantResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + enum: + - assistant.deleted + x-stainless-const: true + required: + - id + - object + - deleted + DeleteFileResponse: + type: object + properties: + id: + type: string + object: + type: string + enum: + - file + x-stainless-const: true + deleted: + type: boolean + required: + - id + - object + - deleted + DeleteMessageResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + enum: + - thread.message.deleted + x-stainless-const: true + required: + - id + - object + - deleted + DeleteModelResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + required: + - id + - object + - deleted + DeleteThreadResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + enum: + - thread.deleted + x-stainless-const: true + required: + - id + - object + - deleted + DeleteVectorStoreFileResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + enum: + - vector_store.file.deleted + x-stainless-const: true + required: + - id + - object + - deleted + DeleteVectorStoreResponse: + type: object + properties: + id: + type: string + deleted: + type: boolean + object: + type: string + enum: + - vector_store.deleted + x-stainless-const: true + required: + - id + - object + - deleted + DoneEvent: + type: object + properties: + event: + type: string + enum: + - done + x-stainless-const: true + data: + type: string + enum: + - "[DONE]" + x-stainless-const: true + required: + - event + - data + description: Occurs when a stream ends. + x-oaiMeta: + dataDescription: "`data` is `[DONE]`" + DoubleClick: + type: object + title: DoubleClick + description: | + A double click action. + properties: + type: + type: string + enum: + - double_click + default: double_click + description: > + Specifies the event type. For a double click action, this property + is + + always set to `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. + required: + - type + - x + - y + Drag: + type: object + title: Drag + description: | + A drag action. + properties: + type: + type: string + enum: + - drag + default: drag + description: | + Specifies the event type. For a drag action, this property is + always set to `drag`. + x-stainless-const: true + path: + 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 } + ] + + ``` + x-oaiExpandable: true + items: + title: Drag path coordinates + x-oaiExpandable: true + description: | + A series of x/y coordinate pairs in the drag path. + $ref: "#/components/schemas/Coordinate" + required: + - type + - path + EasyInputMessage: + 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. + x-oaiExpandable: true + oneOf: + - type: string + title: Text input + description: | + A text input to the model. + - $ref: "#/components/schemas/InputMessageContentList" + type: + type: string + description: | + The type of the message input. Always `message`. + enum: + - message + x-stainless-const: true + required: + - role + - content + Embedding: + type: object + description: | + Represents an embedding vector returned by embedding endpoint. + properties: + index: + type: integer + description: The index of the embedding in the list of embeddings. + embedding: + type: array + description: > + The embedding vector, which is a list of floats. The length of + vector depends on the model as listed in the [embedding + guide](/docs/guides/embeddings). + items: + type: number + object: + type: string + description: The object type, which is always "embedding". + enum: + - embedding + x-stainless-const: true + required: + - index + - object + - embedding + x-oaiMeta: + name: The embedding object + example: | + { + "object": "embedding", + "embedding": [ + 0.0023064255, + -0.009327292, + .... (1536 floats total for ada-002) + -0.0028842222, + ], + "index": 0 + } + Error: + type: object + properties: + code: + type: string + nullable: true + message: + type: string + nullable: false + param: + type: string + nullable: true + type: + type: string + nullable: false + required: + - type + - message + - param + - code + ErrorEvent: + type: object + properties: + event: + type: string + enum: + - error + x-stainless-const: true + data: + $ref: "#/components/schemas/Error" + required: + - event + - data + description: Occurs when an [error](/docs/guides/error-codes#api-errors) occurs. + This can happen due to an internal server error or a timeout. + x-oaiMeta: + dataDescription: "`data` is an [error](/docs/guides/error-codes#api-errors)" + ErrorResponse: + type: object + properties: + error: + $ref: "#/components/schemas/Error" + required: + - error + FileCitation: + type: object + title: File citation + description: | + A citation to a file. + properties: + type: + type: string + description: | + The type of the file citation. Always `file_citation`. + enum: + - file_citation + x-stainless-const: true + index: + type: integer + description: | + The index of the file in the list of files. + file_id: + type: string + description: | + The ID of the file. + required: + - type + - index + - file_id + FilePath: + 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 + FileSearchRanker: + type: string + description: The ranker to use for the file search. If not specified will use + the `auto` ranker. + enum: + - auto + - default_2024_08_21 + FileSearchRankingOptions: + title: File search tool call ranking options + type: object + description: > + The ranking options for the file search. If not specified, the file + search tool will use the `auto` ranker and a score_threshold of 0. + + + See the [file search tool + documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) + for more information. + properties: + ranker: + $ref: "#/components/schemas/FileSearchRanker" + score_threshold: + type: number + description: The score threshold for the file search. All values must be a + floating point number between 0 and 1. + minimum: 0 + maximum: 1 + required: + - score_threshold + FileSearchTool: + type: object + title: File search + description: | + A tool that searches for relevant content from uploaded files. + Learn more about the [file search tool](/docs/guides/tools-file-search). + properties: + type: + type: string + enum: + - file_search + description: | + The type of the file search tool. Always `file_search`. + x-stainless-const: true + vector_store_ids: + type: array + items: + type: string + 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. + filters: + description: A filter to apply based on file attributes. + oneOf: + - $ref: "#/components/schemas/ComparisonFilter" + - $ref: "#/components/schemas/CompoundFilter" + x-oaiExpandable: true + ranking_options: + description: Ranking options for search. + type: object + additionalProperties: false + properties: + ranker: + type: string + description: The ranker to use for the file search. + enum: + - auto + - default-2024-11-15 + default: auto + 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. + minimum: 0 + maximum: 1 + default: 0 + required: + - type + - vector_store_ids + FileSearchToolCall: + type: object + title: File search tool call + description: > + The results of a file search tool call. See the + + [file search guide](/docs/guides/tools-file-search) for more + information. + properties: + 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: + 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/VectorStoreFileAttributes" + score: + type: number + format: float + description: | + The relevance score of the file - a value between 0 and 1. + nullable: true + required: + - id + - type + - status + - queries + FineTuneChatCompletionRequestAssistantMessage: + allOf: + - type: object + title: Assistant message + deprecated: false + properties: + weight: + type: integer + enum: + - 0 + - 1 + description: Controls whether the assistant message is trained against (0 or 1) + - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" + required: + - role + FineTuneChatRequestInput: + type: object + description: The per-line training example of a fine-tuning input file for chat + models using the supervised method. + properties: + messages: + type: array + minItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" + - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" + - $ref: "#/components/schemas/FineTuneChatCompletionRequestAssistantMessage" + - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" + - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" + x-oaiExpandable: true + tools: + type: array + description: A list of tools the model may generate JSON inputs for. + items: + $ref: "#/components/schemas/ChatCompletionTool" + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + functions: + deprecated: true + description: A list of functions the model may generate JSON inputs for. + type: array + minItems: 1 + maxItems: 128 + items: + $ref: "#/components/schemas/ChatCompletionFunctions" + x-oaiMeta: + name: Training format for chat models using the supervised method + example: > + { + "messages": [ + { "role": "user", "content": "What is the weather in San Francisco?" }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "call_id", + "type": "function", + "function": { + "name": "get_current_weather", + "arguments": "{\"location\": \"San Francisco, USA\", \"format\": \"celsius\"}" + } + } + ] + } + ], + "parallel_tool_calls": false, + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and country, eg. San Francisco, USA" + }, + "format": { "type": "string", "enum": ["celsius", "fahrenheit"] } + }, + "required": ["location", "format"] + } + } + } + ] + } + FineTuneCompletionRequestInput: + type: object + description: The per-line training example of a fine-tuning input file for + completions models + properties: + prompt: + type: string + description: The input prompt for this training example. + completion: + type: string + description: The desired completion for this training example. + x-oaiMeta: + name: Training format for completions models + example: | + { + "prompt": "What is the answer to 2+2", + "completion": "4" + } + FineTuneDPOMethod: + type: object + description: Configuration for the DPO fine-tuning method. + properties: + hyperparameters: + type: object + description: The hyperparameters used for the fine-tuning job. + properties: + beta: + description: > + The beta value for the DPO method. A higher beta value will + increase the weight of the penalty between the policy and + reference model. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: number + minimum: 0 + maximum: 2 + exclusiveMinimum: true + default: auto + batch_size: + description: > + Number of examples in each batch. A larger batch size means that + model parameters are updated less frequently, but with lower + variance. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 256 + default: auto + learning_rate_multiplier: + description: > + Scaling factor for the learning rate. A smaller learning rate + may be useful to avoid overfitting. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: number + minimum: 0 + exclusiveMinimum: true + default: auto + n_epochs: + description: > + The number of epochs to train the model for. An epoch refers to + one full cycle through the training dataset. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 50 + default: auto + FineTuneMethod: + type: object + description: The method used for fine-tuning. + properties: + type: + type: string + description: The type of method. Is either `supervised` or `dpo`. + enum: + - supervised + - dpo + supervised: + $ref: "#/components/schemas/FineTuneSupervisedMethod" + dpo: + $ref: "#/components/schemas/FineTuneDPOMethod" + FineTunePreferenceRequestInput: + type: object + description: The per-line training example of a fine-tuning input file for chat + models using the dpo method. + properties: + input: + type: object + properties: + messages: + type: array + minItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" + - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" + - $ref: "#/components/schemas/FineTuneChatCompletionRequestAssistantMessage" + - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" + - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" + x-oaiExpandable: true + tools: + type: array + description: A list of tools the model may generate JSON inputs for. + items: + $ref: "#/components/schemas/ChatCompletionTool" + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + preferred_completion: + type: array + description: The preferred completion message for the output. + maxItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" + x-oaiExpandable: true + non_preferred_completion: + type: array + description: The non-preferred completion message for the output. + maxItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" + x-oaiExpandable: true + x-oaiMeta: + name: Training format for chat models using the preference method + example: > + { + "input": { + "messages": [ + { "role": "user", "content": "What is the weather in San Francisco?" } + ] + }, + "preferred_completion": [ + { + "role": "assistant", + "content": "The weather in San Francisco is 70 degrees Fahrenheit." + } + ], + "non_preferred_completion": [ + { + "role": "assistant", + "content": "The weather in San Francisco is 21 degrees Celsius." + } + ] + } + FineTuneSupervisedMethod: + type: object + description: Configuration for the supervised fine-tuning method. + properties: + hyperparameters: + type: object + description: The hyperparameters used for the fine-tuning job. + properties: + batch_size: + description: > + Number of examples in each batch. A larger batch size means that + model parameters are updated less frequently, but with lower + variance. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 256 + default: auto + learning_rate_multiplier: + description: > + Scaling factor for the learning rate. A smaller learning rate + may be useful to avoid overfitting. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: number + minimum: 0 + exclusiveMinimum: true + default: auto + n_epochs: + description: > + The number of epochs to train the model for. An epoch refers to + one full cycle through the training dataset. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 50 + default: auto + FineTuningIntegration: + type: object + title: Fine-Tuning Job Integration + required: + - type + - wandb + properties: + type: + type: string + description: The type of the integration being enabled for the fine-tuning job + enum: + - wandb + x-stainless-const: true + wandb: + type: object + description: > + The settings for your integration with Weights and Biases. This + payload specifies the project that + + metrics will be sent to. Optionally, you can set an explicit display + name for your run, add tags + + to your run, and set a default entity (team, username, etc) to be + associated with your run. + required: + - project + properties: + project: + description: | + The name of the project that the new run will be created under. + type: string + example: my-wandb-project + name: + description: > + A display name to set for the run. If not set, we will use the + Job ID as the name. + nullable: true + type: string + entity: + description: > + The entity to use for the run. This allows you to set the team + or username of the WandB user that you would + + like associated with the run. If not set, the default entity for + the registered WandB API key is used. + nullable: true + type: string + tags: + description: > + A list of tags to be attached to the newly created run. These + tags are passed through directly to WandB. Some + + default tags are generated by OpenAI: "openai/finetune", + "openai/{base-model}", "openai/{ftjob-abcdef}". + type: array + items: + type: string + example: custom-tag + FineTuningJob: + type: object + title: FineTuningJob + description: > + The `fine_tuning.job` object represents a fine-tuning job that has been + created through the API. + properties: + id: + type: string + description: The object identifier, which can be referenced in the API endpoints. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the fine-tuning job was + created. + error: + type: object + nullable: true + description: For fine-tuning jobs that have `failed`, this will contain more + information on the cause of the failure. + properties: + code: + type: string + description: A machine-readable error code. + message: + type: string + description: A human-readable error message. + param: + type: string + description: The parameter that was invalid, usually `training_file` or + `validation_file`. This field will be null if the failure was + not parameter-specific. + nullable: true + required: + - code + - message + - param + fine_tuned_model: + type: string + nullable: true + description: The name of the fine-tuned model that is being created. The value + will be null if the fine-tuning job is still running. + finished_at: + type: integer + nullable: true + description: The Unix timestamp (in seconds) for when the fine-tuning job was + finished. The value will be null if the fine-tuning job is still + running. + hyperparameters: + type: object + description: The hyperparameters used for the fine-tuning job. This value will + only be returned when running `supervised` jobs. + properties: + batch_size: + description: > + Number of examples in each batch. A larger batch size means that + model parameters + + are updated less frequently, but with lower variance. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 256 + default: auto + learning_rate_multiplier: + description: > + Scaling factor for the learning rate. A smaller learning rate + may be useful to avoid + + overfitting. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: number + minimum: 0 + exclusiveMinimum: true + default: auto + n_epochs: + description: > + The number of epochs to train the model for. An epoch refers to + one full cycle + + through the training dataset. + oneOf: + - type: string + enum: + - auto + x-stainless-const: true + - type: integer + minimum: 1 + maximum: 50 + default: auto + model: + type: string + description: The base model that is being fine-tuned. + object: + type: string + description: The object type, which is always "fine_tuning.job". + enum: + - fine_tuning.job + x-stainless-const: true + organization_id: + type: string + description: The organization that owns the fine-tuning job. + result_files: + type: array + description: The compiled results file ID(s) for the fine-tuning job. You can + retrieve the results with the [Files + API](/docs/api-reference/files/retrieve-contents). + items: + type: string + example: file-abc123 + status: + type: string + description: The current status of the fine-tuning job, which can be either + `validating_files`, `queued`, `running`, `succeeded`, `failed`, or + `cancelled`. + enum: + - validating_files + - queued + - running + - succeeded + - failed + - cancelled + trained_tokens: + type: integer + nullable: true + description: The total number of billable tokens processed by this fine-tuning + job. The value will be null if the fine-tuning job is still running. + training_file: + type: string + description: The file ID used for training. You can retrieve the training data + with the [Files API](/docs/api-reference/files/retrieve-contents). + validation_file: + type: string + nullable: true + description: The file ID used for validation. You can retrieve the validation + results with the [Files + API](/docs/api-reference/files/retrieve-contents). + integrations: + type: array + nullable: true + description: A list of integrations to enable for this fine-tuning job. + maxItems: 5 + items: + oneOf: + - $ref: "#/components/schemas/FineTuningIntegration" + x-oaiExpandable: true + seed: + type: integer + description: The seed used for the fine-tuning job. + estimated_finish: + type: integer + nullable: true + description: The Unix timestamp (in seconds) for when the fine-tuning job is + estimated to finish. The value will be null if the fine-tuning job + is not running. + method: + $ref: "#/components/schemas/FineTuneMethod" + metadata: + $ref: "#/components/schemas/Metadata" + required: + - created_at + - error + - finished_at + - fine_tuned_model + - hyperparameters + - id + - model + - object + - organization_id + - result_files + - status + - trained_tokens + - training_file + - validation_file + - seed + x-oaiMeta: + name: The fine-tuning job object + example: | + { + "object": "fine_tuning.job", + "id": "ftjob-abc123", + "model": "davinci-002", + "created_at": 1692661014, + "finished_at": 1692661190, + "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy", + "organization_id": "org-123", + "result_files": [ + "file-abc123" + ], + "status": "succeeded", + "validation_file": null, + "training_file": "file-abc123", + "hyperparameters": { + "n_epochs": 4, + "batch_size": 1, + "learning_rate_multiplier": 1.0 + }, + "trained_tokens": 5768, + "integrations": [], + "seed": 0, + "estimated_finish": 0, + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "n_epochs": 4, + "batch_size": 1, + "learning_rate_multiplier": 1.0 + } + } + }, + "metadata": { + "key": "value" + } + } + FineTuningJobCheckpoint: + type: object + title: FineTuningJobCheckpoint + description: > + The `fine_tuning.job.checkpoint` object represents a model checkpoint + for a fine-tuning job that is ready to use. + properties: + id: + type: string + description: The checkpoint identifier, which can be referenced in the API + endpoints. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the checkpoint was created. + fine_tuned_model_checkpoint: + type: string + description: The name of the fine-tuned checkpoint model that is created. + step_number: + type: integer + description: The step number that the checkpoint was created at. + metrics: + type: object + description: Metrics at the step number during the fine-tuning job. + properties: + step: + type: number + train_loss: + type: number + train_mean_token_accuracy: + type: number + valid_loss: + type: number + valid_mean_token_accuracy: + type: number + full_valid_loss: + type: number + full_valid_mean_token_accuracy: + type: number + fine_tuning_job_id: + type: string + description: The name of the fine-tuning job that this checkpoint was created + from. + object: + type: string + description: The object type, which is always "fine_tuning.job.checkpoint". + enum: + - fine_tuning.job.checkpoint + x-stainless-const: true + required: + - created_at + - fine_tuning_job_id + - fine_tuned_model_checkpoint + - id + - metrics + - object + - step_number + x-oaiMeta: + name: The fine-tuning job checkpoint object + example: > + { + "object": "fine_tuning.job.checkpoint", + "id": "ftckpt_qtZ5Gyk4BLq1SfLFWp3RtO3P", + "created_at": 1712211699, + "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom_suffix:9ABel2dg:ckpt-step-88", + "fine_tuning_job_id": "ftjob-fpbNQ3H1GrMehXRf8cO97xTN", + "metrics": { + "step": 88, + "train_loss": 0.478, + "train_mean_token_accuracy": 0.924, + "valid_loss": 10.112, + "valid_mean_token_accuracy": 0.145, + "full_valid_loss": 0.567, + "full_valid_mean_token_accuracy": 0.944 + }, + "step_number": 88 + } + FineTuningJobEvent: + type: object + description: Fine-tuning job event object + properties: + object: + type: string + description: The object type, which is always "fine_tuning.job.event". + enum: + - fine_tuning.job.event + x-stainless-const: true + id: + type: string + description: The object identifier. + created_at: + type: integer + description: The Unix timestamp (in seconds) for when the fine-tuning job was + created. + level: + type: string + description: The log level of the event. + enum: + - info + - warn + - error + message: + type: string + description: The message of the event. + type: + type: string + description: The type of event. + enum: + - message + - metrics + data: + type: object + description: The data associated with the event. + required: + - id + - object + - created_at + - level + - message + x-oaiMeta: + name: The fine-tuning job event object + example: | + { + "object": "fine_tuning.job.event", + "id": "ftevent-abc123" + "created_at": 1677610602, + "level": "info", + "message": "Created fine-tuning job", + "data": {}, + "type": "message" + } + FunctionObject: + type: object + properties: + description: + type: string + description: A description of what the function does, used by the model to + choose when and how to call the function. + name: + type: string + description: The name of the function to be called. Must be a-z, A-Z, 0-9, or + contain underscores and dashes, with a maximum length of 64. + parameters: + $ref: "#/components/schemas/FunctionParameters" + strict: + type: boolean + nullable: true + default: false + description: Whether to enable strict schema adherence when generating the + function call. If set to true, the model will follow the exact + schema defined in the `parameters` field. Only a subset of JSON + Schema is supported when `strict` is `true`. Learn more about + Structured Outputs in the [function calling + guide](docs/guides/function-calling). + required: + - name + FunctionParameters: + type: object + description: >- + The parameters the functions accepts, described as a JSON Schema object. + See the [guide](/docs/guides/function-calling) for examples, and the + [JSON Schema + reference](https://json-schema.org/understanding-json-schema/) for + documentation about the format. + + + Omitting `parameters` defines a function with an empty parameter list. + additionalProperties: true + FunctionTool: + type: object + title: Function + description: > + Defines a function in your own code the model can choose to call. Learn + more + + about [function calling](/docs/guides/function-calling). + properties: + type: + type: string + enum: + - function + description: | + The type of the function tool. Always `function`. + x-stainless-const: true + name: + type: string + description: | + The name of the function to call. + description: + type: string + nullable: true + description: > + A description of the function. Used by the model to determine + whether + + or not to call the function. + parameters: + type: object + description: | + A JSON schema object describing the parameters of the function. + additionalProperties: true + strict: + type: boolean + description: | + Whether to enforce strict parameter validation. Default `true`. + required: + - type + - name + - parameters + - strict + FunctionToolCall: + type: object + title: Function tool call + description: > + A tool call to run a function. See the + + [function calling guide](/docs/guides/function-calling) for more + information. + properties: + 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. + 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 + required: + - id + - type + - call_id + - name + - arguments + FunctionToolCallOutput: + type: object + title: Function tool call output + description: | + The output of a function tool call. + properties: + 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. + output: + type: string + description: | + A JSON string of the output of the function tool 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 + - call_id + - output + FunctionToolCallOutputResource: + allOf: + - $ref: "#/components/schemas/FunctionToolCallOutput" + - type: object + properties: + id: + type: string + description: | + The unique ID of the function call tool output. + required: + - id + Image: + type: object + description: Represents the url or the content of an image generated by the + OpenAI API. + properties: + b64_json: + type: string + description: The base64-encoded JSON of the generated image, if + `response_format` is `b64_json`. + url: + type: string + description: The URL of the generated image, if `response_format` is `url` + (default). + revised_prompt: + type: string + description: The prompt that was used to generate the image, if there was any + revision to the prompt. + x-oaiMeta: + name: The image object + example: | + { + "url": "...", + "revised_prompt": "..." + } + ImagesResponse: + properties: + created: + type: integer + data: + type: array + items: + $ref: "#/components/schemas/Image" + required: + - created + - data + Includable: + type: string + description: > + Specify additional output data to include in the model response. + Currently + + supported values are: + + - `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. + + - `computer_call_output.output.image_url`: Include image urls from the + computer call output. + enum: + - file_search_call.results + - message.input_image.image_url + - computer_call_output.output.image_url + InputAudio: + type: object + title: Audio input + 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 + 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: + - type + - data + - format + InputContent: + oneOf: + - $ref: "#/components/schemas/InputText" + - $ref: "#/components/schemas/InputImage" + - $ref: "#/components/schemas/InputFile" + x-oaiExpandable: true + InputFile: + type: object + title: File input + description: | + A file input to the model. + properties: + type: + type: string + description: | + The type of the input item. Always `input_file`. + enum: + - input_file + x-stainless-const: true + file_id: + type: string + description: | + The ID of the file to be sent to the model. + 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. + required: + - type + InputImage: + type: object + title: Image input + description: > + An image input to the model. Learn about [image + inputs](/docs/guides/vision). + properties: + type: + type: string + description: | + The type of the input item. Always `input_image`. + enum: + - input_image + x-stainless-const: true + image_url: + type: string + description: > + The URL of the image to be sent to the model. A fully qualified URL + or + + base64 encoded image in a data URL. + nullable: true + file_id: + type: string + description: | + The ID of the file to be sent to the model. + nullable: true + detail: + type: string + description: > + The detail level of the image to be sent to the model. One of + `high`, + + `low`, or `auto`. Defaults to `auto`. + enum: + - high + - low + - auto + default: auto + required: + - type + - detail + InputItem: + oneOf: + - $ref: "#/components/schemas/EasyInputMessage" + - 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/Item" + - $ref: "#/components/schemas/ItemReference" + discriminator: + propertyName: type + InputMessage: + 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: + 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/InputMessageContentList" + required: + - role + - content + InputMessageContentList: + type: array + title: Input item content list + description: > + A list of one or many input items to the model, containing different + content + + types. + x-oaiExpandable: true + items: + x-oaiExpandable: true + $ref: "#/components/schemas/InputContent" + InputMessageResource: + allOf: + - $ref: "#/components/schemas/InputMessage" + - type: object + properties: + id: + type: string + description: | + The unique ID of the message input. + required: + - id + InputText: + type: object + title: Text input + description: | + A text input to the model. + properties: + type: + type: string + description: | + The type of the input item. Always `input_text`. + enum: + - input_text + x-stainless-const: true + text: + type: string + description: | + The text input to the model. + required: + - type + - text + Invite: + type: object + description: Represents an individual `invite` to the organization. + properties: + object: + type: string + enum: + - organization.invite + description: The object type, which is always `organization.invite` + x-stainless-const: true + id: + type: string + description: The identifier, which can be referenced in API endpoints + email: + type: string + description: The email address of the individual to whom the invite was sent + role: + type: string + enum: + - owner + - reader + description: "`owner` or `reader`" + status: + type: string + enum: + - accepted + - expired + - pending + description: "`accepted`,`expired`, or `pending`" + invited_at: + type: integer + description: The Unix timestamp (in seconds) of when the invite was sent. + expires_at: + type: integer + description: The Unix timestamp (in seconds) of when the invite expires. + accepted_at: + type: integer + description: The Unix timestamp (in seconds) of when the invite was accepted. + projects: + type: array + description: The projects that were granted membership upon acceptance of the + invite. + items: + type: object + properties: + id: + type: string + description: Project's public ID + role: + type: string + enum: + - member + - owner + description: Project membership role + required: + - object + - id + - email + - role + - status + - invited_at + - expires_at x-oaiMeta: - name: The moderation object + name: The invite object example: | { - "id": "modr-0d9740456c391e43c445bf0f010940c7", - "model": "omni-moderation-latest", - "results": [ + "object": "organization.invite", + "id": "invite-abc", + "email": "user@example.com", + "role": "owner", + "status": "accepted", + "invited_at": 1711471533, + "expires_at": 1711471533, + "accepted_at": 1711471533, + "projects": [ { - "flagged": true, - "categories": { - "harassment": true, - "harassment/threatening": true, - "sexual": false, - "hate": false, - "hate/threatening": false, - "illicit": false, - "illicit/violent": false, - "self-harm/intent": false, - "self-harm/instructions": false, - "self-harm": false, - "sexual/minors": false, - "violence": true, - "violence/graphic": true - }, - "category_scores": { - "harassment": 0.8189693396524255, - "harassment/threatening": 0.804985420696006, - "sexual": 1.573112165348997e-6, - "hate": 0.007562942636942845, - "hate/threatening": 0.004208854591835476, - "illicit": 0.030535955153511665, - "illicit/violent": 0.008925306722380033, - "self-harm/intent": 0.00023023930975076432, - "self-harm/instructions": 0.0002293869201073356, - "self-harm": 0.012598046106750154, - "sexual/minors": 2.212566909570261e-8, - "violence": 0.9999992735124786, - "violence/graphic": 0.843064871157054 - }, - "category_applied_input_types": { - "harassment": [ - "text" - ], - "harassment/threatening": [ - "text" - ], - "sexual": [ - "text", - "image" - ], - "hate": [ - "text" - ], - "hate/threatening": [ - "text" - ], - "illicit": [ - "text" - ], - "illicit/violent": [ - "text" - ], - "self-harm/intent": [ - "text", - "image" - ], - "self-harm/instructions": [ - "text", - "image" - ], - "self-harm": [ - "text", - "image" - ], - "sexual/minors": [ - "text" - ], - "violence": [ - "text", - "image" - ], - "violence/graphic": [ - "text", - "image" - ] - } + "id": "project-xyz", + "role": "member" } ] } - CreateRunRequest: + InviteDeleteResponse: + type: object + properties: + object: + type: string + enum: + - organization.invite.deleted + description: The object type, which is always `organization.invite.deleted` + x-stainless-const: true + id: + type: string + deleted: + type: boolean + required: + - object + - id + - deleted + InviteListResponse: + type: object + properties: + object: + type: string + enum: + - list + description: The object type, which is always `list` + x-stainless-const: true + data: + type: array + items: + $ref: "#/components/schemas/Invite" + first_id: + type: string + description: The first `invite_id` in the retrieved `list` + last_id: + type: string + description: The last `invite_id` in the retrieved `list` + has_more: + type: boolean + description: The `has_more` property is used for pagination to indicate there + are additional results. + required: + - object + - data + InviteRequest: type: object - additionalProperties: false properties: - assistant_id: - description: The ID of the [assistant](/docs/api-reference/assistants) to use to - execute this run. - type: string - model: - description: The ID of the [Model](/docs/api-reference/models) to be used to - execute this run. If a value is provided here, it will override the - model associated with the assistant. If not, the model associated - with the assistant will be used. - example: gpt-4o - anyOf: - - type: string - - $ref: "#/components/schemas/AssistantSupportedModels" - x-oaiTypeLabel: string - nullable: true - reasoning_effort: - $ref: "#/components/schemas/ReasoningEffort" - instructions: - description: Overrides the - [instructions](/docs/api-reference/assistants/createAssistant) of - the assistant. This is useful for modifying the behavior on a - per-run basis. + email: type: string - nullable: true - additional_instructions: - description: Appends additional instructions at the end of the instructions for - the run. This is useful for modifying the behavior on a per-run - basis without overriding other instructions. + description: Send an email to this address + role: type: string - nullable: true - additional_messages: - description: Adds additional messages to the thread before creating the run. + enum: + - reader + - owner + description: "`owner` or `reader`" + projects: type: array + description: An array of projects to which membership is granted at the same + time the org invite is accepted. If omitted, the user will be + invited to the default project for compatibility with legacy + behavior. items: - $ref: "#/components/schemas/CreateMessageRequest" - nullable: true - tools: - description: Override the tools the assistant can use for this run. This is - useful for modifying the behavior on a per-run basis. - nullable: true + type: object + properties: + id: + type: string + description: Project's public ID + role: + type: string + enum: + - member + - owner + description: Project membership role + required: + - id + - role + required: + - email + - role + Item: + type: object + description: | + Content item used to generate a response. + oneOf: + - $ref: "#/components/schemas/InputMessage" + - $ref: "#/components/schemas/OutputMessage" + - $ref: "#/components/schemas/FileSearchToolCall" + - $ref: "#/components/schemas/ComputerToolCall" + - $ref: "#/components/schemas/ComputerToolCallOutput" + - $ref: "#/components/schemas/WebSearchToolCall" + - $ref: "#/components/schemas/FunctionToolCall" + - $ref: "#/components/schemas/FunctionToolCallOutput" + - $ref: "#/components/schemas/ReasoningItem" + x-oaiExpandable: true + discriminator: + propertyName: type + ItemReference: + type: object + title: Item reference + description: | + An internal identifier for an item to reference. + properties: + id: + type: string + description: | + The ID of the item to reference. + type: + type: string + description: | + The type of item to reference. Always `item_reference`. + enum: + - item_reference + x-stainless-const: true + required: + - id + - type + ItemResource: + description: | + Content item used to generate a response. + oneOf: + - $ref: "#/components/schemas/InputMessageResource" + - $ref: "#/components/schemas/OutputMessage" + - $ref: "#/components/schemas/FileSearchToolCall" + - $ref: "#/components/schemas/ComputerToolCall" + - $ref: "#/components/schemas/ComputerToolCallOutputResource" + - $ref: "#/components/schemas/WebSearchToolCall" + - $ref: "#/components/schemas/FunctionToolCall" + - $ref: "#/components/schemas/FunctionToolCallOutputResource" + x-oaiExpandable: true + discriminator: + propertyName: type + KeyPress: + type: object + title: KeyPress + description: | + A collection of keypresses the model would like to perform. + properties: + type: + type: string + enum: + - keypress + default: keypress + description: | + Specifies the event type. For a keypress action, this property is + always set to `keypress`. + x-stainless-const: true + keys: type: array - maxItems: 20 items: - oneOf: - - $ref: "#/components/schemas/AssistantToolsCode" - - $ref: "#/components/schemas/AssistantToolsFileSearch" - - $ref: "#/components/schemas/AssistantToolsFunction" - x-oaiExpandable: true - metadata: - $ref: "#/components/schemas/Metadata" - temperature: - type: number - minimum: 0 - maximum: 2 - default: 1 - example: 1 - nullable: true - 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. - top_p: - type: number - minimum: 0 - maximum: 1 - default: 1 - example: 1 - nullable: true + type: string + description: | + One of the keys the model is requesting to be pressed. 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. - + The combination of keys the model is requesting to be pressed. This + is an - We generally recommend altering this or temperature but not both. - stream: + array of strings, each representing a key. + required: + - type + - keys + ListAssistantsResponse: + type: object + properties: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/AssistantObject" + first_id: + type: string + example: asst_abc123 + last_id: + type: string + example: asst_abc456 + has_more: type: boolean - nullable: true - description: > - If `true`, returns a stream of events that happen during the Run as - server-sent events, terminating when the Run enters a terminal state - with a `data: [DONE]` message. - max_prompt_tokens: - type: integer - nullable: true - description: > - The maximum number of prompt tokens that may be used over the course - of the run. The run will make a best effort to use only the number - of prompt tokens specified, across multiple turns of the run. If the - run exceeds the number of prompt tokens specified, the run will end - with status `incomplete`. See `incomplete_details` for more info. - minimum: 256 - max_completion_tokens: - type: integer - nullable: true - description: > - The maximum number of completion tokens that may be used over the - course of the run. The run will make a best effort to use only the - number of completion tokens specified, across multiple turns of the - run. If the run exceeds the number of completion tokens specified, - the run will end with status `incomplete`. See `incomplete_details` - for more info. - minimum: 256 - truncation_strategy: - allOf: - - $ref: "#/components/schemas/TruncationObject" - - nullable: true - tool_choice: - allOf: - - $ref: "#/components/schemas/AssistantsApiToolChoiceOption" - - nullable: true - parallel_tool_calls: - $ref: "#/components/schemas/ParallelToolCalls" - response_format: - allOf: - - $ref: "#/components/schemas/AssistantsApiResponseFormatOption" - - nullable: true + example: false required: - - assistant_id - CreateSpeechRequest: + - object + - data + - first_id + - last_id + - has_more + x-oaiMeta: + name: List assistants response object + group: chat + example: > + { + "object": "list", + "data": [ + { + "id": "asst_abc123", + "object": "assistant", + "created_at": 1698982736, + "name": "Coding Tutor", + "description": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant designed to make me better at coding!", + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + }, + { + "id": "asst_abc456", + "object": "assistant", + "created_at": 1698982718, + "name": "My Assistant", + "description": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant designed to make me better at coding!", + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + }, + { + "id": "asst_abc789", + "object": "assistant", + "created_at": 1698982643, + "name": null, + "description": null, + "model": "gpt-4o", + "instructions": null, + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + } + ], + "first_id": "asst_abc123", + "last_id": "asst_abc789", + "has_more": false + } + ListAuditLogsResponse: type: object - additionalProperties: false properties: - model: - description: > - One of the available [TTS models](/docs/models#tts): `tts-1` or - `tts-1-hd` - anyOf: - - type: string - - type: string - enum: - - tts-1 - - tts-1-hd - x-oaiTypeLabel: string - input: - type: string - description: The text to generate audio for. The maximum length is 4096 - characters. - maxLength: 4096 - voice: - description: The voice to use when generating the audio. Supported voices are - `alloy`, `ash`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage` and - `shimmer`. Previews of the voices are available in the [Text to - speech guide](/docs/guides/text-to-speech#voice-options). + object: type: string enum: - - alloy - - ash - - coral - - echo - - fable - - onyx - - nova - - sage - - shimmer - response_format: - description: The format to audio in. Supported formats are `mp3`, `opus`, `aac`, - `flac`, `wav`, and `pcm`. - default: mp3 + - list + x-stainless-const: true + data: + type: array + items: + $ref: "#/components/schemas/AuditLog" + first_id: type: string - enum: - - mp3 - - opus - - aac - - flac - - wav - - pcm - speed: - description: The speed of the generated audio. Select a value from `0.25` to - `4.0`. `1.0` is the default. - type: number - default: 1 - minimum: 0.25 - maximum: 4 + example: audit_log-defb456h8dks + last_id: + type: string + example: audit_log-hnbkd8s93s + has_more: + type: boolean required: - - model - - input - - voice - CreateThreadAndRunRequest: + - object + - data + - first_id + - last_id + - has_more + ListBatchesResponse: type: object - additionalProperties: false properties: - assistant_id: - description: The ID of the [assistant](/docs/api-reference/assistants) to use to - execute this run. - type: string - thread: - $ref: "#/components/schemas/CreateThreadRequest" - model: - description: The ID of the [Model](/docs/api-reference/models) to be used to - execute this run. If a value is provided here, it will override the - model associated with the assistant. If not, the model associated - with the assistant will be used. - example: gpt-4o - anyOf: - - type: string - - type: string - enum: - - gpt-4o - - gpt-4o-2024-11-20 - - gpt-4o-2024-08-06 - - gpt-4o-2024-05-13 - - gpt-4o-mini - - gpt-4o-mini-2024-07-18 - - gpt-4-turbo - - gpt-4-turbo-2024-04-09 - - gpt-4-0125-preview - - gpt-4-turbo-preview - - gpt-4-1106-preview - - gpt-4-vision-preview - - gpt-4 - - gpt-4-0314 - - gpt-4-0613 - - gpt-4-32k - - gpt-4-32k-0314 - - gpt-4-32k-0613 - - gpt-3.5-turbo - - gpt-3.5-turbo-16k - - gpt-3.5-turbo-0613 - - gpt-3.5-turbo-1106 - - gpt-3.5-turbo-0125 - - gpt-3.5-turbo-16k-0613 - x-oaiTypeLabel: string - nullable: true - instructions: - description: Override the default system message of the assistant. This is - useful for modifying the behavior on a per-run basis. - type: string - nullable: true - tools: - description: Override the tools the assistant can use for this run. This is - useful for modifying the behavior on a per-run basis. - nullable: true + data: type: array - maxItems: 20 items: - oneOf: - - $ref: "#/components/schemas/AssistantToolsCode" - - $ref: "#/components/schemas/AssistantToolsFileSearch" - - $ref: "#/components/schemas/AssistantToolsFunction" - tool_resources: - type: object - description: > - A set of resources that are used by the assistant's tools. The - resources are specific to the type of tool. For example, the - `code_interpreter` tool requires a list of file IDs, while the - `file_search` tool requires a list of vector store IDs. - properties: - code_interpreter: - type: object - properties: - file_ids: - type: array - description: > - A list of [file](/docs/api-reference/files) IDs made - available to the `code_interpreter` tool. There can be a - maximum of 20 files associated with the tool. - default: [] - maxItems: 20 - items: - type: string - file_search: - type: object - properties: - vector_store_ids: - type: array - description: > - The ID of the [vector - store](/docs/api-reference/vector-stores/object) attached to - this assistant. There can be a maximum of 1 vector store - attached to the assistant. - maxItems: 1 - items: - type: string - nullable: true - metadata: - $ref: "#/components/schemas/Metadata" - temperature: - type: number - minimum: 0 - maximum: 2 - default: 1 - example: 1 - nullable: true - 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. - top_p: - type: number - minimum: 0 - maximum: 1 - default: 1 - example: 1 - nullable: true - 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. - stream: - type: boolean - nullable: true - description: > - If `true`, returns a stream of events that happen during the Run as - server-sent events, terminating when the Run enters a terminal state - with a `data: [DONE]` message. - max_prompt_tokens: - type: integer - nullable: true - description: > - The maximum number of prompt tokens that may be used over the course - of the run. The run will make a best effort to use only the number - of prompt tokens specified, across multiple turns of the run. If the - run exceeds the number of prompt tokens specified, the run will end - with status `incomplete`. See `incomplete_details` for more info. - minimum: 256 - max_completion_tokens: - type: integer - nullable: true - description: > - The maximum number of completion tokens that may be used over the - course of the run. The run will make a best effort to use only the - number of completion tokens specified, across multiple turns of the - run. If the run exceeds the number of completion tokens specified, - the run will end with status `incomplete`. See `incomplete_details` - for more info. - minimum: 256 - truncation_strategy: - allOf: - - $ref: "#/components/schemas/TruncationObject" - - nullable: true - tool_choice: - allOf: - - $ref: "#/components/schemas/AssistantsApiToolChoiceOption" - - nullable: true - parallel_tool_calls: - $ref: "#/components/schemas/ParallelToolCalls" - response_format: - allOf: - - $ref: "#/components/schemas/AssistantsApiResponseFormatOption" - - nullable: true + $ref: "#/components/schemas/Batch" + first_id: + type: string + example: batch_abc123 + last_id: + type: string + example: batch_abc456 + has_more: + type: boolean + object: + type: string + enum: + - list + x-stainless-const: true required: - - assistant_id - CreateThreadRequest: + - object + - data + - has_more + ListFilesResponse: type: object - description: | - Options to create a new thread. If no thread is provided when running a - request, an empty thread will be created. - additionalProperties: false properties: - messages: - description: A list of [messages](/docs/api-reference/messages) to start the - thread with. + object: + type: string + example: list + data: type: array items: - $ref: "#/components/schemas/CreateMessageRequest" - tool_resources: - type: object - description: > - A set of resources that are made available to the assistant's tools - in this thread. The resources are specific to the type of tool. For - example, the `code_interpreter` tool requires a list of file IDs, - while the `file_search` tool requires a list of vector store IDs. - properties: - code_interpreter: - type: object - properties: - file_ids: - type: array - description: > - A list of [file](/docs/api-reference/files) IDs made - available to the `code_interpreter` tool. There can be a - maximum of 20 files associated with the tool. - default: [] - maxItems: 20 - items: - type: string - file_search: - type: object - properties: - vector_store_ids: - type: array - description: > - The [vector store](/docs/api-reference/vector-stores/object) - attached to this thread. There can be a maximum of 1 vector - store attached to the thread. - maxItems: 1 - items: - type: string - vector_stores: - type: array - description: > - A helper to create a [vector - store](/docs/api-reference/vector-stores/object) with - file_ids and attach it to this thread. There can be a - maximum of 1 vector store attached to the thread. - maxItems: 1 - items: - type: object - properties: - file_ids: - type: array - description: > - A list of [file](/docs/api-reference/files) IDs to add - to the vector store. There can be a maximum of 10000 - files in a vector store. - maxItems: 10000 - items: - type: string - chunking_strategy: - type: object - description: The chunking strategy used to chunk the file(s). If not set, will - use the `auto` strategy. - oneOf: - - type: object - title: Auto Chunking Strategy - description: The default strategy. This strategy currently uses a - `max_chunk_size_tokens` of `800` and - `chunk_overlap_tokens` of `400`. - additionalProperties: false - properties: - type: - type: string - description: Always `auto`. - enum: - - auto - x-stainless-const: true - required: - - type - - type: object - title: Static Chunking Strategy - additionalProperties: false - properties: - type: - type: string - description: Always `static`. - enum: - - static - x-stainless-const: true - static: - type: object - additionalProperties: false - properties: - max_chunk_size_tokens: - type: integer - minimum: 100 - maximum: 4096 - description: The maximum number of tokens in each chunk. The default value is - `800`. The minimum value is `100` and the - maximum value is `4096`. - chunk_overlap_tokens: - type: integer - description: > - The number of tokens that overlap between - chunks. The default value is `400`. - - - Note that the overlap must not exceed half - of `max_chunk_size_tokens`. - required: - - max_chunk_size_tokens - - chunk_overlap_tokens - required: - - type - - static - x-oaiExpandable: true - metadata: - $ref: "#/components/schemas/Metadata" - x-oaiExpandable: true - oneOf: - - required: - - vector_store_ids - - required: - - vector_stores + $ref: "#/components/schemas/OpenAIFile" + first_id: + type: string + example: file-abc123 + last_id: + type: string + example: file-abc456 + has_more: + type: boolean + example: false + required: + - object + - data + - first_id + - last_id + - has_more + ListFineTuningJobCheckpointsResponse: + type: object + properties: + data: + type: array + items: + $ref: "#/components/schemas/FineTuningJobCheckpoint" + object: + type: string + enum: + - list + x-stainless-const: true + first_id: + type: string nullable: true - metadata: - $ref: "#/components/schemas/Metadata" - CreateTranscriptionRequest: + last_id: + type: string + nullable: true + has_more: + type: boolean + required: + - object + - data + - has_more + ListFineTuningJobEventsResponse: type: object - additionalProperties: false properties: - file: - description: > - The audio file object (not file name) to transcribe, in one of these - formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. + data: + type: array + items: + $ref: "#/components/schemas/FineTuningJobEvent" + object: type: string - x-oaiTypeLabel: file - format: binary - model: - description: > - ID of the model to use. Only `whisper-1` (which is powered by our - open source Whisper V2 model) is currently available. - example: whisper-1 - anyOf: - - type: string - - type: string - enum: - - whisper-1 - x-stainless-const: true - x-oaiTypeLabel: string - language: - description: > - The language of the input audio. Supplying the input language in - [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) - (e.g. `en`) format will improve accuracy and latency. + enum: + - list + x-stainless-const: true + has_more: + type: boolean + required: + - object + - data + - has_more + ListMessagesResponse: + properties: + object: type: string - prompt: - description: > - An optional text to guide the model's style or continue a previous - audio segment. The [prompt](/docs/guides/speech-to-text#prompting) - should match the audio language. + example: list + data: + type: array + items: + $ref: "#/components/schemas/MessageObject" + first_id: + type: string + example: msg_abc123 + last_id: + type: string + example: msg_abc123 + has_more: + type: boolean + example: false + required: + - object + - data + - first_id + - last_id + - has_more + ListModelsResponse: + type: object + properties: + object: type: string - response_format: - $ref: "#/components/schemas/AudioResponseFormat" - temperature: - description: > - The sampling temperature, between 0 and 1. Higher values like 0.8 - will make the output more random, while lower values like 0.2 will - make it more focused and deterministic. If set to 0, the model will - use [log probability](https://en.wikipedia.org/wiki/Log_probability) - to automatically increase the temperature until certain thresholds - are hit. - type: number - default: 0 - timestamp_granularities[]: - description: > - The timestamp granularities to populate for this transcription. - `response_format` must be set `verbose_json` to use timestamp - granularities. Either or both of these options are supported: - `word`, or `segment`. Note: There is no additional latency for - segment timestamps, but generating word timestamps incurs additional - latency. + enum: + - list + x-stainless-const: true + data: type: array items: - type: string - enum: - - word - - segment - default: - - segment + $ref: "#/components/schemas/Model" required: - - file - - model - CreateTranscriptionResponseJson: + - object + - data + ListPaginatedFineTuningJobsResponse: type: object - description: Represents a transcription response returned by model, based on the - provided input. properties: - text: + data: + type: array + items: + $ref: "#/components/schemas/FineTuningJob" + has_more: + type: boolean + object: type: string - description: The transcribed text. + enum: + - list + x-stainless-const: true required: - - text - x-oaiMeta: - name: The transcription object (JSON) - group: audio - example: > - { - "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that." - } - CreateTranscriptionResponseVerboseJson: - type: object - description: Represents a verbose json transcription response returned by model, - based on the provided input. + - object + - data + - has_more + ListRunStepsResponse: properties: - language: + object: type: string - description: The language of the input audio. - duration: - type: number - description: The duration of the input audio. - text: + example: list + data: + type: array + items: + $ref: "#/components/schemas/RunStepObject" + first_id: type: string - description: The transcribed text. - words: + example: step_abc123 + last_id: + type: string + example: step_abc456 + has_more: + type: boolean + example: false + required: + - object + - data + - first_id + - last_id + - has_more + ListRunsResponse: + type: object + properties: + object: + type: string + example: list + data: type: array - description: Extracted words and their corresponding timestamps. items: - $ref: "#/components/schemas/TranscriptionWord" - segments: + $ref: "#/components/schemas/RunObject" + first_id: + type: string + example: run_abc123 + last_id: + type: string + example: run_abc456 + has_more: + type: boolean + example: false + required: + - object + - data + - first_id + - last_id + - has_more + ListThreadsResponse: + properties: + object: + type: string + example: list + data: type: array - description: Segments of the transcribed text and their corresponding details. items: - $ref: "#/components/schemas/TranscriptionSegment" + $ref: "#/components/schemas/ThreadObject" + first_id: + type: string + example: asst_abc123 + last_id: + type: string + example: asst_abc456 + has_more: + type: boolean + example: false required: - - language - - duration - - text - x-oaiMeta: - name: The transcription object (Verbose JSON) - group: audio - example: > - { - "task": "transcribe", - "language": "english", - "duration": 8.470000267028809, - "text": "The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.", - "segments": [ - { - "id": 0, - "seek": 0, - "start": 0.0, - "end": 3.319999933242798, - "text": " The beach was a popular spot on a hot summer day.", - "tokens": [ - 50364, 440, 7534, 390, 257, 3743, 4008, 322, 257, 2368, 4266, 786, 13, 50530 - ], - "temperature": 0.0, - "avg_logprob": -0.2860786020755768, - "compression_ratio": 1.2363636493682861, - "no_speech_prob": 0.00985979475080967 - }, - ... - ] - } - CreateTranslationRequest: - type: object - additionalProperties: false + - object + - data + - first_id + - last_id + - has_more + ListVectorStoreFilesResponse: properties: - file: - description: > - The audio file object (not file name) translate, in one of these - formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. + object: type: string - x-oaiTypeLabel: file - format: binary - model: - description: > - ID of the model to use. Only `whisper-1` (which is powered by our - open source Whisper V2 model) is currently available. - example: whisper-1 - anyOf: - - type: string - - type: string - enum: - - whisper-1 - x-stainless-const: true - x-oaiTypeLabel: string - prompt: - description: > - An optional text to guide the model's style or continue a previous - audio segment. The [prompt](/docs/guides/speech-to-text#prompting) - should be in English. + example: list + data: + type: array + items: + $ref: "#/components/schemas/VectorStoreFileObject" + first_id: type: string - response_format: - $ref: "#/components/schemas/AudioResponseFormat" - temperature: - description: > - The sampling temperature, between 0 and 1. Higher values like 0.8 - will make the output more random, while lower values like 0.2 will - make it more focused and deterministic. If set to 0, the model will - use [log probability](https://en.wikipedia.org/wiki/Log_probability) - to automatically increase the temperature until certain thresholds - are hit. - type: number - default: 0 + example: file-abc123 + last_id: + type: string + example: file-abc456 + has_more: + type: boolean + example: false required: - - file - - model - CreateTranslationResponseJson: - type: object + - object + - data + - first_id + - last_id + - has_more + ListVectorStoresResponse: properties: - text: + object: + type: string + example: list + data: + type: array + items: + $ref: "#/components/schemas/VectorStoreObject" + first_id: + type: string + example: vs_abc123 + last_id: type: string + example: vs_abc456 + has_more: + type: boolean + example: false required: - - text - CreateTranslationResponseVerboseJson: + - object + - data + - first_id + - last_id + - has_more + LogProb: + allOf: + - $ref: "#/components/schemas/LogProbProperties" + - type: object + properties: + top_logprobs: + type: array + items: + $ref: "#/components/schemas/LogProbProperties" + nullable: true + LogProbProperties: type: object + description: | + A log probability object. properties: - language: + token: type: string - description: The language of the output translation (always `english`). - duration: + description: | + The token that was used to generate the log probability. + logprob: type: number - description: The duration of the input audio. - text: - type: string - description: The translated text. - segments: + description: | + The log probability of the token. + bytes: type: array - description: Segments of the translated text and their corresponding details. items: - $ref: "#/components/schemas/TranscriptionSegment" + type: integer + description: | + The bytes that were used to generate the log probability. required: - - language - - duration - - text - CreateUploadRequest: + - token + - logprob + - bytes + MessageContentImageFileObject: + title: Image file type: object - additionalProperties: false + description: References an image [File](/docs/api-reference/files) in the + content of a message. properties: - filename: - description: | - The name of the file to upload. - type: string - purpose: - description: > - The intended purpose of the uploaded file. - - - See the [documentation on File - purposes](/docs/api-reference/files/create#files-create-purpose). + type: + description: Always `image_file`. type: string enum: - - assistants - - batch - - fine-tune - - vision - bytes: - description: | - The number of bytes in the file you are uploading. - type: integer - mime_type: - description: > - The MIME type of the file. - - - This must fall within the supported MIME types for your file - purpose. See the supported MIME types for assistants and vision. - type: string + - image_file + x-stainless-const: true + image_file: + type: object + properties: + file_id: + description: The [File](/docs/api-reference/files) ID of the image in the + message content. Set `purpose="vision"` when uploading the File + if you need to later display the file content. + type: string + detail: + type: string + description: Specifies the detail level of the image if specified by the user. + `low` uses fewer tokens, you can opt in to high resolution using + `high`. + enum: + - auto + - low + - high + default: auto + required: + - file_id required: - - filename - - purpose - - bytes - - mime_type - CreateVectorStoreFileBatchRequest: + - type + - image_file + MessageContentImageUrlObject: + title: Image URL type: object - additionalProperties: false + description: References an image URL in the content of a message. properties: - file_ids: - description: A list of [File](/docs/api-reference/files) IDs that the vector - store should use. Useful for tools like `file_search` that can - access files. - type: array - minItems: 1 - maxItems: 500 - items: - type: string - chunking_strategy: - $ref: "#/components/schemas/ChunkingStrategyRequestParam" + type: + type: string + enum: + - image_url + description: The type of the content part. + x-stainless-const: true + image_url: + type: object + properties: + url: + type: string + description: "The external URL of the image, must be a supported image types: + jpeg, jpg, png, gif, webp." + format: uri + detail: + type: string + description: Specifies the detail level of the image. `low` uses fewer tokens, + you can opt in to high resolution using `high`. Default value is + `auto` + enum: + - auto + - low + - high + default: auto + required: + - url required: - - file_ids - CreateVectorStoreFileRequest: + - type + - image_url + MessageContentRefusalObject: + title: Refusal type: object - additionalProperties: false + description: The refusal content generated by the assistant. properties: - file_id: - description: A [File](/docs/api-reference/files) ID that the vector store should - use. Useful for tools like `file_search` that can access files. + type: + description: Always `refusal`. type: string - chunking_strategy: - $ref: "#/components/schemas/ChunkingStrategyRequestParam" + enum: + - refusal + x-stainless-const: true + refusal: + type: string + nullable: false required: - - file_id - CreateVectorStoreRequest: + - type + - refusal + MessageContentTextAnnotationsFileCitationObject: + title: File citation type: object - additionalProperties: false + description: A citation within the message that points to a specific quote from + a specific File associated with the assistant or the message. Generated + when the assistant uses the "file_search" tool to search files. properties: - file_ids: - description: A list of [File](/docs/api-reference/files) IDs that the vector - store should use. Useful for tools like `file_search` that can - access files. - type: array - maxItems: 500 - items: - type: string - name: - description: The name of the vector store. + type: + description: Always `file_citation`. type: string - expires_after: - $ref: "#/components/schemas/VectorStoreExpirationAfter" - chunking_strategy: + enum: + - file_citation + x-stainless-const: true + text: + description: The text in the message content that needs to be replaced. + type: string + file_citation: type: object - description: The chunking strategy used to chunk the file(s). If not set, will - use the `auto` strategy. Only applicable if `file_ids` is non-empty. - oneOf: - - $ref: "#/components/schemas/AutoChunkingStrategyRequestParam" - - $ref: "#/components/schemas/StaticChunkingStrategyRequestParam" - x-oaiExpandable: true - metadata: - $ref: "#/components/schemas/Metadata" - DefaultProjectErrorResponse: - type: object - properties: - code: + properties: + file_id: + description: The ID of the specific File the citation is from. + type: string + required: + - file_id + start_index: type: integer - message: - type: string + minimum: 0 + end_index: + type: integer + minimum: 0 required: - - code - - message - DeleteAssistantResponse: + - type + - text + - file_citation + - start_index + - end_index + MessageContentTextAnnotationsFilePathObject: + title: File path type: object + description: A URL for the file that's generated when the assistant used the + `code_interpreter` tool to generate a file. properties: - id: - type: string - deleted: - type: boolean - object: + type: + description: Always `file_path`. type: string enum: - - assistant.deleted + - file_path x-stainless-const: true - required: - - id - - object - - deleted - DeleteFileResponse: + text: + description: The text in the message content that needs to be replaced. + type: string + file_path: + type: object + properties: + file_id: + description: The ID of the file that was generated. + type: string + required: + - file_id + start_index: + type: integer + minimum: 0 + end_index: + type: integer + minimum: 0 + required: + - type + - text + - file_path + - start_index + - end_index + MessageContentTextObject: + title: Text type: object + description: The text content that is part of a message. properties: - id: - type: string - object: + type: + description: Always `text`. type: string enum: - - file + - text x-stainless-const: true - deleted: - type: boolean + text: + type: object + properties: + value: + description: The data that makes up the text. + type: string + annotations: + type: array + items: + oneOf: + - $ref: "#/components/schemas/MessageContentTextAnnotationsFileCitationObject" + - $ref: "#/components/schemas/MessageContentTextAnnotationsFilePathObject" + x-oaiExpandable: true + required: + - value + - annotations required: - - id - - object - - deleted - DeleteMessageResponse: + - type + - text + MessageDeltaContentImageFileObject: + title: Image file type: object + description: References an image [File](/docs/api-reference/files) in the + content of a message. properties: - id: - type: string - deleted: - type: boolean - object: + index: + type: integer + description: The index of the content part in the message. + type: + description: Always `image_file`. type: string enum: - - thread.message.deleted + - image_file x-stainless-const: true + image_file: + type: object + properties: + file_id: + description: The [File](/docs/api-reference/files) ID of the image in the + message content. Set `purpose="vision"` when uploading the File + if you need to later display the file content. + type: string + detail: + type: string + description: Specifies the detail level of the image if specified by the user. + `low` uses fewer tokens, you can opt in to high resolution using + `high`. + enum: + - auto + - low + - high + default: auto required: - - id - - object - - deleted - DeleteModelResponse: + - index + - type + MessageDeltaContentImageUrlObject: + title: Image URL type: object + description: References an image URL in the content of a message. properties: - id: - type: string - deleted: - type: boolean - object: + index: + type: integer + description: The index of the content part in the message. + type: + description: Always `image_url`. type: string + enum: + - image_url + x-stainless-const: true + image_url: + type: object + properties: + url: + description: "The URL of the image, must be a supported image types: jpeg, jpg, + png, gif, webp." + type: string + detail: + type: string + description: Specifies the detail level of the image. `low` uses fewer tokens, + you can opt in to high resolution using `high`. + enum: + - auto + - low + - high + default: auto required: - - id - - object - - deleted - DeleteThreadResponse: + - index + - type + MessageDeltaContentRefusalObject: + title: Refusal type: object + description: The refusal content that is part of a message. properties: - id: - type: string - deleted: - type: boolean - object: + index: + type: integer + description: The index of the refusal part in the message. + type: + description: Always `refusal`. type: string enum: - - thread.deleted + - refusal x-stainless-const: true + refusal: + type: string required: - - id - - object - - deleted - DeleteVectorStoreFileResponse: + - index + - type + MessageDeltaContentTextAnnotationsFileCitationObject: + title: File citation type: object + description: A citation within the message that points to a specific quote from + a specific File associated with the assistant or the message. Generated + when the assistant uses the "file_search" tool to search files. properties: - id: - type: string - deleted: - type: boolean - object: + index: + type: integer + description: The index of the annotation in the text content part. + type: + description: Always `file_citation`. type: string enum: - - vector_store.file.deleted + - file_citation x-stainless-const: true + text: + description: The text in the message content that needs to be replaced. + type: string + file_citation: + type: object + properties: + file_id: + description: The ID of the specific File the citation is from. + type: string + quote: + description: The specific quote in the file. + type: string + start_index: + type: integer + minimum: 0 + end_index: + type: integer + minimum: 0 required: - - id - - object - - deleted - DeleteVectorStoreResponse: + - index + - type + MessageDeltaContentTextAnnotationsFilePathObject: + title: File path type: object + description: A URL for the file that's generated when the assistant used the + `code_interpreter` tool to generate a file. properties: - id: - type: string - deleted: - type: boolean - object: + index: + type: integer + description: The index of the annotation in the text content part. + type: + description: Always `file_path`. type: string enum: - - vector_store.deleted + - file_path x-stainless-const: true + text: + description: The text in the message content that needs to be replaced. + type: string + file_path: + type: object + properties: + file_id: + description: The ID of the file that was generated. + type: string + start_index: + type: integer + minimum: 0 + end_index: + type: integer + minimum: 0 required: - - id - - object - - deleted - DoneEvent: + - index + - type + MessageDeltaContentTextObject: + title: Text type: object + description: The text content that is part of a message. properties: - event: - type: string - enum: - - done - x-stainless-const: true - data: + index: + type: integer + description: The index of the content part in the message. + type: + description: Always `text`. type: string enum: - - "[DONE]" + - text x-stainless-const: true - required: - - event - - data - description: Occurs when a stream ends. - x-oaiMeta: - dataDescription: "`data` is `[DONE]`" - Embedding: + text: + type: object + properties: + value: + description: The data that makes up the text. + type: string + annotations: + type: array + items: + oneOf: + - $ref: "#/components/schemas/MessageDeltaContentTextAnnotationsFileCitationObjec\ + t" + - $ref: "#/components/schemas/MessageDeltaContentTextAnnotationsFilePathObject" + x-oaiExpandable: true + required: + - index + - type + MessageDeltaObject: type: object - description: | - Represents an embedding vector returned by embedding endpoint. + title: Message delta object + description: > + Represents a message delta i.e. any changed fields on a message during + streaming. properties: - index: - type: integer - description: The index of the embedding in the list of embeddings. - embedding: - type: array - description: > - The embedding vector, which is a list of floats. The length of - vector depends on the model as listed in the [embedding - guide](/docs/guides/embeddings). - items: - type: number + id: + description: The identifier of the message, which can be referenced in API + endpoints. + type: string object: + description: The object type, which is always `thread.message.delta`. type: string - description: The object type, which is always "embedding". enum: - - embedding + - thread.message.delta x-stainless-const: true + delta: + description: The delta containing the fields that have changed on the Message. + type: object + properties: + role: + description: The entity that produced the message. One of `user` or `assistant`. + type: string + enum: + - user + - assistant + content: + description: The content of the message in array of text and/or images. + type: array + items: + oneOf: + - $ref: "#/components/schemas/MessageDeltaContentImageFileObject" + - $ref: "#/components/schemas/MessageDeltaContentTextObject" + - $ref: "#/components/schemas/MessageDeltaContentRefusalObject" + - $ref: "#/components/schemas/MessageDeltaContentImageUrlObject" + x-oaiExpandable: true required: - - index + - id - object - - embedding + - delta x-oaiMeta: - name: The embedding object + name: The message delta object + beta: true example: | { - "object": "embedding", - "embedding": [ - 0.0023064255, - -0.009327292, - .... (1536 floats total for ada-002) - -0.0028842222, - ], - "index": 0 + "id": "msg_123", + "object": "thread.message.delta", + "delta": { + "content": [ + { + "index": 0, + "type": "text", + "text": { "value": "Hello", "annotations": [] } + } + ] + } } - Error: + MessageObject: type: object + title: The message object + description: Represents a message within a [thread](/docs/api-reference/threads). properties: - code: - type: string - nullable: true - message: - type: string - nullable: false - param: - type: string - nullable: true - type: + id: + description: The identifier, which can be referenced in API endpoints. type: string - nullable: false - required: - - type - - message - - param - - code - ErrorEvent: - type: object - properties: - event: + object: + description: The object type, which is always `thread.message`. type: string enum: - - error + - thread.message x-stainless-const: true - data: - $ref: "#/components/schemas/Error" - required: - - event - - data - description: Occurs when an [error](/docs/guides/error-codes#api-errors) occurs. - This can happen due to an internal server error or a timeout. - x-oaiMeta: - dataDescription: "`data` is an [error](/docs/guides/error-codes#api-errors)" - ErrorResponse: - type: object - properties: - error: - $ref: "#/components/schemas/Error" - required: - - error - FileSearchRankingOptions: - title: File search tool call ranking options - type: object - description: > - The ranking options for the file search. If not specified, the file - search tool will use the `auto` ranker and a score_threshold of 0. - - - See the [file search tool - documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) - for more information. - properties: - ranker: + created_at: + description: The Unix timestamp (in seconds) for when the message was created. + type: integer + thread_id: + description: The [thread](/docs/api-reference/threads) ID that this message + belongs to. + type: string + status: + description: The status of the message, which can be either `in_progress`, + `incomplete`, or `completed`. type: string - description: The ranker to use for the file search. If not specified will use - the `auto` ranker. enum: - - auto - - default_2024_08_21 - score_threshold: - type: number - description: The score threshold for the file search. All values must be a - floating point number between 0 and 1. - minimum: 0 - maximum: 1 - required: - - score_threshold - FineTuneChatCompletionRequestAssistantMessage: - allOf: - - type: object - title: Assistant message - deprecated: false + - in_progress + - incomplete + - completed + incomplete_details: + description: On an incomplete message, details about why the message is + incomplete. + type: object properties: - weight: - type: integer + reason: + type: string + description: The reason the message is incomplete. enum: - - 0 - - 1 - description: Controls whether the assistant message is trained against (0 or 1) - - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" - required: - - role - FineTuneChatRequestInput: - type: object - description: The per-line training example of a fine-tuning input file for chat - models using the supervised method. - properties: - messages: + - content_filter + - max_tokens + - run_cancelled + - run_expired + - run_failed + nullable: true + required: + - reason + completed_at: + description: The Unix timestamp (in seconds) for when the message was completed. + type: integer + nullable: true + incomplete_at: + description: The Unix timestamp (in seconds) for when the message was marked as + incomplete. + type: integer + nullable: true + role: + description: The entity that produced the message. One of `user` or `assistant`. + type: string + enum: + - user + - assistant + content: + description: The content of the message in array of text and/or images. type: array - minItems: 1 items: oneOf: - - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" - - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" - - $ref: "#/components/schemas/FineTuneChatCompletionRequestAssistantMessage" - - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" - - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" + - $ref: "#/components/schemas/MessageContentImageFileObject" + - $ref: "#/components/schemas/MessageContentImageUrlObject" + - $ref: "#/components/schemas/MessageContentTextObject" + - $ref: "#/components/schemas/MessageContentRefusalObject" x-oaiExpandable: true - tools: - type: array - description: A list of tools the model may generate JSON inputs for. - items: - $ref: "#/components/schemas/ChatCompletionTool" - parallel_tool_calls: - $ref: "#/components/schemas/ParallelToolCalls" - functions: - deprecated: true - description: A list of functions the model may generate JSON inputs for. + assistant_id: + description: If applicable, the ID of the + [assistant](/docs/api-reference/assistants) that authored this + message. + type: string + nullable: true + run_id: + description: The ID of the [run](/docs/api-reference/runs) associated with the + creation of this message. Value is `null` when messages are created + manually using the create message or create thread endpoints. + type: string + nullable: true + attachments: type: array - minItems: 1 - maxItems: 128 items: - $ref: "#/components/schemas/ChatCompletionFunctions" + type: object + properties: + file_id: + type: string + description: The ID of the file to attach to the message. + tools: + description: The tools to add this file to. + type: array + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearchTypeOnly" + x-oaiExpandable: true + description: A list of files attached to the message, and the tools they were + added to. + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + required: + - id + - object + - created_at + - thread_id + - status + - incomplete_details + - completed_at + - incomplete_at + - role + - content + - assistant_id + - run_id + - attachments + - metadata x-oaiMeta: - name: Training format for chat models using the supervised method - example: > + name: The message object + beta: true + example: | { - "messages": [ - { "role": "user", "content": "What is the weather in San Francisco?" }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "call_id", - "type": "function", - "function": { - "name": "get_current_weather", - "arguments": "{\"location\": \"San Francisco, USA\", \"format\": \"celsius\"}" - } - } - ] - } - ], - "parallel_tool_calls": false, - "tools": [ + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1698983503, + "thread_id": "thread_abc123", + "role": "assistant", + "content": [ { - "type": "function", - "function": { - "name": "get_current_weather", - "description": "Get the current weather", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and country, eg. San Francisco, USA" - }, - "format": { "type": "string", "enum": ["celsius", "fahrenheit"] } - }, - "required": ["location", "format"] - } + "type": "text", + "text": { + "value": "Hi! How can I help you today?", + "annotations": [] } } - ] + ], + "assistant_id": "asst_abc123", + "run_id": "run_abc123", + "attachments": [], + "metadata": {} } - FineTuneCompletionRequestInput: + MessageRequestContentTextObject: + title: Text type: object - description: The per-line training example of a fine-tuning input file for - completions models + description: The text content that is part of a message. properties: - prompt: + type: + description: Always `text`. type: string - description: The input prompt for this training example. - completion: + enum: + - text + x-stainless-const: true + text: type: string - description: The desired completion for this training example. - x-oaiMeta: - name: Training format for completions models - example: | - { - "prompt": "What is the answer to 2+2", - "completion": "4" - } - FineTuneDPOMethod: - type: object - description: Configuration for the DPO fine-tuning method. - properties: - hyperparameters: - type: object - description: The hyperparameters used for the fine-tuning job. + description: Text content to be sent to the model + required: + - type + - text + MessageStreamEvent: + oneOf: + - type: object properties: - beta: - description: > - The beta value for the DPO method. A higher beta value will - increase the weight of the penalty between the policy and - reference model. - oneOf: - - type: string - enum: - - auto - x-stainless-const: true - - type: number - minimum: 0 - maximum: 2 - exclusiveMinimum: true - default: auto - batch_size: - description: > - Number of examples in each batch. A larger batch size means that - model parameters are updated less frequently, but with lower - variance. - oneOf: - - type: string - enum: - - auto - x-stainless-const: true - - type: integer - minimum: 1 - maximum: 256 - default: auto - learning_rate_multiplier: - description: > - Scaling factor for the learning rate. A smaller learning rate - may be useful to avoid overfitting. - oneOf: - - type: string - enum: - - auto - x-stainless-const: true - - type: number - minimum: 0 - exclusiveMinimum: true - default: auto - n_epochs: - description: > - The number of epochs to train the model for. An epoch refers to - one full cycle through the training dataset. - oneOf: - - type: string - enum: - - auto - x-stainless-const: true - - type: integer - minimum: 1 - maximum: 50 - default: auto - FineTuneMethod: + event: + type: string + enum: + - thread.message.created + x-stainless-const: true + data: + $ref: "#/components/schemas/MessageObject" + required: + - event + - data + description: Occurs when a [message](/docs/api-reference/messages/object) is + created. + x-oaiMeta: + dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" + - type: object + properties: + event: + type: string + enum: + - thread.message.in_progress + x-stainless-const: true + data: + $ref: "#/components/schemas/MessageObject" + required: + - event + - data + description: Occurs when a [message](/docs/api-reference/messages/object) moves + to an `in_progress` state. + x-oaiMeta: + dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" + - type: object + properties: + event: + type: string + enum: + - thread.message.delta + x-stainless-const: true + data: + $ref: "#/components/schemas/MessageDeltaObject" + required: + - event + - data + description: Occurs when parts of a + [Message](/docs/api-reference/messages/object) are being streamed. + x-oaiMeta: + dataDescription: "`data` is a [message + delta](/docs/api-reference/assistants-streaming/message-delta-obj\ + ect)" + - type: object + properties: + event: + type: string + enum: + - thread.message.completed + x-stainless-const: true + data: + $ref: "#/components/schemas/MessageObject" + required: + - event + - data + description: Occurs when a [message](/docs/api-reference/messages/object) is + completed. + x-oaiMeta: + dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" + - type: object + properties: + event: + type: string + enum: + - thread.message.incomplete + x-stainless-const: true + data: + $ref: "#/components/schemas/MessageObject" + required: + - event + - data + description: Occurs when a [message](/docs/api-reference/messages/object) ends + before it is completed. + x-oaiMeta: + dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" + Metadata: type: object - description: The method used for fine-tuning. + 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 + nullable: true + Model: + title: Model + description: Describes an OpenAI model offering that can be used with the API. properties: - type: + id: type: string - description: The type of method. Is either `supervised` or `dpo`. + description: The model identifier, which can be referenced in the API endpoints. + created: + type: integer + description: The Unix timestamp (in seconds) when the model was created. + object: + type: string + description: The object type, which is always "model". enum: - - supervised - - dpo - supervised: - $ref: "#/components/schemas/FineTuneSupervisedMethod" - dpo: - $ref: "#/components/schemas/FineTuneDPOMethod" - FineTunePreferenceRequestInput: - type: object - description: The per-line training example of a fine-tuning input file for chat - models using the dpo method. - properties: - input: - type: object - properties: - messages: - type: array - minItems: 1 - items: - oneOf: - - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" - - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" - - $ref: "#/components/schemas/FineTuneChatCompletionRequestAssistantMessage" - - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" - - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" - x-oaiExpandable: true - tools: - type: array - description: A list of tools the model may generate JSON inputs for. - items: - $ref: "#/components/schemas/ChatCompletionTool" - parallel_tool_calls: - $ref: "#/components/schemas/ParallelToolCalls" - preferred_completion: - type: array - description: The preferred completion message for the output. - maxItems: 1 - items: - oneOf: - - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" - x-oaiExpandable: true - non_preferred_completion: - type: array - description: The non-preferred completion message for the output. - maxItems: 1 - items: - oneOf: - - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" - x-oaiExpandable: true + - model + x-stainless-const: true + owned_by: + type: string + description: The organization that owns the model. + required: + - id + - object + - created + - owned_by x-oaiMeta: - name: Training format for chat models using the preference method - example: > + name: The model object + example: | { - "input": { - "messages": [ - { "role": "user", "content": "What is the weather in San Francisco?" } - ] - }, - "preferred_completion": [ - { - "role": "assistant", - "content": "The weather in San Francisco is 70 degrees Fahrenheit." - } - ], - "non_preferred_completion": [ - { - "role": "assistant", - "content": "The weather in San Francisco is 21 degrees Celsius." - } - ] + "id": "VAR_chat_model_id", + "object": "model", + "created": 1686935002, + "owned_by": "openai" } - FineTuneSupervisedMethod: - type: object - description: Configuration for the supervised fine-tuning method. - properties: - hyperparameters: - type: object - description: The hyperparameters used for the fine-tuning job. - properties: - batch_size: - description: > - Number of examples in each batch. A larger batch size means that - model parameters are updated less frequently, but with lower - variance. - oneOf: - - type: string - enum: - - auto - x-stainless-const: true - - type: integer - minimum: 1 - maximum: 256 - default: auto - learning_rate_multiplier: - description: > - Scaling factor for the learning rate. A smaller learning rate - may be useful to avoid overfitting. - oneOf: - - type: string - enum: - - auto - x-stainless-const: true - - type: number - minimum: 0 - exclusiveMinimum: true - default: auto - n_epochs: - description: > - The number of epochs to train the model for. An epoch refers to - one full cycle through the training dataset. - oneOf: - - type: string - enum: - - auto - x-stainless-const: true - - type: integer - minimum: 1 - maximum: 50 - default: auto - FineTuningIntegration: + ModelIds: + anyOf: + - type: string + - type: string + enum: + - o1 + - o1-2024-12-17 + - o1-preview + - o1-preview-2024-09-12 + - o1-mini + - o1-mini-2024-09-12 + - gpt-4o + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o-audio-preview + - gpt-4o-audio-preview-2024-10-01 + - gpt-4o-audio-preview-2024-12-17 + - gpt-4o-mini-audio-preview + - gpt-4o-mini-audio-preview-2024-12-17 + - gpt-4o-search-preview + - gpt-4o-mini-search-preview + - gpt-4o-search-preview-2025-03-11 + - gpt-4o-mini-search-preview-2025-03-11 + - computer-use-preview + - computer-use-preview-2025-03-11 + - chatgpt-4o-latest + - gpt-4o-mini + - gpt-4o-mini-2024-07-18 + - gpt-4-turbo + - gpt-4-turbo-2024-04-09 + - gpt-4-0125-preview + - gpt-4-turbo-preview + - gpt-4-1106-preview + - gpt-4-vision-preview + - gpt-4 + - gpt-4-0314 + - gpt-4-0613 + - gpt-4-32k + - gpt-4-32k-0314 + - gpt-4-32k-0613 + - gpt-3.5-turbo + - gpt-3.5-turbo-16k + - gpt-3.5-turbo-0301 + - gpt-3.5-turbo-0613 + - gpt-3.5-turbo-1106 + - gpt-3.5-turbo-0125 + - gpt-3.5-turbo-16k-0613 + ModelResponseProperties: type: object - title: Fine-Tuning Job Integration - required: - - type - - wandb properties: - type: - type: string - description: The type of the integration being enabled for the fine-tuning job - enum: - - wandb - x-stainless-const: true - wandb: - type: object + model: description: > - The settings for your integration with Weights and Biases. This - payload specifies the project that + Model ID used to generate the response, like `gpt-4o` or `o1`. + OpenAI - metrics will be sent to. Optionally, you can set an explicit display - name for your run, add tags + offers a wide range of models with different capabilities, + performance - to your run, and set a default entity (team, username, etc) to be - associated with your run. - required: - - project - properties: - project: - description: | - The name of the project that the new run will be created under. - type: string - example: my-wandb-project - name: - description: > - A display name to set for the run. If not set, we will use the - Job ID as the name. - nullable: true - type: string - entity: - description: > - The entity to use for the run. This allows you to set the team - or username of the WandB user that you would + characteristics, and price points. Refer to the [model + guide](/docs/models) + + to browse and compare available models. + example: gpt-4o + anyOf: + - type: string + - type: string + enum: + - o3-mini + - o3-mini-2025-01-31 + - o1 + - o1-2024-12-17 + - o1-preview + - o1-preview-2024-09-12 + - o1-mini + - o1-mini-2024-09-12 + - computer-use-preview + - computer-use-preview-2025-02-04 + - computer-use-preview-2025-03-11 + - gpt-4.5-preview + - gpt-4.5-preview-2025-02-27 + - gpt-4o + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o-audio-preview + - gpt-4o-audio-preview-2024-10-01 + - gpt-4o-audio-preview-2024-12-17 + - gpt-4o-mini-audio-preview + - gpt-4o-mini-audio-preview-2024-12-17 + - chatgpt-4o-latest + - gpt-4o-mini + - gpt-4o-mini-2024-07-18 + - gpt-4-turbo + - gpt-4-turbo-2024-04-09 + - gpt-4-0125-preview + - gpt-4-turbo-preview + - gpt-4-1106-preview + - gpt-4-vision-preview + - gpt-4 + - gpt-4-0314 + - gpt-4-0613 + - gpt-4-32k + - gpt-4-32k-0314 + - gpt-4-32k-0613 + - gpt-3.5-turbo + - gpt-3.5-turbo-16k + - gpt-3.5-turbo-0301 + - gpt-3.5-turbo-0613 + - gpt-3.5-turbo-1106 + - gpt-3.5-turbo-0125 + - gpt-3.5-turbo-16k-0613 + x-oaiTypeLabel: string + metadata: + $ref: "#/components/schemas/Metadata" + temperature: + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + 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. - like associated with the run. If not set, the default entity for - the registered WandB API key is used. - nullable: true - type: string - tags: - description: > - A list of tags to be attached to the newly created run. These - tags are passed through directly to WandB. Some + We generally recommend altering this or `top_p` but not both. + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + description: > + An alternative to sampling with temperature, called nucleus + sampling, - default tags are generated by OpenAI: "openai/finetune", - "openai/{base-model}", "openai/{ftjob-abcdef}". - type: array - items: - type: string - example: custom-tag - FineTuningJob: + 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. + user: + type: string + example: user-1234 + description: > + A unique identifier representing your end-user, which can help + OpenAI to monitor and detect abuse. [Learn + more](/docs/guides/safety-best-practices#end-user-ids). + ModifyAssistantRequest: type: object - title: FineTuningJob - description: > - The `fine_tuning.job` object represents a fine-tuning job that has been - created through the API. + additionalProperties: false properties: - id: + model: + description: > + ID of the model to use. You can use the [List + models](/docs/api-reference/models/list) API to see all of your + available models, or see our [Model overview](/docs/models) for + descriptions of them. + anyOf: + - type: string + - $ref: "#/components/schemas/AssistantSupportedModels" + reasoning_effort: + $ref: "#/components/schemas/ReasoningEffort" + name: + description: | + The name of the assistant. The maximum length is 256 characters. type: string - description: The object identifier, which can be referenced in the API endpoints. - created_at: - type: integer - description: The Unix timestamp (in seconds) for when the fine-tuning job was - created. - error: - type: object nullable: true - description: For fine-tuning jobs that have `failed`, this will contain more - information on the cause of the failure. - properties: - code: - type: string - description: A machine-readable error code. - message: - type: string - description: A human-readable error message. - param: - type: string - description: The parameter that was invalid, usually `training_file` or - `validation_file`. This field will be null if the failure was - not parameter-specific. - nullable: true - required: - - code - - message - - param - fine_tuned_model: + maxLength: 256 + description: + description: > + The description of the assistant. The maximum length is 512 + characters. type: string nullable: true - description: The name of the fine-tuned model that is being created. The value - will be null if the fine-tuning job is still running. - finished_at: - type: integer + maxLength: 512 + instructions: + description: > + The system instructions that the assistant uses. The maximum length + is 256,000 characters. + type: string nullable: true - description: The Unix timestamp (in seconds) for when the fine-tuning job was - finished. The value will be null if the fine-tuning job is still - running. - hyperparameters: + maxLength: 256000 + tools: + description: > + A list of tool enabled on the assistant. There can be a maximum of + 128 tools per assistant. Tools can be of types `code_interpreter`, + `file_search`, or `function`. + default: [] + type: array + maxItems: 128 + items: + oneOf: + - $ref: "#/components/schemas/AssistantToolsCode" + - $ref: "#/components/schemas/AssistantToolsFileSearch" + - $ref: "#/components/schemas/AssistantToolsFunction" + x-oaiExpandable: true + tool_resources: type: object - description: The hyperparameters used for the fine-tuning job. This value will - only be returned when running `supervised` jobs. + description: > + A set of resources that are used by the assistant's tools. The + resources are specific to the type of tool. For example, the + `code_interpreter` tool requires a list of file IDs, while the + `file_search` tool requires a list of vector store IDs. properties: - batch_size: - description: > - Number of examples in each batch. A larger batch size means that - model parameters - - are updated less frequently, but with lower variance. - oneOf: - - type: string - enum: - - auto - x-stainless-const: true - - type: integer - minimum: 1 - maximum: 256 - default: auto - learning_rate_multiplier: - description: > - Scaling factor for the learning rate. A smaller learning rate - may be useful to avoid + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + Overrides the list of [file](/docs/api-reference/files) IDs + made available to the `code_interpreter` tool. There can be + a maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + Overrides the [vector + store](/docs/api-reference/vector-stores/object) attached to + this assistant. There can be a maximum of 1 vector store + attached to the assistant. + maxItems: 1 + items: + type: string + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + temperature: + 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. + type: number + minimum: 0 + maximum: 2 + default: 1 + example: 1 + nullable: true + top_p: + type: number + minimum: 0 + maximum: 1 + default: 1 + example: 1 + nullable: true + 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. - overfitting. - oneOf: - - type: string - enum: - - auto - x-stainless-const: true - - type: number - minimum: 0 - exclusiveMinimum: true - default: auto - n_epochs: - description: > - The number of epochs to train the model for. An epoch refers to - one full cycle - through the training dataset. - oneOf: - - type: string - enum: - - auto - x-stainless-const: true - - type: integer - minimum: 1 - maximum: 50 - default: auto - model: - type: string - description: The base model that is being fine-tuned. - object: + We generally recommend altering this or temperature but not both. + response_format: + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true + ModifyMessageRequest: + type: object + additionalProperties: false + properties: + metadata: + $ref: "#/components/schemas/Metadata" + ModifyRunRequest: + type: object + additionalProperties: false + properties: + metadata: + $ref: "#/components/schemas/Metadata" + ModifyThreadRequest: + type: object + additionalProperties: false + properties: + tool_resources: + type: object + description: > + A set of resources that are made available to the assistant's tools + in this thread. The resources are specific to the type of tool. For + example, the `code_interpreter` tool requires a list of file IDs, + while the `file_search` tool requires a list of vector store IDs. + properties: + code_interpreter: + type: object + properties: + file_ids: + type: array + description: > + A list of [file](/docs/api-reference/files) IDs made + available to the `code_interpreter` tool. There can be a + maximum of 20 files associated with the tool. + default: [] + maxItems: 20 + items: + type: string + file_search: + type: object + properties: + vector_store_ids: + type: array + description: > + The [vector store](/docs/api-reference/vector-stores/object) + attached to this thread. There can be a maximum of 1 vector + store attached to the thread. + maxItems: 1 + items: + type: string + nullable: true + metadata: + $ref: "#/components/schemas/Metadata" + Move: + type: object + title: Move + description: | + A mouse move action. + properties: + type: type: string - description: The object type, which is always "fine_tuning.job". enum: - - fine_tuning.job + - move + default: move + description: | + Specifies the event type. For a move action, this property is + always set to `move`. x-stainless-const: true - organization_id: - type: string - description: The organization that owns the fine-tuning job. - result_files: - type: array - description: The compiled results file ID(s) for the fine-tuning job. You can - retrieve the results with the [Files - API](/docs/api-reference/files/retrieve-contents). - items: - type: string - example: file-abc123 - status: - type: string - description: The current status of the fine-tuning job, which can be either - `validating_files`, `queued`, `running`, `succeeded`, `failed`, or - `cancelled`. - enum: - - validating_files - - queued - - running - - succeeded - - failed - - cancelled - trained_tokens: - type: integer - nullable: true - description: The total number of billable tokens processed by this fine-tuning - job. The value will be null if the fine-tuning job is still running. - training_file: - type: string - description: The file ID used for training. You can retrieve the training data - with the [Files API](/docs/api-reference/files/retrieve-contents). - validation_file: - type: string - nullable: true - description: The file ID used for validation. You can retrieve the validation - results with the [Files - API](/docs/api-reference/files/retrieve-contents). - integrations: - type: array - nullable: true - description: A list of integrations to enable for this fine-tuning job. - maxItems: 5 - items: - oneOf: - - $ref: "#/components/schemas/FineTuningIntegration" - x-oaiExpandable: true - seed: + x: type: integer - description: The seed used for the fine-tuning job. - estimated_finish: + description: | + The x-coordinate to move to. + y: type: integer - nullable: true - description: The Unix timestamp (in seconds) for when the fine-tuning job is - estimated to finish. The value will be null if the fine-tuning job - is not running. - method: - $ref: "#/components/schemas/FineTuneMethod" + description: | + The y-coordinate to move to. required: - - created_at - - error - - finished_at - - fine_tuned_model - - hyperparameters - - id - - model - - object - - organization_id - - result_files - - status - - trained_tokens - - training_file - - validation_file - - seed - x-oaiMeta: - name: The fine-tuning job object - example: | - { - "object": "fine_tuning.job", - "id": "ftjob-abc123", - "model": "davinci-002", - "created_at": 1692661014, - "finished_at": 1692661190, - "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy", - "organization_id": "org-123", - "result_files": [ - "file-abc123" - ], - "status": "succeeded", - "validation_file": null, - "training_file": "file-abc123", - "hyperparameters": { - "n_epochs": 4, - "batch_size": 1, - "learning_rate_multiplier": 1.0 - }, - "trained_tokens": 5768, - "integrations": [], - "seed": 0, - "estimated_finish": 0, - "method": { - "type": "supervised", - "supervised": { - "hyperparameters": { - "n_epochs": 4, - "batch_size": 1, - "learning_rate_multiplier": 1.0 - } - } - } - } - FineTuningJobCheckpoint: - type: object - title: FineTuningJobCheckpoint - description: > - The `fine_tuning.job.checkpoint` object represents a model checkpoint - for a fine-tuning job that is ready to use. + - type + - x + - y + OpenAIFile: + title: OpenAIFile + description: The `File` object represents a document that has been uploaded to OpenAI. properties: id: type: string - description: The checkpoint identifier, which can be referenced in the API - endpoints. + description: The file identifier, which can be referenced in the API endpoints. + bytes: + type: integer + description: The size of the file, in bytes. created_at: type: integer - description: The Unix timestamp (in seconds) for when the checkpoint was created. - fine_tuned_model_checkpoint: - type: string - description: The name of the fine-tuned checkpoint model that is created. - step_number: + description: The Unix timestamp (in seconds) for when the file was created. + expires_at: type: integer - description: The step number that the checkpoint was created at. - metrics: - type: object - description: Metrics at the step number during the fine-tuning job. - properties: - step: - type: number - train_loss: - type: number - train_mean_token_accuracy: - type: number - valid_loss: - type: number - valid_mean_token_accuracy: - type: number - full_valid_loss: - type: number - full_valid_mean_token_accuracy: - type: number - fine_tuning_job_id: + description: The Unix timestamp (in seconds) for when the file will expire. + filename: type: string - description: The name of the fine-tuning job that this checkpoint was created - from. + description: The name of the file. object: type: string - description: The object type, which is always "fine_tuning.job.checkpoint". + description: The object type, which is always `file`. enum: - - fine_tuning.job.checkpoint + - file x-stainless-const: true - required: - - created_at - - fine_tuning_job_id - - fine_tuned_model_checkpoint - - id - - metrics - - object - - step_number - x-oaiMeta: - name: The fine-tuning job checkpoint object - example: > - { - "object": "fine_tuning.job.checkpoint", - "id": "ftckpt_qtZ5Gyk4BLq1SfLFWp3RtO3P", - "created_at": 1712211699, - "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom_suffix:9ABel2dg:ckpt-step-88", - "fine_tuning_job_id": "ftjob-fpbNQ3H1GrMehXRf8cO97xTN", - "metrics": { - "step": 88, - "train_loss": 0.478, - "train_mean_token_accuracy": 0.924, - "valid_loss": 10.112, - "valid_mean_token_accuracy": 0.145, - "full_valid_loss": 0.567, - "full_valid_mean_token_accuracy": 0.944 - }, - "step_number": 88 - } - FineTuningJobEvent: - type: object - description: Fine-tuning job event object - properties: - object: + purpose: type: string - description: The object type, which is always "fine_tuning.job.event". + description: The intended purpose of the file. Supported values are + `assistants`, `assistants_output`, `batch`, `batch_output`, + `fine-tune`, `fine-tune-results` and `vision`. enum: - - fine_tuning.job.event - x-stainless-const: true - id: - type: string - description: The object identifier. - created_at: - type: integer - description: The Unix timestamp (in seconds) for when the fine-tuning job was - created. - level: + - assistants + - assistants_output + - batch + - batch_output + - fine-tune + - fine-tune-results + - vision + status: type: string - description: The log level of the event. + deprecated: true + description: Deprecated. The current status of the file, which can be either + `uploaded`, `processed`, or `error`. enum: - - info - - warn + - uploaded + - processed - error - message: - type: string - description: The message of the event. - type: + status_details: type: string - description: The type of event. - enum: - - message - - metrics - data: - type: object - description: The data associated with the event. + deprecated: true + description: Deprecated. For details on why a fine-tuning training file failed + validation, see the `error` field on `fine_tuning.job`. required: - id - object + - bytes - created_at - - level - - message + - filename + - purpose + - status x-oaiMeta: - name: The fine-tuning job event object + name: The file object example: | { - "object": "fine_tuning.job.event", - "id": "ftevent-abc123" + "id": "file-abc123", + "object": "file", + "bytes": 120000, "created_at": 1677610602, - "level": "info", - "message": "Created fine-tuning job", - "data": {}, - "type": "message" + "expires_at": 1680202602, + "filename": "salesOverview.pdf", + "purpose": "assistants", } - FunctionObject: + OtherChunkingStrategyResponseParam: type: object + title: Other Chunking Strategy + description: This is returned when the chunking strategy is unknown. Typically, + this is because the file was indexed before the `chunking_strategy` + concept was introduced in the API. + additionalProperties: false properties: - description: - type: string - description: A description of what the function does, used by the model to - choose when and how to call the function. - name: + type: type: string - description: The name of the function to be called. Must be a-z, A-Z, 0-9, or - contain underscores and dashes, with a maximum length of 64. - parameters: - $ref: "#/components/schemas/FunctionParameters" - strict: - type: boolean - nullable: true - default: false - description: Whether to enable strict schema adherence when generating the - function call. If set to true, the model will follow the exact - schema defined in the `parameters` field. Only a subset of JSON - Schema is supported when `strict` is `true`. Learn more about - Structured Outputs in the [function calling - guide](docs/guides/function-calling). + description: Always `other`. + enum: + - other + x-stainless-const: true required: - - name - FunctionParameters: + - type + OutputAudio: type: object - description: >- - The parameters the functions accepts, described as a JSON Schema object. - See the [guide](/docs/guides/function-calling) for examples, and the - [JSON Schema - reference](https://json-schema.org/understanding-json-schema/) for - documentation about the format. - - - Omitting `parameters` defines a function with an empty parameter list. - additionalProperties: true - Image: + 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 + OutputContent: + oneOf: + - $ref: "#/components/schemas/OutputText" + - $ref: "#/components/schemas/Refusal" + OutputItem: + anyOf: + - $ref: "#/components/schemas/OutputMessage" + - $ref: "#/components/schemas/FileSearchToolCall" + - $ref: "#/components/schemas/FunctionToolCall" + - $ref: "#/components/schemas/WebSearchToolCall" + - $ref: "#/components/schemas/ComputerToolCall" + - $ref: "#/components/schemas/ReasoningItem" + x-oaiExpandable: true + discriminator: + propertyName: type + OutputMessage: type: object - description: Represents the url or the content of an image generated by the - OpenAI API. + title: Output message + description: | + An output message from the model. properties: - b64_json: + id: type: string - description: The base64-encoded JSON of the generated image, if - `response_format` is `b64_json`. - url: + description: | + The unique ID of the output message. + type: type: string - description: The URL of the generated image, if `response_format` is `url` - (default). - revised_prompt: + description: | + The type of the output message. Always `message`. + enum: + - message + x-stainless-const: true + role: type: string - description: The prompt that was used to generate the image, if there was any - revision to the prompt. - x-oaiMeta: - name: The image object - example: | - { - "url": "...", - "revised_prompt": "..." - } - ImagesResponse: + 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. + x-oaiExpandable: true + items: + x-oaiExpandable: true + $ref: "#/components/schemas/OutputContent" + 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 + OutputText: + type: object + title: Output text + description: | + A text output from the model. properties: - created: - type: integer - data: + type: + type: string + description: | + The type of the output text. Always `output_text`. + enum: + - output_text + x-stainless-const: true + text: + type: string + description: | + The text output from the model. + annotations: type: array + description: | + The annotations of the text output. items: - $ref: "#/components/schemas/Image" + x-oaiExpandable: true + $ref: "#/components/schemas/Annotation" required: - - created - - data - Invite: + - type + - text + - annotations + ParallelToolCalls: + description: Whether to enable [parallel function + calling](/docs/guides/function-calling#configuring-parallel-function-calling) + during tool use. + type: boolean + default: true + PredictionContent: type: object - description: Represents an individual `invite` to the organization. + title: Static Content + description: > + Static predicted output content, such as the content of a text file that + is + + being regenerated. + required: + - type + - content properties: - object: + type: type: string enum: - - organization.invite - description: The object type, which is always `organization.invite` + - content + description: | + The type of the predicted content you want to provide. This type is + currently always `content`. x-stainless-const: true + content: + x-oaiExpandable: true + description: > + The content that should be matched when generating a model response. + + If generated tokens would match this content, the entire model + response + + can be returned much more quickly. + oneOf: + - type: string + title: Text content + description: | + The content used for a Predicted Output. This is often the + text of a file you are regenerating with minor changes. + - type: array + description: An array of content parts with a defined type. Supported options + differ based on the [model](/docs/models) being used to generate + the response. Can contain text inputs. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + minItems: 1 + Project: + type: object + description: Represents an individual project. + properties: id: type: string description: The identifier, which can be referenced in API endpoints - email: - type: string - description: The email address of the individual to whom the invite was sent - role: + object: type: string enum: - - owner - - reader - description: "`owner` or `reader`" - status: + - organization.project + description: The object type, which is always `organization.project` + x-stainless-const: true + name: type: string - enum: - - accepted - - expired - - pending - description: "`accepted`,`expired`, or `pending`" - invited_at: - type: integer - description: The Unix timestamp (in seconds) of when the invite was sent. - expires_at: + description: The name of the project. This appears in reporting. + created_at: type: integer - description: The Unix timestamp (in seconds) of when the invite expires. - accepted_at: + description: The Unix timestamp (in seconds) of when the project was created. + archived_at: type: integer - description: The Unix timestamp (in seconds) of when the invite was accepted. - projects: - type: array - description: The projects that were granted membership upon acceptance of the - invite. - items: - type: object - properties: - id: - type: string - description: Project's public ID - role: - type: string - enum: - - member - - owner - description: Project membership role + nullable: true + description: The Unix timestamp (in seconds) of when the project was archived or + `null`. + status: + type: string + enum: + - active + - archived + description: "`active` or `archived`" required: - - object - id - - email - - role + - object + - name + - created_at - status - - invited_at - - expires_at x-oaiMeta: - name: The invite object + name: The project object example: | { - "object": "organization.invite", - "id": "invite-abc", - "email": "user@example.com", - "role": "owner", - "status": "accepted", - "invited_at": 1711471533, - "expires_at": 1711471533, - "accepted_at": 1711471533, - "projects": [ - { - "id": "project-xyz", - "role": "member" - } - ] + "id": "proj_abc", + "object": "organization.project", + "name": "Project example", + "created_at": 1711471533, + "archived_at": null, + "status": "active" } - InviteDeleteResponse: + ProjectApiKey: type: object + description: Represents an individual API key in a project. properties: object: type: string enum: - - organization.invite.deleted - description: The object type, which is always `organization.invite.deleted` + - organization.project.api_key + description: The object type, which is always `organization.project.api_key` x-stainless-const: true + redacted_value: + type: string + description: The redacted value of the API key + name: + type: string + description: The name of the API key + created_at: + type: integer + description: The Unix timestamp (in seconds) of when the API key was created id: type: string - deleted: - type: boolean + description: The identifier, which can be referenced in API endpoints + owner: + type: object + properties: + type: + type: string + enum: + - user + - service_account + description: "`user` or `service_account`" + user: + $ref: "#/components/schemas/ProjectUser" + service_account: + $ref: "#/components/schemas/ProjectServiceAccount" required: - object + - redacted_value + - name + - created_at - id - - deleted - InviteListResponse: + - owner + x-oaiMeta: + name: The project API key object + example: | + { + "object": "organization.project.api_key", + "redacted_value": "sk-abc...def", + "name": "My API Key", + "created_at": 1711471533, + "id": "key_abc", + "owner": { + "type": "user", + "user": { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "created_at": 1711471533 + } + } + } + ProjectApiKeyDeleteResponse: type: object properties: object: type: string enum: - - list - description: The object type, which is always `list` + - organization.project.api_key.deleted x-stainless-const: true - data: - type: array - items: - $ref: "#/components/schemas/Invite" - first_id: - type: string - description: The first `invite_id` in the retrieved `list` - last_id: - type: string - description: The last `invite_id` in the retrieved `list` - has_more: - type: boolean - description: The `has_more` property is used for pagination to indicate there - are additional results. - required: - - object - - data - InviteRequest: - type: object - properties: - email: - type: string - description: Send an email to this address - role: - type: string - enum: - - reader - - owner - description: "`owner` or `reader`" - projects: - type: array - description: An array of projects to which membership is granted at the same - time the org invite is accepted. If omitted, the user will be - invited to the default project for compatibility with legacy - behavior. - items: - type: object - properties: - id: - type: string - description: Project's public ID - role: - type: string - enum: - - member - - owner - description: Project membership role - required: - - id - - role - required: - - email - - role - ListAssistantsResponse: - type: object - properties: - object: - type: string - example: list - data: - type: array - items: - $ref: "#/components/schemas/AssistantObject" - first_id: - type: string - example: asst_abc123 - last_id: + id: type: string - example: asst_abc456 - has_more: + deleted: type: boolean - example: false required: - object - - data - - first_id - - last_id - - has_more - x-oaiMeta: - name: List assistants response object - group: chat - example: > - { - "object": "list", - "data": [ - { - "id": "asst_abc123", - "object": "assistant", - "created_at": 1698982736, - "name": "Coding Tutor", - "description": null, - "model": "gpt-4o", - "instructions": "You are a helpful assistant designed to make me better at coding!", - "tools": [], - "tool_resources": {}, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" - }, - { - "id": "asst_abc456", - "object": "assistant", - "created_at": 1698982718, - "name": "My Assistant", - "description": null, - "model": "gpt-4o", - "instructions": "You are a helpful assistant designed to make me better at coding!", - "tools": [], - "tool_resources": {}, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" - }, - { - "id": "asst_abc789", - "object": "assistant", - "created_at": 1698982643, - "name": null, - "description": null, - "model": "gpt-4o", - "instructions": null, - "tools": [], - "tool_resources": {}, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" - } - ], - "first_id": "asst_abc123", - "last_id": "asst_abc789", - "has_more": false - } - ListAuditLogsResponse: + - id + - deleted + ProjectApiKeyListResponse: type: object properties: object: @@ -18171,13 +23781,11 @@ components: data: type: array items: - $ref: "#/components/schemas/AuditLog" + $ref: "#/components/schemas/ProjectApiKey" first_id: type: string - example: audit_log-defb456h8dks last_id: type: string - example: audit_log-hnbkd8s93s has_more: type: boolean required: @@ -18186,2846 +23794,3085 @@ components: - first_id - last_id - has_more - ListBatchesResponse: + ProjectCreateRequest: type: object properties: - data: - type: array - items: - $ref: "#/components/schemas/Batch" - first_id: - type: string - example: batch_abc123 - last_id: - type: string - example: batch_abc456 - has_more: - type: boolean - object: + name: type: string - enum: - - list - x-stainless-const: true + description: The friendly name of the project, this name appears in reports. required: - - object - - data - - has_more - ListFilesResponse: + - name + ProjectListResponse: type: object properties: object: type: string - example: list + enum: + - list + x-stainless-const: true data: type: array items: - $ref: "#/components/schemas/OpenAIFile" + $ref: "#/components/schemas/Project" first_id: type: string - example: file-abc123 last_id: type: string - example: file-abc456 has_more: type: boolean - example: false required: - object - data - first_id - last_id - has_more - ListFineTuningJobCheckpointsResponse: + ProjectRateLimit: type: object + description: Represents a project rate limit config. properties: - data: - type: array - items: - $ref: "#/components/schemas/FineTuningJobCheckpoint" object: type: string enum: - - list + - project.rate_limit + description: The object type, which is always `project.rate_limit` x-stainless-const: true - first_id: + id: type: string - nullable: true - last_id: + description: The identifier, which can be referenced in API endpoints. + model: type: string - nullable: true - has_more: - type: boolean + description: The model this rate limit applies to. + max_requests_per_1_minute: + type: integer + description: The maximum requests per minute. + max_tokens_per_1_minute: + type: integer + description: The maximum tokens per minute. + max_images_per_1_minute: + type: integer + description: The maximum images per minute. Only present for relevant models. + max_audio_megabytes_per_1_minute: + type: integer + description: The maximum audio megabytes per minute. Only present for relevant + models. + max_requests_per_1_day: + type: integer + description: The maximum requests per day. Only present for relevant models. + batch_1_day_max_input_tokens: + type: integer + description: The maximum batch input tokens per day. Only present for relevant + models. required: - object - - data - - has_more - ListFineTuningJobEventsResponse: + - id + - model + - max_requests_per_1_minute + - max_tokens_per_1_minute + x-oaiMeta: + name: The project rate limit object + example: | + { + "object": "project.rate_limit", + "id": "rl_ada", + "model": "ada", + "max_requests_per_1_minute": 600, + "max_tokens_per_1_minute": 150000, + "max_images_per_1_minute": 10 + } + ProjectRateLimitListResponse: type: object properties: - data: - type: array - items: - $ref: "#/components/schemas/FineTuningJobEvent" object: type: string enum: - list x-stainless-const: true - has_more: - type: boolean - required: - - object - - data - - has_more - ListMessagesResponse: - properties: - object: - type: string - example: list data: type: array items: - $ref: "#/components/schemas/MessageObject" + $ref: "#/components/schemas/ProjectRateLimit" first_id: type: string - example: msg_abc123 last_id: type: string - example: msg_abc123 has_more: type: boolean - example: false required: - object - data - first_id - last_id - has_more - ListModelsResponse: + ProjectRateLimitUpdateRequest: + type: object + properties: + max_requests_per_1_minute: + type: integer + description: The maximum requests per minute. + max_tokens_per_1_minute: + type: integer + description: The maximum tokens per minute. + max_images_per_1_minute: + type: integer + description: The maximum images per minute. Only relevant for certain models. + max_audio_megabytes_per_1_minute: + type: integer + description: The maximum audio megabytes per minute. Only relevant for certain + models. + max_requests_per_1_day: + type: integer + description: The maximum requests per day. Only relevant for certain models. + batch_1_day_max_input_tokens: + type: integer + description: The maximum batch input tokens per day. Only relevant for certain + models. + ProjectServiceAccount: type: object + description: Represents an individual service account in a project. properties: object: type: string enum: - - list + - organization.project.service_account + description: The object type, which is always + `organization.project.service_account` x-stainless-const: true - data: - type: array - items: - $ref: "#/components/schemas/Model" + id: + type: string + description: The identifier, which can be referenced in API endpoints + name: + type: string + description: The name of the service account + role: + type: string + enum: + - owner + - member + description: "`owner` or `member`" + created_at: + type: integer + description: The Unix timestamp (in seconds) of when the service account was + created required: - object - - data - ListPaginatedFineTuningJobsResponse: + - id + - name + - role + - created_at + x-oaiMeta: + name: The project service account object + example: | + { + "object": "organization.project.service_account", + "id": "svc_acct_abc", + "name": "Service Account", + "role": "owner", + "created_at": 1711471533 + } + ProjectServiceAccountApiKey: type: object properties: - data: - type: array - items: - $ref: "#/components/schemas/FineTuningJob" - has_more: - type: boolean object: type: string enum: - - list + - organization.project.service_account.api_key + description: The object type, which is always + `organization.project.service_account.api_key` x-stainless-const: true - required: - - object - - data - - has_more - ListRunStepsResponse: - properties: - object: + value: type: string - example: list - data: - type: array - items: - $ref: "#/components/schemas/RunStepObject" - first_id: + name: type: string - example: step_abc123 - last_id: + created_at: + type: integer + id: type: string - example: step_abc456 - has_more: - type: boolean - example: false required: - object - - data - - first_id - - last_id - - has_more - ListRunsResponse: + - value + - name + - created_at + - id + ProjectServiceAccountCreateRequest: type: object properties: - object: - type: string - example: list - data: - type: array - items: - $ref: "#/components/schemas/RunObject" - first_id: - type: string - example: run_abc123 - last_id: + name: type: string - example: run_abc456 - has_more: - type: boolean - example: false + description: The name of the service account being created. required: - - object - - data - - first_id - - last_id - - has_more - ListThreadsResponse: + - name + ProjectServiceAccountCreateResponse: + type: object properties: object: type: string - example: list - data: - type: array - items: - $ref: "#/components/schemas/ThreadObject" - first_id: + enum: + - organization.project.service_account + x-stainless-const: true + id: type: string - example: asst_abc123 - last_id: + name: type: string - example: asst_abc456 - has_more: - type: boolean - example: false + role: + type: string + enum: + - member + description: Service accounts can only have one role of type `member` + x-stainless-const: true + created_at: + type: integer + api_key: + $ref: "#/components/schemas/ProjectServiceAccountApiKey" required: - object - - data - - first_id - - last_id - - has_more - ListVectorStoreFilesResponse: + - id + - name + - role + - created_at + - api_key + ProjectServiceAccountDeleteResponse: + type: object properties: object: type: string - example: list - data: - type: array - items: - $ref: "#/components/schemas/VectorStoreFileObject" - first_id: - type: string - example: file-abc123 - last_id: + enum: + - organization.project.service_account.deleted + x-stainless-const: true + id: type: string - example: file-abc456 - has_more: + deleted: type: boolean - example: false required: - object - - data - - first_id - - last_id - - has_more - ListVectorStoresResponse: + - id + - deleted + ProjectServiceAccountListResponse: + type: object properties: object: type: string - example: list + enum: + - list + x-stainless-const: true data: type: array items: - $ref: "#/components/schemas/VectorStoreObject" + $ref: "#/components/schemas/ProjectServiceAccount" first_id: type: string - example: vs_abc123 last_id: type: string - example: vs_abc456 has_more: type: boolean - example: false required: - object - data - first_id - last_id - has_more - MessageContentImageFileObject: - title: Image file + ProjectUpdateRequest: type: object - description: References an image [File](/docs/api-reference/files) in the - content of a message. properties: - type: - description: Always `image_file`. + name: + type: string + description: The updated name of the project, this name appears in reports. + required: + - name + ProjectUser: + type: object + description: Represents an individual user in a project. + properties: + object: type: string enum: - - image_file + - organization.project.user + description: The object type, which is always `organization.project.user` x-stainless-const: true - image_file: - type: object - properties: - file_id: - description: The [File](/docs/api-reference/files) ID of the image in the - message content. Set `purpose="vision"` when uploading the File - if you need to later display the file content. - type: string - detail: - type: string - description: Specifies the detail level of the image if specified by the user. - `low` uses fewer tokens, you can opt in to high resolution using - `high`. - enum: - - auto - - low - - high - default: auto - required: - - file_id + id: + type: string + description: The identifier, which can be referenced in API endpoints + name: + type: string + description: The name of the user + email: + type: string + description: The email address of the user + role: + type: string + enum: + - owner + - member + description: "`owner` or `member`" + added_at: + type: integer + description: The Unix timestamp (in seconds) of when the project was added. required: - - type - - image_file - MessageContentImageUrlObject: - title: Image URL + - object + - id + - name + - email + - role + - added_at + x-oaiMeta: + name: The project user object + example: | + { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + ProjectUserCreateRequest: type: object - description: References an image URL in the content of a message. properties: - type: + user_id: + type: string + description: The ID of the user. + role: type: string enum: - - image_url - description: The type of the content part. - x-stainless-const: true - image_url: - type: object - properties: - url: - type: string - description: "The external URL of the image, must be a supported image types: - jpeg, jpg, png, gif, webp." - format: uri - detail: - type: string - description: Specifies the detail level of the image. `low` uses fewer tokens, - you can opt in to high resolution using `high`. Default value is - `auto` - enum: - - auto - - low - - high - default: auto - required: - - url + - owner + - member + description: "`owner` or `member`" required: - - type - - image_url - MessageContentRefusalObject: - title: Refusal + - user_id + - role + ProjectUserDeleteResponse: type: object - description: The refusal content generated by the assistant. properties: - type: - description: Always `refusal`. + object: type: string enum: - - refusal + - organization.project.user.deleted x-stainless-const: true - refusal: + id: type: string - nullable: false + deleted: + type: boolean required: - - type - - refusal - MessageContentTextAnnotationsFileCitationObject: - title: File citation + - object + - id + - deleted + ProjectUserListResponse: type: object - description: A citation within the message that points to a specific quote from - a specific File associated with the assistant or the message. Generated - when the assistant uses the "file_search" tool to search files. properties: - type: - description: Always `file_citation`. + object: type: string - enum: - - file_citation - x-stainless-const: true - text: - description: The text in the message content that needs to be replaced. + data: + type: array + items: + $ref: "#/components/schemas/ProjectUser" + first_id: type: string - file_citation: - type: object - properties: - file_id: - description: The ID of the specific File the citation is from. - type: string - required: - - file_id - start_index: - type: integer - minimum: 0 - end_index: - type: integer - minimum: 0 + last_id: + type: string + has_more: + type: boolean required: - - type - - text - - file_citation - - start_index - - end_index - MessageContentTextAnnotationsFilePathObject: - title: File path + - object + - data + - first_id + - last_id + - has_more + ProjectUserUpdateRequest: type: object - description: A URL for the file that's generated when the assistant used the - `code_interpreter` tool to generate a file. properties: - type: - description: Always `file_path`. + role: type: string enum: - - file_path - x-stainless-const: true - text: - description: The text in the message content that needs to be replaced. - type: string - file_path: - type: object - properties: - file_id: - description: The ID of the file that was generated. - type: string - required: - - file_id - start_index: - type: integer - minimum: 0 - end_index: - type: integer - minimum: 0 + - owner + - member + description: "`owner` or `member`" required: - - type - - text - - file_path - - start_index - - end_index - MessageContentTextObject: - title: Text + - role + RealtimeClientEventConversationItemCreate: type: object - description: The text content that is part of a message. + description: > + Add a new Item to the Conversation's context, including messages, + function + + calls, and function call responses. This event can be used both to + populate a + + "history" of the conversation and to add new items mid-stream, but has + the + + current limitation that it cannot populate assistant audio messages. + + + If successful, the server will respond with a + `conversation.item.created` + + event, otherwise an `error` event will be sent. properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. type: - description: Always `text`. type: string enum: - - text + - conversation.item.create + description: The event type, must be `conversation.item.create`. x-stainless-const: true - text: - type: object - properties: - value: - description: The data that makes up the text. - type: string - annotations: - type: array - items: - oneOf: - - $ref: "#/components/schemas/MessageContentTextAnnotationsFileCitationObject" - - $ref: "#/components/schemas/MessageContentTextAnnotationsFilePathObject" - x-oaiExpandable: true - required: - - value - - annotations + previous_item_id: + type: string + description: > + The ID of the preceding item after which the new item will be + inserted. + + If not set, the new item will be appended to the end of the + conversation. + + If set to `root`, the new item will be added to the beginning of the + conversation. + + If set to an existing ID, it allows an item to be inserted + mid-conversation. If the + + ID cannot be found, an error will be returned and the item will not + be added. + item: + $ref: "#/components/schemas/RealtimeConversationItem" required: - type - - text - MessageDeltaContentImageFileObject: - title: Image file + - item + x-oaiMeta: + name: conversation.item.create + group: realtime + example: | + { + "event_id": "event_345", + "type": "conversation.item.create", + "previous_item_id": null, + "item": { + "id": "msg_001", + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Hello, how are you?" + } + ] + } + } + RealtimeClientEventConversationItemDelete: type: object - description: References an image [File](/docs/api-reference/files) in the - content of a message. + description: > + Send this event when you want to remove any item from the conversation + + history. The server will respond with a `conversation.item.deleted` + event, + + unless the item does not exist in the conversation history, in which + case the + + server will respond with an error. properties: - index: - type: integer - description: The index of the content part in the message. + event_id: + type: string + description: Optional client-generated ID used to identify this event. type: - description: Always `image_file`. type: string enum: - - image_file + - conversation.item.delete + description: The event type, must be `conversation.item.delete`. x-stainless-const: true - image_file: - type: object - properties: - file_id: - description: The [File](/docs/api-reference/files) ID of the image in the - message content. Set `purpose="vision"` when uploading the File - if you need to later display the file content. - type: string - detail: - type: string - description: Specifies the detail level of the image if specified by the user. - `low` uses fewer tokens, you can opt in to high resolution using - `high`. - enum: - - auto - - low - - high - default: auto + item_id: + type: string + description: The ID of the item to delete. required: - - index - type - MessageDeltaContentImageUrlObject: - title: Image URL + - item_id + x-oaiMeta: + name: conversation.item.delete + group: realtime + example: | + { + "event_id": "event_901", + "type": "conversation.item.delete", + "item_id": "msg_003" + } + RealtimeClientEventConversationItemTruncate: type: object - description: References an image URL in the content of a message. + description: > + Send this event to truncate a previous assistant message’s audio. The + server + + will produce audio faster than realtime, so this event is useful when + the user + + interrupts to truncate audio that has already been sent to the client + but not + + yet played. This will synchronize the server's understanding of the + audio with + + the client's playback. + + + Truncating audio will delete the server-side text transcript to ensure + there + + is not text in the context that hasn't been heard by the user. + + + If successful, the server will respond with a + `conversation.item.truncated` + + event. properties: - index: - type: integer - description: The index of the content part in the message. + event_id: + type: string + description: Optional client-generated ID used to identify this event. type: - description: Always `image_url`. type: string enum: - - image_url + - conversation.item.truncate + description: The event type, must be `conversation.item.truncate`. x-stainless-const: true - image_url: - type: object - properties: - url: - description: "The URL of the image, must be a supported image types: jpeg, jpg, - png, gif, webp." - type: string - detail: - type: string - description: Specifies the detail level of the image. `low` uses fewer tokens, - you can opt in to high resolution using `high`. - enum: - - auto - - low - - high - default: auto + item_id: + type: string + description: > + The ID of the assistant message item to truncate. Only assistant + message + + items can be truncated. + content_index: + type: integer + description: The index of the content part to truncate. Set this to 0. + audio_end_ms: + type: integer + description: > + Inclusive duration up to which audio is truncated, in milliseconds. + If + + the audio_end_ms is greater than the actual audio duration, the + server + + will respond with an error. required: - - index - type - MessageDeltaContentRefusalObject: - title: Refusal + - item_id + - content_index + - audio_end_ms + x-oaiMeta: + name: conversation.item.truncate + group: realtime + example: | + { + "event_id": "event_678", + "type": "conversation.item.truncate", + "item_id": "msg_002", + "content_index": 0, + "audio_end_ms": 1500 + } + RealtimeClientEventInputAudioBufferAppend: type: object - description: The refusal content that is part of a message. + description: > + Send this event to append audio bytes to the input audio buffer. The + audio + + buffer is temporary storage you can write to and later commit. In Server + VAD + + mode, the audio buffer is used to detect speech and the server will + decide + + when to commit. When Server VAD is disabled, you must commit the audio + buffer + + manually. + + + The client may choose how much audio to place in each event up to a + maximum + + of 15 MiB, for example streaming smaller chunks from the client may + allow the + + VAD to be more responsive. Unlike made other client events, the server + will + + not send a confirmation response to this event. properties: - index: - type: integer - description: The index of the refusal part in the message. + event_id: + type: string + description: Optional client-generated ID used to identify this event. type: - description: Always `refusal`. type: string enum: - - refusal + - input_audio_buffer.append + description: The event type, must be `input_audio_buffer.append`. x-stainless-const: true - refusal: + audio: type: string + description: > + Base64-encoded audio bytes. This must be in the format specified by + the + + `input_audio_format` field in the session configuration. required: - - index - type - MessageDeltaContentTextAnnotationsFileCitationObject: - title: File citation + - audio + x-oaiMeta: + name: input_audio_buffer.append + group: realtime + example: | + { + "event_id": "event_456", + "type": "input_audio_buffer.append", + "audio": "Base64EncodedAudioData" + } + RealtimeClientEventInputAudioBufferClear: type: object - description: A citation within the message that points to a specific quote from - a specific File associated with the assistant or the message. Generated - when the assistant uses the "file_search" tool to search files. + description: | + Send this event to clear the audio bytes in the buffer. The server will + respond with an `input_audio_buffer.cleared` event. properties: - index: - type: integer - description: The index of the annotation in the text content part. + event_id: + type: string + description: Optional client-generated ID used to identify this event. type: - description: Always `file_citation`. type: string enum: - - file_citation + - input_audio_buffer.clear + description: The event type, must be `input_audio_buffer.clear`. x-stainless-const: true - text: - description: The text in the message content that needs to be replaced. - type: string - file_citation: - type: object - properties: - file_id: - description: The ID of the specific File the citation is from. - type: string - quote: - description: The specific quote in the file. - type: string - start_index: - type: integer - minimum: 0 - end_index: - type: integer - minimum: 0 required: - - index - type - MessageDeltaContentTextAnnotationsFilePathObject: - title: File path + x-oaiMeta: + name: input_audio_buffer.clear + group: realtime + example: | + { + "event_id": "event_012", + "type": "input_audio_buffer.clear" + } + RealtimeClientEventInputAudioBufferCommit: type: object - description: A URL for the file that's generated when the assistant used the - `code_interpreter` tool to generate a file. + description: > + Send this event to commit the user input audio buffer, which will create + a + + new user message item in the conversation. This event will produce an + error + + if the input audio buffer is empty. When in Server VAD mode, the client + does + + not need to send this event, the server will commit the audio buffer + + automatically. + + + Committing the input audio buffer will trigger input audio + transcription + + (if enabled in session configuration), but it will not create a + response + + from the model. The server will respond with an + `input_audio_buffer.committed` + + event. properties: - index: - type: integer - description: The index of the annotation in the text content part. + event_id: + type: string + description: Optional client-generated ID used to identify this event. type: - description: Always `file_path`. type: string enum: - - file_path + - input_audio_buffer.commit + description: The event type, must be `input_audio_buffer.commit`. x-stainless-const: true - text: - description: The text in the message content that needs to be replaced. - type: string - file_path: - type: object - properties: - file_id: - description: The ID of the file that was generated. - type: string - start_index: - type: integer - minimum: 0 - end_index: - type: integer - minimum: 0 required: - - index - type - MessageDeltaContentTextObject: - title: Text + x-oaiMeta: + name: input_audio_buffer.commit + group: realtime + example: | + { + "event_id": "event_789", + "type": "input_audio_buffer.commit" + } + RealtimeClientEventResponseCancel: type: object - description: The text content that is part of a message. + description: > + Send this event to cancel an in-progress response. The server will + respond + + with a `response.cancelled` event or an error if there is no response + to + + cancel. properties: - index: - type: integer - description: The index of the content part in the message. + event_id: + type: string + description: Optional client-generated ID used to identify this event. type: - description: Always `text`. type: string enum: - - text + - response.cancel + description: The event type, must be `response.cancel`. x-stainless-const: true - text: - type: object - properties: - value: - description: The data that makes up the text. - type: string - annotations: - type: array - items: - oneOf: - - $ref: "#/components/schemas/MessageDeltaContentTextAnnotationsFileCitationObjec\ - t" - - $ref: "#/components/schemas/MessageDeltaContentTextAnnotationsFilePathObject" - x-oaiExpandable: true + response_id: + type: string + description: | + A specific response ID to cancel - if not provided, will cancel an + in-progress response in the default conversation. required: - - index - type - MessageDeltaObject: + x-oaiMeta: + name: response.cancel + group: realtime + example: | + { + "event_id": "event_567", + "type": "response.cancel" + } + RealtimeClientEventResponseCreate: type: object - title: Message delta object description: > - Represents a message delta i.e. any changed fields on a message during - streaming. + This event instructs the server to create a Response, which means + triggering + + model inference. When in Server VAD mode, the server will create + Responses + + automatically. + + + A Response will include at least one Item, and may have two, in which + case + + the second will be a function call. These Items will be appended to the + + conversation history. + + + The server will respond with a `response.created` event, events for + Items + + and content created, and finally a `response.done` event to indicate + the + + Response is complete. + + + The `response.create` event includes inference configuration like + + `instructions`, and `temperature`. These fields will override the + Session's + + configuration for this Response only. properties: - id: - description: The identifier of the message, which can be referenced in API - endpoints. + event_id: type: string - object: - description: The object type, which is always `thread.message.delta`. + description: Optional client-generated ID used to identify this event. + type: type: string enum: - - thread.message.delta + - response.create + description: The event type, must be `response.create`. x-stainless-const: true - delta: - description: The delta containing the fields that have changed on the Message. - type: object - properties: - role: - description: The entity that produced the message. One of `user` or `assistant`. - type: string - enum: - - user - - assistant - content: - description: The content of the message in array of text and/or images. - type: array - items: - oneOf: - - $ref: "#/components/schemas/MessageDeltaContentImageFileObject" - - $ref: "#/components/schemas/MessageDeltaContentTextObject" - - $ref: "#/components/schemas/MessageDeltaContentRefusalObject" - - $ref: "#/components/schemas/MessageDeltaContentImageUrlObject" - x-oaiExpandable: true + response: + $ref: "#/components/schemas/RealtimeResponseCreateParams" required: - - id - - object - - delta + - type x-oaiMeta: - name: The message delta object - beta: true + name: response.create + group: realtime example: | { - "id": "msg_123", - "object": "thread.message.delta", - "delta": { - "content": [ - { - "index": 0, - "type": "text", - "text": { "value": "Hello", "annotations": [] } - } - ] - } + "event_id": "event_234", + "type": "response.create", + "response": { + "modalities": ["text", "audio"], + "instructions": "Please assist the user.", + "voice": "sage", + "output_audio_format": "pcm16", + "tools": [ + { + "type": "function", + "name": "calculate_sum", + "description": "Calculates the sum of two numbers.", + "parameters": { + "type": "object", + "properties": { + "a": { "type": "number" }, + "b": { "type": "number" } + }, + "required": ["a", "b"] + } + } + ], + "tool_choice": "auto", + "temperature": 0.8, + "max_output_tokens": 1024 + } } - MessageObject: + RealtimeClientEventSessionUpdate: type: object - title: The message object - description: Represents a message within a [thread](/docs/api-reference/threads). + description: > + Send this event to update the session’s default configuration. + + The client may send this event at any time to update any field, + + except for `voice`. However, note that once a session has been + + initialized with a particular `model`, it can’t be changed to + + another model using `session.update`. + + + When the server receives a `session.update`, it will respond + + with a `session.updated` event showing the full, effective + configuration. + + Only the fields that are present are updated. To clear a field like + + `instructions`, pass an empty string. properties: - id: - description: The identifier, which can be referenced in API endpoints. + event_id: type: string - object: - description: The object type, which is always `thread.message`. + description: Optional client-generated ID used to identify this event. + type: type: string enum: - - thread.message + - session.update + description: The event type, must be `session.update`. x-stainless-const: true - created_at: - description: The Unix timestamp (in seconds) for when the message was created. - type: integer - thread_id: - description: The [thread](/docs/api-reference/threads) ID that this message - belongs to. - type: string - status: - description: The status of the message, which can be either `in_progress`, - `incomplete`, or `completed`. - type: string - enum: - - in_progress - - incomplete - - completed - incomplete_details: - description: On an incomplete message, details about why the message is - incomplete. - type: object - properties: - reason: - type: string - description: The reason the message is incomplete. - enum: - - content_filter - - max_tokens - - run_cancelled - - run_expired - - run_failed - nullable: true - required: - - reason - completed_at: - description: The Unix timestamp (in seconds) for when the message was completed. - type: integer - nullable: true - incomplete_at: - description: The Unix timestamp (in seconds) for when the message was marked as - incomplete. - type: integer - nullable: true - role: - description: The entity that produced the message. One of `user` or `assistant`. - type: string - enum: - - user - - assistant - content: - description: The content of the message in array of text and/or images. - type: array - items: - oneOf: - - $ref: "#/components/schemas/MessageContentImageFileObject" - - $ref: "#/components/schemas/MessageContentImageUrlObject" - - $ref: "#/components/schemas/MessageContentTextObject" - - $ref: "#/components/schemas/MessageContentRefusalObject" - x-oaiExpandable: true - assistant_id: - description: If applicable, the ID of the - [assistant](/docs/api-reference/assistants) that authored this - message. - type: string - nullable: true - run_id: - description: The ID of the [run](/docs/api-reference/runs) associated with the - creation of this message. Value is `null` when messages are created - manually using the create message or create thread endpoints. - type: string - nullable: true - attachments: - type: array - items: - type: object - properties: - file_id: - type: string - description: The ID of the file to attach to the message. - tools: - description: The tools to add this file to. - type: array - items: - oneOf: - - $ref: "#/components/schemas/AssistantToolsCode" - - $ref: "#/components/schemas/AssistantToolsFileSearchTypeOnly" - x-oaiExpandable: true - description: A list of files attached to the message, and the tools they were - added to. - nullable: true - metadata: - $ref: "#/components/schemas/Metadata" + session: + $ref: "#/components/schemas/RealtimeSessionCreateRequest" required: - - id - - object - - created_at - - thread_id - - status - - incomplete_details - - completed_at - - incomplete_at - - role - - content - - assistant_id - - run_id - - attachments - - metadata + - type + - session x-oaiMeta: - name: The message object - beta: true + name: session.update + group: realtime example: | { - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1698983503, - "thread_id": "thread_abc123", - "role": "assistant", - "content": [ - { - "type": "text", - "text": { - "value": "Hi! How can I help you today?", - "annotations": [] - } + "event_id": "event_123", + "type": "session.update", + "session": { + "modalities": ["text", "audio"], + "instructions": "You are a helpful assistant.", + "voice": "sage", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": { + "type": "server_vad", + "threshold": 0.5, + "prefix_padding_ms": 300, + "silence_duration_ms": 500, + "create_response": true + }, + "tools": [ + { + "type": "function", + "name": "get_weather", + "description": "Get the current weather...", + "parameters": { + "type": "object", + "properties": { + "location": { "type": "string" } + }, + "required": ["location"] + } + } + ], + "tool_choice": "auto", + "temperature": 0.8, + "max_response_output_tokens": "inf" } - ], - "assistant_id": "asst_abc123", - "run_id": "run_abc123", - "attachments": [], - "metadata": {} } - MessageRequestContentTextObject: - title: Text + RealtimeConversationItem: type: object - description: The text content that is part of a message. + x-oaiExpandable: true + description: The item to add to the conversation. properties: + id: + type: string + description: > + The unique ID of the item, this can be generated by the client to + help + + manage server-side context, but is not required because the server + will + + generate one if not provided. type: - description: Always `text`. type: string enum: - - text + - message + - function_call + - function_call_output + description: > + The type of the item (`message`, `function_call`, + `function_call_output`). + object: + type: string + enum: + - realtime.item + description: > + Identifier for the API object being returned - always + `realtime.item`. x-stainless-const: true - text: + status: type: string - description: Text content to be sent to the model - required: - - type - - text - MessageStreamEvent: - oneOf: - - type: object - properties: - event: - type: string - enum: - - thread.message.created - x-stainless-const: true - data: - $ref: "#/components/schemas/MessageObject" - required: - - event - - data - description: Occurs when a [message](/docs/api-reference/messages/object) is - created. - x-oaiMeta: - dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" - - type: object - properties: - event: - type: string - enum: - - thread.message.in_progress - x-stainless-const: true - data: - $ref: "#/components/schemas/MessageObject" - required: - - event - - data - description: Occurs when a [message](/docs/api-reference/messages/object) moves - to an `in_progress` state. - x-oaiMeta: - dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" - - type: object - properties: - event: - type: string - enum: - - thread.message.delta - x-stainless-const: true - data: - $ref: "#/components/schemas/MessageDeltaObject" - required: - - event - - data - description: Occurs when parts of a - [Message](/docs/api-reference/messages/object) are being streamed. - x-oaiMeta: - dataDescription: "`data` is a [message - delta](/docs/api-reference/assistants-streaming/message-delta-obj\ - ect)" - - type: object - properties: - event: - type: string - enum: - - thread.message.completed - x-stainless-const: true - data: - $ref: "#/components/schemas/MessageObject" - required: - - event - - data - description: Occurs when a [message](/docs/api-reference/messages/object) is - completed. - x-oaiMeta: - dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" - - type: object - properties: - event: - type: string - enum: - - thread.message.incomplete - x-stainless-const: true - data: - $ref: "#/components/schemas/MessageObject" - required: - - event - - data - description: Occurs when a [message](/docs/api-reference/messages/object) ends - before it is completed. - x-oaiMeta: - dataDescription: "`data` is a [message](/docs/api-reference/messages/object)" - Metadata: - type: object - description: > - Set of 16 key-value pairs that can be attached to an object. This can be + enum: + - completed + - incomplete + description: > + The status of the item (`completed`, `incomplete`). These have no + effect - useful for storing additional information about the object in a - structured + on the conversation, but are accepted for consistency with the - format, and querying for objects via API or the dashboard. + `conversation.item.created` event. + role: + type: string + enum: + - user + - assistant + - system + description: > + The role of the message sender (`user`, `assistant`, `system`), + only + applicable for `message` items. + content: + type: array + x-oaiExpandable: true + description: > + The content of the message, applicable for `message` items. - Keys are strings with a maximum length of 64 characters. Values are - strings + - Message items of role `system` support only `input_text` content - with a maximum length of 512 characters. - additionalProperties: - type: string - x-oaiTypeLabel: map - nullable: true - Model: - title: Model - description: Describes an OpenAI model offering that can be used with the API. + - Message items of role `user` support `input_text` and + `input_audio` + content + - Message items of role `assistant` support `text` content. + items: + type: object + x-oaiExpandable: true + properties: + type: + type: string + enum: + - input_audio + - input_text + - item_reference + - text + description: > + The content type (`input_text`, `input_audio`, + `item_reference`, `text`). + text: + type: string + description: > + The text content, used for `input_text` and `text` content + types. + id: + type: string + description: > + ID of a previous conversation item to reference (for + `item_reference` + + content types in `response.create` events). These can + reference both + + client and server created items. + audio: + type: string + description: > + Base64-encoded audio bytes, used for `input_audio` content + type. + transcript: + type: string + description: > + The transcript of the audio, used for `input_audio` content + type. + call_id: + type: string + description: > + The ID of the function call (for `function_call` and + + `function_call_output` items). If passed on a + `function_call_output` + + item, the server will check that a `function_call` item with the + same + + ID exists in the conversation history. + name: + type: string + description: | + The name of the function being called (for `function_call` items). + arguments: + type: string + description: | + The arguments of the function call (for `function_call` items). + output: + type: string + description: | + The output of the function call (for `function_call_output` items). + RealtimeConversationItemWithReference: + type: object + x-oaiExpandable: true + description: The item to add to the conversation. properties: id: type: string - description: The model identifier, which can be referenced in the API endpoints. - created: - type: integer - description: The Unix timestamp (in seconds) when the model was created. - object: + description: > + For an item of type (`message` | `function_call` | + `function_call_output`) + + this field allows the client to assign the unique ID of the item. It + is + + not required because the server will generate one if not provided. + + + For an item of type `item_reference`, this field is required and is + a + + reference to any item that has previously existed in the + conversation. + type: type: string - description: The object type, which is always "model". enum: - - model - x-stainless-const: true - owned_by: - type: string - description: The organization that owns the model. - required: - - id - - object - - created - - owned_by - x-oaiMeta: - name: The model object - example: | - { - "id": "VAR_chat_model_id", - "object": "model", - "created": 1686935002, - "owned_by": "openai" - } - ModifyAssistantRequest: - type: object - additionalProperties: false - properties: - model: + - message + - function_call + - function_call_output description: > - ID of the model to use. You can use the [List - models](/docs/api-reference/models/list) API to see all of your - available models, or see our [Model overview](/docs/models) for - descriptions of them. - anyOf: - - type: string - - $ref: "#/components/schemas/AssistantSupportedModels" - reasoning_effort: - $ref: "#/components/schemas/ReasoningEffort" - name: - description: | - The name of the assistant. The maximum length is 256 characters. + The type of the item (`message`, `function_call`, + `function_call_output`, `item_reference`). + object: type: string - nullable: true - maxLength: 256 - description: + enum: + - realtime.item description: > - The description of the assistant. The maximum length is 512 - characters. + Identifier for the API object being returned - always + `realtime.item`. + x-stainless-const: true + status: type: string - nullable: true - maxLength: 512 - instructions: + enum: + - completed + - incomplete description: > - The system instructions that the assistant uses. The maximum length - is 256,000 characters. + The status of the item (`completed`, `incomplete`). These have no + effect + + on the conversation, but are accepted for consistency with the + + `conversation.item.created` event. + role: type: string - nullable: true - maxLength: 256000 - tools: + enum: + - user + - assistant + - system description: > - A list of tool enabled on the assistant. There can be a maximum of - 128 tools per assistant. Tools can be of types `code_interpreter`, - `file_search`, or `function`. - default: [] + The role of the message sender (`user`, `assistant`, `system`), + only + + applicable for `message` items. + content: type: array - maxItems: 128 + x-oaiExpandable: true + description: > + The content of the message, applicable for `message` items. + + - Message items of role `system` support only `input_text` content + + - Message items of role `user` support `input_text` and + `input_audio` + content + - Message items of role `assistant` support `text` content. items: - oneOf: - - $ref: "#/components/schemas/AssistantToolsCode" - - $ref: "#/components/schemas/AssistantToolsFileSearch" - - $ref: "#/components/schemas/AssistantToolsFunction" + type: object x-oaiExpandable: true - tool_resources: - type: object - description: > - A set of resources that are used by the assistant's tools. The - resources are specific to the type of tool. For example, the - `code_interpreter` tool requires a list of file IDs, while the - `file_search` tool requires a list of vector store IDs. - properties: - code_interpreter: - type: object - properties: - file_ids: - type: array - description: > - Overrides the list of [file](/docs/api-reference/files) IDs - made available to the `code_interpreter` tool. There can be - a maximum of 20 files associated with the tool. - default: [] - maxItems: 20 - items: - type: string - file_search: - type: object - properties: - vector_store_ids: - type: array - description: > - Overrides the [vector - store](/docs/api-reference/vector-stores/object) attached to - this assistant. There can be a maximum of 1 vector store - attached to the assistant. - maxItems: 1 - items: - type: string - nullable: true - metadata: - $ref: "#/components/schemas/Metadata" - temperature: - 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. - type: number - minimum: 0 - maximum: 2 - default: 1 - example: 1 - nullable: true - top_p: - type: number - minimum: 0 - maximum: 1 - default: 1 - example: 1 - nullable: true + properties: + type: + type: string + enum: + - input_audio + - input_text + - item_reference + - text + description: > + The content type (`input_text`, `input_audio`, + `item_reference`, `text`). + text: + type: string + description: > + The text content, used for `input_text` and `text` content + types. + id: + type: string + description: > + ID of a previous conversation item to reference (for + `item_reference` + + content types in `response.create` events). These can + reference both + + client and server created items. + audio: + type: string + description: > + Base64-encoded audio bytes, used for `input_audio` content + type. + transcript: + type: string + description: > + The transcript of the audio, used for `input_audio` content + type. + call_id: + type: string 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. + The ID of the function call (for `function_call` and + `function_call_output` items). If passed on a + `function_call_output` - We generally recommend altering this or temperature but not both. - response_format: - allOf: - - $ref: "#/components/schemas/AssistantsApiResponseFormatOption" - - nullable: true - ModifyMessageRequest: - type: object - additionalProperties: false - properties: - metadata: - $ref: "#/components/schemas/Metadata" - ModifyRunRequest: - type: object - additionalProperties: false - properties: - metadata: - $ref: "#/components/schemas/Metadata" - ModifyThreadRequest: + item, the server will check that a `function_call` item with the + same + + ID exists in the conversation history. + name: + type: string + description: | + The name of the function being called (for `function_call` items). + arguments: + type: string + description: | + The arguments of the function call (for `function_call` items). + output: + type: string + description: | + The output of the function call (for `function_call_output` items). + RealtimeResponse: type: object - additionalProperties: false - properties: - tool_resources: - type: object - description: > - A set of resources that are made available to the assistant's tools - in this thread. The resources are specific to the type of tool. For - example, the `code_interpreter` tool requires a list of file IDs, - while the `file_search` tool requires a list of vector store IDs. - properties: - code_interpreter: - type: object - properties: - file_ids: - type: array - description: > - A list of [file](/docs/api-reference/files) IDs made - available to the `code_interpreter` tool. There can be a - maximum of 20 files associated with the tool. - default: [] - maxItems: 20 - items: - type: string - file_search: - type: object - properties: - vector_store_ids: - type: array - description: > - The [vector store](/docs/api-reference/vector-stores/object) - attached to this thread. There can be a maximum of 1 vector - store attached to the thread. - maxItems: 1 - items: - type: string - nullable: true - metadata: - $ref: "#/components/schemas/Metadata" - OpenAIFile: - title: OpenAIFile - description: The `File` object represents a document that has been uploaded to OpenAI. + description: The response resource. properties: id: type: string - description: The file identifier, which can be referenced in the API endpoints. - bytes: - type: integer - description: The size of the file, in bytes. - created_at: - type: integer - description: The Unix timestamp (in seconds) for when the file was created. - filename: - type: string - description: The name of the file. + description: The unique ID of the response. object: type: string - description: The object type, which is always `file`. enum: - - file + - realtime.response + description: The object type, must be `realtime.response`. x-stainless-const: true - purpose: - type: string - description: The intended purpose of the file. Supported values are - `assistants`, `assistants_output`, `batch`, `batch_output`, - `fine-tune`, `fine-tune-results` and `vision`. - enum: - - assistants - - assistants_output - - batch - - batch_output - - fine-tune - - fine-tune-results - - vision status: type: string - deprecated: true - description: Deprecated. The current status of the file, which can be either - `uploaded`, `processed`, or `error`. enum: - - uploaded - - processed - - error + - completed + - cancelled + - failed + - incomplete + description: > + The final status of the response (`completed`, `cancelled`, + `failed`, or + + `incomplete`). status_details: - type: string - deprecated: true - description: Deprecated. For details on why a fine-tuning training file failed - validation, see the `error` field on `fine_tuning.job`. - required: - - id - - object - - bytes - - created_at - - filename - - purpose - - status - x-oaiMeta: - name: The file object - example: | - { - "id": "file-abc123", - "object": "file", - "bytes": 120000, - "created_at": 1677610602, - "filename": "salesOverview.pdf", - "purpose": "assistants", - } - OtherChunkingStrategyResponseParam: - type: object - title: Other Chunking Strategy - description: This is returned when the chunking strategy is unknown. Typically, - this is because the file was indexed before the `chunking_strategy` - concept was introduced in the API. - additionalProperties: false - properties: - type: - type: string - description: Always `other`. - enum: - - other - x-stainless-const: true - required: - - type - ParallelToolCalls: - description: Whether to enable [parallel function - calling](/docs/guides/function-calling#configuring-parallel-function-calling) - during tool use. - type: boolean - default: true - PredictionContent: - type: object - title: Static Content - description: > - Static predicted output content, such as the content of a text file that - is + type: object + description: Additional details about the status. + properties: + type: + type: string + enum: + - completed + - cancelled + - failed + - incomplete + description: > + The type of error that caused the response to fail, + corresponding + + with the `status` field (`completed`, `cancelled`, + `incomplete`, + + `failed`). + reason: + type: string + enum: + - turn_detected + - client_cancelled + - max_output_tokens + - content_filter + description: > + The reason the Response did not complete. For a `cancelled` + Response, + + one of `turn_detected` (the server VAD detected a new start of + speech) + + or `client_cancelled` (the client sent a cancel event). For an + + `incomplete` Response, one of `max_output_tokens` or + `content_filter` + + (the server-side safety filter activated and cut off the + response). + error: + type: object + description: | + A description of the error that caused the response to fail, + populated when the `status` is `failed`. + properties: + type: + type: string + description: The type of error. + code: + type: string + description: Error code, if any. + output: + type: array + description: The list of output items generated by the response. + items: + $ref: "#/components/schemas/RealtimeConversationItem" + metadata: + $ref: "#/components/schemas/Metadata" + usage: + type: object + description: > + Usage statistics for the Response, this will correspond to billing. + A + + Realtime API session will maintain a conversation context and append + new + + Items to the Conversation, thus output from previous turns (text + and + + audio tokens) will become the input for later turns. + properties: + total_tokens: + type: integer + description: > + The total number of tokens in the Response including input and + output + + text and audio tokens. + input_tokens: + type: integer + description: > + The number of input tokens used in the Response, including text + and + + audio tokens. + output_tokens: + type: integer + description: > + The number of output tokens sent in the Response, including text + and + + audio tokens. + input_token_details: + type: object + description: Details about the input tokens used in the Response. + properties: + cached_tokens: + type: integer + description: The number of cached tokens used in the Response. + text_tokens: + type: integer + description: The number of text tokens used in the Response. + audio_tokens: + type: integer + description: The number of audio tokens used in the Response. + output_token_details: + type: object + description: Details about the output tokens used in the Response. + properties: + text_tokens: + type: integer + description: The number of text tokens used in the Response. + audio_tokens: + type: integer + description: The number of audio tokens used in the Response. + conversation_id: + description: > + Which conversation the response is added to, determined by the + `conversation` - being regenerated. - required: - - type - - content - properties: - type: + field in the `response.create` event. If `auto`, the response will + be added to + + the default conversation and the value of `conversation_id` will be + an id like + + `conv_1234`. If `none`, the response will not be added to any + conversation and + + the value of `conversation_id` will be `null`. If responses are + being triggered + + by server VAD, the response will be added to the default + conversation, thus + + the `conversation_id` will be an id like `conv_1234`. + type: string + voice: type: string enum: - - content - description: | - The type of the predicted content you want to provide. This type is - currently always `content`. - x-stainless-const: true - content: - x-oaiExpandable: true + - alloy + - ash + - ballad + - coral + - echo + - sage + - shimmer + - verse description: > - The content that should be matched when generating a model response. + The voice the model used to respond. - If generated tokens would match this content, the entire model - response + Current voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` + `sage`, - can be returned much more quickly. + `shimmer` and `verse`. + modalities: + type: array + description: > + The set of modalities the model used to respond. If there are + multiple modalities, + + the model will pick one, for example if `modalities` is `["text", + "audio"]`, the model + + could be responding in either text or audio. + items: + type: string + enum: + - text + - audio + output_audio_format: + type: string + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + temperature: + type: number + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. Defaults + to 0.8. + max_output_tokens: oneOf: + - type: integer - type: string - title: Text content - description: | - The content used for a Predicted Output. This is often the - text of a file you are regenerating with minor changes. - - type: array - description: An array of content parts with a defined type. Supported options - differ based on the [model](/docs/models) being used to generate - the response. Can contain text inputs. - title: Array of content parts - items: - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" - minItems: 1 - Project: + enum: + - inf + x-stainless-const: true + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls, that was used in this response. + RealtimeResponseCreateParams: type: object - description: Represents an individual project. + description: Create a new Realtime response with these parameters properties: - id: + modalities: + type: array + description: | + The set of modalities the model can respond with. To disable audio, + set this to ["text"]. + items: + type: string + enum: + - text + - audio + instructions: type: string - description: The identifier, which can be referenced in API endpoints - object: + description: > + The default system instructions (i.e. system message) prepended to + model + + calls. This field allows the client to guide the model on desired + + responses. The model can be instructed on response content and + format, + + (e.g. "be extremely succinct", "act friendly", "here are examples of + good + + responses") and on audio behavior (e.g. "talk quickly", "inject + emotion + + into your voice", "laugh frequently"). The instructions are not + guaranteed + + to be followed by the model, but they provide guidance to the model + on the + + desired behavior. + + + Note that the server sets default instructions which will be used if + this + + field is not set and are visible in the `session.created` event at + the + + start of the session. + voice: type: string enum: - - organization.project - description: The object type, which is always `organization.project` - x-stainless-const: true - name: - type: string - description: The name of the project. This appears in reporting. - created_at: - type: integer - description: The Unix timestamp (in seconds) of when the project was created. - archived_at: - type: integer - nullable: true - description: The Unix timestamp (in seconds) of when the project was archived or - `null`. - status: + - alloy + - ash + - ballad + - coral + - echo + - sage + - shimmer + - verse + description: > + The voice the model uses to respond. Voice cannot be changed during + the + + session once the model has responded with audio at least once. + Current + + voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, + + `shimmer` and `verse`. + output_audio_format: type: string enum: - - active - - archived - description: "`active` or `archived`" - required: - - id - - object - - name - - created_at - - status - x-oaiMeta: - name: The project object - example: | - { - "id": "proj_abc", - "object": "organization.project", - "name": "Project example", - "created_at": 1711471533, - "archived_at": null, - "status": "active" - } - ProjectApiKey: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + tools: + type: array + description: Tools (functions) available to the model. + items: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool, i.e. `function`. + x-stainless-const: true + name: + type: string + description: The name of the function. + description: + type: string + description: > + The description of the function, including guidance on when + and how + + to call it, and guidance about what to tell the user when + calling + + (if anything). + parameters: + type: object + description: Parameters of the function in JSON Schema. + tool_choice: + type: string + description: > + How the model chooses tools. Options are `auto`, `none`, `required`, + or + + specify a function, like `{"type": "function", "function": {"name": + "my_function"}}`. + temperature: + type: number + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. Defaults + to 0.8. + max_response_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + x-stainless-const: true + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. + conversation: + description: > + Controls which conversation the response is added to. Currently + supports + + `auto` and `none`, with `auto` as the default value. The `auto` + value + + means that the contents of the response will be added to the default + + conversation. Set this to `none` to create an out-of-band response + which + + will not add items to default conversation. + oneOf: + - type: string + - type: string + default: auto + enum: + - auto + - none + metadata: + $ref: "#/components/schemas/Metadata" + input: + type: array + description: > + Input items to include in the prompt for the model. Using this field + + creates a new context for this Response instead of using the default + + conversation. An empty array `[]` will clear the context for this + Response. + + Note that this can include references to items from the default + conversation. + items: + $ref: "#/components/schemas/RealtimeConversationItemWithReference" + RealtimeServerEventConversationCreated: type: object - description: Represents an individual API key in a project. + description: > + Returned when a conversation is created. Emitted right after session + creation. properties: - object: + event_id: + type: string + description: The unique ID of the server event. + type: type: string enum: - - organization.project.api_key - description: The object type, which is always `organization.project.api_key` + - conversation.created + description: The event type, must be `conversation.created`. x-stainless-const: true - redacted_value: - type: string - description: The redacted value of the API key - name: - type: string - description: The name of the API key - created_at: - type: integer - description: The Unix timestamp (in seconds) of when the API key was created - id: - type: string - description: The identifier, which can be referenced in API endpoints - owner: + conversation: type: object + description: The conversation resource. properties: - type: + id: type: string - enum: - - user - - service_account - description: "`user` or `service_account`" - user: - $ref: "#/components/schemas/ProjectUser" - service_account: - $ref: "#/components/schemas/ProjectServiceAccount" + description: The unique ID of the conversation. + object: + type: string + description: The object type, must be `realtime.conversation`. required: - - object - - redacted_value - - name - - created_at - - id - - owner + - event_id + - type + - conversation x-oaiMeta: - name: The project API key object + name: conversation.created + group: realtime example: | { - "object": "organization.project.api_key", - "redacted_value": "sk-abc...def", - "name": "My API Key", - "created_at": 1711471533, - "id": "key_abc", - "owner": { - "type": "user", - "user": { - "object": "organization.project.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "created_at": 1711471533 - } + "event_id": "event_9101", + "type": "conversation.created", + "conversation": { + "id": "conv_001", + "object": "realtime.conversation" } } - ProjectApiKeyDeleteResponse: - type: object - properties: - object: - type: string - enum: - - organization.project.api_key.deleted - x-stainless-const: true - id: - type: string - deleted: - type: boolean - required: - - object - - id - - deleted - ProjectApiKeyListResponse: - type: object - properties: - object: - type: string - enum: - - list - x-stainless-const: true - data: - type: array - items: - $ref: "#/components/schemas/ProjectApiKey" - first_id: - type: string - last_id: - type: string - has_more: - type: boolean - required: - - object - - data - - first_id - - last_id - - has_more - ProjectCreateRequest: - type: object - properties: - name: - type: string - description: The friendly name of the project, this name appears in reports. - required: - - name - ProjectListResponse: + RealtimeServerEventConversationItemCreated: type: object + description: > + Returned when a conversation item is created. There are several + scenarios that + + produce this event: + - The server is generating a Response, which if successful will produce + either one or two Items, which will be of type `message` + (role `assistant`) or type `function_call`. + - The input audio buffer has been committed, either by the client or the + server (in `server_vad` mode). The server will take the content of the + input audio buffer and add it to a new user message Item. + - The client has sent a `conversation.item.create` event to add a new Item + to the Conversation. properties: - object: - type: string - enum: - - list - x-stainless-const: true - data: - type: array - items: - $ref: "#/components/schemas/Project" - first_id: - type: string - last_id: + event_id: type: string - has_more: - type: boolean - required: - - object - - data - - first_id - - last_id - - has_more - ProjectRateLimit: - type: object - description: Represents a project rate limit config. - properties: - object: + description: The unique ID of the server event. + type: type: string enum: - - project.rate_limit - description: The object type, which is always `project.rate_limit` + - conversation.item.created + description: The event type, must be `conversation.item.created`. x-stainless-const: true - id: - type: string - description: The identifier, which can be referenced in API endpoints. - model: + previous_item_id: type: string - description: The model this rate limit applies to. - max_requests_per_1_minute: - type: integer - description: The maximum requests per minute. - max_tokens_per_1_minute: - type: integer - description: The maximum tokens per minute. - max_images_per_1_minute: - type: integer - description: The maximum images per minute. Only present for relevant models. - max_audio_megabytes_per_1_minute: - type: integer - description: The maximum audio megabytes per minute. Only present for relevant - models. - max_requests_per_1_day: - type: integer - description: The maximum requests per day. Only present for relevant models. - batch_1_day_max_input_tokens: - type: integer - description: The maximum batch input tokens per day. Only present for relevant - models. + description: > + The ID of the preceding item in the Conversation context, allows + the + + client to understand the order of the conversation. + item: + $ref: "#/components/schemas/RealtimeConversationItem" required: - - object - - id - - model - - max_requests_per_1_minute - - max_tokens_per_1_minute + - event_id + - type + - previous_item_id + - item x-oaiMeta: - name: The project rate limit object + name: conversation.item.created + group: realtime example: | { - "object": "project.rate_limit", - "id": "rl_ada", - "model": "ada", - "max_requests_per_1_minute": 600, - "max_tokens_per_1_minute": 150000, - "max_images_per_1_minute": 10 + "event_id": "event_1920", + "type": "conversation.item.created", + "previous_item_id": "msg_002", + "item": { + "id": "msg_003", + "object": "realtime.item", + "type": "message", + "status": "completed", + "role": "user", + "content": [ + { + "type": "input_audio", + "transcript": "hello how are you", + "audio": "base64encodedaudio==" + } + ] + } } - ProjectRateLimitListResponse: + RealtimeServerEventConversationItemDeleted: type: object + description: > + Returned when an item in the conversation is deleted by the client with + a + + `conversation.item.delete` event. This event is used to synchronize the + + server's understanding of the conversation history with the client's + view. properties: - object: + event_id: + type: string + description: The unique ID of the server event. + type: type: string enum: - - list + - conversation.item.deleted + description: The event type, must be `conversation.item.deleted`. x-stainless-const: true - data: - type: array - items: - $ref: "#/components/schemas/ProjectRateLimit" - first_id: - type: string - last_id: + item_id: type: string - has_more: - type: boolean + description: The ID of the item that was deleted. required: - - object - - data - - first_id - - last_id - - has_more - ProjectRateLimitUpdateRequest: - type: object - properties: - max_requests_per_1_minute: - type: integer - description: The maximum requests per minute. - max_tokens_per_1_minute: - type: integer - description: The maximum tokens per minute. - max_images_per_1_minute: - type: integer - description: The maximum images per minute. Only relevant for certain models. - max_audio_megabytes_per_1_minute: - type: integer - description: The maximum audio megabytes per minute. Only relevant for certain - models. - max_requests_per_1_day: - type: integer - description: The maximum requests per day. Only relevant for certain models. - batch_1_day_max_input_tokens: - type: integer - description: The maximum batch input tokens per day. Only relevant for certain - models. - ProjectServiceAccount: + - event_id + - type + - item_id + x-oaiMeta: + name: conversation.item.deleted + group: realtime + example: | + { + "event_id": "event_2728", + "type": "conversation.item.deleted", + "item_id": "msg_005" + } + RealtimeServerEventConversationItemInputAudioTranscriptionCompleted: type: object - description: Represents an individual service account in a project. + description: > + This event is the output of audio transcription for user audio written + to the + + user audio buffer. Transcription begins when the input audio buffer is + + committed by the client or server (in `server_vad` mode). Transcription + runs + + asynchronously with Response creation, so this event may come before or + after + + the Response events. + + + Realtime API models accept audio natively, and thus input transcription + is a + + separate process run on a separate ASR (Automatic Speech Recognition) + model, + + currently always `whisper-1`. Thus the transcript may diverge somewhat + from + + the model's interpretation, and should be treated as a rough guide. properties: - object: + event_id: + type: string + description: The unique ID of the server event. + type: type: string enum: - - organization.project.service_account - description: The object type, which is always - `organization.project.service_account` + - conversation.item.input_audio_transcription.completed + description: | + The event type, must be + `conversation.item.input_audio_transcription.completed`. x-stainless-const: true - id: - type: string - description: The identifier, which can be referenced in API endpoints - name: - type: string - description: The name of the service account - role: + item_id: type: string - enum: - - owner - - member - description: "`owner` or `member`" - created_at: + description: The ID of the user message item containing the audio. + content_index: type: integer - description: The Unix timestamp (in seconds) of when the service account was - created + description: The index of the content part containing the audio. + transcript: + type: string + description: The transcribed text. required: - - object - - id - - name - - role - - created_at + - event_id + - type + - item_id + - content_index + - transcript x-oaiMeta: - name: The project service account object + name: conversation.item.input_audio_transcription.completed + group: realtime example: | { - "object": "organization.project.service_account", - "id": "svc_acct_abc", - "name": "Service Account", - "role": "owner", - "created_at": 1711471533 + "event_id": "event_2122", + "type": "conversation.item.input_audio_transcription.completed", + "item_id": "msg_003", + "content_index": 0, + "transcript": "Hello, how are you?" } - ProjectServiceAccountApiKey: + RealtimeServerEventConversationItemInputAudioTranscriptionFailed: type: object + description: > + Returned when input audio transcription is configured, and a + transcription + + request for a user message failed. These events are separate from other + + `error` events so that the client can identify the related Item. properties: - object: + event_id: + type: string + description: The unique ID of the server event. + type: type: string enum: - - organization.project.service_account.api_key - description: The object type, which is always - `organization.project.service_account.api_key` + - conversation.item.input_audio_transcription.failed + description: | + The event type, must be + `conversation.item.input_audio_transcription.failed`. x-stainless-const: true - value: - type: string - name: + item_id: type: string - created_at: + description: The ID of the user message item. + content_index: type: integer - id: - type: string - required: - - object - - value - - name - - created_at - - id - ProjectServiceAccountCreateRequest: - type: object - properties: - name: - type: string - description: The name of the service account being created. + description: The index of the content part containing the audio. + error: + type: object + description: Details of the transcription error. + properties: + type: + type: string + description: The type of error. + code: + type: string + description: Error code, if any. + message: + type: string + description: A human-readable error message. + param: + type: string + description: Parameter related to the error, if any. required: - - name - ProjectServiceAccountCreateResponse: + - event_id + - type + - item_id + - content_index + - error + x-oaiMeta: + name: conversation.item.input_audio_transcription.failed + group: realtime + example: | + { + "event_id": "event_2324", + "type": "conversation.item.input_audio_transcription.failed", + "item_id": "msg_003", + "content_index": 0, + "error": { + "type": "transcription_error", + "code": "audio_unintelligible", + "message": "The audio could not be transcribed.", + "param": null + } + } + RealtimeServerEventConversationItemTruncated: type: object + description: > + Returned when an earlier assistant audio message item is truncated by + the + + client with a `conversation.item.truncate` event. This event is used to + + synchronize the server's understanding of the audio with the client's + playback. + + + This action will truncate the audio and remove the server-side text + transcript + + to ensure there is no text in the context that hasn't been heard by the + user. properties: - object: - type: string - enum: - - organization.project.service_account - x-stainless-const: true - id: - type: string - name: + event_id: type: string - role: + description: The unique ID of the server event. + type: type: string enum: - - member - description: Service accounts can only have one role of type `member` + - conversation.item.truncated + description: The event type, must be `conversation.item.truncated`. x-stainless-const: true - created_at: + item_id: + type: string + description: The ID of the assistant message item that was truncated. + content_index: type: integer - api_key: - $ref: "#/components/schemas/ProjectServiceAccountApiKey" + description: The index of the content part that was truncated. + audio_end_ms: + type: integer + description: | + The duration up to which the audio was truncated, in milliseconds. required: - - object - - id - - name - - role - - created_at - - api_key - ProjectServiceAccountDeleteResponse: + - event_id + - type + - item_id + - content_index + - audio_end_ms + x-oaiMeta: + name: conversation.item.truncated + group: realtime + example: | + { + "event_id": "event_2526", + "type": "conversation.item.truncated", + "item_id": "msg_004", + "content_index": 0, + "audio_end_ms": 1500 + } + RealtimeServerEventError: type: object + description: > + Returned when an error occurs, which could be a client problem or a + server + + problem. Most errors are recoverable and the session will stay open, we + + recommend to implementors to monitor and log error messages by default. properties: - object: + event_id: + type: string + description: The unique ID of the server event. + type: type: string enum: - - organization.project.service_account.deleted + - error + description: The event type, must be `error`. x-stainless-const: true - id: - type: string - deleted: - type: boolean + error: + type: object + description: Details of the error. + required: + - type + - message + properties: + type: + type: string + description: > + The type of error (e.g., "invalid_request_error", + "server_error"). + code: + type: string + description: Error code, if any. + nullable: true + message: + type: string + description: A human-readable error message. + param: + type: string + description: Parameter related to the error, if any. + nullable: true + event_id: + type: string + description: > + The event_id of the client event that caused the error, if + applicable. + nullable: true required: - - object - - id - - deleted - ProjectServiceAccountListResponse: + - event_id + - type + - error + x-oaiMeta: + name: error + group: realtime + example: | + { + "event_id": "event_890", + "type": "error", + "error": { + "type": "invalid_request_error", + "code": "invalid_event", + "message": "The 'type' field is missing.", + "param": null, + "event_id": "event_567" + } + } + RealtimeServerEventInputAudioBufferCleared: type: object + description: | + Returned when the input audio buffer is cleared by the client with a + `input_audio_buffer.clear` event. properties: - object: + event_id: + type: string + description: The unique ID of the server event. + type: type: string enum: - - list + - input_audio_buffer.cleared + description: The event type, must be `input_audio_buffer.cleared`. x-stainless-const: true - data: - type: array - items: - $ref: "#/components/schemas/ProjectServiceAccount" - first_id: - type: string - last_id: - type: string - has_more: - type: boolean required: - - object - - data - - first_id - - last_id - - has_more - ProjectUpdateRequest: + - event_id + - type + x-oaiMeta: + name: input_audio_buffer.cleared + group: realtime + example: | + { + "event_id": "event_1314", + "type": "input_audio_buffer.cleared" + } + RealtimeServerEventInputAudioBufferCommitted: type: object + description: > + Returned when an input audio buffer is committed, either by the client + or + + automatically in server VAD mode. The `item_id` property is the ID of + the user + + message item that will be created, thus a `conversation.item.created` + event + + will also be sent to the client. properties: - name: + event_id: type: string - description: The updated name of the project, this name appears in reports. - required: - - name - ProjectUser: - type: object - description: Represents an individual user in a project. - properties: - object: + description: The unique ID of the server event. + type: type: string enum: - - organization.project.user - description: The object type, which is always `organization.project.user` + - input_audio_buffer.committed + description: The event type, must be `input_audio_buffer.committed`. x-stainless-const: true - id: + previous_item_id: type: string - description: The identifier, which can be referenced in API endpoints - name: + description: > + The ID of the preceding item after which the new item will be + inserted. + item_id: type: string - description: The name of the user - email: + description: The ID of the user message item that will be created. + required: + - event_id + - type + - previous_item_id + - item_id + x-oaiMeta: + name: input_audio_buffer.committed + group: realtime + example: | + { + "event_id": "event_1121", + "type": "input_audio_buffer.committed", + "previous_item_id": "msg_001", + "item_id": "msg_002" + } + RealtimeServerEventInputAudioBufferSpeechStarted: + type: object + description: > + Sent by the server when in `server_vad` mode to indicate that speech has + been + + detected in the audio buffer. This can happen any time audio is added to + the + + buffer (unless speech is already detected). The client may want to use + this + + event to interrupt audio playback or provide visual feedback to the + user. + + + The client should expect to receive a + `input_audio_buffer.speech_stopped` event + + when speech stops. The `item_id` property is the ID of the user message + item + + that will be created when speech stops and will also be included in the + + `input_audio_buffer.speech_stopped` event (unless the client manually + commits + + the audio buffer during VAD activation). + properties: + event_id: type: string - description: The email address of the user - role: + description: The unique ID of the server event. + type: type: string enum: - - owner - - member - description: "`owner` or `member`" - added_at: + - input_audio_buffer.speech_started + description: The event type, must be `input_audio_buffer.speech_started`. + x-stainless-const: true + audio_start_ms: type: integer - description: The Unix timestamp (in seconds) of when the project was added. + description: > + Milliseconds from the start of all audio written to the buffer + during the + + session when speech was first detected. This will correspond to the + + beginning of audio sent to the model, and thus includes the + + `prefix_padding_ms` configured in the Session. + item_id: + type: string + description: > + The ID of the user message item that will be created when speech + stops. required: - - object - - id - - name - - email - - role - - added_at + - event_id + - type + - audio_start_ms + - item_id x-oaiMeta: - name: The project user object + name: input_audio_buffer.speech_started + group: realtime example: | { - "object": "organization.project.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 + "event_id": "event_1516", + "type": "input_audio_buffer.speech_started", + "audio_start_ms": 1000, + "item_id": "msg_003" } - ProjectUserCreateRequest: + RealtimeServerEventInputAudioBufferSpeechStopped: type: object + description: > + Returned in `server_vad` mode when the server detects the end of speech + in + + the audio buffer. The server will also send an + `conversation.item.created` + + event with the user message item that is created from the audio buffer. properties: - user_id: - type: string - description: The ID of the user. - role: + event_id: type: string - enum: - - owner - - member - description: "`owner` or `member`" - required: - - user_id - - role - ProjectUserDeleteResponse: - type: object - properties: - object: + description: The unique ID of the server event. + type: type: string enum: - - organization.project.user.deleted + - input_audio_buffer.speech_stopped + description: The event type, must be `input_audio_buffer.speech_stopped`. x-stainless-const: true - id: + audio_end_ms: + type: integer + description: > + Milliseconds since the session started when speech stopped. This + will + + correspond to the end of audio sent to the model, and thus includes + the + + `min_silence_duration_ms` configured in the Session. + item_id: type: string - deleted: - type: boolean + description: The ID of the user message item that will be created. required: - - object - - id - - deleted - ProjectUserListResponse: + - event_id + - type + - audio_end_ms + - item_id + x-oaiMeta: + name: input_audio_buffer.speech_stopped + group: realtime + example: | + { + "event_id": "event_1718", + "type": "input_audio_buffer.speech_stopped", + "audio_end_ms": 2000, + "item_id": "msg_003" + } + RealtimeServerEventRateLimitsUpdated: type: object + description: > + Emitted at the beginning of a Response to indicate the updated rate + limits. + + When a Response is created some tokens will be "reserved" for the + output + + tokens, the rate limits shown here reflect that reservation, which is + then + + adjusted accordingly once the Response is completed. properties: - object: - type: string - data: - type: array - items: - $ref: "#/components/schemas/ProjectUser" - first_id: - type: string - last_id: + event_id: type: string - has_more: - type: boolean - required: - - object - - data - - first_id - - last_id - - has_more - ProjectUserUpdateRequest: - type: object - properties: - role: + description: The unique ID of the server event. + type: type: string enum: - - owner - - member - description: "`owner` or `member`" + - rate_limits.updated + description: The event type, must be `rate_limits.updated`. + x-stainless-const: true + rate_limits: + type: array + description: List of rate limit information. + items: + type: object + properties: + name: + type: string + enum: + - requests + - tokens + description: | + The name of the rate limit (`requests`, `tokens`). + limit: + type: integer + description: The maximum allowed value for the rate limit. + remaining: + type: integer + description: The remaining value before the limit is reached. + reset_seconds: + type: number + description: Seconds until the rate limit resets. required: - - role - RealtimeClientEventConversationItemCreate: + - event_id + - type + - rate_limits + x-oaiMeta: + name: rate_limits.updated + group: realtime + example: | + { + "event_id": "event_5758", + "type": "rate_limits.updated", + "rate_limits": [ + { + "name": "requests", + "limit": 1000, + "remaining": 999, + "reset_seconds": 60 + }, + { + "name": "tokens", + "limit": 50000, + "remaining": 49950, + "reset_seconds": 60 + } + ] + } + RealtimeServerEventResponseAudioDelta: type: object - description: > - Add a new Item to the Conversation's context, including messages, - function - - calls, and function call responses. This event can be used both to - populate a - - "history" of the conversation and to add new items mid-stream, but has - the - - current limitation that it cannot populate assistant audio messages. - - - If successful, the server will respond with a - `conversation.item.created` - - event, otherwise an `error` event will be sent. + description: Returned when the model-generated audio is updated. properties: event_id: type: string - description: Optional client-generated ID used to identify this event. + description: The unique ID of the server event. type: type: string enum: - - conversation.item.create - description: The event type, must be `conversation.item.create`. + - response.audio.delta + description: The event type, must be `response.audio.delta`. x-stainless-const: true - previous_item_id: - type: string - description: > - The ID of the preceding item after which the new item will be - inserted. - - If not set, the new item will be appended to the end of the - conversation. - - If set to `root`, the new item will be added to the beginning of the - conversation. - - If set to an existing ID, it allows an item to be inserted - mid-conversation. If the - - ID cannot be found, an error will be returned and the item will not - be added. - item: - $ref: "#/components/schemas/RealtimeConversationItem" + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + delta: + type: string + description: Base64-encoded audio data delta. required: + - event_id - type - - item + - response_id + - item_id + - output_index + - content_index + - delta x-oaiMeta: - name: conversation.item.create + name: response.audio.delta group: realtime example: | { - "event_id": "event_345", - "type": "conversation.item.create", - "previous_item_id": null, - "item": { - "id": "msg_001", - "type": "message", - "role": "user", - "content": [ - { - "type": "input_text", - "text": "Hello, how are you?" - } - ] - } + "event_id": "event_4950", + "type": "response.audio.delta", + "response_id": "resp_001", + "item_id": "msg_008", + "output_index": 0, + "content_index": 0, + "delta": "Base64EncodedAudioDelta" } - RealtimeClientEventConversationItemDelete: + RealtimeServerEventResponseAudioDone: type: object description: > - Send this event when you want to remove any item from the conversation - - history. The server will respond with a `conversation.item.deleted` - event, - - unless the item does not exist in the conversation history, in which - case the + Returned when the model-generated audio is done. Also emitted when a + Response - server will respond with an error. + is interrupted, incomplete, or cancelled. properties: event_id: type: string - description: Optional client-generated ID used to identify this event. + description: The unique ID of the server event. type: type: string enum: - - conversation.item.delete - description: The event type, must be `conversation.item.delete`. + - response.audio.done + description: The event type, must be `response.audio.done`. x-stainless-const: true + response_id: + type: string + description: The ID of the response. item_id: type: string - description: The ID of the item to delete. + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. required: + - event_id - type + - response_id - item_id + - output_index + - content_index x-oaiMeta: - name: conversation.item.delete + name: response.audio.done group: realtime example: | { - "event_id": "event_901", - "type": "conversation.item.delete", - "item_id": "msg_003" + "event_id": "event_5152", + "type": "response.audio.done", + "response_id": "resp_001", + "item_id": "msg_008", + "output_index": 0, + "content_index": 0 } - RealtimeClientEventConversationItemTruncate: + RealtimeServerEventResponseAudioTranscriptDelta: type: object description: > - Send this event to truncate a previous assistant message’s audio. The - server - - will produce audio faster than realtime, so this event is useful when - the user - - interrupts to truncate audio that has already been sent to the client - but not - - yet played. This will synchronize the server's understanding of the - audio with - - the client's playback. - - - Truncating audio will delete the server-side text transcript to ensure - there - - is not text in the context that hasn't been heard by the user. - - - If successful, the server will respond with a - `conversation.item.truncated` - - event. + Returned when the model-generated transcription of audio output is + updated. properties: event_id: type: string - description: Optional client-generated ID used to identify this event. + description: The unique ID of the server event. type: type: string enum: - - conversation.item.truncate - description: The event type, must be `conversation.item.truncate`. + - response.audio_transcript.delta + description: The event type, must be `response.audio_transcript.delta`. x-stainless-const: true + response_id: + type: string + description: The ID of the response. item_id: type: string - description: > - The ID of the assistant message item to truncate. Only assistant - message - - items can be truncated. - content_index: + description: The ID of the item. + output_index: type: integer - description: The index of the content part to truncate. Set this to 0. - audio_end_ms: + description: The index of the output item in the response. + content_index: type: integer - description: > - Inclusive duration up to which audio is truncated, in milliseconds. - If - - the audio_end_ms is greater than the actual audio duration, the - server - - will respond with an error. + description: The index of the content part in the item's content array. + delta: + type: string + description: The transcript delta. required: + - event_id - type + - response_id - item_id + - output_index - content_index - - audio_end_ms + - delta x-oaiMeta: - name: conversation.item.truncate + name: response.audio_transcript.delta group: realtime example: | { - "event_id": "event_678", - "type": "conversation.item.truncate", - "item_id": "msg_002", + "event_id": "event_4546", + "type": "response.audio_transcript.delta", + "response_id": "resp_001", + "item_id": "msg_008", + "output_index": 0, "content_index": 0, - "audio_end_ms": 1500 + "delta": "Hello, how can I a" } - RealtimeClientEventInputAudioBufferAppend: + RealtimeServerEventResponseAudioTranscriptDone: type: object - description: > - Send this event to append audio bytes to the input audio buffer. The - audio - - buffer is temporary storage you can write to and later commit. In Server - VAD - - mode, the audio buffer is used to detect speech and the server will - decide - - when to commit. When Server VAD is disabled, you must commit the audio - buffer - - manually. - - - The client may choose how much audio to place in each event up to a - maximum - - of 15 MiB, for example streaming smaller chunks from the client may - allow the - - VAD to be more responsive. Unlike made other client events, the server - will - - not send a confirmation response to this event. + description: | + Returned when the model-generated transcription of audio output is done + streaming. Also emitted when a Response is interrupted, incomplete, or + cancelled. properties: event_id: type: string - description: Optional client-generated ID used to identify this event. + description: The unique ID of the server event. type: type: string enum: - - input_audio_buffer.append - description: The event type, must be `input_audio_buffer.append`. + - response.audio_transcript.done + description: The event type, must be `response.audio_transcript.done`. x-stainless-const: true - audio: + response_id: type: string - description: > - Base64-encoded audio bytes. This must be in the format specified by - the - - `input_audio_format` field in the session configuration. + description: The ID of the response. + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + transcript: + type: string + description: The final transcript of the audio. required: + - event_id - type - - audio + - response_id + - item_id + - output_index + - content_index + - transcript x-oaiMeta: - name: input_audio_buffer.append + name: response.audio_transcript.done group: realtime example: | { - "event_id": "event_456", - "type": "input_audio_buffer.append", - "audio": "Base64EncodedAudioData" + "event_id": "event_4748", + "type": "response.audio_transcript.done", + "response_id": "resp_001", + "item_id": "msg_008", + "output_index": 0, + "content_index": 0, + "transcript": "Hello, how can I assist you today?" } - RealtimeClientEventInputAudioBufferClear: + RealtimeServerEventResponseContentPartAdded: type: object - description: | - Send this event to clear the audio bytes in the buffer. The server will - respond with an `input_audio_buffer.cleared` event. + description: > + Returned when a new content part is added to an assistant message item + during + + response generation. properties: event_id: type: string - description: Optional client-generated ID used to identify this event. + description: The unique ID of the server event. type: type: string enum: - - input_audio_buffer.clear - description: The event type, must be `input_audio_buffer.clear`. + - response.content_part.added + description: The event type, must be `response.content_part.added`. x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the item to which the content part was added. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + part: + type: object + description: The content part that was added. + properties: + type: + type: string + enum: + - audio + - text + description: The content type ("text", "audio"). + text: + type: string + description: The text content (if type is "text"). + audio: + type: string + description: Base64-encoded audio data (if type is "audio"). + transcript: + type: string + description: The transcript of the audio (if type is "audio"). required: + - event_id - type + - response_id + - item_id + - output_index + - content_index + - part x-oaiMeta: - name: input_audio_buffer.clear + name: response.content_part.added group: realtime example: | { - "event_id": "event_012", - "type": "input_audio_buffer.clear" + "event_id": "event_3738", + "type": "response.content_part.added", + "response_id": "resp_001", + "item_id": "msg_007", + "output_index": 0, + "content_index": 0, + "part": { + "type": "text", + "text": "" + } } - RealtimeClientEventInputAudioBufferCommit: + RealtimeServerEventResponseContentPartDone: type: object description: > - Send this event to commit the user input audio buffer, which will create - a - - new user message item in the conversation. This event will produce an - error - - if the input audio buffer is empty. When in Server VAD mode, the client - does - - not need to send this event, the server will commit the audio buffer - - automatically. - - - Committing the input audio buffer will trigger input audio - transcription - - (if enabled in session configuration), but it will not create a - response - - from the model. The server will respond with an - `input_audio_buffer.committed` + Returned when a content part is done streaming in an assistant message + item. - event. + Also emitted when a Response is interrupted, incomplete, or cancelled. properties: event_id: type: string - description: Optional client-generated ID used to identify this event. + description: The unique ID of the server event. type: type: string enum: - - input_audio_buffer.commit - description: The event type, must be `input_audio_buffer.commit`. + - response.content_part.done + description: The event type, must be `response.content_part.done`. x-stainless-const: true + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + part: + type: object + description: The content part that is done. + properties: + type: + type: string + enum: + - audio + - text + description: The content type ("text", "audio"). + text: + type: string + description: The text content (if type is "text"). + audio: + type: string + description: Base64-encoded audio data (if type is "audio"). + transcript: + type: string + description: The transcript of the audio (if type is "audio"). required: + - event_id - type + - response_id + - item_id + - output_index + - content_index + - part x-oaiMeta: - name: input_audio_buffer.commit + name: response.content_part.done group: realtime example: | { - "event_id": "event_789", - "type": "input_audio_buffer.commit" + "event_id": "event_3940", + "type": "response.content_part.done", + "response_id": "resp_001", + "item_id": "msg_007", + "output_index": 0, + "content_index": 0, + "part": { + "type": "text", + "text": "Sure, I can help with that." + } } - RealtimeClientEventResponseCancel: + RealtimeServerEventResponseCreated: type: object description: > - Send this event to cancel an in-progress response. The server will - respond - - with a `response.cancelled` event or an error if there is no response - to + Returned when a new Response is created. The first event of response + creation, - cancel. + where the response is in an initial state of `in_progress`. properties: event_id: type: string - description: Optional client-generated ID used to identify this event. + description: The unique ID of the server event. type: type: string enum: - - response.cancel - description: The event type, must be `response.cancel`. + - response.created + description: The event type, must be `response.created`. x-stainless-const: true - response_id: - type: string - description: | - A specific response ID to cancel - if not provided, will cancel an - in-progress response in the default conversation. + response: + $ref: "#/components/schemas/RealtimeResponse" required: + - event_id - type + - response x-oaiMeta: - name: response.cancel + name: response.created group: realtime example: | { - "event_id": "event_567", - "type": "response.cancel" + "event_id": "event_2930", + "type": "response.created", + "response": { + "id": "resp_001", + "object": "realtime.response", + "status": "in_progress", + "status_details": null, + "output": [], + "usage": null + } } - RealtimeClientEventResponseCreate: + RealtimeServerEventResponseDone: type: object description: > - This event instructs the server to create a Response, which means - triggering - - model inference. When in Server VAD mode, the server will create - Responses - - automatically. - - - A Response will include at least one Item, and may have two, in which - case - - the second will be a function call. These Items will be appended to the - - conversation history. - - - The server will respond with a `response.created` event, events for - Items - - and content created, and finally a `response.done` event to indicate + Returned when a Response is done streaming. Always emitted, no matter the - Response is complete. - - - The `response.create` event includes inference configuration like - - `instructions`, and `temperature`. These fields will override the - Session's + final state. The Response object included in the `response.done` event + will - configuration for this Response only. + include all output Items in the Response but will omit the raw audio + data. properties: event_id: type: string - description: Optional client-generated ID used to identify this event. + description: The unique ID of the server event. type: type: string enum: - - response.create - description: The event type, must be `response.create`. + - response.done + description: The event type, must be `response.done`. x-stainless-const: true response: - $ref: "#/components/schemas/RealtimeResponseCreateParams" + $ref: "#/components/schemas/RealtimeResponse" required: + - event_id - type + - response x-oaiMeta: - name: response.create + name: response.done group: realtime example: | { - "event_id": "event_234", - "type": "response.create", + "event_id": "event_3132", + "type": "response.done", "response": { - "modalities": ["text", "audio"], - "instructions": "Please assist the user.", - "voice": "sage", - "output_audio_format": "pcm16", - "tools": [ + "id": "resp_001", + "object": "realtime.response", + "status": "completed", + "status_details": null, + "output": [ { - "type": "function", - "name": "calculate_sum", - "description": "Calculates the sum of two numbers.", - "parameters": { - "type": "object", - "properties": { - "a": { "type": "number" }, - "b": { "type": "number" } - }, - "required": ["a", "b"] - } + "id": "msg_006", + "object": "realtime.item", + "type": "message", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "Sure, how can I assist you today?" + } + ] } ], - "tool_choice": "auto", - "temperature": 0.8, - "max_output_tokens": 1024 + "usage": { + "total_tokens":275, + "input_tokens":127, + "output_tokens":148, + "input_token_details": { + "cached_tokens":384, + "text_tokens":119, + "audio_tokens":8, + "cached_tokens_details": { + "text_tokens": 128, + "audio_tokens": 256 + } + }, + "output_token_details": { + "text_tokens":36, + "audio_tokens":112 + } + } } } - RealtimeClientEventSessionUpdate: + RealtimeServerEventResponseFunctionCallArgumentsDelta: type: object - description: > - Send this event to update the session’s default configuration. The - client may - - send this event at any time to update the session configuration, and - any - - field may be updated at any time, except for "voice". The server will - respond - - with a `session.updated` event that shows the full effective - configuration. - - Only fields that are present are updated, thus the correct way to clear - a - - field like "instructions" is to pass an empty string. + description: | + Returned when the model-generated function call arguments are updated. properties: event_id: type: string - description: Optional client-generated ID used to identify this event. + description: The unique ID of the server event. type: type: string enum: - - session.update - description: The event type, must be `session.update`. + - response.function_call_arguments.delta + description: | + The event type, must be `response.function_call_arguments.delta`. x-stainless-const: true - session: - $ref: "#/components/schemas/RealtimeSessionCreateRequest" + response_id: + type: string + description: The ID of the response. + item_id: + type: string + description: The ID of the function call item. + output_index: + type: integer + description: The index of the output item in the response. + call_id: + type: string + description: The ID of the function call. + delta: + type: string + description: The arguments delta as a JSON string. required: + - event_id - type - - session + - response_id + - item_id + - output_index + - call_id + - delta x-oaiMeta: - name: session.update + name: response.function_call_arguments.delta group: realtime example: | { - "event_id": "event_123", - "type": "session.update", - "session": { - "modalities": ["text", "audio"], - "instructions": "You are a helpful assistant.", - "voice": "sage", - "input_audio_format": "pcm16", - "output_audio_format": "pcm16", - "input_audio_transcription": { - "model": "whisper-1" - }, - "turn_detection": { - "type": "server_vad", - "threshold": 0.5, - "prefix_padding_ms": 300, - "silence_duration_ms": 500, - "create_response": true - }, - "tools": [ - { - "type": "function", - "name": "get_weather", - "description": "Get the current weather...", - "parameters": { - "type": "object", - "properties": { - "location": { "type": "string" } - }, - "required": ["location"] - } - } - ], - "tool_choice": "auto", - "temperature": 0.8, - "max_response_output_tokens": "inf" - } + "event_id": "event_5354", + "type": "response.function_call_arguments.delta", + "response_id": "resp_002", + "item_id": "fc_001", + "output_index": 0, + "call_id": "call_001", + "delta": "{\"location\": \"San\"" } - RealtimeConversationItem: + RealtimeServerEventResponseFunctionCallArgumentsDone: type: object - x-oaiExpandable: true - description: The item to add to the conversation. + description: > + Returned when the model-generated function call arguments are done + streaming. + + Also emitted when a Response is interrupted, incomplete, or cancelled. properties: - id: + event_id: type: string - description: > - The unique ID of the item, this can be generated by the client to - help - - manage server-side context, but is not required because the server - will - - generate one if not provided. + description: The unique ID of the server event. type: type: string enum: - - message - - function_call - - function_call_output - description: > - The type of the item (`message`, `function_call`, - `function_call_output`). - object: - type: string - enum: - - realtime.item - description: > - Identifier for the API object being returned - always - `realtime.item`. + - response.function_call_arguments.done + description: | + The event type, must be `response.function_call_arguments.done`. x-stainless-const: true - status: + response_id: type: string - enum: - - completed - - incomplete - description: > - The status of the item (`completed`, `incomplete`). These have no - effect - - on the conversation, but are accepted for consistency with the - - `conversation.item.created` event. - role: + description: The ID of the response. + item_id: type: string - enum: - - user - - assistant - - system - description: > - The role of the message sender (`user`, `assistant`, `system`), - only - - applicable for `message` items. - content: - type: array - x-oaiExpandable: true - description: > - The content of the message, applicable for `message` items. - - - Message items of role `system` support only `input_text` content - - - Message items of role `user` support `input_text` and - `input_audio` - content - - Message items of role `assistant` support `text` content. - items: - type: object - x-oaiExpandable: true - properties: - type: - type: string - enum: - - input_audio - - input_text - - item_reference - - text - description: > - The content type (`input_text`, `input_audio`, - `item_reference`, `text`). - text: - type: string - description: > - The text content, used for `input_text` and `text` content - types. - id: - type: string - description: > - ID of a previous conversation item to reference (for - `item_reference` - - content types in `response.create` events). These can - reference both - - client and server created items. - audio: - type: string - description: > - Base64-encoded audio bytes, used for `input_audio` content - type. - transcript: - type: string - description: > - The transcript of the audio, used for `input_audio` content - type. + description: The ID of the function call item. + output_index: + type: integer + description: The index of the output item in the response. call_id: type: string - description: > - The ID of the function call (for `function_call` and - - `function_call_output` items). If passed on a - `function_call_output` - - item, the server will check that a `function_call` item with the - same - - ID exists in the conversation history. - name: + description: The ID of the function call. + arguments: + type: string + description: The final arguments as a JSON string. + required: + - event_id + - type + - response_id + - item_id + - output_index + - call_id + - arguments + x-oaiMeta: + name: response.function_call_arguments.done + group: realtime + example: | + { + "event_id": "event_5556", + "type": "response.function_call_arguments.done", + "response_id": "resp_002", + "item_id": "fc_001", + "output_index": 0, + "call_id": "call_001", + "arguments": "{\"location\": \"San Francisco\"}" + } + RealtimeServerEventResponseOutputItemAdded: + type: object + description: Returned when a new Item is created during Response generation. + properties: + event_id: type: string - description: | - The name of the function being called (for `function_call` items). - arguments: + description: The unique ID of the server event. + type: type: string - description: | - The arguments of the function call (for `function_call` items). - output: + enum: + - response.output_item.added + description: The event type, must be `response.output_item.added`. + x-stainless-const: true + response_id: type: string - description: | - The output of the function call (for `function_call_output` items). - RealtimeConversationItemWithReference: + description: The ID of the Response to which the item belongs. + output_index: + type: integer + description: The index of the output item in the Response. + item: + $ref: "#/components/schemas/RealtimeConversationItem" + required: + - event_id + - type + - response_id + - output_index + - item + x-oaiMeta: + name: response.output_item.added + group: realtime + example: | + { + "event_id": "event_3334", + "type": "response.output_item.added", + "response_id": "resp_001", + "output_index": 0, + "item": { + "id": "msg_007", + "object": "realtime.item", + "type": "message", + "status": "in_progress", + "role": "assistant", + "content": [] + } + } + RealtimeServerEventResponseOutputItemDone: type: object - x-oaiExpandable: true - description: The item to add to the conversation. + description: > + Returned when an Item is done streaming. Also emitted when a Response + is + + interrupted, incomplete, or cancelled. properties: - id: + event_id: type: string - description: > - For an item of type (`message` | `function_call` | - `function_call_output`) - - this field allows the client to assign the unique ID of the item. It - is - - not required because the server will generate one if not provided. - - - For an item of type `item_reference`, this field is required and is - a - - reference to any item that has previously existed in the - conversation. + description: The unique ID of the server event. type: type: string enum: - - message - - function_call - - function_call_output - description: > - The type of the item (`message`, `function_call`, - `function_call_output`, `item_reference`). - object: + - response.output_item.done + description: The event type, must be `response.output_item.done`. + x-stainless-const: true + response_id: + type: string + description: The ID of the Response to which the item belongs. + output_index: + type: integer + description: The index of the output item in the Response. + item: + $ref: "#/components/schemas/RealtimeConversationItem" + required: + - event_id + - type + - response_id + - output_index + - item + x-oaiMeta: + name: response.output_item.done + group: realtime + example: | + { + "event_id": "event_3536", + "type": "response.output_item.done", + "response_id": "resp_001", + "output_index": 0, + "item": { + "id": "msg_007", + "object": "realtime.item", + "type": "message", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "Sure, I can help with that." + } + ] + } + } + RealtimeServerEventResponseTextDelta: + type: object + description: Returned when the text value of a "text" content part is updated. + properties: + event_id: + type: string + description: The unique ID of the server event. + type: type: string enum: - - realtime.item - description: > - Identifier for the API object being returned - always - `realtime.item`. + - response.text.delta + description: The event type, must be `response.text.delta`. x-stainless-const: true - status: + response_id: type: string - enum: - - completed - - incomplete - description: > - The status of the item (`completed`, `incomplete`). These have no - effect - - on the conversation, but are accepted for consistency with the - - `conversation.item.created` event. - role: + description: The ID of the response. + item_id: type: string - enum: - - user - - assistant - - system - description: > - The role of the message sender (`user`, `assistant`, `system`), - only - - applicable for `message` items. - content: - type: array - x-oaiExpandable: true - description: > - The content of the message, applicable for `message` items. - - - Message items of role `system` support only `input_text` content - - - Message items of role `user` support `input_text` and - `input_audio` - content - - Message items of role `assistant` support `text` content. - items: - type: object - x-oaiExpandable: true - properties: - type: - type: string - enum: - - input_audio - - input_text - - item_reference - - text - description: > - The content type (`input_text`, `input_audio`, - `item_reference`, `text`). - text: - type: string - description: > - The text content, used for `input_text` and `text` content - types. - id: - type: string - description: > - ID of a previous conversation item to reference (for - `item_reference` - - content types in `response.create` events). These can - reference both - - client and server created items. - audio: - type: string - description: > - Base64-encoded audio bytes, used for `input_audio` content - type. - transcript: - type: string - description: > - The transcript of the audio, used for `input_audio` content - type. - call_id: + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + delta: type: string - description: > - The ID of the function call (for `function_call` and - - `function_call_output` items). If passed on a - `function_call_output` - - item, the server will check that a `function_call` item with the - same + description: The text delta. + required: + - event_id + - type + - response_id + - item_id + - output_index + - content_index + - delta + x-oaiMeta: + name: response.text.delta + group: realtime + example: | + { + "event_id": "event_4142", + "type": "response.text.delta", + "response_id": "resp_001", + "item_id": "msg_007", + "output_index": 0, + "content_index": 0, + "delta": "Sure, I can h" + } + RealtimeServerEventResponseTextDone: + type: object + description: > + Returned when the text value of a "text" content part is done streaming. + Also - ID exists in the conversation history. - name: + emitted when a Response is interrupted, incomplete, or cancelled. + properties: + event_id: type: string - description: | - The name of the function being called (for `function_call` items). - arguments: + description: The unique ID of the server event. + type: type: string - description: | - The arguments of the function call (for `function_call` items). - output: + enum: + - response.text.done + description: The event type, must be `response.text.done`. + x-stainless-const: true + response_id: type: string - description: | - The output of the function call (for `function_call_output` items). - RealtimeResponse: + description: The ID of the response. + item_id: + type: string + description: The ID of the item. + output_index: + type: integer + description: The index of the output item in the response. + content_index: + type: integer + description: The index of the content part in the item's content array. + text: + type: string + description: The final text content. + required: + - event_id + - type + - response_id + - item_id + - output_index + - content_index + - text + x-oaiMeta: + name: response.text.done + group: realtime + example: | + { + "event_id": "event_4344", + "type": "response.text.done", + "response_id": "resp_001", + "item_id": "msg_007", + "output_index": 0, + "content_index": 0, + "text": "Sure, I can help with that." + } + RealtimeServerEventSessionCreated: type: object - description: The response resource. + description: > + Returned when a Session is created. Emitted automatically when a new + + connection is established as the first server event. This event will + contain + + the default Session configuration. properties: - id: + event_id: type: string - description: The unique ID of the response. - object: + description: The unique ID of the server event. + type: type: string enum: - - realtime.response - description: The object type, must be `realtime.response`. + - session.created + description: The event type, must be `session.created`. x-stainless-const: true - status: - type: string - enum: - - completed - - cancelled - - failed - - incomplete - description: > - The final status of the response (`completed`, `cancelled`, - `failed`, or - - `incomplete`). - status_details: - type: object - description: Additional details about the status. - properties: - type: - type: string - enum: - - completed - - cancelled - - failed - - incomplete - description: > - The type of error that caused the response to fail, - corresponding - - with the `status` field (`completed`, `cancelled`, - `incomplete`, - - `failed`). - reason: - type: string - enum: - - turn_detected - - client_cancelled - - max_output_tokens - - content_filter - description: > - The reason the Response did not complete. For a `cancelled` - Response, - - one of `turn_detected` (the server VAD detected a new start of - speech) - - or `client_cancelled` (the client sent a cancel event). For an - - `incomplete` Response, one of `max_output_tokens` or - `content_filter` - - (the server-side safety filter activated and cut off the - response). - error: - type: object - description: | - A description of the error that caused the response to fail, - populated when the `status` is `failed`. - properties: - type: - type: string - description: The type of error. - code: - type: string - description: Error code, if any. - output: - type: array - description: The list of output items generated by the response. - items: - $ref: "#/components/schemas/RealtimeConversationItem" - metadata: - $ref: "#/components/schemas/Metadata" - usage: - type: object - description: > - Usage statistics for the Response, this will correspond to billing. - A - - Realtime API session will maintain a conversation context and append - new - - Items to the Conversation, thus output from previous turns (text - and - - audio tokens) will become the input for later turns. - properties: - total_tokens: - type: integer - description: > - The total number of tokens in the Response including input and - output - - text and audio tokens. - input_tokens: - type: integer - description: > - The number of input tokens used in the Response, including text - and - - audio tokens. - output_tokens: - type: integer - description: > - The number of output tokens sent in the Response, including text - and - - audio tokens. - input_token_details: - type: object - description: Details about the input tokens used in the Response. - properties: - cached_tokens: - type: integer - description: The number of cached tokens used in the Response. - text_tokens: - type: integer - description: The number of text tokens used in the Response. - audio_tokens: - type: integer - description: The number of audio tokens used in the Response. - output_token_details: - type: object - description: Details about the output tokens used in the Response. - properties: - text_tokens: - type: integer - description: The number of text tokens used in the Response. - audio_tokens: - type: integer - description: The number of audio tokens used in the Response. - conversation_id: - description: > - Which conversation the response is added to, determined by the - `conversation` - - field in the `response.create` event. If `auto`, the response will - be added to - - the default conversation and the value of `conversation_id` will be - an id like - - `conv_1234`. If `none`, the response will not be added to any - conversation and - - the value of `conversation_id` will be `null`. If responses are - being triggered - - by server VAD, the response will be added to the default - conversation, thus + session: + $ref: "#/components/schemas/RealtimeSession" + required: + - event_id + - type + - session + x-oaiMeta: + name: session.created + group: realtime + example: | + { + "event_id": "event_1234", + "type": "session.created", + "session": { + "id": "sess_001", + "object": "realtime.session", + "model": "gpt-4o-realtime-preview-2024-12-17", + "modalities": ["text", "audio"], + "instructions": "...model instructions here...", + "voice": "sage", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": null, + "turn_detection": { + "type": "server_vad", + "threshold": 0.5, + "prefix_padding_ms": 300, + "silence_duration_ms": 200 + }, + "tools": [], + "tool_choice": "auto", + "temperature": 0.8, + "max_response_output_tokens": "inf" + } + } + RealtimeServerEventSessionUpdated: + type: object + description: > + Returned when a session is updated with a `session.update` event, + unless - the `conversation_id` will be an id like `conv_1234`. - type: string - voice: + there is an error. + properties: + event_id: type: string - enum: - - alloy - - ash - - ballad - - coral - - echo - - sage - - shimmer - - verse - description: > - The voice the model used to respond. - - Current voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` - `sage`, - - `shimmer` and `verse`. - modalities: - type: array - description: > - The set of modalities the model used to respond. If there are - multiple modalities, - - the model will pick one, for example if `modalities` is `["text", - "audio"]`, the model - - could be responding in either text or audio. - items: - type: string - enum: - - text - - audio - output_audio_format: + description: The unique ID of the server event. + type: type: string enum: - - pcm16 - - g711_ulaw - - g711_alaw - description: > - The format of output audio. Options are `pcm16`, `g711_ulaw`, or - `g711_alaw`. - temperature: - type: number - description: > - Sampling temperature for the model, limited to [0.6, 1.2]. Defaults - to 0.8. - max_output_tokens: - oneOf: - - type: integer - - type: string - enum: - - inf - x-stainless-const: true - description: | - Maximum number of output tokens for a single assistant response, - inclusive of tool calls, that was used in this response. - RealtimeResponseCreateParams: + - session.updated + description: The event type, must be `session.updated`. + x-stainless-const: true + session: + $ref: "#/components/schemas/RealtimeSession" + required: + - event_id + - type + - session + x-oaiMeta: + name: session.updated + group: realtime + example: | + { + "event_id": "event_5678", + "type": "session.updated", + "session": { + "id": "sess_001", + "object": "realtime.session", + "model": "gpt-4o-realtime-preview-2024-12-17", + "modalities": ["text"], + "instructions": "New instructions", + "voice": "sage", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": null, + "tools": [], + "tool_choice": "none", + "temperature": 0.7, + "max_response_output_tokens": 200 + } + } + RealtimeSession: type: object - description: Create a new Realtime response with these parameters + description: Realtime session object configuration. properties: + id: + type: string + description: | + Unique identifier for the session object. modalities: - type: array description: | The set of modalities the model can respond with. To disable audio, set this to ["text"]. @@ -21034,6 +26881,18 @@ components: enum: - text - audio + model: + description: | + The Realtime model used for this session. + anyOf: + - type: string + - type: string + enum: + - gpt-4o-realtime-preview + - gpt-4o-realtime-preview-2024-10-01 + - gpt-4o-realtime-preview-2024-12-17 + - gpt-4o-mini-realtime-preview + - gpt-4o-mini-realtime-preview-2024-12-17 instructions: type: string description: > @@ -21088,6 +26947,19 @@ components: voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, `shimmer` and `verse`. + input_audio_format: + type: string + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of input audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + + For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, + + single channel (mono), and little-endian byte order. output_audio_format: type: string enum: @@ -21097,6 +26969,91 @@ components: description: > The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. + + For `pcm16`, output audio is sampled at a rate of 24kHz. + input_audio_transcription: + type: object + description: > + Configuration for input audio transcription, defaults to off and can + be + + set to `null` to turn off once on. Input audio transcription is not + native + + to the model, since the model consumes audio directly. Transcription + runs + + asynchronously through Whisper and should be treated as rough + guidance + + rather than the representation understood by the model. + properties: + model: + type: string + description: > + The model to use for transcription, `whisper-1` is the only + currently + + supported model. + turn_detection: + type: object + nullable: true + description: > + Configuration for turn detection. Can be set to `null` to turn off. + Server + + VAD means that the model will detect the start and end of speech + based on + + audio volume and respond at the end of user speech. + properties: + type: + type: string + enum: + - server_vad + description: > + Type of turn detection, only `server_vad` is currently supported. + x-stainless-const: true + threshold: + type: number + description: > + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. + A + + higher threshold will require louder audio to activate the + model, and + + thus might perform better in noisy environments. + prefix_padding_ms: + type: integer + description: | + Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. + silence_duration_ms: + type: integer + description: > + Duration of silence to detect speech stop (in milliseconds). + Defaults + + to 500ms. With shorter values the model will respond more + quickly, + + but may jump in on short pauses from the user. + create_response: + type: boolean + default: true + description: > + Whether or not to automatically generate a response when a VAD + stop event occurs. `true` by default. + interrupt_response: + type: boolean + default: true + description: > + Whether or not to automatically interrupt any ongoing response + with output to the default + + conversation (i.e. `conversation` of `auto`) when a VAD start + event occurs. `true` by default. tools: type: array description: Tools (functions) available to the model. @@ -21131,8 +27088,7 @@ components: How the model chooses tools. Options are `auto`, `none`, `required`, or - specify a function, like `{"type": "function", "function": {"name": - "my_function"}}`. + specify a function. temperature: type: number description: > @@ -21143,2358 +27099,2498 @@ components: - type: integer - type: string enum: - - inf - x-stainless-const: true - description: | - Maximum number of output tokens for a single assistant response, - inclusive of tool calls. Provide an integer between 1 and 4096 to - limit output tokens, or `inf` for the maximum available tokens for a - given model. Defaults to `inf`. - conversation: - description: > - Controls which conversation the response is added to. Currently - supports - - `auto` and `none`, with `auto` as the default value. The `auto` - value - - means that the contents of the response will be added to the default - - conversation. Set this to `none` to create an out-of-band response - which - - will not add items to default conversation. - oneOf: - - type: string - - type: string - default: auto - enum: - - auto - - none - metadata: - $ref: "#/components/schemas/Metadata" - input: - type: array - description: > - Input items to include in the prompt for the model. Using this field - - creates a new context for this Response instead of using the default - - conversation. An empty array `[]` will clear the context for this - Response. - - Note that this can include references to items from the default - conversation. - items: - $ref: "#/components/schemas/RealtimeConversationItemWithReference" - RealtimeServerEventConversationCreated: - type: object - description: > - Returned when a conversation is created. Emitted right after session - creation. - properties: - event_id: - type: string - description: The unique ID of the server event. - type: - type: string - enum: - - conversation.created - description: The event type, must be `conversation.created`. - x-stainless-const: true - conversation: - type: object - description: The conversation resource. - properties: - id: - type: string - description: The unique ID of the conversation. - object: - type: string - description: The object type, must be `realtime.conversation`. - required: - - event_id - - type - - conversation - x-oaiMeta: - name: conversation.created - group: realtime - example: | - { - "event_id": "event_9101", - "type": "conversation.created", - "conversation": { - "id": "conv_001", - "object": "realtime.conversation" - } - } - RealtimeServerEventConversationItemCreated: + - inf + x-stainless-const: true + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. + RealtimeSessionCreateRequest: type: object - description: > - Returned when a conversation item is created. There are several - scenarios that - - produce this event: - - The server is generating a Response, which if successful will produce - either one or two Items, which will be of type `message` - (role `assistant`) or type `function_call`. - - The input audio buffer has been committed, either by the client or the - server (in `server_vad` mode). The server will take the content of the - input audio buffer and add it to a new user message Item. - - The client has sent a `conversation.item.create` event to add a new Item - to the Conversation. + description: Realtime session object configuration. properties: - event_id: - type: string - description: The unique ID of the server event. - type: + modalities: + description: | + The set of modalities the model can respond with. To disable audio, + set this to ["text"]. + items: + type: string + enum: + - text + - audio + model: type: string + description: | + The Realtime model used for this session. enum: - - conversation.item.created - description: The event type, must be `conversation.item.created`. - x-stainless-const: true - previous_item_id: + - gpt-4o-realtime-preview + - gpt-4o-realtime-preview-2024-10-01 + - gpt-4o-realtime-preview-2024-12-17 + - gpt-4o-mini-realtime-preview + - gpt-4o-mini-realtime-preview-2024-12-17 + instructions: type: string description: > - The ID of the preceding item in the Conversation context, allows - the - - client to understand the order of the conversation. - item: - $ref: "#/components/schemas/RealtimeConversationItem" - required: - - event_id - - type - - previous_item_id - - item - x-oaiMeta: - name: conversation.item.created - group: realtime - example: | - { - "event_id": "event_1920", - "type": "conversation.item.created", - "previous_item_id": "msg_002", - "item": { - "id": "msg_003", - "object": "realtime.item", - "type": "message", - "status": "completed", - "role": "user", - "content": [ - { - "type": "input_audio", - "transcript": "hello how are you", - "audio": "base64encodedaudio==" - } - ] - } - } - RealtimeServerEventConversationItemDeleted: - type: object - description: > - Returned when an item in the conversation is deleted by the client with - a + The default system instructions (i.e. system message) prepended to + model - `conversation.item.delete` event. This event is used to synchronize the + calls. This field allows the client to guide the model on desired - server's understanding of the conversation history with the client's - view. - properties: - event_id: - type: string - description: The unique ID of the server event. - type: - type: string - enum: - - conversation.item.deleted - description: The event type, must be `conversation.item.deleted`. - x-stainless-const: true - item_id: - type: string - description: The ID of the item that was deleted. - required: - - event_id - - type - - item_id - x-oaiMeta: - name: conversation.item.deleted - group: realtime - example: | - { - "event_id": "event_2728", - "type": "conversation.item.deleted", - "item_id": "msg_005" - } - RealtimeServerEventConversationItemInputAudioTranscriptionCompleted: - type: object - description: > - This event is the output of audio transcription for user audio written - to the + responses. The model can be instructed on response content and + format, - user audio buffer. Transcription begins when the input audio buffer is + (e.g. "be extremely succinct", "act friendly", "here are examples of + good - committed by the client or server (in `server_vad` mode). Transcription - runs + responses") and on audio behavior (e.g. "talk quickly", "inject + emotion - asynchronously with Response creation, so this event may come before or - after + into your voice", "laugh frequently"). The instructions are not + guaranteed - the Response events. + to be followed by the model, but they provide guidance to the model + on the + desired behavior. - Realtime API models accept audio natively, and thus input transcription - is a - separate process run on a separate ASR (Automatic Speech Recognition) - model, + Note that the server sets default instructions which will be used if + this - currently always `whisper-1`. Thus the transcript may diverge somewhat - from + field is not set and are visible in the `session.created` event at + the - the model's interpretation, and should be treated as a rough guide. - properties: - event_id: - type: string - description: The unique ID of the server event. - type: + start of the session. + voice: type: string enum: - - conversation.item.input_audio_transcription.completed - description: | - The event type, must be - `conversation.item.input_audio_transcription.completed`. - x-stainless-const: true - item_id: - type: string - description: The ID of the user message item containing the audio. - content_index: - type: integer - description: The index of the content part containing the audio. - transcript: - type: string - description: The transcribed text. - required: - - event_id - - type - - item_id - - content_index - - transcript - x-oaiMeta: - name: conversation.item.input_audio_transcription.completed - group: realtime - example: | - { - "event_id": "event_2122", - "type": "conversation.item.input_audio_transcription.completed", - "item_id": "msg_003", - "content_index": 0, - "transcript": "Hello, how are you?" - } - RealtimeServerEventConversationItemInputAudioTranscriptionFailed: - type: object - description: > - Returned when input audio transcription is configured, and a - transcription + - alloy + - ash + - ballad + - coral + - echo + - sage + - shimmer + - verse + description: > + The voice the model uses to respond. Voice cannot be changed during + the - request for a user message failed. These events are separate from other + session once the model has responded with audio at least once. + Current - `error` events so that the client can identify the related Item. - properties: - event_id: - type: string - description: The unique ID of the server event. - type: + voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, + + `shimmer` and `verse`. + input_audio_format: type: string enum: - - conversation.item.input_audio_transcription.failed - description: | - The event type, must be - `conversation.item.input_audio_transcription.failed`. - x-stainless-const: true - item_id: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of input audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + + For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, + + single channel (mono), and little-endian byte order. + output_audio_format: type: string - description: The ID of the user message item. - content_index: - type: integer - description: The index of the content part containing the audio. - error: + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + + For `pcm16`, output audio is sampled at a rate of 24kHz. + input_audio_transcription: type: object - description: Details of the transcription error. + description: > + Configuration for input audio transcription, defaults to off and can + be set to `null` to turn off once on. Input audio transcription is + not native to the model, since the model consumes audio directly. + Transcription runs asynchronously through [OpenAI Whisper + transcription](https://platform.openai.com/docs/api-reference/audio/createTranscription) + and should be treated as rough guidance rather than the + representation understood by the model. The client can optionally + set the language and prompt for transcription, these fields will be + passed to the Whisper API. properties: - type: + model: type: string - description: The type of error. - code: + description: > + The model to use for transcription, `whisper-1` is the only + currently + + supported model. + language: type: string - description: Error code, if any. - message: + description: > + The language of the input audio. Supplying the input language in + + [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) + (e.g. `en`) format + + will improve accuracy and latency. + prompt: type: string - description: A human-readable error message. - param: + description: > + An optional text to guide the model's style or continue a + previous audio + + segment. The [prompt](/docs/guides/speech-to-text#prompting) + should match + + the audio language. + turn_detection: + type: object + description: > + Configuration for turn detection. Can be set to `null` to turn off. + Server + + VAD means that the model will detect the start and end of speech + based on + + audio volume and respond at the end of user speech. + properties: + type: type: string - description: Parameter related to the error, if any. - required: - - event_id - - type - - item_id - - content_index - - error - x-oaiMeta: - name: conversation.item.input_audio_transcription.failed - group: realtime - example: | - { - "event_id": "event_2324", - "type": "conversation.item.input_audio_transcription.failed", - "item_id": "msg_003", - "content_index": 0, - "error": { - "type": "transcription_error", - "code": "audio_unintelligible", - "message": "The audio could not be transcribed.", - "param": null - } - } - RealtimeServerEventConversationItemTruncated: - type: object - description: > - Returned when an earlier assistant audio message item is truncated by - the + description: > + Type of turn detection, only `server_vad` is currently supported. + threshold: + type: number + description: > + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. + A - client with a `conversation.item.truncate` event. This event is used to + higher threshold will require louder audio to activate the + model, and - synchronize the server's understanding of the audio with the client's - playback. + thus might perform better in noisy environments. + prefix_padding_ms: + type: integer + description: | + Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. + silence_duration_ms: + type: integer + description: > + Duration of silence to detect speech stop (in milliseconds). + Defaults + to 500ms. With shorter values the model will respond more + quickly, - This action will truncate the audio and remove the server-side text - transcript + but may jump in on short pauses from the user. + create_response: + type: boolean + default: true + description: > + Whether or not to automatically generate a response when a VAD + stop event occurs. `true` by default. + interrupt_response: + type: boolean + default: true + description: > + Whether or not to automatically interrupt any ongoing response + with output to the default - to ensure there is no text in the context that hasn't been heard by the - user. - properties: - event_id: - type: string - description: The unique ID of the server event. - type: - type: string - enum: - - conversation.item.truncated - description: The event type, must be `conversation.item.truncated`. - x-stainless-const: true - item_id: + conversation (i.e. `conversation` of `auto`) when a VAD start + event occurs. `true` by default. + tools: + type: array + description: Tools (functions) available to the model. + items: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool, i.e. `function`. + x-stainless-const: true + name: + type: string + description: The name of the function. + description: + type: string + description: > + The description of the function, including guidance on when + and how + + to call it, and guidance about what to tell the user when + calling + + (if anything). + parameters: + type: object + description: Parameters of the function in JSON Schema. + tool_choice: type: string - description: The ID of the assistant message item that was truncated. - content_index: - type: integer - description: The index of the content part that was truncated. - audio_end_ms: - type: integer + description: > + How the model chooses tools. Options are `auto`, `none`, `required`, + or + + specify a function. + temperature: + type: number + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. Defaults + to 0.8. + max_response_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + x-stainless-const: true description: | - The duration up to which the audio was truncated, in milliseconds. - required: - - event_id - - type - - item_id - - content_index - - audio_end_ms - x-oaiMeta: - name: conversation.item.truncated - group: realtime - example: | - { - "event_id": "event_2526", - "type": "conversation.item.truncated", - "item_id": "msg_004", - "content_index": 0, - "audio_end_ms": 1500 - } - RealtimeServerEventError: + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. + RealtimeSessionCreateResponse: type: object description: > - Returned when an error occurs, which could be a client problem or a - server - - problem. Most errors are recoverable and the session will stay open, we + A new Realtime session configuration, with an ephermeral key. Default + TTL - recommend to implementors to monitor and log error messages by default. + for keys is one minute. properties: - event_id: - type: string - description: The unique ID of the server event. - type: - type: string - enum: - - error - description: The event type, must be `error`. - x-stainless-const: true - error: + client_secret: type: object - description: Details of the error. - required: - - type - - message + description: Ephemeral key returned by the API. properties: - type: - type: string - description: > - The type of error (e.g., "invalid_request_error", - "server_error"). - code: - type: string - description: Error code, if any. - nullable: true - message: - type: string - description: A human-readable error message. - param: - type: string - description: Parameter related to the error, if any. - nullable: true - event_id: + value: type: string description: > - The event_id of the client event that caused the error, if - applicable. - nullable: true - required: - - event_id - - type - - error - x-oaiMeta: - name: error - group: realtime - example: | - { - "event_id": "event_890", - "type": "error", - "error": { - "type": "invalid_request_error", - "code": "invalid_event", - "message": "The 'type' field is missing.", - "param": null, - "event_id": "event_567" - } - } - RealtimeServerEventInputAudioBufferCleared: - type: object - description: | - Returned when the input audio buffer is cleared by the client with a - `input_audio_buffer.clear` event. - properties: - event_id: - type: string - description: The unique ID of the server event. - type: - type: string - enum: - - input_audio_buffer.cleared - description: The event type, must be `input_audio_buffer.cleared`. - x-stainless-const: true - required: - - event_id - - type - x-oaiMeta: - name: input_audio_buffer.cleared - group: realtime - example: | - { - "event_id": "event_1314", - "type": "input_audio_buffer.cleared" - } - RealtimeServerEventInputAudioBufferCommitted: - type: object - description: > - Returned when an input audio buffer is committed, either by the client - or + Ephemeral key usable in client environments to authenticate + connections - automatically in server VAD mode. The `item_id` property is the ID of - the user + to the Realtime API. Use this in client-side environments rather + than - message item that will be created, thus a `conversation.item.created` - event + a standard API token, which should only be used server-side. + expires_at: + type: integer + description: > + Timestamp for when the token expires. Currently, all tokens + expire - will also be sent to the client. - properties: - event_id: - type: string - description: The unique ID of the server event. - type: - type: string - enum: - - input_audio_buffer.committed - description: The event type, must be `input_audio_buffer.committed`. - x-stainless-const: true - previous_item_id: + after one minute. + required: + - value + - expires_at + modalities: + description: | + The set of modalities the model can respond with. To disable audio, + set this to ["text"]. + items: + type: string + enum: + - text + - audio + instructions: type: string description: > - The ID of the preceding item after which the new item will be - inserted. - item_id: - type: string - description: The ID of the user message item that will be created. - required: - - event_id - - type - - previous_item_id - - item_id - x-oaiMeta: - name: input_audio_buffer.committed - group: realtime - example: | - { - "event_id": "event_1121", - "type": "input_audio_buffer.committed", - "previous_item_id": "msg_001", - "item_id": "msg_002" - } - RealtimeServerEventInputAudioBufferSpeechStarted: - type: object - description: > - Sent by the server when in `server_vad` mode to indicate that speech has - been - - detected in the audio buffer. This can happen any time audio is added to - the + The default system instructions (i.e. system message) prepended to + model - buffer (unless speech is already detected). The client may want to use - this + calls. This field allows the client to guide the model on desired - event to interrupt audio playback or provide visual feedback to the - user. + responses. The model can be instructed on response content and + format, + (e.g. "be extremely succinct", "act friendly", "here are examples of + good - The client should expect to receive a - `input_audio_buffer.speech_stopped` event + responses") and on audio behavior (e.g. "talk quickly", "inject + emotion - when speech stops. The `item_id` property is the ID of the user message - item + into your voice", "laugh frequently"). The instructions are not + guaranteed - that will be created when speech stops and will also be included in the + to be followed by the model, but they provide guidance to the model + on the - `input_audio_buffer.speech_stopped` event (unless the client manually - commits + desired behavior. - the audio buffer during VAD activation). - properties: - event_id: - type: string - description: The unique ID of the server event. - type: - type: string - enum: - - input_audio_buffer.speech_started - description: The event type, must be `input_audio_buffer.speech_started`. - x-stainless-const: true - audio_start_ms: - type: integer - description: > - Milliseconds from the start of all audio written to the buffer - during the - session when speech was first detected. This will correspond to the + Note that the server sets default instructions which will be used if + this - beginning of audio sent to the model, and thus includes the + field is not set and are visible in the `session.created` event at + the - `prefix_padding_ms` configured in the Session. - item_id: + start of the session. + voice: type: string + enum: + - alloy + - ash + - ballad + - coral + - echo + - sage + - shimmer + - verse description: > - The ID of the user message item that will be created when speech - stops. - required: - - event_id - - type - - audio_start_ms - - item_id - x-oaiMeta: - name: input_audio_buffer.speech_started - group: realtime - example: | - { - "event_id": "event_1516", - "type": "input_audio_buffer.speech_started", - "audio_start_ms": 1000, - "item_id": "msg_003" - } - RealtimeServerEventInputAudioBufferSpeechStopped: - type: object - description: > - Returned in `server_vad` mode when the server detects the end of speech - in + The voice the model uses to respond. Voice cannot be changed during + the - the audio buffer. The server will also send an - `conversation.item.created` + session once the model has responded with audio at least once. + Current - event with the user message item that is created from the audio buffer. - properties: - event_id: + voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, + + `shimmer` and `verse`. + input_audio_format: type: string - description: The unique ID of the server event. - type: + description: > + The format of input audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + output_audio_format: type: string - enum: - - input_audio_buffer.speech_stopped - description: The event type, must be `input_audio_buffer.speech_stopped`. - x-stainless-const: true - audio_end_ms: - type: integer description: > - Milliseconds since the session started when speech stopped. This - will + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + input_audio_transcription: + type: object + description: > + Configuration for input audio transcription, defaults to off and can + be - correspond to the end of audio sent to the model, and thus includes - the + set to `null` to turn off once on. Input audio transcription is not + native - `min_silence_duration_ms` configured in the Session. - item_id: - type: string - description: The ID of the user message item that will be created. - required: - - event_id - - type - - audio_end_ms - - item_id - x-oaiMeta: - name: input_audio_buffer.speech_stopped - group: realtime - example: | - { - "event_id": "event_1718", - "type": "input_audio_buffer.speech_stopped", - "audio_end_ms": 2000, - "item_id": "msg_003" - } - RealtimeServerEventRateLimitsUpdated: - type: object - description: > - Emitted at the beginning of a Response to indicate the updated rate - limits. + to the model, since the model consumes audio directly. Transcription + runs - When a Response is created some tokens will be "reserved" for the - output + asynchronously through Whisper and should be treated as rough + guidance - tokens, the rate limits shown here reflect that reservation, which is - then + rather than the representation understood by the model. + properties: + model: + type: string + description: > + The model to use for transcription, `whisper-1` is the only + currently - adjusted accordingly once the Response is completed. - properties: - event_id: - type: string - description: The unique ID of the server event. - type: - type: string - enum: - - rate_limits.updated - description: The event type, must be `rate_limits.updated`. - x-stainless-const: true - rate_limits: + supported model. + turn_detection: + type: object + description: > + Configuration for turn detection. Can be set to `null` to turn off. + Server + + VAD means that the model will detect the start and end of speech + based on + + audio volume and respond at the end of user speech. + properties: + type: + type: string + description: > + Type of turn detection, only `server_vad` is currently supported. + threshold: + type: number + description: > + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. + A + + higher threshold will require louder audio to activate the + model, and + + thus might perform better in noisy environments. + prefix_padding_ms: + type: integer + description: | + Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. + silence_duration_ms: + type: integer + description: > + Duration of silence to detect speech stop (in milliseconds). + Defaults + + to 500ms. With shorter values the model will respond more + quickly, + + but may jump in on short pauses from the user. + tools: type: array - description: List of rate limit information. + description: Tools (functions) available to the model. items: type: object properties: - name: + type: type: string enum: - - requests - - tokens - description: | - The name of the rate limit (`requests`, `tokens`). - limit: - type: integer - description: The maximum allowed value for the rate limit. - remaining: - type: integer - description: The remaining value before the limit is reached. - reset_seconds: - type: number - description: Seconds until the rate limit resets. - required: - - event_id - - type - - rate_limits - x-oaiMeta: - name: rate_limits.updated - group: realtime - example: | - { - "event_id": "event_5758", - "type": "rate_limits.updated", - "rate_limits": [ - { - "name": "requests", - "limit": 1000, - "remaining": 999, - "reset_seconds": 60 - }, - { - "name": "tokens", - "limit": 50000, - "remaining": 49950, - "reset_seconds": 60 - } - ] - } - RealtimeServerEventResponseAudioDelta: - type: object - description: Returned when the model-generated audio is updated. - properties: - event_id: - type: string - description: The unique ID of the server event. - type: - type: string - enum: - - response.audio.delta - description: The event type, must be `response.audio.delta`. - x-stainless-const: true - response_id: - type: string - description: The ID of the response. - item_id: - type: string - description: The ID of the item. - output_index: - type: integer - description: The index of the output item in the response. - content_index: - type: integer - description: The index of the content part in the item's content array. - delta: + - function + description: The type of the tool, i.e. `function`. + x-stainless-const: true + name: + type: string + description: The name of the function. + description: + type: string + description: > + The description of the function, including guidance on when + and how + + to call it, and guidance about what to tell the user when + calling + + (if anything). + parameters: + type: object + description: Parameters of the function in JSON Schema. + tool_choice: type: string - description: Base64-encoded audio data delta. + description: > + How the model chooses tools. Options are `auto`, `none`, `required`, + or + + specify a function. + temperature: + type: number + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. Defaults + to 0.8. + max_response_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + x-stainless-const: true + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. required: - - event_id - - type - - response_id - - item_id - - output_index - - content_index - - delta + - client_secret x-oaiMeta: - name: response.audio.delta + name: The session object group: realtime example: | { - "event_id": "event_4950", - "type": "response.audio.delta", - "response_id": "resp_001", - "item_id": "msg_008", - "output_index": 0, - "content_index": 0, - "delta": "Base64EncodedAudioDelta" + "id": "sess_001", + "object": "realtime.session", + "model": "gpt-4o-realtime-preview-2024-12-17", + "modalities": ["audio", "text"], + "instructions": "You are a friendly assistant.", + "voice": "alloy", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": null, + "tools": [], + "tool_choice": "none", + "temperature": 0.7, + "max_response_output_tokens": 200, + "client_secret": { + "value": "ek_abc123", + "expires_at": 1234567890 + } } - RealtimeServerEventResponseAudioDone: + Reasoning: type: object - description: > - Returned when the model-generated audio is done. Also emitted when a - Response + description: | + **o-series models only** - is interrupted, incomplete, or cancelled. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + title: Reasoning + x-oaiExpandable: true properties: - event_id: - type: string - description: The unique ID of the server event. - type: + effort: + $ref: "#/components/schemas/ReasoningEffort" + generate_summary: type: string + description: > + **o-series models only** + + + A summary of the reasoning performed by the model. This can be + + useful for debugging and understanding the model's reasoning + process. + + One of `concise` or `detailed`. enum: - - response.audio.done - description: The event type, must be `response.audio.done`. - x-stainless-const: true - response_id: - type: string - description: The ID of the response. - item_id: - type: string - description: The ID of the item. - output_index: - type: integer - description: The index of the output item in the response. - content_index: - type: integer - description: The index of the content part in the item's content array. + - concise + - detailed + nullable: true required: - - event_id - - type - - response_id - - item_id - - output_index - - content_index - x-oaiMeta: - name: response.audio.done - group: realtime - example: | - { - "event_id": "event_5152", - "type": "response.audio.done", - "response_id": "resp_001", - "item_id": "msg_008", - "output_index": 0, - "content_index": 0 - } - RealtimeServerEventResponseAudioTranscriptDelta: + - effort + ReasoningEffort: + type: string + enum: + - low + - medium + - high + default: medium + nullable: true + description: | + **o-series models only** + + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + Currently supported values are `low`, `medium`, and `high`. Reducing + reasoning effort can result in faster responses and fewer tokens used + on reasoning in a response. + ReasoningItem: type: object description: > - Returned when the model-generated transcription of audio output is - updated. + A description of the chain of thought used by a reasoning model while + generating + + a response. + title: Reasoning + x-oaiExpandable: true properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: | + The type of the object. Always `reasoning`. enum: - - response.audio_transcript.delta - description: The event type, must be `response.audio_transcript.delta`. + - reasoning x-stainless-const: true - response_id: - type: string - description: The ID of the response. - item_id: + id: type: string - description: The ID of the item. - output_index: - type: integer - description: The index of the output item in the response. - content_index: - type: integer - description: The index of the content part in the item's content array. - delta: + description: | + The unique identifier of the reasoning content. + content: + type: array + description: | + Reasoning text contents. + items: + type: object + properties: + type: + type: string + description: | + The type of the object. Always `text`. + enum: + - reasoning_summary + x-stainless-const: true + text: + type: string + description: > + A short summary of the reasoning used by the model when + generating + + the response. + required: + - type + - text + status: type: string - description: The transcript delta. + 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: - - event_id + - id + - content - type - - response_id - - item_id - - output_index - - content_index - - delta - x-oaiMeta: - name: response.audio_transcript.delta - group: realtime - example: | - { - "event_id": "event_4546", - "type": "response.audio_transcript.delta", - "response_id": "resp_001", - "item_id": "msg_008", - "output_index": 0, - "content_index": 0, - "delta": "Hello, how can I a" - } - RealtimeServerEventResponseAudioTranscriptDone: + Refusal: type: object + title: Refusal description: | - Returned when the model-generated transcription of audio output is done - streaming. Also emitted when a Response is interrupted, incomplete, or - cancelled. + A refusal from the model. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: | + The type of the refusal. Always `refusal`. enum: - - response.audio_transcript.done - description: The event type, must be `response.audio_transcript.done`. + - refusal x-stainless-const: true - response_id: - type: string - description: The ID of the response. - item_id: - type: string - description: The ID of the item. - output_index: - type: integer - description: The index of the output item in the response. - content_index: - type: integer - description: The index of the content part in the item's content array. - transcript: + refusal: type: string - description: The final transcript of the audio. + description: | + The refusal explanationfrom the model. required: - - event_id - type - - response_id - - item_id - - output_index - - content_index - - transcript - x-oaiMeta: - name: response.audio_transcript.done - group: realtime - example: | - { - "event_id": "event_4748", - "type": "response.audio_transcript.done", - "response_id": "resp_001", - "item_id": "msg_008", - "output_index": 0, - "content_index": 0, - "transcript": "Hello, how can I assist you today?" - } - RealtimeServerEventResponseContentPartAdded: + - refusal + Response: + allOf: + - $ref: "#/components/schemas/ModelResponseProperties" + - $ref: "#/components/schemas/ResponseProperties" + - type: object + properties: + 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`, or `incomplete`. + enum: + - completed + - failed + - in_progress + - incomplete + created_at: + type: number + description: | + Unix timestamp (in seconds) of when this Response was created. + error: + $ref: "#/components/schemas/ResponseError" + incomplete_details: + type: object + nullable: true + description: | + Details about why the response is incomplete. + properties: + reason: + type: string + description: The reason why the response is incomplete. + enum: + - max_output_tokens + - content_filter + output: + type: array + x-oaiExpandable: true + 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/OutputItem" + x-oaiExpandable: true + output_text: + type: string + nullable: true + 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 + usage: + $ref: "#/components/schemas/ResponseUsage" + parallel_tool_calls: + type: boolean + description: | + Whether to allow the model to run tool calls in parallel. + default: true + required: + - id + - object + - created_at + - error + - incomplete_details + - instructions + - model + - tools + - output + - parallel_tool_calls + - metadata + - tool_choice + - temperature + - top_p + x-oaiMeta: + name: The response object + group: responses + example: > + { + "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", + "object": "response", + "created_at": 1741476777, + "status": "completed", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "output": [ + { + "type": "message", + "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41", + "status": "completed", + "role": "assistant", + "content": [ + { + "type": "output_text", + "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.", + "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": { + "input_tokens": 328, + "input_tokens_details": { + "cached_tokens": 0 + }, + "output_tokens": 52, + "output_tokens_details": { + "reasoning_tokens": 0 + }, + "total_tokens": 380 + }, + "user": null, + "metadata": {} + } + ResponseAudioDeltaEvent: type: object - description: > - Returned when a new content part is added to an assistant message item - during - - response generation. + description: Emitted when there is a partial audio response. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: | + The type of the event. Always `response.audio.delta`. enum: - - response.content_part.added - description: The event type, must be `response.content_part.added`. + - response.audio.delta x-stainless-const: true - response_id: - type: string - description: The ID of the response. - item_id: + delta: type: string - description: The ID of the item to which the content part was added. - output_index: - type: integer - description: The index of the output item in the response. - content_index: - type: integer - description: The index of the content part in the item's content array. - part: - type: object - description: The content part that was added. - properties: - type: - type: string - enum: - - audio - - text - description: The content type ("text", "audio"). - text: - type: string - description: The text content (if type is "text"). - audio: - type: string - description: Base64-encoded audio data (if type is "audio"). - transcript: - type: string - description: The transcript of the audio (if type is "audio"). + description: | + A chunk of Base64 encoded response audio bytes. required: - - event_id - type - - response_id - - item_id - - output_index - - content_index - - part + - delta x-oaiMeta: - name: response.content_part.added - group: realtime + name: response.audio.delta + group: responses example: | { - "event_id": "event_3738", - "type": "response.content_part.added", - "response_id": "resp_001", - "item_id": "msg_007", - "output_index": 0, - "content_index": 0, - "part": { - "type": "text", - "text": "" - } + "type": "response.audio.delta", + "response_id": "resp_123", + "delta": "base64encoded..." } - RealtimeServerEventResponseContentPartDone: + ResponseAudioDoneEvent: type: object - description: > - Returned when a content part is done streaming in an assistant message - item. - - Also emitted when a Response is interrupted, incomplete, or cancelled. + description: Emitted when the audio response is complete. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: | + The type of the event. Always `response.audio.done`. enum: - - response.content_part.done - description: The event type, must be `response.content_part.done`. + - response.audio.done x-stainless-const: true - response_id: - type: string - description: The ID of the response. - item_id: - type: string - description: The ID of the item. - output_index: - type: integer - description: The index of the output item in the response. - content_index: - type: integer - description: The index of the content part in the item's content array. - part: - type: object - description: The content part that is done. - properties: - type: - type: string - enum: - - audio - - text - description: The content type ("text", "audio"). - text: - type: string - description: The text content (if type is "text"). - audio: - type: string - description: Base64-encoded audio data (if type is "audio"). - transcript: - type: string - description: The transcript of the audio (if type is "audio"). required: - - event_id - type - response_id - - item_id - - output_index - - content_index - - part x-oaiMeta: - name: response.content_part.done - group: realtime + name: response.audio.done + group: responses example: | { - "event_id": "event_3940", - "type": "response.content_part.done", - "response_id": "resp_001", - "item_id": "msg_007", - "output_index": 0, - "content_index": 0, - "part": { - "type": "text", - "text": "Sure, I can help with that." - } + "type": "response.audio.done", + "response_id": "resp-123" } - RealtimeServerEventResponseCreated: + ResponseAudioTranscriptDeltaEvent: type: object - description: > - Returned when a new Response is created. The first event of response - creation, - - where the response is in an initial state of `in_progress`. + description: Emitted when there is a partial transcript of audio. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: | + The type of the event. Always `response.audio.transcript.delta`. enum: - - response.created - description: The event type, must be `response.created`. + - response.audio.transcript.delta x-stainless-const: true - response: - $ref: "#/components/schemas/RealtimeResponse" + delta: + type: string + description: | + The partial transcript of the audio response. required: - - event_id - type - - response + - response_id + - delta x-oaiMeta: - name: response.created - group: realtime + name: response.audio.transcript.delta + group: responses example: | { - "event_id": "event_2930", - "type": "response.created", - "response": { - "id": "resp_001", - "object": "realtime.response", - "status": "in_progress", - "status_details": null, - "output": [], - "usage": null - } + "type": "response.audio.transcript.delta", + "response_id": "resp_123", + "delta": " ... partial transcript ... " } - RealtimeServerEventResponseDone: + ResponseAudioTranscriptDoneEvent: type: object - description: > - Returned when a Response is done streaming. Always emitted, no matter - the - - final state. The Response object included in the `response.done` event - will - - include all output Items in the Response but will omit the raw audio - data. + description: Emitted when the full audio transcript is completed. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: | + The type of the event. Always `response.audio.transcript.done`. enum: - - response.done - description: The event type, must be `response.done`. + - response.audio.transcript.done x-stainless-const: true - response: - $ref: "#/components/schemas/RealtimeResponse" required: - - event_id - type - - response + - response_id x-oaiMeta: - name: response.done - group: realtime + name: response.audio.transcript.done + group: responses example: | { - "event_id": "event_3132", - "type": "response.done", - "response": { - "id": "resp_001", - "object": "realtime.response", - "status": "completed", - "status_details": null, - "output": [ - { - "id": "msg_006", - "object": "realtime.item", - "type": "message", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "text", - "text": "Sure, how can I assist you today?" - } - ] - } - ], - "usage": { - "total_tokens":275, - "input_tokens":127, - "output_tokens":148, - "input_token_details": { - "cached_tokens":384, - "text_tokens":119, - "audio_tokens":8, - "cached_tokens_details": { - "text_tokens": 128, - "audio_tokens": 256 - } - }, - "output_token_details": { - "text_tokens":36, - "audio_tokens":112 - } - } - } + "type": "response.audio.transcript.done", + "response_id": "resp_123" } - RealtimeServerEventResponseFunctionCallArgumentsDelta: + ResponseCodeInterpreterCallCodeDeltaEvent: type: object - description: | - Returned when the model-generated function call arguments are updated. + description: Emitted when a partial code snippet is added by the code interpreter. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: > + The type of the event. Always + `response.code_interpreter_call.code.delta`. enum: - - response.function_call_arguments.delta - description: | - The event type, must be `response.function_call_arguments.delta`. + - response.code_interpreter_call.code.delta x-stainless-const: true - response_id: - type: string - description: The ID of the response. - item_id: - type: string - description: The ID of the function call item. output_index: type: integer - description: The index of the output item in the response. - call_id: - type: string - description: The ID of the function call. + description: > + The index of the output item that the code interpreter call is in + progress. delta: type: string - description: The arguments delta as a JSON string. + description: | + The partial code snippet added by the code interpreter. required: - - event_id - type - response_id - - item_id - output_index - - call_id - delta x-oaiMeta: - name: response.function_call_arguments.delta - group: realtime + name: response.code_interpreter_call.code.delta + group: responses example: | { - "event_id": "event_5354", - "type": "response.function_call_arguments.delta", - "response_id": "resp_002", - "item_id": "fc_001", - "output_index": 0, - "call_id": "call_001", - "delta": "{\"location\": \"San\"" + "type": "response.code_interpreter_call.code.delta", + "response_id": "resp-123", + "output_index": 0, + "delta": "partial code" } - RealtimeServerEventResponseFunctionCallArgumentsDone: + ResponseCodeInterpreterCallCodeDoneEvent: type: object - description: > - Returned when the model-generated function call arguments are done - streaming. - - Also emitted when a Response is interrupted, incomplete, or cancelled. + description: Emitted when code snippet output is finalized by the code interpreter. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: > + The type of the event. Always + `response.code_interpreter_call.code.done`. enum: - - response.function_call_arguments.done - description: | - The event type, must be `response.function_call_arguments.done`. + - response.code_interpreter_call.code.done x-stainless-const: true - response_id: - type: string - description: The ID of the response. - item_id: - type: string - description: The ID of the function call item. output_index: type: integer - description: The index of the output item in the response. - call_id: - type: string - description: The ID of the function call. - arguments: + description: > + The index of the output item that the code interpreter call is in + progress. + code: type: string - description: The final arguments as a JSON string. + description: | + The final code snippet output by the code interpreter. required: - - event_id - type - response_id - - item_id - output_index - - call_id - - arguments + - code x-oaiMeta: - name: response.function_call_arguments.done - group: realtime + name: response.code_interpreter_call.code.done + group: responses example: | { - "event_id": "event_5556", - "type": "response.function_call_arguments.done", - "response_id": "resp_002", - "item_id": "fc_001", - "output_index": 0, - "call_id": "call_001", - "arguments": "{\"location\": \"San Francisco\"}" + "type": "response.code_interpreter_call.code.done", + "response_id": "resp-123", + "output_index": 3, + "code": "console.log('done');" } - RealtimeServerEventResponseOutputItemAdded: + ResponseCodeInterpreterCallCompletedEvent: type: object - description: Returned when a new Item is created during Response generation. + description: Emitted when the code interpreter call is completed. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: > + The type of the event. Always + `response.code_interpreter_call.completed`. enum: - - response.output_item.added - description: The event type, must be `response.output_item.added`. + - response.code_interpreter_call.completed x-stainless-const: true - response_id: - type: string - description: The ID of the Response to which the item belongs. output_index: type: integer - description: The index of the output item in the Response. - item: - $ref: "#/components/schemas/RealtimeConversationItem" + description: > + The index of the output item that the code interpreter call is in + progress. + code_interpreter_call: + $ref: "#/components/schemas/CodeInterpreterToolCall" required: - - event_id - type - response_id - output_index - - item + - code_interpreter_call x-oaiMeta: - name: response.output_item.added - group: realtime + name: response.code_interpreter_call.completed + group: responses example: | { - "event_id": "event_3334", - "type": "response.output_item.added", - "response_id": "resp_001", - "output_index": 0, - "item": { - "id": "msg_007", - "object": "realtime.item", - "type": "message", - "status": "in_progress", - "role": "assistant", - "content": [] - } + "type": "response.code_interpreter_call.completed", + "response_id": "resp-123", + "output_index": 5, + "code_interpreter_call": {} } - RealtimeServerEventResponseOutputItemDone: + ResponseCodeInterpreterCallInProgressEvent: type: object - description: > - Returned when an Item is done streaming. Also emitted when a Response - is - - interrupted, incomplete, or cancelled. + description: Emitted when a code interpreter call is in progress. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: > + The type of the event. Always + `response.code_interpreter_call.in_progress`. enum: - - response.output_item.done - description: The event type, must be `response.output_item.done`. + - response.code_interpreter_call.in_progress x-stainless-const: true - response_id: - type: string - description: The ID of the Response to which the item belongs. output_index: type: integer - description: The index of the output item in the Response. - item: - $ref: "#/components/schemas/RealtimeConversationItem" + description: > + The index of the output item that the code interpreter call is in + progress. + code_interpreter_call: + $ref: "#/components/schemas/CodeInterpreterToolCall" required: - - event_id - type - response_id - output_index - - item + - code_interpreter_call x-oaiMeta: - name: response.output_item.done - group: realtime + name: response.code_interpreter_call.in_progress + group: responses example: | { - "event_id": "event_3536", - "type": "response.output_item.done", - "response_id": "resp_001", - "output_index": 0, - "item": { - "id": "msg_007", - "object": "realtime.item", - "type": "message", - "status": "completed", - "role": "assistant", - "content": [ - { - "type": "text", - "text": "Sure, I can help with that." - } - ] - } + "type": "response.code_interpreter_call.in.progress", + "response_id": "resp-123", + "output_index": 0, + "code_interpreter_call": {} } - RealtimeServerEventResponseTextDelta: + ResponseCodeInterpreterCallInterpretingEvent: type: object - description: Returned when the text value of a "text" content part is updated. + description: Emitted when the code interpreter is actively interpreting the code + snippet. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: > + The type of the event. Always + `response.code_interpreter_call.interpreting`. enum: - - response.text.delta - description: The event type, must be `response.text.delta`. + - response.code_interpreter_call.interpreting x-stainless-const: true - response_id: - type: string - description: The ID of the response. - item_id: - type: string - description: The ID of the item. output_index: type: integer - description: The index of the output item in the response. - content_index: - type: integer - description: The index of the content part in the item's content array. - delta: - type: string - description: The text delta. + description: > + The index of the output item that the code interpreter call is in + progress. + code_interpreter_call: + $ref: "#/components/schemas/CodeInterpreterToolCall" required: - - event_id - type - response_id - - item_id - output_index - - content_index - - delta + - code_interpreter_call x-oaiMeta: - name: response.text.delta - group: realtime + name: response.code_interpreter_call.interpreting + group: responses example: | { - "event_id": "event_4142", - "type": "response.text.delta", - "response_id": "resp_001", - "item_id": "msg_007", - "output_index": 0, - "content_index": 0, - "delta": "Sure, I can h" + "type": "response.code_interpreter_call.interpreting", + "response_id": "resp-123", + "output_index": 4, + "code_interpreter_call": {} } - RealtimeServerEventResponseTextDone: + ResponseCompletedEvent: type: object - description: > - Returned when the text value of a "text" content part is done streaming. - Also - - emitted when a Response is interrupted, incomplete, or cancelled. + description: Emitted when the model response is complete. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: | + The type of the event. Always `response.completed`. enum: - - response.text.done - description: The event type, must be `response.text.done`. + - response.completed x-stainless-const: true - response_id: + response: + $ref: "#/components/schemas/Response" + description: | + Properties of the completed response. + required: + - type + - response + x-oaiMeta: + name: response.completed + group: responses + example: > + { + "type": "response.completed", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "completed", + "error": null, + "incomplete_details": null, + "input": [], + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-mini-2024-07-18", + "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": {} + } + } + ResponseContentPartAddedEvent: + type: object + description: Emitted when a new content part is added. + properties: + type: type: string - description: The ID of the response. + 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 item. + 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 in the response. + 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 in the item's content array. - text: - type: string - description: The final text content. + description: | + The index of the content part that was added. + part: + x-oaiExpandable: true + $ref: "#/components/schemas/OutputContent" + description: | + The content part that was added. required: - - event_id - type - - response_id - item_id - output_index - content_index - - text + - part x-oaiMeta: - name: response.text.done - group: realtime - example: | - { - "event_id": "event_4344", - "type": "response.text.done", - "response_id": "resp_001", - "item_id": "msg_007", - "output_index": 0, - "content_index": 0, - "text": "Sure, I can help with that." + 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": [] + } } - RealtimeServerEventSessionCreated: + ResponseContentPartDoneEvent: type: object - description: > - Returned when a Session is created. Emitted automatically when a new - - connection is established as the first server event. This event will - contain - - the default Session configuration. + description: Emitted when a content part is done. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: | + The type of the event. Always `response.content_part.done`. enum: - - session.created - description: The event type, must be `session.created`. + - response.content_part.done x-stainless-const: true - session: - $ref: "#/components/schemas/RealtimeSession" + 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. + part: + x-oaiExpandable: true + $ref: "#/components/schemas/OutputContent" + description: | + The content part that is done. required: - - event_id - type - - session + - item_id + - output_index + - content_index + - part x-oaiMeta: - name: session.created - group: realtime - example: | + name: response.content_part.done + group: responses + example: > { - "event_id": "event_1234", - "type": "session.created", - "session": { - "id": "sess_001", - "object": "realtime.session", - "model": "gpt-4o-realtime-preview-2024-12-17", - "modalities": ["text", "audio"], - "instructions": "...model instructions here...", - "voice": "sage", - "input_audio_format": "pcm16", - "output_audio_format": "pcm16", - "input_audio_transcription": null, - "turn_detection": { - "type": "server_vad", - "threshold": 0.5, - "prefix_padding_ms": 300, - "silence_duration_ms": 200 - }, - "tools": [], - "tool_choice": "auto", - "temperature": 0.8, - "max_response_output_tokens": "inf" - } + "type": "response.content_part.done", + "item_id": "msg_123", + "output_index": 0, + "content_index": 0, + "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": [] + } } - RealtimeServerEventSessionUpdated: + ResponseCreatedEvent: type: object - description: > - Returned when a session is updated with a `session.update` event, - unless - - there is an error. + description: | + An event that is emitted when a response is created. properties: - event_id: - type: string - description: The unique ID of the server event. type: type: string + description: | + The type of the event. Always `response.created`. enum: - - session.updated - description: The event type, must be `session.updated`. + - response.created x-stainless-const: true - session: - $ref: "#/components/schemas/RealtimeSession" + response: + $ref: "#/components/schemas/Response" + description: | + The response that was created. required: - - event_id - type - - session + - response x-oaiMeta: - name: session.updated - group: realtime + name: response.created + group: responses example: | { - "event_id": "event_5678", - "type": "session.updated", - "session": { - "id": "sess_001", - "object": "realtime.session", - "model": "gpt-4o-realtime-preview-2024-12-17", - "modalities": ["text"], - "instructions": "New instructions", - "voice": "sage", - "input_audio_format": "pcm16", - "output_audio_format": "pcm16", - "input_audio_transcription": { - "model": "whisper-1" - }, - "turn_detection": null, - "tools": [], - "tool_choice": "none", - "temperature": 0.7, - "max_response_output_tokens": 200 - } + "type": "response.created", + "response": { + "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", + "object": "response", + "created_at": 1741487325, + "status": "in_progress", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "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": {} + } } - RealtimeSession: + ResponseError: type: object - description: Realtime session object configuration. - properties: - id: - type: string - description: | - Unique identifier for the session object. - modalities: - description: | - The set of modalities the model can respond with. To disable audio, - set this to ["text"]. - items: - type: string - enum: - - text - - audio - model: - description: | - The Realtime model used for this session. - anyOf: - - type: string - - type: string - enum: - - gpt-4o-realtime-preview - - gpt-4o-realtime-preview-2024-10-01 - - gpt-4o-realtime-preview-2024-12-17 - - gpt-4o-mini-realtime-preview - - gpt-4o-mini-realtime-preview-2024-12-17 - instructions: - type: string - description: > - The default system instructions (i.e. system message) prepended to - model - - calls. This field allows the client to guide the model on desired - - responses. The model can be instructed on response content and - format, - - (e.g. "be extremely succinct", "act friendly", "here are examples of - good - - responses") and on audio behavior (e.g. "talk quickly", "inject - emotion - - into your voice", "laugh frequently"). The instructions are not - guaranteed - - to be followed by the model, but they provide guidance to the model - on the - - desired behavior. - - - Note that the server sets default instructions which will be used if - this - - field is not set and are visible in the `session.created` event at - the - - start of the session. - voice: - type: string - enum: - - alloy - - ash - - ballad - - coral - - echo - - sage - - shimmer - - verse - description: > - The voice the model uses to respond. Voice cannot be changed during - the - - session once the model has responded with audio at least once. - Current - - voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, - - `shimmer` and `verse`. - input_audio_format: - type: string - enum: - - pcm16 - - g711_ulaw - - g711_alaw - description: > - The format of input audio. Options are `pcm16`, `g711_ulaw`, or - `g711_alaw`. - - For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, - - single channel (mono), and little-endian byte order. - output_audio_format: - type: string - enum: - - pcm16 - - g711_ulaw - - g711_alaw - description: > - The format of output audio. Options are `pcm16`, `g711_ulaw`, or - `g711_alaw`. - - For `pcm16`, output audio is sampled at a rate of 24kHz. - input_audio_transcription: - type: object - description: > - Configuration for input audio transcription, defaults to off and can - be - - set to `null` to turn off once on. Input audio transcription is not - native - - to the model, since the model consumes audio directly. Transcription - runs - - asynchronously through Whisper and should be treated as rough - guidance - - rather than the representation understood by the model. - properties: - model: - type: string - description: > - The model to use for transcription, `whisper-1` is the only - currently - - supported model. - turn_detection: - type: object + description: | + An error object returned when the model fails to generate a Response. + nullable: true + properties: + code: + $ref: "#/components/schemas/ResponseErrorCode" + message: + type: string + description: | + A human-readable description of the error. + required: + - code + - message + ResponseErrorCode: + type: string + description: | + The error code for the response. + enum: + - server_error + - rate_limit_exceeded + - invalid_prompt + - vector_store_timeout + - invalid_image + - invalid_image_format + - invalid_base64_image + - invalid_image_url + - image_too_large + - image_too_small + - image_parse_error + - image_content_policy_violation + - invalid_image_mode + - image_file_too_large + - unsupported_image_media_type + - empty_image_file + - failed_to_download_image + - image_file_not_found + ResponseErrorEvent: + type: object + description: Emitted when an error occurs. + properties: + type: + type: string + description: | + The type of the event. Always `error`. + enum: + - error + x-stainless-const: true + code: + type: string + description: | + The error code. nullable: true - description: > - Configuration for turn detection. Can be set to `null` to turn off. - Server - - VAD means that the model will detect the start and end of speech - based on - - audio volume and respond at the end of user speech. - properties: - type: - type: string - enum: - - server_vad - description: > - Type of turn detection, only `server_vad` is currently supported. - x-stainless-const: true - threshold: - type: number - description: > - Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. - A - - higher threshold will require louder audio to activate the - model, and - - thus might perform better in noisy environments. - prefix_padding_ms: - type: integer - description: | - Amount of audio to include before the VAD detected speech (in - milliseconds). Defaults to 300ms. - silence_duration_ms: - type: integer - description: > - Duration of silence to detect speech stop (in milliseconds). - Defaults - - to 500ms. With shorter values the model will respond more - quickly, - - but may jump in on short pauses from the user. - tools: - type: array - description: Tools (functions) available to the model. - items: - type: object - properties: - type: - type: string - enum: - - function - description: The type of the tool, i.e. `function`. - x-stainless-const: true - name: - type: string - description: The name of the function. - description: - type: string - description: > - The description of the function, including guidance on when - and how - - to call it, and guidance about what to tell the user when - calling - - (if anything). - parameters: - type: object - description: Parameters of the function in JSON Schema. - tool_choice: + message: type: string - description: > - How the model chooses tools. Options are `auto`, `none`, `required`, - or - - specify a function. - temperature: - type: number - description: > - Sampling temperature for the model, limited to [0.6, 1.2]. Defaults - to 0.8. - max_response_output_tokens: - oneOf: - - type: integer - - type: string - enum: - - inf - x-stainless-const: true description: | - Maximum number of output tokens for a single assistant response, - inclusive of tool calls. Provide an integer between 1 and 4096 to - limit output tokens, or `inf` for the maximum available tokens for a - given model. Defaults to `inf`. - RealtimeSessionCreateRequest: + The error message. + param: + type: string + description: | + The error parameter. + nullable: true + required: + - type + - code + - message + - param + x-oaiMeta: + name: error + group: responses + example: | + { + "type": "error", + "code": "ERR_SOMETHING", + "message": "Something went wrong", + "param": null + } + ResponseFailedEvent: type: object - description: Realtime session object configuration. + description: | + An event that is emitted when a response fails. properties: - modalities: + type: + type: string description: | - The set of modalities the model can respond with. To disable audio, - set this to ["text"]. - items: - type: string - enum: - - text - - audio - model: + The type of the event. Always `response.failed`. + enum: + - response.failed + x-stainless-const: true + response: + $ref: "#/components/schemas/Response" + description: | + The response that failed. + required: + - type + - response + x-oaiMeta: + name: response.failed + group: responses + example: | + { + "type": "response.failed", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "failed", + "error": { + "code": "server_error", + "message": "The model failed to generate a response." + }, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-mini-2024-07-18", + "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": {} + } + } + ResponseFileSearchCallCompletedEvent: + type: object + description: Emitted when a file search call is completed (results found). + properties: + type: type: string description: | - The Realtime model used for this session. + The type of the event. Always `response.file_search_call.completed`. enum: - - gpt-4o-realtime-preview - - gpt-4o-realtime-preview-2024-10-01 - - gpt-4o-realtime-preview-2024-12-17 - - gpt-4o-mini-realtime-preview - - gpt-4o-mini-realtime-preview-2024-12-17 - instructions: + - 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. + required: + - type + - output_index + - item_id + x-oaiMeta: + name: response.file_search_call.completed + group: responses + example: | + { + "type": "response.file_search_call.completed", + "output_index": 0, + "item_id": "fs_123", + } + ResponseFileSearchCallInProgressEvent: + type: object + description: Emitted when a file search call is initiated. + properties: + type: type: string description: > - The default system instructions (i.e. system message) prepended to - model - - calls. This field allows the client to guide the model on desired - - responses. The model can be instructed on response content and - format, - - (e.g. "be extremely succinct", "act friendly", "here are examples of - good - - responses") and on audio behavior (e.g. "talk quickly", "inject - emotion - - into your voice", "laugh frequently"). The instructions are not - guaranteed - - to be followed by the model, but they provide guidance to the model - on the - - desired behavior. - - - Note that the server sets default instructions which will be used if - this - - field is not set and are visible in the `session.created` event at - the - - start of the session. - voice: + 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. + required: + - type + - output_index + - item_id + 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", + } + ResponseFileSearchCallSearchingEvent: + type: object + description: Emitted when a file search is currently searching. + properties: + type: type: string + description: | + The type of the event. Always `response.file_search_call.searching`. enum: - - alloy - - ash - - ballad - - coral - - echo - - sage - - shimmer - - verse - description: > - The voice the model uses to respond. Voice cannot be changed during - the + - 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. + required: + - type + - output_index + - item_id + x-oaiMeta: + name: response.file_search_call.searching + group: responses + example: | + { + "type": "response.file_search_call.searching", + "output_index": 0, + "item_id": "fs_123", + } + ResponseFormatJsonObject: + type: object + title: JSON object + description: > + JSON object response format. An older method of generating JSON + responses. - session once the model has responded with audio at least once. - Current + Using `json_schema` is recommended for models that support it. Note that + the - voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, + model will not generate JSON without a system or user message + instructing it - `shimmer` and `verse`. - input_audio_format: + to do so. + properties: + type: type: string + description: The type of response format being defined. Always `json_object`. enum: - - pcm16 - - g711_ulaw - - g711_alaw - description: > - The format of input audio. Options are `pcm16`, `g711_ulaw`, or - `g711_alaw`. - - For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, - - single channel (mono), and little-endian byte order. - output_audio_format: + - json_object + x-stainless-const: true + required: + - type + ResponseFormatJsonSchema: + type: object + title: JSON schema + description: | + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). + properties: + type: type: string + description: The type of response format being defined. Always `json_schema`. enum: - - pcm16 - - g711_ulaw - - g711_alaw - description: > - The format of output audio. Options are `pcm16`, `g711_ulaw`, or - `g711_alaw`. - - For `pcm16`, output audio is sampled at a rate of 24kHz. - input_audio_transcription: + - json_schema + x-stainless-const: true + json_schema: type: object - description: > - Configuration for input audio transcription, defaults to off and can - be set to `null` to turn off once on. Input audio transcription is - not native to the model, since the model consumes audio directly. - Transcription runs asynchronously through [OpenAI Whisper - transcription](https://platform.openai.com/docs/api-reference/audio/createTranscription) - and should be treated as rough guidance rather than the - representation understood by the model. The client can optionally - set the language and prompt for transcription, these fields will be - passed to the Whisper API. + title: JSON schema + description: | + Structured Outputs configuration options, including a JSON Schema. properties: - model: - type: string - description: > - The model to use for transcription, `whisper-1` is the only - currently - - supported model. - language: - type: string - description: > - The language of the input audio. Supplying the input language in - - [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) - (e.g. `en`) format - - will improve accuracy and latency. - prompt: + description: type: string description: > - An optional text to guide the model's style or continue a - previous audio - - segment. The [prompt](/docs/guides/speech-to-text#prompting) - should match - - the audio language. - turn_detection: - type: object - description: > - Configuration for turn detection. Can be set to `null` to turn off. - Server - - VAD means that the model will detect the start and end of speech - based on + A description of what the response format is for, used by the + model to - audio volume and respond at the end of user speech. - properties: - type: + determine how to respond in the format. + name: type: string description: > - Type of turn detection, only `server_vad` is currently supported. - threshold: - type: number - description: > - Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. - A - - higher threshold will require louder audio to activate the - model, and + The name of the response format. Must be a-z, A-Z, 0-9, or + contain - thus might perform better in noisy environments. - prefix_padding_ms: - type: integer - description: | - Amount of audio to include before the VAD detected speech (in - milliseconds). Defaults to 300ms. - silence_duration_ms: - type: integer + underscores and dashes, with a maximum length of 64. + schema: + $ref: "#/components/schemas/ResponseFormatJsonSchemaSchema" + strict: + type: boolean + nullable: true + default: false description: > - Duration of silence to detect speech stop (in milliseconds). - Defaults + Whether to enable strict schema adherence when generating the + output. - to 500ms. With shorter values the model will respond more - quickly, + If set to true, the model will always follow the exact schema + defined - but may jump in on short pauses from the user. - create_response: - type: boolean - default: true - description: | - Whether or not to automatically generate a response when VAD is - enabled. `true` by default. - tools: - type: array - description: Tools (functions) available to the model. - items: - type: object - properties: - type: - type: string - enum: - - function - description: The type of the tool, i.e. `function`. - x-stainless-const: true - name: - type: string - description: The name of the function. - description: - type: string - description: > - The description of the function, including guidance on when - and how + in the `schema` field. Only a subset of JSON Schema is supported + when - to call it, and guidance about what to tell the user when - calling + `strict` is `true`. To learn more, read the [Structured Outputs - (if anything). - parameters: - type: object - description: Parameters of the function in JSON Schema. - tool_choice: + guide](/docs/guides/structured-outputs). + required: + - name + required: + - type + - json_schema + ResponseFormatJsonSchemaSchema: + 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 + ResponseFormatText: + 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 + ResponseFunctionCallArgumentsDeltaEvent: + type: object + description: Emitted when there is a partial function-call arguments delta. + properties: + type: type: string description: > - How the model chooses tools. Options are `auto`, `none`, `required`, - or - - specify a function. - temperature: - type: number + 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: > - Sampling temperature for the model, limited to [0.6, 1.2]. Defaults - to 0.8. - max_response_output_tokens: - oneOf: - - type: integer - - type: string - enum: - - inf - x-stainless-const: true + 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. + delta: + type: string + description: | + The function-call arguments delta that is added. + required: + - type + - item_id + - output_index + - delta + 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\":" + } + ResponseFunctionCallArgumentsDoneEvent: + type: object + description: Emitted when function-call arguments are finalized. + properties: + 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. + arguments: + type: string + description: The function-call arguments. + required: + - type + - item_id + - output_index + - arguments + 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 }" + } + ResponseInProgressEvent: + type: object + description: Emitted when the response is in progress. + properties: + 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/Response" description: | - Maximum number of output tokens for a single assistant response, - inclusive of tool calls. Provide an integer between 1 and 4096 to - limit output tokens, or `inf` for the maximum available tokens for a - given model. Defaults to `inf`. - RealtimeSessionCreateResponse: + The response that is in progress. + required: + - type + - response + 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", + "error": null, + "incomplete_details": null, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-2024-08-06", + "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": {} + } + } + ResponseIncompleteEvent: type: object - description: > - A new Realtime session configuration, with an ephermeral key. Default - TTL - - for keys is one minute. + description: | + An event that is emitted when a response finishes as incomplete. properties: - client_secret: - type: object - description: Ephemeral key returned by the API. - properties: - value: - type: string - description: > - Ephemeral key usable in client environments to authenticate - connections - - to the Realtime API. Use this in client-side environments rather - than - - a standard API token, which should only be used server-side. - expires_at: - type: integer - description: > - Timestamp for when the token expires. Currently, all tokens - expire - - after one minute. - required: - - value - - expires_at - modalities: + type: + type: string description: | - The set of modalities the model can respond with. To disable audio, - set this to ["text"]. + The type of the event. Always `response.incomplete`. + enum: + - response.incomplete + x-stainless-const: true + response: + $ref: "#/components/schemas/Response" + description: | + The response that was incomplete. + required: + - type + - response + x-oaiMeta: + name: response.incomplete + group: responses + example: | + { + "type": "response.incomplete", + "response": { + "id": "resp_123", + "object": "response", + "created_at": 1740855869, + "status": "incomplete", + "error": null, + "incomplete_details": { + "reason": "max_tokens" + }, + "instructions": null, + "max_output_tokens": null, + "model": "gpt-4o-mini-2024-07-18", + "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": {} + } + } + ResponseItemList: + type: object + description: A list of Response items. + properties: + object: + type: string + description: The type of object returned, must be `list`. + enum: + - list + x-stainless-const: true + data: + type: array + description: A list of items used to generate this response. items: - type: string - enum: - - text - - audio - instructions: + $ref: "#/components/schemas/ItemResource" + has_more: + type: boolean + description: Whether there are more items available. + first_id: type: string - description: > - The default system instructions (i.e. system message) prepended to - model + 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-oaiExpandable: true + 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 + } + ResponseModalities: + type: array + nullable: true + description: > + Output types that you would like the model to generate. - calls. This field allows the client to guide the model on desired + Most models are capable of generating text, which is the default: - responses. The model can be instructed on response content and - format, - (e.g. "be extremely succinct", "act friendly", "here are examples of - good + `["text"]` - responses") and on audio behavior (e.g. "talk quickly", "inject - emotion - into your voice", "laugh frequently"). The instructions are not - guaranteed + The `gpt-4o-audio-preview` model can also be used to - to be followed by the model, but they provide guidance to the model - on the + [generate audio](/docs/guides/audio). To request that this model + generate - desired behavior. + both text and audio responses, you can use: - Note that the server sets default instructions which will be used if - this + `["text", "audio"]` + items: + type: string + enum: + - text + - audio + ResponseModalitiesTextOnly: + type: array + nullable: true + description: > + Output types that you would like the model to generate. - field is not set and are visible in the `session.created` event at - the + Most models are capable of generating text, which is the default: - start of the session. - voice: - type: string - enum: - - alloy - - ash - - ballad - - coral - - echo - - sage - - shimmer - - verse - description: > - The voice the model uses to respond. Voice cannot be changed during - the - session once the model has responded with audio at least once. - Current + `["text"]` - voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, - `shimmer` and `verse`. - input_audio_format: + This API will soon support other output modalities, including audio and + images. + items: + type: string + enum: + - text + ResponseOutputItemAddedEvent: + type: object + description: Emitted when a new output item is added. + properties: + type: type: string - description: > - The format of input audio. Options are `pcm16`, `g711_ulaw`, or - `g711_alaw`. - output_audio_format: + 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. + item: + $ref: "#/components/schemas/OutputItem" + x-oaiExpandable: true + description: | + The output item that was added. + required: + - type + - output_index + - item + 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": [] + } + } + ResponseOutputItemDoneEvent: + type: object + description: Emitted when an output item is marked done. + properties: + 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. + item: + $ref: "#/components/schemas/OutputItem" + x-oaiExpandable: true + description: | + The output item that was marked done. + required: + - type + - output_index + - item + 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": [] + } + ] + } + } + ResponseProperties: + type: object + properties: + previous_response_id: + 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](/docs/guides/conversation-state). + nullable: true + reasoning: + $ref: "#/components/schemas/Reasoning" + nullable: true + max_output_tokens: description: > - The format of output audio. Options are `pcm16`, `g711_ulaw`, or - `g711_alaw`. - input_audio_transcription: - type: object - description: > - Configuration for input audio transcription, defaults to off and can - be - - set to `null` to turn off once on. Input audio transcription is not - native + An upper bound for the number of tokens that can be generated for a + response, including visible output tokens and [reasoning + tokens](/docs/guides/reasoning). + type: integer + nullable: true + instructions: + type: string + description: > + Inserts a system (or developer) message as the first item in the + model's context. - to the model, since the model consumes audio directly. Transcription - runs - asynchronously through Whisper and should be treated as rough - guidance + When using along with `previous_response_id`, the instructions from + a previous - rather than the representation understood by the model. - properties: - model: - type: string - description: > - The model to use for transcription, `whisper-1` is the only - currently + response will be not be carried over to the next response. This + makes it simple - supported model. - turn_detection: + to swap out system (or developer) messages in new responses. + nullable: true + text: type: object description: > - Configuration for turn detection. Can be set to `null` to turn off. - Server + Configuration options for a text response from the model. Can be + plain - VAD means that the model will detect the start and end of speech - based on + text or structured JSON data. Learn more: - audio volume and respond at the end of user speech. + - [Text inputs and outputs](/docs/guides/text) + + - [Structured Outputs](/docs/guides/structured-outputs) properties: - type: - type: string - description: > - Type of turn detection, only `server_vad` is currently supported. - threshold: - type: number - description: > - Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. - A + format: + $ref: "#/components/schemas/TextResponseFormatConfiguration" + tools: + type: array + description: > + An array of tools the model may call while generating a response. + You - higher threshold will require louder audio to activate the - model, and + can specify which tool to use by setting the `tool_choice` + parameter. - thus might perform better in noisy environments. - prefix_padding_ms: - type: integer - description: | - Amount of audio to include before the VAD detected speech (in - milliseconds). Defaults to 300ms. - silence_duration_ms: - type: integer - description: > - Duration of silence to detect speech stop (in milliseconds). - Defaults - to 500ms. With shorter values the model will respond more - quickly, + The two categories of tools you can provide the model are: - but may jump in on short pauses from the user. - tools: - type: array - description: Tools (functions) available to the model. + + - **Built-in tools**: Tools that are provided by OpenAI that extend + the + model's capabilities, like [web search](/docs/guides/tools-web-search) + or [file search](/docs/guides/tools-file-search). Learn more about + [built-in tools](/docs/guides/tools). + - **Function calls (custom tools)**: Functions that are defined by + you, + enabling the model to call your own code. Learn more about + [function calling](/docs/guides/function-calling). items: - type: object - properties: - type: - type: string - enum: - - function - description: The type of the tool, i.e. `function`. - x-stainless-const: true - name: - type: string - description: The name of the function. - description: - type: string - description: > - The description of the function, including guidance on when - and how + $ref: "#/components/schemas/Tool" + tool_choice: + description: > + How the model should select which tool (or tools) to use when + generating - to call it, and guidance about what to tell the user when - calling + a response. See the `tools` parameter to see how to specify which + tools - (if anything). - parameters: - type: object - description: Parameters of the function in JSON Schema. - tool_choice: + the model can call. + x-oaiExpandable: true + oneOf: + - $ref: "#/components/schemas/ToolChoiceOptions" + - $ref: "#/components/schemas/ToolChoiceTypes" + - $ref: "#/components/schemas/ToolChoiceFunction" + truncation: type: string description: > - How the model chooses tools. Options are `auto`, `none`, `required`, - or - - specify a function. - temperature: - type: number + The truncation strategy to use for the model response. + + - `auto`: If the context of this response and previous ones exceeds + the model's context window size, the model will truncate the + response to fit the context window by dropping input items in the + middle of the conversation. + - `disabled` (default): If a model response will exceed the context + window + size for a model, the request will fail with a 400 error. + enum: + - auto + - disabled + nullable: true + default: disabled + ResponseRefusalDeltaEvent: + type: object + description: Emitted when there is a partial refusal text. + properties: + 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. + required: + - type + - item_id + - output_index + - content_index + - delta + 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" + } + ResponseRefusalDoneEvent: + type: object + description: Emitted when refusal text is finalized. + properties: + 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. + required: + - type + - item_id + - output_index + - content_index + - refusal + 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" + } + ResponseStreamEvent: + anyOf: + - $ref: "#/components/schemas/ResponseAudioDeltaEvent" + - $ref: "#/components/schemas/ResponseAudioDoneEvent" + - $ref: "#/components/schemas/ResponseAudioTranscriptDeltaEvent" + - $ref: "#/components/schemas/ResponseAudioTranscriptDoneEvent" + - $ref: "#/components/schemas/ResponseCodeInterpreterCallCodeDeltaEvent" + - $ref: "#/components/schemas/ResponseCodeInterpreterCallCodeDoneEvent" + - $ref: "#/components/schemas/ResponseCodeInterpreterCallCompletedEvent" + - $ref: "#/components/schemas/ResponseCodeInterpreterCallInProgressEvent" + - $ref: "#/components/schemas/ResponseCodeInterpreterCallInterpretingEvent" + - $ref: "#/components/schemas/ResponseCompletedEvent" + - $ref: "#/components/schemas/ResponseContentPartAddedEvent" + - $ref: "#/components/schemas/ResponseContentPartDoneEvent" + - $ref: "#/components/schemas/ResponseCreatedEvent" + - $ref: "#/components/schemas/ResponseErrorEvent" + - $ref: "#/components/schemas/ResponseFileSearchCallCompletedEvent" + - $ref: "#/components/schemas/ResponseFileSearchCallInProgressEvent" + - $ref: "#/components/schemas/ResponseFileSearchCallSearchingEvent" + - $ref: "#/components/schemas/ResponseFunctionCallArgumentsDeltaEvent" + - $ref: "#/components/schemas/ResponseFunctionCallArgumentsDoneEvent" + - $ref: "#/components/schemas/ResponseInProgressEvent" + - $ref: "#/components/schemas/ResponseFailedEvent" + - $ref: "#/components/schemas/ResponseIncompleteEvent" + - $ref: "#/components/schemas/ResponseOutputItemAddedEvent" + - $ref: "#/components/schemas/ResponseOutputItemDoneEvent" + - $ref: "#/components/schemas/ResponseRefusalDeltaEvent" + - $ref: "#/components/schemas/ResponseRefusalDoneEvent" + - $ref: "#/components/schemas/ResponseTextAnnotationDeltaEvent" + - $ref: "#/components/schemas/ResponseTextDeltaEvent" + - $ref: "#/components/schemas/ResponseTextDoneEvent" + - $ref: "#/components/schemas/ResponseWebSearchCallCompletedEvent" + - $ref: "#/components/schemas/ResponseWebSearchCallInProgressEvent" + - $ref: "#/components/schemas/ResponseWebSearchCallSearchingEvent" + discriminator: + propertyName: type + ResponseTextAnnotationDeltaEvent: + type: object + description: Emitted when a text annotation is added. + properties: + type: + type: string description: > - Sampling temperature for the model, limited to [0.6, 1.2]. Defaults - to 0.8. - max_response_output_tokens: - oneOf: - - type: integer - - type: string - enum: - - inf - x-stainless-const: true + The type of the event. Always + `response.output_text.annotation.added`. + enum: + - response.output_text.annotation.added + x-stainless-const: true + item_id: + type: string description: | - Maximum number of output tokens for a single assistant response, - inclusive of tool calls. Provide an integer between 1 and 4096 to - limit output tokens, or `inf` for the maximum available tokens for a - given model. Defaults to `inf`. + The ID of the output item that the text annotation was added to. + output_index: + type: integer + description: | + The index of the output item that the text annotation was added to. + content_index: + type: integer + description: | + The index of the content part that the text annotation was added to. + annotation_index: + type: integer + description: | + The index of the annotation that was added. + annotation: + $ref: "#/components/schemas/Annotation" required: - - client_secret + - type + - item_id + - output_index + - content_index + - annotation_index + - annotation x-oaiMeta: - name: The session object - group: realtime + name: response.output_text.annotation.added + group: responses example: | { - "id": "sess_001", - "object": "realtime.session", - "model": "gpt-4o-realtime-preview-2024-12-17", - "modalities": ["audio", "text"], - "instructions": "You are a friendly assistant.", - "voice": "alloy", - "input_audio_format": "pcm16", - "output_audio_format": "pcm16", - "input_audio_transcription": { - "model": "whisper-1" - }, - "turn_detection": null, - "tools": [], - "tool_choice": "none", - "temperature": 0.7, - "max_response_output_tokens": 200, - "client_secret": { - "value": "ek_abc123", - "expires_at": 1234567890 + "type": "response.output_text.annotation.added", + "item_id": "msg_abc123", + "output_index": 1, + "content_index": 0, + "annotation_index": 0, + "annotation": { + "type": "file_citation", + "index": 390, + "file_id": "file-4wDz5b167pAf72nx1h9eiN", + "filename": "dragons.pdf" } } - ReasoningEffort: - type: string - enum: - - low - - medium - - high - default: medium - nullable: true + ResponseTextDeltaEvent: + type: object + description: Emitted when there is an additional text delta. + properties: + 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. + required: + - type + - item_id + - output_index + - content_index + - delta + 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" + } + ResponseTextDoneEvent: + type: object + description: Emitted when text content is finalized. + properties: + 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. + required: + - type + - item_id + - output_index + - content_index + - text + 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." + } + ResponseUsage: + type: object description: | - **o1 and o3-mini models only** - - Constrains effort on reasoning for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Currently supported values are `low`, `medium`, and `high`. Reducing - reasoning effort can result in faster responses and fewer tokens used - on reasoning in a response. - ResponseFormatJsonObject: + 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. + 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. + required: + - input_tokens + - output_tokens + - output_tokens_details + - total_tokens + ResponseWebSearchCallCompletedEvent: type: object + description: Emitted when a web search call is completed. properties: type: type: string - description: "The type of response format being defined: `json_object`" + description: | + The type of the event. Always `response.web_search_call.completed`. enum: - - json_object + - 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. required: - type - ResponseFormatJsonSchema: + - output_index + - item_id + x-oaiMeta: + name: response.web_search_call.completed + group: responses + example: | + { + "type": "response.web_search_call.completed", + "output_index": 0, + "item_id": "ws_123", + } + ResponseWebSearchCallInProgressEvent: type: object + description: Emitted when a web search call is initiated. properties: type: type: string - description: "The type of response format being defined: `json_schema`" + description: > + The type of the event. Always `response.web_search_call.in_progress`. enum: - - json_schema + - response.web_search_call.in_progress x-stainless-const: true - json_schema: - type: object - properties: - 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/ResponseFormatJsonSchemaSchema" - strict: - type: boolean - nullable: true - 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](/docs/guides/structured-outputs). - required: - - name + 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. required: - type - - json_schema - ResponseFormatJsonSchemaSchema: - type: object - description: The schema for the response format, described as a JSON Schema object. - additionalProperties: true - ResponseFormatText: + - output_index + - item_id + 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", + } + ResponseWebSearchCallSearchingEvent: type: object + description: Emitted when a web search call is executing. properties: type: type: string - description: "The type of response format being defined: `text`" + description: | + The type of the event. Always `response.web_search_call.searching`. enum: - - text + - 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: | + Unique ID for the output item associated with the web search call. required: - type + - output_index + - item_id + x-oaiMeta: + name: response.web_search_call.searching + group: responses + example: | + { + "type": "response.web_search_call.searching", + "output_index": 0, + "item_id": "ws_123", + } RunCompletionUsage: type: object description: Usage statistics related to the run. This value will be `null` if @@ -23691,9 +29787,8 @@ components: parallel_tool_calls: $ref: "#/components/schemas/ParallelToolCalls" response_format: - allOf: - - $ref: "#/components/schemas/AssistantsApiResponseFormatOption" - - nullable: true + $ref: "#/components/schemas/AssistantsApiResponseFormatOption" + nullable: true required: - id - object @@ -24158,11 +30253,7 @@ components: description: The ranking options for the file search. properties: ranker: - type: string - description: The ranker used for the file search. - enum: - - default_2024_08_21 - x-stainless-const: true + $ref: "#/components/schemas/FileSearchRanker" score_threshold: type: number description: The score threshold for the file search. All values must be a @@ -24720,6 +30811,60 @@ components: - id - type - function + Screenshot: + type: object + title: Screenshot + description: | + A screenshot action. + properties: + type: + type: string + enum: + - screenshot + default: screenshot + description: | + Specifies the event type. For a screenshot action, this property is + always set to `screenshot`. + x-stainless-const: true + required: + - type + Scroll: + type: object + title: Scroll + description: | + A scroll action. + properties: + type: + type: string + enum: + - scroll + default: scroll + description: | + Specifies the event type. For a scroll action, this property is + always set to `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. + required: + - type + - x + - y + - scroll_x + - scroll_y StaticChunkingStrategy: type: object additionalProperties: false @@ -24745,6 +30890,8 @@ components: StaticChunkingStrategyRequestParam: type: object title: Static Chunking Strategy + description: Customize your own chunking strategy by setting chunk size and + chunk overlap. additionalProperties: false properties: type: @@ -24774,6 +30921,23 @@ components: required: - type - static + StopConfiguration: + description: | + Up to 4 sequences where the API will stop generating further tokens. The + returned text will not contain the stop sequence. + default: null + nullable: true + oneOf: + - type: string + default: <|endoftext|> + example: "\n" + nullable: true + - type: array + minItems: 1 + maxItems: 4 + items: + type: string + example: '["\n"]' SubmitToolOutputsRunRequest: type: object additionalProperties: false @@ -24800,6 +30964,84 @@ components: with a `data: [DONE]` message. required: - tool_outputs + TextResponseFormatConfiguration: + 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](/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. + oneOf: + - $ref: "#/components/schemas/ResponseFormatText" + - $ref: "#/components/schemas/TextResponseFormatJsonSchema" + - $ref: "#/components/schemas/ResponseFormatJsonObject" + x-oaiExpandable: true + TextResponseFormatJsonSchema: + type: object + title: JSON schema + description: | + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/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/ResponseFormatJsonSchemaSchema" + strict: + type: boolean + nullable: true + 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](/docs/guides/structured-outputs). + required: + - type + - schema ThreadObject: type: object title: Thread @@ -24891,6 +31133,79 @@ components: created. x-oaiMeta: dataDescription: "`data` is a [thread](/docs/api-reference/threads/object)" + Tool: + oneOf: + - $ref: "#/components/schemas/FileSearchTool" + - $ref: "#/components/schemas/FunctionTool" + - $ref: "#/components/schemas/ComputerTool" + - $ref: "#/components/schemas/WebSearchTool" + x-oaiExpandable: true + ToolChoiceFunction: + 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 + ToolChoiceOptions: + 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 + ToolChoiceTypes: + 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](/docs/guides/tools). + properties: + type: + type: string + description: | + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). + + Allowed values are: + - `file_search` + - `web_search_preview` + - `computer_use_preview` + enum: + - file_search + - web_search_preview + - computer_use_preview + - web_search_preview_2025_03_11 + required: + - type TranscriptionSegment: type: object properties: @@ -24989,6 +31304,38 @@ components: nullable: true required: - type + Type: + type: object + title: Type + description: | + An action to type in text. + properties: + type: + type: string + enum: + - type + default: type + description: | + Specifies the event type. For a type action, this property is + always set to `type`. + x-stainless-const: true + text: + type: string + description: | + The text to type. + required: + - type + - text + UpdateVectorStoreFileAttributesRequest: + type: object + additionalProperties: false + properties: + attributes: + $ref: "#/components/schemas/VectorStoreFileAttributes" + required: + - attributes + x-oaiMeta: + name: Update vector store file attributes request UpdateVectorStoreRequest: type: object additionalProperties: false @@ -25037,7 +31384,7 @@ components: - expired expires_at: type: integer - description: The Unix timestamp (in seconds) for when the Upload was created. + description: The Unix timestamp (in seconds) for when the Upload will expire. object: type: string description: The object type, which is always "upload". @@ -25115,6 +31462,41 @@ components: "created_at": 1719186911, "upload_id": "upload_abc123" } + UrlCitation: + type: object + title: URL citation + description: | + A citation for a web resource used to generate a model response. + properties: + url: + type: string + description: | + The URL of the web resource. + title: + type: string + description: | + The title of the web resource. + type: + type: string + description: | + The type of the URL citation. Always `url_citation`. + enum: + - url_citation + x-stainless-const: true + 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. + required: + - url + - title + - type + - start_index + - end_index UsageAudioSpeechesResult: type: object description: The aggregated audio speeches usage details of the specific time bucket. @@ -25690,6 +32072,34 @@ components: required: - anchor - days + VectorStoreFileAttributes: + 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, booleans, or numbers. + maxProperties: 16 + propertyNames: + type: string + maxLength: 64 + additionalProperties: + oneOf: + - type: string + maxLength: 512 + - type: number + - type: boolean + x-oaiTypeLabel: map + nullable: true VectorStoreFileBatchObject: type: object title: Vector store file batch @@ -25771,6 +32181,40 @@ components: "total": 100 } } + VectorStoreFileContentResponse: + type: object + description: Represents the parsed content of a vector store file. + properties: + object: + type: string + enum: + - vector_store.file_content.page + description: The object type, which is always `vector_store.file_content.page` + x-stainless-const: true + data: + type: array + description: Parsed content of the file. + items: + type: object + properties: + type: + type: string + description: The content type (currently only `"text"`) + text: + type: string + description: The text content + has_more: + type: boolean + description: Indicates if there are more content pages to fetch. + next_page: + type: string + description: The token for the next page, if any. + nullable: true + required: + - object + - data + - has_more + - next_page VectorStoreFileObject: type: object title: Vector store files @@ -25834,6 +32278,8 @@ components: - $ref: "#/components/schemas/StaticChunkingStrategyResponseParam" - $ref: "#/components/schemas/OtherChunkingStrategyResponseParam" x-oaiExpandable: true + attributes: + $ref: "#/components/schemas/VectorStoreFileAttributes" required: - id - object @@ -25946,7 +32392,6 @@ components: - metadata x-oaiMeta: name: The vector store object - beta: true example: | { "id": "vs_123", @@ -25963,9 +32408,265 @@ components: "failed": 0, "total": 100 }, - "metadata": {}, "last_used_at": 1698107661 } + VectorStoreSearchRequest: + type: object + additionalProperties: false + properties: + query: + description: A query string for a search + oneOf: + - type: string + - type: array + items: + type: string + description: A list of queries to search for. + minItems: 1 + rewrite_query: + description: Whether to rewrite the natural language query for vector search. + type: boolean + default: false + max_num_results: + description: The maximum number of results to return. This number should be + between 1 and 50 inclusive. + type: integer + default: 10 + minimum: 1 + maximum: 50 + filters: + description: A filter to apply based on file attributes. + oneOf: + - $ref: "#/components/schemas/ComparisonFilter" + - $ref: "#/components/schemas/CompoundFilter" + x-oaiExpandable: true + ranking_options: + description: Ranking options for search. + type: object + additionalProperties: false + properties: + ranker: + type: string + enum: + - auto + - default-2024-11-15 + default: auto + score_threshold: + type: number + minimum: 0 + maximum: 1 + default: 0 + required: + - query + x-oaiMeta: + name: Vector store search request + VectorStoreSearchResultContentObject: + type: object + additionalProperties: false + properties: + type: + description: The type of content. + type: string + enum: + - text + text: + description: The text content returned from search. + type: string + required: + - type + - text + x-oaiMeta: + name: Vector store search result content object + VectorStoreSearchResultItem: + type: object + additionalProperties: false + properties: + file_id: + type: string + description: The ID of the vector store file. + filename: + type: string + description: The name of the vector store file. + score: + type: number + description: The similarity score for the result. + minimum: 0 + maximum: 1 + attributes: + $ref: "#/components/schemas/VectorStoreFileAttributes" + content: + type: array + description: Content chunks from the file. + items: + $ref: "#/components/schemas/VectorStoreSearchResultContentObject" + required: + - file_id + - filename + - score + - attributes + - content + x-oaiMeta: + name: Vector store search result item + VectorStoreSearchResultsPage: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - vector_store.search_results.page + description: The object type, which is always `vector_store.search_results.page` + x-stainless-const: true + search_query: + type: array + items: + type: string + description: The query used for this search. + minItems: 1 + data: + type: array + description: The list of search result items. + items: + $ref: "#/components/schemas/VectorStoreSearchResultItem" + has_more: + type: boolean + description: Indicates if there are more results to fetch. + next_page: + type: string + description: The token for the next page, if any. + nullable: true + required: + - object + - search_query + - data + - has_more + - next_page + x-oaiMeta: + name: Vector store search results page + Wait: + type: object + title: Wait + description: | + A wait action. + properties: + type: + type: string + enum: + - wait + default: wait + description: | + Specifies the event type. For a wait action, this property is + always set to `wait`. + x-stainless-const: true + required: + - type + WebSearchContextSize: + type: string + 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. + enum: + - low + - medium + - high + default: medium + WebSearchLocation: + type: object + title: Web search location + description: Approximate location parameters for the search. + properties: + country: + type: string + description: > + The two-letter + + [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the + user, + + e.g. `US`. + region: + type: string + description: | + Free text input for the region of the user, e.g. `California`. + city: + type: string + description: | + Free text input for the city of the user, e.g. `San Francisco`. + timezone: + type: string + description: > + The [IANA + timezone](https://timeapi.io/documentation/iana-timezones) + + of the user, e.g. `America/Los_Angeles`. + WebSearchTool: + type: object + title: Web search + description: | + This tool searches the web for relevant results to use in a response. + Learn more about the [web search tool](/docs/guides/tools-web-search). + 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` + - `web_search_preview_2025_03_11` + user_location: + allOf: + - $ref: "#/components/schemas/WebSearchLocation" + - type: object + properties: + type: + type: string + description: | + The type of location approximation. Always `approximate`. + enum: + - approximate + x-stainless-const: true + required: + - type + nullable: true + search_context_size: + $ref: "#/components/schemas/WebSearchContextSize" + required: + - type + WebSearchToolCall: + type: object + title: Web search tool call + description: | + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. + properties: + 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: + type: string + description: | + The status of the web search tool call. + enum: + - in_progress + - searching + - completed + - failed + required: + - id + - type + - status securitySchemes: ApiKeyAuth: type: http @@ -25974,19 +32675,97 @@ security: - ApiKeyAuth: [] x-oaiMeta: navigationGroups: + - id: chat + title: Chat Completions - id: endpoints - title: Endpoints - - id: assistants - title: Assistants + title: Platform APIs + - id: responses + title: Responses + - id: vector_stores + title: Vector stores + - id: realtime + title: Realtime beta: true - id: administration title: Administration - - id: realtime - title: Realtime + - id: assistants + title: Assistants beta: true - id: legacy title: Legacy groups: + - id: chat + title: Chat Completions + description: > + The Chat Completions API endpoint will generate a model response from a + + list of messages comprising a conversation. + + + Related guides: + + - [Quickstart](/docs/quickstart?api-mode=chat) + + - [Text inputs and outputs](/docs/guides/text?api-mode=chat) + + - [Image inputs](/docs/guides/images?api-mode=chat) + + - [Audio inputs and outputs](/docs/guides/audio?api-mode=chat) + + - [Structured Outputs](/docs/guides/structured-outputs?api-mode=chat) + + - [Function calling](/docs/guides/function-calling?api-mode=chat) + + - [Conversation state](/docs/guides/conversation-state?api-mode=chat) + + + **Starting a new project?** We recommend trying + [Responses](/docs/api-reference/responses) + + to take advantage of the latest OpenAI platform features. Compare + + [Chat Completions with + Responses](/docs/guides/responses-vs-chat-completions?api-mode=responses). + navigationGroup: chat + sections: + - type: endpoint + key: createChatCompletion + path: create + - type: endpoint + key: getChatCompletion + path: get + - type: endpoint + key: getChatCompletionMessages + path: getMessages + - type: endpoint + key: listChatCompletions + path: list + - type: endpoint + key: updateChatCompletion + path: update + - type: endpoint + key: deleteChatCompletion + path: delete + - type: object + key: CreateChatCompletionResponse + path: object + - type: object + key: ChatCompletionList + path: list-object + - type: object + key: ChatCompletionMessageList + path: message-list + - id: chat-streaming + title: Streaming + description: | + Stream Chat Completions in real time. Receive chunks of completions + returned from the model using server-sent events. + [Learn more](/docs/guides/streaming-responses?api-mode=chat). + navigationGroup: chat + sections: + - type: object + key: CreateChatCompletionStreamResponse + path: streaming - id: audio title: Audio description: | @@ -26010,24 +32789,6 @@ x-oaiMeta: - type: object key: CreateTranscriptionResponseVerboseJson path: verbose-json-object - - id: chat - title: Chat - description: > - Given a list of messages comprising a conversation, the model will - return a response. - - Related guide: [Chat Completions](/docs/guides/text-generation) - navigationGroup: endpoints - sections: - - type: endpoint - key: createChatCompletion - path: create - - type: object - key: CreateChatCompletionResponse - path: object - - type: object - key: CreateChatCompletionStreamResponse - path: streaming - id: embeddings title: Embeddings description: > @@ -26225,143 +32986,306 @@ x-oaiMeta: - type: object key: CreateModerationResponse path: object - - id: assistants - title: Assistants - beta: true - description: | - Build assistants that can call models and use tools to perform tasks. + - id: responses + title: Responses + description: > + OpenAI's most advanced interface for generating model responses. + Supports - [Get started with the Assistants API](/docs/assistants) - navigationGroup: assistants + text and image inputs, and text outputs. Create stateful interactions + + with the model, using the output of previous responses as input. Extend + + the model's capabilities with built-in tools for file search, web + search, + + computer use, and more. Allow the model access to external systems and + data + + using function calling. + + + Related guides: + + - [Quickstart](/docs/quickstart?api-mode=responses) + + - [Text inputs and outputs](/docs/guides/text?api-mode=responses) + + - [Image inputs](/docs/guides/images?api-mode=responses) + + - [Structured + Outputs](/docs/guides/structured-outputs?api-mode=responses) + + - [Function calling](/docs/guides/function-calling?api-mode=responses) + + - [Conversation + state](/docs/guides/conversation-state?api-mode=responses) + + - [Extend the models with tools](/docs/guides/tools?api-mode=responses) + navigationGroup: responses sections: - type: endpoint - key: createAssistant - path: createAssistant - - type: endpoint - key: listAssistants - path: listAssistants + key: createResponse + path: create - type: endpoint - key: getAssistant - path: getAssistant + key: getResponse + path: get - type: endpoint - key: modifyAssistant - path: modifyAssistant + key: deleteResponse + path: delete - type: endpoint - key: deleteAssistant - path: deleteAssistant + key: listInputItems + path: input-items - type: object - key: AssistantObject + key: Response path: object - - id: threads - title: Threads + - type: object + key: ResponseItemList + path: list + - id: responses-streaming + title: Streaming + description: > + When you [create a Response](/docs/api-reference/responses/create) with + + `stream` set to `true`, the server will emit server-sent events to the + + client as the Response is generated. This section contains the events + that + + are emitted by the server. + + + [Learn more about streaming + responses](/docs/guides/streaming-responses?api-mode=responses). + navigationGroup: responses + sections: + - type: object + key: ResponseCreatedEvent + path: + - type: object + key: ResponseInProgressEvent + path: + - type: object + key: ResponseCompletedEvent + path: + - type: object + key: ResponseFailedEvent + path: + - type: object + key: ResponseIncompleteEvent + path: + - type: object + key: ResponseOutputItemAddedEvent + path: + - type: object + key: ResponseOutputItemDoneEvent + path: + - type: object + key: ResponseContentPartAddedEvent + path: + - type: object + key: ResponseContentPartDoneEvent + path: + - type: object + key: ResponseTextDeltaEvent + path: + - type: object + key: ResponseTextAnnotationDeltaEvent + path: + - type: object + key: ResponseTextDoneEvent + path: + - type: object + key: ResponseRefusalDeltaEvent + path: + - type: object + key: ResponseRefusalDoneEvent + path: + - type: object + key: ResponseFunctionCallArgumentsDeltaEvent + path: + - type: object + key: ResponseFunctionCallArgumentsDoneEvent + path: + - type: object + key: ResponseFileSearchCallInProgressEvent + path: + - type: object + key: ResponseFileSearchCallSearchingEvent + path: + - type: object + key: ResponseFileSearchCallCompletedEvent + path: + - type: object + key: ResponseWebSearchCallInProgressEvent + path: + - type: object + key: ResponseWebSearchCallSearchingEvent + path: + - type: object + key: ResponseWebSearchCallCompletedEvent + path: + - type: object + key: ResponseErrorEvent + path: + - id: realtime + title: Realtime beta: true description: | - Create threads that assistants can interact with. + Communicate with a GPT-4o class model in real time using WebRTC or + WebSockets. Supports text and audio inputs and ouputs, along with audio + transcriptions. + [Learn more about the Realtime API](/docs/guides/realtime). + navigationGroup: realtime + - id: realtime-sessions + title: Session tokens + description: > + REST API endpoint to generate ephemeral session tokens for use in + client-side - Related guide: [Assistants](/docs/assistants/overview) - navigationGroup: assistants + applications. + navigationGroup: realtime sections: - type: endpoint - key: createThread - path: createThread - - type: endpoint - key: getThread - path: getThread - - type: endpoint - key: modifyThread - path: modifyThread - - type: endpoint - key: deleteThread - path: deleteThread + key: create-realtime-session + path: create + - type: object + key: RealtimeSessionCreateResponse + path: session_object + - id: realtime-client-events + title: Client events + description: > + These are events that the OpenAI Realtime WebSocket server will accept + from the client. + navigationGroup: realtime + sections: + - type: object + key: RealtimeClientEventSessionUpdate + path: + - type: object + key: RealtimeClientEventInputAudioBufferAppend + path: + - type: object + key: RealtimeClientEventInputAudioBufferCommit + path: + - type: object + key: RealtimeClientEventInputAudioBufferClear + path: + - type: object + key: RealtimeClientEventConversationItemCreate + path: + - type: object + key: RealtimeClientEventConversationItemTruncate + path: + - type: object + key: RealtimeClientEventConversationItemDelete + path: + - type: object + key: RealtimeClientEventResponseCreate + path: + - type: object + key: RealtimeClientEventResponseCancel + path: + - id: realtime-server-events + title: Server events + description: > + These are events emitted from the OpenAI Realtime WebSocket server to + the client. + navigationGroup: realtime + sections: + - type: object + key: RealtimeServerEventError + path: + - type: object + key: RealtimeServerEventSessionCreated + path: + - type: object + key: RealtimeServerEventSessionUpdated + path: + - type: object + key: RealtimeServerEventConversationCreated + path: + - type: object + key: RealtimeServerEventConversationItemCreated + path: + - type: object + key: RealtimeServerEventConversationItemInputAudioTranscriptionCompleted + path: + - type: object + key: RealtimeServerEventConversationItemInputAudioTranscriptionFailed + path: + - type: object + key: RealtimeServerEventConversationItemTruncated + path: + - type: object + key: RealtimeServerEventConversationItemDeleted + path: + - type: object + key: RealtimeServerEventInputAudioBufferCommitted + path: + - type: object + key: RealtimeServerEventInputAudioBufferCleared + path: + - type: object + key: RealtimeServerEventInputAudioBufferSpeechStarted + path: + - type: object + key: RealtimeServerEventInputAudioBufferSpeechStopped + path: + - type: object + key: RealtimeServerEventResponseCreated + path: + - type: object + key: RealtimeServerEventResponseDone + path: + - type: object + key: RealtimeServerEventResponseOutputItemAdded + path: + - type: object + key: RealtimeServerEventResponseOutputItemDone + path: + - type: object + key: RealtimeServerEventResponseContentPartAdded + path: + - type: object + key: RealtimeServerEventResponseContentPartDone + path: + - type: object + key: RealtimeServerEventResponseTextDelta + path: + - type: object + key: RealtimeServerEventResponseTextDone + path: + - type: object + key: RealtimeServerEventResponseAudioTranscriptDelta + path: - type: object - key: ThreadObject - path: object - - id: messages - title: Messages - beta: true - description: | - Create messages within threads - - Related guide: [Assistants](/docs/assistants/overview) - navigationGroup: assistants - sections: - - type: endpoint - key: createMessage - path: createMessage - - type: endpoint - key: listMessages - path: listMessages - - type: endpoint - key: getMessage - path: getMessage - - type: endpoint - key: modifyMessage - path: modifyMessage - - type: endpoint - key: deleteMessage - path: deleteMessage + key: RealtimeServerEventResponseAudioTranscriptDone + path: - type: object - key: MessageObject - path: object - - id: runs - title: Runs - beta: true - description: | - Represents an execution run on a thread. - - Related guide: [Assistants](/docs/assistants/overview) - navigationGroup: assistants - sections: - - type: endpoint - key: createRun - path: createRun - - type: endpoint - key: createThreadAndRun - path: createThreadAndRun - - type: endpoint - key: listRuns - path: listRuns - - type: endpoint - key: getRun - path: getRun - - type: endpoint - key: modifyRun - path: modifyRun - - type: endpoint - key: submitToolOuputsToRun - path: submitToolOutputs - - type: endpoint - key: cancelRun - path: cancelRun + key: RealtimeServerEventResponseAudioDelta + path: - type: object - key: RunObject - path: object - - id: run-steps - title: Run steps - beta: true - description: | - Represents the steps (model and tool calls) taken during the run. - - Related guide: [Assistants](/docs/assistants/overview) - navigationGroup: assistants - sections: - - type: endpoint - key: listRunSteps - path: listRunSteps - - type: endpoint - key: getRunStep - path: getRunStep + key: RealtimeServerEventResponseAudioDone + path: - type: object - key: RunStepObject - path: step-object + key: RealtimeServerEventResponseFunctionCallArgumentsDelta + path: + - type: object + key: RealtimeServerEventResponseFunctionCallArgumentsDone + path: + - type: object + key: RealtimeServerEventRateLimitsUpdated + path: - id: vector-stores title: Vector stores - beta: true - description: | - Vector stores are used to store files for use by the `file_search` tool. + description: > + Vector stores power semantic search for the Retrieval API and the + `file_search` tool in the Responses and Assistants APIs. + Related guide: [File Search](/docs/assistants/tools/file-search) - navigationGroup: assistants + navigationGroup: vector_stores sections: - type: endpoint key: createVectorStore @@ -26378,17 +33302,19 @@ x-oaiMeta: - type: endpoint key: deleteVectorStore path: delete + - type: endpoint + key: searchVectorStore + path: search - type: object key: VectorStoreObject path: object - id: vector-stores-files title: Vector store files - beta: true description: | Vector store files represent files inside a vector store. Related guide: [File Search](/docs/assistants/tools/file-search) - navigationGroup: assistants + navigationGroup: vector_stores sections: - type: endpoint key: createVectorStoreFile @@ -26399,6 +33325,12 @@ x-oaiMeta: - type: endpoint key: getVectorStoreFile path: getFile + - type: endpoint + key: retrieveVectorStoreFileContent + path: getContent + - type: endpoint + key: updateVectorStoreFileAttributes + path: updateAttributes - type: endpoint key: deleteVectorStoreFile path: deleteFile @@ -26407,13 +33339,12 @@ x-oaiMeta: path: file-object - id: vector-stores-file-batches title: Vector store file batches - beta: true description: > Vector store file batches represent operations to add multiple files to a vector store. Related guide: [File Search](/docs/assistants/tools/file-search) - navigationGroup: assistants + navigationGroup: vector_stores sections: - type: endpoint key: createVectorStoreFileBatch @@ -26430,39 +33361,6 @@ x-oaiMeta: - type: object key: VectorStoreFileBatchObject path: batch-object - - id: assistants-streaming - title: Streaming - beta: true - description: > - Stream the result of executing a Run or resuming a Run after submitting - tool outputs. - - You can stream events from the [Create Thread and - Run](/docs/api-reference/runs/createThreadAndRun), - - [Create Run](/docs/api-reference/runs/createRun), and [Submit Tool - Outputs](/docs/api-reference/runs/submitToolOutputs) - - endpoints by passing `"stream": true`. The response will be a - [Server-Sent - events](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events) - stream. - - Our Node and Python SDKs provide helpful utilities to make streaming - easy. Reference the - - [Assistants API quickstart](/docs/assistants/overview) to learn more. - navigationGroup: assistants - sections: - - type: object - key: MessageDeltaObject - path: message-delta-object - - type: object - key: RunStepDeltaObject - path: run-step-delta-object - - type: object - key: AssistantStreamEvent - path: events - id: administration title: Administration description: > @@ -26702,208 +33600,221 @@ x-oaiMeta: navigationGroup: administration sections: - type: endpoint - key: usage-completions - path: completions - - type: object - key: UsageCompletionsResult - path: completions_object + key: usage-completions + path: completions + - type: object + key: UsageCompletionsResult + path: completions_object + - type: endpoint + key: usage-embeddings + path: embeddings + - type: object + key: UsageEmbeddingsResult + path: embeddings_object + - type: endpoint + key: usage-moderations + path: moderations + - type: object + key: UsageModerationsResult + path: moderations_object + - type: endpoint + key: usage-images + path: images + - type: object + key: UsageImagesResult + path: images_object + - type: endpoint + key: usage-audio-speeches + path: audio_speeches + - type: object + key: UsageAudioSpeechesResult + path: audio_speeches_object + - type: endpoint + key: usage-audio-transcriptions + path: audio_transcriptions + - type: object + key: UsageAudioTranscriptionsResult + path: audio_transcriptions_object + - type: endpoint + key: usage-vector-stores + path: vector_stores + - type: object + key: UsageVectorStoresResult + path: vector_stores_object + - type: endpoint + key: usage-code-interpreter-sessions + path: code_interpreter_sessions + - type: object + key: UsageCodeInterpreterSessionsResult + path: code_interpreter_sessions_object + - type: endpoint + key: usage-costs + path: costs + - type: object + key: CostsResult + path: costs_object + - id: assistants + title: Assistants + beta: true + description: | + Build assistants that can call models and use tools to perform tasks. + + [Get started with the Assistants API](/docs/assistants) + navigationGroup: assistants + sections: + - type: endpoint + key: createAssistant + path: createAssistant + - type: endpoint + key: listAssistants + path: listAssistants + - type: endpoint + key: getAssistant + path: getAssistant + - type: endpoint + key: modifyAssistant + path: modifyAssistant + - type: endpoint + key: deleteAssistant + path: deleteAssistant + - type: object + key: AssistantObject + path: object + - id: threads + title: Threads + beta: true + description: | + Create threads that assistants can interact with. + + Related guide: [Assistants](/docs/assistants/overview) + navigationGroup: assistants + sections: + - type: endpoint + key: createThread + path: createThread + - type: endpoint + key: getThread + path: getThread + - type: endpoint + key: modifyThread + path: modifyThread + - type: endpoint + key: deleteThread + path: deleteThread + - type: object + key: ThreadObject + path: object + - id: messages + title: Messages + beta: true + description: | + Create messages within threads + + Related guide: [Assistants](/docs/assistants/overview) + navigationGroup: assistants + sections: + - type: endpoint + key: createMessage + path: createMessage + - type: endpoint + key: listMessages + path: listMessages + - type: endpoint + key: getMessage + path: getMessage - type: endpoint - key: usage-embeddings - path: embeddings - - type: object - key: UsageEmbeddingsResult - path: embeddings_object + key: modifyMessage + path: modifyMessage - type: endpoint - key: usage-moderations - path: moderations + key: deleteMessage + path: deleteMessage - type: object - key: UsageModerationsResult - path: moderations_object + key: MessageObject + path: object + - id: runs + title: Runs + beta: true + description: | + Represents an execution run on a thread. + + Related guide: [Assistants](/docs/assistants/overview) + navigationGroup: assistants + sections: - type: endpoint - key: usage-images - path: images - - type: object - key: UsageImagesResult - path: images_object + key: createRun + path: createRun - type: endpoint - key: usage-audio-speeches - path: audio_speeches - - type: object - key: UsageAudioSpeechesResult - path: audio_speeches_object + key: createThreadAndRun + path: createThreadAndRun - type: endpoint - key: usage-audio-transcriptions - path: audio_transcriptions - - type: object - key: UsageAudioTranscriptionsResult - path: audio_transcriptions_object + key: listRuns + path: listRuns - type: endpoint - key: usage-vector-stores - path: vector_stores - - type: object - key: UsageVectorStoresResult - path: vector_stores_object + key: getRun + path: getRun - type: endpoint - key: usage-code-interpreter-sessions - path: code_interpreter_sessions - - type: object - key: UsageCodeInterpreterSessionsResult - path: code_interpreter_sessions_object + key: modifyRun + path: modifyRun - type: endpoint - key: usage-costs - path: costs + key: submitToolOuputsToRun + path: submitToolOutputs + - type: endpoint + key: cancelRun + path: cancelRun - type: object - key: CostsResult - path: costs_object - - id: realtime - title: Realtime + key: RunObject + path: object + - id: run-steps + title: Run steps beta: true description: | - Communicate with a GPT-4o class model in real time using WebRTC or - WebSockets. Supports text and audio inputs and ouputs, along with audio - transcriptions. - [Learn more about the Realtime API](/docs/guides/realtime). - navigationGroup: realtime - - id: realtime-sessions - title: Session tokens - description: > - REST API endpoint to generate ephemeral session tokens for use in - client-side + Represents the steps (model and tool calls) taken during the run. - applications. - navigationGroup: realtime + Related guide: [Assistants](/docs/assistants/overview) + navigationGroup: assistants sections: - type: endpoint - key: create-realtime-session - path: create - - type: object - key: RealtimeSessionCreateResponse - path: session_object - - id: realtime-client-events - title: Client events - description: > - These are events that the OpenAI Realtime WebSocket server will accept - from the client. - navigationGroup: realtime - sections: - - type: object - key: RealtimeClientEventSessionUpdate - path: - - type: object - key: RealtimeClientEventInputAudioBufferAppend - path: - - type: object - key: RealtimeClientEventInputAudioBufferCommit - path: - - type: object - key: RealtimeClientEventInputAudioBufferClear - path: - - type: object - key: RealtimeClientEventConversationItemCreate - path: - - type: object - key: RealtimeClientEventConversationItemTruncate - path: - - type: object - key: RealtimeClientEventConversationItemDelete - path: - - type: object - key: RealtimeClientEventResponseCreate - path: + key: listRunSteps + path: listRunSteps + - type: endpoint + key: getRunStep + path: getRunStep - type: object - key: RealtimeClientEventResponseCancel - path: - - id: realtime-server-events - title: Server events + key: RunStepObject + path: step-object + - id: assistants-streaming + title: Streaming + beta: true description: > - These are events emitted from the OpenAI Realtime WebSocket server to - the client. - navigationGroup: realtime + Stream the result of executing a Run or resuming a Run after submitting + tool outputs. + + You can stream events from the [Create Thread and + Run](/docs/api-reference/runs/createThreadAndRun), + + [Create Run](/docs/api-reference/runs/createRun), and [Submit Tool + Outputs](/docs/api-reference/runs/submitToolOutputs) + + endpoints by passing `"stream": true`. The response will be a + [Server-Sent + events](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events) + stream. + + Our Node and Python SDKs provide helpful utilities to make streaming + easy. Reference the + + [Assistants API quickstart](/docs/assistants/overview) to learn more. + navigationGroup: assistants sections: - type: object - key: RealtimeServerEventError - path: - - type: object - key: RealtimeServerEventSessionCreated - path: - - type: object - key: RealtimeServerEventSessionUpdated - path: - - type: object - key: RealtimeServerEventConversationCreated - path: - - type: object - key: RealtimeServerEventConversationItemCreated - path: - - type: object - key: RealtimeServerEventConversationItemInputAudioTranscriptionCompleted - path: - - type: object - key: RealtimeServerEventConversationItemInputAudioTranscriptionFailed - path: - - type: object - key: RealtimeServerEventConversationItemTruncated - path: - - type: object - key: RealtimeServerEventConversationItemDeleted - path: - - type: object - key: RealtimeServerEventInputAudioBufferCommitted - path: - - type: object - key: RealtimeServerEventInputAudioBufferCleared - path: - - type: object - key: RealtimeServerEventInputAudioBufferSpeechStarted - path: - - type: object - key: RealtimeServerEventInputAudioBufferSpeechStopped - path: - - type: object - key: RealtimeServerEventResponseCreated - path: - - type: object - key: RealtimeServerEventResponseDone - path: - - type: object - key: RealtimeServerEventResponseOutputItemAdded - path: - - type: object - key: RealtimeServerEventResponseOutputItemDone - path: - - type: object - key: RealtimeServerEventResponseContentPartAdded - path: - - type: object - key: RealtimeServerEventResponseContentPartDone - path: - - type: object - key: RealtimeServerEventResponseTextDelta - path: - - type: object - key: RealtimeServerEventResponseTextDone - path: - - type: object - key: RealtimeServerEventResponseAudioTranscriptDelta - path: - - type: object - key: RealtimeServerEventResponseAudioTranscriptDone - path: - - type: object - key: RealtimeServerEventResponseAudioDelta - path: - - type: object - key: RealtimeServerEventResponseAudioDone - path: - - type: object - key: RealtimeServerEventResponseFunctionCallArgumentsDelta - path: + key: MessageDeltaObject + path: message-delta-object - type: object - key: RealtimeServerEventResponseFunctionCallArgumentsDone - path: + key: RunStepDeltaObject + path: run-step-delta-object - type: object - key: RealtimeServerEventRateLimitsUpdated - path: + key: AssistantStreamEvent + path: events - id: completions title: Completions legacy: true