# openapi 3.1.0 # info ## title OpenAI API ## description The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference for more details. ## version 2.3.0 ## termsOfService https://openai.com/policies/terms-of-use ## contact ### name OpenAI Support ### url https://help.openai.com/ ## license ### name MIT ### url https://github.com/openai/openai-openapi/blob/master/LICENSE # servers ## url https://api.openai.com/v1 # security ## ApiKeyAuth # tags ## name Assistants ## description Build Assistants that can call models and use tools. ## name Audio ## description Turn audio into text or text into audio. ## name Chat ## description Given a list of messages comprising a conversation, the model will return a response. ## name Conversations ## description Manage conversations and conversation items. ## name Completions ## description Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position. ## name Embeddings ## description Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms. ## name Evals ## description Manage and run evals in the OpenAI platform. ## name Fine-tuning ## description Manage fine-tuning jobs to tailor a model to your specific training data. ## name Graders ## description Manage and run graders in the OpenAI platform. ## name Batch ## description Create large batches of API requests to run asynchronously. ## name Files ## description Files are used to upload documents that can be used with features like Assistants and Fine-tuning. ## name Uploads ## description Use Uploads to upload large files in multiple parts. ## name Images ## description Given a prompt and/or an input image, the model will generate a new image. ## name Models ## description List and describe the various models available in the API. ## name Moderations ## description Given text and/or image inputs, classifies if those inputs are potentially harmful. ## name Audit Logs ## description List user actions and configuration changes within this organization. # paths ## /assistants ### get #### operationId listAssistants #### tags - Assistants #### summary List assistants #### 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/ListAssistantsResponse #### x-oaiMeta ##### name List assistants ##### group assistants ##### beta true ##### returns A list of [assistant](https://platform.openai.com/docs/api-reference/assistants/object) objects. ##### examples ###### response { "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 } ###### request ####### curl curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.beta.assistants.list() page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const assistant of client.beta.assistants.list()) { console.log(assistant.id); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Beta.Assistants.List(context.TODO(), openai.BetaAssistantListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.assistants.AssistantListPage; import com.openai.models.beta.assistants.AssistantListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); AssistantListPage page = client.beta().assistants().list(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.beta.assistants.list puts(page) #### description Returns a list of assistants. ### post #### operationId createAssistant #### tags - Assistants #### summary Create assistant #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateAssistantRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/AssistantObject #### x-oaiMeta ##### name Create assistant ##### group assistants ##### beta true ##### returns An [assistant](https://platform.openai.com/docs/api-reference/assistants/object) object. ##### examples ###### title Code Interpreter ###### request ####### curl curl "https://api.openai.com/v1/assistants" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -d '{ "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", "name": "Math Tutor", "tools": [{"type": "code_interpreter"}], "model": "gpt-4o" }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) assistant = client.beta.assistants.create( model="gpt-4o", ) print(assistant.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const assistant = await client.beta.assistants.create({ model: 'gpt-4o' }); console.log(assistant.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/shared" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) assistant, err := client.Beta.Assistants.New(context.TODO(), openai.BetaAssistantNewParams{ Model: shared.ChatModelGPT5, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", assistant.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.ChatModel; import com.openai.models.beta.assistants.Assistant; import com.openai.models.beta.assistants.AssistantCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); AssistantCreateParams params = AssistantCreateParams.builder() .model(ChatModel.GPT_5) .build(); Assistant assistant = client.beta().assistants().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") assistant = openai.beta.assistants.create(model: :"gpt-5") puts(assistant) ###### response { "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" } ###### title Files ###### request ####### curl curl https://api.openai.com/v1/assistants \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -d '{ "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", "tools": [{"type": "file_search"}], "tool_resources": {"file_search": {"vector_store_ids": ["vs_123"]}}, "model": "gpt-4o" }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) assistant = client.beta.assistants.create( model="gpt-4o", ) print(assistant.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const assistant = await client.beta.assistants.create({ model: 'gpt-4o' }); console.log(assistant.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/shared" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) assistant, err := client.Beta.Assistants.New(context.TODO(), openai.BetaAssistantNewParams{ Model: shared.ChatModelGPT5, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", assistant.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.ChatModel; import com.openai.models.beta.assistants.Assistant; import com.openai.models.beta.assistants.AssistantCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); AssistantCreateParams params = AssistantCreateParams.builder() .model(ChatModel.GPT_5) .build(); Assistant assistant = client.beta().assistants().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") assistant = openai.beta.assistants.create(model: :"gpt-5") puts(assistant) ###### response { "id": "asst_abc123", "object": "assistant", "created_at": 1699009403, "name": "HR Helper", "description": null, "model": "gpt-4o", "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", "tools": [ { "type": "file_search" } ], "tool_resources": { "file_search": { "vector_store_ids": ["vs_123"] } }, "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" } #### description Create an assistant with a model and instructions. ## /assistants/{assistant_id} ### get #### operationId getAssistant #### tags - Assistants #### summary Retrieve assistant #### parameters ##### in path ##### name assistant_id ##### required true ##### schema ###### type string ##### description The ID of the assistant to retrieve. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/AssistantObject #### x-oaiMeta ##### name Retrieve assistant ##### group assistants ##### beta true ##### returns The [assistant](https://platform.openai.com/docs/api-reference/assistants/object) object matching the specified ID. ##### examples ###### response { "id": "asst_abc123", "object": "assistant", "created_at": 1699009709, "name": "HR Helper", "description": null, "model": "gpt-4o", "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", "tools": [ { "type": "file_search" } ], "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" } ###### request ####### curl curl https://api.openai.com/v1/assistants/asst_abc123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) assistant = client.beta.assistants.retrieve( "assistant_id", ) print(assistant.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const assistant = await client.beta.assistants.retrieve('assistant_id'); console.log(assistant.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) assistant, err := client.Beta.Assistants.Get(context.TODO(), "assistant_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", assistant.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.assistants.Assistant; import com.openai.models.beta.assistants.AssistantRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Assistant assistant = client.beta().assistants().retrieve("assistant_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") assistant = openai.beta.assistants.retrieve("assistant_id") puts(assistant) #### description Retrieves an assistant. ### post #### operationId modifyAssistant #### tags - Assistants #### summary Modify assistant #### parameters ##### in path ##### name assistant_id ##### required true ##### schema ###### type string ##### description The ID of the assistant to modify. #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ModifyAssistantRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/AssistantObject #### x-oaiMeta ##### name Modify assistant ##### group assistants ##### beta true ##### returns The modified [assistant](https://platform.openai.com/docs/api-reference/assistants/object) object. ##### examples ###### response { "id": "asst_123", "object": "assistant", "created_at": 1699009709, "name": "HR Helper", "description": null, "model": "gpt-4o", "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", "tools": [ { "type": "file_search" } ], "tool_resources": { "file_search": { "vector_store_ids": [] } }, "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" } ###### request ####### curl curl https://api.openai.com/v1/assistants/asst_abc123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -d '{ "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", "tools": [{"type": "file_search"}], "model": "gpt-4o" }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) assistant = client.beta.assistants.update( assistant_id="assistant_id", ) print(assistant.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const assistant = await client.beta.assistants.update('assistant_id'); console.log(assistant.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) assistant, err := client.Beta.Assistants.Update( context.TODO(), "assistant_id", openai.BetaAssistantUpdateParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", assistant.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.assistants.Assistant; import com.openai.models.beta.assistants.AssistantUpdateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Assistant assistant = client.beta().assistants().update("assistant_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") assistant = openai.beta.assistants.update("assistant_id") puts(assistant) #### description Modifies an assistant. ### delete #### operationId deleteAssistant #### tags - Assistants #### summary Delete assistant #### parameters ##### in path ##### name assistant_id ##### required true ##### schema ###### type string ##### description The ID of the assistant to delete. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/DeleteAssistantResponse #### x-oaiMeta ##### name Delete assistant ##### group assistants ##### beta true ##### returns Deletion status ##### examples ###### response { "id": "asst_abc123", "object": "assistant.deleted", "deleted": true } ###### request ####### curl curl https://api.openai.com/v1/assistants/asst_abc123 \ -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( api_key="My API Key", ) assistant_deleted = client.beta.assistants.delete( "assistant_id", ) print(assistant_deleted.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const assistantDeleted = await client.beta.assistants.delete('assistant_id'); console.log(assistantDeleted.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) assistantDeleted, err := client.Beta.Assistants.Delete(context.TODO(), "assistant_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", assistantDeleted.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.assistants.AssistantDeleteParams; import com.openai.models.beta.assistants.AssistantDeleted; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); AssistantDeleted assistantDeleted = client.beta().assistants().delete("assistant_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") assistant_deleted = openai.beta.assistants.delete("assistant_id") puts(assistant_deleted) #### description Delete an assistant. ## /audio/speech ### post #### operationId createSpeech #### tags - Audio #### summary Create speech #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateSpeechRequest #### responses ##### 200 ###### description OK ###### headers ####### Transfer-Encoding ######## schema ######### type string ######## description chunked ###### content ####### application/octet-stream ######## schema ######### type string ######### format binary ####### text/event-stream ######## schema ######### $ref #/components/schemas/CreateSpeechResponseStreamEvent #### x-oaiMeta ##### name Create speech ##### group audio ##### returns The audio file content or a [stream of audio events](https://platform.openai.com/docs/api-reference/audio/speech-audio-delta-event). ##### examples ###### title Default ###### request ####### curl curl https://api.openai.com/v1/audio/speech \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini-tts", "input": "The quick brown fox jumped over the lazy dog.", "voice": "alloy" }' \ --output speech.mp3 ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) speech = client.audio.speech.create( input="input", model="string", voice="ash", ) print(speech) content = speech.read() print(content) ####### javascript import fs from "fs"; import path from "path"; import OpenAI from "openai"; const openai = new OpenAI(); const speechFile = path.resolve("./speech.mp3"); async function main() { const mp3 = await openai.audio.speech.create({ model: "gpt-4o-mini-tts", voice: "alloy", input: "Today is a wonderful day to build something people love!", }); console.log(speechFile); const buffer = Buffer.from(await mp3.arrayBuffer()); await fs.promises.writeFile(speechFile, buffer); } main(); ####### csharp using System; using System.IO; using OpenAI.Audio; AudioClient client = new( model: "gpt-4o-mini-tts", 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); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const speech = await client.audio.speech.create({ input: 'input', model: 'string', voice: 'ash' }); console.log(speech); const content = await speech.blob(); console.log(content); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) speech, err := client.Audio.Speech.New(context.TODO(), openai.AudioSpeechNewParams{ Input: "input", Model: openai.SpeechModelTTS1, Voice: openai.AudioSpeechNewParamsVoiceAlloy, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", speech) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.core.http.HttpResponse; import com.openai.models.audio.speech.SpeechCreateParams; import com.openai.models.audio.speech.SpeechModel; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); SpeechCreateParams params = SpeechCreateParams.builder() .input("input") .model(SpeechModel.TTS_1) .voice(SpeechCreateParams.Voice.ALLOY) .build(); HttpResponse speech = client.audio().speech().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") speech = openai.audio.speech.create(input: "input", model: :"tts-1", voice: :alloy) puts(speech) ###### title SSE Stream Format ###### request ####### curl curl https://api.openai.com/v1/audio/speech \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini-tts", "input": "The quick brown fox jumped over the lazy dog.", "voice": "alloy", "stream_format": "sse" }' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const speech = await client.audio.speech.create({ input: 'input', model: 'string', voice: 'ash' }); console.log(speech); const content = await speech.blob(); console.log(content); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) speech = client.audio.speech.create( input="input", model="string", voice="ash", ) print(speech) content = speech.read() print(content) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) speech, err := client.Audio.Speech.New(context.TODO(), openai.AudioSpeechNewParams{ Input: "input", Model: openai.SpeechModelTTS1, Voice: openai.AudioSpeechNewParamsVoiceAlloy, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", speech) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.core.http.HttpResponse; import com.openai.models.audio.speech.SpeechCreateParams; import com.openai.models.audio.speech.SpeechModel; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); SpeechCreateParams params = SpeechCreateParams.builder() .input("input") .model(SpeechModel.TTS_1) .voice(SpeechCreateParams.Voice.ALLOY) .build(); HttpResponse speech = client.audio().speech().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") speech = openai.audio.speech.create(input: "input", model: :"tts-1", voice: :alloy) puts(speech) #### description Generates audio from the input text. ## /audio/transcriptions ### post #### operationId createTranscription #### tags - Audio #### summary Create transcription #### requestBody ##### required true ##### content ###### multipart/form-data ####### schema ######## $ref #/components/schemas/CreateTranscriptionRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### anyOf ########## $ref #/components/schemas/CreateTranscriptionResponseJson ########## $ref #/components/schemas/CreateTranscriptionResponseVerboseJson ########## x-stainless-skip - go ####### text/event-stream ######## schema ######### $ref #/components/schemas/CreateTranscriptionResponseStreamEvent #### x-oaiMeta ##### name Create transcription ##### group audio ##### returns The [transcription object](https://platform.openai.com/docs/api-reference/audio/json-object), a [verbose transcription object](https://platform.openai.com/docs/api-reference/audio/verbose-json-object) or a [stream of transcript events](https://platform.openai.com/docs/api-reference/audio/transcript-text-delta-event). ##### examples ###### title Default ###### request ####### curl curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F model="gpt-4o-transcribe" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) transcription = client.audio.transcriptions.create( file=b"raw file contents", model="gpt-4o-transcribe", ) print(transcription) ####### javascript import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const transcription = await openai.audio.transcriptions.create({ file: fs.createReadStream("audio.mp3"), model: "gpt-4o-transcribe", }); console.log(transcription.text); } main(); ####### csharp using System; using OpenAI.Audio; string audioFilePath = "audio.mp3"; AudioClient client = new( model: "gpt-4o-transcribe", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); AudioTranscription transcription = client.TranscribeAudio(audioFilePath); Console.WriteLine($"{transcription.Text}"); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const transcription = await client.audio.transcriptions.create({ file: fs.createReadStream('speech.mp3'), model: 'gpt-4o-transcribe', }); console.log(transcription); ####### go package main import ( "bytes" "context" "fmt" "io" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) transcription, err := client.Audio.Transcriptions.New(context.TODO(), openai.AudioTranscriptionNewParams{ File: io.Reader(bytes.NewBuffer([]byte("some file contents"))), Model: openai.AudioModelWhisper1, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", transcription) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.audio.AudioModel; import com.openai.models.audio.transcriptions.TranscriptionCreateParams; import com.openai.models.audio.transcriptions.TranscriptionCreateResponse; import java.io.ByteArrayInputStream; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); TranscriptionCreateParams params = TranscriptionCreateParams.builder() .file(ByteArrayInputStream("some content".getBytes())) .model(AudioModel.WHISPER_1) .build(); TranscriptionCreateResponse transcription = client.audio().transcriptions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") transcription = openai.audio.transcriptions.create(file: Pathname(__FILE__), model: :"whisper-1") puts(transcription) ###### 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.", "usage": { "type": "tokens", "input_tokens": 14, "input_token_details": { "text_tokens": 0, "audio_tokens": 14 }, "output_tokens": 45, "total_tokens": 59 } } ###### title Streaming ###### request ####### curl curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F model="gpt-4o-mini-transcribe" \ -F stream=true ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) transcription = client.audio.transcriptions.create( file=b"raw file contents", model="gpt-4o-transcribe", ) print(transcription) ####### javascript import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); const stream = await openai.audio.transcriptions.create({ file: fs.createReadStream("audio.mp3"), model: "gpt-4o-mini-transcribe", stream: true, }); for await (const event of stream) { console.log(event); } ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const transcription = await client.audio.transcriptions.create({ file: fs.createReadStream('speech.mp3'), model: 'gpt-4o-transcribe', }); console.log(transcription); ####### go package main import ( "bytes" "context" "fmt" "io" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) transcription, err := client.Audio.Transcriptions.New(context.TODO(), openai.AudioTranscriptionNewParams{ File: io.Reader(bytes.NewBuffer([]byte("some file contents"))), Model: openai.AudioModelWhisper1, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", transcription) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.audio.AudioModel; import com.openai.models.audio.transcriptions.TranscriptionCreateParams; import com.openai.models.audio.transcriptions.TranscriptionCreateResponse; import java.io.ByteArrayInputStream; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); TranscriptionCreateParams params = TranscriptionCreateParams.builder() .file(ByteArrayInputStream("some content".getBytes())) .model(AudioModel.WHISPER_1) .build(); TranscriptionCreateResponse transcription = client.audio().transcriptions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") transcription = openai.audio.transcriptions.create(file: Pathname(__FILE__), model: :"whisper-1") puts(transcription) ###### response data: {"type":"transcript.text.delta","delta":"I","logprobs":[{"token":"I","logprob":-0.00007588794,"bytes":[73]}]} data: {"type":"transcript.text.delta","delta":" see","logprobs":[{"token":" see","logprob":-3.1281633e-7,"bytes":[32,115,101,101]}]} data: {"type":"transcript.text.delta","delta":" skies","logprobs":[{"token":" skies","logprob":-2.3392786e-6,"bytes":[32,115,107,105,101,115]}]} data: {"type":"transcript.text.delta","delta":" of","logprobs":[{"token":" of","logprob":-3.1281633e-7,"bytes":[32,111,102]}]} data: {"type":"transcript.text.delta","delta":" blue","logprobs":[{"token":" blue","logprob":-1.0280384e-6,"bytes":[32,98,108,117,101]}]} data: {"type":"transcript.text.delta","delta":" and","logprobs":[{"token":" and","logprob":-0.0005108566,"bytes":[32,97,110,100]}]} data: {"type":"transcript.text.delta","delta":" clouds","logprobs":[{"token":" clouds","logprob":-1.9361265e-7,"bytes":[32,99,108,111,117,100,115]}]} data: {"type":"transcript.text.delta","delta":" of","logprobs":[{"token":" of","logprob":-1.9361265e-7,"bytes":[32,111,102]}]} data: {"type":"transcript.text.delta","delta":" white","logprobs":[{"token":" white","logprob":-7.89631e-7,"bytes":[32,119,104,105,116,101]}]} data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.0014890312,"bytes":[44]}]} data: {"type":"transcript.text.delta","delta":" the","logprobs":[{"token":" the","logprob":-0.0110956915,"bytes":[32,116,104,101]}]} data: {"type":"transcript.text.delta","delta":" bright","logprobs":[{"token":" bright","logprob":0.0,"bytes":[32,98,114,105,103,104,116]}]} data: {"type":"transcript.text.delta","delta":" blessed","logprobs":[{"token":" blessed","logprob":-0.000045848617,"bytes":[32,98,108,101,115,115,101,100]}]} data: {"type":"transcript.text.delta","delta":" days","logprobs":[{"token":" days","logprob":-0.000010802739,"bytes":[32,100,97,121,115]}]} data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.00001700133,"bytes":[44]}]} data: {"type":"transcript.text.delta","delta":" the","logprobs":[{"token":" the","logprob":-0.0000118755715,"bytes":[32,116,104,101]}]} data: {"type":"transcript.text.delta","delta":" dark","logprobs":[{"token":" dark","logprob":-5.5122365e-7,"bytes":[32,100,97,114,107]}]} data: {"type":"transcript.text.delta","delta":" sacred","logprobs":[{"token":" sacred","logprob":-5.4385737e-6,"bytes":[32,115,97,99,114,101,100]}]} data: {"type":"transcript.text.delta","delta":" nights","logprobs":[{"token":" nights","logprob":-4.00813e-6,"bytes":[32,110,105,103,104,116,115]}]} data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.0036910512,"bytes":[44]}]} data: {"type":"transcript.text.delta","delta":" and","logprobs":[{"token":" and","logprob":-0.0031903093,"bytes":[32,97,110,100]}]} data: {"type":"transcript.text.delta","delta":" I","logprobs":[{"token":" I","logprob":-1.504853e-6,"bytes":[32,73]}]} data: {"type":"transcript.text.delta","delta":" think","logprobs":[{"token":" think","logprob":-4.3202e-7,"bytes":[32,116,104,105,110,107]}]} data: {"type":"transcript.text.delta","delta":" to","logprobs":[{"token":" to","logprob":-1.9361265e-7,"bytes":[32,116,111]}]} data: {"type":"transcript.text.delta","delta":" myself","logprobs":[{"token":" myself","logprob":-1.7432603e-6,"bytes":[32,109,121,115,101,108,102]}]} data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.29254505,"bytes":[44]}]} data: {"type":"transcript.text.delta","delta":" what","logprobs":[{"token":" what","logprob":-0.016815351,"bytes":[32,119,104,97,116]}]} data: {"type":"transcript.text.delta","delta":" a","logprobs":[{"token":" a","logprob":-3.1281633e-7,"bytes":[32,97]}]} data: {"type":"transcript.text.delta","delta":" wonderful","logprobs":[{"token":" wonderful","logprob":-2.1008714e-6,"bytes":[32,119,111,110,100,101,114,102,117,108]}]} data: {"type":"transcript.text.delta","delta":" world","logprobs":[{"token":" world","logprob":-8.180258e-6,"bytes":[32,119,111,114,108,100]}]} data: {"type":"transcript.text.delta","delta":".","logprobs":[{"token":".","logprob":-0.014231676,"bytes":[46]}]} data: {"type":"transcript.text.done","text":"I see skies of blue and clouds of white, the bright blessed days, the dark sacred nights, and I think to myself, what a wonderful world.","logprobs":[{"token":"I","logprob":-0.00007588794,"bytes":[73]},{"token":" see","logprob":-3.1281633e-7,"bytes":[32,115,101,101]},{"token":" skies","logprob":-2.3392786e-6,"bytes":[32,115,107,105,101,115]},{"token":" of","logprob":-3.1281633e-7,"bytes":[32,111,102]},{"token":" blue","logprob":-1.0280384e-6,"bytes":[32,98,108,117,101]},{"token":" and","logprob":-0.0005108566,"bytes":[32,97,110,100]},{"token":" clouds","logprob":-1.9361265e-7,"bytes":[32,99,108,111,117,100,115]},{"token":" of","logprob":-1.9361265e-7,"bytes":[32,111,102]},{"token":" white","logprob":-7.89631e-7,"bytes":[32,119,104,105,116,101]},{"token":",","logprob":-0.0014890312,"bytes":[44]},{"token":" the","logprob":-0.0110956915,"bytes":[32,116,104,101]},{"token":" bright","logprob":0.0,"bytes":[32,98,114,105,103,104,116]},{"token":" blessed","logprob":-0.000045848617,"bytes":[32,98,108,101,115,115,101,100]},{"token":" days","logprob":-0.000010802739,"bytes":[32,100,97,121,115]},{"token":",","logprob":-0.00001700133,"bytes":[44]},{"token":" the","logprob":-0.0000118755715,"bytes":[32,116,104,101]},{"token":" dark","logprob":-5.5122365e-7,"bytes":[32,100,97,114,107]},{"token":" sacred","logprob":-5.4385737e-6,"bytes":[32,115,97,99,114,101,100]},{"token":" nights","logprob":-4.00813e-6,"bytes":[32,110,105,103,104,116,115]},{"token":",","logprob":-0.0036910512,"bytes":[44]},{"token":" and","logprob":-0.0031903093,"bytes":[32,97,110,100]},{"token":" I","logprob":-1.504853e-6,"bytes":[32,73]},{"token":" think","logprob":-4.3202e-7,"bytes":[32,116,104,105,110,107]},{"token":" to","logprob":-1.9361265e-7,"bytes":[32,116,111]},{"token":" myself","logprob":-1.7432603e-6,"bytes":[32,109,121,115,101,108,102]},{"token":",","logprob":-0.29254505,"bytes":[44]},{"token":" what","logprob":-0.016815351,"bytes":[32,119,104,97,116]},{"token":" a","logprob":-3.1281633e-7,"bytes":[32,97]},{"token":" wonderful","logprob":-2.1008714e-6,"bytes":[32,119,111,110,100,101,114,102,117,108]},{"token":" world","logprob":-8.180258e-6,"bytes":[32,119,111,114,108,100]},{"token":".","logprob":-0.014231676,"bytes":[46]}],"usage":{"input_tokens":14,"input_token_details":{"text_tokens":0,"audio_tokens":14},"output_tokens":45,"total_tokens":59}} ###### title Logprobs ###### request ####### curl curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F "include[]=logprobs" \ -F model="gpt-4o-transcribe" \ -F response_format="json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) transcription = client.audio.transcriptions.create( file=b"raw file contents", model="gpt-4o-transcribe", ) print(transcription) ####### javascript import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const transcription = await openai.audio.transcriptions.create({ file: fs.createReadStream("audio.mp3"), model: "gpt-4o-transcribe", response_format: "json", include: ["logprobs"] }); console.log(transcription); } main(); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const transcription = await client.audio.transcriptions.create({ file: fs.createReadStream('speech.mp3'), model: 'gpt-4o-transcribe', }); console.log(transcription); ####### go package main import ( "bytes" "context" "fmt" "io" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) transcription, err := client.Audio.Transcriptions.New(context.TODO(), openai.AudioTranscriptionNewParams{ File: io.Reader(bytes.NewBuffer([]byte("some file contents"))), Model: openai.AudioModelWhisper1, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", transcription) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.audio.AudioModel; import com.openai.models.audio.transcriptions.TranscriptionCreateParams; import com.openai.models.audio.transcriptions.TranscriptionCreateResponse; import java.io.ByteArrayInputStream; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); TranscriptionCreateParams params = TranscriptionCreateParams.builder() .file(ByteArrayInputStream("some content".getBytes())) .model(AudioModel.WHISPER_1) .build(); TranscriptionCreateResponse transcription = client.audio().transcriptions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") transcription = openai.audio.transcriptions.create(file: Pathname(__FILE__), model: :"whisper-1") puts(transcription) ###### response { "text": "Hey, my knee is hurting and I want to see the doctor tomorrow ideally.", "logprobs": [ { "token": "Hey", "logprob": -1.0415299, "bytes": [72, 101, 121] }, { "token": ",", "logprob": -9.805982e-5, "bytes": [44] }, { "token": " my", "logprob": -0.00229799, "bytes": [32, 109, 121] }, { "token": " knee", "logprob": -4.7159858e-5, "bytes": [32, 107, 110, 101, 101] }, { "token": " is", "logprob": -0.043909557, "bytes": [32, 105, 115] }, { "token": " hurting", "logprob": -1.1041146e-5, "bytes": [32, 104, 117, 114, 116, 105, 110, 103] }, { "token": " and", "logprob": -0.011076359, "bytes": [32, 97, 110, 100] }, { "token": " I", "logprob": -5.3193703e-6, "bytes": [32, 73] }, { "token": " want", "logprob": -0.0017156356, "bytes": [32, 119, 97, 110, 116] }, { "token": " to", "logprob": -7.89631e-7, "bytes": [32, 116, 111] }, { "token": " see", "logprob": -5.5122365e-7, "bytes": [32, 115, 101, 101] }, { "token": " the", "logprob": -0.0040786397, "bytes": [32, 116, 104, 101] }, { "token": " doctor", "logprob": -2.3392786e-6, "bytes": [32, 100, 111, 99, 116, 111, 114] }, { "token": " tomorrow", "logprob": -7.89631e-7, "bytes": [32, 116, 111, 109, 111, 114, 114, 111, 119] }, { "token": " ideally", "logprob": -0.5800861, "bytes": [32, 105, 100, 101, 97, 108, 108, 121] }, { "token": ".", "logprob": -0.00011093382, "bytes": [46] } ], "usage": { "type": "tokens", "input_tokens": 14, "input_token_details": { "text_tokens": 0, "audio_tokens": 14 }, "output_tokens": 45, "total_tokens": 59 } } ###### title Word timestamps ###### request ####### curl curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F "timestamp_granularities[]=word" \ -F model="whisper-1" \ -F response_format="verbose_json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) transcription = client.audio.transcriptions.create( file=b"raw file contents", model="gpt-4o-transcribe", ) print(transcription) ####### javascript import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const transcription = await openai.audio.transcriptions.create({ file: fs.createReadStream("audio.mp3"), model: "whisper-1", response_format: "verbose_json", timestamp_granularities: ["word"] }); console.log(transcription.text); } 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}"); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const transcription = await client.audio.transcriptions.create({ file: fs.createReadStream('speech.mp3'), model: 'gpt-4o-transcribe', }); console.log(transcription); ####### go package main import ( "bytes" "context" "fmt" "io" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) transcription, err := client.Audio.Transcriptions.New(context.TODO(), openai.AudioTranscriptionNewParams{ File: io.Reader(bytes.NewBuffer([]byte("some file contents"))), Model: openai.AudioModelWhisper1, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", transcription) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.audio.AudioModel; import com.openai.models.audio.transcriptions.TranscriptionCreateParams; import com.openai.models.audio.transcriptions.TranscriptionCreateResponse; import java.io.ByteArrayInputStream; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); TranscriptionCreateParams params = TranscriptionCreateParams.builder() .file(ByteArrayInputStream("some content".getBytes())) .model(AudioModel.WHISPER_1) .build(); TranscriptionCreateResponse transcription = client.audio().transcriptions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") transcription = openai.audio.transcriptions.create(file: Pathname(__FILE__), model: :"whisper-1") puts(transcription) ###### response { "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.", "words": [ { "word": "The", "start": 0.0, "end": 0.23999999463558197 }, ... { "word": "volleyball", "start": 7.400000095367432, "end": 7.900000095367432 } ], "usage": { "type": "duration", "seconds": 9 } } ###### title Segment timestamps ###### request ####### curl curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F "timestamp_granularities[]=segment" \ -F model="whisper-1" \ -F response_format="verbose_json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) transcription = client.audio.transcriptions.create( file=b"raw file contents", model="gpt-4o-transcribe", ) print(transcription) ####### javascript import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const transcription = await openai.audio.transcriptions.create({ file: fs.createReadStream("audio.mp3"), model: "whisper-1", response_format: "verbose_json", timestamp_granularities: ["segment"] }); console.log(transcription.text); } 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}"); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const transcription = await client.audio.transcriptions.create({ file: fs.createReadStream('speech.mp3'), model: 'gpt-4o-transcribe', }); console.log(transcription); ####### go package main import ( "bytes" "context" "fmt" "io" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) transcription, err := client.Audio.Transcriptions.New(context.TODO(), openai.AudioTranscriptionNewParams{ File: io.Reader(bytes.NewBuffer([]byte("some file contents"))), Model: openai.AudioModelWhisper1, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", transcription) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.audio.AudioModel; import com.openai.models.audio.transcriptions.TranscriptionCreateParams; import com.openai.models.audio.transcriptions.TranscriptionCreateResponse; import java.io.ByteArrayInputStream; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); TranscriptionCreateParams params = TranscriptionCreateParams.builder() .file(ByteArrayInputStream("some content".getBytes())) .model(AudioModel.WHISPER_1) .build(); TranscriptionCreateResponse transcription = client.audio().transcriptions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") transcription = openai.audio.transcriptions.create(file: Pathname(__FILE__), model: :"whisper-1") puts(transcription) ###### response { "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 }, ... ], "usage": { "type": "duration", "seconds": 9 } } #### description Transcribes audio into the input language. ## /audio/translations ### post #### operationId createTranslation #### tags - Audio #### summary Create translation #### requestBody ##### required true ##### content ###### multipart/form-data ####### schema ######## $ref #/components/schemas/CreateTranslationRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### anyOf ########## $ref #/components/schemas/CreateTranslationResponseJson ########## $ref #/components/schemas/CreateTranslationResponseVerboseJson ########## x-stainless-skip - go #### x-oaiMeta ##### name Create translation ##### group audio ##### returns The translated text. ##### examples ###### response { "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?" } ###### request ####### curl curl https://api.openai.com/v1/audio/translations \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/german.m4a" \ -F model="whisper-1" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) translation = client.audio.translations.create( file=b"raw file contents", model="whisper-1", ) print(translation) ####### javascript import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const translation = await openai.audio.translations.create({ file: fs.createReadStream("speech.mp3"), model: "whisper-1", }); 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}"); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const translation = await client.audio.translations.create({ file: fs.createReadStream('speech.mp3'), model: 'whisper-1', }); console.log(translation); ####### go package main import ( "bytes" "context" "fmt" "io" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) translation, err := client.Audio.Translations.New(context.TODO(), openai.AudioTranslationNewParams{ File: io.Reader(bytes.NewBuffer([]byte("some file contents"))), Model: openai.AudioModelWhisper1, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", translation) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.audio.AudioModel; import com.openai.models.audio.translations.TranslationCreateParams; import com.openai.models.audio.translations.TranslationCreateResponse; import java.io.ByteArrayInputStream; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); TranslationCreateParams params = TranslationCreateParams.builder() .file(ByteArrayInputStream("some content".getBytes())) .model(AudioModel.WHISPER_1) .build(); TranslationCreateResponse translation = client.audio().translations().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") translation = openai.audio.translations.create(file: Pathname(__FILE__), model: :"whisper-1") puts(translation) #### description Translates audio into English. ## /batches ### post #### summary Create batch #### operationId createBatch #### tags - Batch #### requestBody ##### required true ##### content ###### application/json ####### schema ######## type object ######## required - input_file_id - endpoint - completion_window ######## properties ######### input_file_id ########## type string ########## description The ID of an uploaded file that contains requests for the new batch. See [upload file](https://platform.openai.com/docs/api-reference/files/create) for how to upload a file. Your input file must be formatted as a [JSONL file](https://platform.openai.com/docs/api-reference/batch/request-input), and must be uploaded with the purpose `batch`. The file can contain up to 50,000 requests, and can be up to 200 MB in size. ######### endpoint ########## type string ########## enum - /v1/responses - /v1/chat/completions - /v1/embeddings - /v1/completions ########## description The endpoint to be used for all requests in the batch. Currently `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are supported. Note that `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch. ######### completion_window ########## type string ########## enum - 24h ########## description The time frame within which the batch should be processed. Currently only `24h` is supported. ######### metadata ########## $ref #/components/schemas/Metadata ######### output_expires_after ########## $ref #/components/schemas/BatchFileExpirationAfter #### responses ##### 200 ###### description Batch created successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Batch #### x-oaiMeta ##### name Create batch ##### group batch ##### returns The created [Batch](https://platform.openai.com/docs/api-reference/batch/object) object. ##### examples ###### response { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/chat/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "validating", "output_file_id": null, "error_file_id": null, "created_at": 1711471533, "in_progress_at": null, "expires_at": null, "finalizing_at": null, "completed_at": null, "failed_at": null, "expired_at": null, "cancelling_at": null, "cancelled_at": null, "request_counts": { "total": 0, "completed": 0, "failed": 0 }, "metadata": { "customer_id": "user_123456789", "batch_description": "Nightly eval job", } } ###### request ####### curl curl https://api.openai.com/v1/batches \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input_file_id": "file-abc123", "endpoint": "/v1/chat/completions", "completion_window": "24h" }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) batch = client.batches.create( completion_window="24h", endpoint="/v1/responses", input_file_id="input_file_id", ) print(batch.id) ####### node import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const batch = await openai.batches.create({ input_file_id: "file-abc123", endpoint: "/v1/chat/completions", completion_window: "24h" }); console.log(batch); } main(); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const batch = await client.batches.create({ completion_window: '24h', endpoint: '/v1/responses', input_file_id: 'input_file_id', }); console.log(batch.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) batch, err := client.Batches.New(context.TODO(), openai.BatchNewParams{ CompletionWindow: openai.BatchNewParamsCompletionWindow24h, Endpoint: openai.BatchNewParamsEndpointV1Responses, InputFileID: "input_file_id", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", batch.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.batches.Batch; import com.openai.models.batches.BatchCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); BatchCreateParams params = BatchCreateParams.builder() .completionWindow(BatchCreateParams.CompletionWindow._24H) .endpoint(BatchCreateParams.Endpoint.V1_RESPONSES) .inputFileId("input_file_id") .build(); Batch batch = client.batches().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") batch = openai.batches.create( completion_window: :"24h", endpoint: :"/v1/responses", input_file_id: "input_file_id" ) puts(batch) #### description Creates and executes a batch from an uploaded file of requests ### get #### operationId listBatches #### tags - Batch #### summary List batch #### parameters ##### in query ##### name after ##### required false ##### schema ###### type string ##### 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. ##### 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 #### responses ##### 200 ###### description Batch listed successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListBatchesResponse #### x-oaiMeta ##### name List batch ##### group batch ##### returns A list of paginated [Batch](https://platform.openai.com/docs/api-reference/batch/object) objects. ##### examples ###### response { "object": "list", "data": [ { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/chat/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 job", } }, { ... }, ], "first_id": "batch_abc123", "last_id": "batch_abc456", "has_more": true } ###### request ####### curl curl https://api.openai.com/v1/batches?limit=2 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.batches.list() page = page.data[0] print(page.id) ####### node import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const list = await openai.batches.list(); for await (const batch of list) { console.log(batch); } } main(); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const batch of client.batches.list()) { console.log(batch.id); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Batches.List(context.TODO(), openai.BatchListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.batches.BatchListPage; import com.openai.models.batches.BatchListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); BatchListPage page = client.batches().list(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.batches.list puts(page) #### description List your organization's batches. ## /batches/{batch_id} ### get #### operationId retrieveBatch #### tags - Batch #### summary Retrieve batch #### parameters ##### in path ##### name batch_id ##### required true ##### schema ###### type string ##### description The ID of the batch to retrieve. #### responses ##### 200 ###### description Batch retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Batch #### x-oaiMeta ##### name Retrieve batch ##### group batch ##### returns The [Batch](https://platform.openai.com/docs/api-reference/batch/object) object matching the specified ID. ##### examples ###### response { "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", } } ###### request ####### curl curl https://api.openai.com/v1/batches/batch_abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) batch = client.batches.retrieve( "batch_id", ) print(batch.id) ####### node import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const batch = await openai.batches.retrieve("batch_abc123"); console.log(batch); } main(); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const batch = await client.batches.retrieve('batch_id'); console.log(batch.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) batch, err := client.Batches.Get(context.TODO(), "batch_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", batch.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.batches.Batch; import com.openai.models.batches.BatchRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Batch batch = client.batches().retrieve("batch_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") batch = openai.batches.retrieve("batch_id") puts(batch) #### description Retrieves a batch. ## /batches/{batch_id}/cancel ### post #### operationId cancelBatch #### tags - Batch #### summary Cancel batch #### parameters ##### in path ##### name batch_id ##### required true ##### schema ###### type string ##### description The ID of the batch to cancel. #### responses ##### 200 ###### description Batch is cancelling. Returns the cancelling batch's details. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Batch #### x-oaiMeta ##### name Cancel batch ##### group batch ##### returns The [Batch](https://platform.openai.com/docs/api-reference/batch/object) object matching the specified ID. ##### examples ###### response { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/chat/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "cancelling", "output_file_id": null, "error_file_id": null, "created_at": 1711471533, "in_progress_at": 1711471538, "expires_at": 1711557933, "finalizing_at": null, "completed_at": null, "failed_at": null, "expired_at": null, "cancelling_at": 1711475133, "cancelled_at": null, "request_counts": { "total": 100, "completed": 23, "failed": 1 }, "metadata": { "customer_id": "user_123456789", "batch_description": "Nightly eval job", } } ###### request ####### curl curl https://api.openai.com/v1/batches/batch_abc123/cancel \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -X POST ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) batch = client.batches.cancel( "batch_id", ) print(batch.id) ####### node import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const batch = await openai.batches.cancel("batch_abc123"); console.log(batch); } main(); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const batch = await client.batches.cancel('batch_id'); console.log(batch.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) batch, err := client.Batches.Cancel(context.TODO(), "batch_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", batch.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.batches.Batch; import com.openai.models.batches.BatchCancelParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Batch batch = client.batches().cancel("batch_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") batch = openai.batches.cancel("batch_id") puts(batch) #### description Cancels an in-progress batch. The batch will be in status `cancelling` for up to 10 minutes, before changing to `cancelled`, where it will have partial results (if any) available in the output file. ## /chat/completions ### get #### operationId listChatCompletions #### tags - Chat #### summary List Chat Completions #### 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](https://platform.openai.com/docs/api-reference/chat/list-object) matching the specified filters. ##### path list ##### examples ###### response { "object": "list", "data": [ { "object": "chat.completion", "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", "model": "gpt-4.1-2025-04-14", "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 } ###### 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( api_key="My API Key", ) page = client.chat.completions.list() page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const chatCompletion of client.chat.completions.list()) { console.log(chatCompletion.id); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Chat.Completions.List(context.TODO(), openai.ChatCompletionListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.chat.completions.ChatCompletionListPage; import com.openai.models.chat.completions.ChatCompletionListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ChatCompletionListPage page = client.chat().completions().list(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.chat.completions.list puts(page) #### description List stored Chat Completions. Only Chat Completions that have been stored with the `store` parameter set to `true` will be returned. ### post #### operationId createChatCompletion #### tags - Chat #### summary Create chat completion #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateChatCompletionRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/CreateChatCompletionResponse ####### text/event-stream ######## schema ######### $ref #/components/schemas/CreateChatCompletionStreamResponse #### x-oaiMeta ##### name Create chat completion ##### group chat ##### returns Returns a [chat completion](https://platform.openai.com/docs/api-reference/chat/object) object, or a streamed sequence of [chat completion chunk](https://platform.openai.com/docs/api-reference/chat/streaming) objects if the request is streamed. ##### path create ##### examples ###### title Default ###### request ####### curl curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "VAR_chat_model_id", "messages": [ { "role": "developer", "content": "You are a helpful assistant." }, { "role": "user", "content": "Hello!" } ] }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) chat_completion = client.chat.completions.create( messages=[{ "content": "string", "role": "developer", }], model="gpt-4o", ) print(chat_completion) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const chatCompletion = await client.chat.completions.create({ messages: [{ content: 'string', role: 'developer' }], model: 'gpt-4o', }); console.log(chatCompletion); ####### csharp using System; using System.Collections.Generic; using OpenAI.Chat; ChatClient client = new( model: "gpt-4.1", 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); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/shared" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{openai.ChatCompletionMessageParamUnion{ OfDeveloper: &openai.ChatCompletionDeveloperMessageParam{ Content: openai.ChatCompletionDeveloperMessageParamContentUnion{ OfString: openai.String("string"), }, }, }}, Model: shared.ChatModelGPT5, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", chatCompletion) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.ChatModel; import com.openai.models.chat.completions.ChatCompletion; import com.openai.models.chat.completions.ChatCompletionCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ChatCompletionCreateParams params = ChatCompletionCreateParams.builder() .addDeveloperMessage("string") .model(ChatModel.GPT_5) .build(); ChatCompletion chatCompletion = client.chat().completions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") chat_completion = openai.chat.completions.create(messages: [{content: "string", role: :developer}], model: :"gpt-5") puts(chat_completion) ###### response { "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT", "object": "chat.completion", "created": 1741569952, "model": "gpt-4.1-2025-04-14", "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": 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 ####### curl curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-4.1", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is in this image?" }, { "type": "image_url", "image_url": { "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" } } ] } ], "max_tokens": 300 }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) chat_completion = client.chat.completions.create( messages=[{ "content": "string", "role": "developer", }], model="gpt-4o", ) print(chat_completion) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const chatCompletion = await client.chat.completions.create({ messages: [{ content: 'string', role: 'developer' }], model: 'gpt-4o', }); console.log(chatCompletion); ####### csharp using System; using System.Collections.Generic; using OpenAI.Chat; ChatClient client = new( model: "gpt-4.1", 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); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/shared" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{openai.ChatCompletionMessageParamUnion{ OfDeveloper: &openai.ChatCompletionDeveloperMessageParam{ Content: openai.ChatCompletionDeveloperMessageParamContentUnion{ OfString: openai.String("string"), }, }, }}, Model: shared.ChatModelGPT5, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", chatCompletion) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.ChatModel; import com.openai.models.chat.completions.ChatCompletion; import com.openai.models.chat.completions.ChatCompletionCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ChatCompletionCreateParams params = ChatCompletionCreateParams.builder() .addDeveloperMessage("string") .model(ChatModel.GPT_5) .build(); ChatCompletion chatCompletion = client.chat().completions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") chat_completion = openai.chat.completions.create(messages: [{content: "string", role: :developer}], model: :"gpt-5") puts(chat_completion) ###### response { "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG", "object": "chat.completion", "created": 1741570283, "model": "gpt-4.1-2025-04-14", "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": 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 ####### curl curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "VAR_chat_model_id", "messages": [ { "role": "developer", "content": "You are a helpful assistant." }, { "role": "user", "content": "Hello!" } ], "stream": true }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) chat_completion = client.chat.completions.create( messages=[{ "content": "string", "role": "developer", }], model="gpt-4o", ) print(chat_completion) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const chatCompletion = await client.chat.completions.create({ messages: [{ content: 'string', role: 'developer' }], model: 'gpt-4o', }); console.log(chatCompletion); ####### csharp using System; using System.ClientModel; using System.Collections.Generic; using System.Threading.Tasks; using OpenAI.Chat; ChatClient client = new( model: "gpt-4.1", 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); } } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/shared" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{openai.ChatCompletionMessageParamUnion{ OfDeveloper: &openai.ChatCompletionDeveloperMessageParam{ Content: openai.ChatCompletionDeveloperMessageParamContentUnion{ OfString: openai.String("string"), }, }, }}, Model: shared.ChatModelGPT5, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", chatCompletion) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.ChatModel; import com.openai.models.chat.completions.ChatCompletion; import com.openai.models.chat.completions.ChatCompletionCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ChatCompletionCreateParams params = ChatCompletionCreateParams.builder() .addDeveloperMessage("string") .model(ChatModel.GPT_5) .build(); ChatCompletion chatCompletion = client.chat().completions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") chat_completion = openai.chat.completions.create(messages: [{content: "string", role: :developer}], model: :"gpt-5") puts(chat_completion) ###### response {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}]} .... {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]} ###### title Functions ###### request ####### curl curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-4.1", "messages": [ { "role": "user", "content": "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"] } }, "required": ["location"] } } } ], "tool_choice": "auto" }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) chat_completion = client.chat.completions.create( messages=[{ "content": "string", "role": "developer", }], model="gpt-4o", ) print(chat_completion) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const chatCompletion = await client.chat.completions.create({ messages: [{ content: 'string', role: 'developer' }], model: 'gpt-4o', }); console.log(chatCompletion); ####### csharp using System; using System.Collections.Generic; using OpenAI.Chat; ChatClient client = new( model: "gpt-4.1", 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(""" { "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); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/shared" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{openai.ChatCompletionMessageParamUnion{ OfDeveloper: &openai.ChatCompletionDeveloperMessageParam{ Content: openai.ChatCompletionDeveloperMessageParamContentUnion{ OfString: openai.String("string"), }, }, }}, Model: shared.ChatModelGPT5, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", chatCompletion) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.ChatModel; import com.openai.models.chat.completions.ChatCompletion; import com.openai.models.chat.completions.ChatCompletionCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ChatCompletionCreateParams params = ChatCompletionCreateParams.builder() .addDeveloperMessage("string") .model(ChatModel.GPT_5) .build(); ChatCompletion chatCompletion = client.chat().completions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") chat_completion = openai.chat.completions.create(messages: [{content: "string", role: :developer}], model: :"gpt-5") puts(chat_completion) ###### 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}" } } ] }, "logprobs": null, "finish_reason": "tool_calls" } ], "usage": { "prompt_tokens": 82, "completion_tokens": 17, "total_tokens": 99, "completion_tokens_details": { "reasoning_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } } } ###### title Logprobs ###### request ####### curl curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "VAR_chat_model_id", "messages": [ { "role": "user", "content": "Hello!" } ], "logprobs": true, "top_logprobs": 2 }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) chat_completion = client.chat.completions.create( messages=[{ "content": "string", "role": "developer", }], model="gpt-4o", ) print(chat_completion) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const chatCompletion = await client.chat.completions.create({ messages: [{ content: 'string', role: 'developer' }], model: 'gpt-4o', }); console.log(chatCompletion); ####### csharp using System; using System.Collections.Generic; using OpenAI.Chat; ChatClient client = new( model: "gpt-4.1", 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); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/shared" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{ Messages: []openai.ChatCompletionMessageParamUnion{openai.ChatCompletionMessageParamUnion{ OfDeveloper: &openai.ChatCompletionDeveloperMessageParam{ Content: openai.ChatCompletionDeveloperMessageParamContentUnion{ OfString: openai.String("string"), }, }, }}, Model: shared.ChatModelGPT5, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", chatCompletion) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.ChatModel; import com.openai.models.chat.completions.ChatCompletion; import com.openai.models.chat.completions.ChatCompletionCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ChatCompletionCreateParams params = ChatCompletionCreateParams.builder() .addDeveloperMessage("string") .model(ChatModel.GPT_5) .build(); ChatCompletion chatCompletion = client.chat().completions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") chat_completion = openai.chat.completions.create(messages: [{content: "string", role: :developer}], model: :"gpt-5") puts(chat_completion) ###### response { "id": "chatcmpl-123", "object": "chat.completion", "created": 1702685778, "model": "gpt-4o-mini", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I assist you today?" }, "logprobs": { "content": [ { "token": "Hello", "logprob": -0.31725305, "bytes": [72, 101, 108, 108, 111], "top_logprobs": [ { "token": "Hello", "logprob": -0.31725305, "bytes": [72, 101, 108, 108, 111] }, { "token": "Hi", "logprob": -1.3190403, "bytes": [72, 105] } ] }, { "token": "!", "logprob": -0.02380986, "bytes": [ 33 ], "top_logprobs": [ { "token": "!", "logprob": -0.02380986, "bytes": [33] }, { "token": " there", "logprob": -3.787621, "bytes": [32, 116, 104, 101, 114, 101] } ] }, { "token": " How", "logprob": -0.000054669687, "bytes": [32, 72, 111, 119], "top_logprobs": [ { "token": " How", "logprob": -0.000054669687, "bytes": [32, 72, 111, 119] }, { "token": "<|end|>", "logprob": -10.953937, "bytes": null } ] }, { "token": " can", "logprob": -0.015801601, "bytes": [32, 99, 97, 110], "top_logprobs": [ { "token": " can", "logprob": -0.015801601, "bytes": [32, 99, 97, 110] }, { "token": " may", "logprob": -4.161023, "bytes": [32, 109, 97, 121] } ] }, { "token": " I", "logprob": -3.7697225e-6, "bytes": [ 32, 73 ], "top_logprobs": [ { "token": " I", "logprob": -3.7697225e-6, "bytes": [32, 73] }, { "token": " assist", "logprob": -13.596657, "bytes": [32, 97, 115, 115, 105, 115, 116] } ] }, { "token": " assist", "logprob": -0.04571125, "bytes": [32, 97, 115, 115, 105, 115, 116], "top_logprobs": [ { "token": " assist", "logprob": -0.04571125, "bytes": [32, 97, 115, 115, 105, 115, 116] }, { "token": " help", "logprob": -3.1089056, "bytes": [32, 104, 101, 108, 112] } ] }, { "token": " you", "logprob": -5.4385737e-6, "bytes": [32, 121, 111, 117], "top_logprobs": [ { "token": " you", "logprob": -5.4385737e-6, "bytes": [32, 121, 111, 117] }, { "token": " today", "logprob": -12.807695, "bytes": [32, 116, 111, 100, 97, 121] } ] }, { "token": " today", "logprob": -0.0040071653, "bytes": [32, 116, 111, 100, 97, 121], "top_logprobs": [ { "token": " today", "logprob": -0.0040071653, "bytes": [32, 116, 111, 100, 97, 121] }, { "token": "?", "logprob": -5.5247097, "bytes": [63] } ] }, { "token": "?", "logprob": -0.0008108172, "bytes": [63], "top_logprobs": [ { "token": "?", "logprob": -0.0008108172, "bytes": [63] }, { "token": "?\n", "logprob": -7.184561, "bytes": [63, 10] } ] } ] }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 9, "completion_tokens": 9, "total_tokens": 18, "completion_tokens_details": { "reasoning_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } }, "system_fingerprint": null } #### description **Starting a new project?** We recommend trying [Responses](https://platform.openai.com/docs/api-reference/responses) to take advantage of the latest OpenAI platform features. Compare [Chat Completions with Responses](https://platform.openai.com/docs/guides/responses-vs-chat-completions?api-mode=responses). --- Creates a model response for the given chat conversation. Learn more in the [text generation](https://platform.openai.com/docs/guides/text-generation), [vision](https://platform.openai.com/docs/guides/vision), and [audio](https://platform.openai.com/docs/guides/audio) guides. Parameter support can differ depending on the model used to generate the response, particularly for newer reasoning models. Parameters that are only supported for reasoning models are noted below. For the current state of unsupported parameters in reasoning models, [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning). ## /chat/completions/{completion_id} ### get #### operationId getChatCompletion #### tags - Chat #### summary Get chat completion #### parameters ##### in path ##### name completion_id ##### required true ##### schema ###### type string ##### description The ID of the chat completion to retrieve. #### responses ##### 200 ###### description A chat completion ###### content ####### application/json ######## schema ######### $ref #/components/schemas/CreateChatCompletionResponse #### x-oaiMeta ##### name Get chat completion ##### group chat ##### returns The [ChatCompletion](https://platform.openai.com/docs/api-reference/chat/object) object matching the specified ID. ##### examples ###### 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 } ], "response_format": null } ###### 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 client = OpenAI( api_key="My API Key", ) chat_completion = client.chat.completions.retrieve( "completion_id", ) print(chat_completion.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const chatCompletion = await client.chat.completions.retrieve('completion_id'); console.log(chatCompletion.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) chatCompletion, err := client.Chat.Completions.Get(context.TODO(), "completion_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", chatCompletion.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.chat.completions.ChatCompletion; import com.openai.models.chat.completions.ChatCompletionRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ChatCompletion chatCompletion = client.chat().completions().retrieve("completion_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") chat_completion = openai.chat.completions.retrieve("completion_id") puts(chat_completion) #### description Get a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` will be returned. ### post #### operationId updateChatCompletion #### tags - Chat #### summary Update chat completion #### 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 ######## type object ######## required - metadata ######## properties ######### metadata ########## $ref #/components/schemas/Metadata #### responses ##### 200 ###### description A chat completion ###### content ####### application/json ######## schema ######### $ref #/components/schemas/CreateChatCompletionResponse #### x-oaiMeta ##### name Update chat completion ##### group chat ##### returns The [ChatCompletion](https://platform.openai.com/docs/api-reference/chat/object) object matching the specified ID. ##### examples ###### response { "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": [ { "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 } ###### request ####### 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 '{"metadata": {"foo": "bar"}}' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) chat_completion = client.chat.completions.update( completion_id="completion_id", metadata={ "foo": "string" }, ) print(chat_completion.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const chatCompletion = await client.chat.completions.update('completion_id', { metadata: { foo: 'string' } }); console.log(chatCompletion.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/shared" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) chatCompletion, err := client.Chat.Completions.Update( context.TODO(), "completion_id", openai.ChatCompletionUpdateParams{ Metadata: shared.Metadata{ "foo": "string", }, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", chatCompletion.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.core.JsonValue; import com.openai.models.chat.completions.ChatCompletion; import com.openai.models.chat.completions.ChatCompletionUpdateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ChatCompletionUpdateParams params = ChatCompletionUpdateParams.builder() .completionId("completion_id") .metadata(ChatCompletionUpdateParams.Metadata.builder() .putAdditionalProperty("foo", JsonValue.from("string")) .build()) .build(); ChatCompletion chatCompletion = client.chat().completions().update(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") chat_completion = openai.chat.completions.update("completion_id", metadata: {foo: "string"}) puts(chat_completion) #### description 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. ### delete #### operationId deleteChatCompletion #### tags - Chat #### summary Delete chat completion #### 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 ###### response { "object": "chat.completion.deleted", "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", "deleted": true } ###### 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( api_key="My API Key", ) chat_completion_deleted = client.chat.completions.delete( "completion_id", ) print(chat_completion_deleted.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const chatCompletionDeleted = await client.chat.completions.delete('completion_id'); console.log(chatCompletionDeleted.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) chatCompletionDeleted, err := client.Chat.Completions.Delete(context.TODO(), "completion_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", chatCompletionDeleted.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.chat.completions.ChatCompletionDeleteParams; import com.openai.models.chat.completions.ChatCompletionDeleted; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ChatCompletionDeleted chatCompletionDeleted = client.chat().completions().delete("completion_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") chat_completion_deleted = openai.chat.completions.delete("completion_id") puts(chat_completion_deleted) #### description Delete a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` can be deleted. ## /chat/completions/{completion_id}/messages ### get #### operationId getChatCompletionMessages #### tags - Chat #### summary Get chat messages #### parameters ##### 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 ##### name limit ##### in query ##### description Number of messages to retrieve. ##### required false ##### schema ###### type integer ###### default 20 ##### name order ##### in query ##### 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 ###### enum - asc - desc ###### default asc #### responses ##### 200 ###### description A list of messages ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ChatCompletionMessageList #### x-oaiMeta ##### name Get chat messages ##### group chat ##### returns A list of [messages](https://platform.openai.com/docs/api-reference/chat/message-list) for the specified chat completion. ##### examples ###### response { "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 } ###### request ####### 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( api_key="My API Key", ) page = client.chat.completions.messages.list( completion_id="completion_id", ) page = page.data[0] print(page) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const chatCompletionStoreMessage of client.chat.completions.messages.list('completion_id')) { console.log(chatCompletionStoreMessage); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Chat.Completions.Messages.List( context.TODO(), "completion_id", openai.ChatCompletionMessageListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.chat.completions.messages.MessageListPage; import com.openai.models.chat.completions.messages.MessageListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); MessageListPage page = client.chat().completions().messages().list("completion_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.chat.completions.messages.list("completion_id") puts(page) #### description 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. ## /completions ### post #### operationId createCompletion #### tags - Completions #### summary Create completion #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateCompletionRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/CreateCompletionResponse #### x-oaiMeta ##### name Create completion ##### group completions ##### returns Returns a [completion](https://platform.openai.com/docs/api-reference/completions/object) object, or a sequence of completion objects if the request is streamed. ##### legacy true ##### 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( api_key="My API Key", ) completion = client.completions.create( model="string", prompt="This is a test.", ) print(completion) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const completion = await client.completions.create({ model: 'string', prompt: 'This is a test.' }); console.log(completion); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) completion, err := client.Completions.New(context.TODO(), openai.CompletionNewParams{ Model: openai.CompletionNewParamsModelGPT3_5TurboInstruct, Prompt: openai.CompletionNewParamsPromptUnion{ OfString: openai.String("This is a test."), }, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", completion) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.completions.Completion; import com.openai.models.completions.CompletionCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); CompletionCreateParams params = CompletionCreateParams.builder() .model(CompletionCreateParams.Model.GPT_3_5_TURBO_INSTRUCT) .prompt("This is a test.") .build(); Completion completion = client.completions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") completion = openai.completions.create(model: :"gpt-3.5-turbo-instruct", prompt: "This is a test.") puts(completion) ###### 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( api_key="My API Key", ) completion = client.completions.create( model="string", prompt="This is a test.", ) print(completion) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const completion = await client.completions.create({ model: 'string', prompt: 'This is a test.' }); console.log(completion); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) completion, err := client.Completions.New(context.TODO(), openai.CompletionNewParams{ Model: openai.CompletionNewParamsModelGPT3_5TurboInstruct, Prompt: openai.CompletionNewParamsPromptUnion{ OfString: openai.String("This is a test."), }, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", completion) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.completions.Completion; import com.openai.models.completions.CompletionCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); CompletionCreateParams params = CompletionCreateParams.builder() .model(CompletionCreateParams.Model.GPT_3_5_TURBO_INSTRUCT) .prompt("This is a test.") .build(); Completion completion = client.completions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") completion = openai.completions.create(model: :"gpt-3.5-turbo-instruct", prompt: "This is a test.") puts(completion) ###### 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", } #### description Creates a completion for the provided prompt and parameters. ## /containers ### get #### summary List containers #### description List Containers #### operationId ListContainers #### 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 #### responses ##### 200 ###### description Success ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ContainerListResource #### x-oaiMeta ##### name List containers ##### group containers ##### returns a list of [container](https://platform.openai.com/docs/api-reference/containers/object) objects. ##### path get ##### examples ###### response { "object": "list", "data": [ { "id": "cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863", "object": "container", "created_at": 1747844794, "status": "running", "expires_after": { "anchor": "last_active_at", "minutes": 20 }, "last_active_at": 1747844794, "name": "My Container" } ], "first_id": "container_123", "last_id": "container_123", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/containers \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const containerListResponse of client.containers.list()) { console.log(containerListResponse.id); } ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.containers.list() page = page.data[0] print(page.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Containers.List(context.TODO(), openai.ContainerListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.containers.ContainerListPage; import com.openai.models.containers.ContainerListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ContainerListPage page = client.containers().list(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.containers.list puts(page) ### post #### summary Create container #### description Create Container #### operationId CreateContainer #### parameters #### requestBody ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateContainerBody #### responses ##### 200 ###### description Success ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ContainerResource #### x-oaiMeta ##### name Create container ##### group containers ##### returns The created [container](https://platform.openai.com/docs/api-reference/containers/object) object. ##### path post ##### examples ###### response { "id": "cntr_682e30645a488191b6363a0cbefc0f0a025ec61b66250591", "object": "container", "created_at": 1747857508, "status": "running", "expires_after": { "anchor": "last_active_at", "minutes": 20 }, "last_active_at": 1747857508, "name": "My Container" } ###### request ####### curl curl https://api.openai.com/v1/containers \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "My Container" }' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const container = await client.containers.create({ name: 'name' }); console.log(container.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) container = client.containers.create( name="name", ) print(container.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) container, err := client.Containers.New(context.TODO(), openai.ContainerNewParams{ Name: "name", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", container.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.containers.ContainerCreateParams; import com.openai.models.containers.ContainerCreateResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ContainerCreateParams params = ContainerCreateParams.builder() .name("name") .build(); ContainerCreateResponse container = client.containers().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") container = openai.containers.create(name: "name") puts(container) ## /containers/{container_id} ### get #### summary Retrieve container #### description Retrieve Container #### operationId RetrieveContainer #### parameters ##### name container_id ##### in path ##### required true ##### schema ###### type string #### responses ##### 200 ###### description Success ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ContainerResource #### x-oaiMeta ##### name Retrieve container ##### group containers ##### returns The [container](https://platform.openai.com/docs/api-reference/containers/object) object. ##### path get ##### examples ###### response { "id": "cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863", "object": "container", "created_at": 1747844794, "status": "running", "expires_after": { "anchor": "last_active_at", "minutes": 20 }, "last_active_at": 1747844794, "name": "My Container" } ###### request ####### curl curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863 \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const container = await client.containers.retrieve('container_id'); console.log(container.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) container = client.containers.retrieve( "container_id", ) print(container.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) container, err := client.Containers.Get(context.TODO(), "container_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", container.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.containers.ContainerRetrieveParams; import com.openai.models.containers.ContainerRetrieveResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ContainerRetrieveResponse container = client.containers().retrieve("container_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") container = openai.containers.retrieve("container_id") puts(container) ### delete #### operationId DeleteContainer #### summary Delete a container #### description Delete Container #### parameters ##### name container_id ##### in path ##### description The ID of the container to delete. ##### required true ##### schema ###### type string #### responses ##### 200 ###### description OK #### x-oaiMeta ##### name Delete a container ##### group containers ##### returns Deletion Status ##### path delete ##### examples ###### response { "id": "cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863", "object": "container.deleted", "deleted": true } ###### request ####### curl curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863 \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); await client.containers.delete('container_id'); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) client.containers.delete( "container_id", ) ####### go package main import ( "context" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) err := client.Containers.Delete(context.TODO(), "container_id") if err != nil { panic(err.Error()) } } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.containers.ContainerDeleteParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); client.containers().delete("container_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") result = openai.containers.delete("container_id") puts(result) ## /containers/{container_id}/files ### post #### summary Create container file #### description Create a Container File You can send either a multipart/form-data request with the raw file content, or a JSON request with a file ID. #### operationId CreateContainerFile #### parameters ##### name container_id ##### in path ##### required true ##### schema ###### type string #### requestBody ##### required true ##### content ###### multipart/form-data ####### schema ######## $ref #/components/schemas/CreateContainerFileBody #### responses ##### 200 ###### description Success ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ContainerFileResource #### x-oaiMeta ##### name Create container file ##### group containers ##### returns The created [container file](https://platform.openai.com/docs/api-reference/container-files/object) object. ##### path post ##### examples ###### response { "id": "cfile_682e0e8a43c88191a7978f477a09bdf5", "object": "container.file", "created_at": 1747848842, "bytes": 880, "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04", "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json", "source": "user" } ###### request ####### curl curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F file="@example.txt" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const file = await client.containers.files.create('container_id'); console.log(file.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) file = client.containers.files.create( container_id="container_id", ) print(file.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) file, err := client.Containers.Files.New( context.TODO(), "container_id", openai.ContainerFileNewParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", file.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.containers.files.FileCreateParams; import com.openai.models.containers.files.FileCreateResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileCreateResponse file = client.containers().files().create("container_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") file = openai.containers.files.create("container_id") puts(file) ### get #### summary List container files #### description List Container files #### operationId ListContainerFiles #### parameters ##### name container_id ##### in path ##### 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 #### responses ##### 200 ###### description Success ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ContainerFileListResource #### x-oaiMeta ##### name List container files ##### group containers ##### returns a list of [container file](https://platform.openai.com/docs/api-reference/container-files/object) objects. ##### path get ##### examples ###### response { "object": "list", "data": [ { "id": "cfile_682e0e8a43c88191a7978f477a09bdf5", "object": "container.file", "created_at": 1747848842, "bytes": 880, "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04", "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json", "source": "user" } ], "first_id": "cfile_682e0e8a43c88191a7978f477a09bdf5", "has_more": false, "last_id": "cfile_682e0e8a43c88191a7978f477a09bdf5" } ###### request ####### curl curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const fileListResponse of client.containers.files.list('container_id')) { console.log(fileListResponse.id); } ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.containers.files.list( container_id="container_id", ) page = page.data[0] print(page.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Containers.Files.List( context.TODO(), "container_id", openai.ContainerFileListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.containers.files.FileListPage; import com.openai.models.containers.files.FileListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileListPage page = client.containers().files().list("container_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.containers.files.list("container_id") puts(page) ## /containers/{container_id}/files/{file_id} ### get #### summary Retrieve container file #### description Retrieve Container File #### operationId RetrieveContainerFile #### parameters ##### name container_id ##### in path ##### required true ##### schema ###### type string ##### name file_id ##### in path ##### required true ##### schema ###### type string #### responses ##### 200 ###### description Success ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ContainerFileResource #### x-oaiMeta ##### name Retrieve container file ##### group containers ##### returns The [container file](https://platform.openai.com/docs/api-reference/container-files/object) object. ##### path get ##### examples ###### response { "id": "cfile_682e0e8a43c88191a7978f477a09bdf5", "object": "container.file", "created_at": 1747848842, "bytes": 880, "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04", "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json", "source": "user" } ###### request ####### curl curl https://api.openai.com/v1/containers/container_123/files/file_456 \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const file = await client.containers.files.retrieve('file_id', { container_id: 'container_id' }); console.log(file.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) file = client.containers.files.retrieve( file_id="file_id", container_id="container_id", ) print(file.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) file, err := client.Containers.Files.Get( context.TODO(), "container_id", "file_id", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", file.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.containers.files.FileRetrieveParams; import com.openai.models.containers.files.FileRetrieveResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileRetrieveParams params = FileRetrieveParams.builder() .containerId("container_id") .fileId("file_id") .build(); FileRetrieveResponse file = client.containers().files().retrieve(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") file = openai.containers.files.retrieve("file_id", container_id: "container_id") puts(file) ### delete #### operationId DeleteContainerFile #### summary Delete a container file #### description Delete Container File #### parameters ##### name container_id ##### in path ##### required true ##### schema ###### type string ##### name file_id ##### in path ##### required true ##### schema ###### type string #### responses ##### 200 ###### description OK #### x-oaiMeta ##### name Delete a container file ##### group containers ##### returns Deletion Status ##### path delete ##### examples ###### response { "id": "cfile_682e0e8a43c88191a7978f477a09bdf5", "object": "container.file.deleted", "deleted": true } ###### request ####### curl curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863/files/cfile_682e0e8a43c88191a7978f477a09bdf5 \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); await client.containers.files.delete('file_id', { container_id: 'container_id' }); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) client.containers.files.delete( file_id="file_id", container_id="container_id", ) ####### go package main import ( "context" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) err := client.Containers.Files.Delete( context.TODO(), "container_id", "file_id", ) if err != nil { panic(err.Error()) } } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.containers.files.FileDeleteParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileDeleteParams params = FileDeleteParams.builder() .containerId("container_id") .fileId("file_id") .build(); client.containers().files().delete(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") result = openai.containers.files.delete("file_id", container_id: "container_id") puts(result) ## /containers/{container_id}/files/{file_id}/content ### get #### summary Retrieve container file content #### description Retrieve Container File Content #### operationId RetrieveContainerFileContent #### parameters ##### name container_id ##### in path ##### required true ##### schema ###### type string ##### name file_id ##### in path ##### required true ##### schema ###### type string #### responses ##### 200 ###### description Success #### x-oaiMeta ##### name Retrieve container file content ##### group containers ##### returns The contents of the container file. ##### path get ##### examples ###### response ###### request ####### curl curl https://api.openai.com/v1/containers/container_123/files/cfile_456/content \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const content = await client.containers.files.content.retrieve('file_id', { container_id: 'container_id' }); console.log(content); const data = await content.blob(); console.log(data); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) content = client.containers.files.content.retrieve( file_id="file_id", container_id="container_id", ) print(content) data = content.read() print(data) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) content, err := client.Containers.Files.Content.Get( context.TODO(), "container_id", "file_id", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", content) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.core.http.HttpResponse; import com.openai.models.containers.files.content.ContentRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ContentRetrieveParams params = ContentRetrieveParams.builder() .containerId("container_id") .fileId("file_id") .build(); HttpResponse content = client.containers().files().content().retrieve(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") content = openai.containers.files.content.retrieve("file_id", container_id: "container_id") puts(content) ## /conversations ### post #### operationId createConversation #### tags - Conversations #### summary Create a conversation #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateConversationRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ConversationResource #### x-oaiMeta ##### name Create a conversation ##### group conversations ##### returns Returns a [Conversation](https://platform.openai.com/docs/api-reference/conversations/object) object. ##### path create ##### examples ###### title Create a conversation. ###### request ####### curl curl https://api.openai.com/v1/conversations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "metadata": {"topic": "demo"}, "items": [ { "type": "message", "role": "user", "content": "Hello!" } ] }' ####### javascript import OpenAI from "openai"; const client = new OpenAI(); const conversation = await client.conversations.create({ metadata: { topic: "demo" }, items: [ { type: "message", role: "user", content: "Hello!" } ], }); console.log(conversation); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) conversation = client.conversations.create() print(conversation.id) ####### csharp using System; using System.Collections.Generic; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); Conversation conversation = client.CreateConversation( new CreateConversationOptions { Metadata = new Dictionary { { "topic", "demo" } }, Items = { new ConversationMessageInput { Role = "user", Content = "Hello!" } } } ); Console.WriteLine(conversation.Id); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const conversation = await client.conversations.create(); console.log(conversation.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/conversations" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) conversation, err := client.Conversations.New(context.TODO(), conversations.ConversationNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", conversation.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.conversations.Conversation; import com.openai.models.conversations.ConversationCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Conversation conversation = client.conversations().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") conversation = openai.conversations.create puts(conversation) ###### response { "id": "conv_123", "object": "conversation", "created_at": 1741900000, "metadata": {"topic": "demo"} } #### description Create a conversation. ## /conversations/{conversation_id} ### get #### operationId getConversation #### tags - Conversations #### summary Retrieve a conversation #### parameters ##### in path ##### name conversation_id ##### required true ##### schema ###### type string ###### example conv_123 ##### description The ID of the conversation to retrieve. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ConversationResource #### x-oaiMeta ##### name Retrieve a conversation ##### group conversations ##### returns Returns a [Conversation](https://platform.openai.com/docs/api-reference/conversations/object) object. ##### path retrieve ##### examples ###### title Retrieve a conversation ###### request ####### curl curl https://api.openai.com/v1/conversations/conv_123 \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### javascript import OpenAI from "openai"; const client = new OpenAI(); const conversation = await client.conversations.retrieve("conv_123"); console.log(conversation); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) conversation = client.conversations.retrieve( "conv_123", ) print(conversation.id) ####### csharp using System; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); Conversation conversation = client.GetConversation("conv_123"); Console.WriteLine(conversation.Id); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const conversation = await client.conversations.retrieve('conv_123'); console.log(conversation.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) conversation, err := client.Conversations.Get(context.TODO(), "conv_123") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", conversation.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.conversations.Conversation; import com.openai.models.conversations.ConversationRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Conversation conversation = client.conversations().retrieve("conv_123"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") conversation = openai.conversations.retrieve("conv_123") puts(conversation) ###### response { "id": "conv_123", "object": "conversation", "created_at": 1741900000, "metadata": {"topic": "demo"} } #### description Get a conversation with the given ID. ### post #### operationId updateConversation #### tags - Conversations #### summary Update a conversation #### parameters ##### in path ##### name conversation_id ##### required true ##### schema ###### type string ###### example conv_123 ##### description The ID of the conversation to update. #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/UpdateConversationBody #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ConversationResource #### x-oaiMeta ##### name Update a conversation ##### group conversations ##### returns Returns the updated [Conversation](https://platform.openai.com/docs/api-reference/conversations/object) object. ##### path update ##### examples ###### title Update conversation metadata ###### request ####### curl curl https://api.openai.com/v1/conversations/conv_123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "metadata": {"topic": "project-x"} }' ####### javascript import OpenAI from "openai"; const client = new OpenAI(); const updated = await client.conversations.update( "conv_123", { metadata: { topic: "project-x" } } ); console.log(updated); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) conversation = client.conversations.update( conversation_id="conv_123", metadata={ "foo": "string" }, ) print(conversation.id) ####### csharp using System; using System.Collections.Generic; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); Conversation updated = client.UpdateConversation( conversationId: "conv_123", new UpdateConversationOptions { Metadata = new Dictionary { { "topic", "project-x" } } } ); Console.WriteLine(updated.Id); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const conversation = await client.conversations.update('conv_123', { metadata: { foo: 'string' } }); console.log(conversation.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/conversations" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) conversation, err := client.Conversations.Update( context.TODO(), "conv_123", conversations.ConversationUpdateParams{ Metadata: map[string]string{ "foo": "string", }, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", conversation.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.core.JsonValue; import com.openai.models.conversations.Conversation; import com.openai.models.conversations.ConversationUpdateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ConversationUpdateParams params = ConversationUpdateParams.builder() .conversationId("conv_123") .metadata(ConversationUpdateParams.Metadata.builder() .putAdditionalProperty("foo", JsonValue.from("string")) .build()) .build(); Conversation conversation = client.conversations().update(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") conversation = openai.conversations.update("conv_123", metadata: {foo: "string"}) puts(conversation) ###### response { "id": "conv_123", "object": "conversation", "created_at": 1741900000, "metadata": {"topic": "project-x"} } #### description Update a conversation's metadata with the given ID. ### delete #### operationId deleteConversation #### tags - Conversations #### summary Delete a conversation #### parameters ##### in path ##### name conversation_id ##### required true ##### schema ###### type string ###### example conv_123 ##### description The ID of the conversation to delete. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/DeletedConversationResource #### x-oaiMeta ##### name Delete a conversation ##### group conversations ##### returns A success message. ##### path delete ##### examples ###### title Delete a conversation ###### request ####### curl curl -X DELETE https://api.openai.com/v1/conversations/conv_123 \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### javascript import OpenAI from "openai"; const client = new OpenAI(); const deleted = await client.conversations.delete("conv_123"); console.log(deleted); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) conversation_deleted_resource = client.conversations.delete( "conv_123", ) print(conversation_deleted_resource.id) ####### csharp using System; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); DeletedConversation deleted = client.DeleteConversation("conv_123"); Console.WriteLine(deleted.Id); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const conversationDeletedResource = await client.conversations.delete('conv_123'); console.log(conversationDeletedResource.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) conversationDeletedResource, err := client.Conversations.Delete(context.TODO(), "conv_123") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", conversationDeletedResource.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.conversations.ConversationDeleteParams; import com.openai.models.conversations.ConversationDeletedResource; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ConversationDeletedResource conversationDeletedResource = client.conversations().delete("conv_123"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") conversation_deleted_resource = openai.conversations.delete("conv_123") puts(conversation_deleted_resource) ###### response { "id": "conv_123", "object": "conversation.deleted", "deleted": true } #### description Delete a conversation with the given ID. ## /conversations/{conversation_id}/items ### post #### operationId createConversationItems #### tags - Conversations #### summary Create items #### parameters ##### in path ##### name conversation_id ##### required true ##### schema ###### type string ###### example conv_123 ##### description The ID of the conversation to add the item to. ##### name include ##### in query ##### required false ##### schema ###### type array ###### items ####### $ref #/components/schemas/Includable ##### description Additional fields to include in the response. See the `include` parameter for [listing Conversation items above](https://platform.openai.com/docs/api-reference/conversations/list-items#conversations_list_items-include) for more information. #### requestBody ##### required true ##### content ###### application/json ####### schema ######## properties ######### items ########## type array ########## description The items to add to the conversation. You may add up to 20 items at a time. ########## items ########### $ref #/components/schemas/InputItem ########## maxItems 20 ######## required - items #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ConversationItemList #### x-oaiMeta ##### name Create items ##### group conversations ##### returns Returns the list of added [items](https://platform.openai.com/docs/api-reference/conversations/list-items-object). ##### path create-item ##### examples ###### title Add a user message to a conversation ###### request ####### curl curl https://api.openai.com/v1/conversations/conv_123/items \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "items": [ { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "Hello!"} ] }, { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "How are you?"} ] } ] }' ####### javascript import OpenAI from "openai"; const client = new OpenAI(); const items = await client.conversations.items.create( "conv_123", { items: [ { type: "message", role: "user", content: [{ type: "input_text", text: "Hello!" }], }, { type: "message", role: "user", content: [{ type: "input_text", text: "How are you?" }], }, ], } ); console.log(items.data); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) conversation_item_list = client.conversations.items.create( conversation_id="conv_123", items=[{ "content": "string", "role": "user", }], ) print(conversation_item_list.first_id) ####### csharp using System; using System.Collections.Generic; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); ConversationItemList created = client.ConversationItems.Create( conversationId: "conv_123", new CreateConversationItemsOptions { Items = new List { new ConversationMessage { Role = "user", Content = { new ConversationInputText { Text = "Hello!" } } }, new ConversationMessage { Role = "user", Content = { new ConversationInputText { Text = "How are you?" } } } } } ); Console.WriteLine(created.Data.Count); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const conversationItemList = await client.conversations.items.create('conv_123', { items: [{ content: 'string', role: 'user' }], }); console.log(conversationItemList.first_id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/conversations" "github.com/openai/openai-go/option" "github.com/openai/openai-go/responses" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) conversationItemList, err := client.Conversations.Items.New( context.TODO(), "conv_123", conversations.ItemNewParams{ Items: []responses.ResponseInputItemUnionParam{responses.ResponseInputItemUnionParam{ OfMessage: &responses.EasyInputMessageParam{ Content: responses.EasyInputMessageContentUnionParam{ OfString: openai.String("string"), }, Role: responses.EasyInputMessageRoleUser, }, }}, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", conversationItemList.FirstID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.conversations.items.ConversationItemList; import com.openai.models.conversations.items.ItemCreateParams; import com.openai.models.responses.EasyInputMessage; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ItemCreateParams params = ItemCreateParams.builder() .conversationId("conv_123") .addItem(EasyInputMessage.builder() .content("string") .role(EasyInputMessage.Role.USER) .build()) .build(); ConversationItemList conversationItemList = client.conversations().items().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") conversation_item_list = openai.conversations.items.create("conv_123", items: [{content: "string", role: :user}]) puts(conversation_item_list) ###### response { "object": "list", "data": [ { "type": "message", "id": "msg_abc", "status": "completed", "role": "user", "content": [ {"type": "input_text", "text": "Hello!"} ] }, { "type": "message", "id": "msg_def", "status": "completed", "role": "user", "content": [ {"type": "input_text", "text": "How are you?"} ] } ], "first_id": "msg_abc", "last_id": "msg_def", "has_more": false } #### description Create items in a conversation with the given ID. ### get #### operationId listConversationItems #### tags - Conversations #### summary List items #### parameters ##### in path ##### name conversation_id ##### required true ##### schema ###### type string ###### example conv_123 ##### description The ID of the conversation to list items for. ##### name limit ##### in query ##### description A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. ##### required false ##### schema ###### type integer ###### default 20 ##### in query ##### name order ##### schema ###### type string ###### enum - asc - desc ##### description The order to return the input items in. Default is `desc`. - `asc`: Return the input items in ascending order. - `desc`: Return the input items in descending order. ##### in query ##### name after ##### schema ###### type string ##### description An item ID to list items after, used in pagination. ##### name include ##### in query ##### required false ##### schema ###### type array ###### items ####### $ref #/components/schemas/Includable ##### description Specify additional output data to include in the model response. Currently supported values are: - `web_search_call.action.sources`: Include the sources of the web search tool call. - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - `computer_call_output.output.image_url`: Include image urls from the computer call output. - `file_search_call.results`: Include the search results of the file search tool call. - `message.input_image.image_url`: Include image urls from the input message. - `message.output_text.logprobs`: Include logprobs with assistant messages. - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ConversationItemList #### x-oaiMeta ##### name List items ##### group conversations ##### returns Returns a [list object](https://platform.openai.com/docs/api-reference/conversations/list-items-object) containing Conversation items. ##### path list-items ##### examples ###### title List items in a conversation ###### request ####### curl curl "https://api.openai.com/v1/conversations/conv_123/items?limit=10" \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### javascript import OpenAI from "openai"; const client = new OpenAI(); const items = await client.conversations.items.list("conv_123", { limit: 10 }); console.log(items.data); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.conversations.items.list( conversation_id="conv_123", ) page = page.data[0] print(page) ####### csharp using System; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); ConversationItemList items = client.ConversationItems.List( conversationId: "conv_123", new ListConversationItemsOptions { Limit = 10 } ); Console.WriteLine(items.Data.Count); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const conversationItem of client.conversations.items.list('conv_123')) { console.log(conversationItem); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/conversations" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Conversations.Items.List( context.TODO(), "conv_123", conversations.ItemListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.conversations.items.ItemListPage; import com.openai.models.conversations.items.ItemListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ItemListPage page = client.conversations().items().list("conv_123"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.conversations.items.list("conv_123") puts(page) ###### response { "object": "list", "data": [ { "type": "message", "id": "msg_abc", "status": "completed", "role": "user", "content": [ {"type": "input_text", "text": "Hello!"} ] } ], "first_id": "msg_abc", "last_id": "msg_abc", "has_more": false } #### description List all items for a conversation with the given ID. ## /conversations/{conversation_id}/items/{item_id} ### get #### operationId getConversationItem #### tags - Conversations #### summary Retrieve an item #### parameters ##### in path ##### name conversation_id ##### required true ##### schema ###### type string ###### example conv_123 ##### description The ID of the conversation that contains the item. ##### in path ##### name item_id ##### required true ##### schema ###### type string ###### example msg_abc ##### description The ID of the item to retrieve. ##### name include ##### in query ##### required false ##### schema ###### type array ###### items ####### $ref #/components/schemas/Includable ##### description Additional fields to include in the response. See the `include` parameter for [listing Conversation items above](https://platform.openai.com/docs/api-reference/conversations/list-items#conversations_list_items-include) for more information. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ConversationItem #### x-oaiMeta ##### name Retrieve an item ##### group conversations ##### returns Returns a [Conversation Item](https://platform.openai.com/docs/api-reference/conversations/item-object). ##### path get-item ##### examples ###### title Retrieve an item ###### request ####### curl curl https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### javascript import OpenAI from "openai"; const client = new OpenAI(); const item = await client.conversations.items.retrieve( "conv_123", "msg_abc" ); console.log(item); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) conversation_item = client.conversations.items.retrieve( item_id="msg_abc", conversation_id="conv_123", ) print(conversation_item) ####### csharp using System; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); ConversationItem item = client.ConversationItems.Get( conversationId: "conv_123", itemId: "msg_abc" ); Console.WriteLine(item.Id); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const conversationItem = await client.conversations.items.retrieve('msg_abc', { conversation_id: 'conv_123', }); console.log(conversationItem); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/conversations" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) conversationItem, err := client.Conversations.Items.Get( context.TODO(), "conv_123", "msg_abc", conversations.ItemGetParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", conversationItem) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.conversations.items.ConversationItem; import com.openai.models.conversations.items.ItemRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ItemRetrieveParams params = ItemRetrieveParams.builder() .conversationId("conv_123") .itemId("msg_abc") .build(); ConversationItem conversationItem = client.conversations().items().retrieve(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") conversation_item = openai.conversations.items.retrieve("msg_abc", conversation_id: "conv_123") puts(conversation_item) ###### response { "type": "message", "id": "msg_abc", "status": "completed", "role": "user", "content": [ {"type": "input_text", "text": "Hello!"} ] } #### description Get a single item from a conversation with the given IDs. ### delete #### operationId deleteConversationItem #### tags - Conversations #### summary Delete an item #### parameters ##### in path ##### name conversation_id ##### required true ##### schema ###### type string ###### example conv_123 ##### description The ID of the conversation that contains the item. ##### in path ##### name item_id ##### required true ##### schema ###### type string ###### example msg_abc ##### description The ID of the item to delete. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ConversationResource #### x-oaiMeta ##### name Delete an item ##### group conversations ##### returns Returns the updated [Conversation](https://platform.openai.com/docs/api-reference/conversations/object) object. ##### path delete-item ##### examples ###### title Delete an item ###### request ####### curl curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### javascript import OpenAI from "openai"; const client = new OpenAI(); const conversation = await client.conversations.items.delete( "conv_123", "msg_abc" ); console.log(conversation); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) conversation = client.conversations.items.delete( item_id="msg_abc", conversation_id="conv_123", ) print(conversation.id) ####### csharp using System; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); Conversation conversation = client.ConversationItems.Delete( conversationId: "conv_123", itemId: "msg_abc" ); Console.WriteLine(conversation.Id); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const conversation = await client.conversations.items.delete('msg_abc', { conversation_id: 'conv_123' }); console.log(conversation.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) conversation, err := client.Conversations.Items.Delete( context.TODO(), "conv_123", "msg_abc", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", conversation.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.conversations.Conversation; import com.openai.models.conversations.items.ItemDeleteParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ItemDeleteParams params = ItemDeleteParams.builder() .conversationId("conv_123") .itemId("msg_abc") .build(); Conversation conversation = client.conversations().items().delete(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") conversation = openai.conversations.items.delete("msg_abc", conversation_id: "conv_123") puts(conversation) ###### response { "id": "conv_123", "object": "conversation", "created_at": 1741900000, "metadata": {"topic": "demo"} } #### description Delete an item from a conversation with the given IDs. ## /embeddings ### post #### operationId createEmbedding #### tags - Embeddings #### summary Create embeddings #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateEmbeddingRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/CreateEmbeddingResponse #### x-oaiMeta ##### name Create embeddings ##### group embeddings ##### returns A list of [embedding](https://platform.openai.com/docs/api-reference/embeddings/object) objects. ##### examples ###### response { "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 } } ###### request ####### curl 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( api_key="My API Key", ) create_embedding_response = client.embeddings.create( input="The quick brown fox jumped over the lazy dog", model="text-embedding-3-small", ) print(create_embedding_response.data) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const createEmbeddingResponse = await client.embeddings.create({ input: 'The quick brown fox jumped over the lazy dog', model: 'text-embedding-3-small', }); console.log(createEmbeddingResponse.data); ####### 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]}"); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) createEmbeddingResponse, err := client.Embeddings.New(context.TODO(), openai.EmbeddingNewParams{ Input: openai.EmbeddingNewParamsInputUnion{ OfString: openai.String("The quick brown fox jumped over the lazy dog"), }, Model: openai.EmbeddingModelTextEmbeddingAda002, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", createEmbeddingResponse.Data) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.embeddings.CreateEmbeddingResponse; import com.openai.models.embeddings.EmbeddingCreateParams; import com.openai.models.embeddings.EmbeddingModel; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); EmbeddingCreateParams params = EmbeddingCreateParams.builder() .input("The quick brown fox jumped over the lazy dog") .model(EmbeddingModel.TEXT_EMBEDDING_ADA_002) .build(); CreateEmbeddingResponse createEmbeddingResponse = client.embeddings().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") create_embedding_response = openai.embeddings.create( input: "The quick brown fox jumped over the lazy dog", model: :"text-embedding-ada-002" ) puts(create_embedding_response) #### description Creates an embedding vector representing the input text. ## /evals ### get #### operationId listEvals #### tags - Evals #### summary List evals #### parameters ##### name after ##### in query ##### description Identifier for the last eval from the previous pagination request. ##### required false ##### schema ###### type string ##### name limit ##### in query ##### description Number of evals to retrieve. ##### required false ##### schema ###### type integer ###### default 20 ##### name order ##### in query ##### description Sort order for evals by timestamp. Use `asc` for ascending order or `desc` for descending order. ##### required false ##### schema ###### type string ###### enum - asc - desc ###### default asc ##### name order_by ##### in query ##### description Evals can be ordered by creation time or last updated time. Use `created_at` for creation time or `updated_at` for last updated time. ##### required false ##### schema ###### type string ###### enum - created_at - updated_at ###### default created_at #### responses ##### 200 ###### description A list of evals ###### content ####### application/json ######## schema ######### $ref #/components/schemas/EvalList #### x-oaiMeta ##### name List evals ##### group evals ##### returns A list of [evals](https://platform.openai.com/docs/api-reference/evals/object) matching the specified filters. ##### path list ##### examples ###### response { "object": "list", "data": [ { "id": "eval_67abd54d9b0081909a86353f6fb9317a", "object": "eval", "data_source_config": { "type": "stored_completions", "metadata": { "usecase": "push_notifications_summarizer" }, "schema": { "type": "object", "properties": { "item": { "type": "object" }, "sample": { "type": "object" } }, "required": [ "item", "sample" ] } }, "testing_criteria": [ { "name": "Push Notification Summary Grader", "id": "Push Notification Summary Grader-9b876f24-4762-4be9-aff4-db7a9b31c673", "type": "label_model", "model": "o3-mini", "input": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "text": "\nLabel the following push notification summary as either correct or incorrect.\nThe push notification and the summary will be provided below.\nA good push notificiation summary is concise and snappy.\nIf it is good, then label it as correct, if not, then incorrect.\n" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "\nPush notifications: {{item.input}}\nSummary: {{sample.output_text}}\n" } } ], "passing_labels": [ "correct" ], "labels": [ "correct", "incorrect" ], "sampling_params": null } ], "name": "Push Notification Summary Grader", "created_at": 1739314509, "metadata": { "description": "A stored completions eval for push notification summaries" } } ], "first_id": "eval_67abd54d9b0081909a86353f6fb9317a", "last_id": "eval_67aa884cf6688190b58f657d4441c8b7", "has_more": true } ###### request ####### curl curl https://api.openai.com/v1/evals?limit=1 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.evals.list() page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const evalListResponse of client.evals.list()) { console.log(evalListResponse.id); } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.evals.EvalListPage; import com.openai.models.evals.EvalListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); EvalListPage page = client.evals().list(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.evals.list puts(page) #### description List evaluations for a project. ### post #### operationId createEval #### tags - Evals #### summary Create eval #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateEvalRequest #### responses ##### 201 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Eval #### x-oaiMeta ##### name Create eval ##### group evals ##### returns The created [Eval](https://platform.openai.com/docs/api-reference/evals/object) object. ##### path post ##### examples ###### response { "object": "eval", "id": "eval_67b7fa9a81a88190ab4aa417e397ea21", "data_source_config": { "type": "stored_completions", "metadata": { "usecase": "chatbot" }, "schema": { "type": "object", "properties": { "item": { "type": "object" }, "sample": { "type": "object" } }, "required": [ "item", "sample" ] }, "testing_criteria": [ { "name": "Example label grader", "type": "label_model", "model": "o3-mini", "input": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "text": "Classify the sentiment of the following statement as one of positive, neutral, or negative" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "Statement: {{item.input}}" } } ], "passing_labels": [ "positive" ], "labels": [ "positive", "neutral", "negative" ] } ], "name": "Sentiment", "created_at": 1740110490, "metadata": { "description": "An eval for sentiment analysis" } } ###### request ####### curl curl https://api.openai.com/v1/evals \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Sentiment", "data_source_config": { "type": "stored_completions", "metadata": { "usecase": "chatbot" } }, "testing_criteria": [ { "type": "label_model", "model": "o3-mini", "input": [ { "role": "developer", "content": "Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'" }, { "role": "user", "content": "Statement: {{item.input}}" } ], "passing_labels": [ "positive" ], "labels": [ "positive", "neutral", "negative" ], "name": "Example label grader" } ] }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) eval = client.evals.create( data_source_config={ "item_schema": { "foo": "bar" }, "type": "custom", }, testing_criteria=[{ "input": [{ "content": "content", "role": "role", }], "labels": ["string"], "model": "model", "name": "name", "passing_labels": ["string"], "type": "label_model", }], ) print(eval.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const _eval = await client.evals.create({ data_source_config: { item_schema: { foo: 'bar' }, type: 'custom' }, testing_criteria: [ { input: [{ content: 'content', role: 'role' }], labels: ['string'], model: 'model', name: 'name', passing_labels: ['string'], type: 'label_model', }, ], }); console.log(_eval.id); ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.core.JsonValue; import com.openai.models.evals.EvalCreateParams; import com.openai.models.evals.EvalCreateResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); EvalCreateParams params = EvalCreateParams.builder() .customDataSourceConfig(EvalCreateParams.DataSourceConfig.Custom.ItemSchema.builder() .putAdditionalProperty("foo", JsonValue.from("bar")) .build()) .addTestingCriterion(EvalCreateParams.TestingCriterion.LabelModel.builder() .addInput(EvalCreateParams.TestingCriterion.LabelModel.Input.SimpleInputMessage.builder() .content("content") .role("role") .build()) .addLabel("string") .model("model") .name("name") .addPassingLabel("string") .build()) .build(); EvalCreateResponse eval = client.evals().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") eval_ = openai.evals.create( data_source_config: {item_schema: {foo: "bar"}, type: :custom}, testing_criteria: [ { input: [{content: "content", role: "role"}], labels: ["string"], model: "model", name: "name", passing_labels: ["string"], type: :label_model } ] ) puts(eval_) #### description Create the structure of an evaluation that can be used to test a model's performance. An evaluation is a set of testing criteria and the config for a data source, which dictates the schema of the data used in the evaluation. After creating an evaluation, you can run it on different models and model parameters. We support several types of graders and datasources. For more information, see the [Evals guide](https://platform.openai.com/docs/guides/evals). ## /evals/{eval_id} ### get #### operationId getEval #### tags - Evals #### summary Get an eval #### parameters ##### name eval_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the evaluation to retrieve. #### responses ##### 200 ###### description The evaluation ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Eval #### x-oaiMeta ##### name Get an eval ##### group evals ##### returns The [Eval](https://platform.openai.com/docs/api-reference/evals/object) object matching the specified ID. ##### path get ##### examples ###### response { "object": "eval", "id": "eval_67abd54d9b0081909a86353f6fb9317a", "data_source_config": { "type": "custom", "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "input": { "type": "string" }, "ground_truth": { "type": "string" } }, "required": [ "input", "ground_truth" ] } }, "required": [ "item" ] } }, "testing_criteria": [ { "name": "String check", "id": "String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2", "type": "string_check", "input": "{{item.input}}", "reference": "{{item.ground_truth}}", "operation": "eq" } ], "name": "External Data Eval", "created_at": 1739314509, "metadata": {}, } ###### request ####### curl curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) eval = client.evals.retrieve( "eval_id", ) print(eval.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const _eval = await client.evals.retrieve('eval_id'); console.log(_eval.id); ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.evals.EvalRetrieveParams; import com.openai.models.evals.EvalRetrieveResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); EvalRetrieveResponse eval = client.evals().retrieve("eval_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") eval_ = openai.evals.retrieve("eval_id") puts(eval_) #### description Get an evaluation by ID. ### post #### operationId updateEval #### tags - Evals #### summary Update an eval #### parameters ##### name eval_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the evaluation to update. #### requestBody ##### description Request to update an evaluation ##### required true ##### content ###### application/json ####### schema ######## type object ######## properties ######### name ########## type string ########## description Rename the evaluation. ######### metadata ########## $ref #/components/schemas/Metadata #### responses ##### 200 ###### description The updated evaluation ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Eval #### x-oaiMeta ##### name Update an eval ##### group evals ##### returns The [Eval](https://platform.openai.com/docs/api-reference/evals/object) object matching the updated version. ##### path update ##### examples ###### response { "object": "eval", "id": "eval_67abd54d9b0081909a86353f6fb9317a", "data_source_config": { "type": "custom", "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "input": { "type": "string" }, "ground_truth": { "type": "string" } }, "required": [ "input", "ground_truth" ] } }, "required": [ "item" ] } }, "testing_criteria": [ { "name": "String check", "id": "String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2", "type": "string_check", "input": "{{item.input}}", "reference": "{{item.ground_truth}}", "operation": "eq" } ], "name": "Updated Eval", "created_at": 1739314509, "metadata": {"description": "Updated description"}, } ###### request ####### curl curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Updated Eval", "metadata": {"description": "Updated description"}}' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) eval = client.evals.update( eval_id="eval_id", ) print(eval.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const _eval = await client.evals.update('eval_id'); console.log(_eval.id); ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.evals.EvalUpdateParams; import com.openai.models.evals.EvalUpdateResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); EvalUpdateResponse eval = client.evals().update("eval_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") eval_ = openai.evals.update("eval_id") puts(eval_) #### description Update certain properties of an evaluation. ### delete #### operationId deleteEval #### tags - Evals #### summary Delete an eval #### parameters ##### name eval_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the evaluation to delete. #### responses ##### 200 ###### description Successfully deleted the evaluation. ###### content ####### application/json ######## schema ######### type object ######### properties ########## object ########### type string ########### example eval.deleted ########## deleted ########### type boolean ########### example true ########## eval_id ########### type string ########### example eval_abc123 ######### required - object - deleted - eval_id ##### 404 ###### description Evaluation not found. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Error #### x-oaiMeta ##### name Delete an eval ##### group evals ##### returns A deletion confirmation object. ##### examples ###### response { "object": "eval.deleted", "deleted": true, "eval_id": "eval_abc123" } ###### request ####### curl curl https://api.openai.com/v1/evals/eval_abc123 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) eval = client.evals.delete( "eval_id", ) print(eval.eval_id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const _eval = await client.evals.delete('eval_id'); console.log(_eval.eval_id); ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.evals.EvalDeleteParams; import com.openai.models.evals.EvalDeleteResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); EvalDeleteResponse eval = client.evals().delete("eval_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") eval_ = openai.evals.delete("eval_id") puts(eval_) #### description Delete an evaluation. ## /evals/{eval_id}/runs ### get #### operationId getEvalRuns #### tags - Evals #### summary Get eval runs #### parameters ##### name eval_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the evaluation to retrieve runs for. ##### name after ##### in query ##### description Identifier for the last run from the previous pagination request. ##### required false ##### schema ###### type string ##### name limit ##### in query ##### description Number of runs to retrieve. ##### required false ##### schema ###### type integer ###### default 20 ##### name order ##### in query ##### description Sort order for runs 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 ##### name status ##### in query ##### description Filter runs by status. One of `queued` | `in_progress` | `failed` | `completed` | `canceled`. ##### required false ##### schema ###### type string ###### enum - queued - in_progress - completed - canceled - failed #### responses ##### 200 ###### description A list of runs for the evaluation ###### content ####### application/json ######## schema ######### $ref #/components/schemas/EvalRunList #### x-oaiMeta ##### name Get eval runs ##### group evals ##### returns A list of [EvalRun](https://platform.openai.com/docs/api-reference/evals/run-object) objects matching the specified ID. ##### path get-runs ##### examples ###### response { "object": "list", "data": [ { "object": "eval.run", "id": "evalrun_67e0c7d31560819090d60c0780591042", "eval_id": "eval_67e0c726d560819083f19a957c4c640b", "report_url": "https://platform.openai.com/evaluations/eval_67e0c726d560819083f19a957c4c640b", "status": "completed", "model": "o3-mini", "name": "bulk_with_negative_examples_o3-mini", "created_at": 1742784467, "result_counts": { "total": 1, "errored": 0, "failed": 0, "passed": 1 }, "per_model_usage": [ { "model_name": "o3-mini", "invocation_count": 1, "prompt_tokens": 563, "completion_tokens": 874, "total_tokens": 1437, "cached_tokens": 0 } ], "per_testing_criteria_results": [ { "testing_criteria": "Push Notification Summary Grader-1808cd0b-eeec-4e0b-a519-337e79f4f5d1", "passed": 1, "failed": 0 } ], "data_source": { "type": "completions", "source": { "type": "file_content", "content": [ { "item": { "notifications": "\n- New message from Sarah: \"Can you call me later?\"\n- Your package has been delivered!\n- Flash sale: 20% off electronics for the next 2 hours!\n" } } ] }, "input_messages": { "type": "template", "template": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "text": "\n\n\n\nYou are a helpful assistant that takes in an array of push notifications and returns a collapsed summary of them.\nThe push notification will be provided as follows:\n\n...notificationlist...\n\n\nYou should return just the summary and nothing else.\n\n\nYou should return a summary that is concise and snappy.\n\n\nHere is an example of a good summary:\n\n- Traffic alert: Accident reported on Main Street.- Package out for delivery: Expected by 5 PM.- New friend suggestion: Connect with Emma.\n\n\nTraffic alert, package expected by 5pm, suggestion for new friend (Emily).\n\n\n\nHere is an example of a bad summary:\n\n- Traffic alert: Accident reported on Main Street.- Package out for delivery: Expected by 5 PM.- New friend suggestion: Connect with Emma.\n\n\nTraffic alert reported on main street. You have a package that will arrive by 5pm, Emily is a new friend suggested for you.\n\n" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "{{item.notifications}}" } } ] }, "model": "o3-mini", "sampling_params": null }, "error": null, "metadata": {} } ], "first_id": "evalrun_67e0c7d31560819090d60c0780591042", "last_id": "evalrun_67e0c7d31560819090d60c0780591042", "has_more": true } ###### request ####### curl curl https://api.openai.com/v1/evals/egroup_67abd54d9b0081909a86353f6fb9317a/runs \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.evals.runs.list( eval_id="eval_id", ) page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const runListResponse of client.evals.runs.list('eval_id')) { console.log(runListResponse.id); } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.evals.runs.RunListPage; import com.openai.models.evals.runs.RunListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunListPage page = client.evals().runs().list("eval_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.evals.runs.list("eval_id") puts(page) #### description Get a list of runs for an evaluation. ### post #### operationId createEvalRun #### tags - Evals #### summary Create eval run #### parameters ##### in path ##### name eval_id ##### required true ##### schema ###### type string ##### description The ID of the evaluation to create a run for. #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateEvalRunRequest #### responses ##### 201 ###### description Successfully created a run for the evaluation ###### content ####### application/json ######## schema ######### $ref #/components/schemas/EvalRun ##### 400 ###### description Bad request (for example, missing eval object) ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Error #### x-oaiMeta ##### name Create eval run ##### group evals ##### returns The [EvalRun](https://platform.openai.com/docs/api-reference/evals/run-object) object matching the specified ID. ##### examples ###### response { "object": "eval.run", "id": "evalrun_67e57965b480819094274e3a32235e4c", "eval_id": "eval_67e579652b548190aaa83ada4b125f47", "report_url": "https://platform.openai.com/evaluations/eval_67e579652b548190aaa83ada4b125f47&run_id=evalrun_67e57965b480819094274e3a32235e4c", "status": "queued", "model": "gpt-4o-mini", "name": "gpt-4o-mini", "created_at": 1743092069, "result_counts": { "total": 0, "errored": 0, "failed": 0, "passed": 0 }, "per_model_usage": null, "per_testing_criteria_results": null, "data_source": { "type": "completions", "source": { "type": "file_content", "content": [ { "item": { "input": "Tech Company Launches Advanced Artificial Intelligence Platform", "ground_truth": "Technology" } } ] }, "input_messages": { "type": "template", "template": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "text": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "{{item.input}}" } } ] }, "model": "gpt-4o-mini", "sampling_params": { "seed": 42, "temperature": 1.0, "top_p": 1.0, "max_completions_tokens": 2048 } }, "error": null, "metadata": {} } ###### request ####### curl curl https://api.openai.com/v1/evals/eval_67e579652b548190aaa83ada4b125f47/runs \ -X POST \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"gpt-4o-mini","data_source":{"type":"completions","input_messages":{"type":"template","template":[{"role":"developer","content":"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n"} , {"role":"user","content":"{{item.input}}"}]} ,"sampling_params":{"temperature":1,"max_completions_tokens":2048,"top_p":1,"seed":42},"model":"gpt-4o-mini","source":{"type":"file_content","content":[{"item":{"input":"Tech Company Launches Advanced Artificial Intelligence Platform","ground_truth":"Technology"}}]}}' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) run = client.evals.runs.create( eval_id="eval_id", data_source={ "source": { "content": [{ "item": { "foo": "bar" } }], "type": "file_content", }, "type": "jsonl", }, ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.evals.runs.create('eval_id', { data_source: { source: { content: [{ item: { foo: 'bar' } }], type: 'file_content' }, type: 'jsonl' }, }); console.log(run.id); ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.core.JsonValue; import com.openai.models.evals.runs.CreateEvalJsonlRunDataSource; import com.openai.models.evals.runs.RunCreateParams; import com.openai.models.evals.runs.RunCreateResponse; import java.util.List; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunCreateParams params = RunCreateParams.builder() .evalId("eval_id") .dataSource(CreateEvalJsonlRunDataSource.builder() .fileContentSource(List.of(CreateEvalJsonlRunDataSource.Source.FileContent.Content.builder() .item(CreateEvalJsonlRunDataSource.Source.FileContent.Content.Item.builder() .putAdditionalProperty("foo", JsonValue.from("bar")) .build()) .build())) .build()) .build(); RunCreateResponse run = client.evals().runs().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.evals.runs.create( "eval_id", data_source: {source: {content: [{item: {foo: "bar"}}], type: :file_content}, type: :jsonl} ) puts(run) #### description Kicks off a new run for a given evaluation, specifying the data source, and what model configuration to use to test. The datasource will be validated against the schema specified in the config of the evaluation. ## /evals/{eval_id}/runs/{run_id} ### get #### operationId getEvalRun #### tags - Evals #### summary Get an eval run #### parameters ##### name eval_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the evaluation to retrieve runs for. ##### name run_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the run to retrieve. #### responses ##### 200 ###### description The evaluation run ###### content ####### application/json ######## schema ######### $ref #/components/schemas/EvalRun #### x-oaiMeta ##### name Get an eval run ##### group evals ##### returns The [EvalRun](https://platform.openai.com/docs/api-reference/evals/run-object) object matching the specified ID. ##### path get ##### examples ###### response { "object": "eval.run", "id": "evalrun_67abd54d60ec8190832b46859da808f7", "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", "report_url": "https://platform.openai.com/evaluations/eval_67abd54d9b0081909a86353f6fb9317a?run_id=evalrun_67abd54d60ec8190832b46859da808f7", "status": "queued", "model": "gpt-4o-mini", "name": "gpt-4o-mini", "created_at": 1743092069, "result_counts": { "total": 0, "errored": 0, "failed": 0, "passed": 0 }, "per_model_usage": null, "per_testing_criteria_results": null, "data_source": { "type": "completions", "source": { "type": "file_content", "content": [ { "item": { "input": "Tech Company Launches Advanced Artificial Intelligence Platform", "ground_truth": "Technology" } }, { "item": { "input": "Central Bank Increases Interest Rates Amid Inflation Concerns", "ground_truth": "Markets" } }, { "item": { "input": "International Summit Addresses Climate Change Strategies", "ground_truth": "World" } }, { "item": { "input": "Major Retailer Reports Record-Breaking Holiday Sales", "ground_truth": "Business" } }, { "item": { "input": "National Team Qualifies for World Championship Finals", "ground_truth": "Sports" } }, { "item": { "input": "Stock Markets Rally After Positive Economic Data Released", "ground_truth": "Markets" } }, { "item": { "input": "Global Manufacturer Announces Merger with Competitor", "ground_truth": "Business" } }, { "item": { "input": "Breakthrough in Renewable Energy Technology Unveiled", "ground_truth": "Technology" } }, { "item": { "input": "World Leaders Sign Historic Climate Agreement", "ground_truth": "World" } }, { "item": { "input": "Professional Athlete Sets New Record in Championship Event", "ground_truth": "Sports" } }, { "item": { "input": "Financial Institutions Adapt to New Regulatory Requirements", "ground_truth": "Business" } }, { "item": { "input": "Tech Conference Showcases Advances in Artificial Intelligence", "ground_truth": "Technology" } }, { "item": { "input": "Global Markets Respond to Oil Price Fluctuations", "ground_truth": "Markets" } }, { "item": { "input": "International Cooperation Strengthened Through New Treaty", "ground_truth": "World" } }, { "item": { "input": "Sports League Announces Revised Schedule for Upcoming Season", "ground_truth": "Sports" } } ] }, "input_messages": { "type": "template", "template": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "text": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "{{item.input}}" } } ] }, "model": "gpt-4o-mini", "sampling_params": { "seed": 42, "temperature": 1.0, "top_p": 1.0, "max_completions_tokens": 2048 } }, "error": null, "metadata": {} } ###### request ####### curl curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) run = client.evals.runs.retrieve( run_id="run_id", eval_id="eval_id", ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.evals.runs.retrieve('run_id', { eval_id: 'eval_id' }); console.log(run.id); ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.evals.runs.RunRetrieveParams; import com.openai.models.evals.runs.RunRetrieveResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunRetrieveParams params = RunRetrieveParams.builder() .evalId("eval_id") .runId("run_id") .build(); RunRetrieveResponse run = client.evals().runs().retrieve(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.evals.runs.retrieve("run_id", eval_id: "eval_id") puts(run) #### description Get an evaluation run by ID. ### post #### operationId cancelEvalRun #### tags - Evals #### summary Cancel eval run #### parameters ##### name eval_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the evaluation whose run you want to cancel. ##### name run_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the run to cancel. #### responses ##### 200 ###### description The canceled eval run object ###### content ####### application/json ######## schema ######### $ref #/components/schemas/EvalRun #### x-oaiMeta ##### name Cancel eval run ##### group evals ##### returns The updated [EvalRun](https://platform.openai.com/docs/api-reference/evals/run-object) object reflecting that the run is canceled. ##### path post ##### examples ###### response { "object": "eval.run", "id": "evalrun_67abd54d60ec8190832b46859da808f7", "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", "report_url": "https://platform.openai.com/evaluations/eval_67abd54d9b0081909a86353f6fb9317a?run_id=evalrun_67abd54d60ec8190832b46859da808f7", "status": "canceled", "model": "gpt-4o-mini", "name": "gpt-4o-mini", "created_at": 1743092069, "result_counts": { "total": 0, "errored": 0, "failed": 0, "passed": 0 }, "per_model_usage": null, "per_testing_criteria_results": null, "data_source": { "type": "completions", "source": { "type": "file_content", "content": [ { "item": { "input": "Tech Company Launches Advanced Artificial Intelligence Platform", "ground_truth": "Technology" } }, { "item": { "input": "Central Bank Increases Interest Rates Amid Inflation Concerns", "ground_truth": "Markets" } }, { "item": { "input": "International Summit Addresses Climate Change Strategies", "ground_truth": "World" } }, { "item": { "input": "Major Retailer Reports Record-Breaking Holiday Sales", "ground_truth": "Business" } }, { "item": { "input": "National Team Qualifies for World Championship Finals", "ground_truth": "Sports" } }, { "item": { "input": "Stock Markets Rally After Positive Economic Data Released", "ground_truth": "Markets" } }, { "item": { "input": "Global Manufacturer Announces Merger with Competitor", "ground_truth": "Business" } }, { "item": { "input": "Breakthrough in Renewable Energy Technology Unveiled", "ground_truth": "Technology" } }, { "item": { "input": "World Leaders Sign Historic Climate Agreement", "ground_truth": "World" } }, { "item": { "input": "Professional Athlete Sets New Record in Championship Event", "ground_truth": "Sports" } }, { "item": { "input": "Financial Institutions Adapt to New Regulatory Requirements", "ground_truth": "Business" } }, { "item": { "input": "Tech Conference Showcases Advances in Artificial Intelligence", "ground_truth": "Technology" } }, { "item": { "input": "Global Markets Respond to Oil Price Fluctuations", "ground_truth": "Markets" } }, { "item": { "input": "International Cooperation Strengthened Through New Treaty", "ground_truth": "World" } }, { "item": { "input": "Sports League Announces Revised Schedule for Upcoming Season", "ground_truth": "Sports" } } ] }, "input_messages": { "type": "template", "template": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "text": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "{{item.input}}" } } ] }, "model": "gpt-4o-mini", "sampling_params": { "seed": 42, "temperature": 1.0, "top_p": 1.0, "max_completions_tokens": 2048 } }, "error": null, "metadata": {} } ###### request ####### curl curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7/cancel \ -X POST \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) response = client.evals.runs.cancel( run_id="run_id", eval_id="eval_id", ) print(response.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.evals.runs.cancel('run_id', { eval_id: 'eval_id' }); console.log(response.id); ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.evals.runs.RunCancelParams; import com.openai.models.evals.runs.RunCancelResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunCancelParams params = RunCancelParams.builder() .evalId("eval_id") .runId("run_id") .build(); RunCancelResponse response = client.evals().runs().cancel(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.evals.runs.cancel("run_id", eval_id: "eval_id") puts(response) #### description Cancel an ongoing evaluation run. ### delete #### operationId deleteEvalRun #### tags - Evals #### summary Delete eval run #### parameters ##### name eval_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the evaluation to delete the run from. ##### name run_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the run to delete. #### responses ##### 200 ###### description Successfully deleted the eval run ###### content ####### application/json ######## schema ######### type object ######### properties ########## object ########### type string ########### example eval.run.deleted ########## deleted ########### type boolean ########### example true ########## run_id ########### type string ########### example evalrun_677469f564d48190807532a852da3afb ##### 404 ###### description Run not found ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Error #### x-oaiMeta ##### name Delete eval run ##### group evals ##### returns An object containing the status of the delete operation. ##### path delete ##### examples ###### response { "object": "eval.run.deleted", "deleted": true, "run_id": "evalrun_abc456" } ###### request ####### curl curl https://api.openai.com/v1/evals/eval_123abc/runs/evalrun_abc456 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) run = client.evals.runs.delete( run_id="run_id", eval_id="eval_id", ) print(run.run_id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.evals.runs.delete('run_id', { eval_id: 'eval_id' }); console.log(run.run_id); ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.evals.runs.RunDeleteParams; import com.openai.models.evals.runs.RunDeleteResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunDeleteParams params = RunDeleteParams.builder() .evalId("eval_id") .runId("run_id") .build(); RunDeleteResponse run = client.evals().runs().delete(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.evals.runs.delete("run_id", eval_id: "eval_id") puts(run) #### description Delete an eval run. ## /evals/{eval_id}/runs/{run_id}/output_items ### get #### operationId getEvalRunOutputItems #### tags - Evals #### summary Get eval run output items #### parameters ##### name eval_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the evaluation to retrieve runs for. ##### name run_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the run to retrieve output items for. ##### name after ##### in query ##### description Identifier for the last output item from the previous pagination request. ##### required false ##### schema ###### type string ##### name limit ##### in query ##### description Number of output items to retrieve. ##### required false ##### schema ###### type integer ###### default 20 ##### name status ##### in query ##### description Filter output items by status. Use `failed` to filter by failed output items or `pass` to filter by passed output items. ##### required false ##### schema ###### type string ###### enum - fail - pass ##### name order ##### in query ##### description Sort order for output items 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 output items for the evaluation run ###### content ####### application/json ######## schema ######### $ref #/components/schemas/EvalRunOutputItemList #### x-oaiMeta ##### name Get eval run output items ##### group evals ##### returns A list of [EvalRunOutputItem](https://platform.openai.com/docs/api-reference/evals/run-output-item-object) objects matching the specified ID. ##### path get ##### examples ###### response { "object": "list", "data": [ { "object": "eval.run.output_item", "id": "outputitem_67e5796c28e081909917bf79f6e6214d", "created_at": 1743092076, "run_id": "evalrun_67abd54d60ec8190832b46859da808f7", "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", "status": "pass", "datasource_item_id": 5, "datasource_item": { "input": "Stock Markets Rally After Positive Economic Data Released", "ground_truth": "Markets" }, "results": [ { "name": "String check-a2486074-d803-4445-b431-ad2262e85d47", "sample": null, "passed": true, "score": 1.0 } ], "sample": { "input": [ { "role": "developer", "content": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n", "tool_call_id": null, "tool_calls": null, "function_call": null }, { "role": "user", "content": "Stock Markets Rally After Positive Economic Data Released", "tool_call_id": null, "tool_calls": null, "function_call": null } ], "output": [ { "role": "assistant", "content": "Markets", "tool_call_id": null, "tool_calls": null, "function_call": null } ], "finish_reason": "stop", "model": "gpt-4o-mini-2024-07-18", "usage": { "total_tokens": 325, "completion_tokens": 2, "prompt_tokens": 323, "cached_tokens": 0 }, "error": null, "temperature": 1.0, "max_completion_tokens": 2048, "top_p": 1.0, "seed": 42 } } ], "first_id": "outputitem_67e5796c28e081909917bf79f6e6214d", "last_id": "outputitem_67e5796c28e081909917bf79f6e6214d", "has_more": true } ###### request ####### curl curl https://api.openai.com/v1/evals/egroup_67abd54d9b0081909a86353f6fb9317a/runs/erun_67abd54d60ec8190832b46859da808f7/output_items \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.evals.runs.output_items.list( run_id="run_id", eval_id="eval_id", ) page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const outputItemListResponse of client.evals.runs.outputItems.list('run_id', { eval_id: 'eval_id', })) { console.log(outputItemListResponse.id); } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.evals.runs.outputitems.OutputItemListPage; import com.openai.models.evals.runs.outputitems.OutputItemListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); OutputItemListParams params = OutputItemListParams.builder() .evalId("eval_id") .runId("run_id") .build(); OutputItemListPage page = client.evals().runs().outputItems().list(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.evals.runs.output_items.list("run_id", eval_id: "eval_id") puts(page) #### description Get a list of output items for an evaluation run. ## /evals/{eval_id}/runs/{run_id}/output_items/{output_item_id} ### get #### operationId getEvalRunOutputItem #### tags - Evals #### summary Get an output item of an eval run #### parameters ##### name eval_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the evaluation to retrieve runs for. ##### name run_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the run to retrieve. ##### name output_item_id ##### in path ##### required true ##### schema ###### type string ##### description The ID of the output item to retrieve. #### responses ##### 200 ###### description The evaluation run output item ###### content ####### application/json ######## schema ######### $ref #/components/schemas/EvalRunOutputItem #### x-oaiMeta ##### name Get an output item of an eval run ##### group evals ##### returns The [EvalRunOutputItem](https://platform.openai.com/docs/api-reference/evals/run-output-item-object) object matching the specified ID. ##### path get ##### examples ###### response { "object": "eval.run.output_item", "id": "outputitem_67e5796c28e081909917bf79f6e6214d", "created_at": 1743092076, "run_id": "evalrun_67abd54d60ec8190832b46859da808f7", "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", "status": "pass", "datasource_item_id": 5, "datasource_item": { "input": "Stock Markets Rally After Positive Economic Data Released", "ground_truth": "Markets" }, "results": [ { "name": "String check-a2486074-d803-4445-b431-ad2262e85d47", "sample": null, "passed": true, "score": 1.0 } ], "sample": { "input": [ { "role": "developer", "content": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n", "tool_call_id": null, "tool_calls": null, "function_call": null }, { "role": "user", "content": "Stock Markets Rally After Positive Economic Data Released", "tool_call_id": null, "tool_calls": null, "function_call": null } ], "output": [ { "role": "assistant", "content": "Markets", "tool_call_id": null, "tool_calls": null, "function_call": null } ], "finish_reason": "stop", "model": "gpt-4o-mini-2024-07-18", "usage": { "total_tokens": 325, "completion_tokens": 2, "prompt_tokens": 323, "cached_tokens": 0 }, "error": null, "temperature": 1.0, "max_completion_tokens": 2048, "top_p": 1.0, "seed": 42 } } ###### request ####### curl curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7/output_items/outputitem_67abd55eb6548190bb580745d5644a33 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) output_item = client.evals.runs.output_items.retrieve( output_item_id="output_item_id", eval_id="eval_id", run_id="run_id", ) print(output_item.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const outputItem = await client.evals.runs.outputItems.retrieve('output_item_id', { eval_id: 'eval_id', run_id: 'run_id', }); console.log(outputItem.id); ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.evals.runs.outputitems.OutputItemRetrieveParams; import com.openai.models.evals.runs.outputitems.OutputItemRetrieveResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); OutputItemRetrieveParams params = OutputItemRetrieveParams.builder() .evalId("eval_id") .runId("run_id") .outputItemId("output_item_id") .build(); OutputItemRetrieveResponse outputItem = client.evals().runs().outputItems().retrieve(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") output_item = openai.evals.runs.output_items.retrieve("output_item_id", eval_id: "eval_id", run_id: "run_id") puts(output_item) #### description Get an evaluation run output item by ID. ## /files ### get #### operationId listFiles #### tags - Files #### summary List files #### parameters ##### 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 #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListFilesResponse #### x-oaiMeta ##### name List files ##### group files ##### returns A list of [File](https://platform.openai.com/docs/api-reference/files/object) objects. ##### examples ###### response { "object": "list", "data": [ { "id": "file-abc123", "object": "file", "bytes": 175, "created_at": 1613677385, "expires_at": 1677614202, "filename": "salesOverview.pdf", "purpose": "assistants", }, { "id": "file-abc456", "object": "file", "bytes": 140, "created_at": 1613779121, "expires_at": 1677614202, "filename": "puppy.jsonl", "purpose": "fine-tune", } ], "first_id": "file-abc123", "last_id": "file-abc456", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/files \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.files.list() page = page.data[0] print(page) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const fileObject of client.files.list()) { console.log(fileObject); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Files.List(context.TODO(), openai.FileListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.files.FileListPage; import com.openai.models.files.FileListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileListPage page = client.files().list(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.files.list puts(page) #### description Returns a list of files. ### post #### operationId createFile #### tags - Files #### summary Upload file #### 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](https://platform.openai.com/docs/api-reference/files/object) object. ##### examples ###### response { "id": "file-abc123", "object": "file", "bytes": 120000, "created_at": 1677610602, "expires_at": 1677614202, "filename": "mydata.jsonl", "purpose": "fine-tune", } ###### request ####### curl curl https://api.openai.com/v1/files \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F purpose="fine-tune" \ -F file="@mydata.jsonl" -F expires_after[anchor]="created_at" -F expires_after[seconds]=3600 ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) file_object = client.files.create( file=b"raw file contents", purpose="assistants", ) print(file_object.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fileObject = await client.files.create({ file: fs.createReadStream('fine-tune.jsonl'), purpose: 'assistants', }); console.log(fileObject.id); ####### go package main import ( "bytes" "context" "fmt" "io" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fileObject, err := client.Files.New(context.TODO(), openai.FileNewParams{ File: io.Reader(bytes.NewBuffer([]byte("some file contents"))), Purpose: openai.FilePurposeAssistants, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fileObject.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.files.FileCreateParams; import com.openai.models.files.FileObject; import com.openai.models.files.FilePurpose; import java.io.ByteArrayInputStream; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileCreateParams params = FileCreateParams.builder() .file(ByteArrayInputStream("some content".getBytes())) .purpose(FilePurpose.ASSISTANTS) .build(); FileObject fileObject = client.files().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") file_object = openai.files.create(file: Pathname(__FILE__), purpose: :assistants) puts(file_object) #### description 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 1 TB. The Assistants API supports files up to 2 million tokens and of specific file types. See the [Assistants Tools guide](https://platform.openai.com/docs/assistants/tools) for details. The Fine-tuning API only supports `.jsonl` files. The input also has certain required formats for fine-tuning [chat](https://platform.openai.com/docs/api-reference/fine-tuning/chat-input) or [completions](https://platform.openai.com/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](https://platform.openai.com/docs/api-reference/batch/request-input). Please [contact us](https://help.openai.com/) if you need to increase these storage limits. ## /files/{file_id} ### delete #### operationId deleteFile #### tags - Files #### summary Delete 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 ###### response { "id": "file-abc123", "object": "file", "deleted": true } ###### 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( api_key="My API Key", ) file_deleted = client.files.delete( "file_id", ) print(file_deleted.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fileDeleted = await client.files.delete('file_id'); console.log(fileDeleted.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fileDeleted, err := client.Files.Delete(context.TODO(), "file_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fileDeleted.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.files.FileDeleteParams; import com.openai.models.files.FileDeleted; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileDeleted fileDeleted = client.files().delete("file_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") file_deleted = openai.files.delete("file_id") puts(file_deleted) #### description Delete a file. ### get #### operationId retrieveFile #### tags - Files #### summary Retrieve 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](https://platform.openai.com/docs/api-reference/files/object) object matching the specified ID. ##### examples ###### response { "id": "file-abc123", "object": "file", "bytes": 120000, "created_at": 1677610602, "expires_at": 1677614202, "filename": "mydata.jsonl", "purpose": "fine-tune", } ###### request ####### curl curl https://api.openai.com/v1/files/file-abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) file_object = client.files.retrieve( "file_id", ) print(file_object.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fileObject = await client.files.retrieve('file_id'); console.log(fileObject.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fileObject, err := client.Files.Get(context.TODO(), "file_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fileObject.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.files.FileObject; import com.openai.models.files.FileRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileObject fileObject = client.files().retrieve("file_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") file_object = openai.files.retrieve("file_id") puts(file_object) #### description Returns information about a specific file. ## /files/{file_id}/content ### get #### operationId downloadFile #### tags - Files #### summary Retrieve file content #### 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 ######### type string #### x-oaiMeta ##### name Retrieve file content ##### group files ##### returns The file content. ##### examples ###### response ###### request ####### curl curl https://api.openai.com/v1/files/file-abc123/content \ -H "Authorization: Bearer $OPENAI_API_KEY" > file.jsonl ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) response = client.files.content( "file_id", ) print(response) content = response.read() print(content) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.files.content('file_id'); console.log(response); const content = await response.blob(); console.log(content); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Files.Content(context.TODO(), "file_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.core.http.HttpResponse; import com.openai.models.files.FileContentParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); HttpResponse response = client.files().content("file_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.files.content("file_id") puts(response) #### description Returns the contents of the specified file. ## /fine_tuning/alpha/graders/run ### post #### operationId runGrader #### tags - Fine-tuning #### summary Run grader #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/RunGraderRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/RunGraderResponse #### x-oaiMeta ##### name Run grader ##### beta true ##### group graders ##### returns The results from the grader run. ##### examples ###### response { "reward": 1.0, "metadata": { "name": "Example score model grader", "type": "score_model", "errors": { "formula_parse_error": false, "sample_parse_error": false, "truncated_observation_error": false, "unresponsive_reward_error": false, "invalid_variable_error": false, "other_error": false, "python_grader_server_error": false, "python_grader_server_error_type": null, "python_grader_runtime_error": false, "python_grader_runtime_error_details": null, "model_grader_server_error": false, "model_grader_refusal_error": false, "model_grader_parse_error": false, "model_grader_server_error_details": null }, "execution_time": 4.365238428115845, "scores": {}, "token_usage": { "prompt_tokens": 190, "total_tokens": 324, "completion_tokens": 134, "cached_tokens": 0 }, "sampled_model_name": "gpt-4o-2024-08-06" }, "sub_rewards": {}, "model_grader_token_usage_per_model": { "gpt-4o-2024-08-06": { "prompt_tokens": 190, "total_tokens": 324, "completion_tokens": 134, "cached_tokens": 0 } } } ###### request ####### curl curl -X POST https://api.openai.com/v1/fine_tuning/alpha/graders/run \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "grader": { "type": "score_model", "name": "Example score model grader", "input": [ { "role": "user", "content": "Score how close the reference answer is to the model answer. Score 1.0 if they are the same and 0.0 if they are different. Return just a floating point score\n\nReference answer: {{item.reference_answer}}\n\nModel answer: {{sample.output_text}}" } ], "model": "gpt-4o-2024-08-06", "sampling_params": { "temperature": 1, "top_p": 1, "seed": 42 } }, "item": { "reference_answer": "fuzzy wuzzy was a bear" }, "model_sample": "fuzzy wuzzy was a bear" }' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.fineTuning.alpha.graders.run({ grader: { input: 'input', name: 'name', operation: 'eq', reference: 'reference', type: 'string_check' }, model_sample: 'model_sample', }); console.log(response.metadata); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) response = client.fine_tuning.alpha.graders.run( grader={ "input": "input", "name": "name", "operation": "eq", "reference": "reference", "type": "string_check", }, model_sample="model_sample", ) print(response.metadata) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.FineTuning.Alpha.Graders.Run(context.TODO(), openai.FineTuningAlphaGraderRunParams{ Grader: openai.FineTuningAlphaGraderRunParamsGraderUnion{ OfStringCheck: &openai.StringCheckGraderParam{ Input: "input", Name: "name", Operation: openai.StringCheckGraderOperationEq, Reference: "reference", }, }, ModelSample: "model_sample", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.Metadata) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.alpha.graders.GraderRunParams; import com.openai.models.finetuning.alpha.graders.GraderRunResponse; import com.openai.models.graders.gradermodels.StringCheckGrader; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); GraderRunParams params = GraderRunParams.builder() .grader(StringCheckGrader.builder() .input("input") .name("name") .operation(StringCheckGrader.Operation.EQ) .reference("reference") .build()) .modelSample("model_sample") .build(); GraderRunResponse response = client.fineTuning().alpha().graders().run(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.fine_tuning.alpha.graders.run( grader: {input: "input", name: "name", operation: :eq, reference: "reference", type: :string_check}, model_sample: "model_sample" ) puts(response) #### description Run a grader. ## /fine_tuning/alpha/graders/validate ### post #### operationId validateGrader #### tags - Fine-tuning #### summary Validate grader #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ValidateGraderRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ValidateGraderResponse #### x-oaiMeta ##### name Validate grader ##### beta true ##### group graders ##### returns The validated grader object. ##### examples ###### response { "grader": { "type": "string_check", "name": "Example string check grader", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "operation": "eq" } } ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/alpha/graders/validate \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "grader": { "type": "string_check", "name": "Example string check grader", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "operation": "eq" } }' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.fineTuning.alpha.graders.validate({ grader: { input: 'input', name: 'name', operation: 'eq', reference: 'reference', type: 'string_check' }, }); console.log(response.grader); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) response = client.fine_tuning.alpha.graders.validate( grader={ "input": "input", "name": "name", "operation": "eq", "reference": "reference", "type": "string_check", }, ) print(response.grader) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.FineTuning.Alpha.Graders.Validate(context.TODO(), openai.FineTuningAlphaGraderValidateParams{ Grader: openai.FineTuningAlphaGraderValidateParamsGraderUnion{ OfStringCheckGrader: &openai.StringCheckGraderParam{ Input: "input", Name: "name", Operation: openai.StringCheckGraderOperationEq, Reference: "reference", }, }, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.Grader) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.alpha.graders.GraderValidateParams; import com.openai.models.finetuning.alpha.graders.GraderValidateResponse; import com.openai.models.graders.gradermodels.StringCheckGrader; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); GraderValidateParams params = GraderValidateParams.builder() .grader(StringCheckGrader.builder() .input("input") .name("name") .operation(StringCheckGrader.Operation.EQ) .reference("reference") .build()) .build(); GraderValidateResponse response = client.fineTuning().alpha().graders().validate(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.fine_tuning.alpha.graders.validate( grader: {input: "input", name: "name", operation: :eq, reference: "reference", type: :string_check} ) puts(response) #### description Validate a grader. ## /fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions ### get #### operationId listFineTuningCheckpointPermissions #### tags - Fine-tuning #### summary List checkpoint permissions #### parameters ##### in path ##### name fine_tuned_model_checkpoint ##### required true ##### schema ###### type string ###### example ft-AF1WoRqd3aJAHsqc9NY7iL8F ##### description The ID of the fine-tuned model checkpoint to get permissions for. ##### name project_id ##### in query ##### description The ID of the project to get permissions for. ##### required false ##### schema ###### type string ##### name after ##### in query ##### description Identifier for the last permission ID from the previous pagination request. ##### required false ##### schema ###### type string ##### name limit ##### in query ##### description Number of permissions to retrieve. ##### required false ##### schema ###### type integer ###### default 10 ##### name order ##### in query ##### description The order in which to retrieve permissions. ##### required false ##### schema ###### type string ###### enum - ascending - descending ###### default descending #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListFineTuningCheckpointPermissionResponse #### x-oaiMeta ##### name List checkpoint permissions ##### group fine-tuning ##### returns A list of fine-tuned model checkpoint [permission objects](https://platform.openai.com/docs/api-reference/fine-tuning/permission-object) for a fine-tuned model checkpoint. ##### examples ###### response { "object": "list", "data": [ { "object": "checkpoint.permission", "id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "created_at": 1721764867, "project_id": "proj_abGMw1llN8IrBb6SvvY5A1iH" }, { "object": "checkpoint.permission", "id": "cp_enQCFmOTGj3syEpYVhBRLTSy", "created_at": 1721764800, "project_id": "proj_iqGMw1llN8IrBb6SvvY5A1oF" }, ], "first_id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "last_id": "cp_enQCFmOTGj3syEpYVhBRLTSy", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const permission = await client.fineTuning.checkpoints.permissions.retrieve('ft-AF1WoRqd3aJAHsqc9NY7iL8F'); console.log(permission.first_id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) permission = client.fine_tuning.checkpoints.permissions.retrieve( fine_tuned_model_checkpoint="ft-AF1WoRqd3aJAHsqc9NY7iL8F", ) print(permission.first_id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) permission, err := client.FineTuning.Checkpoints.Permissions.Get( context.TODO(), "ft-AF1WoRqd3aJAHsqc9NY7iL8F", openai.FineTuningCheckpointPermissionGetParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", permission.FirstID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.checkpoints.permissions.PermissionRetrieveParams; import com.openai.models.finetuning.checkpoints.permissions.PermissionRetrieveResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); PermissionRetrieveResponse permission = client.fineTuning().checkpoints().permissions().retrieve("ft-AF1WoRqd3aJAHsqc9NY7iL8F"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") permission = openai.fine_tuning.checkpoints.permissions.retrieve("ft-AF1WoRqd3aJAHsqc9NY7iL8F") puts(permission) #### description **NOTE:** This endpoint requires an [admin API key](../admin-api-keys). Organization owners can use this endpoint to view all permissions for a fine-tuned model checkpoint. ### post #### operationId createFineTuningCheckpointPermission #### tags - Fine-tuning #### summary Create checkpoint permissions #### parameters ##### in path ##### name fine_tuned_model_checkpoint ##### required true ##### schema ###### type string ###### example ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd ##### description The ID of the fine-tuned model checkpoint to create a permission for. #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateFineTuningCheckpointPermissionRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListFineTuningCheckpointPermissionResponse #### x-oaiMeta ##### name Create checkpoint permissions ##### group fine-tuning ##### returns A list of fine-tuned model checkpoint [permission objects](https://platform.openai.com/docs/api-reference/fine-tuning/permission-object) for a fine-tuned model checkpoint. ##### examples ###### response { "object": "list", "data": [ { "object": "checkpoint.permission", "id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "created_at": 1721764867, "project_id": "proj_abGMw1llN8IrBb6SvvY5A1iH" } ], "first_id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "last_id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions \ -H "Authorization: Bearer $OPENAI_API_KEY" -d '{"project_ids": ["proj_abGMw1llN8IrBb6SvvY5A1iH"]}' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const permissionCreateResponse of client.fineTuning.checkpoints.permissions.create( 'ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd', { project_ids: ['string'] }, )) { console.log(permissionCreateResponse.id); } ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.fine_tuning.checkpoints.permissions.create( fine_tuned_model_checkpoint="ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd", project_ids=["string"], ) page = page.data[0] print(page.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.FineTuning.Checkpoints.Permissions.New( context.TODO(), "ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd", openai.FineTuningCheckpointPermissionNewParams{ ProjectIDs: []string{"string"}, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.checkpoints.permissions.PermissionCreatePage; import com.openai.models.finetuning.checkpoints.permissions.PermissionCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); PermissionCreateParams params = PermissionCreateParams.builder() .fineTunedModelCheckpoint("ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd") .addProjectId("string") .build(); PermissionCreatePage page = client.fineTuning().checkpoints().permissions().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.fine_tuning.checkpoints.permissions.create( "ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd", project_ids: ["string"] ) puts(page) #### description **NOTE:** Calling this endpoint requires an [admin API key](../admin-api-keys). This enables organization owners to share fine-tuned models with other projects in their organization. ## /fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions/{permission_id} ### delete #### operationId deleteFineTuningCheckpointPermission #### tags - Fine-tuning #### summary Delete checkpoint permission #### parameters ##### in path ##### name fine_tuned_model_checkpoint ##### required true ##### schema ###### type string ###### example ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd ##### description The ID of the fine-tuned model checkpoint to delete a permission for. ##### in path ##### name permission_id ##### required true ##### schema ###### type string ###### example cp_zc4Q7MP6XxulcVzj4MZdwsAB ##### description The ID of the fine-tuned model checkpoint permission to delete. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/DeleteFineTuningCheckpointPermissionResponse #### x-oaiMeta ##### name Delete checkpoint permission ##### group fine-tuning ##### returns The deletion status of the fine-tuned model checkpoint [permission object](https://platform.openai.com/docs/api-reference/fine-tuning/permission-object). ##### examples ###### response { "object": "checkpoint.permission", "id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "deleted": true } ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions/cp_zc4Q7MP6XxulcVzj4MZdwsAB \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const permission = await client.fineTuning.checkpoints.permissions.delete('cp_zc4Q7MP6XxulcVzj4MZdwsAB', { fine_tuned_model_checkpoint: 'ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd', }); console.log(permission.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) permission = client.fine_tuning.checkpoints.permissions.delete( permission_id="cp_zc4Q7MP6XxulcVzj4MZdwsAB", fine_tuned_model_checkpoint="ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd", ) print(permission.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) permission, err := client.FineTuning.Checkpoints.Permissions.Delete( context.TODO(), "ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd", "cp_zc4Q7MP6XxulcVzj4MZdwsAB", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", permission.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.checkpoints.permissions.PermissionDeleteParams; import com.openai.models.finetuning.checkpoints.permissions.PermissionDeleteResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); PermissionDeleteParams params = PermissionDeleteParams.builder() .fineTunedModelCheckpoint("ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd") .permissionId("cp_zc4Q7MP6XxulcVzj4MZdwsAB") .build(); PermissionDeleteResponse permission = client.fineTuning().checkpoints().permissions().delete(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") permission = openai.fine_tuning.checkpoints.permissions.delete( "cp_zc4Q7MP6XxulcVzj4MZdwsAB", fine_tuned_model_checkpoint: "ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd" ) puts(permission) #### description **NOTE:** This endpoint requires an [admin API key](../admin-api-keys). Organization owners can use this endpoint to delete a permission for a fine-tuned model checkpoint. ## /fine_tuning/jobs ### post #### operationId createFineTuningJob #### tags - Fine-tuning #### summary Create fine-tuning job #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateFineTuningJobRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/FineTuningJob #### x-oaiMeta ##### name Create fine-tuning job ##### group fine-tuning ##### returns A [fine-tuning.job](https://platform.openai.com/docs/api-reference/fine-tuning/object) object. ##### examples ###### title Default ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-BK7bzQj3FfZFXr7DbL6xJwfo", "model": "gpt-4o-mini" }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) fine_tuning_job = client.fine_tuning.jobs.create( model="gpt-4o-mini", training_file="file-abc123", ) print(fine_tuning_job.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fineTuningJob = await client.fineTuning.jobs.create({ model: 'gpt-4o-mini', training_file: 'file-abc123', }); console.log(fineTuningJob.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fineTuningJob, err := client.FineTuning.Jobs.New(context.TODO(), openai.FineTuningJobNewParams{ Model: openai.FineTuningJobNewParamsModelBabbage002, TrainingFile: "file-abc123", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fineTuningJob.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.FineTuningJob; import com.openai.models.finetuning.jobs.JobCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); JobCreateParams params = JobCreateParams.builder() .model(JobCreateParams.Model.BABBAGE_002) .trainingFile("file-abc123") .build(); FineTuningJob fineTuningJob = client.fineTuning().jobs().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") fine_tuning_job = openai.fine_tuning.jobs.create(model: :"babbage-002", training_file: "file-abc123") puts(fine_tuning_job) ###### response { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-4o-mini-2024-07-18", "created_at": 1721764800, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "queued", "validation_file": null, "training_file": "file-abc123", "method": { "type": "supervised", "supervised": { "hyperparameters": { "batch_size": "auto", "learning_rate_multiplier": "auto", "n_epochs": "auto", } } }, "metadata": null } ###### title Epochs ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-abc123", "model": "gpt-4o-mini", "method": { "type": "supervised", "supervised": { "hyperparameters": { "n_epochs": 2 } } } }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) fine_tuning_job = client.fine_tuning.jobs.create( model="gpt-4o-mini", training_file="file-abc123", ) print(fine_tuning_job.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fineTuningJob = await client.fineTuning.jobs.create({ model: 'gpt-4o-mini', training_file: 'file-abc123', }); console.log(fineTuningJob.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fineTuningJob, err := client.FineTuning.Jobs.New(context.TODO(), openai.FineTuningJobNewParams{ Model: openai.FineTuningJobNewParamsModelBabbage002, TrainingFile: "file-abc123", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fineTuningJob.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.FineTuningJob; import com.openai.models.finetuning.jobs.JobCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); JobCreateParams params = JobCreateParams.builder() .model(JobCreateParams.Model.BABBAGE_002) .trainingFile("file-abc123") .build(); FineTuningJob fineTuningJob = client.fineTuning().jobs().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") fine_tuning_job = openai.fine_tuning.jobs.create(model: :"babbage-002", training_file: "file-abc123") puts(fine_tuning_job) ###### response { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-4o-mini", "created_at": 1721764800, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "queued", "validation_file": null, "training_file": "file-abc123", "hyperparameters": { "batch_size": "auto", "learning_rate_multiplier": "auto", "n_epochs": 2 }, "method": { "type": "supervised", "supervised": { "hyperparameters": { "batch_size": "auto", "learning_rate_multiplier": "auto", "n_epochs": 2 } } }, "metadata": null, "error": { "code": null, "message": null, "param": null }, "finished_at": null, "seed": 683058546, "trained_tokens": null, "estimated_finish": null, "integrations": [], "user_provided_suffix": null, "usage_metrics": null, "shared_with_openai": false } ###### title DPO ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-abc123", "validation_file": "file-abc123", "model": "gpt-4o-mini", "method": { "type": "dpo", "dpo": { "hyperparameters": { "beta": 0.1 } } } }' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fineTuningJob = await client.fineTuning.jobs.create({ model: 'gpt-4o-mini', training_file: 'file-abc123', }); console.log(fineTuningJob.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) fine_tuning_job = client.fine_tuning.jobs.create( model="gpt-4o-mini", training_file="file-abc123", ) print(fine_tuning_job.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fineTuningJob, err := client.FineTuning.Jobs.New(context.TODO(), openai.FineTuningJobNewParams{ Model: openai.FineTuningJobNewParamsModelBabbage002, TrainingFile: "file-abc123", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fineTuningJob.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.FineTuningJob; import com.openai.models.finetuning.jobs.JobCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); JobCreateParams params = JobCreateParams.builder() .model(JobCreateParams.Model.BABBAGE_002) .trainingFile("file-abc123") .build(); FineTuningJob fineTuningJob = client.fineTuning().jobs().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") fine_tuning_job = openai.fine_tuning.jobs.create(model: :"babbage-002", training_file: "file-abc123") puts(fine_tuning_job) ###### python from openai import OpenAI from openai.types.fine_tuning import DpoMethod, DpoHyperparameters client = OpenAI() client.fine_tuning.jobs.create( training_file="file-abc", validation_file="file-123", model="gpt-4o-mini", method={ "type": "dpo", "dpo": DpoMethod( hyperparameters=DpoHyperparameters(beta=0.1) ) } ) ###### response { "object": "fine_tuning.job", "id": "ftjob-abc", "model": "gpt-4o-mini", "created_at": 1746130590, "fine_tuned_model": null, "organization_id": "org-abc", "result_files": [], "status": "queued", "validation_file": "file-123", "training_file": "file-abc", "method": { "type": "dpo", "dpo": { "hyperparameters": { "beta": 0.1, "batch_size": "auto", "learning_rate_multiplier": "auto", "n_epochs": "auto" } } }, "metadata": null, "error": { "code": null, "message": null, "param": null }, "finished_at": null, "hyperparameters": null, "seed": 1036326793, "estimated_finish": null, "integrations": [], "user_provided_suffix": null, "usage_metrics": null, "shared_with_openai": false } ###### title Reinforcement ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-abc", "validation_file": "file-123", "model": "o4-mini", "method": { "type": "reinforcement", "reinforcement": { "grader": { "type": "string_check", "name": "Example string check grader", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "operation": "eq" }, "hyperparameters": { "reasoning_effort": "medium" } } } }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) fine_tuning_job = client.fine_tuning.jobs.create( model="gpt-4o-mini", training_file="file-abc123", ) print(fine_tuning_job.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fineTuningJob = await client.fineTuning.jobs.create({ model: 'gpt-4o-mini', training_file: 'file-abc123', }); console.log(fineTuningJob.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fineTuningJob, err := client.FineTuning.Jobs.New(context.TODO(), openai.FineTuningJobNewParams{ Model: openai.FineTuningJobNewParamsModelBabbage002, TrainingFile: "file-abc123", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fineTuningJob.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.FineTuningJob; import com.openai.models.finetuning.jobs.JobCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); JobCreateParams params = JobCreateParams.builder() .model(JobCreateParams.Model.BABBAGE_002) .trainingFile("file-abc123") .build(); FineTuningJob fineTuningJob = client.fineTuning().jobs().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") fine_tuning_job = openai.fine_tuning.jobs.create(model: :"babbage-002", training_file: "file-abc123") puts(fine_tuning_job) ###### response { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "o4-mini", "created_at": 1721764800, "finished_at": null, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "validating_files", "validation_file": "file-123", "training_file": "file-abc", "trained_tokens": null, "error": {}, "user_provided_suffix": null, "seed": 950189191, "estimated_finish": null, "integrations": [], "method": { "type": "reinforcement", "reinforcement": { "hyperparameters": { "batch_size": "auto", "learning_rate_multiplier": "auto", "n_epochs": "auto", "eval_interval": "auto", "eval_samples": "auto", "compute_multiplier": "auto", "reasoning_effort": "medium" }, "grader": { "type": "string_check", "name": "Example string check grader", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "operation": "eq" }, "response_format": null } }, "metadata": null, "usage_metrics": null, "shared_with_openai": false } ###### title Validation file ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-abc123", "validation_file": "file-abc123", "model": "gpt-4o-mini" }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) fine_tuning_job = client.fine_tuning.jobs.create( model="gpt-4o-mini", training_file="file-abc123", ) print(fine_tuning_job.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fineTuningJob = await client.fineTuning.jobs.create({ model: 'gpt-4o-mini', training_file: 'file-abc123', }); console.log(fineTuningJob.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fineTuningJob, err := client.FineTuning.Jobs.New(context.TODO(), openai.FineTuningJobNewParams{ Model: openai.FineTuningJobNewParamsModelBabbage002, TrainingFile: "file-abc123", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fineTuningJob.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.FineTuningJob; import com.openai.models.finetuning.jobs.JobCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); JobCreateParams params = JobCreateParams.builder() .model(JobCreateParams.Model.BABBAGE_002) .trainingFile("file-abc123") .build(); FineTuningJob fineTuningJob = client.fineTuning().jobs().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") fine_tuning_job = openai.fine_tuning.jobs.create(model: :"babbage-002", training_file: "file-abc123") puts(fine_tuning_job) ###### response { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-4o-mini-2024-07-18", "created_at": 1721764800, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "queued", "validation_file": "file-abc123", "training_file": "file-abc123", "method": { "type": "supervised", "supervised": { "hyperparameters": { "batch_size": "auto", "learning_rate_multiplier": "auto", "n_epochs": "auto", } } }, "metadata": null } ###### title W&B Integration ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-abc123", "validation_file": "file-abc123", "model": "gpt-4o-mini", "integrations": [ { "type": "wandb", "wandb": { "project": "my-wandb-project", "name": "ft-run-display-name" "tags": [ "first-experiment", "v2" ] } } ] }' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fineTuningJob = await client.fineTuning.jobs.create({ model: 'gpt-4o-mini', training_file: 'file-abc123', }); console.log(fineTuningJob.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) fine_tuning_job = client.fine_tuning.jobs.create( model="gpt-4o-mini", training_file="file-abc123", ) print(fine_tuning_job.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fineTuningJob, err := client.FineTuning.Jobs.New(context.TODO(), openai.FineTuningJobNewParams{ Model: openai.FineTuningJobNewParamsModelBabbage002, TrainingFile: "file-abc123", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fineTuningJob.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.FineTuningJob; import com.openai.models.finetuning.jobs.JobCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); JobCreateParams params = JobCreateParams.builder() .model(JobCreateParams.Model.BABBAGE_002) .trainingFile("file-abc123") .build(); FineTuningJob fineTuningJob = client.fineTuning().jobs().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") fine_tuning_job = openai.fine_tuning.jobs.create(model: :"babbage-002", training_file: "file-abc123") puts(fine_tuning_job) ###### response { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-4o-mini-2024-07-18", "created_at": 1721764800, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "queued", "validation_file": "file-abc123", "training_file": "file-abc123", "integrations": [ { "type": "wandb", "wandb": { "project": "my-wandb-project", "entity": None, "run_id": "ftjob-abc123" } } ], "method": { "type": "supervised", "supervised": { "hyperparameters": { "batch_size": "auto", "learning_rate_multiplier": "auto", "n_epochs": "auto", } } }, "metadata": null } #### description Creates a fine-tuning job which begins the process of creating a new model from a given dataset. Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete. [Learn more about fine-tuning](https://platform.openai.com/docs/guides/model-optimization) ### get #### operationId listPaginatedFineTuningJobs #### tags - Fine-tuning #### summary List fine-tuning jobs #### parameters ##### name after ##### in query ##### description Identifier for the last job from the previous pagination request. ##### required false ##### schema ###### type string ##### name limit ##### in query ##### description Number of fine-tuning jobs to retrieve. ##### required false ##### 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 ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListPaginatedFineTuningJobsResponse #### x-oaiMeta ##### name List fine-tuning jobs ##### group fine-tuning ##### returns A list of paginated [fine-tuning job](https://platform.openai.com/docs/api-reference/fine-tuning/object) objects. ##### examples ###### response { "object": "list", "data": [ { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-4o-mini-2024-07-18", "created_at": 1721764800, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "queued", "validation_file": null, "training_file": "file-abc123", "metadata": { "key": "value" } }, { ... }, { ... } ], "has_more": true } ###### request ####### 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 client = OpenAI( api_key="My API Key", ) page = client.fine_tuning.jobs.list() page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const fineTuningJob of client.fineTuning.jobs.list()) { console.log(fineTuningJob.id); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.FineTuning.Jobs.List(context.TODO(), openai.FineTuningJobListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.JobListPage; import com.openai.models.finetuning.jobs.JobListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); JobListPage page = client.fineTuning().jobs().list(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.fine_tuning.jobs.list puts(page) #### description List your organization's fine-tuning jobs ## /fine_tuning/jobs/{fine_tuning_job_id} ### get #### operationId retrieveFineTuningJob #### tags - Fine-tuning #### summary Retrieve fine-tuning job #### parameters ##### in path ##### name fine_tuning_job_id ##### required true ##### schema ###### type string ###### example ft-AF1WoRqd3aJAHsqc9NY7iL8F ##### description The ID of the fine-tuning job. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/FineTuningJob #### x-oaiMeta ##### name Retrieve fine-tuning job ##### group fine-tuning ##### returns The [fine-tuning](https://platform.openai.com/docs/api-reference/fine-tuning/object) object with the given ID. ##### examples ###### response { "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 } } } } ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/jobs/ft-AF1WoRqd3aJAHsqc9NY7iL8F \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) fine_tuning_job = client.fine_tuning.jobs.retrieve( "ft-AF1WoRqd3aJAHsqc9NY7iL8F", ) print(fine_tuning_job.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fineTuningJob = await client.fineTuning.jobs.retrieve('ft-AF1WoRqd3aJAHsqc9NY7iL8F'); console.log(fineTuningJob.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fineTuningJob, err := client.FineTuning.Jobs.Get(context.TODO(), "ft-AF1WoRqd3aJAHsqc9NY7iL8F") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fineTuningJob.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.FineTuningJob; import com.openai.models.finetuning.jobs.JobRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FineTuningJob fineTuningJob = client.fineTuning().jobs().retrieve("ft-AF1WoRqd3aJAHsqc9NY7iL8F"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") fine_tuning_job = openai.fine_tuning.jobs.retrieve("ft-AF1WoRqd3aJAHsqc9NY7iL8F") puts(fine_tuning_job) #### description Get info about a fine-tuning job. [Learn more about fine-tuning](https://platform.openai.com/docs/guides/model-optimization) ## /fine_tuning/jobs/{fine_tuning_job_id}/cancel ### post #### operationId cancelFineTuningJob #### tags - Fine-tuning #### summary Cancel fine-tuning #### parameters ##### in path ##### name fine_tuning_job_id ##### required true ##### schema ###### type string ###### example ft-AF1WoRqd3aJAHsqc9NY7iL8F ##### description The ID of the fine-tuning job to cancel. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/FineTuningJob #### x-oaiMeta ##### name Cancel fine-tuning ##### group fine-tuning ##### returns The cancelled [fine-tuning](https://platform.openai.com/docs/api-reference/fine-tuning/object) object. ##### examples ###### response { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-4o-mini-2024-07-18", "created_at": 1721764800, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "cancelled", "validation_file": "file-abc123", "training_file": "file-abc123" } ###### request ####### curl curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/cancel \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) fine_tuning_job = client.fine_tuning.jobs.cancel( "ft-AF1WoRqd3aJAHsqc9NY7iL8F", ) print(fine_tuning_job.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fineTuningJob = await client.fineTuning.jobs.cancel('ft-AF1WoRqd3aJAHsqc9NY7iL8F'); console.log(fineTuningJob.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fineTuningJob, err := client.FineTuning.Jobs.Cancel(context.TODO(), "ft-AF1WoRqd3aJAHsqc9NY7iL8F") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fineTuningJob.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.FineTuningJob; import com.openai.models.finetuning.jobs.JobCancelParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FineTuningJob fineTuningJob = client.fineTuning().jobs().cancel("ft-AF1WoRqd3aJAHsqc9NY7iL8F"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") fine_tuning_job = openai.fine_tuning.jobs.cancel("ft-AF1WoRqd3aJAHsqc9NY7iL8F") puts(fine_tuning_job) #### description Immediately cancel a fine-tune job. ## /fine_tuning/jobs/{fine_tuning_job_id}/checkpoints ### get #### operationId listFineTuningJobCheckpoints #### tags - Fine-tuning #### summary List fine-tuning checkpoints #### parameters ##### in path ##### name fine_tuning_job_id ##### required true ##### schema ###### type string ###### example ft-AF1WoRqd3aJAHsqc9NY7iL8F ##### description The ID of the fine-tuning job to get checkpoints for. ##### name after ##### in query ##### description Identifier for the last checkpoint ID from the previous pagination request. ##### required false ##### schema ###### type string ##### name limit ##### in query ##### description Number of checkpoints to retrieve. ##### required false ##### schema ###### type integer ###### default 10 #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListFineTuningJobCheckpointsResponse #### x-oaiMeta ##### name List fine-tuning checkpoints ##### group fine-tuning ##### returns A list of fine-tuning [checkpoint objects](https://platform.openai.com/docs/api-reference/fine-tuning/checkpoint-object) for a fine-tuning job. ##### examples ###### response { "object": "list", "data": [ { "object": "fine_tuning.job.checkpoint", "id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB", "created_at": 1721764867, "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:96olL566:ckpt-step-2000", "metrics": { "full_valid_loss": 0.134, "full_valid_mean_token_accuracy": 0.874 }, "fine_tuning_job_id": "ftjob-abc123", "step_number": 2000 }, { "object": "fine_tuning.job.checkpoint", "id": "ftckpt_enQCFmOTGj3syEpYVhBRLTSy", "created_at": 1721764800, "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:7q8mpxmy:ckpt-step-1000", "metrics": { "full_valid_loss": 0.167, "full_valid_mean_token_accuracy": 0.781 }, "fine_tuning_job_id": "ftjob-abc123", "step_number": 1000 } ], "first_id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB", "last_id": "ftckpt_enQCFmOTGj3syEpYVhBRLTSy", "has_more": true } ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/checkpoints \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const fineTuningJobCheckpoint of client.fineTuning.jobs.checkpoints.list( 'ft-AF1WoRqd3aJAHsqc9NY7iL8F', )) { console.log(fineTuningJobCheckpoint.id); } ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.fine_tuning.jobs.checkpoints.list( fine_tuning_job_id="ft-AF1WoRqd3aJAHsqc9NY7iL8F", ) page = page.data[0] print(page.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.FineTuning.Jobs.Checkpoints.List( context.TODO(), "ft-AF1WoRqd3aJAHsqc9NY7iL8F", openai.FineTuningJobCheckpointListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.checkpoints.CheckpointListPage; import com.openai.models.finetuning.jobs.checkpoints.CheckpointListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); CheckpointListPage page = client.fineTuning().jobs().checkpoints().list("ft-AF1WoRqd3aJAHsqc9NY7iL8F"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.fine_tuning.jobs.checkpoints.list("ft-AF1WoRqd3aJAHsqc9NY7iL8F") puts(page) #### description List checkpoints for a fine-tuning job. ## /fine_tuning/jobs/{fine_tuning_job_id}/events ### get #### operationId listFineTuningEvents #### tags - Fine-tuning #### summary List fine-tuning events #### parameters ##### in path ##### name fine_tuning_job_id ##### required true ##### schema ###### type string ###### example ft-AF1WoRqd3aJAHsqc9NY7iL8F ##### description The ID of the fine-tuning job to get events for. ##### name after ##### in query ##### description Identifier for the last event from the previous pagination request. ##### required false ##### schema ###### type string ##### name limit ##### in query ##### description Number of events to retrieve. ##### required false ##### schema ###### type integer ###### default 20 #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListFineTuningJobEventsResponse #### x-oaiMeta ##### name List fine-tuning events ##### group fine-tuning ##### returns A list of fine-tuning event objects. ##### examples ###### response { "object": "list", "data": [ { "object": "fine_tuning.job.event", "id": "ft-event-ddTJfwuMVpfLXseO0Am0Gqjm", "created_at": 1721764800, "level": "info", "message": "Fine tuning job successfully completed", "data": null, "type": "message" }, { "object": "fine_tuning.job.event", "id": "ft-event-tyiGuB72evQncpH87xe505Sv", "created_at": 1721764800, "level": "info", "message": "New fine-tuned model created: ft:gpt-4o-mini:openai::7p4lURel", "data": null, "type": "message" } ], "has_more": true } ###### request ####### curl curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/events \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.fine_tuning.jobs.list_events( fine_tuning_job_id="ft-AF1WoRqd3aJAHsqc9NY7iL8F", ) page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const fineTuningJobEvent of client.fineTuning.jobs.listEvents('ft-AF1WoRqd3aJAHsqc9NY7iL8F')) { console.log(fineTuningJobEvent.id); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.FineTuning.Jobs.ListEvents( context.TODO(), "ft-AF1WoRqd3aJAHsqc9NY7iL8F", openai.FineTuningJobListEventsParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.JobListEventsPage; import com.openai.models.finetuning.jobs.JobListEventsParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); JobListEventsPage page = client.fineTuning().jobs().listEvents("ft-AF1WoRqd3aJAHsqc9NY7iL8F"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.fine_tuning.jobs.list_events("ft-AF1WoRqd3aJAHsqc9NY7iL8F") puts(page) #### description Get status updates for a fine-tuning job. ## /fine_tuning/jobs/{fine_tuning_job_id}/pause ### post #### operationId pauseFineTuningJob #### tags - Fine-tuning #### summary Pause fine-tuning #### parameters ##### in path ##### name fine_tuning_job_id ##### required true ##### schema ###### type string ###### example ft-AF1WoRqd3aJAHsqc9NY7iL8F ##### description The ID of the fine-tuning job to pause. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/FineTuningJob #### x-oaiMeta ##### name Pause fine-tuning ##### group fine-tuning ##### returns The paused [fine-tuning](https://platform.openai.com/docs/api-reference/fine-tuning/object) object. ##### examples ###### response { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-4o-mini-2024-07-18", "created_at": 1721764800, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "paused", "validation_file": "file-abc123", "training_file": "file-abc123" } ###### request ####### curl curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/pause \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) fine_tuning_job = client.fine_tuning.jobs.pause( "ft-AF1WoRqd3aJAHsqc9NY7iL8F", ) print(fine_tuning_job.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fineTuningJob = await client.fineTuning.jobs.pause('ft-AF1WoRqd3aJAHsqc9NY7iL8F'); console.log(fineTuningJob.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fineTuningJob, err := client.FineTuning.Jobs.Pause(context.TODO(), "ft-AF1WoRqd3aJAHsqc9NY7iL8F") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fineTuningJob.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.FineTuningJob; import com.openai.models.finetuning.jobs.JobPauseParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FineTuningJob fineTuningJob = client.fineTuning().jobs().pause("ft-AF1WoRqd3aJAHsqc9NY7iL8F"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") fine_tuning_job = openai.fine_tuning.jobs.pause("ft-AF1WoRqd3aJAHsqc9NY7iL8F") puts(fine_tuning_job) #### description Pause a fine-tune job. ## /fine_tuning/jobs/{fine_tuning_job_id}/resume ### post #### operationId resumeFineTuningJob #### tags - Fine-tuning #### summary Resume fine-tuning #### parameters ##### in path ##### name fine_tuning_job_id ##### required true ##### schema ###### type string ###### example ft-AF1WoRqd3aJAHsqc9NY7iL8F ##### description The ID of the fine-tuning job to resume. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/FineTuningJob #### x-oaiMeta ##### name Resume fine-tuning ##### group fine-tuning ##### returns The resumed [fine-tuning](https://platform.openai.com/docs/api-reference/fine-tuning/object) object. ##### examples ###### response { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-4o-mini-2024-07-18", "created_at": 1721764800, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "queued", "validation_file": "file-abc123", "training_file": "file-abc123" } ###### request ####### curl curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/resume \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) fine_tuning_job = client.fine_tuning.jobs.resume( "ft-AF1WoRqd3aJAHsqc9NY7iL8F", ) print(fine_tuning_job.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const fineTuningJob = await client.fineTuning.jobs.resume('ft-AF1WoRqd3aJAHsqc9NY7iL8F'); console.log(fineTuningJob.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) fineTuningJob, err := client.FineTuning.Jobs.Resume(context.TODO(), "ft-AF1WoRqd3aJAHsqc9NY7iL8F") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", fineTuningJob.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.finetuning.jobs.FineTuningJob; import com.openai.models.finetuning.jobs.JobResumeParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FineTuningJob fineTuningJob = client.fineTuning().jobs().resume("ft-AF1WoRqd3aJAHsqc9NY7iL8F"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") fine_tuning_job = openai.fine_tuning.jobs.resume("ft-AF1WoRqd3aJAHsqc9NY7iL8F") puts(fine_tuning_job) #### description Resume a fine-tune job. ## /images/edits ### post #### operationId createImageEdit #### tags - Images #### summary Create image edit #### requestBody ##### required true ##### content ###### multipart/form-data ####### schema ######## $ref #/components/schemas/CreateImageEditRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ImagesResponse ####### text/event-stream ######## schema ######### $ref #/components/schemas/ImageEditStreamEvent #### x-oaiMeta ##### name Create image edit ##### group images ##### returns Returns an [image](https://platform.openai.com/docs/api-reference/images/object) object. ##### examples ###### title Edit image ###### request ####### curl curl -s -D >(grep -i x-request-id >&2) \ -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \ -X POST "https://api.openai.com/v1/images/edits" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F "model=gpt-image-1" \ -F "image[]=@body-lotion.png" \ -F "image[]=@bath-bomb.png" \ -F "image[]=@incense-kit.png" \ -F "image[]=@soap.png" \ -F 'prompt=Create a lovely gift basket with these four items in it' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) images_response = client.images.edit( image=b"raw file contents", prompt="A cute baby sea otter wearing a beret", ) print(images_response) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const imagesResponse = await client.images.edit({ image: fs.createReadStream('path/to/file'), prompt: 'A cute baby sea otter wearing a beret', }); console.log(imagesResponse); ####### go package main import ( "bytes" "context" "fmt" "io" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) imagesResponse, err := client.Images.Edit(context.TODO(), openai.ImageEditParams{ Image: openai.ImageEditParamsImageUnion{ OfFile: io.Reader(bytes.NewBuffer([]byte("some file contents"))), }, Prompt: "A cute baby sea otter wearing a beret", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", imagesResponse) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.images.ImageEditParams; import com.openai.models.images.ImagesResponse; import java.io.ByteArrayInputStream; import java.io.InputStream; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ImageEditParams params = ImageEditParams.builder() .image(ByteArrayInputStream("some content".getBytes())) .prompt("A cute baby sea otter wearing a beret") .build(); ImagesResponse imagesResponse = client.images().edit(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") images_response = openai.images.edit(image: Pathname(__FILE__), prompt: "A cute baby sea otter wearing a beret") puts(images_response) ###### title Streaming ###### request ####### curl curl -s -N -X POST "https://api.openai.com/v1/images/edits" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F "model=gpt-image-1" \ -F "image[]=@body-lotion.png" \ -F "image[]=@bath-bomb.png" \ -F "image[]=@incense-kit.png" \ -F "image[]=@soap.png" \ -F 'prompt=Create a lovely gift basket with these four items in it' \ -F "stream=true" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) images_response = client.images.edit( image=b"raw file contents", prompt="A cute baby sea otter wearing a beret", ) print(images_response) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const imagesResponse = await client.images.edit({ image: fs.createReadStream('path/to/file'), prompt: 'A cute baby sea otter wearing a beret', }); console.log(imagesResponse); ####### go package main import ( "bytes" "context" "fmt" "io" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) imagesResponse, err := client.Images.Edit(context.TODO(), openai.ImageEditParams{ Image: openai.ImageEditParamsImageUnion{ OfFile: io.Reader(bytes.NewBuffer([]byte("some file contents"))), }, Prompt: "A cute baby sea otter wearing a beret", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", imagesResponse) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.images.ImageEditParams; import com.openai.models.images.ImagesResponse; import java.io.ByteArrayInputStream; import java.io.InputStream; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ImageEditParams params = ImageEditParams.builder() .image(ByteArrayInputStream("some content".getBytes())) .prompt("A cute baby sea otter wearing a beret") .build(); ImagesResponse imagesResponse = client.images().edit(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") images_response = openai.images.edit(image: Pathname(__FILE__), prompt: "A cute baby sea otter wearing a beret") puts(images_response) ###### response event: image_edit.partial_image data: {"type":"image_edit.partial_image","b64_json":"...","partial_image_index":0} event: image_edit.completed data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":100,"input_tokens":50,"output_tokens":50,"input_tokens_details":{"text_tokens":10,"image_tokens":40}}} #### description Creates an edited or extended image given one or more source images and a prompt. This endpoint only supports `gpt-image-1` and `dall-e-2`. ## /images/generations ### post #### operationId createImage #### tags - Images #### summary Create image #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateImageRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ImagesResponse ####### text/event-stream ######## schema ######### $ref #/components/schemas/ImageGenStreamEvent #### x-oaiMeta ##### name Create image ##### group images ##### returns Returns an [image](https://platform.openai.com/docs/api-reference/images/object) object. ##### examples ###### title Generate image ###### request ####### curl curl https://api.openai.com/v1/images/generations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-image-1", "prompt": "A cute baby sea otter", "n": 1, "size": "1024x1024" }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) images_response = client.images.generate( prompt="A cute baby sea otter", ) print(images_response) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const imagesResponse = await client.images.generate({ prompt: 'A cute baby sea otter' }); console.log(imagesResponse); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) imagesResponse, err := client.Images.Generate(context.TODO(), openai.ImageGenerateParams{ Prompt: "A cute baby sea otter", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", imagesResponse) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.images.ImageGenerateParams; import com.openai.models.images.ImagesResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ImageGenerateParams params = ImageGenerateParams.builder() .prompt("A cute baby sea otter") .build(); ImagesResponse imagesResponse = client.images().generate(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") images_response = openai.images.generate(prompt: "A cute baby sea otter") puts(images_response) ###### response { "created": 1713833628, "data": [ { "b64_json": "..." } ], "usage": { "total_tokens": 100, "input_tokens": 50, "output_tokens": 50, "input_tokens_details": { "text_tokens": 10, "image_tokens": 40 } } } ###### title Streaming ###### request ####### curl curl https://api.openai.com/v1/images/generations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-image-1", "prompt": "A cute baby sea otter", "n": 1, "size": "1024x1024", "stream": true }' \ --no-buffer ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) images_response = client.images.generate( prompt="A cute baby sea otter", ) print(images_response) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const imagesResponse = await client.images.generate({ prompt: 'A cute baby sea otter' }); console.log(imagesResponse); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) imagesResponse, err := client.Images.Generate(context.TODO(), openai.ImageGenerateParams{ Prompt: "A cute baby sea otter", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", imagesResponse) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.images.ImageGenerateParams; import com.openai.models.images.ImagesResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ImageGenerateParams params = ImageGenerateParams.builder() .prompt("A cute baby sea otter") .build(); ImagesResponse imagesResponse = client.images().generate(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") images_response = openai.images.generate(prompt: "A cute baby sea otter") puts(images_response) ###### response event: image_generation.partial_image data: {"type":"image_generation.partial_image","b64_json":"...","partial_image_index":0} event: image_generation.completed data: {"type":"image_generation.completed","b64_json":"...","usage":{"total_tokens":100,"input_tokens":50,"output_tokens":50,"input_tokens_details":{"text_tokens":10,"image_tokens":40}}} #### description Creates an image given a prompt. [Learn more](https://platform.openai.com/docs/guides/images). ## /images/variations ### post #### operationId createImageVariation #### tags - Images #### summary Create image variation #### requestBody ##### required true ##### content ###### multipart/form-data ####### schema ######## $ref #/components/schemas/CreateImageVariationRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ImagesResponse #### x-oaiMeta ##### name Create image variation ##### group images ##### returns Returns a list of [image](https://platform.openai.com/docs/api-reference/images/object) objects. ##### examples ###### response { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] } ###### request ####### curl curl https://api.openai.com/v1/images/variations \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F image="@otter.png" \ -F n=2 \ -F size="1024x1024" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) images_response = client.images.create_variation( image=b"raw file contents", ) print(images_response.created) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const imagesResponse = await client.images.createVariation({ image: fs.createReadStream('otter.png') }); console.log(imagesResponse.created); ####### 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); ####### go package main import ( "bytes" "context" "fmt" "io" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) imagesResponse, err := client.Images.NewVariation(context.TODO(), openai.ImageNewVariationParams{ Image: io.Reader(bytes.NewBuffer([]byte("some file contents"))), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", imagesResponse.Created) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.images.ImageCreateVariationParams; import com.openai.models.images.ImagesResponse; import java.io.ByteArrayInputStream; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ImageCreateVariationParams params = ImageCreateVariationParams.builder() .image(ByteArrayInputStream("some content".getBytes())) .build(); ImagesResponse imagesResponse = client.images().createVariation(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") images_response = openai.images.create_variation(image: Pathname(__FILE__)) puts(images_response) #### description Creates a variation of a given image. This endpoint only supports `dall-e-2`. ## /models ### get #### operationId listModels #### tags - Models #### summary List models #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListModelsResponse #### x-oaiMeta ##### name List models ##### group models ##### returns A list of [model](https://platform.openai.com/docs/api-reference/models/object) objects. ##### examples ###### response { "object": "list", "data": [ { "id": "model-id-0", "object": "model", "created": 1686935002, "owned_by": "organization-owner" }, { "id": "model-id-1", "object": "model", "created": 1686935002, "owned_by": "organization-owner", }, { "id": "model-id-2", "object": "model", "created": 1686935002, "owned_by": "openai" }, ], "object": "list" } ###### request ####### curl curl https://api.openai.com/v1/models \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.models.list() page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const model of client.models.list()) { console.log(model.id); } ####### 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); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Models.List(context.TODO()) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.models.ModelListPage; import com.openai.models.models.ModelListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ModelListPage page = client.models().list(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.models.list puts(page) #### description Lists the currently available models, and provides basic information about each one such as the owner and availability. ## /models/{model} ### get #### operationId retrieveModel #### tags - Models #### summary Retrieve model #### parameters ##### in path ##### name model ##### required true ##### schema ###### type string ###### example gpt-4o-mini ##### description The ID of the model to use for this request #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Model #### x-oaiMeta ##### name Retrieve model ##### group models ##### returns The [model](https://platform.openai.com/docs/api-reference/models/object) object matching the specified ID. ##### examples ###### response { "id": "VAR_chat_model_id", "object": "model", "created": 1686935002, "owned_by": "openai" } ###### request ####### curl curl https://api.openai.com/v1/models/VAR_chat_model_id \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) model = client.models.retrieve( "gpt-4o-mini", ) print(model.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const model = await client.models.retrieve('gpt-4o-mini'); console.log(model.id); ####### 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); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) model, err := client.Models.Get(context.TODO(), "gpt-4o-mini") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", model.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.models.Model; import com.openai.models.models.ModelRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Model model = client.models().retrieve("gpt-4o-mini"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") model = openai.models.retrieve("gpt-4o-mini") puts(model) #### description Retrieves a model instance, providing basic information about the model such as the owner and permissioning. ### delete #### operationId deleteModel #### tags - Models #### summary Delete a fine-tuned model #### parameters ##### in path ##### name model ##### required true ##### schema ###### type string ###### example ft:gpt-4o-mini:acemeco:suffix:abc123 ##### description The model to delete #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/DeleteModelResponse #### x-oaiMeta ##### name Delete a fine-tuned model ##### group models ##### returns Deletion status. ##### examples ###### response { "id": "ft:gpt-4o-mini:acemeco:suffix:abc123", "object": "model", "deleted": true } ###### request ####### curl curl https://api.openai.com/v1/models/ft:gpt-4o-mini:acemeco:suffix:abc123 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) model_deleted = client.models.delete( "ft:gpt-4o-mini:acemeco:suffix:abc123", ) print(model_deleted.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const modelDeleted = await client.models.delete('ft:gpt-4o-mini:acemeco:suffix:abc123'); console.log(modelDeleted.id); ####### 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); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) modelDeleted, err := client.Models.Delete(context.TODO(), "ft:gpt-4o-mini:acemeco:suffix:abc123") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", modelDeleted.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.models.ModelDeleteParams; import com.openai.models.models.ModelDeleted; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ModelDeleted modelDeleted = client.models().delete("ft:gpt-4o-mini:acemeco:suffix:abc123"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") model_deleted = openai.models.delete("ft:gpt-4o-mini:acemeco:suffix:abc123") puts(model_deleted) #### description Delete a fine-tuned model. You must have the Owner role in your organization to delete a model. ## /moderations ### post #### operationId createModeration #### tags - Moderations #### summary Create moderation #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateModerationRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/CreateModerationResponse #### x-oaiMeta ##### name Create moderation ##### group moderations ##### returns A [moderation](https://platform.openai.com/docs/api-reference/moderations/object) object. ##### examples ###### title Single string ###### request ####### curl curl https://api.openai.com/v1/moderations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "input": "I want to kill them." }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) moderation = client.moderations.create( input="I want to kill them.", ) print(moderation.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const moderation = await client.moderations.create({ input: 'I want to kill them.' }); console.log(moderation.id); ####### 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."); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) moderation, err := client.Moderations.New(context.TODO(), openai.ModerationNewParams{ Input: openai.ModerationNewParamsInputUnion{ OfString: openai.String("I want to kill them."), }, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", moderation.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.moderations.ModerationCreateParams; import com.openai.models.moderations.ModerationCreateResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ModerationCreateParams params = ModerationCreateParams.builder() .input("I want to kill them.") .build(); ModerationCreateResponse moderation = client.moderations().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") moderation = openai.moderations.create(input: "I want to kill them.") puts(moderation) ###### response { "id": "modr-AB8CjOTu2jiq12hp1AQPfeqFWaORR", "model": "text-moderation-007", "results": [ { "flagged": true, "categories": { "sexual": false, "hate": false, "harassment": true, "self-harm": false, "sexual/minors": false, "hate/threatening": false, "violence/graphic": false, "self-harm/intent": false, "self-harm/instructions": false, "harassment/threatening": true, "violence": true }, "category_scores": { "sexual": 0.000011726012417057063, "hate": 0.22706663608551025, "harassment": 0.5215635299682617, "self-harm": 2.227119921371923e-6, "sexual/minors": 7.107352217872176e-8, "hate/threatening": 0.023547329008579254, "violence/graphic": 0.00003391829886822961, "self-harm/intent": 1.646940972932498e-6, "self-harm/instructions": 1.1198755256458526e-9, "harassment/threatening": 0.5694745779037476, "violence": 0.9971134662628174 } } ] } ###### title Image and text ###### request ####### curl curl https://api.openai.com/v1/moderations \ -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "omni-moderation-latest", "input": [ { "type": "text", "text": "...text to classify goes here..." }, { "type": "image_url", "image_url": { "url": "https://example.com/image.png" } } ] }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) moderation = client.moderations.create( input="I want to kill them.", ) print(moderation.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const moderation = await client.moderations.create({ input: 'I want to kill them.' }); console.log(moderation.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) moderation, err := client.Moderations.New(context.TODO(), openai.ModerationNewParams{ Input: openai.ModerationNewParamsInputUnion{ OfString: openai.String("I want to kill them."), }, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", moderation.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.moderations.ModerationCreateParams; import com.openai.models.moderations.ModerationCreateResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ModerationCreateParams params = ModerationCreateParams.builder() .input("I want to kill them.") .build(); ModerationCreateResponse moderation = client.moderations().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") moderation = openai.moderations.create(input: "I want to kill them.") puts(moderation) ###### response { "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" ] } } ] } #### description Classifies if text and/or image inputs are potentially harmful. Learn more in the [moderation guide](https://platform.openai.com/docs/guides/moderation). ## /organization/admin_api_keys ### get #### summary List all organization and project API keys. #### operationId admin-api-keys-list #### description List organization API keys #### parameters ##### in query ##### name after ##### required false ##### schema ###### type string ###### nullable true ###### description Return keys with IDs that come after this ID in the pagination order. ##### in query ##### name order ##### required false ##### schema ###### type string ###### enum - asc - desc ###### default asc ###### description Order results by creation time, ascending or descending. ##### in query ##### name limit ##### required false ##### schema ###### type integer ###### default 20 ###### description Maximum number of keys to return. #### responses ##### 200 ###### description A list of organization API keys. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ApiKeyList #### x-oaiMeta ##### name List all organization and project API keys. ##### group administration ##### returns A list of admin and project API key objects. ##### examples ###### response { "object": "list", "data": [ { "object": "organization.admin_api_key", "id": "key_abc", "name": "Main Admin Key", "redacted_value": "sk-admin...def", "created_at": 1711471533, "last_used_at": 1711471534, "owner": { "type": "service_account", "object": "organization.service_account", "id": "sa_456", "name": "My Service Account", "created_at": 1711471533, "role": "member" } } ], "first_id": "key_abc", "last_id": "key_abc", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/organization/admin_api_keys?after=key_abc&limit=20 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" ### post #### summary Create admin API key #### operationId admin-api-keys-create #### description Create an organization admin API key #### requestBody ##### required true ##### content ###### application/json ####### schema ######## type object ######## required - name ######## properties ######### name ########## type string ########## example New Admin Key #### responses ##### 200 ###### description The newly created admin API key. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/AdminApiKey #### x-oaiMeta ##### name Create admin API key ##### group administration ##### returns The created [AdminApiKey](https://platform.openai.com/docs/api-reference/admin-api-keys/object) object. ##### examples ###### response { "object": "organization.admin_api_key", "id": "key_xyz", "name": "New Admin Key", "redacted_value": "sk-admin...xyz", "created_at": 1711471533, "last_used_at": 1711471534, "owner": { "type": "user", "object": "organization.user", "id": "user_123", "name": "John Doe", "created_at": 1711471533, "role": "owner" }, "value": "sk-admin-1234abcd" } ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/admin_api_keys \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "New Admin Key" }' ## /organization/admin_api_keys/{key_id} ### get #### summary Retrieve admin API key #### operationId admin-api-keys-get #### description Retrieve a single organization API key #### parameters ##### in path ##### name key_id ##### required true ##### schema ###### type string ###### description The ID of the API key. #### responses ##### 200 ###### description Details of the requested API key. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/AdminApiKey #### x-oaiMeta ##### name Retrieve admin API key ##### group administration ##### returns The requested [AdminApiKey](https://platform.openai.com/docs/api-reference/admin-api-keys/object) object. ##### examples ###### response { "object": "organization.admin_api_key", "id": "key_abc", "name": "Main Admin Key", "redacted_value": "sk-admin...xyz", "created_at": 1711471533, "last_used_at": 1711471534, "owner": { "type": "user", "object": "organization.user", "id": "user_123", "name": "John Doe", "created_at": 1711471533, "role": "owner" } } ###### request ####### curl curl https://api.openai.com/v1/organization/admin_api_keys/key_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" ### delete #### summary Delete admin API key #### operationId admin-api-keys-delete #### description Delete an organization admin API key #### parameters ##### in path ##### name key_id ##### required true ##### schema ###### type string ###### description The ID of the API key to be deleted. #### responses ##### 200 ###### description Confirmation that the API key was deleted. ###### content ####### application/json ######## schema ######### type object ######### properties ########## id ########### type string ########### example key_abc ########## object ########### type string ########### example organization.admin_api_key.deleted ########## deleted ########### type boolean ########### example true #### x-oaiMeta ##### name Delete admin API key ##### group administration ##### returns A confirmation object indicating the key was deleted. ##### examples ###### response { "id": "key_abc", "object": "organization.admin_api_key.deleted", "deleted": true } ###### request ####### curl curl -X DELETE https://api.openai.com/v1/organization/admin_api_keys/key_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" ## /organization/audit_logs ### get #### summary List audit logs #### operationId list-audit-logs #### tags - Audit Logs #### parameters ##### name effective_at ##### in query ##### description Return only events whose `effective_at` (Unix seconds) is in this range. ##### required false ##### schema ###### type object ###### properties ####### gt ######## type integer ######## description Return only events whose `effective_at` (Unix seconds) is greater than this value. ####### gte ######## type integer ######## description Return only events whose `effective_at` (Unix seconds) is greater than or equal to this value. ####### lt ######## type integer ######## description Return only events whose `effective_at` (Unix seconds) is less than this value. ####### lte ######## type integer ######## description Return only events whose `effective_at` (Unix seconds) is less than or equal to this value. ##### name project_ids[] ##### in query ##### description Return only events for these projects. ##### required false ##### schema ###### type array ###### items ####### type string ##### name event_types[] ##### in query ##### description Return only events with a `type` in one of these values. For example, `project.created`. For all options, see the documentation for the [audit log object](https://platform.openai.com/docs/api-reference/audit-logs/object). ##### required false ##### schema ###### type array ###### items ####### $ref #/components/schemas/AuditLogEventType ##### name actor_ids[] ##### in query ##### description Return only events performed by these actors. Can be a user ID, a service account ID, or an api key tracking ID. ##### required false ##### schema ###### type array ###### items ####### type string ##### name actor_emails[] ##### in query ##### description Return only events performed by users with these emails. ##### required false ##### schema ###### type array ###### items ####### type string ##### name resource_ids[] ##### in query ##### description Return only events performed on these targets. For example, a project ID updated. ##### required false ##### schema ###### type array ###### items ####### 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 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 Audit logs listed successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListAuditLogsResponse #### x-oaiMeta ##### name List audit logs ##### group audit-logs ##### returns A list of paginated [Audit Log](https://platform.openai.com/docs/api-reference/audit-logs/object) objects. ##### examples ###### response { "object": "list", "data": [ { "id": "audit_log-xxx_yyyymmdd", "type": "project.archived", "effective_at": 1722461446, "actor": { "type": "api_key", "api_key": { "type": "user", "user": { "id": "user-xxx", "email": "user@example.com" } } }, "project.archived": { "id": "proj_abc" }, }, { "id": "audit_log-yyy__20240101", "type": "api_key.updated", "effective_at": 1720804190, "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", "ja3": "a497151ce4338a12c4418c44d375173e", "ja4": "q13d0313h3_55b375c5d22e_c7319ce65786", "ip_address_details": { "country": "US", "city": "San Francisco", "region": "California", "region_code": "CA", "asn": "1234", "latitude": "37.77490", "longitude": "-122.41940" } } }, "api_key.updated": { "id": "key_xxxx", "data": { "scopes": ["resource_2.operation_2"] } }, } ], "first_id": "audit_log-xxx__20240101", "last_id": "audit_log_yyy__20240101", "has_more": true } ###### request ####### curl curl https://api.openai.com/v1/organization/audit_logs \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description List user actions and configuration changes within this organization. ## /organization/certificates ### get #### summary List organization certificates #### operationId listOrganizationCertificates #### tags - Certificates #### 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 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. ##### required false ##### schema ###### type string ##### 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 #### responses ##### 200 ###### description Certificates listed successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListCertificatesResponse #### x-oaiMeta ##### name List organization certificates ##### group administration ##### returns A list of [Certificate](https://platform.openai.com/docs/api-reference/certificates/object) objects. ##### examples ###### request ####### curl curl https://api.openai.com/v1/organization/certificates \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ###### response { "object": "list", "data": [ { "object": "organization.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, ], "first_id": "cert_abc", "last_id": "cert_abc", "has_more": false } #### description List uploaded certificates for this organization. ### post #### summary Upload certificate #### operationId uploadCertificate #### tags - Certificates #### requestBody ##### description The certificate upload payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/UploadCertificateRequest #### responses ##### 200 ###### description Certificate uploaded successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Certificate #### x-oaiMeta ##### name Upload certificate ##### group administration ##### returns A single [Certificate](https://platform.openai.com/docs/api-reference/certificates/object) object. ##### examples ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/certificates \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "My Example Certificate", "certificate": "-----BEGIN CERTIFICATE-----\\nMIIDeT...\\n-----END CERTIFICATE-----" }' ###### response { "object": "certificate", "id": "cert_abc", "name": "My Example Certificate", "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } } #### description Upload a certificate to the organization. This does **not** automatically activate the certificate. Organizations can upload up to 50 certificates. ## /organization/certificates/activate ### post #### summary Activate certificates for organization #### operationId activateOrganizationCertificates #### tags - Certificates #### requestBody ##### description The certificate activation payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ToggleCertificatesRequest #### responses ##### 200 ###### description Certificates activated successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListCertificatesResponse #### x-oaiMeta ##### name Activate certificates for organization ##### group administration ##### returns A list of [Certificate](https://platform.openai.com/docs/api-reference/certificates/object) objects that were activated. ##### examples ###### request ####### curl curl https://api.openai.com/v1/organization/certificates/activate \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "data": ["cert_abc", "cert_def"] }' ###### response { "object": "organization.certificate.activation", "data": [ { "object": "organization.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, { "object": "organization.certificate", "id": "cert_def", "name": "My Example Certificate 2", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, ], } #### description Activate certificates at the organization level. You can atomically and idempotently activate up to 10 certificates at a time. ## /organization/certificates/deactivate ### post #### summary Deactivate certificates for organization #### operationId deactivateOrganizationCertificates #### tags - Certificates #### requestBody ##### description The certificate deactivation payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ToggleCertificatesRequest #### responses ##### 200 ###### description Certificates deactivated successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListCertificatesResponse #### x-oaiMeta ##### name Deactivate certificates for organization ##### group administration ##### returns A list of [Certificate](https://platform.openai.com/docs/api-reference/certificates/object) objects that were deactivated. ##### examples ###### request ####### curl curl https://api.openai.com/v1/organization/certificates/deactivate \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "data": ["cert_abc", "cert_def"] }' ###### response { "object": "organization.certificate.deactivation", "data": [ { "object": "organization.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": false, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, { "object": "organization.certificate", "id": "cert_def", "name": "My Example Certificate 2", "active": false, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, ], } #### description Deactivate certificates at the organization level. You can atomically and idempotently deactivate up to 10 certificates at a time. ## /organization/certificates/{certificate_id} ### get #### summary Get certificate #### operationId getCertificate #### tags - Certificates #### parameters ##### name certificate_id ##### in path ##### description Unique ID of the certificate to retrieve. ##### required true ##### schema ###### type string ##### name include ##### in query ##### description A list of additional fields to include in the response. Currently the only supported value is `content` to fetch the PEM content of the certificate. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - content #### responses ##### 200 ###### description Certificate retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Certificate #### x-oaiMeta ##### name Get certificate ##### group administration ##### returns A single [Certificate](https://platform.openai.com/docs/api-reference/certificates/object) object. ##### examples ###### request ####### curl curl "https://api.openai.com/v1/organization/certificates/cert_abc?include[]=content" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ###### response { "object": "certificate", "id": "cert_abc", "name": "My Example Certificate", "created_at": 1234567, "certificate_details": { "valid_at": 1234567, "expires_at": 12345678, "content": "-----BEGIN CERTIFICATE-----MIIDeT...-----END CERTIFICATE-----" } } #### description Get a certificate that has been uploaded to the organization. You can get a certificate regardless of whether it is active or not. ### post #### summary Modify certificate #### operationId modifyCertificate #### tags - Certificates #### requestBody ##### description The certificate modification payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ModifyCertificateRequest #### responses ##### 200 ###### description Certificate modified successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Certificate #### x-oaiMeta ##### name Modify certificate ##### group administration ##### returns The updated [Certificate](https://platform.openai.com/docs/api-reference/certificates/object) object. ##### examples ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/certificates/cert_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Renamed Certificate" }' ###### response { "object": "certificate", "id": "cert_abc", "name": "Renamed Certificate", "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } } #### description Modify a certificate. Note that only the name can be modified. ### delete #### summary Delete certificate #### operationId deleteCertificate #### tags - Certificates #### responses ##### 200 ###### description Certificate deleted successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/DeleteCertificateResponse #### x-oaiMeta ##### name Delete certificate ##### group administration ##### returns A confirmation object indicating the certificate was deleted. ##### examples ###### request ####### curl curl -X DELETE https://api.openai.com/v1/organization/certificates/cert_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ###### response { "object": "certificate.deleted", "id": "cert_abc" } #### description Delete a certificate from the organization. The certificate must be inactive for the organization and all projects. ## /organization/costs ### get #### summary Costs #### operationId usage-costs #### tags - Usage #### parameters ##### name start_time ##### in query ##### description Start time (Unix seconds) of the query time range, inclusive. ##### required true ##### schema ###### type integer ##### name end_time ##### in query ##### description End time (Unix seconds) of the query time range, exclusive. ##### required false ##### schema ###### type integer ##### name bucket_width ##### in query ##### description Width of each time bucket in response. Currently only `1d` is supported, default to `1d`. ##### required false ##### schema ###### type string ###### enum - 1d ###### default 1d ##### name project_ids ##### in query ##### description Return only costs for these projects. ##### required false ##### schema ###### type array ###### items ####### type string ##### name group_by ##### in query ##### description Group the costs by the specified fields. Support fields include `project_id`, `line_item` and any combination of them. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - project_id - line_item ##### name limit ##### in query ##### description A limit on the number of buckets to be returned. Limit can range between 1 and 180, and the default is 7. ##### required false ##### schema ###### type integer ###### default 7 ##### name page ##### in query ##### description A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. ##### schema ###### type string #### responses ##### 200 ###### description Costs data retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/UsageResponse #### x-oaiMeta ##### name Costs ##### group usage-costs ##### returns A list of paginated, time bucketed [Costs](https://platform.openai.com/docs/api-reference/usage/costs_object) objects. ##### examples ###### response { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.costs.result", "amount": { "value": 0.06, "currency": "usd" }, "line_item": null, "project_id": null } ] } ], "has_more": false, "next_page": null } ###### request ####### curl curl "https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Get costs details for the organization. ## /organization/invites ### get #### summary List invites #### operationId list-invites #### tags - Invites #### 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 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. ##### required false ##### schema ###### type string #### responses ##### 200 ###### description Invites listed successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/InviteListResponse #### x-oaiMeta ##### name List invites ##### group administration ##### returns A list of [Invite](https://platform.openai.com/docs/api-reference/invite/object) objects. ##### examples ###### response { "object": "list", "data": [ { "object": "organization.invite", "id": "invite-abc", "email": "user@example.com", "role": "owner", "status": "accepted", "invited_at": 1711471533, "expires_at": 1711471533, "accepted_at": 1711471533 } ], "first_id": "invite-abc", "last_id": "invite-abc", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/organization/invites?after=invite-abc&limit=20 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Returns a list of invites in the organization. ### post #### summary Create invite #### operationId inviteUser #### tags - Invites #### requestBody ##### description The invite request payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/InviteRequest #### responses ##### 200 ###### description User invited successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Invite #### x-oaiMeta ##### name Create invite ##### group administration ##### returns The created [Invite](https://platform.openai.com/docs/api-reference/invite/object) object. ##### examples ###### response { "object": "organization.invite", "id": "invite-def", "email": "anotheruser@example.com", "role": "reader", "status": "pending", "invited_at": 1711471533, "expires_at": 1711471533, "accepted_at": null, "projects": [ { "id": "project-xyz", "role": "member" }, { "id": "project-abc", "role": "owner" } ] } ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/invites \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "anotheruser@example.com", "role": "reader", "projects": [ { "id": "project-xyz", "role": "member" }, { "id": "project-abc", "role": "owner" } ] }' #### description Create an invite for a user to the organization. The invite must be accepted by the user before they have access to the organization. ## /organization/invites/{invite_id} ### get #### summary Retrieve invite #### operationId retrieve-invite #### tags - Invites #### parameters ##### in path ##### name invite_id ##### required true ##### schema ###### type string ##### description The ID of the invite to retrieve. #### responses ##### 200 ###### description Invite retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Invite #### x-oaiMeta ##### name Retrieve invite ##### group administration ##### returns The [Invite](https://platform.openai.com/docs/api-reference/invite/object) object matching the specified ID. ##### examples ###### response { "object": "organization.invite", "id": "invite-abc", "email": "user@example.com", "role": "owner", "status": "accepted", "invited_at": 1711471533, "expires_at": 1711471533, "accepted_at": 1711471533 } ###### request ####### curl curl https://api.openai.com/v1/organization/invites/invite-abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Retrieves an invite. ### delete #### summary Delete invite #### operationId delete-invite #### tags - Invites #### parameters ##### in path ##### name invite_id ##### required true ##### schema ###### type string ##### description The ID of the invite to delete. #### responses ##### 200 ###### description Invite deleted successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/InviteDeleteResponse #### x-oaiMeta ##### name Delete invite ##### group administration ##### returns Confirmation that the invite has been deleted ##### examples ###### response { "object": "organization.invite.deleted", "id": "invite-abc", "deleted": true } ###### request ####### curl curl -X DELETE https://api.openai.com/v1/organization/invites/invite-abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Delete an invite. If the invite has already been accepted, it cannot be deleted. ## /organization/projects ### get #### summary List projects #### operationId list-projects #### tags - Projects #### 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 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. ##### required false ##### schema ###### type string ##### name include_archived ##### in query ##### schema ###### type boolean ###### default false ##### description If `true` returns all projects including those that have been `archived`. Archived projects are not included by default. #### responses ##### 200 ###### description Projects listed successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectListResponse #### x-oaiMeta ##### name List projects ##### group administration ##### returns A list of [Project](https://platform.openai.com/docs/api-reference/projects/object) objects. ##### examples ###### response { "object": "list", "data": [ { "id": "proj_abc", "object": "organization.project", "name": "Project example", "created_at": 1711471533, "archived_at": null, "status": "active" } ], "first_id": "proj-abc", "last_id": "proj-xyz", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/organization/projects?after=proj_abc&limit=20&include_archived=false \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Returns a list of projects. ### post #### summary Create project #### operationId create-project #### tags - Projects #### requestBody ##### description The project create request payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ProjectCreateRequest #### responses ##### 200 ###### description Project created successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Project #### x-oaiMeta ##### name Create project ##### group administration ##### returns The created [Project](https://platform.openai.com/docs/api-reference/projects/object) object. ##### examples ###### response { "id": "proj_abc", "object": "organization.project", "name": "Project ABC", "created_at": 1711471533, "archived_at": null, "status": "active" } ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/projects \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Project ABC" }' #### description Create a new project in the organization. Projects can be created and archived, but cannot be deleted. ## /organization/projects/{project_id} ### get #### summary Retrieve project #### operationId retrieve-project #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string #### responses ##### 200 ###### description Project retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Project #### x-oaiMeta ##### name Retrieve project ##### group administration ##### description Retrieve a project. ##### returns The [Project](https://platform.openai.com/docs/api-reference/projects/object) object matching the specified ID. ##### examples ###### response { "id": "proj_abc", "object": "organization.project", "name": "Project example", "created_at": 1711471533, "archived_at": null, "status": "active" } ###### request ####### curl curl https://api.openai.com/v1/organization/projects/proj_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Retrieves a project. ### post #### summary Modify project #### operationId modify-project #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string #### requestBody ##### description The project update request payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ProjectUpdateRequest #### responses ##### 200 ###### description Project updated successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Project ##### 400 ###### description Error response when updating the default project. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ErrorResponse #### x-oaiMeta ##### name Modify project ##### group administration ##### returns The updated [Project](https://platform.openai.com/docs/api-reference/projects/object) object. ##### examples ###### response ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/projects/proj_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Project DEF" }' #### description Modifies a project in the organization. ## /organization/projects/{project_id}/api_keys ### get #### summary List project API keys #### operationId list-project-api-keys #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### 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 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. ##### required false ##### schema ###### type string #### responses ##### 200 ###### description Project API keys listed successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectApiKeyListResponse #### x-oaiMeta ##### name List project API keys ##### group administration ##### returns A list of [ProjectApiKey](https://platform.openai.com/docs/api-reference/project-api-keys/object) objects. ##### examples ###### response { "object": "list", "data": [ { "object": "organization.project.api_key", "redacted_value": "sk-abc...def", "name": "My API Key", "created_at": 1711471533, "last_used_at": 1711471534, "id": "key_abc", "owner": { "type": "user", "user": { "object": "organization.project.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } } } ], "first_id": "key_abc", "last_id": "key_xyz", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys?after=key_abc&limit=20 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Returns a list of API keys in the project. ## /organization/projects/{project_id}/api_keys/{key_id} ### get #### summary Retrieve project API key #### operationId retrieve-project-api-key #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string ##### name key_id ##### in path ##### description The ID of the API key. ##### required true ##### schema ###### type string #### responses ##### 200 ###### description Project API key retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectApiKey #### x-oaiMeta ##### name Retrieve project API key ##### group administration ##### returns The [ProjectApiKey](https://platform.openai.com/docs/api-reference/project-api-keys/object) object matching the specified ID. ##### examples ###### response { "object": "organization.project.api_key", "redacted_value": "sk-abc...def", "name": "My API Key", "created_at": 1711471533, "last_used_at": 1711471534, "id": "key_abc", "owner": { "type": "user", "user": { "object": "organization.project.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } } } ###### request ####### curl curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Retrieves an API key in the project. ### delete #### summary Delete project API key #### operationId delete-project-api-key #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string ##### name key_id ##### in path ##### description The ID of the API key. ##### required true ##### schema ###### type string #### responses ##### 200 ###### description Project API key deleted successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectApiKeyDeleteResponse ##### 400 ###### description Error response for various conditions. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ErrorResponse #### x-oaiMeta ##### name Delete project API key ##### group administration ##### returns Confirmation of the key's deletion or an error if the key belonged to a service account ##### examples ###### response { "object": "organization.project.api_key.deleted", "id": "key_abc", "deleted": true } ###### request ####### curl curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Deletes an API key from the project. ## /organization/projects/{project_id}/archive ### post #### summary Archive project #### operationId archive-project #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string #### responses ##### 200 ###### description Project archived successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Project #### x-oaiMeta ##### name Archive project ##### group administration ##### returns The archived [Project](https://platform.openai.com/docs/api-reference/projects/object) object. ##### examples ###### response { "id": "proj_abc", "object": "organization.project", "name": "Project DEF", "created_at": 1711471533, "archived_at": 1711471533, "status": "archived" } ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/archive \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Archives a project in the organization. Archived projects cannot be used or updated. ## /organization/projects/{project_id}/certificates ### get #### summary List project certificates #### operationId listProjectCertificates #### tags - Certificates #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### 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 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. ##### required false ##### schema ###### type string ##### 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 #### responses ##### 200 ###### description Certificates listed successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListCertificatesResponse #### x-oaiMeta ##### name List project certificates ##### group administration ##### returns A list of [Certificate](https://platform.openai.com/docs/api-reference/certificates/object) objects. ##### examples ###### request ####### curl curl https://api.openai.com/v1/organization/projects/proj_abc/certificates \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" ###### response { "object": "list", "data": [ { "object": "organization.project.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, ], "first_id": "cert_abc", "last_id": "cert_abc", "has_more": false } #### description List certificates for this project. ## /organization/projects/{project_id}/certificates/activate ### post #### summary Activate certificates for project #### operationId activateProjectCertificates #### tags - Certificates #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string #### requestBody ##### description The certificate activation payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ToggleCertificatesRequest #### responses ##### 200 ###### description Certificates activated successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListCertificatesResponse #### x-oaiMeta ##### name Activate certificates for project ##### group administration ##### returns A list of [Certificate](https://platform.openai.com/docs/api-reference/certificates/object) objects that were activated. ##### examples ###### request ####### curl curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/activate \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "data": ["cert_abc", "cert_def"] }' ###### response { "object": "organization.project.certificate.activation", "data": [ { "object": "organization.project.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, { "object": "organization.project.certificate", "id": "cert_def", "name": "My Example Certificate 2", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, ], } #### description Activate certificates at the project level. You can atomically and idempotently activate up to 10 certificates at a time. ## /organization/projects/{project_id}/certificates/deactivate ### post #### summary Deactivate certificates for project #### operationId deactivateProjectCertificates #### tags - Certificates #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string #### requestBody ##### description The certificate deactivation payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ToggleCertificatesRequest #### responses ##### 200 ###### description Certificates deactivated successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ListCertificatesResponse #### x-oaiMeta ##### name Deactivate certificates for project ##### group administration ##### returns A list of [Certificate](https://platform.openai.com/docs/api-reference/certificates/object) objects that were deactivated. ##### examples ###### request ####### curl curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/deactivate \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "data": ["cert_abc", "cert_def"] }' ###### response { "object": "organization.project.certificate.deactivation", "data": [ { "object": "organization.project.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": false, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, { "object": "organization.project.certificate", "id": "cert_def", "name": "My Example Certificate 2", "active": false, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, ], } #### description Deactivate certificates at the project level. You can atomically and idempotently deactivate up to 10 certificates at a time. ## /organization/projects/{project_id}/rate_limits ### get #### summary List project rate limits #### operationId list-project-rate-limits #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string ##### name limit ##### in query ##### description A limit on the number of objects to be returned. The default is 100. ##### required false ##### schema ###### type integer ###### default 100 ##### 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. ##### required false ##### 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, beginning with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. ##### required false ##### schema ###### type string #### responses ##### 200 ###### description Project rate limits listed successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectRateLimitListResponse #### x-oaiMeta ##### name List project rate limits ##### group administration ##### returns A list of [ProjectRateLimit](https://platform.openai.com/docs/api-reference/project-rate-limits/object) objects. ##### examples ###### response { "object": "list", "data": [ { "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 } ], "first_id": "rl-ada", "last_id": "rl-ada", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/organization/projects/proj_abc/rate_limits?after=rl_xxx&limit=20 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" ###### error_response { "code": 404, "message": "The project {project_id} was not found" } #### description Returns the rate limits per model for a project. ## /organization/projects/{project_id}/rate_limits/{rate_limit_id} ### post #### summary Modify project rate limit #### operationId update-project-rate-limits #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string ##### name rate_limit_id ##### in path ##### description The ID of the rate limit. ##### required true ##### schema ###### type string #### requestBody ##### description The project rate limit update request payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ProjectRateLimitUpdateRequest #### responses ##### 200 ###### description Project rate limit updated successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectRateLimit ##### 400 ###### description Error response for various conditions. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ErrorResponse #### x-oaiMeta ##### name Modify project rate limit ##### group administration ##### returns The updated [ProjectRateLimit](https://platform.openai.com/docs/api-reference/project-rate-limits/object) object. ##### examples ###### response { "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 } ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/rate_limits/rl_xxx \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "max_requests_per_1_minute": 500 }' ###### error_response { "code": 404, "message": "The project {project_id} was not found" } #### description Updates a project rate limit. ## /organization/projects/{project_id}/service_accounts ### get #### summary List project service accounts #### operationId list-project-service-accounts #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### 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 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. ##### required false ##### schema ###### type string #### responses ##### 200 ###### description Project service accounts listed successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectServiceAccountListResponse ##### 400 ###### description Error response when project is archived. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ErrorResponse #### x-oaiMeta ##### name List project service accounts ##### group administration ##### returns A list of [ProjectServiceAccount](https://platform.openai.com/docs/api-reference/project-service-accounts/object) objects. ##### examples ###### response { "object": "list", "data": [ { "object": "organization.project.service_account", "id": "svc_acct_abc", "name": "Service Account", "role": "owner", "created_at": 1711471533 } ], "first_id": "svc_acct_abc", "last_id": "svc_acct_xyz", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts?after=custom_id&limit=20 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Returns a list of service accounts in the project. ### post #### summary Create project service account #### operationId create-project-service-account #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string #### requestBody ##### description The project service account create request payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ProjectServiceAccountCreateRequest #### responses ##### 200 ###### description Project service account created successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectServiceAccountCreateResponse ##### 400 ###### description Error response when project is archived. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ErrorResponse #### x-oaiMeta ##### name Create project service account ##### group administration ##### returns The created [ProjectServiceAccount](https://platform.openai.com/docs/api-reference/project-service-accounts/object) object. ##### examples ###### response { "object": "organization.project.service_account", "id": "svc_acct_abc", "name": "Production App", "role": "member", "created_at": 1711471533, "api_key": { "object": "organization.project.service_account.api_key", "value": "sk-abcdefghijklmnop123", "name": "Secret Key", "created_at": 1711471533, "id": "key_abc" } } ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production App" }' #### description Creates a new service account in the project. This also returns an unredacted API key for the service account. ## /organization/projects/{project_id}/service_accounts/{service_account_id} ### get #### summary Retrieve project service account #### operationId retrieve-project-service-account #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string ##### name service_account_id ##### in path ##### description The ID of the service account. ##### required true ##### schema ###### type string #### responses ##### 200 ###### description Project service account retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectServiceAccount #### x-oaiMeta ##### name Retrieve project service account ##### group administration ##### returns The [ProjectServiceAccount](https://platform.openai.com/docs/api-reference/project-service-accounts/object) object matching the specified ID. ##### examples ###### response { "object": "organization.project.service_account", "id": "svc_acct_abc", "name": "Service Account", "role": "owner", "created_at": 1711471533 } ###### request ####### curl curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Retrieves a service account in the project. ### delete #### summary Delete project service account #### operationId delete-project-service-account #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string ##### name service_account_id ##### in path ##### description The ID of the service account. ##### required true ##### schema ###### type string #### responses ##### 200 ###### description Project service account deleted successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectServiceAccountDeleteResponse #### x-oaiMeta ##### name Delete project service account ##### group administration ##### returns Confirmation of service account being deleted, or an error in case of an archived project, which has no service accounts ##### examples ###### response { "object": "organization.project.service_account.deleted", "id": "svc_acct_abc", "deleted": true } ###### request ####### curl curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Deletes a service account from the project. ## /organization/projects/{project_id}/users ### get #### summary List project users #### operationId list-project-users #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### 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 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. ##### required false ##### schema ###### type string #### responses ##### 200 ###### description Project users listed successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectUserListResponse ##### 400 ###### description Error response when project is archived. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ErrorResponse #### x-oaiMeta ##### name List project users ##### group administration ##### returns A list of [ProjectUser](https://platform.openai.com/docs/api-reference/project-users/object) objects. ##### examples ###### response { "object": "list", "data": [ { "object": "organization.project.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } ], "first_id": "user-abc", "last_id": "user-xyz", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/organization/projects/proj_abc/users?after=user_abc&limit=20 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Returns a list of users in the project. ### post #### summary Create project user #### operationId create-project-user #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string #### tags - Projects #### requestBody ##### description The project user create request payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ProjectUserCreateRequest #### responses ##### 200 ###### description User added to project successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectUser ##### 400 ###### description Error response for various conditions. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ErrorResponse #### x-oaiMeta ##### name Create project user ##### group administration ##### returns The created [ProjectUser](https://platform.openai.com/docs/api-reference/project-users/object) object. ##### examples ###### response { "object": "organization.project.user", "id": "user_abc", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "user_id": "user_abc", "role": "member" }' #### description Adds a user to the project. Users must already be members of the organization to be added to a project. ## /organization/projects/{project_id}/users/{user_id} ### get #### summary Retrieve project user #### operationId retrieve-project-user #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string ##### name user_id ##### in path ##### description The ID of the user. ##### required true ##### schema ###### type string #### responses ##### 200 ###### description Project user retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectUser #### x-oaiMeta ##### name Retrieve project user ##### group administration ##### returns The [ProjectUser](https://platform.openai.com/docs/api-reference/project-users/object) object matching the specified ID. ##### examples ###### response { "object": "organization.project.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } ###### request ####### curl curl https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Retrieves a user in the project. ### post #### summary Modify project user #### operationId modify-project-user #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string ##### name user_id ##### in path ##### description The ID of the user. ##### required true ##### schema ###### type string #### requestBody ##### description The project user update request payload. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ProjectUserUpdateRequest #### responses ##### 200 ###### description Project user's role updated successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectUser ##### 400 ###### description Error response for various conditions. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ErrorResponse #### x-oaiMeta ##### name Modify project user ##### group administration ##### returns The updated [ProjectUser](https://platform.openai.com/docs/api-reference/project-users/object) object. ##### examples ###### response { "object": "organization.project.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role": "owner" }' #### description Modifies a user's role in the project. ### delete #### summary Delete project user #### operationId delete-project-user #### tags - Projects #### parameters ##### name project_id ##### in path ##### description The ID of the project. ##### required true ##### schema ###### type string ##### name user_id ##### in path ##### description The ID of the user. ##### required true ##### schema ###### type string #### responses ##### 200 ###### description Project user deleted successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ProjectUserDeleteResponse ##### 400 ###### description Error response for various conditions. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ErrorResponse #### x-oaiMeta ##### name Delete project user ##### group administration ##### returns Confirmation that project has been deleted or an error in case of an archived project, which has no users ##### examples ###### response { "object": "organization.project.user.deleted", "id": "user_abc", "deleted": true } ###### request ####### curl curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Deletes a user from the project. ## /organization/usage/audio_speeches ### get #### summary Audio speeches #### operationId usage-audio-speeches #### tags - Usage #### parameters ##### name start_time ##### in query ##### description Start time (Unix seconds) of the query time range, inclusive. ##### required true ##### schema ###### type integer ##### name end_time ##### in query ##### description End time (Unix seconds) of the query time range, exclusive. ##### required false ##### schema ###### type integer ##### name bucket_width ##### in query ##### description Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. ##### required false ##### schema ###### type string ###### enum - 1m - 1h - 1d ###### default 1d ##### name project_ids ##### in query ##### description Return only usage for these projects. ##### required false ##### schema ###### type array ###### items ####### type string ##### name user_ids ##### in query ##### description Return only usage for these users. ##### required false ##### schema ###### type array ###### items ####### type string ##### name api_key_ids ##### in query ##### description Return only usage for these API keys. ##### required false ##### schema ###### type array ###### items ####### type string ##### name models ##### in query ##### description Return only usage for these models. ##### required false ##### schema ###### type array ###### items ####### type string ##### name group_by ##### in query ##### description Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - project_id - user_id - api_key_id - model ##### name limit ##### in query ##### description Specifies the number of buckets to return. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 ##### required false ##### schema ###### type integer ##### name page ##### in query ##### description A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. ##### schema ###### type string #### responses ##### 200 ###### description Usage data retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/UsageResponse #### x-oaiMeta ##### name Audio speeches ##### group usage-audio-speeches ##### returns A list of paginated, time bucketed [Audio speeches usage](https://platform.openai.com/docs/api-reference/usage/audio_speeches_object) objects. ##### examples ###### response { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.audio_speeches.result", "characters": 45, "num_model_requests": 1, "project_id": null, "user_id": null, "api_key_id": null, "model": null } ] } ], "has_more": false, "next_page": null } ###### request ####### curl curl "https://api.openai.com/v1/organization/usage/audio_speeches?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Get audio speeches usage details for the organization. ## /organization/usage/audio_transcriptions ### get #### summary Audio transcriptions #### operationId usage-audio-transcriptions #### tags - Usage #### parameters ##### name start_time ##### in query ##### description Start time (Unix seconds) of the query time range, inclusive. ##### required true ##### schema ###### type integer ##### name end_time ##### in query ##### description End time (Unix seconds) of the query time range, exclusive. ##### required false ##### schema ###### type integer ##### name bucket_width ##### in query ##### description Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. ##### required false ##### schema ###### type string ###### enum - 1m - 1h - 1d ###### default 1d ##### name project_ids ##### in query ##### description Return only usage for these projects. ##### required false ##### schema ###### type array ###### items ####### type string ##### name user_ids ##### in query ##### description Return only usage for these users. ##### required false ##### schema ###### type array ###### items ####### type string ##### name api_key_ids ##### in query ##### description Return only usage for these API keys. ##### required false ##### schema ###### type array ###### items ####### type string ##### name models ##### in query ##### description Return only usage for these models. ##### required false ##### schema ###### type array ###### items ####### type string ##### name group_by ##### in query ##### description Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - project_id - user_id - api_key_id - model ##### name limit ##### in query ##### description Specifies the number of buckets to return. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 ##### required false ##### schema ###### type integer ##### name page ##### in query ##### description A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. ##### schema ###### type string #### responses ##### 200 ###### description Usage data retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/UsageResponse #### x-oaiMeta ##### name Audio transcriptions ##### group usage-audio-transcriptions ##### returns A list of paginated, time bucketed [Audio transcriptions usage](https://platform.openai.com/docs/api-reference/usage/audio_transcriptions_object) objects. ##### examples ###### response { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.audio_transcriptions.result", "seconds": 20, "num_model_requests": 1, "project_id": null, "user_id": null, "api_key_id": null, "model": null } ] } ], "has_more": false, "next_page": null } ###### request ####### curl curl "https://api.openai.com/v1/organization/usage/audio_transcriptions?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Get audio transcriptions usage details for the organization. ## /organization/usage/code_interpreter_sessions ### get #### summary Code interpreter sessions #### operationId usage-code-interpreter-sessions #### tags - Usage #### parameters ##### name start_time ##### in query ##### description Start time (Unix seconds) of the query time range, inclusive. ##### required true ##### schema ###### type integer ##### name end_time ##### in query ##### description End time (Unix seconds) of the query time range, exclusive. ##### required false ##### schema ###### type integer ##### name bucket_width ##### in query ##### description Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. ##### required false ##### schema ###### type string ###### enum - 1m - 1h - 1d ###### default 1d ##### name project_ids ##### in query ##### description Return only usage for these projects. ##### required false ##### schema ###### type array ###### items ####### type string ##### name group_by ##### in query ##### description Group the usage data by the specified fields. Support fields include `project_id`. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - project_id ##### name limit ##### in query ##### description Specifies the number of buckets to return. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 ##### required false ##### schema ###### type integer ##### name page ##### in query ##### description A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. ##### schema ###### type string #### responses ##### 200 ###### description Usage data retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/UsageResponse #### x-oaiMeta ##### name Code interpreter sessions ##### group usage-code-interpreter-sessions ##### returns A list of paginated, time bucketed [Code interpreter sessions usage](https://platform.openai.com/docs/api-reference/usage/code_interpreter_sessions_object) objects. ##### examples ###### response { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.code_interpreter_sessions.result", "num_sessions": 1, "project_id": null } ] } ], "has_more": false, "next_page": null } ###### request ####### curl curl "https://api.openai.com/v1/organization/usage/code_interpreter_sessions?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Get code interpreter sessions usage details for the organization. ## /organization/usage/completions ### get #### summary Completions #### operationId usage-completions #### tags - Usage #### parameters ##### name start_time ##### in query ##### description Start time (Unix seconds) of the query time range, inclusive. ##### required true ##### schema ###### type integer ##### name end_time ##### in query ##### description End time (Unix seconds) of the query time range, exclusive. ##### required false ##### schema ###### type integer ##### name bucket_width ##### in query ##### description Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. ##### required false ##### schema ###### type string ###### enum - 1m - 1h - 1d ###### default 1d ##### name project_ids ##### in query ##### description Return only usage for these projects. ##### required false ##### schema ###### type array ###### items ####### type string ##### name user_ids ##### in query ##### description Return only usage for these users. ##### required false ##### schema ###### type array ###### items ####### type string ##### name api_key_ids ##### in query ##### description Return only usage for these API keys. ##### required false ##### schema ###### type array ###### items ####### type string ##### name models ##### in query ##### description Return only usage for these models. ##### required false ##### schema ###### type array ###### items ####### type string ##### name batch ##### in query ##### description If `true`, return batch jobs only. If `false`, return non-batch jobs only. By default, return both. ##### required false ##### schema ###### type boolean ##### name group_by ##### in query ##### description Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `batch` or any combination of them. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - project_id - user_id - api_key_id - model - batch ##### name limit ##### in query ##### description Specifies the number of buckets to return. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 ##### required false ##### schema ###### type integer ##### name page ##### in query ##### description A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. ##### schema ###### type string #### responses ##### 200 ###### description Usage data retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/UsageResponse #### x-oaiMeta ##### name Completions ##### group usage-completions ##### returns A list of paginated, time bucketed [Completions usage](https://platform.openai.com/docs/api-reference/usage/completions_object) objects. ##### examples ###### response { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.completions.result", "input_tokens": 1000, "output_tokens": 500, "input_cached_tokens": 800, "input_audio_tokens": 0, "output_audio_tokens": 0, "num_model_requests": 5, "project_id": null, "user_id": null, "api_key_id": null, "model": null, "batch": null } ] } ], "has_more": true, "next_page": "page_AAAAAGdGxdEiJdKOAAAAAGcqsYA=" } ###### request ####### curl curl "https://api.openai.com/v1/organization/usage/completions?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Get completions usage details for the organization. ## /organization/usage/embeddings ### get #### summary Embeddings #### operationId usage-embeddings #### tags - Usage #### parameters ##### name start_time ##### in query ##### description Start time (Unix seconds) of the query time range, inclusive. ##### required true ##### schema ###### type integer ##### name end_time ##### in query ##### description End time (Unix seconds) of the query time range, exclusive. ##### required false ##### schema ###### type integer ##### name bucket_width ##### in query ##### description Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. ##### required false ##### schema ###### type string ###### enum - 1m - 1h - 1d ###### default 1d ##### name project_ids ##### in query ##### description Return only usage for these projects. ##### required false ##### schema ###### type array ###### items ####### type string ##### name user_ids ##### in query ##### description Return only usage for these users. ##### required false ##### schema ###### type array ###### items ####### type string ##### name api_key_ids ##### in query ##### description Return only usage for these API keys. ##### required false ##### schema ###### type array ###### items ####### type string ##### name models ##### in query ##### description Return only usage for these models. ##### required false ##### schema ###### type array ###### items ####### type string ##### name group_by ##### in query ##### description Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - project_id - user_id - api_key_id - model ##### name limit ##### in query ##### description Specifies the number of buckets to return. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 ##### required false ##### schema ###### type integer ##### name page ##### in query ##### description A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. ##### schema ###### type string #### responses ##### 200 ###### description Usage data retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/UsageResponse #### x-oaiMeta ##### name Embeddings ##### group usage-embeddings ##### returns A list of paginated, time bucketed [Embeddings usage](https://platform.openai.com/docs/api-reference/usage/embeddings_object) objects. ##### examples ###### response { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.embeddings.result", "input_tokens": 16, "num_model_requests": 2, "project_id": null, "user_id": null, "api_key_id": null, "model": null } ] } ], "has_more": false, "next_page": null } ###### request ####### curl curl "https://api.openai.com/v1/organization/usage/embeddings?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Get embeddings usage details for the organization. ## /organization/usage/images ### get #### summary Images #### operationId usage-images #### tags - Usage #### parameters ##### name start_time ##### in query ##### description Start time (Unix seconds) of the query time range, inclusive. ##### required true ##### schema ###### type integer ##### name end_time ##### in query ##### description End time (Unix seconds) of the query time range, exclusive. ##### required false ##### schema ###### type integer ##### name bucket_width ##### in query ##### description Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. ##### required false ##### schema ###### type string ###### enum - 1m - 1h - 1d ###### default 1d ##### name sources ##### in query ##### description Return only usages for these sources. Possible values are `image.generation`, `image.edit`, `image.variation` or any combination of them. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - image.generation - image.edit - image.variation ##### name sizes ##### in query ##### description Return only usages for these image sizes. Possible values are `256x256`, `512x512`, `1024x1024`, `1792x1792`, `1024x1792` or any combination of them. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - 256x256 - 512x512 - 1024x1024 - 1792x1792 - 1024x1792 ##### name project_ids ##### in query ##### description Return only usage for these projects. ##### required false ##### schema ###### type array ###### items ####### type string ##### name user_ids ##### in query ##### description Return only usage for these users. ##### required false ##### schema ###### type array ###### items ####### type string ##### name api_key_ids ##### in query ##### description Return only usage for these API keys. ##### required false ##### schema ###### type array ###### items ####### type string ##### name models ##### in query ##### description Return only usage for these models. ##### required false ##### schema ###### type array ###### items ####### type string ##### name group_by ##### in query ##### description Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `size`, `source` or any combination of them. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - project_id - user_id - api_key_id - model - size - source ##### name limit ##### in query ##### description Specifies the number of buckets to return. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 ##### required false ##### schema ###### type integer ##### name page ##### in query ##### description A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. ##### schema ###### type string #### responses ##### 200 ###### description Usage data retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/UsageResponse #### x-oaiMeta ##### name Images ##### group usage-images ##### returns A list of paginated, time bucketed [Images usage](https://platform.openai.com/docs/api-reference/usage/images_object) objects. ##### examples ###### response { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.images.result", "images": 2, "num_model_requests": 2, "size": null, "source": null, "project_id": null, "user_id": null, "api_key_id": null, "model": null } ] } ], "has_more": false, "next_page": null } ###### request ####### curl curl "https://api.openai.com/v1/organization/usage/images?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Get images usage details for the organization. ## /organization/usage/moderations ### get #### summary Moderations #### operationId usage-moderations #### tags - Usage #### parameters ##### name start_time ##### in query ##### description Start time (Unix seconds) of the query time range, inclusive. ##### required true ##### schema ###### type integer ##### name end_time ##### in query ##### description End time (Unix seconds) of the query time range, exclusive. ##### required false ##### schema ###### type integer ##### name bucket_width ##### in query ##### description Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. ##### required false ##### schema ###### type string ###### enum - 1m - 1h - 1d ###### default 1d ##### name project_ids ##### in query ##### description Return only usage for these projects. ##### required false ##### schema ###### type array ###### items ####### type string ##### name user_ids ##### in query ##### description Return only usage for these users. ##### required false ##### schema ###### type array ###### items ####### type string ##### name api_key_ids ##### in query ##### description Return only usage for these API keys. ##### required false ##### schema ###### type array ###### items ####### type string ##### name models ##### in query ##### description Return only usage for these models. ##### required false ##### schema ###### type array ###### items ####### type string ##### name group_by ##### in query ##### description Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - project_id - user_id - api_key_id - model ##### name limit ##### in query ##### description Specifies the number of buckets to return. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 ##### required false ##### schema ###### type integer ##### name page ##### in query ##### description A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. ##### schema ###### type string #### responses ##### 200 ###### description Usage data retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/UsageResponse #### x-oaiMeta ##### name Moderations ##### group usage-moderations ##### returns A list of paginated, time bucketed [Moderations usage](https://platform.openai.com/docs/api-reference/usage/moderations_object) objects. ##### examples ###### response { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.moderations.result", "input_tokens": 16, "num_model_requests": 2, "project_id": null, "user_id": null, "api_key_id": null, "model": null } ] } ], "has_more": false, "next_page": null } ###### request ####### curl curl "https://api.openai.com/v1/organization/usage/moderations?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Get moderations usage details for the organization. ## /organization/usage/vector_stores ### get #### summary Vector stores #### operationId usage-vector-stores #### tags - Usage #### parameters ##### name start_time ##### in query ##### description Start time (Unix seconds) of the query time range, inclusive. ##### required true ##### schema ###### type integer ##### name end_time ##### in query ##### description End time (Unix seconds) of the query time range, exclusive. ##### required false ##### schema ###### type integer ##### name bucket_width ##### in query ##### description Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`. ##### required false ##### schema ###### type string ###### enum - 1m - 1h - 1d ###### default 1d ##### name project_ids ##### in query ##### description Return only usage for these projects. ##### required false ##### schema ###### type array ###### items ####### type string ##### name group_by ##### in query ##### description Group the usage data by the specified fields. Support fields include `project_id`. ##### required false ##### schema ###### type array ###### items ####### type string ####### enum - project_id ##### name limit ##### in query ##### description Specifies the number of buckets to return. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 ##### required false ##### schema ###### type integer ##### name page ##### in query ##### description A cursor for use in pagination. Corresponding to the `next_page` field from the previous response. ##### schema ###### type string #### responses ##### 200 ###### description Usage data retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/UsageResponse #### x-oaiMeta ##### name Vector stores ##### group usage-vector-stores ##### returns A list of paginated, time bucketed [Vector stores usage](https://platform.openai.com/docs/api-reference/usage/vector_stores_object) objects. ##### examples ###### response { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.vector_stores.result", "usage_bytes": 1024, "project_id": null } ] } ], "has_more": false, "next_page": null } ###### request ####### curl curl "https://api.openai.com/v1/organization/usage/vector_stores?start_time=1730419200&limit=1" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Get vector stores usage details for the organization. ## /organization/users ### get #### summary List users #### operationId list-users #### tags - Users #### 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 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. ##### required false ##### schema ###### type string ##### name emails ##### in query ##### description Filter by the email address of users. ##### required false ##### schema ###### type array ###### items ####### type string #### responses ##### 200 ###### description Users listed successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/UserListResponse #### x-oaiMeta ##### name List users ##### group administration ##### returns A list of [User](https://platform.openai.com/docs/api-reference/users/object) objects. ##### examples ###### response { "object": "list", "data": [ { "object": "organization.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } ], "first_id": "user-abc", "last_id": "user-xyz", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/organization/users?after=user_abc&limit=20 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Lists all of the users in the organization. ## /organization/users/{user_id} ### get #### summary Retrieve user #### operationId retrieve-user #### tags - Users #### parameters ##### name user_id ##### in path ##### description The ID of the user. ##### required true ##### schema ###### type string #### responses ##### 200 ###### description User retrieved successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/User #### x-oaiMeta ##### name Retrieve user ##### group administration ##### returns The [User](https://platform.openai.com/docs/api-reference/users/object) object matching the specified ID. ##### examples ###### response { "object": "organization.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } ###### request ####### curl curl https://api.openai.com/v1/organization/users/user_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Retrieves a user by their identifier. ### post #### summary Modify user #### operationId modify-user #### tags - Users #### parameters ##### name user_id ##### in path ##### description The ID of the user. ##### required true ##### schema ###### type string #### requestBody ##### description The new user role to modify. This must be one of `owner` or `member`. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/UserRoleUpdateRequest #### responses ##### 200 ###### description User role updated successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/User #### x-oaiMeta ##### name Modify user ##### group administration ##### returns The updated [User](https://platform.openai.com/docs/api-reference/users/object) object. ##### examples ###### response { "object": "organization.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } ###### request ####### curl curl -X POST https://api.openai.com/v1/organization/users/user_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role": "owner" }' #### description Modifies a user's role in the organization. ### delete #### summary Delete user #### operationId delete-user #### tags - Users #### parameters ##### name user_id ##### in path ##### description The ID of the user. ##### required true ##### schema ###### type string #### responses ##### 200 ###### description User deleted successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/UserDeleteResponse #### x-oaiMeta ##### name Delete user ##### group administration ##### returns Confirmation of the deleted user ##### examples ###### response { "object": "organization.user.deleted", "id": "user_abc", "deleted": true } ###### request ####### curl curl -X DELETE https://api.openai.com/v1/organization/users/user_abc \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" #### description Deletes a user from the organization. ## /realtime/sessions ### post #### summary Create session #### operationId create-realtime-session #### tags - Realtime #### requestBody ##### description Create an ephemeral API key with the given session configuration. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/RealtimeSessionCreateRequest #### responses ##### 200 ###### description Session created successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/RealtimeSessionCreateResponse #### x-oaiMeta ##### name Create session ##### group realtime ##### returns The created Realtime session object, plus an ephemeral key ##### examples ###### response { "id": "sess_001", "object": "realtime.session", "model": "gpt-4o-realtime-preview", "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, "speed": 1.1, "tracing": "auto", "client_secret": { "value": "ek_abc123", "expires_at": 1234567890 } } ###### request ####### curl curl -X POST https://api.openai.com/v1/realtime/sessions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-realtime-preview", "modalities": ["audio", "text"], "instructions": "You are a friendly assistant." }' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const session = await client.beta.realtime.sessions.create(); console.log(session.client_secret); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) session = client.beta.realtime.sessions.create() print(session.client_secret) ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.realtime.sessions.SessionCreateParams; import com.openai.models.beta.realtime.sessions.SessionCreateResponse; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); SessionCreateResponse session = client.beta().realtime().sessions().create(); } } #### description Create an ephemeral API token for use in client-side applications with the Realtime API. Can be configured with the same session parameters as the `session.update` client event. It responds with a session object, plus a `client_secret` key which contains a usable ephemeral API token that can be used to authenticate browser clients for the Realtime API. ## /realtime/transcription_sessions ### post #### summary Create transcription session #### operationId create-realtime-transcription-session #### tags - Realtime #### requestBody ##### description Create an ephemeral API key with the given session configuration. ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/RealtimeTranscriptionSessionCreateRequest #### responses ##### 200 ###### description Session created successfully. ###### content ####### application/json ######## schema ######### $ref #/components/schemas/RealtimeTranscriptionSessionCreateResponse #### x-oaiMeta ##### name Create transcription session ##### group realtime ##### returns The created [Realtime transcription session object](https://platform.openai.com/docs/api-reference/realtime-sessions/transcription_session_object), plus an ephemeral key ##### examples ###### response { "id": "sess_BBwZc7cFV3XizEyKGDCGL", "object": "realtime.transcription_session", "modalities": ["audio", "text"], "turn_detection": { "type": "server_vad", "threshold": 0.5, "prefix_padding_ms": 300, "silence_duration_ms": 200 }, "input_audio_format": "pcm16", "input_audio_transcription": { "model": "gpt-4o-transcribe", "language": null, "prompt": "" }, "client_secret": null } ###### request ####### curl curl -X POST https://api.openai.com/v1/realtime/transcription_sessions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const transcriptionSession = await client.beta.realtime.transcriptionSessions.create(); console.log(transcriptionSession.client_secret); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) transcription_session = client.beta.realtime.transcription_sessions.create() print(transcription_session.client_secret) ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.realtime.transcriptionsessions.TranscriptionSession; import com.openai.models.beta.realtime.transcriptionsessions.TranscriptionSessionCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); TranscriptionSession transcriptionSession = client.beta().realtime().transcriptionSessions().create(); } } #### description Create an ephemeral API token for use in client-side applications with the Realtime API specifically for realtime transcriptions. Can be configured with the same session parameters as the `transcription_session.update` client event. It responds with a session object, plus a `client_secret` key which contains a usable ephemeral API token that can be used to authenticate browser clients for the Realtime API. ## /responses ### post #### operationId createResponse #### tags - Responses #### summary Create a model response #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateResponse #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Response ####### text/event-stream ######## schema ######### $ref #/components/schemas/ResponseStreamEvent #### x-oaiMeta ##### name Create a model response ##### group responses ##### returns Returns a [Response](https://platform.openai.com/docs/api-reference/responses/object) object. ##### path create ##### examples ###### title Text input ###### request ####### curl curl https://api.openai.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-4.1", "input": "Tell me a three sentence bedtime story about a unicorn." }' ####### javascript import OpenAI from "openai"; const openai = new OpenAI(); const response = await openai.responses.create({ model: "gpt-4.1", input: "Tell me a three sentence bedtime story about a unicorn." }); console.log(response); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) response = client.responses.create() print(response.id) ####### csharp using System; using OpenAI.Responses; OpenAIResponseClient client = new( model: "gpt-4.1", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); OpenAIResponse response = client.CreateResponse("Tell me a three sentence bedtime story about a unicorn."); Console.WriteLine(response.GetOutputText()); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.responses.create(); console.log(response.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/responses" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.Response; import com.openai.models.responses.ResponseCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Response response = client.responses().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.responses.create puts(response) ###### response { "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b", "object": "response", "created_at": 1741476542, "status": "completed", "error": null, "incomplete_details": null, "instructions": null, "max_output_tokens": null, "model": "gpt-4.1-2025-04-14", "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": {} } ###### title Image input ###### request ####### curl curl https://api.openai.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-4.1", "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" } ] } ] }' ####### javascript import OpenAI from "openai"; const openai = new OpenAI(); const response = await openai.responses.create({ model: "gpt-4.1", 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", }, ], }, ], }); console.log(response); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) response = client.responses.create() print(response.id) ####### csharp using System; using System.Collections.Generic; using OpenAI.Responses; OpenAIResponseClient client = new( model: "gpt-4.1", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); List inputItems = [ ResponseItem.CreateUserMessageItem( [ ResponseContentPart.CreateInputTextPart("What is in this image?"), ResponseContentPart.CreateInputImagePart(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")) ] ) ]; OpenAIResponse response = client.CreateResponse(inputItems); Console.WriteLine(response.GetOutputText()); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.responses.create(); console.log(response.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/responses" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.Response; import com.openai.models.responses.ResponseCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Response response = client.responses().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.responses.create puts(response) ###### response { "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41", "object": "response", "created_at": 1741476777, "status": "completed", "error": null, "incomplete_details": null, "instructions": null, "max_output_tokens": null, "model": "gpt-4.1-2025-04-14", "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": {} } ###### title File input ###### request ####### curl curl https://api.openai.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-4.1", "input": [ { "role": "user", "content": [ {"type": "input_text", "text": "what is in this file?"}, { "type": "input_file", "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf" } ] } ] }' ####### javascript import OpenAI from "openai"; const openai = new OpenAI(); const response = await openai.responses.create({ model: "gpt-4.1", input: [ { role: "user", content: [ { type: "input_text", text: "what is in this file?" }, { type: "input_file", file_url: "https://www.berkshirehathaway.com/letters/2024ltr.pdf", }, ], }, ], }); console.log(response); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) response = client.responses.create() print(response.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.responses.create(); console.log(response.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/responses" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.Response; import com.openai.models.responses.ResponseCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Response response = client.responses().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.responses.create puts(response) ###### response { "id": "resp_686eef60237881a2bd1180bb8b13de430e34c516d176ff86", "object": "response", "created_at": 1752100704, "status": "completed", "background": false, "error": null, "incomplete_details": null, "instructions": null, "max_output_tokens": null, "max_tool_calls": null, "model": "gpt-4.1-2025-04-14", "output": [ { "id": "msg_686eef60d3e081a29283bdcbc4322fd90e34c516d176ff86", "type": "message", "status": "completed", "content": [ { "type": "output_text", "annotations": [], "logprobs": [], "text": "The file seems to contain excerpts from a letter to the shareholders of Berkshire Hathaway Inc., likely written by Warren Buffett. It covers several topics:\n\n1. **Communication Philosophy**: Buffett emphasizes the importance of transparency and candidness in reporting mistakes and successes to shareholders.\n\n2. **Mistakes and Learnings**: The letter acknowledges past mistakes in business assessments and management hires, highlighting the importance of correcting errors promptly.\n\n3. **CEO Succession**: Mention of Greg Abel stepping in as the new CEO and continuing the tradition of honest communication.\n\n4. **Pete Liegl Story**: A detailed account of acquiring Forest River and the relationship with its founder, highlighting trust and effective business decisions.\n\n5. **2024 Performance**: Overview of business performance, particularly in insurance and investment activities, with a focus on GEICO's improvement.\n\n6. **Tax Contributions**: Discussion of significant tax payments to the U.S. Treasury, credited to shareholders' reinvestments.\n\n7. **Investment Strategy**: A breakdown of Berkshire\u2019s investments in both controlled subsidiaries and marketable equities, along with a focus on long-term holding strategies.\n\n8. **American Capitalism**: Reflections on America\u2019s economic development and Berkshire\u2019s role within it.\n\n9. **Property-Casualty Insurance**: Insights into the P/C insurance business model and its challenges and benefits.\n\n10. **Japanese Investments**: Information about Berkshire\u2019s investments in Japanese companies and future plans.\n\n11. **Annual Meeting**: Details about the upcoming annual gathering in Omaha, including schedule changes and new book releases.\n\n12. **Personal Anecdotes**: Light-hearted stories about family and interactions, conveying Buffett's personable approach.\n\n13. **Financial Performance Data**: Tables comparing Berkshire\u2019s annual performance to the S&P 500, showing impressive long-term gains.\n\nOverall, the letter reinforces Berkshire Hathaway's commitment to transparency, investment in both its businesses and the wider economy, and emphasizes strong leadership and prudent financial management." } ], "role": "assistant" } ], "parallel_tool_calls": true, "previous_response_id": null, "reasoning": { "effort": null, "summary": null }, "service_tier": "default", "store": true, "temperature": 1.0, "text": { "format": { "type": "text" } }, "tool_choice": "auto", "tools": [], "top_logprobs": 0, "top_p": 1.0, "truncation": "disabled", "usage": { "input_tokens": 8438, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 398, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 8836 }, "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-4.1", "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-4.1", tools: [{ type: "web_search_preview" }], input: "What was a positive news story from today?", }); console.log(response); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) response = client.responses.create() print(response.id) ####### csharp using System; using OpenAI.Responses; OpenAIResponseClient client = new( model: "gpt-4.1", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); string userInputText = "What was a positive news story from today?"; ResponseCreationOptions options = new() { Tools = { ResponseTool.CreateWebSearchTool() }, }; OpenAIResponse response = client.CreateResponse(userInputText, options); Console.WriteLine(response.GetOutputText()); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.responses.create(); console.log(response.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/responses" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.Response; import com.openai.models.responses.ResponseCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Response response = client.responses().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.responses.create puts(response) ###### response { "id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c", "object": "response", "created_at": 1741484430, "status": "completed", "error": null, "incomplete_details": null, "instructions": null, "max_output_tokens": null, "model": "gpt-4.1-2025-04-14", "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", "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-4.1", "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-4.1", 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( api_key="My API Key", ) response = client.responses.create() print(response.id) ####### csharp using System; using OpenAI.Responses; OpenAIResponseClient client = new( model: "gpt-4.1", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); string userInputText = "What are the attributes of an ancient brown dragon?"; ResponseCreationOptions options = new() { Tools = { ResponseTool.CreateFileSearchTool( vectorStoreIds: ["vs_1234567890"], maxResultCount: 20 ) }, }; OpenAIResponse response = client.CreateResponse(userInputText, options); Console.WriteLine(response.GetOutputText()); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.responses.create(); console.log(response.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/responses" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.Response; import com.openai.models.responses.ResponseCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Response response = client.responses().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.responses.create puts(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-4.1-2025-04-14", "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/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-4.1", "instructions": "You are a helpful assistant.", "input": "Hello!", "stream": true }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) response = client.responses.create() print(response.id) ####### javascript import OpenAI from "openai"; const openai = new OpenAI(); const response = await openai.responses.create({ model: "gpt-4.1", instructions: "You are a helpful assistant.", input: "Hello!", stream: true, }); for await (const event of response) { console.log(event); } ####### csharp using System; using System.ClientModel; using System.Threading.Tasks; using OpenAI.Responses; OpenAIResponseClient client = new( model: "gpt-4.1", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); string userInputText = "Hello!"; ResponseCreationOptions options = new() { Instructions = "You are a helpful assistant.", }; AsyncCollectionResult responseUpdates = client.CreateResponseStreamingAsync(userInputText, options); await foreach (StreamingResponseUpdate responseUpdate in responseUpdates) { if (responseUpdate is StreamingResponseOutputTextDeltaUpdate outputTextDeltaUpdate) { Console.Write(outputTextDeltaUpdate.Delta); } } ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.responses.create(); console.log(response.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/responses" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.Response; import com.openai.models.responses.ResponseCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Response response = client.responses().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.responses.create puts(response) ###### response event: response.created data: {"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-4.1-2025-04-14","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: response.in_progress data: {"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-4.1-2025-04-14","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: response.output_item.added data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}} event: response.content_part.added data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}} event: response.output_text.delta data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi"} ... event: response.output_text.done data: {"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: response.content_part.done data: {"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: response.output_item.done data: {"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: response.completed data: {"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-4.1-2025-04-14","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/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-4.1", "input": "What is the weather like in Boston today?", "tools": [ { "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"] } }, "required": ["location", "unit"] } } ], "tool_choice": "auto" }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) response = client.responses.create() print(response.id) ####### javascript import OpenAI from "openai"; const openai = new OpenAI(); const tools = [ { 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"] }, }, required: ["location", "unit"], }, }, ]; const response = await openai.responses.create({ model: "gpt-4.1", tools: tools, input: "What is the weather like in Boston today?", tool_choice: "auto", }); console.log(response); ####### csharp using System; using OpenAI.Responses; OpenAIResponseClient client = new( model: "gpt-4.1", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); ResponseTool getCurrentWeatherFunctionTool = ResponseTool.CreateFunctionTool( functionName: "get_current_weather", functionDescription: "Get the current weather in a given location", functionParameters: BinaryData.FromString(""" { "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"] } """ ) ); string userInputText = "What is the weather like in Boston today?"; ResponseCreationOptions options = new() { Tools = { getCurrentWeatherFunctionTool }, ToolChoice = ResponseToolChoice.CreateAutoChoice(), }; OpenAIResponse response = client.CreateResponse(userInputText, options); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.responses.create(); console.log(response.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/responses" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.Response; import com.openai.models.responses.ResponseCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Response response = client.responses().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.responses.create puts(response) ###### response { "id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0", "object": "response", "created_at": 1741294021, "status": "completed", "error": null, "incomplete_details": null, "instructions": null, "max_output_tokens": null, "model": "gpt-4.1-2025-04-14", "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(); 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( api_key="My API Key", ) response = client.responses.create() print(response.id) ####### csharp using System; using OpenAI.Responses; OpenAIResponseClient client = new( model: "o3-mini", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); string userInputText = "How much wood would a woodchuck chuck?"; ResponseCreationOptions options = new() { ReasoningOptions = new() { ReasoningEffortLevel = ResponseReasoningEffortLevel.High, }, }; OpenAIResponse response = client.CreateResponse(userInputText, options); Console.WriteLine(response.GetOutputText()); ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.responses.create(); console.log(response.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/responses" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.Response; import com.openai.models.responses.ResponseCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Response response = client.responses().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.responses.create puts(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": {} } #### description Creates a model response. Provide [text](https://platform.openai.com/docs/guides/text) or [image](https://platform.openai.com/docs/guides/images) inputs to generate [text](https://platform.openai.com/docs/guides/text) or [JSON](https://platform.openai.com/docs/guides/structured-outputs) outputs. Have the model call your own [custom code](https://platform.openai.com/docs/guides/function-calling) or use built-in [tools](https://platform.openai.com/docs/guides/tools) like [web search](https://platform.openai.com/docs/guides/tools-web-search) or [file search](https://platform.openai.com/docs/guides/tools-file-search) to use your own data as input for the model's response. ## /responses/{response_id} ### get #### operationId getResponse #### tags - Responses #### summary Get a model response #### parameters ##### in path ##### name response_id ##### required true ##### schema ###### type string ###### 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. ##### in query ##### name stream ##### schema ###### type boolean ##### description If set to true, the model response data will be streamed to the client as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). See the [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) for more information. ##### in query ##### name starting_after ##### schema ###### type integer ##### description The sequence number of the event after which to start streaming. ##### in query ##### name include_obfuscation ##### schema ###### type boolean ##### description When true, stream obfuscation will be enabled. Stream obfuscation adds random characters to an `obfuscation` field on streaming delta events to normalize payload sizes as a mitigation to certain side-channel attacks. These obfuscation fields are included by default, but add a small amount of overhead to the data stream. You can set `include_obfuscation` to false to optimize for bandwidth if you trust the network links between your application and the OpenAI API. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Response #### x-oaiMeta ##### name Get a model response ##### group responses ##### returns The [Response](https://platform.openai.com/docs/api-reference/responses/object) object matching the specified ID. ##### examples ###### response { "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": {} } ###### request ####### curl 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( api_key="My API Key", ) response = client.responses.retrieve( response_id="resp_677efb5139a88190b512bc3fef8e535d", ) print(response.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.responses.retrieve('resp_677efb5139a88190b512bc3fef8e535d'); console.log(response.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/responses" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Responses.Get( context.TODO(), "resp_677efb5139a88190b512bc3fef8e535d", responses.ResponseGetParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.Response; import com.openai.models.responses.ResponseRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Response response = client.responses().retrieve("resp_677efb5139a88190b512bc3fef8e535d"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.responses.retrieve("resp_677efb5139a88190b512bc3fef8e535d") puts(response) #### description Retrieves a model response with the given ID. ### delete #### operationId deleteResponse #### tags - Responses #### summary Delete a model response #### parameters ##### in path ##### name response_id ##### required true ##### schema ###### type string ###### 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/Error #### x-oaiMeta ##### name Delete a model response ##### group responses ##### returns A success message. ##### examples ###### response { "id": "resp_6786a1bec27481909a17d673315b29f6", "object": "response", "deleted": true } ###### request ####### curl 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.delete("resp_123"); console.log(response); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) client.responses.delete( "resp_677efb5139a88190b512bc3fef8e535d", ) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); await client.responses.delete('resp_677efb5139a88190b512bc3fef8e535d'); ####### go package main import ( "context" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) err := client.Responses.Delete(context.TODO(), "resp_677efb5139a88190b512bc3fef8e535d") if err != nil { panic(err.Error()) } } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.ResponseDeleteParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); client.responses().delete("resp_677efb5139a88190b512bc3fef8e535d"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") result = openai.responses.delete("resp_677efb5139a88190b512bc3fef8e535d") puts(result) #### description Deletes a model response with the given ID. ## /responses/{response_id}/cancel ### post #### operationId cancelResponse #### tags - Responses #### summary Cancel a response #### parameters ##### in path ##### name response_id ##### required true ##### schema ###### type string ###### example resp_677efb5139a88190b512bc3fef8e535d ##### description The ID of the response to cancel. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Response ##### 404 ###### description Not Found ###### content ####### application/json ######## schema ######### $ref #/components/schemas/Error #### x-oaiMeta ##### name Cancel a response ##### group responses ##### returns A [Response](https://platform.openai.com/docs/api-reference/responses/object) object. ##### examples ###### response { "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": {} } ###### request ####### curl curl -X POST https://api.openai.com/v1/responses/resp_123/cancel \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### javascript import OpenAI from "openai"; const client = new OpenAI(); const response = await client.responses.cancel("resp_123"); console.log(response); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) response = client.responses.cancel( "resp_677efb5139a88190b512bc3fef8e535d", ) print(response.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const response = await client.responses.cancel('resp_677efb5139a88190b512bc3fef8e535d'); console.log(response.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.Responses.Cancel(context.TODO(), "resp_677efb5139a88190b512bc3fef8e535d") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.Response; import com.openai.models.responses.ResponseCancelParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Response response = client.responses().cancel("resp_677efb5139a88190b512bc3fef8e535d"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") response = openai.responses.cancel("resp_677efb5139a88190b512bc3fef8e535d") puts(response) #### description Cancels a model response with the given ID. Only responses created with the `background` parameter set to `true` can be cancelled. [Learn more](https://platform.openai.com/docs/guides/background). ## /responses/{response_id}/input_items ### get #### operationId listInputItems #### tags - Responses #### summary List input items #### parameters ##### in path ##### name response_id ##### required true ##### schema ###### type string ##### description The ID of the response to retrieve input items for. ##### name limit ##### in query ##### description A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. ##### required false ##### schema ###### type integer ###### default 20 ##### in query ##### name order ##### schema ###### type string ###### enum - asc - desc ##### description The order to return the input items in. Default is `desc`. - `asc`: Return the input items in ascending order. - `desc`: Return the input items in descending order. ##### in query ##### name after ##### schema ###### type string ##### description An item ID to list items after, used in pagination. ##### in query ##### name include ##### schema ###### type array ###### items ####### $ref #/components/schemas/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/ResponseItemList #### x-oaiMeta ##### name List input items ##### group responses ##### returns A list of input item objects. ##### examples ###### response { "object": "list", "data": [ { "id": "msg_abc123", "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "Tell me a three sentence bedtime story about a unicorn." } ] } ], "first_id": "msg_abc123", "last_id": "msg_abc123", "has_more": false } ###### request ####### curl curl https://api.openai.com/v1/responses/resp_abc123/input_items \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### javascript import OpenAI from "openai"; const client = new OpenAI(); const response = await client.responses.inputItems.list("resp_123"); console.log(response.data); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.responses.input_items.list( response_id="response_id", ) page = page.data[0] print(page) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const responseItem of client.responses.inputItems.list('response_id')) { console.log(responseItem); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" "github.com/openai/openai-go/responses" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Responses.InputItems.List( context.TODO(), "response_id", responses.InputItemListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.responses.inputitems.InputItemListPage; import com.openai.models.responses.inputitems.InputItemListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); InputItemListPage page = client.responses().inputItems().list("response_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.responses.input_items.list("response_id") puts(page) #### description Returns a list of input items for a given response. ## /threads ### post #### operationId createThread #### tags - Assistants #### summary Create thread #### requestBody ##### content ###### application/json ####### schema ######## $ref #/components/schemas/CreateThreadRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ThreadObject #### x-oaiMeta ##### name Create thread ##### group threads ##### beta true ##### returns A [thread](https://platform.openai.com/docs/api-reference/threads) object. ##### examples ###### 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( api_key="My API Key", ) thread = client.beta.threads.create() print(thread.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const thread = await client.beta.threads.create(); console.log(thread.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) thread, err := client.Beta.Threads.New(context.TODO(), openai.BetaThreadNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", thread.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.Thread; import com.openai.models.beta.threads.ThreadCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Thread thread = client.beta().threads().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") thread = openai.beta.threads.create puts(thread) ###### 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( api_key="My API Key", ) thread = client.beta.threads.create() print(thread.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const thread = await client.beta.threads.create(); console.log(thread.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) thread, err := client.Beta.Threads.New(context.TODO(), openai.BetaThreadNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", thread.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.Thread; import com.openai.models.beta.threads.ThreadCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Thread thread = client.beta().threads().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") thread = openai.beta.threads.create puts(thread) ###### response { "id": "thread_abc123", "object": "thread", "created_at": 1699014083, "metadata": {}, "tool_resources": {} } #### description Create a thread. ## /threads/runs ### post #### operationId createThreadAndRun #### tags - Assistants #### summary Create thread and run #### 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](https://platform.openai.com/docs/api-reference/runs/object) object. ##### examples ###### 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 client = OpenAI( api_key="My API Key", ) run = client.beta.threads.create_and_run( assistant_id="assistant_id", ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.beta.threads.createAndRun({ assistant_id: 'assistant_id' }); console.log(run.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) run, err := client.Beta.Threads.NewAndRun(context.TODO(), openai.BetaThreadNewAndRunParams{ AssistantID: "assistant_id", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", run.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.ThreadCreateAndRunParams; import com.openai.models.beta.threads.runs.Run; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ThreadCreateAndRunParams params = ThreadCreateAndRunParams.builder() .assistantId("assistant_id") .build(); Run run = client.beta().threads().createAndRun(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.beta.threads.create_and_run(assistant_id: "assistant_id") puts(run) ###### 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 } ###### 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"} ] }, "stream": true }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) run = client.beta.threads.create_and_run( assistant_id="assistant_id", ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.beta.threads.createAndRun({ assistant_id: 'assistant_id' }); console.log(run.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) run, err := client.Beta.Threads.NewAndRun(context.TODO(), openai.BetaThreadNewAndRunParams{ AssistantID: "assistant_id", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", run.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.ThreadCreateAndRunParams; import com.openai.models.beta.threads.runs.Run; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ThreadCreateAndRunParams params = ThreadCreateAndRunParams.builder() .assistantId("assistant_id") .build(); Run run = client.beta().threads().createAndRun(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.beta.threads.create_and_run(assistant_id: "assistant_id") puts(run) ###### 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":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":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":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":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 {"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 ###### 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": "What is the weather like in San Francisco?"} ] }, "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 client = OpenAI( api_key="My API Key", ) run = client.beta.threads.create_and_run( assistant_id="assistant_id", ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.beta.threads.createAndRun({ assistant_id: 'assistant_id' }); console.log(run.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) run, err := client.Beta.Threads.NewAndRun(context.TODO(), openai.BetaThreadNewAndRunParams{ AssistantID: "assistant_id", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", run.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.ThreadCreateAndRunParams; import com.openai.models.beta.threads.runs.Run; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ThreadCreateAndRunParams params = ThreadCreateAndRunParams.builder() .assistantId("assistant_id") .build(); Run run = client.beta().threads().createAndRun(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.beta.threads.create_and_run(assistant_id: "assistant_id") puts(run) ###### 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 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.in_progress 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] #### description Create a thread and run it in one request. ## /threads/{thread_id} ### get #### operationId getThread #### tags - Assistants #### summary Retrieve thread #### parameters ##### in path ##### name thread_id ##### required true ##### schema ###### type string ##### description The ID of the thread to retrieve. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ThreadObject #### x-oaiMeta ##### name Retrieve thread ##### group threads ##### beta true ##### returns The [thread](https://platform.openai.com/docs/api-reference/threads/object) object matching the specified ID. ##### examples ###### response { "id": "thread_abc123", "object": "thread", "created_at": 1699014083, "metadata": {}, "tool_resources": { "code_interpreter": { "file_ids": [] } } } ###### 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" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) thread = client.beta.threads.retrieve( "thread_id", ) print(thread.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const thread = await client.beta.threads.retrieve('thread_id'); console.log(thread.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) thread, err := client.Beta.Threads.Get(context.TODO(), "thread_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", thread.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.Thread; import com.openai.models.beta.threads.ThreadRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Thread thread = client.beta().threads().retrieve("thread_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") thread = openai.beta.threads.retrieve("thread_id") puts(thread) #### description Retrieves a thread. ### post #### operationId modifyThread #### tags - Assistants #### summary Modify thread #### parameters ##### in path ##### name thread_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 #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/ThreadObject #### x-oaiMeta ##### name Modify thread ##### group threads ##### beta true ##### returns The modified [thread](https://platform.openai.com/docs/api-reference/threads/object) object matching the specified ID. ##### examples ###### response { "id": "thread_abc123", "object": "thread", "created_at": 1699014083, "metadata": { "modified": "true", "user": "abc123" }, "tool_resources": {} } ###### 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" } }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) thread = client.beta.threads.update( thread_id="thread_id", ) print(thread.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const thread = await client.beta.threads.update('thread_id'); console.log(thread.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) thread, err := client.Beta.Threads.Update( context.TODO(), "thread_id", openai.BetaThreadUpdateParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", thread.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.Thread; import com.openai.models.beta.threads.ThreadUpdateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Thread thread = client.beta().threads().update("thread_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") thread = openai.beta.threads.update("thread_id") puts(thread) #### description Modifies a thread. ### delete #### operationId deleteThread #### tags - Assistants #### summary Delete thread #### parameters ##### in path ##### name thread_id ##### required true ##### schema ###### type string ##### description The ID of the thread to delete. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/DeleteThreadResponse #### x-oaiMeta ##### name Delete thread ##### group threads ##### beta true ##### returns Deletion status ##### examples ###### response { "id": "thread_abc123", "object": "thread.deleted", "deleted": true } ###### 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" \ -X DELETE ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) thread_deleted = client.beta.threads.delete( "thread_id", ) print(thread_deleted.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const threadDeleted = await client.beta.threads.delete('thread_id'); console.log(threadDeleted.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) threadDeleted, err := client.Beta.Threads.Delete(context.TODO(), "thread_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", threadDeleted.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.ThreadDeleteParams; import com.openai.models.beta.threads.ThreadDeleted; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); ThreadDeleted threadDeleted = client.beta().threads().delete("thread_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") thread_deleted = openai.beta.threads.delete("thread_id") puts(thread_deleted) #### description Delete a thread. ## /threads/{thread_id}/messages ### get #### operationId listMessages #### tags - Assistants #### summary List messages #### parameters ##### in path ##### name thread_id ##### required true ##### schema ###### type string ##### description The ID of the [thread](https://platform.openai.com/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](https://platform.openai.com/docs/api-reference/messages) objects. ##### examples ###### 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, "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 } ###### 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 client = OpenAI( api_key="My API Key", ) page = client.beta.threads.messages.list( thread_id="thread_id", ) page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const message of client.beta.threads.messages.list('thread_id')) { console.log(message.id); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Beta.Threads.Messages.List( context.TODO(), "thread_id", openai.BetaThreadMessageListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.messages.MessageListPage; import com.openai.models.beta.threads.messages.MessageListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); MessageListPage page = client.beta().threads().messages().list("thread_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.beta.threads.messages.list("thread_id") puts(page) #### description Returns a list of messages for a given thread. ### post #### operationId createMessage #### tags - Assistants #### summary Create message #### parameters ##### in path ##### name thread_id ##### required true ##### schema ###### type string ##### description The ID of the [thread](https://platform.openai.com/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](https://platform.openai.com/docs/api-reference/messages/object) object. ##### examples ###### 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": {} } ###### 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( api_key="My API Key", ) message = client.beta.threads.messages.create( thread_id="thread_id", content="string", role="user", ) print(message.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const message = await client.beta.threads.messages.create('thread_id', { content: 'string', role: 'user' }); console.log(message.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) message, err := client.Beta.Threads.Messages.New( context.TODO(), "thread_id", openai.BetaThreadMessageNewParams{ Content: openai.BetaThreadMessageNewParamsContentUnion{ OfString: openai.String("string"), }, Role: openai.BetaThreadMessageNewParamsRoleUser, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", message.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.messages.Message; import com.openai.models.beta.threads.messages.MessageCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .threadId("thread_id") .content("string") .role(MessageCreateParams.Role.USER) .build(); Message message = client.beta().threads().messages().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") message = openai.beta.threads.messages.create("thread_id", content: "string", role: :user) puts(message) #### description Create a message. ## /threads/{thread_id}/messages/{message_id} ### get #### operationId getMessage #### tags - Assistants #### summary Retrieve message #### parameters ##### in path ##### name thread_id ##### required true ##### schema ###### type string ##### description The ID of the [thread](https://platform.openai.com/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](https://platform.openai.com/docs/api-reference/messages/object) object matching the specified ID. ##### examples ###### 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": [] } } ], "attachments": [], "metadata": {} } ###### 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" ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) message = client.beta.threads.messages.retrieve( message_id="message_id", thread_id="thread_id", ) print(message.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const message = await client.beta.threads.messages.retrieve('message_id', { thread_id: 'thread_id' }); console.log(message.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) message, err := client.Beta.Threads.Messages.Get( context.TODO(), "thread_id", "message_id", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", message.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.messages.Message; import com.openai.models.beta.threads.messages.MessageRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); MessageRetrieveParams params = MessageRetrieveParams.builder() .threadId("thread_id") .messageId("message_id") .build(); Message message = client.beta().threads().messages().retrieve(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") message = openai.beta.threads.messages.retrieve("message_id", thread_id: "thread_id") puts(message) #### description Retrieve a message. ### post #### operationId modifyMessage #### tags - Assistants #### summary Modify 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. #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ModifyMessageRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/MessageObject #### x-oaiMeta ##### name Modify message ##### group threads ##### beta true ##### returns The modified [message](https://platform.openai.com/docs/api-reference/messages/object) object. ##### examples ###### 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" } } ###### 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( api_key="My API Key", ) message = client.beta.threads.messages.update( message_id="message_id", thread_id="thread_id", ) print(message.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const message = await client.beta.threads.messages.update('message_id', { thread_id: 'thread_id' }); console.log(message.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) message, err := client.Beta.Threads.Messages.Update( context.TODO(), "thread_id", "message_id", openai.BetaThreadMessageUpdateParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", message.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.messages.Message; import com.openai.models.beta.threads.messages.MessageUpdateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); MessageUpdateParams params = MessageUpdateParams.builder() .threadId("thread_id") .messageId("message_id") .build(); Message message = client.beta().threads().messages().update(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") message = openai.beta.threads.messages.update("message_id", thread_id: "thread_id") puts(message) #### description Modifies a message. ### delete #### operationId deleteMessage #### tags - Assistants #### summary Delete 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 ###### response { "id": "msg_abc123", "object": "thread.message.deleted", "deleted": true } ###### 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( api_key="My API Key", ) message_deleted = client.beta.threads.messages.delete( message_id="message_id", thread_id="thread_id", ) print(message_deleted.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const messageDeleted = await client.beta.threads.messages.delete('message_id', { thread_id: 'thread_id' }); console.log(messageDeleted.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) messageDeleted, err := client.Beta.Threads.Messages.Delete( context.TODO(), "thread_id", "message_id", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", messageDeleted.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.messages.MessageDeleteParams; import com.openai.models.beta.threads.messages.MessageDeleted; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); MessageDeleteParams params = MessageDeleteParams.builder() .threadId("thread_id") .messageId("message_id") .build(); MessageDeleted messageDeleted = client.beta().threads().messages().delete(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") message_deleted = openai.beta.threads.messages.delete("message_id", thread_id: "thread_id") puts(message_deleted) #### description Deletes a message. ## /threads/{thread_id}/runs ### get #### operationId listRuns #### tags - Assistants #### summary List runs #### 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](https://platform.openai.com/docs/api-reference/runs/object) objects. ##### examples ###### 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 } ###### 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( api_key="My API Key", ) page = client.beta.threads.runs.list( thread_id="thread_id", ) page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const run of client.beta.threads.runs.list('thread_id')) { console.log(run.id); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Beta.Threads.Runs.List( context.TODO(), "thread_id", openai.BetaThreadRunListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.runs.RunListPage; import com.openai.models.beta.threads.runs.RunListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunListPage page = client.beta().threads().runs().list("thread_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.beta.threads.runs.list("thread_id") puts(page) #### description Returns a list of runs belonging to a thread. ### post #### operationId createRun #### tags - Assistants #### summary Create 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](https://platform.openai.com/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](https://platform.openai.com/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( api_key="My API Key", ) run = client.beta.threads.runs.create( thread_id="thread_id", assistant_id="assistant_id", ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.beta.threads.runs.create('thread_id', { assistant_id: 'assistant_id' }); console.log(run.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) run, err := client.Beta.Threads.Runs.New( context.TODO(), "thread_id", openai.BetaThreadRunNewParams{ AssistantID: "assistant_id", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", run.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.runs.Run; import com.openai.models.beta.threads.runs.RunCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunCreateParams params = RunCreateParams.builder() .threadId("thread_id") .assistantId("assistant_id") .build(); Run run = client.beta().threads().runs().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.beta.threads.runs.create("thread_id", assistant_id: "assistant_id") puts(run) ###### 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( api_key="My API Key", ) run = client.beta.threads.runs.create( thread_id="thread_id", assistant_id="assistant_id", ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.beta.threads.runs.create('thread_id', { assistant_id: 'assistant_id' }); console.log(run.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) run, err := client.Beta.Threads.Runs.New( context.TODO(), "thread_id", openai.BetaThreadRunNewParams{ AssistantID: "assistant_id", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", run.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.runs.Run; import com.openai.models.beta.threads.runs.RunCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunCreateParams params = RunCreateParams.builder() .threadId("thread_id") .assistantId("assistant_id") .build(); Run run = client.beta().threads().runs().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.beta.threads.runs.create("thread_id", assistant_id: "assistant_id") puts(run) ###### response 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}} 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}} 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}} 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} 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} 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":{}} 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":{}} 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":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":{}} 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}} 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}} 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 client = OpenAI( api_key="My API Key", ) run = client.beta.threads.runs.create( thread_id="thread_id", assistant_id="assistant_id", ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.beta.threads.runs.create('thread_id', { assistant_id: 'assistant_id' }); console.log(run.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) run, err := client.Beta.Threads.Runs.New( context.TODO(), "thread_id", openai.BetaThreadRunNewParams{ AssistantID: "assistant_id", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", run.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.runs.Run; import com.openai.models.beta.threads.runs.RunCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunCreateParams params = RunCreateParams.builder() .threadId("thread_id") .assistantId("assistant_id") .build(); Run run = client.beta().threads().runs().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.beta.threads.runs.create("thread_id", assistant_id: "assistant_id") puts(run) ###### 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] #### description Create a run. ## /threads/{thread_id}/runs/{run_id} ### get #### operationId getRun #### tags - Assistants #### summary Retrieve run #### parameters ##### in path ##### name thread_id ##### required true ##### schema ###### type string ##### description The ID of the [thread](https://platform.openai.com/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/RunObject #### x-oaiMeta ##### name Retrieve run ##### group threads ##### beta true ##### returns The [run](https://platform.openai.com/docs/api-reference/runs/object) object matching the specified ID. ##### examples ###### 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" } ], "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 } ###### request ####### 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( api_key="My API Key", ) run = client.beta.threads.runs.retrieve( run_id="run_id", thread_id="thread_id", ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.beta.threads.runs.retrieve('run_id', { thread_id: 'thread_id' }); console.log(run.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) run, err := client.Beta.Threads.Runs.Get( context.TODO(), "thread_id", "run_id", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", run.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.runs.Run; import com.openai.models.beta.threads.runs.RunRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunRetrieveParams params = RunRetrieveParams.builder() .threadId("thread_id") .runId("run_id") .build(); Run run = client.beta().threads().runs().retrieve(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.beta.threads.runs.retrieve("run_id", thread_id: "thread_id") puts(run) #### description Retrieves a run. ### post #### operationId modifyRun #### tags - Assistants #### summary Modify run #### parameters ##### in path ##### name thread_id ##### required true ##### schema ###### type string ##### description The ID of the [thread](https://platform.openai.com/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. #### requestBody ##### required true ##### content ###### application/json ####### schema ######## $ref #/components/schemas/ModifyRunRequest #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/RunObject #### x-oaiMeta ##### name Modify run ##### group threads ##### beta true ##### returns The modified [run](https://platform.openai.com/docs/api-reference/runs/object) object matching the specified ID. ##### examples ###### 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" ] } }, "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 } ###### request ####### curl curl 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" \ -d '{ "metadata": { "user_id": "user_abc123" } }' ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) run = client.beta.threads.runs.update( run_id="run_id", thread_id="thread_id", ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.beta.threads.runs.update('run_id', { thread_id: 'thread_id' }); console.log(run.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) run, err := client.Beta.Threads.Runs.Update( context.TODO(), "thread_id", "run_id", openai.BetaThreadRunUpdateParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", run.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.runs.Run; import com.openai.models.beta.threads.runs.RunUpdateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunUpdateParams params = RunUpdateParams.builder() .threadId("thread_id") .runId("run_id") .build(); Run run = client.beta().threads().runs().update(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.beta.threads.runs.update("run_id", thread_id: "thread_id") puts(run) #### description Modifies a run. ## /threads/{thread_id}/runs/{run_id}/cancel ### post #### operationId cancelRun #### tags - Assistants #### summary Cancel a run #### 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. #### responses ##### 200 ###### description OK ###### content ####### application/json ######## schema ######### $ref #/components/schemas/RunObject #### x-oaiMeta ##### name Cancel a run ##### group threads ##### beta true ##### returns The modified [run](https://platform.openai.com/docs/api-reference/runs/object) object matching the specified ID. ##### examples ###### 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 } ###### request ####### curl curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -X POST ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) run = client.beta.threads.runs.cancel( run_id="run_id", thread_id="thread_id", ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.beta.threads.runs.cancel('run_id', { thread_id: 'thread_id' }); console.log(run.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) run, err := client.Beta.Threads.Runs.Cancel( context.TODO(), "thread_id", "run_id", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", run.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.runs.Run; import com.openai.models.beta.threads.runs.RunCancelParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunCancelParams params = RunCancelParams.builder() .threadId("thread_id") .runId("run_id") .build(); Run run = client.beta().threads().runs().cancel(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.beta.threads.runs.cancel("run_id", thread_id: "thread_id") puts(run) #### description Cancels a run that is `in_progress`. ## /threads/{thread_id}/runs/{run_id}/steps ### get #### operationId listRunSteps #### tags - Assistants #### summary List run steps #### 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 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 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](https://platform.openai.com/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 ##### returns A list of [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) objects. ##### examples ###### 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 } ###### 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( api_key="My API Key", ) page = client.beta.threads.runs.steps.list( run_id="run_id", thread_id="thread_id", ) page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const runStep of client.beta.threads.runs.steps.list('run_id', { thread_id: 'thread_id' })) { console.log(runStep.id); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.Beta.Threads.Runs.Steps.List( context.TODO(), "thread_id", "run_id", openai.BetaThreadRunStepListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.runs.steps.StepListPage; import com.openai.models.beta.threads.runs.steps.StepListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); StepListParams params = StepListParams.builder() .threadId("thread_id") .runId("run_id") .build(); StepListPage page = client.beta().threads().runs().steps().list(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.beta.threads.runs.steps.list("run_id", thread_id: "thread_id") puts(page) #### description Returns a list of run steps belonging to a run. ## /threads/{thread_id}/runs/{run_id}/steps/{step_id} ### get #### operationId getRunStep #### tags - Assistants #### summary Retrieve 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. See the [file search tool documentation](https://platform.openai.com/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](https://platform.openai.com/docs/api-reference/run-steps/step-object) object matching the specified ID. ##### examples ###### 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 } } ###### 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( api_key="My API Key", ) run_step = client.beta.threads.runs.steps.retrieve( step_id="step_id", thread_id="thread_id", run_id="run_id", ) print(run_step.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const runStep = await client.beta.threads.runs.steps.retrieve('step_id', { thread_id: 'thread_id', run_id: 'run_id', }); console.log(runStep.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) runStep, err := client.Beta.Threads.Runs.Steps.Get( context.TODO(), "thread_id", "run_id", "step_id", openai.BetaThreadRunStepGetParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", runStep.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.runs.steps.RunStep; import com.openai.models.beta.threads.runs.steps.StepRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); StepRetrieveParams params = StepRetrieveParams.builder() .threadId("thread_id") .runId("run_id") .stepId("step_id") .build(); RunStep runStep = client.beta().threads().runs().steps().retrieve(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run_step = openai.beta.threads.runs.steps.retrieve("step_id", thread_id: "thread_id", run_id: "run_id") puts(run_step) #### description Retrieves a run step. ## /threads/{thread_id}/runs/{run_id}/submit_tool_outputs ### post #### operationId submitToolOuputsToRun #### tags - Assistants #### summary Submit tool outputs to run #### parameters ##### in path ##### name thread_id ##### required true ##### schema ###### type string ##### description The ID of the [thread](https://platform.openai.com/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](https://platform.openai.com/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( api_key="My API Key", ) run = client.beta.threads.runs.submit_tool_outputs( run_id="run_id", thread_id="thread_id", tool_outputs=[{}], ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.beta.threads.runs.submitToolOutputs('run_id', { thread_id: 'thread_id', tool_outputs: [{}], }); console.log(run.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) run, err := client.Beta.Threads.Runs.SubmitToolOutputs( context.TODO(), "thread_id", "run_id", openai.BetaThreadRunSubmitToolOutputsParams{ ToolOutputs: []openai.BetaThreadRunSubmitToolOutputsParamsToolOutput{openai.BetaThreadRunSubmitToolOutputsParamsToolOutput{ }}, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", run.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.runs.Run; import com.openai.models.beta.threads.runs.RunSubmitToolOutputsParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunSubmitToolOutputsParams params = RunSubmitToolOutputsParams.builder() .threadId("thread_id") .runId("run_id") .addToolOutput(RunSubmitToolOutputsParams.ToolOutput.builder().build()) .build(); Run run = client.beta().threads().runs().submitToolOutputs(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.beta.threads.runs.submit_tool_outputs("run_id", thread_id: "thread_id", tool_outputs: [{}]) puts(run) ###### 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( api_key="My API Key", ) run = client.beta.threads.runs.submit_tool_outputs( run_id="run_id", thread_id="thread_id", tool_outputs=[{}], ) print(run.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const run = await client.beta.threads.runs.submitToolOutputs('run_id', { thread_id: 'thread_id', tool_outputs: [{}], }); console.log(run.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) run, err := client.Beta.Threads.Runs.SubmitToolOutputs( context.TODO(), "thread_id", "run_id", openai.BetaThreadRunSubmitToolOutputsParams{ ToolOutputs: []openai.BetaThreadRunSubmitToolOutputsParamsToolOutput{openai.BetaThreadRunSubmitToolOutputsParamsToolOutput{ }}, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", run.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.threads.runs.Run; import com.openai.models.beta.threads.runs.RunSubmitToolOutputsParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); RunSubmitToolOutputsParams params = RunSubmitToolOutputsParams.builder() .threadId("thread_id") .runId("run_id") .addToolOutput(RunSubmitToolOutputsParams.ToolOutput.builder().build()) .build(); Run run = client.beta().threads().runs().submitToolOutputs(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") run = openai.beta.threads.runs.submit_tool_outputs("run_id", thread_id: "thread_id", tool_outputs: [{}]) puts(run) ###### 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] #### description 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. ## /uploads ### post #### operationId createUpload #### tags - Uploads #### summary Create upload #### 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](https://platform.openai.com/docs/api-reference/uploads/object) object with status `pending`. ##### examples ###### response { "id": "upload_abc123", "object": "upload", "bytes": 2147483648, "created_at": 1719184911, "filename": "training_examples.jsonl", "purpose": "fine-tune", "status": "pending", "expires_at": 1719127296 } ###### 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", "expires_after": { "anchor": "created_at", "seconds": 3600 } }' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const upload = await client.uploads.create({ bytes: 0, filename: 'filename', mime_type: 'mime_type', purpose: 'assistants', }); console.log(upload.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) upload = client.uploads.create( bytes=0, filename="filename", mime_type="mime_type", purpose="assistants", ) print(upload.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) upload, err := client.Uploads.New(context.TODO(), openai.UploadNewParams{ Bytes: 0, Filename: "filename", MimeType: "mime_type", Purpose: openai.FilePurposeAssistants, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", upload.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.files.FilePurpose; import com.openai.models.uploads.Upload; import com.openai.models.uploads.UploadCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); UploadCreateParams params = UploadCreateParams.builder() .bytes(0L) .filename("filename") .mimeType("mime_type") .purpose(FilePurpose.ASSISTANTS) .build(); Upload upload = client.uploads().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") upload = openai.uploads.create(bytes: 0, filename: "filename", mime_type: "mime_type", purpose: :assistants) puts(upload) #### description Creates an intermediate [Upload](https://platform.openai.com/docs/api-reference/uploads/object) object that you can add [Parts](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/api-reference/files/create). ## /uploads/{upload_id}/cancel ### post #### operationId cancelUpload #### tags - Uploads #### summary Cancel upload #### 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](https://platform.openai.com/docs/api-reference/uploads/object) object with status `cancelled`. ##### examples ###### response { "id": "upload_abc123", "object": "upload", "bytes": 2147483648, "created_at": 1719184911, "filename": "training_examples.jsonl", "purpose": "fine-tune", "status": "cancelled", "expires_at": 1719127296 } ###### request ####### curl curl https://api.openai.com/v1/uploads/upload_abc123/cancel ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const upload = await client.uploads.cancel('upload_abc123'); console.log(upload.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) upload = client.uploads.cancel( "upload_abc123", ) print(upload.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) upload, err := client.Uploads.Cancel(context.TODO(), "upload_abc123") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", upload.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.uploads.Upload; import com.openai.models.uploads.UploadCancelParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); Upload upload = client.uploads().cancel("upload_abc123"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") upload = openai.uploads.cancel("upload_abc123") puts(upload) #### description Cancels the Upload. No Parts may be added after an Upload is cancelled. ## /uploads/{upload_id}/complete ### post #### operationId completeUpload #### tags - Uploads #### summary Complete upload #### 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](https://platform.openai.com/docs/api-reference/uploads/object) object with status `completed` with an additional `file` property containing the created usable File object. ##### examples ###### 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, "expires_at": 1719127296, "filename": "training_examples.jsonl", "purpose": "fine-tune", } } ###### request ####### curl curl https://api.openai.com/v1/uploads/upload_abc123/complete -d '{ "part_ids": ["part_def456", "part_ghi789"] }' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const upload = await client.uploads.complete('upload_abc123', { part_ids: ['string'] }); console.log(upload.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) upload = client.uploads.complete( upload_id="upload_abc123", part_ids=["string"], ) print(upload.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) upload, err := client.Uploads.Complete( context.TODO(), "upload_abc123", openai.UploadCompleteParams{ PartIDs: []string{"string"}, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", upload.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.uploads.Upload; import com.openai.models.uploads.UploadCompleteParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); UploadCompleteParams params = UploadCompleteParams.builder() .uploadId("upload_abc123") .addPartId("string") .build(); Upload upload = client.uploads().complete(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") upload = openai.uploads.complete("upload_abc123", part_ids: ["string"]) puts(upload) #### description Completes the [Upload](https://platform.openai.com/docs/api-reference/uploads/object). Within the returned Upload object, there is a nested [File](https://platform.openai.com/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. ## /uploads/{upload_id}/parts ### post #### operationId addUploadPart #### tags - Uploads #### summary Add upload part #### 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](https://platform.openai.com/docs/api-reference/uploads/part-object) object. ##### examples ###### response { "id": "part_def456", "object": "upload.part", "created_at": 1719185911, "upload_id": "upload_abc123" } ###### request ####### curl curl https://api.openai.com/v1/uploads/upload_abc123/parts -F data="aHR0cHM6Ly9hcGkub3BlbmFpLmNvbS92MS91cGxvYWRz..." ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const uploadPart = await client.uploads.parts.create('upload_abc123', { data: fs.createReadStream('path/to/file'), }); console.log(uploadPart.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) upload_part = client.uploads.parts.create( upload_id="upload_abc123", data=b"raw file contents", ) print(upload_part.id) ####### go package main import ( "bytes" "context" "fmt" "io" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) uploadPart, err := client.Uploads.Parts.New( context.TODO(), "upload_abc123", openai.UploadPartNewParams{ Data: io.Reader(bytes.NewBuffer([]byte("some file contents"))), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", uploadPart.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.uploads.parts.PartCreateParams; import com.openai.models.uploads.parts.UploadPart; import java.io.ByteArrayInputStream; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); PartCreateParams params = PartCreateParams.builder() .uploadId("upload_abc123") .data(ByteArrayInputStream("some content".getBytes())) .build(); UploadPart uploadPart = client.uploads().parts().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") upload_part = openai.uploads.parts.create("upload_abc123", data: Pathname(__FILE__)) puts(upload_part) #### description Adds a [Part](https://platform.openai.com/docs/api-reference/uploads/part-object) to an [Upload](https://platform.openai.com/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](https://platform.openai.com/docs/api-reference/uploads/complete). ## /vector_stores ### get #### operationId listVectorStores #### tags - Vector stores #### summary List 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](https://platform.openai.com/docs/api-reference/vector-stores/object) objects. ##### examples ###### 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 } ###### 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( api_key="My API Key", ) page = client.vector_stores.list() page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const vectorStore of client.vectorStores.list()) { console.log(vectorStore.id); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.VectorStores.List(context.TODO(), openai.VectorStoreListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.VectorStoreListPage; import com.openai.models.vectorstores.VectorStoreListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); VectorStoreListPage page = client.vectorStores().list(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.vector_stores.list puts(page) #### description Returns a list of vector stores. ### post #### operationId createVectorStore #### tags - Vector stores #### summary Create 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](https://platform.openai.com/docs/api-reference/vector-stores/object) object. ##### examples ###### 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 } } ###### 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( api_key="My API Key", ) vector_store = client.vector_stores.create() print(vector_store.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const vectorStore = await client.vectorStores.create(); console.log(vectorStore.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) vectorStore, err := client.VectorStores.New(context.TODO(), openai.VectorStoreNewParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", vectorStore.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.VectorStore; import com.openai.models.vectorstores.VectorStoreCreateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); VectorStore vectorStore = client.vectorStores().create(); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") vector_store = openai.vector_stores.create puts(vector_store) #### description Create a vector store. ## /vector_stores/{vector_store_id} ### get #### operationId getVectorStore #### tags - Vector stores #### summary Retrieve 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](https://platform.openai.com/docs/api-reference/vector-stores/object) object matching the specified ID. ##### examples ###### response { "id": "vs_abc123", "object": "vector_store", "created_at": 1699061776 } ###### 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( api_key="My API Key", ) vector_store = client.vector_stores.retrieve( "vector_store_id", ) print(vector_store.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const vectorStore = await client.vectorStores.retrieve('vector_store_id'); console.log(vectorStore.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) vectorStore, err := client.VectorStores.Get(context.TODO(), "vector_store_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", vectorStore.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.VectorStore; import com.openai.models.vectorstores.VectorStoreRetrieveParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); VectorStore vectorStore = client.vectorStores().retrieve("vector_store_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") vector_store = openai.vector_stores.retrieve("vector_store_id") puts(vector_store) #### description Retrieves a vector store. ### post #### operationId modifyVectorStore #### tags - Vector stores #### summary Modify 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](https://platform.openai.com/docs/api-reference/vector-stores/object) object. ##### examples ###### 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 } } ###### 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( api_key="My API Key", ) vector_store = client.vector_stores.update( vector_store_id="vector_store_id", ) print(vector_store.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const vectorStore = await client.vectorStores.update('vector_store_id'); console.log(vectorStore.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) vectorStore, err := client.VectorStores.Update( context.TODO(), "vector_store_id", openai.VectorStoreUpdateParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", vectorStore.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.VectorStore; import com.openai.models.vectorstores.VectorStoreUpdateParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); VectorStore vectorStore = client.vectorStores().update("vector_store_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") vector_store = openai.vector_stores.update("vector_store_id") puts(vector_store) #### description Modifies a vector store. ### delete #### operationId deleteVectorStore #### tags - Vector stores #### summary Delete 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 ###### response { id: "vs_abc123", object: "vector_store.deleted", deleted: true } ###### 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( api_key="My API Key", ) vector_store_deleted = client.vector_stores.delete( "vector_store_id", ) print(vector_store_deleted.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const vectorStoreDeleted = await client.vectorStores.delete('vector_store_id'); console.log(vectorStoreDeleted.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) vectorStoreDeleted, err := client.VectorStores.Delete(context.TODO(), "vector_store_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", vectorStoreDeleted.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.VectorStoreDeleteParams; import com.openai.models.vectorstores.VectorStoreDeleted; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); VectorStoreDeleted vectorStoreDeleted = client.vectorStores().delete("vector_store_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") vector_store_deleted = openai.vector_stores.delete("vector_store_id") puts(vector_store_deleted) #### description Delete a vector store. ## /vector_stores/{vector_store_id}/file_batches ### post #### operationId createVectorStoreFileBatch #### tags - Vector stores #### summary Create 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](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/batch-object) object. ##### examples ###### 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, } } ###### 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( api_key="My API Key", ) vector_store_file_batch = client.vector_stores.file_batches.create( vector_store_id="vs_abc123", file_ids=["string"], ) print(vector_store_file_batch.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const vectorStoreFileBatch = await client.vectorStores.fileBatches.create('vs_abc123', { file_ids: ['string'], }); console.log(vectorStoreFileBatch.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) vectorStoreFileBatch, err := client.VectorStores.FileBatches.New( context.TODO(), "vs_abc123", openai.VectorStoreFileBatchNewParams{ FileIDs: []string{"string"}, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", vectorStoreFileBatch.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.filebatches.FileBatchCreateParams; import com.openai.models.vectorstores.filebatches.VectorStoreFileBatch; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileBatchCreateParams params = FileBatchCreateParams.builder() .vectorStoreId("vs_abc123") .addFileId("string") .build(); VectorStoreFileBatch vectorStoreFileBatch = client.vectorStores().fileBatches().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") vector_store_file_batch = openai.vector_stores.file_batches.create("vs_abc123", file_ids: ["string"]) puts(vector_store_file_batch) #### description Create a vector store file batch. ## /vector_stores/{vector_store_id}/file_batches/{batch_id} ### get #### operationId getVectorStoreFileBatch #### tags - Vector stores #### summary Retrieve 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](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/batch-object) object. ##### examples ###### 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, } } ###### 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( api_key="My API Key", ) vector_store_file_batch = client.vector_stores.file_batches.retrieve( batch_id="vsfb_abc123", vector_store_id="vs_abc123", ) print(vector_store_file_batch.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const vectorStoreFileBatch = await client.vectorStores.fileBatches.retrieve('vsfb_abc123', { vector_store_id: 'vs_abc123', }); console.log(vectorStoreFileBatch.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) vectorStoreFileBatch, err := client.VectorStores.FileBatches.Get( context.TODO(), "vs_abc123", "vsfb_abc123", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", vectorStoreFileBatch.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.filebatches.FileBatchRetrieveParams; import com.openai.models.vectorstores.filebatches.VectorStoreFileBatch; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileBatchRetrieveParams params = FileBatchRetrieveParams.builder() .vectorStoreId("vs_abc123") .batchId("vsfb_abc123") .build(); VectorStoreFileBatch vectorStoreFileBatch = client.vectorStores().fileBatches().retrieve(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") vector_store_file_batch = openai.vector_stores.file_batches.retrieve("vsfb_abc123", vector_store_id: "vs_abc123") puts(vector_store_file_batch) #### description Retrieves a vector store file batch. ## /vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel ### post #### operationId cancelVectorStoreFileBatch #### tags - Vector stores #### summary Cancel vector store file batch #### 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 ###### 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, } } ###### 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( api_key="My API Key", ) vector_store_file_batch = client.vector_stores.file_batches.cancel( batch_id="batch_id", vector_store_id="vector_store_id", ) print(vector_store_file_batch.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const vectorStoreFileBatch = await client.vectorStores.fileBatches.cancel('batch_id', { vector_store_id: 'vector_store_id', }); console.log(vectorStoreFileBatch.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) vectorStoreFileBatch, err := client.VectorStores.FileBatches.Cancel( context.TODO(), "vector_store_id", "batch_id", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", vectorStoreFileBatch.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.filebatches.FileBatchCancelParams; import com.openai.models.vectorstores.filebatches.VectorStoreFileBatch; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileBatchCancelParams params = FileBatchCancelParams.builder() .vectorStoreId("vector_store_id") .batchId("batch_id") .build(); VectorStoreFileBatch vectorStoreFileBatch = client.vectorStores().fileBatches().cancel(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") vector_store_file_batch = openai.vector_stores.file_batches.cancel("batch_id", vector_store_id: "vector_store_id") puts(vector_store_file_batch) #### description Cancel a vector store file batch. This attempts to cancel the processing of files in this batch as soon as possible. ## /vector_stores/{vector_store_id}/file_batches/{batch_id}/files ### get #### operationId listFilesInVectorStoreBatch #### tags - Vector stores #### summary List 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](https://platform.openai.com/docs/api-reference/vector-stores-files/file-object) objects. ##### examples ###### 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 } ###### 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( api_key="My API Key", ) page = client.vector_stores.file_batches.list_files( batch_id="batch_id", vector_store_id="vector_store_id", ) page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const vectorStoreFile of client.vectorStores.fileBatches.listFiles('batch_id', { vector_store_id: 'vector_store_id', })) { console.log(vectorStoreFile.id); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.VectorStores.FileBatches.ListFiles( context.TODO(), "vector_store_id", "batch_id", openai.VectorStoreFileBatchListFilesParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.filebatches.FileBatchListFilesPage; import com.openai.models.vectorstores.filebatches.FileBatchListFilesParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileBatchListFilesParams params = FileBatchListFilesParams.builder() .vectorStoreId("vector_store_id") .batchId("batch_id") .build(); FileBatchListFilesPage page = client.vectorStores().fileBatches().listFiles(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.vector_stores.file_batches.list_files("batch_id", vector_store_id: "vector_store_id") puts(page) #### description Returns a list of vector store files in a batch. ## /vector_stores/{vector_store_id}/files ### get #### operationId listVectorStoreFiles #### tags - Vector stores #### summary List 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](https://platform.openai.com/docs/api-reference/vector-stores-files/file-object) objects. ##### examples ###### 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 } ###### 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( api_key="My API Key", ) page = client.vector_stores.files.list( vector_store_id="vector_store_id", ) page = page.data[0] print(page.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const vectorStoreFile of client.vectorStores.files.list('vector_store_id')) { console.log(vectorStoreFile.id); } ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.VectorStores.Files.List( context.TODO(), "vector_store_id", openai.VectorStoreFileListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.files.FileListPage; import com.openai.models.vectorstores.files.FileListParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileListPage page = client.vectorStores().files().list("vector_store_id"); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.vector_stores.files.list("vector_store_id") puts(page) #### description Returns a list of vector store files. ### post #### operationId createVectorStoreFile #### tags - Vector stores #### summary Create 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 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](https://platform.openai.com/docs/api-reference/vector-stores-files/file-object) object. ##### examples ###### response { "id": "file-abc123", "object": "vector_store.file", "created_at": 1699061776, "usage_bytes": 1234, "vector_store_id": "vs_abcd", "status": "completed", "last_error": null } ###### 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( api_key="My API Key", ) vector_store_file = client.vector_stores.files.create( vector_store_id="vs_abc123", file_id="file_id", ) print(vector_store_file.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const vectorStoreFile = await client.vectorStores.files.create('vs_abc123', { file_id: 'file_id' }); console.log(vectorStoreFile.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) vectorStoreFile, err := client.VectorStores.Files.New( context.TODO(), "vs_abc123", openai.VectorStoreFileNewParams{ FileID: "file_id", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", vectorStoreFile.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.files.FileCreateParams; import com.openai.models.vectorstores.files.VectorStoreFile; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileCreateParams params = FileCreateParams.builder() .vectorStoreId("vs_abc123") .fileId("file_id") .build(); VectorStoreFile vectorStoreFile = client.vectorStores().files().create(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") vector_store_file = openai.vector_stores.files.create("vs_abc123", file_id: "file_id") puts(vector_store_file) #### description Create a vector store file by attaching a [File](https://platform.openai.com/docs/api-reference/files) to a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object). ## /vector_stores/{vector_store_id}/files/{file_id} ### get #### operationId getVectorStoreFile #### tags - Vector stores #### summary Retrieve 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](https://platform.openai.com/docs/api-reference/vector-stores-files/file-object) object. ##### examples ###### response { "id": "file-abc123", "object": "vector_store.file", "created_at": 1699061776, "vector_store_id": "vs_abcd", "status": "completed", "last_error": null } ###### 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( api_key="My API Key", ) vector_store_file = client.vector_stores.files.retrieve( file_id="file-abc123", vector_store_id="vs_abc123", ) print(vector_store_file.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const vectorStoreFile = await client.vectorStores.files.retrieve('file-abc123', { vector_store_id: 'vs_abc123', }); console.log(vectorStoreFile.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) vectorStoreFile, err := client.VectorStores.Files.Get( context.TODO(), "vs_abc123", "file-abc123", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", vectorStoreFile.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.files.FileRetrieveParams; import com.openai.models.vectorstores.files.VectorStoreFile; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileRetrieveParams params = FileRetrieveParams.builder() .vectorStoreId("vs_abc123") .fileId("file-abc123") .build(); VectorStoreFile vectorStoreFile = client.vectorStores().files().retrieve(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") vector_store_file = openai.vector_stores.files.retrieve("file-abc123", vector_store_id: "vs_abc123") puts(vector_store_file) #### description Retrieves a vector store file. ### delete #### operationId deleteVectorStoreFile #### tags - Vector stores #### summary Delete vector store file #### 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 ###### response { id: "file-abc123", object: "vector_store.file.deleted", deleted: true } ###### 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( api_key="My API Key", ) vector_store_file_deleted = client.vector_stores.files.delete( file_id="file_id", vector_store_id="vector_store_id", ) print(vector_store_file_deleted.id) ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const vectorStoreFileDeleted = await client.vectorStores.files.delete('file_id', { vector_store_id: 'vector_store_id', }); console.log(vectorStoreFileDeleted.id); ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) vectorStoreFileDeleted, err := client.VectorStores.Files.Delete( context.TODO(), "vector_store_id", "file_id", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", vectorStoreFileDeleted.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.files.FileDeleteParams; import com.openai.models.vectorstores.files.VectorStoreFileDeleted; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileDeleteParams params = FileDeleteParams.builder() .vectorStoreId("vector_store_id") .fileId("file_id") .build(); VectorStoreFileDeleted vectorStoreFileDeleted = client.vectorStores().files().delete(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") vector_store_file_deleted = openai.vector_stores.files.delete("file_id", vector_store_id: "vector_store_id") puts(vector_store_file_deleted) #### description 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](https://platform.openai.com/docs/api-reference/files/delete) endpoint. ### post #### operationId updateVectorStoreFileAttributes #### tags - Vector stores #### summary Update vector store file attributes #### 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](https://platform.openai.com/docs/api-reference/vector-stores-files/file-object) object. ##### examples ###### 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} } ###### 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}}' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); const vectorStoreFile = await client.vectorStores.files.update('file-abc123', { vector_store_id: 'vs_abc123', attributes: { foo: 'string' }, }); console.log(vectorStoreFile.id); ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) vector_store_file = client.vector_stores.files.update( file_id="file-abc123", vector_store_id="vs_abc123", attributes={ "foo": "string" }, ) print(vector_store_file.id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) vectorStoreFile, err := client.VectorStores.Files.Update( context.TODO(), "vs_abc123", "file-abc123", openai.VectorStoreFileUpdateParams{ Attributes: map[string]openai.VectorStoreFileUpdateParamsAttributeUnion{ "foo": openai.VectorStoreFileUpdateParamsAttributeUnion{ OfString: openai.String("string"), }, }, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", vectorStoreFile.ID) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.core.JsonValue; import com.openai.models.vectorstores.files.FileUpdateParams; import com.openai.models.vectorstores.files.VectorStoreFile; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileUpdateParams params = FileUpdateParams.builder() .vectorStoreId("vs_abc123") .fileId("file-abc123") .attributes(FileUpdateParams.Attributes.builder() .putAdditionalProperty("foo", JsonValue.from("string")) .build()) .build(); VectorStoreFile vectorStoreFile = client.vectorStores().files().update(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") vector_store_file = openai.vector_stores.files.update( "file-abc123", vector_store_id: "vs_abc123", attributes: {foo: "string"} ) puts(vector_store_file) #### description Update attributes on a vector store file. ## /vector_stores/{vector_store_id}/files/{file_id}/content ### get #### operationId retrieveVectorStoreFileContent #### tags - Vector stores #### summary Retrieve vector store file content #### 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 ###### response { "file_id": "file-abc123", "filename": "example.txt", "attributes": {"key": "value"}, "content": [ {"type": "text", "text": "..."}, ... ] } ###### request ####### curl curl \ https://api.openai.com/v1/vector_stores/vs_abc123/files/file-abc123/content \ -H "Authorization: Bearer $OPENAI_API_KEY" ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const fileContentResponse of client.vectorStores.files.content('file-abc123', { vector_store_id: 'vs_abc123', })) { console.log(fileContentResponse.text); } ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.vector_stores.files.content( file_id="file-abc123", vector_store_id="vs_abc123", ) page = page.data[0] print(page.text) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.VectorStores.Files.Content( context.TODO(), "vs_abc123", "file-abc123", ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.files.FileContentPage; import com.openai.models.vectorstores.files.FileContentParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); FileContentParams params = FileContentParams.builder() .vectorStoreId("vs_abc123") .fileId("file-abc123") .build(); FileContentPage page = client.vectorStores().files().content(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.vector_stores.files.content("file-abc123", vector_store_id: "vs_abc123") puts(page) #### description Retrieve the parsed contents of a vector store file. ## /vector_stores/{vector_store_id}/search ### post #### operationId searchVectorStore #### tags - Vector stores #### summary Search vector store #### 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 ###### 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 } ###### 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": {...}}' ####### node.js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'My API Key', }); // Automatically fetches more pages as needed. for await (const vectorStoreSearchResponse of client.vectorStores.search('vs_abc123', { query: 'string' })) { console.log(vectorStoreSearchResponse.file_id); } ####### python from openai import OpenAI client = OpenAI( api_key="My API Key", ) page = client.vector_stores.search( vector_store_id="vs_abc123", query="string", ) page = page.data[0] print(page.file_id) ####### go package main import ( "context" "fmt" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { client := openai.NewClient( option.WithAPIKey("My API Key"), ) page, err := client.VectorStores.Search( context.TODO(), "vs_abc123", openai.VectorStoreSearchParams{ Query: openai.VectorStoreSearchParamsQueryUnion{ OfString: openai.String("string"), }, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ####### java package com.openai.example; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.vectorstores.VectorStoreSearchPage; import com.openai.models.vectorstores.VectorStoreSearchParams; public final class Main { private Main() {} public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.fromEnv(); VectorStoreSearchParams params = VectorStoreSearchParams.builder() .vectorStoreId("vs_abc123") .query("string") .build(); VectorStoreSearchPage page = client.vectorStores().search(params); } } ####### ruby require "openai" openai = OpenAI::Client.new(api_key: "My API Key") page = openai.vector_stores.search("vs_abc123", query: "string") puts(page) #### description Search a vector store for relevant chunks based on a query and file attributes filter. # webhooks ## batch_cancelled ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookBatchCancelled #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## batch_completed ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookBatchCompleted #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## batch_expired ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookBatchExpired #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## batch_failed ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookBatchFailed #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## eval_run_canceled ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookEvalRunCanceled #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## eval_run_failed ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookEvalRunFailed #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## eval_run_succeeded ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookEvalRunSucceeded #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## fine_tuning_job_cancelled ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookFineTuningJobCancelled #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## fine_tuning_job_failed ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookFineTuningJobFailed #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## fine_tuning_job_succeeded ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookFineTuningJobSucceeded #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## response_cancelled ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookResponseCancelled #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## response_completed ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookResponseCompleted #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## response_failed ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookResponseFailed #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. ## response_incomplete ### post #### requestBody ##### description The event payload sent by the API. ##### content ###### application/json ####### schema ######## $ref #/components/schemas/WebhookResponseIncomplete #### responses ##### 200 ###### description Return a 200 status code to acknowledge receipt of the event. Non-200 status codes will be retried. # 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 #### description Represents an individual Admin API key in an org. #### properties ##### object ###### type string ###### example organization.admin_api_key ###### description The object type, which is always `organization.admin_api_key` ###### x-stainless-const true ##### id ###### type string ###### example key_abc ###### description The identifier, which can be referenced in API endpoints ##### name ###### type string ###### example Administration Key ###### description The name of the API key ##### redacted_value ###### type string ###### example sk-admin...def ###### description The redacted value of the API key ##### value ###### type string ###### example sk-admin-1234abcd ###### description The value of the API key. Only shown on create. ##### created_at ###### type integer ###### format int64 ###### example 1711471533 ###### description The Unix timestamp (in seconds) of when the API key was created ##### last_used_at ###### type integer ###### format int64 ###### nullable true ###### example 1711471534 ###### description The Unix timestamp (in seconds) of when the API key was last used ##### owner ###### type object ###### properties ####### type ######## type string ######## example user ######## description Always `user` ####### object ######## type string ######## example organization.user ######## description The object type, which is always organization.user ####### id ######## type string ######## example sa_456 ######## description The identifier, which can be referenced in API endpoints ####### name ######## type string ######## example My Service Account ######## description The name of the user ####### created_at ######## type integer ######## format int64 ######## example 1711471533 ######## description The Unix timestamp (in seconds) of when the user was created ####### role ######## type string ######## example owner ######## description Always `owner` #### required - object - redacted_value - name - created_at - last_used_at - id - owner #### x-oaiMeta ##### name The admin API key object ##### example { "object": "organization.admin_api_key", "id": "key_abc", "name": "Main Admin Key", "redacted_value": "sk-admin...xyz", "created_at": 1711471533, "last_used_at": 1711471534, "owner": { "type": "user", "object": "organization.user", "id": "user_123", "name": "John Doe", "created_at": 1711471533, "role": "owner" } } ### 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](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/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 ####### $ref #/components/schemas/AssistantTool ##### 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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/assistants/overview) to learn how to integrate the Assistants API with streaming. #### x-oaiMeta ##### name Assistant stream events ##### beta true #### anyOf ##### $ref #/components/schemas/ThreadStreamEvent ##### $ref #/components/schemas/RunStreamEvent ##### $ref #/components/schemas/RunStepStreamEvent ##### $ref #/components/schemas/MessageStreamEvent ##### $ref #/components/schemas/ErrorEvent ##### x-stainless-variantName error_event #### discriminator ##### propertyName event ### AssistantSupportedModels #### type string #### enum - gpt-5 - gpt-5-mini - gpt-5-nano - gpt-5-2025-08-07 - gpt-5-mini-2025-08-07 - gpt-5-nano-2025-08-07 - gpt-4.1 - gpt-4.1-mini - gpt-4.1-nano - gpt-4.1-2025-04-14 - gpt-4.1-mini-2025-04-14 - gpt-4.1-nano-2025-04-14 - o3-mini - o3-mini-2025-01-31 - o1 - o1-2024-12-17 - gpt-4o - gpt-4o-2024-11-20 - gpt-4o-2024-08-06 - gpt-4o-2024-05-13 - gpt-4o-mini - gpt-4o-mini-2024-07-18 - gpt-4.5-preview - gpt-4.5-preview-2025-02-27 - gpt-4-turbo - gpt-4-turbo-2024-04-09 - gpt-4-0125-preview - gpt-4-turbo-preview - gpt-4-1106-preview - gpt-4-vision-preview - gpt-4 - gpt-4-0314 - gpt-4-0613 - gpt-4-32k - gpt-4-32k-0314 - gpt-4-32k-0613 - gpt-3.5-turbo - gpt-3.5-turbo-16k - gpt-3.5-turbo-0613 - gpt-3.5-turbo-1106 - gpt-3.5-turbo-0125 - gpt-3.5-turbo-16k-0613 ### 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](https://platform.openai.com/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](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/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](https://platform.openai.com/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. #### anyOf ##### 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 ### 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. #### anyOf ##### 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 ##### title Auto ##### $ref #/components/schemas/AssistantsNamedToolChoice ### AssistantsNamedToolChoice #### type object #### description Specifies a tool the model should use. Use to force the model to call a specific tool. #### properties ##### type ###### type string ###### enum - function - code_interpreter - file_search ###### description The type of the tool. If type is `function`, the function name must be set ##### function ###### type object ###### properties ####### name ######## type string ######## description The name of the function to call. ###### required - name #### required - type ### AudioResponseFormat #### description The format of the output, in one of these options: `json`, `text`, `srt`, `verbose_json`, or `vtt`. For `gpt-4o-transcribe` and `gpt-4o-mini-transcribe`, the only supported format is `json`. #### type string #### enum - json - text - srt - verbose_json - vtt #### default json ### AuditLog #### type object #### description A log of a user action or configuration change within this organization. #### properties ##### id ###### type string ###### description The ID of this log. ##### type ###### $ref #/components/schemas/AuditLogEventType ##### effective_at ###### type integer ###### description The Unix timestamp (in seconds) of the event. ##### project ###### type object ###### description The project that the action was scoped to. Absent for actions not scoped to projects. Note that any admin actions taken via Admin API keys are associated with the default project. ###### properties ####### id ######## type string ######## description The project ID. ####### name ######## type string ######## description The project title. ##### actor ###### $ref #/components/schemas/AuditLogActor ##### api_key.created ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The tracking ID of the API key. ####### data ######## type object ######## description The payload used to create the API key. ######## properties ######### scopes ########## type array ########## items ########### type string ########## description A list of scopes allowed for the API key, e.g. `["api.model.request"]` ##### api_key.updated ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The tracking ID of the API key. ####### changes_requested ######## type object ######## description The payload used to update the API key. ######## properties ######### scopes ########## type array ########## items ########### type string ########## description A list of scopes allowed for the API key, e.g. `["api.model.request"]` ##### api_key.deleted ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The tracking ID of the API key. ##### checkpoint_permission.created ###### type object ###### description The project and fine-tuned model checkpoint that the checkpoint permission was created for. ###### properties ####### id ######## type string ######## description The ID of the checkpoint permission. ####### data ######## type object ######## description The payload used to create the checkpoint permission. ######## properties ######### project_id ########## type string ########## description The ID of the project that the checkpoint permission was created for. ######### fine_tuned_model_checkpoint ########## type string ########## description The ID of the fine-tuned model checkpoint. ##### checkpoint_permission.deleted ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The ID of the checkpoint permission. ##### invite.sent ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The ID of the invite. ####### data ######## type object ######## description The payload used to create the invite. ######## properties ######### email ########## type string ########## description The email invited to the organization. ######### role ########## type string ########## description The role the email was invited to be. Is either `owner` or `member`. ##### invite.accepted ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The ID of the invite. ##### invite.deleted ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The ID of the invite. ##### login.failed ###### type object ###### description The details for events with this `type`. ###### properties ####### error_code ######## type string ######## description The error code of the failure. ####### error_message ######## type string ######## description The error message of the failure. ##### logout.failed ###### type object ###### description The details for events with this `type`. ###### properties ####### error_code ######## type string ######## description The error code of the failure. ####### error_message ######## type string ######## description The error message of the failure. ##### organization.updated ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The organization ID. ####### changes_requested ######## type object ######## description The payload used to update the organization settings. ######## properties ######### title ########## type string ########## description The organization title. ######### description ########## type string ########## description The organization description. ######### name ########## type string ########## description The organization name. ######### threads_ui_visibility ########## type string ########## description Visibility of the threads page which shows messages created with the Assistants API and Playground. One of `ANY_ROLE`, `OWNERS`, or `NONE`. ######### usage_dashboard_visibility ########## type string ########## description Visibility of the usage dashboard which shows activity and costs for your organization. One of `ANY_ROLE` or `OWNERS`. ######### api_call_logging ########## type string ########## description How your organization logs data from supported API calls. One of `disabled`, `enabled_per_call`, `enabled_for_all_projects`, or `enabled_for_selected_projects` ######### api_call_logging_project_ids ########## type string ########## description The list of project ids if api_call_logging is set to `enabled_for_selected_projects` ##### project.created ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The project ID. ####### data ######## type object ######## description The payload used to create the project. ######## properties ######### name ########## type string ########## description The project name. ######### title ########## type string ########## description The title of the project as seen on the dashboard. ##### project.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 project. ######## properties ######### title ########## type string ########## description The title of the project as seen on the dashboard. ##### project.archived ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The project ID. ##### rate_limit.updated ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The rate limit ID ####### changes_requested ######## type object ######## description The payload used to update the rate limits. ######## 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. ##### rate_limit.deleted ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The rate limit ID ##### service_account.created ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The service account ID. ####### data ######## type object ######## description The payload used to create the service account. ######## properties ######### role ########## type string ########## description The role of the service account. Is either `owner` or `member`. ##### service_account.updated ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The service account ID. ####### changes_requested ######## type object ######## description The payload used to updated the service account. ######## properties ######### role ########## type string ########## 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`. ###### 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. ##### certificate.created ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The certificate ID. ####### name ######## type string ######## description The name of the certificate. ##### certificate.updated ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The certificate ID. ####### name ######## type string ######## description The name of the certificate. ##### certificate.deleted ###### type object ###### description The details for events with this `type`. ###### properties ####### id ######## type string ######## description The certificate ID. ####### name ######## type string ######## description The name of the certificate. ####### certificate ######## type string ######## description The certificate content in PEM format. ##### certificates.activated ###### type object ###### description The details for events with this `type`. ###### properties ####### certificates ######## type array ######## items ######### type object ######### properties ########## id ########### type string ########### description The certificate ID. ########## name ########### type string ########### description The name of the certificate. ##### certificates.deactivated ###### type object ###### description The details for events with this `type`. ###### properties ####### certificates ######## type array ######## items ######### type object ######### properties ########## id ########### type string ########### description The certificate ID. ########## name ########### type string ########### description The name of the certificate. #### required - id - type - 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. #### enum - api_key.created - api_key.updated - api_key.deleted - checkpoint_permission.created - checkpoint_permission.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 ######### $ref #/components/schemas/BatchError ##### 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 ###### $ref #/components/schemas/BatchRequestCounts ##### 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", } } ### BatchFileExpirationAfter #### type object #### title File expiration policy #### description The expiration policy for the output and/or error file that are generated for a batch. #### properties ##### anchor ###### description Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`. Note that the anchor is the file creation time, not the time the batch is created. ###### type string ###### enum - created_at ###### x-stainless-const true ##### seconds ###### description The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days). ###### type integer ###### minimum 3600 ###### maximum 2592000 #### required - anchor - seconds ### 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 ###### nullable true ###### properties ####### status_code ######## type integer ######## description The HTTP status code of the response ####### request_id ######## 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 ###### 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 ######## type string ######## description A machine-readable error code. ####### message ######## 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} ### Certificate #### type object #### description Represents an individual `certificate` uploaded to the organization. #### properties ##### object ###### type string ###### enum - certificate - organization.certificate - organization.project.certificate ###### description The object type. - If creating, updating, or getting a specific certificate, the object type is `certificate`. - If listing, activating, or deactivating certificates for the organization, the object type is `organization.certificate`. - If listing, activating, or deactivating certificates for a project, the object type is `organization.project.certificate`. ###### 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 certificate. ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the certificate was uploaded. ##### certificate_details ###### type object ###### properties ####### valid_at ######## type integer ######## description The Unix timestamp (in seconds) of when the certificate becomes valid. ####### expires_at ######## type integer ######## description The Unix timestamp (in seconds) of when the certificate expires. ####### content ######## type string ######## description The content of the certificate in PEM format. ##### active ###### type boolean ###### description Whether the certificate is currently active at the specified scope. Not returned when getting details for a specific certificate. #### required - object - id - name - created_at - certificate_details #### x-oaiMeta ##### name The certificate object ##### example { "object": "certificate", "id": "cert_abc", "name": "My Certificate", "created_at": 1234567, "certificate_details": { "valid_at": 1234567, "expires_at": 12345678, "content": "-----BEGIN CERTIFICATE----- MIIGAjCCA...6znFlOW+ -----END CERTIFICATE-----" } } ### ChatCompletionAllowedTools #### type object #### title Allowed tools #### description Constrains the tools available to the model to a pre-defined set. #### properties ##### mode ###### type string ###### enum - auto - required ###### description Constrains the tools available to the model to a pre-defined set. `auto` allows the model to pick from among the allowed tools and generate a message. `required` requires the model to call one or more of the allowed tools. ##### tools ###### type array ###### description A list of tool definitions that the model should be allowed to call. For the Chat Completions API, the list of tool definitions might look like: ```json [ { "type": "function", "function": { "name": "get_weather" } }, { "type": "function", "function": { "name": "get_time" } } ] ``` ###### items ####### type object ####### x-oaiExpandable false ####### description A tool definition that the model should be allowed to call. ####### additionalProperties true #### required - mode - tools ### ChatCompletionAllowedToolsChoice #### type object #### title Allowed tools #### description Constrains the tools available to the model to a pre-defined set. #### properties ##### type ###### type string ###### enum - allowed_tools ###### description Allowed tool configuration type. Always `allowed_tools`. ###### x-stainless-const true ##### allowed_tools ###### $ref #/components/schemas/ChatCompletionAllowedTools #### required - type - allowed_tools ### 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 #### x-stainless-variantName function_call_option ### 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 - object - data - first_id - last_id - has_more #### x-oaiMeta ##### name The chat completion list object ##### group chat ##### example { "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 } ### ChatCompletionMessageCustomToolCall #### type object #### title Custom tool call #### description A call to a custom tool created by the model. #### properties ##### id ###### type string ###### description The ID of the tool call. ##### type ###### type string ###### enum - custom ###### description The type of the tool. Always `custom`. ###### x-stainless-const true ##### custom ###### type object ###### description The custom tool that the model called. ###### properties ####### name ######## type string ######## description The name of the custom tool to call. ####### input ######## type string ######## description The input for the custom tool call generated by the model. ###### required - name - input #### required - id - type - custom ### ChatCompletionMessageList #### type object #### title ChatCompletionMessageList #### description An object representing a list of chat completion messages. #### 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 message objects. ###### items ####### allOf ######## $ref #/components/schemas/ChatCompletionResponseMessage ######## type object ######## required - id ######## properties ######### id ########## type string ########## description The identifier of the chat message. ######### content_parts ########## type array ########## nullable true ########## description If a content parts array was provided, this is an array of `text` and `image_url` parts. Otherwise, null. ########## items ########### anyOf ############ $ref #/components/schemas/ChatCompletionRequestMessageContentPartText ############ $ref #/components/schemas/ChatCompletionRequestMessageContentPartImage ##### first_id ###### type string ###### description The identifier of the first chat message in the data array. ##### last_id ###### type string ###### 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 #### title Function tool call #### description A call to a function tool created by the model. #### properties ##### 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 ###### 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 #### 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 ###### 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 ##### anyOf ###### $ref #/components/schemas/ChatCompletionMessageToolCall ###### $ref #/components/schemas/ChatCompletionMessageCustomToolCall ##### x-stainless-naming ###### python ####### model_name chat_completion_message_tool_call_union ####### param_model_name chat_completion_message_tool_call_union_param ##### discriminator ###### propertyName type ##### x-stainless-go-variant-constructor skip ### 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](https://platform.openai.com/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 Function tool choice #### 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 For function calling, the type is always `function`. ###### x-stainless-const true ##### function ###### type object ###### properties ####### name ######## type string ######## description The name of the function to call. ###### required - name #### required - type - function ### ChatCompletionNamedToolChoiceCustom #### type object #### title Custom tool choice #### description Specifies a tool the model should use. Use to force the model to call a specific custom tool. #### properties ##### type ###### type string ###### enum - custom ###### description For custom tool calling, the type is always `custom`. ###### x-stainless-const true ##### custom ###### type object ###### properties ####### name ######## type string ######## description The name of the custom tool to call. ###### required - name #### required - type - custom ### ChatCompletionRequestAssistantMessage #### type object #### title Assistant message #### description Messages sent by the model in response to user messages. #### properties ##### content ###### nullable true ###### description The contents of the assistant message. Required unless `tool_calls` or `function_call` is specified. ###### anyOf ####### 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 ##### 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 ###### type string ###### description An optional name for the participant. Provides the model information to differentiate between participants of the same role. ##### audio ###### type object ###### nullable true ###### description Data about a previous audio response from the model. [Learn more](https://platform.openai.com/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 ###### 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 ######## 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 - arguments - name #### required - role #### x-stainless-soft-required - content ### ChatCompletionRequestAssistantMessageContentPart #### anyOf ##### $ref #/components/schemas/ChatCompletionRequestMessageContentPartText ##### $ref #/components/schemas/ChatCompletionRequestMessageContentPartRefusal #### discriminator ##### propertyName type ### 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. ###### anyOf ####### 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 ###### 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 #### x-stainless-naming ##### go ###### variant_constructor DeveloperMessage ### ChatCompletionRequestFunctionMessage #### type object #### title Function message #### deprecated true #### properties ##### role ###### type string ###### enum - function ###### description The role of the messages author, in this case `function`. ###### 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. #### required - role - content - name ### ChatCompletionRequestMessage #### anyOf ##### $ref #/components/schemas/ChatCompletionRequestDeveloperMessage ##### $ref #/components/schemas/ChatCompletionRequestSystemMessage ##### $ref #/components/schemas/ChatCompletionRequestUserMessage ##### $ref #/components/schemas/ChatCompletionRequestAssistantMessage ##### $ref #/components/schemas/ChatCompletionRequestToolMessage ##### $ref #/components/schemas/ChatCompletionRequestFunctionMessage #### discriminator ##### propertyName role ### ChatCompletionRequestMessageContentPartAudio #### type object #### title Audio content part #### description Learn about [audio inputs](https://platform.openai.com/docs/guides/audio). #### properties ##### type ###### type string ###### 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 #### x-stainless-naming ##### go ###### variant_constructor InputAudioContentPart ### ChatCompletionRequestMessageContentPartFile #### type object #### title File content part #### description Learn about [file inputs](https://platform.openai.com/docs/guides/text) for text generation. #### properties ##### type ###### type string ###### enum - file ###### description The type of the content part. Always `file`. ###### x-stainless-const true ##### file ###### type object ###### properties ####### filename ######## type string ######## 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. ###### x-stainless-naming ####### java ######## type_name FileObject ####### kotlin ######## type_name FileObject #### required - type - file #### x-stainless-naming ##### go ###### variant_constructor FileContentPart ### ChatCompletionRequestMessageContentPartImage #### type object #### title Image content part #### description Learn about [image inputs](https://platform.openai.com/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 ###### 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](https://platform.openai.com/docs/guides/vision#low-or-high-fidelity-image-understanding). ######## enum - auto - low - high ######## default auto ###### required - url #### required - type - image_url #### x-stainless-naming ##### go ###### variant_constructor ImageContentPart ### ChatCompletionRequestMessageContentPartRefusal #### type object #### 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](https://platform.openai.com/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 #### x-stainless-naming ##### go ###### variant_constructor TextContentPart ### ChatCompletionRequestSystemMessage #### 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. #### properties ##### content ###### description The contents of the system message. ###### anyOf ####### 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 An optional name for the participant. Provides the model information to differentiate between participants of the same role. #### required - content - role #### x-stainless-naming ##### go ###### variant_constructor SystemMessage ### ChatCompletionRequestSystemMessageContentPart #### anyOf ##### $ref #/components/schemas/ChatCompletionRequestMessageContentPartText ### 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 ###### description The contents of the tool message. ###### anyOf ####### 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 ##### tool_call_id ###### type string ###### description Tool call that this message is responding to. #### required - role - content - tool_call_id #### x-stainless-naming ##### go ###### variant_constructor ToolMessage ### ChatCompletionRequestToolMessageContentPart #### anyOf ##### $ref #/components/schemas/ChatCompletionRequestMessageContentPartText ### ChatCompletionRequestUserMessage #### type object #### title User message #### description Messages sent by an end user, containing prompts or additional context information. #### properties ##### content ###### description The contents of the user message. ###### anyOf ####### 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](https://platform.openai.com/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 ##### role ###### type string ###### enum - user ###### description The role of the messages author, in this case `user`. ###### 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 #### x-stainless-naming ##### go ###### variant_constructor UserMessage ### ChatCompletionRequestUserMessageContentPart #### anyOf ##### $ref #/components/schemas/ChatCompletionRequestMessageContentPartText ##### $ref #/components/schemas/ChatCompletionRequestMessageContentPartImage ##### $ref #/components/schemas/ChatCompletionRequestMessageContentPartAudio ##### $ref #/components/schemas/ChatCompletionRequestMessageContentPartFile #### discriminator ##### propertyName type ### ChatCompletionResponseMessage #### type object #### description A chat completion message generated by the model. #### 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 ##### annotations ###### type array ###### description Annotations for the message, when applicable, as when using the [web search tool](https://platform.openai.com/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 - 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](https://platform.openai.com/docs/guides/audio). ###### required - id - expires_at - data - transcript ###### properties ####### id ######## type string ######## 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 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. #### 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. **NOTE:** If the stream is interrupted, you may not receive the final usage chunk which contains the total token usage for the request. ##### include_obfuscation ###### type boolean ###### description When true, stream obfuscation will be enabled. Stream obfuscation adds random characters to an `obfuscation` field on streaming delta events to normalize payload sizes as a mitigation to certain side-channel attacks. These obfuscation fields are included by default, but add a small amount of overhead to the data stream. You can set `include_obfuscation` to false to optimize for bandwidth if you trust the network links between your application and the OpenAI API. ### ChatCompletionStreamResponseDelta #### type object #### description A chat completion delta generated by streamed model responses. #### properties ##### content ###### 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 ###### type array ###### items ####### $ref #/components/schemas/ChatCompletionMessageToolCallChunk ##### role ###### type string ###### enum - developer - system - user - assistant - tool ###### description The role of the author of this message. ##### refusal ###### type string ###### description The refusal message generated by the model. ###### nullable true ### ChatCompletionTokenLogprob #### type object #### properties ##### token ###### description The token. ###### type string ##### logprob ###### 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 ###### 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 ######### description The token. ######### type string ######## logprob ######### 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 ######### 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 ####### required - token - logprob - bytes #### required - token - logprob - bytes - top_logprobs ### ChatCompletionTool #### type object #### title Function tool #### description A function tool that can be used to generate a response. #### properties ##### type ###### type string ###### enum - function ###### description The type of the tool. Currently, only `function` is supported. ###### x-stainless-const true ##### function ###### $ref #/components/schemas/FunctionObject #### required - 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. #### anyOf ##### type string ##### title Auto ##### 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/ChatCompletionAllowedToolsChoice ##### $ref #/components/schemas/ChatCompletionNamedToolChoice ##### $ref #/components/schemas/ChatCompletionNamedToolChoiceCustom #### x-stainless-go-variant-constructor ##### naming tool_choice_option_{variant} ### ChunkingStrategyRequestParam #### 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. #### anyOf ##### $ref #/components/schemas/AutoChunkingStrategyRequestParam ##### $ref #/components/schemas/StaticChunkingStrategyRequestParam #### discriminator ##### propertyName type ### Click #### type object #### title Click #### description A click action. #### properties ##### type ###### type string ###### enum - click ###### default click ###### description Specifies the event type. For a click action, this property is always set to `click`. ###### x-stainless-const true ##### 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 - button - x - y ### CodeInterpreterFileOutput #### type object #### title Code interpreter file output #### description The output of a code interpreter tool call that is a file. #### properties ##### type ###### type string ###### enum - 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 - files ### CodeInterpreterOutputImage #### type object #### title Code interpreter output image #### description The image output from the code interpreter. #### properties ##### type ###### type string ###### enum - image ###### default image ###### x-stainless-const true ###### description The type of the output. Always 'image'. ##### url ###### type string ###### description The URL of the image output from the code interpreter. #### required - type - url ### CodeInterpreterOutputLogs #### type object #### title Code interpreter output logs #### description The logs output from the code interpreter. #### properties ##### type ###### type string ###### enum - logs ###### default logs ###### x-stainless-const true ###### description The type of the output. Always 'logs'. ##### logs ###### type string ###### description The logs output from the code interpreter. #### required - type - logs ### CodeInterpreterTextOutput #### type object #### title Code interpreter text output #### description The output of a code interpreter tool call that is text. #### properties ##### type ###### type string ###### enum - logs ###### description The type of the code interpreter text output. Always `logs`. ###### x-stainless-const true ##### logs ###### type string ###### description The logs of the code interpreter tool call. #### required - type - logs ### CodeInterpreterTool #### type object #### title Code interpreter #### description A tool that runs Python code to help generate a response to a prompt. #### properties ##### type ###### type string ###### enum - code_interpreter ###### description The type of the code interpreter tool. Always `code_interpreter`. ###### x-stainless-const true ##### container ###### description The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code. ###### anyOf ####### type string ####### description The container ID. ####### $ref #/components/schemas/CodeInterpreterToolAuto #### required - type - container ### CodeInterpreterToolAuto #### type object #### title CodeInterpreterContainerAuto #### description Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. #### required - type #### properties ##### type ###### type string ###### enum - auto ###### description Always `auto`. ###### x-stainless-const true ##### file_ids ###### type array ###### items ####### type string ###### description An optional list of uploaded files to make available to your code. ### CodeInterpreterToolCall #### type object #### title Code interpreter tool call #### description A tool call to run code. #### properties ##### type ###### type string ###### enum - code_interpreter_call ###### default code_interpreter_call ###### x-stainless-const true ###### description The type of the code interpreter tool call. Always `code_interpreter_call`. ##### id ###### type string ###### description The unique ID of the code interpreter tool call. ##### status ###### type string ###### enum - in_progress - completed - incomplete - interpreting - failed ###### description The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. ##### container_id ###### type string ###### description The ID of the container used to run the code. ##### code ###### type string ###### nullable true ###### description The code to run, or null if not available. ##### outputs ###### type array ###### items ####### anyOf ######## $ref #/components/schemas/CodeInterpreterOutputLogs ######## $ref #/components/schemas/CodeInterpreterOutputImage ####### discriminator ######## propertyName type ###### discriminator ####### propertyName type ###### nullable true ###### description The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. #### required - type - id - status - container_id - code - outputs ### ComparisonFilter #### type object #### additionalProperties false #### title Comparison Filter #### description A filter used to compare a specified attribute key to a given value using a defined comparison operation. #### properties ##### type ###### type string ###### default eq ###### enum - eq - ne - gt - gte - lt - lte ###### 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 ###### description The value to compare against the attribute key; supports string, number, or boolean types. ###### anyOf ####### type string ####### type number ####### type boolean #### required - type - key - value #### x-oaiMeta ##### name ComparisonFilter ### CompleteUploadRequest #### type object #### additionalProperties false #### properties ##### part_ids ###### type array ###### description 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 #### required - part_ids ### CompletionUsage #### type object #### description Usage statistics for the completion request. #### properties ##### 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 ####### 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. #### required - prompt_tokens - completion_tokens - total_tokens ### CompoundFilter #### $recursiveAnchor true #### type object #### additionalProperties false #### title Compound Filter #### description Combine multiple filters using `and` or `or`. #### properties ##### type ###### type string ###### description Type of operation: `and` or `or`. ###### enum - and - or ##### filters ###### type array ###### description Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. ###### items ####### anyOf ######## $ref #/components/schemas/ComparisonFilter ######## $recursiveRef # #### required - type - filters #### x-oaiMeta ##### name CompoundFilter ### ComputerAction #### anyOf ##### $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 #### discriminator ##### propertyName type ### ComputerScreenshotImage #### type object #### description A computer screenshot image used with the computer use tool. #### properties ##### type ###### type string ###### enum - computer_screenshot ###### default computer_screenshot ###### description Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. ###### x-stainless-const true ##### image_url ###### type string ###### description The URL of the screenshot image. ##### file_id ###### type string ###### description The identifier of an uploaded file that contains the screenshot. #### required - type ### ComputerToolCall #### type object #### title Computer tool call #### description A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information. #### properties ##### type ###### type string ###### description The type of the computer call. Always `computer_call`. ###### enum - computer_call ###### default computer_call ##### id ###### type string ###### description The unique ID of the computer call. ##### call_id ###### type string ###### description An identifier used when responding to the tool call with output. ##### action ###### $ref #/components/schemas/ComputerAction ##### pending_safety_checks ###### type array ###### 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 #### title Computer tool call output #### description The output of a computer tool call. #### properties ##### type ###### type string ###### description The type of the computer tool call output. Always `computer_call_output`. ###### enum - computer_call_output ###### default computer_call_output ###### x-stainless-const true ##### id ###### type string ###### description The ID of the computer tool call output. ##### call_id ###### type string ###### description The ID of the computer tool call that produced the output. ##### acknowledged_safety_checks ###### type array ###### description The safety checks reported by the API that have been acknowledged by the developer. ###### items ####### $ref #/components/schemas/ComputerToolCallSafetyCheck ##### output ###### $ref #/components/schemas/ComputerScreenshotImage ##### status ###### type string ###### description The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. ###### enum - in_progress - completed - incomplete #### required - type - call_id - output ### 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 - id - code - message ### ContainerFileListResource #### type object #### properties ##### object ###### description The type of object returned, must be 'list'. ###### const list ##### data ###### type array ###### description A list of container files. ###### items ####### $ref #/components/schemas/ContainerFileResource ##### first_id ###### type string ###### description The ID of the first file in the list. ##### last_id ###### type string ###### description The ID of the last file in the list. ##### has_more ###### type boolean ###### description Whether there are more files available. #### required - object - data - first_id - last_id - has_more ### ContainerFileResource #### type object #### title The container file object #### properties ##### id ###### type string ###### description Unique identifier for the file. ##### object ###### type string ###### description The type of this object (`container.file`). ###### const container.file ##### container_id ###### type string ###### description The container this file belongs to. ##### created_at ###### type integer ###### description Unix timestamp (in seconds) when the file was created. ##### bytes ###### type integer ###### description Size of the file in bytes. ##### path ###### type string ###### description Path of the file in the container. ##### source ###### type string ###### description Source of the file (e.g., `user`, `assistant`). #### required - id - object - created_at - bytes - container_id - path - source #### x-oaiMeta ##### name The container file object ##### example { "id": "cfile_682e0e8a43c88191a7978f477a09bdf5", "object": "container.file", "created_at": 1747848842, "bytes": 880, "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04", "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json", "source": "user" } ### ContainerListResource #### type object #### properties ##### object ###### description The type of object returned, must be 'list'. ###### const list ##### data ###### type array ###### description A list of containers. ###### items ####### $ref #/components/schemas/ContainerResource ##### first_id ###### type string ###### description The ID of the first container in the list. ##### last_id ###### type string ###### description The ID of the last container in the list. ##### has_more ###### type boolean ###### description Whether there are more containers available. #### required - object - data - first_id - last_id - has_more ### ContainerResource #### type object #### title The container object #### properties ##### id ###### type string ###### description Unique identifier for the container. ##### object ###### type string ###### description The type of this object. ##### name ###### type string ###### description Name of the container. ##### created_at ###### type integer ###### description Unix timestamp (in seconds) when the container was created. ##### status ###### type string ###### description Status of the container (e.g., active, deleted). ##### expires_after ###### type object ###### description The container will expire after this time period. The anchor is the reference point for the expiration. The minutes is the number of minutes after the anchor before the container expires. ###### properties ####### anchor ######## type string ######## description The reference point for the expiration. ######## enum - last_active_at ####### minutes ######## type integer ######## description The number of minutes after the anchor before the container expires. #### required - id - object - name - created_at - status - id - name - created_at - status #### x-oaiMeta ##### name The container object ##### example { "id": "cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863", "object": "container", "created_at": 1747844794, "status": "running", "expires_after": { "anchor": "last_active_at", "minutes": 20 }, "last_active_at": 1747844794, "name": "My Container" } ### Content #### description Multi-modal input and output contents. #### anyOf ##### title Input content types ##### $ref #/components/schemas/InputContent ##### title Output content types ##### $ref #/components/schemas/OutputContent ### Conversation #### title The conversation object #### allOf ##### $ref #/components/schemas/ConversationResource #### x-oaiMeta ##### name The conversation object ##### group conversations ### ConversationItem #### title Conversation item #### description A single item within a conversation. The set of possible types are the same as the `output` type of a [Response object](https://platform.openai.com/docs/api-reference/responses/object#responses/object-output). #### discriminator ##### propertyName type #### x-oaiMeta ##### name The item object ##### group conversations #### anyOf ##### $ref #/components/schemas/Message ##### $ref #/components/schemas/FunctionToolCallResource ##### $ref #/components/schemas/FunctionToolCallOutputResource ##### $ref #/components/schemas/FileSearchToolCall ##### $ref #/components/schemas/WebSearchToolCall ##### $ref #/components/schemas/ImageGenToolCall ##### $ref #/components/schemas/ComputerToolCall ##### $ref #/components/schemas/ComputerToolCallOutputResource ##### $ref #/components/schemas/ReasoningItem ##### $ref #/components/schemas/CodeInterpreterToolCall ##### $ref #/components/schemas/LocalShellToolCall ##### $ref #/components/schemas/LocalShellToolCallOutput ##### $ref #/components/schemas/MCPListTools ##### $ref #/components/schemas/MCPApprovalRequest ##### $ref #/components/schemas/MCPApprovalResponseResource ##### $ref #/components/schemas/MCPToolCall ##### $ref #/components/schemas/CustomToolCall ##### $ref #/components/schemas/CustomToolCallOutput ### ConversationItemList #### type object #### title The conversation item list #### description A list of Conversation items. #### properties ##### object ###### description The type of object returned, must be `list`. ###### x-stainless-const true ###### const list ##### data ###### type array ###### description A list of conversation items. ###### items ####### $ref #/components/schemas/ConversationItem ##### has_more ###### type boolean ###### description Whether there are more items available. ##### first_id ###### type string ###### description The ID of the first item in the list. ##### last_id ###### type string ###### description The ID of the last item in the list. #### required - object - data - has_more - first_id - last_id #### x-oaiMeta ##### name The item list ##### group conversations ### Coordinate #### type object #### title Coordinate #### description An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`. #### properties ##### x ###### type integer ###### description The x-coordinate. ##### y ###### type integer ###### description The y-coordinate. #### required - x - y ### CostsResult #### type object #### description The aggregated costs details of the specific time bucket. #### properties ##### object ###### type string ###### enum - organization.costs.result ###### x-stainless-const true ##### amount ###### type object ###### description The monetary value in its associated currency. ###### properties ####### value ######## type number ######## description The numeric value of the cost. ####### currency ######## type string ######## description Lowercase ISO-4217 currency e.g. "usd" ##### line_item ###### type string ###### nullable true ###### description When `group_by=line_item`, this field provides the line item of the grouped costs result. ##### project_id ###### type string ###### nullable true ###### description When `group_by=project_id`, this field provides the project ID of the grouped costs result. #### required - object #### x-oaiMeta ##### name Costs object ##### example { "object": "organization.costs.result", "amount": { "value": 0.06, "currency": "usd" }, "line_item": "Image models", "project_id": "proj_abc" } ### CreateAssistantRequest #### type object #### additionalProperties false #### properties ##### model ###### description ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. ###### example gpt-4o ###### anyOf ####### type string ####### $ref #/components/schemas/AssistantSupportedModels ###### x-oaiTypeLabel string ##### name ###### description The name of the assistant. The maximum length is 256 characters. ###### type string ###### nullable true ###### maxLength 256 ##### description ###### description The description of the assistant. The maximum length is 512 characters. ###### type string ###### nullable true ###### maxLength 512 ##### instructions ###### description The system instructions that the assistant uses. The maximum length is 256,000 characters. ###### type string ###### nullable true ###### maxLength 256000 ##### reasoning_effort ###### $ref #/components/schemas/ReasoningEffort ##### 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 ####### $ref #/components/schemas/AssistantTool ##### 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](https://platform.openai.com/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](https://platform.openai.com/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 ######### vector_stores ########## type array ########## description A helper to create a [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) with file_ids and attach it to this assistant. There can be a maximum of 1 vector store attached to the assistant. ########## maxItems 1 ########## items ########### type object ########### properties ############ file_ids ############# type array ############# description A list of [file](https://platform.openai.com/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. ############# anyOf ############## 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-stainless-naming ############### java ################ type_name StaticObject ############### kotlin ################ type_name StaticObject ############# discriminator ############## propertyName type ############ metadata ############# $ref #/components/schemas/Metadata ######## anyOf ######### required - vector_store_ids ######### required - vector_stores ###### 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 - model ### CreateChatCompletionRequest #### allOf ##### $ref #/components/schemas/CreateModelResponseProperties ##### type object ##### properties ###### messages ####### description A list of messages comprising the conversation so far. Depending on the [model](https://platform.openai.com/docs/models) you use, different message types (modalities) are supported, like [text](https://platform.openai.com/docs/guides/text-generation), [images](https://platform.openai.com/docs/guides/vision), and [audio](https://platform.openai.com/docs/guides/audio). ####### type array ####### minItems 1 ####### items ######## $ref #/components/schemas/ChatCompletionRequestMessage ###### model ####### description Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. ####### $ref #/components/schemas/ModelIdsShared ###### modalities ####### $ref #/components/schemas/ResponseModalities ###### verbosity ####### $ref #/components/schemas/Verbosity ###### 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](https://platform.openai.com/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 their existing frequency in the text so far, decreasing the model's 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 whether they appear in the text so far, increasing the model's likelihood 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. Learn more about the [web search tool](https://platform.openai.com/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 return at each token position, each with an associated log probability. `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. 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](https://platform.openai.com/docs/guides/structured-outputs). Setting to `{ "type": "json_object" }` enables the older JSON mode, which ensures the message the model generates is valid JSON. Using `json_schema` is preferred for models that support it. ####### anyOf ######## $ref #/components/schemas/ResponseFormatText ######## $ref #/components/schemas/ResponseFormatJsonSchema ######## $ref #/components/schemas/ResponseFormatJsonObject ###### audio ####### type object ####### nullable true ####### description Parameters for audio output. Required when audio output is requested with `modalities: ["audio"]`. [Learn more](https://platform.openai.com/docs/guides/audio). ####### required - voice - format ####### properties ######## voice ######### $ref #/components/schemas/VoiceIdsShared ######### description The voice the model uses to respond. Supported voices are `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `nova`, `onyx`, `sage`, and `shimmer`. ######## format ######### type string ######### enum - wav - aac - 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 use in our [model distillation](https://platform.openai.com/docs/guides/distillation) or [evals](https://platform.openai.com/docs/guides/evals) products. Supports text and image inputs. Note: image inputs over 8MB will be dropped. ###### 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](https://platform.openai.com/docs/api-reference/chat/streaming) for more information, along with the [streaming responses](https://platform.openai.com/docs/guides/streaming-responses) 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. 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, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 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, returns the log probabilities of each output token returned in the `content` of `message`. ####### type boolean ####### default false ####### nullable true ###### max_tokens ####### description The maximum number of [tokens](/tokenizer) that can be generated in the chat completion. This value can be used to control [costs](https://openai.com/api/pricing/) for text generated via API. This value is now deprecated in favor of `max_completion_tokens`, and is not compatible with [o-series models](https://platform.openai.com/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 ####### description Configuration for a [Predicted Output](https://platform.openai.com/docs/guides/predicted-outputs), 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 regenerating a file with only minor changes to most of the content. ####### anyOf ######## $ref #/components/schemas/PredictionContent ####### discriminator ######## propertyName type ###### seed ####### type integer ####### minimum -9223372036854776000 ####### maximum 9223372036854776000 ####### nullable true ####### deprecated 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. You can provide either [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) or [function tools](https://platform.openai.com/docs/guides/function-calling). ####### items ######## anyOf ######### $ref #/components/schemas/ChatCompletionTool ######### $ref #/components/schemas/CustomToolChatCompletions ######## x-stainless-naming ######### python ########## model_name chat_completion_tool_union ########## param_model_name chat_completion_tool_union_param ######## discriminator ######### propertyName type ######## x-stainless-go-variant-constructor ######### naming chat_completion_{variant}_tool ###### 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. `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. Specifying a particular function via `{"name": "my_function"}` forces the model to call that function. `none` is the default when no functions are present. `auto` is the default if functions are present. ####### anyOf ######## 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 ######## title function call mode ######## $ref #/components/schemas/ChatCompletionFunctionCallOption ###### 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 ### CreateChatCompletionResponse #### type object #### description Represents a chat completion response returned by model, based on the provided input. #### properties ##### id ###### type string ###### description A unique identifier for the chat completion. ##### choices ###### type array ###### description A list of chat completion choices. Can be more than one if `n` is greater than 1. ###### items ####### type object ####### required - finish_reason - index - message - logprobs ####### properties ######## finish_reason ######### type string ######### description The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `content_filter` if content was omitted due to a flag from our content filters, `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function. ######### enum - stop - length - tool_calls - content_filter - function_call ######## index ######### type integer ######### description The index of the choice in the list of choices. ######## message ######### $ref #/components/schemas/ChatCompletionResponseMessage ######## logprobs ######### description Log probability information for the choice. ######### type object ######### nullable true ######### properties ########## content ########### description A list of message content tokens with log probability information. ########### type array ########### items ############ $ref #/components/schemas/ChatCompletionTokenLogprob ########### nullable true ########## refusal ########### description A list of message refusal tokens with log probability information. ########### type array ########### items ############ $ref #/components/schemas/ChatCompletionTokenLogprob ########### nullable true ######### required - content - refusal ##### created ###### type integer ###### description The Unix timestamp (in seconds) of when the chat completion was created. ##### model ###### type string ###### description The model used for the chat completion. ##### service_tier ###### $ref #/components/schemas/ServiceTier ##### system_fingerprint ###### type string ###### deprecated true ###### description This fingerprint represents the backend configuration that the model runs with. Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism. ##### object ###### type string ###### description The object type, which is always `chat.completion`. ###### enum - chat.completion ###### x-stainless-const true ##### usage ###### $ref #/components/schemas/CompletionUsage #### required - choices - created - id - model - object #### x-oaiMeta ##### name The chat completion object ##### group chat ##### example { "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG", "object": "chat.completion", "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": 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", "system_fingerprint": "fp_fc9f1d7035" } ### CreateChatCompletionStreamResponse #### type object #### description Represents a streamed chunk of a chat completion response returned by the model, based on the provided input. [Learn more](https://platform.openai.com/docs/guides/streaming-responses). #### properties ##### id ###### type string ###### description A unique identifier for the chat completion. Each chunk has the same ID. ##### choices ###### type array ###### description A list of chat completion choices. Can contain more than one elements if `n` is greater than 1. Can also be empty for the last chunk if you set `stream_options: {"include_usage": true}`. ###### items ####### type object ####### required - delta - finish_reason - index ####### properties ######## delta ######### $ref #/components/schemas/ChatCompletionStreamResponseDelta ######## logprobs ######### description Log probability information for the choice. ######### type object ######### nullable true ######### properties ########## content ########### description A list of message content tokens with log probability information. ########### type array ########### items ############ $ref #/components/schemas/ChatCompletionTokenLogprob ########### nullable true ########## refusal ########### description A list of message refusal tokens with log probability information. ########### type array ########### items ############ $ref #/components/schemas/ChatCompletionTokenLogprob ########### nullable true ######### required - content - refusal ######## finish_reason ######### type string ######### description The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `content_filter` if content was omitted due to a flag from our content filters, `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function. ######### enum - stop - length - tool_calls - content_filter - function_call ######### nullable true ######## index ######### type integer ######### description The index of the choice in the list of choices. ##### created ###### type integer ###### description The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp. ##### model ###### type string ###### description The model to generate the completion. ##### service_tier ###### $ref #/components/schemas/ServiceTier ##### system_fingerprint ###### type string ###### deprecated true ###### description This fingerprint represents the backend configuration that the model runs with. Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism. ##### object ###### type string ###### description The object type, which is always `chat.completion.chunk`. ###### enum - chat.completion.chunk ###### x-stainless-const true ##### usage ###### $ref #/components/schemas/CompletionUsage ###### nullable true ###### description An optional field that will only be present when you set `stream_options: {"include_usage": true}` in your request. When present, it contains a null value **except for the last chunk** which contains the token usage statistics for the entire request. **NOTE:** If the stream is interrupted or cancelled, you may not receive the final usage chunk which contains the total token usage for the request. #### required - choices - created - id - model - object #### x-oaiMeta ##### name The chat completion chunk object ##### group chat ##### example {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}]} .... {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]} ### CreateCompletionRequest #### type object #### properties ##### model ###### description ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. ###### anyOf ####### type string ####### type string ####### enum - gpt-3.5-turbo-instruct - davinci-002 - babbage-002 ####### title Preset ###### x-oaiTypeLabel string ##### prompt ###### description The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays. Note that <|endoftext|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document. ###### nullable true ###### anyOf ####### type string ####### default ####### example This is a test. ####### type array ####### items ######## type string ######## default ######## example This is a test. ####### title Array of strings ####### type array ####### minItems 1 ####### items ######## type integer ####### title Array of tokens ####### type array ####### minItems 1 ####### items ######## type array ######## minItems 1 ######## items ######### type integer ####### title Array of token arrays ##### best_of ###### type integer ###### default 1 ###### minimum 0 ###### maximum 20 ###### nullable true ###### description Generates `best_of` completions server-side and returns the "best" (the one with the highest log probability per token). Results cannot be streamed. When used with `n`, `best_of` controls the number of candidate completions and `n` specifies how many to return – `best_of` must be greater than `n`. **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`. ##### echo ###### type boolean ###### default false ###### nullable true ###### description Echo back the prompt in addition to the completion ##### 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. [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation) ##### 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 GPT tokenizer) to an associated bias value from -100 to 100. You can use this [tokenizer tool](/tokenizer?view=bpe) to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. As an example, you can pass `{"50256": -100}` to prevent the <|endoftext|> token from being generated. ##### logprobs ###### type integer ###### minimum 0 ###### maximum 5 ###### default null ###### nullable true ###### description Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response. The maximum value for `logprobs` is 5. ##### max_tokens ###### type integer ###### minimum 0 ###### default 16 ###### example 16 ###### nullable true ###### description The maximum number of [tokens](/tokenizer) that can be generated in the completion. The token count of your prompt plus `max_tokens` cannot exceed the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. ##### n ###### type integer ###### minimum 1 ###### maximum 128 ###### default 1 ###### example 1 ###### nullable true ###### description How many completions to generate for each prompt. **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`. ##### 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 whether they appear in the text so far, increasing the model's likelihood to talk about new topics. [See more information about frequency and presence penalties.](https://platform.openai.com/docs/guides/text-generation) ##### seed ###### type integer ###### format int64 ###### 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 ###### $ref #/components/schemas/StopConfiguration ##### stream ###### description Whether to stream back partial progress. If set, 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 ##### suffix ###### description The suffix that comes after a completion of inserted text. This parameter is only supported for `gpt-3.5-turbo-instruct`. ###### default null ###### nullable true ###### type string ###### example test. ##### 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. 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 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](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids). #### required - model - prompt ### CreateCompletionResponse #### type object #### description Represents a completion response from the API. Note: both the streamed and non-streamed response objects share the same shape (unlike the chat endpoint). #### properties ##### id ###### type string ###### description A unique identifier for the completion. ##### choices ###### type array ###### description The list of completion choices the model generated for the input prompt. ###### items ####### type object ####### required - finish_reason - index - logprobs - text ####### properties ######## finish_reason ######### type string ######### description The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, or `content_filter` if content was omitted due to a flag from our content filters. ######### enum - stop - length - content_filter ######## index ######### type integer ######## logprobs ######### type object ######### nullable true ######### properties ########## text_offset ########### type array ########### items ############ type integer ########## token_logprobs ########### type array ########### items ############ type number ########## tokens ########### type array ########### items ############ type string ########## top_logprobs ########### type array ########### items ############ type object ############ additionalProperties ############# type number ######## text ######### type string ##### created ###### type integer ###### description The Unix timestamp (in seconds) of when the completion was created. ##### model ###### type string ###### description The model used for completion. ##### system_fingerprint ###### type string ###### description This fingerprint represents the backend configuration that the model runs with. Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism. ##### object ###### type string ###### description The object type, which is always "text_completion" ###### enum - text_completion ###### x-stainless-const true ##### usage ###### $ref #/components/schemas/CompletionUsage #### required - id - object - created - model - choices #### x-oaiMeta ##### name The completion object ##### legacy true ##### example { "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", "object": "text_completion", "created": 1589478378, "model": "gpt-4-turbo", "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 } } ### CreateContainerBody #### type object #### properties ##### name ###### type string ###### description Name of the container to create. ##### file_ids ###### type array ###### description IDs of files to copy to the container. ###### items ####### type string ##### expires_after ###### type object ###### description Container expiration time in seconds relative to the 'anchor' time. ###### properties ####### anchor ######## type string ######## enum - last_active_at ######## description Time anchor for the expiration time. Currently only 'last_active_at' is supported. ####### minutes ######## type integer ###### required - anchor - minutes #### required - name ### CreateContainerFileBody #### type object #### properties ##### file_id ###### type string ###### description Name of the file to create. ##### file ###### description The File object (not file name) to be uploaded. ###### type string ###### format binary #### required ### CreateConversationRequest #### type object #### description Create a conversation #### properties ##### metadata ###### $ref #/components/schemas/Metadata ###### description Set of 16 key-value pairs that can be attached to an object. Useful for storing additional information about the object in a structured format. ##### items ###### type array ###### description Initial items to include in the conversation context. You may add up to 20 items at a time. ###### items ####### $ref #/components/schemas/InputItem ###### nullable true ###### maxItems 20 #### required ### CreateEmbeddingRequest #### type object #### additionalProperties false #### properties ##### input ###### description Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (8192 tokens for all embedding models), cannot be an empty string, and any array must be 2048 dimensions or less. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. In addition to the per-input token limit, all embedding models enforce a maximum of 300,000 tokens summed across all inputs in a single request. ###### example The quick brown fox jumped over the lazy dog ###### anyOf ####### type string ####### title string ####### description The string that will be turned into an embedding. ####### default ####### example This is a test. ####### type array ####### title Array of strings ####### description The array of strings that will be turned into an embedding. ####### minItems 1 ####### maxItems 2048 ####### items ######## type string ######## default ######## example ['This is a test.'] ####### type array ####### title Array of tokens ####### description The array of integers that will be turned into an embedding. ####### minItems 1 ####### maxItems 2048 ####### items ######## type integer ####### type array ####### title Array of token arrays ####### description The array of arrays containing integers that will be turned into an embedding. ####### minItems 1 ####### maxItems 2048 ####### items ######## type array ######## minItems 1 ######## items ######### type integer ##### model ###### description ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) for descriptions of them. ###### example text-embedding-3-small ###### anyOf ####### type string ####### type string ####### enum - text-embedding-ada-002 - text-embedding-3-small - text-embedding-3-large ####### x-stainless-nominal false ###### x-oaiTypeLabel string ##### encoding_format ###### description The format to return the embeddings in. Can be either `float` or [`base64`](https://pypi.org/project/pybase64/). ###### example float ###### default float ###### type string ###### enum - float - base64 ##### dimensions ###### description The number of dimensions the resulting output embeddings should have. Only supported in `text-embedding-3` and later models. ###### type integer ###### minimum 1 ##### 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](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids). #### required - model - input ### CreateEmbeddingResponse #### type object #### properties ##### data ###### type array ###### description The list of embeddings generated by the model. ###### items ####### $ref #/components/schemas/Embedding ##### model ###### type string ###### description The name of the model used to generate the embedding. ##### object ###### type string ###### description The object type, which is always "list". ###### enum - list ###### x-stainless-const true ##### usage ###### type object ###### description The usage information for the request. ###### properties ####### prompt_tokens ######## type integer ######## description The number of tokens used by the prompt. ####### total_tokens ######## type integer ######## description The total number of tokens used by the request. ###### required - prompt_tokens - total_tokens #### required - object - model - data - usage ### CreateEvalCompletionsRunDataSource #### type object #### title CompletionsRunDataSource #### description A CompletionsRunDataSource object describing a model sampling configuration. #### properties ##### type ###### type string ###### enum - completions ###### default completions ###### description The type of run data source. Always `completions`. ##### input_messages ###### description Used when sampling from a model. Dictates the structure of the messages passed into the model. Can either be a reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template with variable references to the `item` namespace. ###### anyOf ####### type object ####### title TemplateInputMessages ####### properties ######## type ######### type string ######### enum - template ######### description The type of input messages. Always `template`. ######## template ######### type array ######### description A list of chat messages forming the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}. ######### items ########## anyOf ########### $ref #/components/schemas/EasyInputMessage ########### $ref #/components/schemas/EvalItem ####### required - type - template ####### type object ####### title ItemReferenceInputMessages ####### properties ######## type ######### type string ######### enum - item_reference ######### description The type of input messages. Always `item_reference`. ######## item_reference ######### type string ######### description A reference to a variable in the `item` namespace. Ie, "item.input_trajectory" ####### required - type - item_reference ###### discriminator ####### propertyName type ##### sampling_params ###### type object ###### properties ####### temperature ######## type number ######## description A higher temperature increases randomness in the outputs. ######## default 1 ####### max_completion_tokens ######## type integer ######## description The maximum number of tokens in the generated output. ####### top_p ######## type number ######## description An alternative to temperature for nucleus sampling; 1.0 includes all tokens. ######## default 1 ####### seed ######## type integer ######## description A seed value to initialize the randomness, during sampling. ######## default 42 ####### response_format ######## description An object specifying the format that the model must output. 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](https://platform.openai.com/docs/guides/structured-outputs). Setting to `{ "type": "json_object" }` enables the older JSON mode, which ensures the message the model generates is valid JSON. Using `json_schema` is preferred for models that support it. ######## anyOf ######### $ref #/components/schemas/ResponseFormatText ######### $ref #/components/schemas/ResponseFormatJsonSchema ######### $ref #/components/schemas/ResponseFormatJsonObject ####### 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 ##### model ###### type string ###### description The name of the model to use for generating completions (e.g. "o3-mini"). ##### source ###### description Determines what populates the `item` namespace in this run's data source. ###### anyOf ####### $ref #/components/schemas/EvalJsonlFileContentSource ####### $ref #/components/schemas/EvalJsonlFileIdSource ####### $ref #/components/schemas/EvalStoredCompletionsSource ###### discriminator ####### propertyName type #### required - type - source #### x-oaiMeta ##### name The completions data source object used to configure an individual run ##### group eval runs ##### example { "name": "gpt-4o-mini-2024-07-18", "data_source": { "type": "completions", "input_messages": { "type": "item_reference", "item_reference": "item.input" }, "model": "gpt-4o-mini-2024-07-18", "source": { "type": "stored_completions", "model": "gpt-4o-mini-2024-07-18" } } } ### CreateEvalCustomDataSourceConfig #### type object #### title CustomDataSourceConfig #### description A CustomDataSourceConfig object that defines the schema for the data source used for the evaluation runs. This schema is used to define the shape of the data that will be: - Used to define your testing criteria and - What data is required when creating a run #### properties ##### type ###### type string ###### enum - custom ###### default custom ###### description The type of data source. Always `custom`. ###### x-stainless-const true ##### item_schema ###### type object ###### description The json schema for each row in the data source. ###### additionalProperties true ##### include_sample_schema ###### type boolean ###### default false ###### description Whether the eval should expect you to populate the sample namespace (ie, by generating responses off of your data source) #### required - item_schema - type #### x-oaiMeta ##### name The eval file data source config object ##### group evals ##### example { "type": "custom", "item_schema": { "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "integer"} }, "required": ["name", "age"] }, "include_sample_schema": true } ### CreateEvalItem #### title CreateEvalItem #### description A chat message that makes up the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}. #### type object #### x-oaiMeta ##### name The chat message object used to configure an individual run #### anyOf ##### type object ##### title SimpleInputMessage ##### properties ###### role ####### type string ####### description The role of the message (e.g. "system", "assistant", "user"). ###### content ####### type string ####### description The content of the message. ##### required - role - content ##### $ref #/components/schemas/EvalItem ### CreateEvalJsonlRunDataSource #### type object #### title JsonlRunDataSource #### description A JsonlRunDataSource object with that specifies a JSONL file that matches the eval #### properties ##### type ###### type string ###### enum - jsonl ###### default jsonl ###### description The type of data source. Always `jsonl`. ###### x-stainless-const true ##### source ###### description Determines what populates the `item` namespace in the data source. ###### anyOf ####### $ref #/components/schemas/EvalJsonlFileContentSource ####### $ref #/components/schemas/EvalJsonlFileIdSource ###### discriminator ####### propertyName type #### required - type - source #### x-oaiMeta ##### name The file data source object for the eval run configuration ##### group evals ##### example { "type": "jsonl", "source": { "type": "file_id", "id": "file-9GYS6xbkWgWhmE7VoLUWFg" } } ### CreateEvalLabelModelGrader #### type object #### title LabelModelGrader #### description A LabelModelGrader object which uses a model to assign labels to each item in the evaluation. #### properties ##### type ###### description The object type, which is always `label_model`. ###### type string ###### enum - label_model ###### x-stainless-const true ##### name ###### type string ###### description The name of the grader. ##### model ###### type string ###### description The model to use for the evaluation. Must support structured outputs. ##### input ###### type array ###### description A list of chat messages forming the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}. ###### items ####### $ref #/components/schemas/CreateEvalItem ##### labels ###### type array ###### items ####### type string ###### description The labels to classify to each item in the evaluation. ##### passing_labels ###### type array ###### items ####### type string ###### description The labels that indicate a passing result. Must be a subset of labels. #### required - type - model - input - passing_labels - labels - name #### x-oaiMeta ##### name The eval label model grader object ##### group evals ##### example { "type": "label_model", "model": "gpt-4o-2024-08-06", "input": [ { "role": "system", "content": "Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'" }, { "role": "user", "content": "Statement: {{item.response}}" } ], "passing_labels": ["positive"], "labels": ["positive", "neutral", "negative"], "name": "Sentiment label grader" } ### CreateEvalLogsDataSourceConfig #### type object #### title LogsDataSourceConfig #### description A data source config which specifies the metadata property of your logs query. This is usually metadata like `usecase=chatbot` or `prompt-version=v2`, etc. #### properties ##### type ###### type string ###### enum - logs ###### default logs ###### description The type of data source. Always `logs`. ###### x-stainless-const true ##### metadata ###### type object ###### description Metadata filters for the logs data source. ###### additionalProperties true #### required - type #### x-oaiMeta ##### name The logs data source object for evals ##### group evals ##### example { "type": "logs", "metadata": { "use_case": "customer_support_agent" } } ### CreateEvalRequest #### type object #### title CreateEvalRequest #### properties ##### name ###### type string ###### description The name of the evaluation. ##### metadata ###### $ref #/components/schemas/Metadata ##### data_source_config ###### type object ###### description The configuration for the data source used for the evaluation runs. Dictates the schema of the data used in the evaluation. ###### anyOf ####### $ref #/components/schemas/CreateEvalCustomDataSourceConfig ####### $ref #/components/schemas/CreateEvalLogsDataSourceConfig ####### $ref #/components/schemas/CreateEvalStoredCompletionsDataSourceConfig ###### discriminator ####### propertyName type ##### testing_criteria ###### type array ###### description A list of graders for all eval runs in this group. Graders can reference variables in the data source using double curly braces notation, like `{{item.variable_name}}`. To reference the model's output, use the `sample` namespace (ie, `{{sample.output_text}}`). ###### items ####### anyOf ######## $ref #/components/schemas/CreateEvalLabelModelGrader ######## $ref #/components/schemas/EvalGraderStringCheck ######## $ref #/components/schemas/EvalGraderTextSimilarity ######## $ref #/components/schemas/EvalGraderPython ######## $ref #/components/schemas/EvalGraderScoreModel ####### discriminator ######## propertyName type #### required - data_source_config - testing_criteria ### CreateEvalResponsesRunDataSource #### type object #### title ResponsesRunDataSource #### description A ResponsesRunDataSource object describing a model sampling configuration. #### properties ##### type ###### type string ###### enum - responses ###### default responses ###### description The type of run data source. Always `responses`. ##### input_messages ###### description Used when sampling from a model. Dictates the structure of the messages passed into the model. Can either be a reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template with variable references to the `item` namespace. ###### anyOf ####### type object ####### title InputMessagesTemplate ####### properties ######## type ######### type string ######### enum - template ######### description The type of input messages. Always `template`. ######## template ######### type array ######### description A list of chat messages forming the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}. ######### items ########## anyOf ########### type object ########### title ChatMessage ########### properties ############ role ############# type string ############# description The role of the message (e.g. "system", "assistant", "user"). ############ content ############# type string ############# description The content of the message. ########### required - role - content ########### $ref #/components/schemas/EvalItem ####### required - type - template ####### type object ####### title InputMessagesItemReference ####### properties ######## type ######### type string ######### enum - item_reference ######### description The type of input messages. Always `item_reference`. ######## item_reference ######### type string ######### description A reference to a variable in the `item` namespace. Ie, "item.name" ####### required - type - item_reference ###### discriminator ####### propertyName type ##### sampling_params ###### type object ###### properties ####### temperature ######## type number ######## description A higher temperature increases randomness in the outputs. ######## default 1 ####### max_completion_tokens ######## type integer ######## description The maximum number of tokens in the generated output. ####### top_p ######## type number ######## description An alternative to temperature for nucleus sampling; 1.0 includes all tokens. ######## default 1 ####### seed ######## type integer ######## description A seed value to initialize the randomness, during sampling. ######## default 42 ####### tools ######## type array ######## description An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. The two categories of tools you can provide the model are: - **Built-in tools**: Tools that are provided by OpenAI that extend the model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about [built-in tools](https://platform.openai.com/docs/guides/tools). - **Function calls (custom tools)**: Functions that are defined by you, enabling the model to call your own code. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). ######## items ######### $ref #/components/schemas/Tool ####### text ######## type object ######## description Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) ######## properties ######### format ########## $ref #/components/schemas/TextResponseFormatConfiguration ##### model ###### type string ###### description The name of the model to use for generating completions (e.g. "o3-mini"). ##### source ###### description Determines what populates the `item` namespace in this run's data source. ###### anyOf ####### $ref #/components/schemas/EvalJsonlFileContentSource ####### $ref #/components/schemas/EvalJsonlFileIdSource ####### $ref #/components/schemas/EvalResponsesSource ###### discriminator ####### propertyName type #### required - type - source #### x-oaiMeta ##### name The completions data source object used to configure an individual run ##### group eval runs ##### example { "name": "gpt-4o-mini-2024-07-18", "data_source": { "type": "responses", "input_messages": { "type": "item_reference", "item_reference": "item.input" }, "model": "gpt-4o-mini-2024-07-18", "source": { "type": "responses", "model": "gpt-4o-mini-2024-07-18" } } } ### CreateEvalRunRequest #### type object #### title CreateEvalRunRequest #### properties ##### name ###### type string ###### description The name of the run. ##### metadata ###### $ref #/components/schemas/Metadata ##### data_source ###### type object ###### description Details about the run's data source. ###### anyOf ####### $ref #/components/schemas/CreateEvalJsonlRunDataSource ####### $ref #/components/schemas/CreateEvalCompletionsRunDataSource ####### $ref #/components/schemas/CreateEvalResponsesRunDataSource #### required - data_source ### CreateEvalStoredCompletionsDataSourceConfig #### type object #### title StoredCompletionsDataSourceConfig #### description Deprecated in favor of LogsDataSourceConfig. #### properties ##### type ###### type string ###### enum - stored_completions ###### default stored_completions ###### description The type of data source. Always `stored_completions`. ###### x-stainless-const true ##### metadata ###### type object ###### description Metadata filters for the stored completions data source. ###### additionalProperties true #### required - type #### deprecated true #### x-oaiMeta ##### name The stored completions data source object for evals ##### group evals ##### example { "type": "stored_completions", "metadata": { "use_case": "customer_support_agent" } } ### CreateFileRequest #### type object #### additionalProperties false #### properties ##### file ###### description The File object (not file name) to be uploaded. ###### type string ###### format binary ###### x-oaiMeta ####### exampleFilePath fine-tune.jsonl ##### purpose ###### $ref #/components/schemas/FilePurpose ##### expires_after ###### $ref #/components/schemas/FileExpirationAfter #### required - file - purpose ### CreateFineTuningCheckpointPermissionRequest #### type object #### additionalProperties false #### properties ##### project_ids ###### type array ###### description The project identifiers to grant access to. ###### items ####### type string #### required - project_ids ### CreateFineTuningJobRequest #### type object #### properties ##### model ###### description The name of the model to fine-tune. You can select one of the [supported models](https://platform.openai.com/docs/guides/fine-tuning#which-models-can-be-fine-tuned). ###### example gpt-4o-mini ###### anyOf ####### type string ####### type string ####### enum - babbage-002 - davinci-002 - gpt-3.5-turbo - gpt-4o-mini ####### title Preset ###### x-oaiTypeLabel string ##### training_file ###### description The ID of an uploaded file that contains training data. See [upload file](https://platform.openai.com/docs/api-reference/files/create) for how to upload a file. Your dataset must be formatted as a JSONL file. Additionally, you must upload your file with the purpose `fine-tune`. The contents of the file should differ depending on if the model uses the [chat](https://platform.openai.com/docs/api-reference/fine-tuning/chat-input), [completions](https://platform.openai.com/docs/api-reference/fine-tuning/completions-input) format, or if the fine-tuning method uses the [preference](https://platform.openai.com/docs/api-reference/fine-tuning/preference-input) format. See the [fine-tuning guide](https://platform.openai.com/docs/guides/model-optimization) for more details. ###### type string ###### example file-abc123 ##### hyperparameters ###### type object ###### description The hyperparameters used for the fine-tuning job. This value is now deprecated in favor of `method`, and should be passed in under the `method` parameter. ###### 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. ######## default auto ######## anyOf ######### type string ######### enum - auto ######### x-stainless-const true ######### title Auto ######### type integer ######### minimum 1 ######### maximum 256 ####### learning_rate_multiplier ######## description Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting. ######## anyOf ######### type string ######### enum - auto ######### x-stainless-const true ######### title Auto ######### type number ######### minimum 0 ######### exclusiveMinimum true ####### n_epochs ######## description The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset. ######## default auto ######## anyOf ######### type string ######### enum - auto ######### x-stainless-const true ######### title Auto ######### type integer ######### minimum 1 ######### maximum 50 ###### deprecated true ##### suffix ###### description A string of up to 64 characters that will be added to your fine-tuned model name. For example, a `suffix` of "custom-model-name" would produce a model name like `ft:gpt-4o-mini:openai:custom-model-name:7p4lURel`. ###### type string ###### minLength 1 ###### maxLength 64 ###### default null ###### nullable true ##### validation_file ###### description The ID of an uploaded file that contains validation data. If you provide this file, the data is used to generate validation metrics periodically during fine-tuning. These metrics can be viewed in the fine-tuning results file. The same data should not be present in both train and validation files. Your dataset must be formatted as a JSONL file. You must upload your file with the purpose `fine-tune`. See the [fine-tuning guide](https://platform.openai.com/docs/guides/model-optimization) for more details. ###### type string ###### nullable true ###### example file-abc123 ##### integrations ###### type array ###### description A list of integrations to enable for your fine-tuning job. ###### nullable true ###### items ####### type object ####### required - type - wandb ####### properties ######## type ######### description The type of integration to enable. Currently, only "wandb" (Weights and Biases) is supported. ######### anyOf ########## type string ########## 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 ##### seed ###### description The seed controls the reproducibility of the job. Passing in the same seed and job parameters should produce the same results, but may differ in rare cases. If a seed is not specified, one will be generated for you. ###### type integer ###### nullable true ###### minimum 0 ###### maximum 2147483647 ###### example 42 ##### method ###### $ref #/components/schemas/FineTuneMethod ##### metadata ###### $ref #/components/schemas/Metadata #### required - model - training_file ### CreateImageEditRequest #### type object #### properties ##### image ###### anyOf ####### type string ####### format binary ####### type array ####### maxItems 16 ####### items ######## type string ######## format binary ###### description The image(s) to edit. Must be a supported image file or an array of images. For `gpt-image-1`, each image should be a `png`, `webp`, or `jpg` file less than 50MB. You can provide up to 16 images. For `dall-e-2`, you can only provide one image, and it should be a square `png` file less than 4MB. ###### x-oaiMeta ####### exampleFilePath otter.png ##### prompt ###### description A text description of the desired image(s). The maximum length is 1000 characters for `dall-e-2`, and 32000 characters for `gpt-image-1`. ###### type string ###### example A cute baby sea otter wearing a beret ##### mask ###### description An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where `image` should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as `image`. ###### type string ###### format binary ###### x-oaiMeta ####### exampleFilePath mask.png ##### background ###### type string ###### enum - transparent - opaque - auto ###### default auto ###### example transparent ###### nullable true ###### description Allows to set transparency for the background of the generated image(s). This parameter is only supported for `gpt-image-1`. Must be one of `transparent`, `opaque` or `auto` (default value). When `auto` is used, the model will automatically determine the best background for the image. If `transparent`, the output format needs to support transparency, so it should be set to either `png` (default value) or `webp`. ##### model ###### anyOf ####### type string ####### type string ####### enum - dall-e-2 - gpt-image-1 ####### x-stainless-const true ###### x-oaiTypeLabel string ###### nullable true ###### description The model to use for image generation. Only `dall-e-2` and `gpt-image-1` are supported. Defaults to `dall-e-2` unless a parameter specific to `gpt-image-1` is used. ##### n ###### type integer ###### minimum 1 ###### maximum 10 ###### default 1 ###### example 1 ###### nullable true ###### description The number of images to generate. Must be between 1 and 10. ##### size ###### type string ###### enum - 256x256 - 512x512 - 1024x1024 - 1536x1024 - 1024x1536 - auto ###### default 1024x1024 ###### example 1024x1024 ###### nullable true ###### description The size of the generated images. Must be one of `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto` (default value) for `gpt-image-1`, and one of `256x256`, `512x512`, or `1024x1024` for `dall-e-2`. ##### response_format ###### type string ###### enum - url - b64_json ###### default url ###### example url ###### nullable true ###### description The format in which the generated images are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter is only supported for `dall-e-2`, as `gpt-image-1` will always return base64-encoded images. ##### output_format ###### type string ###### enum - png - jpeg - webp ###### default png ###### example png ###### nullable true ###### description The format in which the generated images are returned. This parameter is only supported for `gpt-image-1`. Must be one of `png`, `jpeg`, or `webp`. The default value is `png`. ##### output_compression ###### type integer ###### default 100 ###### example 100 ###### nullable true ###### description The compression level (0-100%) for the generated images. This parameter is only supported for `gpt-image-1` with the `webp` or `jpeg` output formats, and defaults to 100. ##### 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](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids). ##### input_fidelity ###### $ref #/components/schemas/ImageInputFidelity ##### stream ###### type boolean ###### default false ###### example false ###### nullable true ###### description Edit the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://platform.openai.com/docs/guides/image-generation) for more information. ##### partial_images ###### $ref #/components/schemas/PartialImages ##### quality ###### type string ###### enum - standard - low - medium - high - auto ###### default auto ###### example high ###### nullable true ###### description The quality of the image that will be generated. `high`, `medium` and `low` are only supported for `gpt-image-1`. `dall-e-2` only supports `standard` quality. Defaults to `auto`. #### required - prompt - image ### CreateImageRequest #### type object #### properties ##### prompt ###### description A text description of the desired image(s). The maximum length is 32000 characters for `gpt-image-1`, 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`. ###### type string ###### example A cute baby sea otter ##### model ###### anyOf ####### type string ####### type string ####### enum - dall-e-2 - dall-e-3 - gpt-image-1 ####### x-stainless-nominal false ###### x-oaiTypeLabel string ###### nullable true ###### description The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or `gpt-image-1`. Defaults to `dall-e-2` unless a parameter specific to `gpt-image-1` is used. ##### n ###### type integer ###### minimum 1 ###### maximum 10 ###### default 1 ###### example 1 ###### nullable true ###### description The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported. ##### quality ###### type string ###### enum - standard - hd - low - medium - high - auto ###### default auto ###### example medium ###### nullable true ###### description The quality of the image that will be generated. - `auto` (default value) will automatically select the best quality for the given model. - `high`, `medium` and `low` are supported for `gpt-image-1`. - `hd` and `standard` are supported for `dall-e-3`. - `standard` is the only option for `dall-e-2`. ##### response_format ###### type string ###### enum - url - b64_json ###### default url ###### example url ###### nullable true ###### description The format in which generated images with `dall-e-2` and `dall-e-3` are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter isn't supported for `gpt-image-1` which will always return base64-encoded images. ##### output_format ###### type string ###### enum - png - jpeg - webp ###### default png ###### example png ###### nullable true ###### description The format in which the generated images are returned. This parameter is only supported for `gpt-image-1`. Must be one of `png`, `jpeg`, or `webp`. ##### output_compression ###### type integer ###### default 100 ###### example 100 ###### nullable true ###### description The compression level (0-100%) for the generated images. This parameter is only supported for `gpt-image-1` with the `webp` or `jpeg` output formats, and defaults to 100. ##### stream ###### type boolean ###### default false ###### example false ###### nullable true ###### description Generate the image in streaming mode. Defaults to `false`. See the [Image generation guide](https://platform.openai.com/docs/guides/image-generation) for more information. This parameter is only supported for `gpt-image-1`. ##### partial_images ###### $ref #/components/schemas/PartialImages ##### size ###### type string ###### enum - auto - 1024x1024 - 1536x1024 - 1024x1536 - 256x256 - 512x512 - 1792x1024 - 1024x1792 ###### default auto ###### example 1024x1024 ###### nullable true ###### description The size of the generated images. Must be one of `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto` (default value) for `gpt-image-1`, one of `256x256`, `512x512`, or `1024x1024` for `dall-e-2`, and one of `1024x1024`, `1792x1024`, or `1024x1792` for `dall-e-3`. ##### moderation ###### type string ###### enum - low - auto ###### default auto ###### example low ###### nullable true ###### description Control the content-moderation level for images generated by `gpt-image-1`. Must be either `low` for less restrictive filtering or `auto` (default value). ##### background ###### type string ###### enum - transparent - opaque - auto ###### default auto ###### example transparent ###### nullable true ###### description Allows to set transparency for the background of the generated image(s). This parameter is only supported for `gpt-image-1`. Must be one of `transparent`, `opaque` or `auto` (default value). When `auto` is used, the model will automatically determine the best background for the image. If `transparent`, the output format needs to support transparency, so it should be set to either `png` (default value) or `webp`. ##### style ###### type string ###### enum - vivid - natural ###### default vivid ###### example vivid ###### nullable true ###### description The style of the generated images. This parameter is only supported for `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images. ##### 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](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids). #### required - prompt ### CreateImageVariationRequest #### type object #### properties ##### image ###### description The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square. ###### type string ###### format binary ###### x-oaiMeta ####### exampleFilePath otter.png ##### model ###### anyOf ####### type string ####### type string ####### enum - dall-e-2 ####### x-stainless-const true ###### x-oaiTypeLabel string ###### nullable true ###### description The model to use for image generation. Only `dall-e-2` is supported at this time. ##### n ###### type integer ###### minimum 1 ###### maximum 10 ###### default 1 ###### example 1 ###### nullable true ###### description The number of images to generate. Must be between 1 and 10. ##### response_format ###### type string ###### enum - url - b64_json ###### default url ###### example url ###### nullable true ###### description The format in which the generated images are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. ##### size ###### type string ###### enum - 256x256 - 512x512 - 1024x1024 ###### default 1024x1024 ###### example 1024x1024 ###### nullable true ###### description The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`. ##### 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](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids). #### required - image ### CreateMessageRequest #### type object #### additionalProperties false #### required - role - content #### properties ##### role ###### type string ###### enum - user - assistant ###### description The role of the entity that is creating the message. Allowed values include: - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. ##### content ###### anyOf ####### type string ####### description The text contents of the message. ####### title Text content ####### type array ####### description An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](https://platform.openai.com/docs/models). ####### title Array of content parts ####### items ######## anyOf ######### $ref #/components/schemas/MessageContentImageFileObject ######### $ref #/components/schemas/MessageContentImageUrlObject ######### $ref #/components/schemas/MessageRequestContentTextObject ######## discriminator ######### propertyName type ####### minItems 1 ##### 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 ########## anyOf ########### $ref #/components/schemas/AssistantToolsCode ########### $ref #/components/schemas/AssistantToolsFileSearchTypeOnly ########## discriminator ########### propertyName type ###### description A list of files attached to the message, and the tools they should be added to. ###### required - file_id - tools ###### nullable true ##### metadata ###### $ref #/components/schemas/Metadata ### CreateModelResponseProperties #### allOf ##### $ref #/components/schemas/ModelResponseProperties ##### type object ##### properties ###### top_logprobs ####### description An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. ####### type integer ####### minimum 0 ####### maximum 20 ### CreateModerationRequest #### type object #### properties ##### input ###### description Input (or inputs) to classify. Can be a single string, an array of strings, or an array of multi-modal input objects similar to other models. ###### anyOf ####### type string ####### description A string of text to classify for moderation. ####### default ####### example I want to kill them. ####### type array ####### description An array of strings to classify for moderation. ####### items ######## type string ######## default ######## example I want to kill them. ####### type array ####### description An array of multi-modal inputs to the moderation model. ####### items ######## anyOf ######### $ref #/components/schemas/ModerationImageURLInput ######### $ref #/components/schemas/ModerationTextInput ######## discriminator ######### propertyName type ####### title Moderation Multi Modal Array ##### model ###### description The content moderation model you would like to use. Learn more in [the moderation guide](https://platform.openai.com/docs/guides/moderation), and learn about available models [here](https://platform.openai.com/docs/models#moderation). ###### nullable false ###### anyOf ####### type string ####### type string ####### enum - omni-moderation-latest - omni-moderation-2024-09-26 - text-moderation-latest - text-moderation-stable ####### x-stainless-nominal false ###### x-oaiTypeLabel string #### required - input ### CreateModerationResponse #### type object #### description Represents if a given text input is potentially harmful. #### properties ##### id ###### type string ###### description The unique identifier for the moderation request. ##### model ###### type string ###### description The model used to generate the moderation results. ##### results ###### type array ###### description A list of moderation objects. ###### items ####### type object ####### properties ######## flagged ######### type boolean ######### description Whether any of the below categories are flagged. ######## categories ######### type object ######### description A list of the categories, and whether they are flagged or not. ######### properties ########## hate ########### type boolean ########### description Content that expresses, incites, or promotes hate based on race, gender, ethnicity, religion, nationality, sexual orientation, disability status, or caste. Hateful content aimed at non-protected groups (e.g., chess players) is harassment. ########## hate/threatening ########### type boolean ########### description Hateful content that also includes violence or serious harm towards the targeted group based on race, gender, ethnicity, religion, nationality, sexual orientation, disability status, or caste. ########## harassment ########### type boolean ########### description Content that expresses, incites, or promotes harassing language towards any target. ########## harassment/threatening ########### type boolean ########### description Harassment content that also includes violence or serious harm towards any target. ########## illicit ########### type boolean ########### nullable true ########### description Content that includes instructions or advice that facilitate the planning or execution of wrongdoing, or that gives advice or instruction on how to commit illicit acts. For example, "how to shoplift" would fit this category. ########## illicit/violent ########### type boolean ########### nullable true ########### description Content that includes instructions or advice that facilitate the planning or execution of wrongdoing that also includes violence, or that gives advice or instruction on the procurement of any weapon. ########## self-harm ########### type boolean ########### description Content that promotes, encourages, or depicts acts of self-harm, such as suicide, cutting, and eating disorders. ########## self-harm/intent ########### type boolean ########### description Content where the speaker expresses that they are engaging or intend to engage in acts of self-harm, such as suicide, cutting, and eating disorders. ########## self-harm/instructions ########### type boolean ########### description Content that encourages performing acts of self-harm, such as suicide, cutting, and eating disorders, or that gives instructions or advice on how to commit such acts. ########## sexual ########### type boolean ########### description Content meant to arouse sexual excitement, such as the description of sexual activity, or that promotes sexual services (excluding sex education and wellness). ########## sexual/minors ########### type boolean ########### description Sexual content that includes an individual who is under 18 years old. ########## violence ########### type boolean ########### description Content that depicts death, violence, or physical injury. ########## violence/graphic ########### type boolean ########### description Content that depicts death, violence, or physical injury in graphic detail. ######### required - hate - hate/threatening - harassment - harassment/threatening - illicit - illicit/violent - self-harm - self-harm/intent - self-harm/instructions - sexual - sexual/minors - violence - violence/graphic ######## category_scores ######### type object ######### description A list of the categories along with their scores as predicted by model. ######### properties ########## hate ########### type number ########### description The score for the category 'hate'. ########## hate/threatening ########### type number ########### description The score for the category 'hate/threatening'. ########## harassment ########### type number ########### description The score for the category 'harassment'. ########## harassment/threatening ########### type number ########### description The score for the category 'harassment/threatening'. ########## illicit ########### type number ########### description The score for the category 'illicit'. ########## illicit/violent ########### type number ########### description The score for the category 'illicit/violent'. ########## self-harm ########### type number ########### description The score for the category 'self-harm'. ########## self-harm/intent ########### type number ########### description The score for the category 'self-harm/intent'. ########## self-harm/instructions ########### type number ########### description The score for the category 'self-harm/instructions'. ########## sexual ########### type number ########### description The score for the category 'sexual'. ########## sexual/minors ########### type number ########### description The score for the category 'sexual/minors'. ########## violence ########### type number ########### description The score for the category 'violence'. ########## violence/graphic ########### type number ########### description The score for the category 'violence/graphic'. ######### required - hate - hate/threatening - harassment - harassment/threatening - illicit - illicit/violent - self-harm - self-harm/intent - self-harm/instructions - sexual - sexual/minors - violence - violence/graphic ######## category_applied_input_types ######### type object ######### description A list of the categories along with the input type(s) that the score applies to. ######### properties ########## hate ########### type array ########### description The applied input type(s) for the category 'hate'. ########### items ############ type string ############ enum - text ############ x-stainless-const true ########## hate/threatening ########### type array ########### description The applied input type(s) for the category 'hate/threatening'. ########### items ############ type string ############ enum - text ############ x-stainless-const true ########## harassment ########### type array ########### description The applied input type(s) for the category 'harassment'. ########### items ############ type string ############ enum - text ############ x-stainless-const true ########## harassment/threatening ########### type array ########### description The applied input type(s) for the category 'harassment/threatening'. ########### items ############ type string ############ enum - text ############ x-stainless-const true ########## illicit ########### type array ########### description The applied input type(s) for the category 'illicit'. ########### items ############ type string ############ enum - text ############ x-stainless-const true ########## illicit/violent ########### type array ########### description The applied input type(s) for the category 'illicit/violent'. ########### items ############ type string ############ enum - text ############ x-stainless-const true ########## self-harm ########### type array ########### description The applied input type(s) for the category 'self-harm'. ########### items ############ type string ############ enum - text - image ########## self-harm/intent ########### type array ########### description The applied input type(s) for the category 'self-harm/intent'. ########### items ############ type string ############ enum - text - image ########## self-harm/instructions ########### type array ########### description The applied input type(s) for the category 'self-harm/instructions'. ########### items ############ type string ############ enum - text - image ########## sexual ########### type array ########### description The applied input type(s) for the category 'sexual'. ########### items ############ type string ############ enum - text - image ########## sexual/minors ########### type array ########### description The applied input type(s) for the category 'sexual/minors'. ########### items ############ type string ############ enum - text ############ x-stainless-const true ########## violence ########### type array ########### description The applied input type(s) for the category 'violence'. ########### items ############ type string ############ enum - text - image ########## violence/graphic ########### type array ########### description The applied input type(s) for the category 'violence/graphic'. ########### items ############ type string ############ enum - text - image ######### required - hate - hate/threatening - harassment - harassment/threatening - illicit - illicit/violent - self-harm - self-harm/intent - self-harm/instructions - sexual - sexual/minors - violence - violence/graphic ####### required - flagged - categories - category_scores - category_applied_input_types #### required - id - 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](https://platform.openai.com/docs/guides/text) - [Image inputs](https://platform.openai.com/docs/guides/images) - [File inputs](https://platform.openai.com/docs/guides/pdf-files) - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) - [Function calling](https://platform.openai.com/docs/guides/function-calling) ####### anyOf ######## type string ######## title Text input ######## description A text input to the model, equivalent to a text input with the `user` role. ######## type array ######## title Input item list ######## description A list of one or many input items to the model, containing different content types. ######## items ######### $ref #/components/schemas/InputItem ###### include ####### type array ####### description Specify additional output data to include in the model response. Currently supported values are: - `web_search_call.action.sources`: Include the sources of the web search tool call. - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - `computer_call_output.output.image_url`: Include image urls from the computer call output. - `file_search_call.results`: Include the search results of the file search tool call. - `message.input_image.image_url`: Include image urls from the input message. - `message.output_text.logprobs`: Include logprobs with assistant messages. - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). ####### items ######## $ref #/components/schemas/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 ###### instructions ####### type string ####### nullable true ####### description A system (or developer) message inserted into the model's context. When using along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. ###### 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](https://platform.openai.com/docs/api-reference/responses-streaming) for more information. ####### type boolean ####### nullable true ####### default false ###### stream_options ####### $ref #/components/schemas/ResponseStreamOptions ###### conversation ####### description The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. Input items and output items from this response are automatically added to this conversation after this response completes. ####### nullable true ####### anyOf ######## type string ######## title Conversation ID ######## description The unique ID of the conversation. ######## $ref #/components/schemas/ConversationParam ### CreateRunRequest #### type object #### additionalProperties false #### properties ##### assistant_id ###### description The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. ###### type string ##### model ###### description The ID of the [Model](https://platform.openai.com/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. ###### anyOf ####### type string ####### $ref #/components/schemas/AssistantSupportedModels ###### x-oaiTypeLabel string ###### nullable true ##### reasoning_effort ###### $ref #/components/schemas/ReasoningEffort ##### instructions ###### description Overrides the [instructions](https://platform.openai.com/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 ####### $ref #/components/schemas/AssistantTool ##### 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](https://platform.openai.com/docs/models#tts): `tts-1`, `tts-1-hd` or `gpt-4o-mini-tts`. ###### anyOf ####### type string ####### type string ####### enum - tts-1 - tts-1-hd - gpt-4o-mini-tts ####### x-stainless-nominal false ###### x-oaiTypeLabel string ##### input ###### type string ###### description The text to generate audio for. The maximum length is 4096 characters. ###### maxLength 4096 ##### instructions ###### type string ###### description Control the voice of your generated audio with additional instructions. Does not work with `tts-1` or `tts-1-hd`. ###### maxLength 4096 ##### voice ###### description The voice to use when generating the audio. Supported voices are `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer`, and `verse`. Previews of the voices are available in the [Text to speech guide](https://platform.openai.com/docs/guides/text-to-speech#voice-options). ###### $ref #/components/schemas/VoiceIdsShared ##### 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 ##### stream_format ###### description The format to stream the audio in. Supported formats are `sse` and `audio`. `sse` is not supported for `tts-1` or `tts-1-hd`. ###### type string ###### default audio ###### enum - sse - audio #### required - model - input - voice ### CreateSpeechResponseStreamEvent #### anyOf ##### $ref #/components/schemas/SpeechAudioDeltaEvent ##### $ref #/components/schemas/SpeechAudioDoneEvent #### discriminator ##### propertyName type ### CreateThreadAndRunRequest #### type object #### additionalProperties false #### properties ##### assistant_id ###### description The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. ###### type string ##### thread ###### $ref #/components/schemas/CreateThreadRequest ##### model ###### description The ID of the [Model](https://platform.openai.com/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. ###### anyOf ####### type string ####### type string ####### enum - gpt-5 - gpt-5-mini - gpt-5-nano - gpt-5-2025-08-07 - gpt-5-mini-2025-08-07 - gpt-5-nano-2025-08-07 - gpt-4.1 - gpt-4.1-mini - gpt-4.1-nano - gpt-4.1-2025-04-14 - gpt-4.1-mini-2025-04-14 - gpt-4.1-nano-2025-04-14 - 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 ####### $ref #/components/schemas/AssistantTool ##### 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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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. ############# anyOf ############## 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-stainless-naming ############### java ################ type_name StaticObject ############### kotlin ################ type_name StaticObject ############# discriminator ############## propertyName type ############ metadata ############# $ref #/components/schemas/Metadata ######## anyOf ######### 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 ###### x-oaiMeta ####### exampleFilePath speech.mp3 ##### model ###### description ID of the model to use. The options are `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, and `whisper-1` (which is powered by our open source Whisper V2 model). ###### example gpt-4o-transcribe ###### anyOf ####### type string ####### type string ####### enum - whisper-1 - gpt-4o-transcribe - gpt-4o-mini-transcribe ####### x-stainless-const true ####### x-stainless-nominal false ###### 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](https://platform.openai.com/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 ##### 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 of the Speech-to-Text guide](https://platform.openai.com/docs/guides/speech-to-text?lang=curl#streaming-transcriptions) for more information. Note: Streaming is not supported for the `whisper-1` model and will be ignored. ###### type boolean ###### nullable true ###### default false ##### chunking_strategy ###### $ref #/components/schemas/TranscriptionChunkingStrategy ##### 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 ##### include ###### description Additional information to include in the transcription response. `logprobs` will return the log probabilities of the tokens in the response to understand the model's confidence in the transcription. `logprobs` only works with response_format set to `json` and only with the models `gpt-4o-transcribe` and `gpt-4o-mini-transcribe`. ###### type array ###### items ####### $ref #/components/schemas/TranscriptionInclude #### 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. ##### logprobs ###### type array ###### optional true ###### description The log probabilities of the tokens in the transcription. Only returned with the models `gpt-4o-transcribe` and `gpt-4o-mini-transcribe` if `logprobs` is added to the `include` array. ###### items ####### type object ####### properties ######## token ######### type string ######### description The token in the transcription. ######## logprob ######### type number ######### description The log probability of the token. ######## bytes ######### type array ######### items ########## type number ######### description The bytes of the token. ##### usage ###### type object ###### description Token usage statistics for the request. ###### anyOf ####### $ref #/components/schemas/TranscriptTextUsageTokens ####### title Token Usage ####### $ref #/components/schemas/TranscriptTextUsageDuration ####### title Duration Usage ###### discriminator ####### propertyName type #### 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.", "usage": { "type": "tokens", "input_tokens": 14, "input_token_details": { "text_tokens": 10, "audio_tokens": 4 }, "output_tokens": 101, "total_tokens": 115 } } ### CreateTranscriptionResponseStreamEvent #### anyOf ##### $ref #/components/schemas/TranscriptTextDeltaEvent ##### $ref #/components/schemas/TranscriptTextDoneEvent #### discriminator ##### propertyName type ### 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 ##### usage ###### $ref #/components/schemas/TranscriptTextUsageDuration #### 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 }, ... ], "usage": { "type": "duration", "seconds": 9 } } ### 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 ###### x-oaiMeta ####### exampleFilePath speech.mp3 ##### 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](https://platform.openai.com/docs/guides/speech-to-text#prompting) should be in English. ###### type string ##### response_format ###### description The format of the output, in one of these options: `json`, `text`, `srt`, `verbose_json`, or `vtt`. ###### type string ###### enum - json - text - srt - verbose_json - vtt ###### default json ##### 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](https://platform.openai.com/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 ##### expires_after ###### $ref #/components/schemas/FileExpirationAfter #### required - filename - purpose - bytes - mime_type ### CreateVectorStoreFileBatchRequest #### type object #### additionalProperties false #### properties ##### file_ids ###### description A list of [File](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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 ###### $ref #/components/schemas/ChunkingStrategyRequestParam ##### metadata ###### $ref #/components/schemas/Metadata ### CustomTool #### type object #### title Custom tool #### description A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools). #### properties ##### type ###### type string ###### enum - custom ###### description The type of the custom tool. Always `custom`. ###### x-stainless-const true ##### name ###### type string ###### description The name of the custom tool, used to identify it in tool calls. ##### description ###### type string ###### description Optional description of the custom tool, used to provide more context. ##### format ###### description The input format for the custom tool. Default is unconstrained text. ###### anyOf ####### type object ####### title Text format ####### description Unconstrained free-form text. ####### properties ######## type ######### type string ######### enum - text ######### description Unconstrained text format. Always `text`. ######### x-stainless-const true ####### required - type ####### additionalProperties false ####### type object ####### title Grammar format ####### description A grammar defined by the user. ####### properties ######## type ######### type string ######### enum - grammar ######### description Grammar format. Always `grammar`. ######### x-stainless-const true ######## definition ######### type string ######### description The grammar definition. ######## syntax ######### type string ######### description The syntax of the grammar definition. One of `lark` or `regex`. ######### enum - lark - regex ####### required - type - definition - syntax ####### additionalProperties false ###### discriminator ####### propertyName type #### required - type - name ### CustomToolCall #### type object #### title Custom tool call #### description A call to a custom tool created by the model. #### properties ##### type ###### type string ###### enum - custom_tool_call ###### x-stainless-const true ###### description The type of the custom tool call. Always `custom_tool_call`. ##### id ###### type string ###### description The unique ID of the custom tool call in the OpenAI platform. ##### call_id ###### type string ###### description An identifier used to map this custom tool call to a tool call output. ##### name ###### type string ###### description The name of the custom tool being called. ##### input ###### type string ###### description The input for the custom tool call generated by the model. #### required - type - call_id - name - input ### CustomToolCallOutput #### type object #### title Custom tool call output #### description The output of a custom tool call from your code, being sent back to the model. #### properties ##### type ###### type string ###### enum - custom_tool_call_output ###### x-stainless-const true ###### description The type of the custom tool call output. Always `custom_tool_call_output`. ##### id ###### type string ###### description The unique ID of the custom tool call output in the OpenAI platform. ##### call_id ###### type string ###### description The call ID, used to map this custom tool call output to a custom tool call. ##### output ###### type string ###### description The output from the custom tool call generated by your code. #### required - type - call_id - output ### CustomToolChatCompletions #### type object #### title Custom tool #### description A custom tool that processes input using a specified format. #### properties ##### type ###### type string ###### enum - custom ###### description The type of the custom tool. Always `custom`. ###### x-stainless-const true ##### custom ###### type object ###### title Custom tool properties ###### description Properties of the custom tool. ###### properties ####### name ######## type string ######## description The name of the custom tool, used to identify it in tool calls. ####### description ######## type string ######## description Optional description of the custom tool, used to provide more context. ####### format ######## description The input format for the custom tool. Default is unconstrained text. ######## anyOf ######### type object ######### title Text format ######### description Unconstrained free-form text. ######### properties ########## type ########### type string ########### enum - text ########### description Unconstrained text format. Always `text`. ########### x-stainless-const true ######### required - type ######### additionalProperties false ######### type object ######### title Grammar format ######### description A grammar defined by the user. ######### properties ########## type ########### type string ########### enum - grammar ########### description Grammar format. Always `grammar`. ########### x-stainless-const true ########## grammar ########### type object ########### title Grammar format ########### description Your chosen grammar. ########### properties ############ definition ############# type string ############# description The grammar definition. ############ syntax ############# type string ############# description The syntax of the grammar definition. One of `lark` or `regex`. ############# enum - lark - regex ########### required - definition - syntax ######### required - type - grammar ######### additionalProperties false ######## discriminator ######### propertyName type ###### required - name #### required - type - custom ### DeleteAssistantResponse #### type object #### properties ##### id ###### type string ##### deleted ###### type boolean ##### object ###### type string ###### enum - assistant.deleted ###### x-stainless-const true #### required - id - object - deleted ### DeleteCertificateResponse #### type object #### properties ##### object ###### description The object type, must be `certificate.deleted`. ###### x-stainless-const true ###### const certificate.deleted ##### id ###### type string ###### description The ID of the certificate that was deleted. #### required - object - id ### DeleteFileResponse #### type object #### properties ##### id ###### type string ##### object ###### type string ###### enum - file ###### x-stainless-const true ##### deleted ###### type boolean #### required - id - object - deleted ### DeleteFineTuningCheckpointPermissionResponse #### type object #### properties ##### id ###### type string ###### description The ID of the fine-tuned model checkpoint permission that was deleted. ##### object ###### type string ###### description The object type, which is always "checkpoint.permission". ###### enum - checkpoint.permission ###### x-stainless-const true ##### deleted ###### type boolean ###### description Whether the fine-tuned model checkpoint permission was successfully deleted. #### 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 ### DeletedConversation #### title The deleted conversation object #### allOf ##### $ref #/components/schemas/DeletedConversationResource #### x-oaiMeta ##### name The deleted conversation object ##### group conversations ### 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 } ] ``` ###### items ####### title Drag path coordinates ####### 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. ###### anyOf ####### 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](https://platform.openai.com/docs/guides/embeddings). ###### items ####### type number ####### format float ##### 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](https://platform.openai.com/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 ### Eval #### type object #### title Eval #### description An Eval object with a data source config and testing criteria. An Eval represents a task to be done for your LLM integration. Like: - Improve the quality of my chatbot - See how well my chatbot handles customer support - Check if o4-mini is better at my usecase than gpt-4o #### properties ##### object ###### type string ###### enum - eval ###### default eval ###### description The object type. ###### x-stainless-const true ##### id ###### type string ###### description Unique identifier for the evaluation. ##### name ###### type string ###### description The name of the evaluation. ###### example Chatbot effectiveness Evaluation ##### data_source_config ###### type object ###### description Configuration of data sources used in runs of the evaluation. ###### anyOf ####### $ref #/components/schemas/EvalCustomDataSourceConfig ####### $ref #/components/schemas/EvalLogsDataSourceConfig ####### $ref #/components/schemas/EvalStoredCompletionsDataSourceConfig ###### discriminator ####### propertyName type ##### testing_criteria ###### description A list of testing criteria. ###### type array ###### items ####### anyOf ######## $ref #/components/schemas/EvalGraderLabelModel ######## $ref #/components/schemas/EvalGraderStringCheck ######## $ref #/components/schemas/EvalGraderTextSimilarity ######## $ref #/components/schemas/EvalGraderPython ######## $ref #/components/schemas/EvalGraderScoreModel ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) for when the eval was created. ##### metadata ###### $ref #/components/schemas/Metadata #### required - id - data_source_config - object - testing_criteria - name - created_at - metadata #### x-oaiMeta ##### name The eval object ##### group evals ##### example { "object": "eval", "id": "eval_67abd54d9b0081909a86353f6fb9317a", "data_source_config": { "type": "custom", "item_schema": { "type": "object", "properties": { "label": {"type": "string"}, }, "required": ["label"] }, "include_sample_schema": true }, "testing_criteria": [ { "name": "My string check grader", "type": "string_check", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "operation": "eq", } ], "name": "External Data Eval", "created_at": 1739314509, "metadata": { "test": "synthetics", } } ### EvalApiError #### type object #### title EvalApiError #### description An object representing an error response from the Eval API. #### properties ##### code ###### type string ###### description The error code. ##### message ###### type string ###### description The error message. #### required - code - message #### x-oaiMeta ##### name The API error object ##### group evals ##### example { "code": "internal_error", "message": "The eval run failed due to an internal error." } ### EvalCustomDataSourceConfig #### type object #### title CustomDataSourceConfig #### description A CustomDataSourceConfig which specifies the schema of your `item` and optionally `sample` namespaces. The response schema defines the shape of the data that will be: - Used to define your testing criteria and - What data is required when creating a run #### properties ##### type ###### type string ###### enum - custom ###### default custom ###### description The type of data source. Always `custom`. ###### x-stainless-const true ##### schema ###### type object ###### description The json schema for the run data source items. Learn how to build JSON schemas [here](https://json-schema.org/). ###### additionalProperties true #### required - type - schema #### x-oaiMeta ##### name The eval custom data source config object ##### group evals ##### example { "type": "custom", "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "label": {"type": "string"}, }, "required": ["label"] } }, "required": ["item"] } } ### EvalGraderLabelModel #### type object #### title LabelModelGrader #### allOf ##### $ref #/components/schemas/GraderLabelModel ### EvalGraderPython #### type object #### title PythonGrader #### allOf ##### $ref #/components/schemas/GraderPython ##### type object ##### properties ###### pass_threshold ####### type number ####### description The threshold for the score. ##### x-oaiMeta ###### name Eval Python Grader ###### group graders ###### example { "type": "python", "name": "Example python grader", "image_tag": "2025-05-08", "source": """ def grade(sample: dict, item: dict) -> float: \""" Returns 1.0 if `output_text` equals `label`, otherwise 0.0. \""" output = sample.get("output_text") label = item.get("label") return 1.0 if output == label else 0.0 """, "pass_threshold": 0.8 } ### EvalGraderScoreModel #### type object #### title ScoreModelGrader #### allOf ##### $ref #/components/schemas/GraderScoreModel ##### type object ##### properties ###### pass_threshold ####### type number ####### description The threshold for the score. ### EvalGraderStringCheck #### type object #### title StringCheckGrader #### allOf ##### $ref #/components/schemas/GraderStringCheck ### EvalGraderTextSimilarity #### type object #### title TextSimilarityGrader #### allOf ##### $ref #/components/schemas/GraderTextSimilarity ##### type object ##### properties ###### pass_threshold ####### type number ####### description The threshold for the score. ##### required - pass_threshold ##### x-oaiMeta ###### name Text Similarity Grader ###### group graders ###### example { "type": "text_similarity", "name": "Example text similarity grader", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "pass_threshold": 0.8, "evaluation_metric": "fuzzy_match" } ### EvalItem #### type object #### title Eval message object #### 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 Inputs to the model - can contain template strings. ###### anyOf ####### type string ####### title Text input ####### description A text input to the model. ####### $ref #/components/schemas/InputTextContent ####### type object ####### title Output text ####### description A text output from the model. ####### properties ######## 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. ####### required - type - text ####### type object ####### title Input image ####### description An image input to the model. ####### properties ######## type ######### type string ######### description The type of the image input. Always `input_image`. ######### enum - input_image ######### x-stainless-const true ######## image_url ######### type string ######### description The URL of the image input. ######## 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`. ####### required - type - image_url ####### type array ####### title An array of Input text and Input image ####### description A list of inputs, each of which may be either an input text or input image object. ##### type ###### type string ###### description The type of the message input. Always `message`. ###### enum - message ###### x-stainless-const true #### required - role - content ### EvalJsonlFileContentSource #### type object #### title EvalJsonlFileContentSource #### properties ##### type ###### type string ###### enum - file_content ###### default file_content ###### description The type of jsonl source. Always `file_content`. ###### x-stainless-const true ##### content ###### type array ###### items ####### type object ####### properties ######## item ######### type object ######### additionalProperties true ######## sample ######### type object ######### additionalProperties true ####### required - item ###### description The content of the jsonl file. #### required - type - content ### EvalJsonlFileIdSource #### type object #### title EvalJsonlFileIdSource #### properties ##### type ###### type string ###### enum - file_id ###### default file_id ###### description The type of jsonl source. Always `file_id`. ###### x-stainless-const true ##### id ###### type string ###### description The identifier of the file. #### required - type - id ### EvalList #### type object #### title EvalList #### description An object representing a list of evals. #### 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 eval objects. ###### items ####### $ref #/components/schemas/Eval ##### first_id ###### type string ###### description The identifier of the first eval in the data array. ##### last_id ###### type string ###### description The identifier of the last eval in the data array. ##### has_more ###### type boolean ###### description Indicates whether there are more evals available. #### required - object - data - first_id - last_id - has_more #### x-oaiMeta ##### name The eval list object ##### group evals ##### example { "object": "list", "data": [ { "object": "eval", "id": "eval_67abd54d9b0081909a86353f6fb9317a", "data_source_config": { "type": "custom", "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "input": { "type": "string" }, "ground_truth": { "type": "string" } }, "required": [ "input", "ground_truth" ] } }, "required": [ "item" ] } }, "testing_criteria": [ { "name": "String check", "id": "String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2", "type": "string_check", "input": "{{item.input}}", "reference": "{{item.ground_truth}}", "operation": "eq" } ], "name": "External Data Eval", "created_at": 1739314509, "metadata": {}, } ], "first_id": "eval_67abd54d9b0081909a86353f6fb9317a", "last_id": "eval_67abd54d9b0081909a86353f6fb9317a", "has_more": true } ### EvalLogsDataSourceConfig #### type object #### title LogsDataSourceConfig #### description A LogsDataSourceConfig which specifies the metadata property of your logs query. This is usually metadata like `usecase=chatbot` or `prompt-version=v2`, etc. The schema returned by this data source config is used to defined what variables are available in your evals. `item` and `sample` are both defined when using this data source config. #### properties ##### type ###### type string ###### enum - logs ###### default logs ###### description The type of data source. Always `logs`. ###### x-stainless-const true ##### metadata ###### $ref #/components/schemas/Metadata ##### schema ###### type object ###### description The json schema for the run data source items. Learn how to build JSON schemas [here](https://json-schema.org/). ###### additionalProperties true #### required - type - schema #### x-oaiMeta ##### name The logs data source object for evals ##### group evals ##### example { "type": "logs", "metadata": { "language": "english" }, "schema": { "type": "object", "properties": { "item": { "type": "object" }, "sample": { "type": "object" } }, "required": [ "item", "sample" } } ### EvalResponsesSource #### type object #### title EvalResponsesSource #### description A EvalResponsesSource object describing a run data source configuration. #### properties ##### type ###### type string ###### enum - responses ###### description The type of run data source. Always `responses`. ##### metadata ###### type object ###### nullable true ###### description Metadata filter for the responses. This is a query parameter used to select responses. ##### model ###### type string ###### nullable true ###### description The name of the model to find responses for. This is a query parameter used to select responses. ##### instructions_search ###### type string ###### nullable true ###### description Optional string to search the 'instructions' field. This is a query parameter used to select responses. ##### created_after ###### type integer ###### minimum 0 ###### nullable true ###### description Only include items created after this timestamp (inclusive). This is a query parameter used to select responses. ##### created_before ###### type integer ###### minimum 0 ###### nullable true ###### description Only include items created before this timestamp (inclusive). This is a query parameter used to select responses. ##### reasoning_effort ###### $ref #/components/schemas/ReasoningEffort ###### nullable true ###### description Optional reasoning effort parameter. This is a query parameter used to select responses. ##### temperature ###### type number ###### nullable true ###### description Sampling temperature. This is a query parameter used to select responses. ##### top_p ###### type number ###### nullable true ###### description Nucleus sampling parameter. This is a query parameter used to select responses. ##### users ###### type array ###### items ####### type string ###### nullable true ###### description List of user identifiers. This is a query parameter used to select responses. ##### tools ###### type array ###### items ####### type string ###### nullable true ###### description List of tool names. This is a query parameter used to select responses. #### required - type #### x-oaiMeta ##### name The run data source object used to configure an individual run ##### group eval runs ##### example { "type": "responses", "model": "gpt-4o-mini-2024-07-18", "temperature": 0.7, "top_p": 1.0, "users": ["user1", "user2"], "tools": ["tool1", "tool2"], "instructions_search": "You are a coding assistant" } ### EvalRun #### type object #### title EvalRun #### description A schema representing an evaluation run. #### properties ##### object ###### type string ###### enum - eval.run ###### default eval.run ###### description The type of the object. Always "eval.run". ###### x-stainless-const true ##### id ###### type string ###### description Unique identifier for the evaluation run. ##### eval_id ###### type string ###### description The identifier of the associated evaluation. ##### status ###### type string ###### description The status of the evaluation run. ##### model ###### type string ###### description The model that is evaluated, if applicable. ##### name ###### type string ###### description The name of the evaluation run. ##### created_at ###### type integer ###### description Unix timestamp (in seconds) when the evaluation run was created. ##### report_url ###### type string ###### description The URL to the rendered evaluation run report on the UI dashboard. ##### result_counts ###### type object ###### description Counters summarizing the outcomes of the evaluation run. ###### properties ####### total ######## type integer ######## description Total number of executed output items. ####### errored ######## type integer ######## description Number of output items that resulted in an error. ####### failed ######## type integer ######## description Number of output items that failed to pass the evaluation. ####### passed ######## type integer ######## description Number of output items that passed the evaluation. ###### required - total - errored - failed - passed ##### per_model_usage ###### type array ###### description Usage statistics for each model during the evaluation run. ###### items ####### type object ####### properties ######## model_name ######### type string ######### description The name of the model. ######### x-stainless-naming ########## python ########### property_name run_model_name ######## invocation_count ######### type integer ######### description The number of invocations. ######## prompt_tokens ######### type integer ######### description The number of prompt tokens used. ######## completion_tokens ######### type integer ######### description The number of completion tokens generated. ######## total_tokens ######### type integer ######### description The total number of tokens used. ######## cached_tokens ######### type integer ######### description The number of tokens retrieved from cache. ####### required - model_name - invocation_count - prompt_tokens - completion_tokens - total_tokens - cached_tokens ##### per_testing_criteria_results ###### type array ###### description Results per testing criteria applied during the evaluation run. ###### items ####### type object ####### properties ######## testing_criteria ######### type string ######### description A description of the testing criteria. ######## passed ######### type integer ######### description Number of tests passed for this criteria. ######## failed ######### type integer ######### description Number of tests failed for this criteria. ####### required - testing_criteria - passed - failed ##### data_source ###### type object ###### description Information about the run's data source. ###### anyOf ####### $ref #/components/schemas/CreateEvalJsonlRunDataSource ####### $ref #/components/schemas/CreateEvalCompletionsRunDataSource ####### $ref #/components/schemas/CreateEvalResponsesRunDataSource ###### discriminator ####### propertyName type ##### metadata ###### $ref #/components/schemas/Metadata ##### error ###### $ref #/components/schemas/EvalApiError #### required - object - id - eval_id - status - model - name - created_at - report_url - result_counts - per_model_usage - per_testing_criteria_results - data_source - metadata - error #### x-oaiMeta ##### name The eval run object ##### group evals ##### example { "object": "eval.run", "id": "evalrun_67e57965b480819094274e3a32235e4c", "eval_id": "eval_67e579652b548190aaa83ada4b125f47", "report_url": "https://platform.openai.com/evaluations/eval_67e579652b548190aaa83ada4b125f47?run_id=evalrun_67e57965b480819094274e3a32235e4c", "status": "queued", "model": "gpt-4o-mini", "name": "gpt-4o-mini", "created_at": 1743092069, "result_counts": { "total": 0, "errored": 0, "failed": 0, "passed": 0 }, "per_model_usage": null, "per_testing_criteria_results": null, "data_source": { "type": "completions", "source": { "type": "file_content", "content": [ { "item": { "input": "Tech Company Launches Advanced Artificial Intelligence Platform", "ground_truth": "Technology" } }, { "item": { "input": "Central Bank Increases Interest Rates Amid Inflation Concerns", "ground_truth": "Markets" } }, { "item": { "input": "International Summit Addresses Climate Change Strategies", "ground_truth": "World" } }, { "item": { "input": "Major Retailer Reports Record-Breaking Holiday Sales", "ground_truth": "Business" } }, { "item": { "input": "National Team Qualifies for World Championship Finals", "ground_truth": "Sports" } }, { "item": { "input": "Stock Markets Rally After Positive Economic Data Released", "ground_truth": "Markets" } }, { "item": { "input": "Global Manufacturer Announces Merger with Competitor", "ground_truth": "Business" } }, { "item": { "input": "Breakthrough in Renewable Energy Technology Unveiled", "ground_truth": "Technology" } }, { "item": { "input": "World Leaders Sign Historic Climate Agreement", "ground_truth": "World" } }, { "item": { "input": "Professional Athlete Sets New Record in Championship Event", "ground_truth": "Sports" } }, { "item": { "input": "Financial Institutions Adapt to New Regulatory Requirements", "ground_truth": "Business" } }, { "item": { "input": "Tech Conference Showcases Advances in Artificial Intelligence", "ground_truth": "Technology" } }, { "item": { "input": "Global Markets Respond to Oil Price Fluctuations", "ground_truth": "Markets" } }, { "item": { "input": "International Cooperation Strengthened Through New Treaty", "ground_truth": "World" } }, { "item": { "input": "Sports League Announces Revised Schedule for Upcoming Season", "ground_truth": "Sports" } } ] }, "input_messages": { "type": "template", "template": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "text": "Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\n\n# Steps\n\n1. Analyze the content of the news headline to understand its primary focus.\n2. Extract the subject matter, identifying any key indicators or keywords.\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\n4. Ensure only one category is selected per headline.\n\n# Output Format\n\nRespond with the chosen category as a single word. For instance: \"Technology\", \"Markets\", \"World\", \"Business\", or \"Sports\".\n\n# Examples\n\n**Input**: \"Apple Unveils New iPhone Model, Featuring Advanced AI Features\" \n**Output**: \"Technology\"\n\n**Input**: \"Global Stocks Mixed as Investors Await Central Bank Decisions\" \n**Output**: \"Markets\"\n\n**Input**: \"War in Ukraine: Latest Updates on Negotiation Status\" \n**Output**: \"World\"\n\n**Input**: \"Microsoft in Talks to Acquire Gaming Company for $2 Billion\" \n**Output**: \"Business\"\n\n**Input**: \"Manchester United Secures Win in Premier League Football Match\" \n**Output**: \"Sports\" \n\n# Notes\n\n- If the headline appears to fit into more than one category, choose the most dominant theme.\n- Keywords or phrases such as \"stocks\", \"company acquisition\", \"match\", or technological brands can be good indicators for classification.\n" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "{{item.input}}" } } ] }, "model": "gpt-4o-mini", "sampling_params": { "seed": 42, "temperature": 1.0, "top_p": 1.0, "max_completions_tokens": 2048 } }, "error": null, "metadata": {} } ### EvalRunList #### type object #### title EvalRunList #### description An object representing a list of runs for an evaluation. #### 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 eval run objects. ###### items ####### $ref #/components/schemas/EvalRun ##### first_id ###### type string ###### description The identifier of the first eval run in the data array. ##### last_id ###### type string ###### description The identifier of the last eval run in the data array. ##### has_more ###### type boolean ###### description Indicates whether there are more evals available. #### required - object - data - first_id - last_id - has_more #### x-oaiMeta ##### name The eval run list object ##### group evals ##### example { "object": "list", "data": [ { "object": "eval.run", "id": "evalrun_67b7fbdad46c819092f6fe7a14189620", "eval_id": "eval_67b7fa9a81a88190ab4aa417e397ea21", "report_url": "https://platform.openai.com/evaluations/eval_67b7fa9a81a88190ab4aa417e397ea21?run_id=evalrun_67b7fbdad46c819092f6fe7a14189620", "status": "completed", "model": "o3-mini", "name": "Academic Assistant", "created_at": 1740110812, "result_counts": { "total": 171, "errored": 0, "failed": 80, "passed": 91 }, "per_model_usage": null, "per_testing_criteria_results": [ { "testing_criteria": "String check grader", "passed": 91, "failed": 80 } ], "run_data_source": { "type": "completions", "template_messages": [ { "type": "message", "role": "system", "content": { "type": "input_text", "text": "You are a helpful assistant." } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "Hello, can you help me with my homework?" } } ], "datasource_reference": null, "model": "o3-mini", "max_completion_tokens": null, "seed": null, "temperature": null, "top_p": null }, "error": null, "metadata": {"test": "synthetics"} } ], "first_id": "evalrun_67abd54d60ec8190832b46859da808f7", "last_id": "evalrun_67abd54d60ec8190832b46859da808f7", "has_more": false } ### EvalRunOutputItem #### type object #### title EvalRunOutputItem #### description A schema representing an evaluation run output item. #### properties ##### object ###### type string ###### enum - eval.run.output_item ###### default eval.run.output_item ###### description The type of the object. Always "eval.run.output_item". ###### x-stainless-const true ##### id ###### type string ###### description Unique identifier for the evaluation run output item. ##### run_id ###### type string ###### description The identifier of the evaluation run associated with this output item. ##### eval_id ###### type string ###### description The identifier of the evaluation group. ##### created_at ###### type integer ###### description Unix timestamp (in seconds) when the evaluation run was created. ##### status ###### type string ###### description The status of the evaluation run. ##### datasource_item_id ###### type integer ###### description The identifier for the data source item. ##### datasource_item ###### type object ###### description Details of the input data source item. ###### additionalProperties true ##### results ###### type array ###### description A list of results from the evaluation run. ###### items ####### type object ####### description A result object. ####### additionalProperties true ##### sample ###### type object ###### description A sample containing the input and output of the evaluation run. ###### properties ####### input ######## type array ######## description An array of input messages. ######## items ######### type object ######### description An input message. ######### properties ########## role ########### type string ########### description The role of the message sender (e.g., system, user, developer). ########## content ########### type string ########### description The content of the message. ######### required - role - content ####### output ######## type array ######## description An array of output messages. ######## items ######### type object ######### properties ########## role ########### type string ########### description The role of the message (e.g. "system", "assistant", "user"). ########## content ########### type string ########### description The content of the message. ####### finish_reason ######## type string ######## description The reason why the sample generation was finished. ####### model ######## type string ######## description The model used for generating the sample. ####### usage ######## type object ######## description Token usage details for the sample. ######## properties ######### total_tokens ########## type integer ########## description The total number of tokens used. ######### completion_tokens ########## type integer ########## description The number of completion tokens generated. ######### prompt_tokens ########## type integer ########## description The number of prompt tokens used. ######### cached_tokens ########## type integer ########## description The number of tokens retrieved from cache. ######## required - total_tokens - completion_tokens - prompt_tokens - cached_tokens ####### error ######## $ref #/components/schemas/EvalApiError ####### temperature ######## type number ######## description The sampling temperature used. ####### max_completion_tokens ######## type integer ######## description The maximum number of tokens allowed for completion. ####### top_p ######## type number ######## description The top_p value used for sampling. ####### seed ######## type integer ######## description The seed used for generating the sample. ###### required - input - output - finish_reason - model - usage - error - temperature - max_completion_tokens - top_p - seed #### required - object - id - run_id - eval_id - created_at - status - datasource_item_id - datasource_item - results - sample #### x-oaiMeta ##### name The eval run output item object ##### group evals ##### example { "object": "eval.run.output_item", "id": "outputitem_67abd55eb6548190bb580745d5644a33", "run_id": "evalrun_67abd54d60ec8190832b46859da808f7", "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", "created_at": 1739314509, "status": "pass", "datasource_item_id": 137, "datasource_item": { "teacher": "To grade essays, I only check for style, content, and grammar.", "student": "I am a student who is trying to write the best essay." }, "results": [ { "name": "String Check Grader", "type": "string-check-grader", "score": 1.0, "passed": true, } ], "sample": { "input": [ { "role": "system", "content": "You are an evaluator bot..." }, { "role": "user", "content": "You are assessing..." } ], "output": [ { "role": "assistant", "content": "The rubric is not clear nor concise." } ], "finish_reason": "stop", "model": "gpt-4o-2024-08-06", "usage": { "total_tokens": 521, "completion_tokens": 2, "prompt_tokens": 519, "cached_tokens": 0 }, "error": null, "temperature": 1.0, "max_completion_tokens": 2048, "top_p": 1.0, "seed": 42 } } ### EvalRunOutputItemList #### type object #### title EvalRunOutputItemList #### description An object representing a list of output items for an evaluation run. #### 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 eval run output item objects. ###### items ####### $ref #/components/schemas/EvalRunOutputItem ##### first_id ###### type string ###### description The identifier of the first eval run output item in the data array. ##### last_id ###### type string ###### description The identifier of the last eval run output item in the data array. ##### has_more ###### type boolean ###### description Indicates whether there are more eval run output items available. #### required - object - data - first_id - last_id - has_more #### x-oaiMeta ##### name The eval run output item list object ##### group evals ##### example { "object": "list", "data": [ { "object": "eval.run.output_item", "id": "outputitem_67abd55eb6548190bb580745d5644a33", "run_id": "evalrun_67abd54d60ec8190832b46859da808f7", "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", "created_at": 1739314509, "status": "pass", "datasource_item_id": 137, "datasource_item": { "teacher": "To grade essays, I only check for style, content, and grammar.", "student": "I am a student who is trying to write the best essay." }, "results": [ { "name": "String Check Grader", "type": "string-check-grader", "score": 1.0, "passed": true, } ], "sample": { "input": [ { "role": "system", "content": "You are an evaluator bot..." }, { "role": "user", "content": "You are assessing..." } ], "output": [ { "role": "assistant", "content": "The rubric is not clear nor concise." } ], "finish_reason": "stop", "model": "gpt-4o-2024-08-06", "usage": { "total_tokens": 521, "completion_tokens": 2, "prompt_tokens": 519, "cached_tokens": 0 }, "error": null, "temperature": 1.0, "max_completion_tokens": 2048, "top_p": 1.0, "seed": 42 } }, ], "first_id": "outputitem_67abd55eb6548190bb580745d5644a33", "last_id": "outputitem_67abd55eb6548190bb580745d5644a33", "has_more": false } ### EvalStoredCompletionsDataSourceConfig #### type object #### title StoredCompletionsDataSourceConfig #### description Deprecated in favor of LogsDataSourceConfig. #### properties ##### type ###### type string ###### enum - stored_completions ###### default stored_completions ###### description The type of data source. Always `stored_completions`. ###### x-stainless-const true ##### metadata ###### $ref #/components/schemas/Metadata ##### schema ###### type object ###### description The json schema for the run data source items. Learn how to build JSON schemas [here](https://json-schema.org/). ###### additionalProperties true #### required - type - schema #### deprecated true #### x-oaiMeta ##### name The stored completions data source object for evals ##### group evals ##### example { "type": "stored_completions", "metadata": { "language": "english" }, "schema": { "type": "object", "properties": { "item": { "type": "object" }, "sample": { "type": "object" } }, "required": [ "item", "sample" } } ### EvalStoredCompletionsSource #### type object #### title StoredCompletionsRunDataSource #### description A StoredCompletionsRunDataSource configuration describing a set of filters #### properties ##### type ###### type string ###### enum - stored_completions ###### default stored_completions ###### description The type of source. Always `stored_completions`. ###### x-stainless-const true ##### metadata ###### $ref #/components/schemas/Metadata ##### model ###### type string ###### nullable true ###### description An optional model to filter by (e.g., 'gpt-4o'). ##### created_after ###### type integer ###### nullable true ###### description An optional Unix timestamp to filter items created after this time. ##### created_before ###### type integer ###### nullable true ###### description An optional Unix timestamp to filter items created before this time. ##### limit ###### type integer ###### nullable true ###### description An optional maximum number of items to return. #### required - type #### x-oaiMeta ##### name The stored completions data source object used to configure an individual run ##### group eval runs ##### example { "type": "stored_completions", "model": "gpt-4o", "created_after": 1668124800, "created_before": 1668124900, "limit": 100, "metadata": {} } ### FileExpirationAfter #### type object #### title File expiration policy #### description The expiration policy for a file. By default, files with `purpose=batch` expire after 30 days and all other files are persisted until they are manually deleted. #### properties ##### anchor ###### description Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`. ###### type string ###### enum - created_at ###### x-stainless-const true ##### seconds ###### description The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days). ###### type integer ###### minimum 3600 ###### maximum 2592000 #### required - anchor - seconds ### 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](https://platform.openai.com/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 ### FileSearchToolCall #### type object #### title File search tool call #### description The results of a file search tool call. See the [file search guide](https://platform.openai.com/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. Input messages may contain text or image content only. Audio and file input messages are not currently supported for fine-tuning. #### properties ##### messages ###### type array ###### minItems 1 ###### items ####### anyOf ######## $ref #/components/schemas/ChatCompletionRequestSystemMessage ######## $ref #/components/schemas/ChatCompletionRequestUserMessage ######## $ref #/components/schemas/FineTuneChatCompletionRequestAssistantMessage ######## $ref #/components/schemas/ChatCompletionRequestToolMessage ######## $ref #/components/schemas/ChatCompletionRequestFunctionMessage ##### 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"] } } } ] } ### FineTuneDPOHyperparameters #### type object #### description The hyperparameters used for the DPO 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. ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type number ####### minimum 0 ####### maximum 2 ####### exclusiveMinimum true ##### 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. ###### default auto ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type integer ####### minimum 1 ####### maximum 256 ##### learning_rate_multiplier ###### description Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting. ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type number ####### minimum 0 ####### exclusiveMinimum true ##### n_epochs ###### description The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset. ###### default auto ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type integer ####### minimum 1 ####### maximum 50 ### FineTuneDPOMethod #### type object #### description Configuration for the DPO fine-tuning method. #### properties ##### hyperparameters ###### $ref #/components/schemas/FineTuneDPOHyperparameters ### FineTuneMethod #### type object #### description The method used for fine-tuning. #### properties ##### type ###### type string ###### description The type of method. Is either `supervised`, `dpo`, or `reinforcement`. ###### enum - supervised - dpo - reinforcement ##### supervised ###### $ref #/components/schemas/FineTuneSupervisedMethod ##### dpo ###### $ref #/components/schemas/FineTuneDPOMethod ##### reinforcement ###### $ref #/components/schemas/FineTuneReinforcementMethod #### required - type ### FineTunePreferenceRequestInput #### type object #### description The per-line training example of a fine-tuning input file for chat models using the dpo method. Input messages may contain text or image content only. Audio and file input messages are not currently supported for fine-tuning. #### properties ##### input ###### type object ###### properties ####### messages ######## type array ######## minItems 1 ######## items ######### anyOf ########## $ref #/components/schemas/ChatCompletionRequestSystemMessage ########## $ref #/components/schemas/ChatCompletionRequestUserMessage ########## $ref #/components/schemas/FineTuneChatCompletionRequestAssistantMessage ########## $ref #/components/schemas/ChatCompletionRequestToolMessage ########## $ref #/components/schemas/ChatCompletionRequestFunctionMessage ####### 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_output ###### type array ###### description The preferred completion message for the output. ###### maxItems 1 ###### items ####### anyOf ######## $ref #/components/schemas/ChatCompletionRequestAssistantMessage ##### non_preferred_output ###### type array ###### description The non-preferred completion message for the output. ###### maxItems 1 ###### items ####### anyOf ######## $ref #/components/schemas/ChatCompletionRequestAssistantMessage #### 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_output": [ { "role": "assistant", "content": "The weather in San Francisco is 70 degrees Fahrenheit." } ], "non_preferred_output": [ { "role": "assistant", "content": "The weather in San Francisco is 21 degrees Celsius." } ] } ### FineTuneReinforcementHyperparameters #### type object #### description The hyperparameters used for the reinforcement 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. ###### default auto ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type integer ####### minimum 1 ####### maximum 256 ##### learning_rate_multiplier ###### description Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting. ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type number ####### minimum 0 ####### exclusiveMinimum true ##### n_epochs ###### description The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset. ###### default auto ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type integer ####### minimum 1 ####### maximum 50 ##### reasoning_effort ###### description Level of reasoning effort. ###### type string ###### enum - default - low - medium - high ###### default default ##### compute_multiplier ###### description Multiplier on amount of compute used for exploring search space during training. ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type number ####### minimum 0.00001 ####### maximum 10 ####### exclusiveMinimum true ##### eval_interval ###### description The number of training steps between evaluation runs. ###### default auto ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type integer ####### minimum 1 ##### eval_samples ###### description Number of evaluation samples to generate per training step. ###### default auto ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type integer ####### minimum 1 ### FineTuneReinforcementMethod #### type object #### description Configuration for the reinforcement fine-tuning method. #### properties ##### grader ###### type object ###### description The grader used for the fine-tuning job. ###### anyOf ####### $ref #/components/schemas/GraderStringCheck ####### $ref #/components/schemas/GraderTextSimilarity ####### $ref #/components/schemas/GraderPython ####### $ref #/components/schemas/GraderScoreModel ####### $ref #/components/schemas/GraderMulti ##### hyperparameters ###### $ref #/components/schemas/FineTuneReinforcementHyperparameters #### required - grader ### FineTuneReinforcementRequestInput #### type object #### unevaluatedProperties true #### description Per-line training example for reinforcement fine-tuning. Note that `messages` and `tools` are the only reserved keywords. Any other arbitrary key-value data can be included on training datapoints and will be available to reference during grading under the `{{ item.XXX }}` template variable. Input messages may contain text or image content only. Audio and file input messages are not currently supported for fine-tuning. #### required - messages #### properties ##### messages ###### type array ###### minItems 1 ###### items ####### anyOf ######## $ref #/components/schemas/ChatCompletionRequestDeveloperMessage ######## $ref #/components/schemas/ChatCompletionRequestUserMessage ######## $ref #/components/schemas/FineTuneChatCompletionRequestAssistantMessage ######## $ref #/components/schemas/ChatCompletionRequestToolMessage ##### tools ###### type array ###### description A list of tools the model may generate JSON inputs for. ###### items ####### $ref #/components/schemas/ChatCompletionTool #### x-oaiMeta ##### name Training format for reasoning models using the reinforcement method ##### example { "messages": [ { "role": "user", "content": "Your task is to take a chemical in SMILES format and predict the number of hydrobond bond donors and acceptors according to Lipinkski's rule. CCN(CC)CCC(=O)c1sc(N)nc1C" }, ], # Any other JSON data can be inserted into an example and referenced during RFT grading "reference_answer": { "donor_bond_counts": 5, "acceptor_bond_counts": 7 } } ### FineTuneSupervisedHyperparameters #### 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. ###### default auto ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type integer ####### minimum 1 ####### maximum 256 ##### learning_rate_multiplier ###### description Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting. ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type number ####### minimum 0 ####### exclusiveMinimum true ##### n_epochs ###### description The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset. ###### default auto ###### anyOf ####### type string ####### enum - auto ####### x-stainless-const true ####### type integer ####### minimum 1 ####### maximum 50 ### FineTuneSupervisedMethod #### type object #### description Configuration for the supervised fine-tuning method. #### properties ##### hyperparameters ###### $ref #/components/schemas/FineTuneSupervisedHyperparameters ### FineTuningCheckpointPermission #### type object #### title FineTuningCheckpointPermission #### description The `checkpoint.permission` object represents a permission for a fine-tuned model checkpoint. #### properties ##### id ###### type string ###### description The permission identifier, which can be referenced in the API endpoints. ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) for when the permission was created. ##### project_id ###### type string ###### description The project identifier that the permission is for. ##### object ###### type string ###### description The object type, which is always "checkpoint.permission". ###### enum - checkpoint.permission ###### x-stainless-const true #### required - created_at - id - object - project_id #### x-oaiMeta ##### name The fine-tuned model checkpoint permission object ##### example { "object": "checkpoint.permission", "id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "created_at": 1712211699, "project_id": "proj_abGMw1llN8IrBb6SvvY5A1iH" } ### 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 ######## nullable true ######## description Number of examples in each batch. A larger batch size means that model parameters are updated less frequently, but with lower variance. ######## anyOf ######### type string ######### enum - auto ######### x-stainless-const true ######### title Auto ######### type integer ######### minimum 1 ######### maximum 256 ######### title Manual ####### learning_rate_multiplier ######## description Scaling factor for the learning rate. A smaller learning rate may be useful to avoid overfitting. ######## anyOf ######### type string ######### enum - auto ######### x-stainless-const true ######### title Auto ######### type number ######### minimum 0 ######### exclusiveMinimum true ####### n_epochs ######## description The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset. ######## default auto ######## anyOf ######### type string ######### enum - auto ######### x-stainless-const true ######### title Auto ######### type integer ######### minimum 1 ######### maximum 50 ##### 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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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 ####### anyOf ######## $ref #/components/schemas/FineTuningIntegration ####### discriminator ######## propertyName type ##### 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](https://platform.openai.com/docs/guides/function-calling). #### required - name ### FunctionParameters #### type object #### description The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/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 ### FunctionToolCall #### type object #### title Function tool call #### description A tool call to run a function. See the [function calling guide](https://platform.openai.com/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 - 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 ### FunctionToolCallResource #### allOf ##### $ref #/components/schemas/FunctionToolCall ##### type object ##### properties ###### id ####### type string ####### description The unique ID of the function tool call. ##### required - id ### GraderLabelModel #### type object #### title LabelModelGrader #### description A LabelModelGrader object which uses a model to assign labels to each item in the evaluation. #### properties ##### type ###### description The object type, which is always `label_model`. ###### type string ###### enum - label_model ###### x-stainless-const true ##### name ###### type string ###### description The name of the grader. ##### model ###### type string ###### description The model to use for the evaluation. Must support structured outputs. ##### input ###### type array ###### items ####### $ref #/components/schemas/EvalItem ##### labels ###### type array ###### items ####### type string ###### description The labels to assign to each item in the evaluation. ##### passing_labels ###### type array ###### items ####### type string ###### description The labels that indicate a passing result. Must be a subset of labels. #### required - type - model - input - passing_labels - labels - name #### x-oaiMeta ##### name Label Model Grader ##### group graders ##### example { "name": "First label grader", "type": "label_model", "model": "gpt-4o-2024-08-06", "input": [ { "type": "message", "role": "system", "content": { "type": "input_text", "text": "Classify the sentiment of the following statement as one of positive, neutral, or negative" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "Statement: {{item.response}}" } } ], "passing_labels": [ "positive" ], "labels": [ "positive", "neutral", "negative" ] } ### GraderMulti #### type object #### title MultiGrader #### description A MultiGrader object combines the output of multiple graders to produce a single score. #### properties ##### type ###### type string ###### enum - multi ###### default multi ###### description The object type, which is always `multi`. ###### x-stainless-const true ##### name ###### type string ###### description The name of the grader. ##### graders ###### anyOf ####### $ref #/components/schemas/GraderStringCheck ####### $ref #/components/schemas/GraderTextSimilarity ####### $ref #/components/schemas/GraderPython ####### $ref #/components/schemas/GraderScoreModel ####### $ref #/components/schemas/GraderLabelModel ##### calculate_output ###### type string ###### description A formula to calculate the output based on grader results. #### required - name - type - graders - calculate_output #### x-oaiMeta ##### name Multi Grader ##### group graders ##### example { "type": "multi", "name": "example multi grader", "graders": [ { "type": "text_similarity", "name": "example text similarity grader", "input": "The graded text", "reference": "The reference text", "evaluation_metric": "fuzzy_match" }, { "type": "string_check", "name": "Example string check grader", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "operation": "eq" } ], "calculate_output": "0.5 * text_similarity_score + 0.5 * string_check_score)" } ### GraderPython #### type object #### title PythonGrader #### description A PythonGrader object that runs a python script on the input. #### properties ##### type ###### type string ###### enum - python ###### description The object type, which is always `python`. ###### x-stainless-const true ##### name ###### type string ###### description The name of the grader. ##### source ###### type string ###### description The source code of the python script. ##### image_tag ###### type string ###### description The image tag to use for the python script. #### required - type - name - source #### x-oaiMeta ##### name Python Grader ##### group graders ##### example { "type": "python", "name": "Example python grader", "image_tag": "2025-05-08", "source": """ def grade(sample: dict, item: dict) -> float: \""" Returns 1.0 if `output_text` equals `label`, otherwise 0.0. \""" output = sample.get("output_text") label = item.get("label") return 1.0 if output == label else 0.0 """, } ### GraderScoreModel #### type object #### title ScoreModelGrader #### description A ScoreModelGrader object that uses a model to assign a score to the input. #### properties ##### type ###### type string ###### enum - score_model ###### description The object type, which is always `score_model`. ###### x-stainless-const true ##### name ###### type string ###### description The name of the grader. ##### model ###### type string ###### description The model to use for the evaluation. ##### sampling_params ###### type object ###### description The sampling parameters for the model. ##### input ###### type array ###### items ####### $ref #/components/schemas/EvalItem ###### description The input text. This may include template strings. ##### range ###### type array ###### items ####### type number ####### min_items 2 ####### max_items 2 ###### description The range of the score. Defaults to `[0, 1]`. #### required - type - name - input - model #### x-oaiMeta ##### name Score Model Grader ##### group graders ##### example { "type": "score_model", "name": "Example score model grader", "input": [ { "role": "user", "content": ( "Score how close the reference answer is to the model answer. Score 1.0 if they are the same and 0.0 if they are different." " Return just a floating point score\n\n" " Reference answer: {{item.label}}\n\n" " Model answer: {{sample.output_text}}" ), } ], "model": "gpt-4o-2024-08-06", "sampling_params": { "temperature": 1, "top_p": 1, "seed": 42, }, } ### GraderStringCheck #### type object #### title StringCheckGrader #### description A StringCheckGrader object that performs a string comparison between input and reference using a specified operation. #### properties ##### type ###### type string ###### enum - string_check ###### description The object type, which is always `string_check`. ###### x-stainless-const true ##### name ###### type string ###### description The name of the grader. ##### input ###### type string ###### description The input text. This may include template strings. ##### reference ###### type string ###### description The reference text. This may include template strings. ##### operation ###### type string ###### enum - eq - ne - like - ilike ###### description The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`. #### required - type - name - input - reference - operation #### x-oaiMeta ##### name String Check Grader ##### group graders ##### example { "type": "string_check", "name": "Example string check grader", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "operation": "eq" } ### GraderTextSimilarity #### type object #### title TextSimilarityGrader #### description A TextSimilarityGrader object which grades text based on similarity metrics. #### properties ##### type ###### type string ###### enum - text_similarity ###### default text_similarity ###### description The type of grader. ###### x-stainless-const true ##### name ###### type string ###### description The name of the grader. ##### input ###### type string ###### description The text being graded. ##### reference ###### type string ###### description The text being graded against. ##### evaluation_metric ###### type string ###### enum - cosine - fuzzy_match - bleu - gleu - meteor - rouge_1 - rouge_2 - rouge_3 - rouge_4 - rouge_5 - rouge_l ###### description The evaluation metric to use. One of `cosine`, `fuzzy_match`, `bleu`, `gleu`, `meteor`, `rouge_1`, `rouge_2`, `rouge_3`, `rouge_4`, `rouge_5`, or `rouge_l`. #### required - type - name - input - reference - evaluation_metric #### x-oaiMeta ##### name Text Similarity Grader ##### group graders ##### example { "type": "text_similarity", "name": "Example text similarity grader", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "evaluation_metric": "fuzzy_match" } ### Image #### type object #### description Represents the content or the URL of an image generated by the OpenAI API. #### properties ##### b64_json ###### type string ###### description The base64-encoded JSON of the generated image. Default value for `gpt-image-1`, and only present if `response_format` is set to `b64_json` for `dall-e-2` and `dall-e-3`. ##### url ###### type string ###### description When using `dall-e-2` or `dall-e-3`, the URL of the generated image if `response_format` is set to `url` (default value). Unsupported for `gpt-image-1`. ##### revised_prompt ###### type string ###### description For `dall-e-3` only, the revised prompt that was used to generate the image. ### ImageEditCompletedEvent #### type object #### description Emitted when image editing has completed and the final image is available. #### properties ##### type ###### type string ###### description The type of the event. Always `image_edit.completed`. ###### enum - image_edit.completed ###### x-stainless-const true ##### b64_json ###### type string ###### description Base64-encoded final edited image data, suitable for rendering as an image. ##### created_at ###### type integer ###### description The Unix timestamp when the event was created. ##### size ###### type string ###### description The size of the edited image. ###### enum - 1024x1024 - 1024x1536 - 1536x1024 - auto ##### quality ###### type string ###### description The quality setting for the edited image. ###### enum - low - medium - high - auto ##### background ###### type string ###### description The background setting for the edited image. ###### enum - transparent - opaque - auto ##### output_format ###### type string ###### description The output format for the edited image. ###### enum - png - webp - jpeg ##### usage ###### $ref #/components/schemas/ImagesUsage #### required - type - b64_json - created_at - size - quality - background - output_format - usage #### x-oaiMeta ##### name image_edit.completed ##### group images ##### example { "type": "image_edit.completed", "b64_json": "...", "created_at": 1620000000, "size": "1024x1024", "quality": "high", "background": "transparent", "output_format": "png", "usage": { "total_tokens": 100, "input_tokens": 50, "output_tokens": 50, "input_tokens_details": { "text_tokens": 10, "image_tokens": 40 } } } ### ImageEditPartialImageEvent #### type object #### description Emitted when a partial image is available during image editing streaming. #### properties ##### type ###### type string ###### description The type of the event. Always `image_edit.partial_image`. ###### enum - image_edit.partial_image ###### x-stainless-const true ##### b64_json ###### type string ###### description Base64-encoded partial image data, suitable for rendering as an image. ##### created_at ###### type integer ###### description The Unix timestamp when the event was created. ##### size ###### type string ###### description The size of the requested edited image. ###### enum - 1024x1024 - 1024x1536 - 1536x1024 - auto ##### quality ###### type string ###### description The quality setting for the requested edited image. ###### enum - low - medium - high - auto ##### background ###### type string ###### description The background setting for the requested edited image. ###### enum - transparent - opaque - auto ##### output_format ###### type string ###### description The output format for the requested edited image. ###### enum - png - webp - jpeg ##### partial_image_index ###### type integer ###### description 0-based index for the partial image (streaming). #### required - type - b64_json - created_at - size - quality - background - output_format - partial_image_index #### x-oaiMeta ##### name image_edit.partial_image ##### group images ##### example { "type": "image_edit.partial_image", "b64_json": "...", "created_at": 1620000000, "size": "1024x1024", "quality": "high", "background": "transparent", "output_format": "png", "partial_image_index": 0 } ### ImageEditStreamEvent #### anyOf ##### $ref #/components/schemas/ImageEditPartialImageEvent ##### $ref #/components/schemas/ImageEditCompletedEvent #### discriminator ##### propertyName type ### ImageGenCompletedEvent #### type object #### description Emitted when image generation has completed and the final image is available. #### properties ##### type ###### type string ###### description The type of the event. Always `image_generation.completed`. ###### enum - image_generation.completed ###### x-stainless-const true ##### b64_json ###### type string ###### description Base64-encoded image data, suitable for rendering as an image. ##### created_at ###### type integer ###### description The Unix timestamp when the event was created. ##### size ###### type string ###### description The size of the generated image. ###### enum - 1024x1024 - 1024x1536 - 1536x1024 - auto ##### quality ###### type string ###### description The quality setting for the generated image. ###### enum - low - medium - high - auto ##### background ###### type string ###### description The background setting for the generated image. ###### enum - transparent - opaque - auto ##### output_format ###### type string ###### description The output format for the generated image. ###### enum - png - webp - jpeg ##### usage ###### $ref #/components/schemas/ImagesUsage #### required - type - b64_json - created_at - size - quality - background - output_format - usage #### x-oaiMeta ##### name image_generation.completed ##### group images ##### example { "type": "image_generation.completed", "b64_json": "...", "created_at": 1620000000, "size": "1024x1024", "quality": "high", "background": "transparent", "output_format": "png", "usage": { "total_tokens": 100, "input_tokens": 50, "output_tokens": 50, "input_tokens_details": { "text_tokens": 10, "image_tokens": 40 } } } ### ImageGenPartialImageEvent #### type object #### description Emitted when a partial image is available during image generation streaming. #### properties ##### type ###### type string ###### description The type of the event. Always `image_generation.partial_image`. ###### enum - image_generation.partial_image ###### x-stainless-const true ##### b64_json ###### type string ###### description Base64-encoded partial image data, suitable for rendering as an image. ##### created_at ###### type integer ###### description The Unix timestamp when the event was created. ##### size ###### type string ###### description The size of the requested image. ###### enum - 1024x1024 - 1024x1536 - 1536x1024 - auto ##### quality ###### type string ###### description The quality setting for the requested image. ###### enum - low - medium - high - auto ##### background ###### type string ###### description The background setting for the requested image. ###### enum - transparent - opaque - auto ##### output_format ###### type string ###### description The output format for the requested image. ###### enum - png - webp - jpeg ##### partial_image_index ###### type integer ###### description 0-based index for the partial image (streaming). #### required - type - b64_json - created_at - size - quality - background - output_format - partial_image_index #### x-oaiMeta ##### name image_generation.partial_image ##### group images ##### example { "type": "image_generation.partial_image", "b64_json": "...", "created_at": 1620000000, "size": "1024x1024", "quality": "high", "background": "transparent", "output_format": "png", "partial_image_index": 0 } ### ImageGenStreamEvent #### anyOf ##### $ref #/components/schemas/ImageGenPartialImageEvent ##### $ref #/components/schemas/ImageGenCompletedEvent #### discriminator ##### propertyName type ### ImageGenTool #### type object #### title Image generation tool #### description A tool that generates images using a model like `gpt-image-1`. #### properties ##### type ###### type string ###### enum - image_generation ###### description The type of the image generation tool. Always `image_generation`. ###### x-stainless-const true ##### model ###### type string ###### enum - gpt-image-1 ###### description The image generation model to use. Default: `gpt-image-1`. ###### default gpt-image-1 ##### quality ###### type string ###### enum - low - medium - high - auto ###### description The quality of the generated image. One of `low`, `medium`, `high`, or `auto`. Default: `auto`. ###### default auto ##### size ###### type string ###### enum - 1024x1024 - 1024x1536 - 1536x1024 - auto ###### description The size of the generated image. One of `1024x1024`, `1024x1536`, `1536x1024`, or `auto`. Default: `auto`. ###### default auto ##### output_format ###### type string ###### enum - png - webp - jpeg ###### description The output format of the generated image. One of `png`, `webp`, or `jpeg`. Default: `png`. ###### default png ##### output_compression ###### type integer ###### minimum 0 ###### maximum 100 ###### description Compression level for the output image. Default: 100. ###### default 100 ##### moderation ###### type string ###### enum - auto - low ###### description Moderation level for the generated image. Default: `auto`. ###### default auto ##### background ###### type string ###### enum - transparent - opaque - auto ###### description Background type for the generated image. One of `transparent`, `opaque`, or `auto`. Default: `auto`. ###### default auto ##### input_fidelity ###### $ref #/components/schemas/ImageInputFidelity ##### input_image_mask ###### type object ###### description Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). ###### properties ####### image_url ######## type string ######## description Base64-encoded mask image. ####### file_id ######## type string ######## description File ID for the mask image. ###### required ###### additionalProperties false ##### partial_images ###### type integer ###### minimum 0 ###### maximum 3 ###### description Number of partial images to generate in streaming mode, from 0 (default value) to 3. ###### default 0 #### required - type ### ImageGenToolCall #### type object #### title Image generation call #### description An image generation request made by the model. #### properties ##### type ###### type string ###### enum - image_generation_call ###### description The type of the image generation call. Always `image_generation_call`. ###### x-stainless-const true ##### id ###### type string ###### description The unique ID of the image generation call. ##### status ###### type string ###### enum - in_progress - completed - generating - failed ###### description The status of the image generation call. ##### result ###### type string ###### description The generated image encoded in base64. ###### nullable true #### required - type - id - status - result ### ImageInputFidelity #### type string #### enum - high - low #### default low #### nullable true #### description Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1`. Supports `high` and `low`. Defaults to `low`. ### ImagesResponse #### type object #### title Image generation response #### description The response from the image generation endpoint. #### properties ##### created ###### type integer ###### description The Unix timestamp (in seconds) of when the image was created. ##### data ###### type array ###### description The list of generated images. ###### items ####### $ref #/components/schemas/Image ##### background ###### type string ###### description The background parameter used for the image generation. Either `transparent` or `opaque`. ###### enum - transparent - opaque ##### output_format ###### type string ###### description The output format of the image generation. Either `png`, `webp`, or `jpeg`. ###### enum - png - webp - jpeg ##### size ###### type string ###### description The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`. ###### enum - 1024x1024 - 1024x1536 - 1536x1024 ##### quality ###### type string ###### description The quality of the image generated. Either `low`, `medium`, or `high`. ###### enum - low - medium - high ##### usage ###### $ref #/components/schemas/ImageGenUsage #### required - created #### x-oaiMeta ##### name The image generation response ##### group images ##### example { "created": 1713833628, "data": [ { "b64_json": "..." } ], "background": "transparent", "output_format": "png", "size": "1024x1024", "quality": "high", "usage": { "total_tokens": 100, "input_tokens": 50, "output_tokens": 50, "input_tokens_details": { "text_tokens": 10, "image_tokens": 40 } } } ### ImagesUsage #### type object #### description For `gpt-image-1` only, the token usage information for the image generation. #### required - total_tokens - input_tokens - output_tokens - input_tokens_details #### properties ##### total_tokens ###### type integer ###### description The total number of tokens (images and text) used for the image generation. ##### input_tokens ###### type integer ###### description The number of tokens (images and text) in the input prompt. ##### output_tokens ###### type integer ###### description The number of image tokens in the output image. ##### input_tokens_details ###### type object ###### description The input tokens detailed information for the image generation. ###### required - text_tokens - image_tokens ###### properties ####### text_tokens ######## type integer ######## description The number of text tokens in the input prompt. ####### image_tokens ######## type integer ######## description The number of image tokens in the input prompt. ### Includable #### type string #### description Specify additional output data to include in the model response. Currently supported values are: - `web_search_call.action.sources`: Include the sources of the web search tool call. - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - `computer_call_output.output.image_url`: Include image urls from the computer call output. - `file_search_call.results`: Include the search results of the file search tool call. - `message.input_image.image_url`: Include image urls from the input message. - `message.output_text.logprobs`: Include logprobs with assistant messages. - `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program). #### enum - code_interpreter_call.outputs - computer_call_output.output.image_url - file_search_call.results - message.input_image.image_url - message.output_text.logprobs - reasoning.encrypted_content ### 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 #### anyOf ##### $ref #/components/schemas/InputTextContent ##### $ref #/components/schemas/InputImageContent ##### $ref #/components/schemas/InputFileContent #### discriminator ##### propertyName type ### InputItem #### discriminator ##### propertyName type #### anyOf ##### $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/ItemReferenceParam ### 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. #### items ##### $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 ### 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 invite 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" } ] } ### 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 #### 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 ### Item #### type object #### description Content item used to generate a response. #### discriminator ##### propertyName type #### anyOf ##### $ref #/components/schemas/InputMessage ##### $ref #/components/schemas/OutputMessage ##### $ref #/components/schemas/FileSearchToolCall ##### $ref #/components/schemas/ComputerToolCall ##### $ref #/components/schemas/ComputerCallOutputItemParam ##### $ref #/components/schemas/WebSearchToolCall ##### $ref #/components/schemas/FunctionToolCall ##### $ref #/components/schemas/FunctionCallOutputItemParam ##### $ref #/components/schemas/ReasoningItem ##### $ref #/components/schemas/ImageGenToolCall ##### $ref #/components/schemas/CodeInterpreterToolCall ##### $ref #/components/schemas/LocalShellToolCall ##### $ref #/components/schemas/LocalShellToolCallOutput ##### $ref #/components/schemas/MCPListTools ##### $ref #/components/schemas/MCPApprovalRequest ##### $ref #/components/schemas/MCPApprovalResponse ##### $ref #/components/schemas/MCPToolCall ##### $ref #/components/schemas/CustomToolCallOutput ##### $ref #/components/schemas/CustomToolCall ### ItemResource #### description Content item used to generate a response. #### discriminator ##### propertyName type #### anyOf ##### $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/FunctionToolCallResource ##### $ref #/components/schemas/FunctionToolCallOutputResource ##### $ref #/components/schemas/ImageGenToolCall ##### $ref #/components/schemas/CodeInterpreterToolCall ##### $ref #/components/schemas/LocalShellToolCall ##### $ref #/components/schemas/LocalShellToolCallOutput ##### $ref #/components/schemas/MCPListTools ##### $ref #/components/schemas/MCPApprovalRequest ##### $ref #/components/schemas/MCPApprovalResponseResource ##### $ref #/components/schemas/MCPToolCall ### 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 ###### items ####### type string ####### description One of the keys the model is requesting to be pressed. ###### description The combination of keys the model is requesting to be pressed. This is an 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 ###### 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 #### type object #### properties ##### object ###### type string ###### enum - list ###### x-stainless-const true ##### data ###### type array ###### items ####### $ref #/components/schemas/AuditLog ##### first_id ###### type string ###### example audit_log-defb456h8dks ##### last_id ###### type string ###### example audit_log-hnbkd8s93s ##### has_more ###### type boolean #### required - object - data - first_id - last_id - has_more ### ListBatchesResponse #### 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 ###### type string ###### enum - list ###### x-stainless-const true #### required - object - data - has_more ### ListCertificatesResponse #### type object #### properties ##### data ###### type array ###### items ####### $ref #/components/schemas/Certificate ##### first_id ###### type string ###### example cert_abc ##### last_id ###### type string ###### example cert_abc ##### has_more ###### type boolean ##### object ###### type string ###### enum - list ###### x-stainless-const true #### required - object - data - has_more ### ListFilesResponse #### type object #### properties ##### object ###### type string ###### example list ##### data ###### type array ###### items ####### $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 ### ListFineTuningCheckpointPermissionResponse #### type object #### properties ##### data ###### type array ###### items ####### $ref #/components/schemas/FineTuningCheckpointPermission ##### object ###### type string ###### enum - list ###### x-stainless-const true ##### first_id ###### type string ###### nullable true ##### last_id ###### type string ###### nullable true ##### has_more ###### type boolean #### required - object - data - 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 ##### last_id ###### type string ###### nullable true ##### has_more ###### type boolean #### required - object - data - has_more ### ListFineTuningJobEventsResponse #### 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 ##### 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 ###### enum - list ###### x-stainless-const true ##### data ###### type array ###### items ####### $ref #/components/schemas/Model #### required - object - data ### ListPaginatedFineTuningJobsResponse #### type object #### properties ##### data ###### type array ###### items ####### $ref #/components/schemas/FineTuningJob ##### has_more ###### type boolean ##### object ###### type string ###### enum - list ###### x-stainless-const true #### required - object - data - has_more ### ListRunStepsResponse #### properties ##### object ###### type string ###### example list ##### data ###### type array ###### items ####### $ref #/components/schemas/RunStepObject ##### first_id ###### type string ###### 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 ###### items ####### $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 ### ListVectorStoreFilesResponse #### properties ##### object ###### type string ###### example list ##### data ###### type array ###### items ####### $ref #/components/schemas/VectorStoreFileObject ##### 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 ### ListVectorStoresResponse #### properties ##### 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 - object - data - first_id - last_id - has_more ### LocalShellExecAction #### type object #### title Local shell exec action #### description Execute a shell command on the server. #### properties ##### type ###### type string ###### enum - exec ###### description The type of the local shell action. Always `exec`. ###### x-stainless-const true ##### command ###### type array ###### items ####### type string ###### description The command to run. ##### timeout_ms ###### type integer ###### description Optional timeout in milliseconds for the command. ###### nullable true ##### working_directory ###### type string ###### description Optional working directory to run the command in. ###### nullable true ##### env ###### type object ###### additionalProperties ####### type string ###### description Environment variables to set for the command. ##### user ###### type string ###### description Optional user to run the command as. ###### nullable true #### required - type - command - env ### LocalShellTool #### type object #### title Local shell tool #### description A tool that allows the model to execute shell commands in a local environment. #### properties ##### type ###### type string ###### enum - local_shell ###### description The type of the local shell tool. Always `local_shell`. ###### x-stainless-const true #### required - type ### LocalShellToolCall #### type object #### title Local shell call #### description A tool call to run a command on the local shell. #### properties ##### type ###### type string ###### enum - local_shell_call ###### description The type of the local shell call. Always `local_shell_call`. ###### x-stainless-const true ##### id ###### type string ###### description The unique ID of the local shell call. ##### call_id ###### type string ###### description The unique ID of the local shell tool call generated by the model. ##### action ###### $ref #/components/schemas/LocalShellExecAction ##### status ###### type string ###### enum - in_progress - completed - incomplete ###### description The status of the local shell call. #### required - type - id - call_id - action - status ### LocalShellToolCallOutput #### type object #### title Local shell call output #### description The output of a local shell tool call. #### properties ##### type ###### type string ###### enum - local_shell_call_output ###### description The type of the local shell tool call output. Always `local_shell_call_output`. ###### x-stainless-const true ##### id ###### type string ###### description The unique ID of the local shell tool call generated by the model. ##### output ###### type string ###### description A JSON string of the output of the local shell tool call. ##### status ###### type string ###### enum - in_progress - completed - incomplete ###### description The status of the item. One of `in_progress`, `completed`, or `incomplete`. ###### nullable true #### required - id - type - call_id - output ### LogProbProperties #### type object #### description A log probability object. #### properties ##### token ###### type string ###### description The token that was used to generate the log probability. ##### logprob ###### type number ###### description The log probability of the token. ##### bytes ###### type array ###### items ####### type integer ###### description The bytes that were used to generate the log probability. #### required - token - logprob - bytes ### MCPApprovalRequest #### type object #### title MCP approval request #### description A request for human approval of a tool invocation. #### properties ##### type ###### type string ###### enum - mcp_approval_request ###### description The type of the item. Always `mcp_approval_request`. ###### x-stainless-const true ##### id ###### type string ###### description The unique ID of the approval request. ##### server_label ###### type string ###### description The label of the MCP server making the request. ##### name ###### type string ###### description The name of the tool to run. ##### arguments ###### type string ###### description A JSON string of arguments for the tool. #### required - type - id - server_label - name - arguments ### MCPApprovalResponse #### type object #### title MCP approval response #### description A response to an MCP approval request. #### properties ##### type ###### type string ###### enum - mcp_approval_response ###### description The type of the item. Always `mcp_approval_response`. ###### x-stainless-const true ##### id ###### type string ###### description The unique ID of the approval response ###### nullable true ##### approval_request_id ###### type string ###### description The ID of the approval request being answered. ##### approve ###### type boolean ###### description Whether the request was approved. ##### reason ###### type string ###### description Optional reason for the decision. ###### nullable true #### required - type - request_id - approve - approval_request_id ### MCPApprovalResponseResource #### type object #### title MCP approval response #### description A response to an MCP approval request. #### properties ##### type ###### type string ###### enum - mcp_approval_response ###### description The type of the item. Always `mcp_approval_response`. ###### x-stainless-const true ##### id ###### type string ###### description The unique ID of the approval response ##### approval_request_id ###### type string ###### description The ID of the approval request being answered. ##### approve ###### type boolean ###### description Whether the request was approved. ##### reason ###### type string ###### description Optional reason for the decision. ###### nullable true #### required - type - id - request_id - approve - approval_request_id ### MCPListTools #### type object #### title MCP list tools #### description A list of tools available on an MCP server. #### properties ##### type ###### type string ###### enum - mcp_list_tools ###### description The type of the item. Always `mcp_list_tools`. ###### x-stainless-const true ##### id ###### type string ###### description The unique ID of the list. ##### server_label ###### type string ###### description The label of the MCP server. ##### tools ###### type array ###### items ####### $ref #/components/schemas/MCPListToolsTool ###### description The tools available on the server. ##### error ###### type string ###### description Error message if the server could not list tools. ###### nullable true #### required - type - id - server_label - tools ### MCPListToolsTool #### type object #### title MCP list tools tool #### description A tool available on an MCP server. #### properties ##### name ###### type string ###### description The name of the tool. ##### description ###### type string ###### description The description of the tool. ###### nullable true ##### input_schema ###### type object ###### description The JSON schema describing the tool's input. ##### annotations ###### type object ###### description Additional annotations about the tool. ###### nullable true #### required - name - input_schema ### MCPTool #### type object #### title MCP tool #### description Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp). #### properties ##### type ###### type string ###### enum - mcp ###### description The type of the MCP tool. Always `mcp`. ###### x-stainless-const true ##### server_label ###### type string ###### description A label for this MCP server, used to identify it in tool calls. ##### server_url ###### type string ###### description The URL for the MCP server. One of `server_url` or `connector_id` must be provided. ##### connector_id ###### type string ###### enum - connector_dropbox - connector_gmail - connector_googlecalendar - connector_googledrive - connector_microsoftteams - connector_outlookcalendar - connector_outlookemail - connector_sharepoint ###### description Identifier for service connectors, like those available in ChatGPT. One of `server_url` or `connector_id` must be provided. Learn more about service connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: - Dropbox: `connector_dropbox` - Gmail: `connector_gmail` - Google Calendar: `connector_googlecalendar` - Google Drive: `connector_googledrive` - Microsoft Teams: `connector_microsoftteams` - Outlook Calendar: `connector_outlookcalendar` - Outlook Email: `connector_outlookemail` - SharePoint: `connector_sharepoint` ##### authorization ###### type string ###### description An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here. ##### server_description ###### type string ###### description Optional description of the MCP server, used to provide more context. ##### headers ###### type object ###### additionalProperties ####### type string ###### nullable true ###### description Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. ##### allowed_tools ###### description List of allowed tool names or a filter object. ###### nullable true ###### anyOf ####### type array ####### title MCP allowed tools ####### description A string array of allowed tool names ####### items ######## type string ####### $ref #/components/schemas/MCPToolFilter ##### require_approval ###### description Specify which of the MCP server's tools require approval. ###### nullable true ###### anyOf ####### type object ####### title MCP tool approval filter ####### description Specify which of the MCP server's tools require approval. Can be `always`, `never`, or a filter object associated with tools that require approval. ####### properties ######## always ######### $ref #/components/schemas/MCPToolFilter ######## never ######### $ref #/components/schemas/MCPToolFilter ####### additionalProperties false ####### type string ####### title MCP tool approval setting ####### description Specify a single approval policy for all tools. One of `always` or `never`. When set to `always`, all tools will require approval. When set to `never`, all tools will not require approval. ####### enum - always - never #### required - type - server_label ### MCPToolCall #### type object #### title MCP tool call #### description An invocation of a tool on an MCP server. #### properties ##### type ###### type string ###### enum - mcp_call ###### description The type of the item. Always `mcp_call`. ###### x-stainless-const true ##### id ###### type string ###### description The unique ID of the tool call. ##### server_label ###### type string ###### description The label of the MCP server running the tool. ##### name ###### type string ###### description The name of the tool that was run. ##### arguments ###### type string ###### description A JSON string of the arguments passed to the tool. ##### output ###### type string ###### description The output from the tool call. ###### nullable true ##### error ###### type string ###### description The error from the tool call, if any. ###### nullable true #### required - type - id - server_label - name - arguments ### MCPToolFilter #### type object #### title MCP tool filter #### description A filter object to specify which tools are allowed. #### properties ##### tool_names ###### type array ###### title MCP allowed tools ###### items ####### type string ###### description List of allowed tool names. ##### read_only ###### type boolean ###### description Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. #### required #### additionalProperties false ### MessageContentImageFileObject #### title Image file #### type object #### description References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. #### properties ##### type ###### description Always `image_file`. ###### type string ###### enum - image_file ###### x-stainless-const true ##### image_file ###### type object ###### properties ####### file_id ######## description The [File](https://platform.openai.com/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 - type - image_file ### MessageContentImageUrlObject #### title Image URL #### type object #### description References an image URL in the content of a message. #### 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 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 - type - image_url ### MessageContentRefusalObject #### title Refusal #### type object #### description The refusal content generated by the assistant. #### properties ##### type ###### description Always `refusal`. ###### type string ###### enum - refusal ###### x-stainless-const true ##### refusal ###### type string ###### nullable false #### required - type - refusal ### MessageContentTextAnnotationsFileCitationObject #### 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 ##### type ###### description Always `file_citation`. ###### type string ###### 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 ###### 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 #### required - 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 ##### type ###### description Always `file_path`. ###### 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 #### 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 ##### type ###### description Always `text`. ###### type string ###### enum - text ###### x-stainless-const true ##### text ###### type object ###### properties ####### value ######## description The data that makes up the text. ######## type string ####### annotations ######## type array ######## items ######### $ref #/components/schemas/TextAnnotation ###### required - value - annotations #### required - type - text ### MessageDeltaContentImageFileObject #### title Image file #### type object #### description References an image [File](https://platform.openai.com/docs/api-reference/files) in the content of a message. #### properties ##### index ###### type integer ###### description The index of the content part in the message. ##### type ###### description Always `image_file`. ###### type string ###### enum - image_file ###### x-stainless-const true ##### image_file ###### type object ###### properties ####### file_id ######## description The [File](https://platform.openai.com/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 - index - type ### MessageDeltaContentImageUrlObject #### title Image URL #### type object #### description References an image URL in the content of a message. #### properties ##### 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 - index - type ### MessageDeltaContentRefusalObject #### title Refusal #### type object #### description The refusal content that is part of a message. #### properties ##### index ###### type integer ###### description The index of the refusal part in the message. ##### type ###### description Always `refusal`. ###### type string ###### enum - refusal ###### x-stainless-const true ##### refusal ###### type string #### required - 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 ##### index ###### type integer ###### description The index of the annotation in the text content part. ##### type ###### description Always `file_citation`. ###### type string ###### 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 ###### 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 #### type object #### description A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. #### properties ##### index ###### type integer ###### description The index of the annotation in the text content part. ##### type ###### description Always `file_path`. ###### 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 ##### start_index ###### type integer ###### minimum 0 ##### end_index ###### type integer ###### minimum 0 #### required - index - type ### MessageDeltaContentTextObject #### title Text #### type object #### description The text content that is part of a message. #### properties ##### index ###### type integer ###### description The index of the content part in the message. ##### type ###### description Always `text`. ###### type string ###### enum - text ###### x-stainless-const true ##### text ###### type object ###### properties ####### value ######## description The data that makes up the text. ######## type string ####### annotations ######## type array ######## items ######### $ref #/components/schemas/TextAnnotationDelta #### required - index - type ### MessageDeltaObject #### type object #### title Message delta object #### description Represents a message delta i.e. any changed fields on a message during streaming. #### properties ##### 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 ###### enum - 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 ######### $ref #/components/schemas/MessageContentDelta #### required - id - object - delta #### x-oaiMeta ##### name The message delta object ##### beta true ##### example { "id": "msg_123", "object": "thread.message.delta", "delta": { "content": [ { "index": 0, "type": "text", "text": { "value": "Hello", "annotations": [] } } ] } } ### MessageObject #### type object #### title The message object #### description Represents a message within a [thread](https://platform.openai.com/docs/api-reference/threads). #### properties ##### id ###### description The identifier, which can be referenced in API endpoints. ###### type string ##### object ###### description The object type, which is always `thread.message`. ###### type string ###### enum - thread.message ###### 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](https://platform.openai.com/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 ####### $ref #/components/schemas/MessageContent ##### assistant_id ###### description If applicable, the ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) that authored this message. ###### type string ###### nullable true ##### run_id ###### description The ID of the [run](https://platform.openai.com/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 ########## anyOf ########### $ref #/components/schemas/AssistantToolsCode ########### $ref #/components/schemas/AssistantToolsFileSearchTypeOnly ###### 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 The message object ##### beta true ##### 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": [] } } ], "assistant_id": "asst_abc123", "run_id": "run_abc123", "attachments": [], "metadata": {} } ### MessageRequestContentTextObject #### title Text #### type object #### description The text content that is part of a message. #### properties ##### type ###### description Always `text`. ###### type string ###### enum - text ###### x-stainless-const true ##### text ###### type string ###### description Text content to be sent to the model #### required - type - text ### MessageStreamEvent #### anyOf ##### 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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/docs/api-reference/messages/object) are being streamed. ##### x-oaiMeta ###### dataDescription `data` is a [message delta](/docs/api-reference/assistants-streaming/message-delta-object) ##### 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](https://platform.openai.com/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](https://platform.openai.com/docs/api-reference/messages/object) ends before it is completed. ##### x-oaiMeta ###### dataDescription `data` is a [message](/docs/api-reference/messages/object) #### discriminator ##### propertyName event ### Metadata #### type object #### description Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. #### additionalProperties ##### type string #### x-oaiTypeLabel map #### nullable true ### Model #### title Model #### description Describes an OpenAI model offering that can be used with the API. #### 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 ###### 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" } ### ModelIds #### anyOf ##### $ref #/components/schemas/ModelIdsShared ##### $ref #/components/schemas/ModelIdsResponses ### ModelIdsResponses #### example gpt-4o #### anyOf ##### $ref #/components/schemas/ModelIdsShared ##### type string ##### title ResponsesOnlyModel ##### enum - o1-pro - o1-pro-2025-03-19 - o3-pro - o3-pro-2025-06-10 - o3-deep-research - o3-deep-research-2025-06-26 - o4-mini-deep-research - o4-mini-deep-research-2025-06-26 - computer-use-preview - computer-use-preview-2025-03-11 ### ModelIdsShared #### example gpt-4o #### anyOf ##### type string ##### $ref #/components/schemas/ChatModel ### ModelResponseProperties #### type object #### properties ##### metadata ###### $ref #/components/schemas/Metadata ##### top_logprobs ###### description An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. ###### type integer ###### minimum 0 ###### maximum 20 ###### nullable true ##### 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. 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 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 ###### deprecated true ###### description This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations. A stable identifier for your end-users. Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). ##### safety_identifier ###### type string ###### example safety-identifier-1234 ###### description A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). ##### prompt_cache_key ###### type string ###### example prompt-cache-key-1234 ###### description Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching). ##### service_tier ###### $ref #/components/schemas/ServiceTier ### ModifyAssistantRequest #### type object #### additionalProperties false #### properties ##### model ###### description ID of the model to use. You can use the [List models](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/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 ###### nullable true ###### maxLength 256 ##### description ###### description The description of the assistant. The maximum length is 512 characters. ###### type string ###### nullable true ###### maxLength 512 ##### instructions ###### description The system instructions that the assistant uses. The maximum length is 256,000 characters. ###### type string ###### nullable true ###### 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 ####### $ref #/components/schemas/AssistantTool ##### 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](https://platform.openai.com/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](https://platform.openai.com/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 ### ModifyCertificateRequest #### type object #### properties ##### name ###### type string ###### description The updated name for the certificate #### required - name ### 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](https://platform.openai.com/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](https://platform.openai.com/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 ###### enum - move ###### default move ###### description Specifies the event type. For a move action, this property is always set to `move`. ###### x-stainless-const true ##### x ###### type integer ###### description The x-coordinate to move to. ##### y ###### type integer ###### description The y-coordinate to move to. #### required - 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 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. ##### expires_at ###### type integer ###### description The Unix timestamp (in seconds) for when the file will expire. ##### filename ###### type string ###### description The name of the file. ##### object ###### type string ###### description The object type, which is always `file`. ###### enum - file ###### 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`, `vision`, and `user_data`. ###### enum - assistants - assistants_output - batch - batch_output - fine-tune - fine-tune-results - vision - user_data ##### 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 ##### 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, "expires_at": 1680202602, "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 ### OutputAudio #### type object #### title Output audio #### description An audio output from the model. #### properties ##### type ###### type string ###### description The type of the output audio. Always `output_audio`. ###### enum - output_audio ###### x-stainless-const true ##### data ###### type string ###### description Base64-encoded audio data from the model. ##### transcript ###### type string ###### description The transcript of the audio data from the model. #### required - type - data - transcript ### OutputContent #### anyOf ##### $ref #/components/schemas/OutputTextContent ##### $ref #/components/schemas/RefusalContent #### discriminator ##### propertyName type ### 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 ##### $ref #/components/schemas/ImageGenToolCall ##### $ref #/components/schemas/CodeInterpreterToolCall ##### $ref #/components/schemas/LocalShellToolCall ##### $ref #/components/schemas/MCPToolCall ##### $ref #/components/schemas/MCPListTools ##### $ref #/components/schemas/MCPApprovalRequest ##### $ref #/components/schemas/CustomToolCall #### discriminator ##### propertyName type ### OutputMessage #### type object #### title Output message #### description An output message from the model. #### properties ##### id ###### type string ###### description The unique ID of the output message. ###### x-stainless-go-json omitzero ##### type ###### type string ###### description The type of the output message. Always `message`. ###### enum - message ###### x-stainless-const true ##### role ###### type string ###### description The role of the output message. Always `assistant`. ###### enum - assistant ###### x-stainless-const true ##### content ###### type array ###### description The content of the output message. ###### items ####### $ref #/components/schemas/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 ### ParallelToolCalls #### description Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. #### type boolean #### default true ### PartialImages #### type integer #### maximum 3 #### minimum 0 #### default 0 #### example 1 #### nullable true #### description The number of partial images to generate. This parameter is used for streaming responses that return partial images. Value must be between 0 and 3. When set to 0, the response will be a single image sent in one streaming event. Note that the final image may be sent before the full number of partial images are generated if the full image is generated more quickly. ### PredictionContent #### type object #### title Static Content #### description Static predicted output content, such as the content of a text file that is being regenerated. #### required - type - content #### properties ##### type ###### 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 ###### 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. ###### anyOf ####### 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](https://platform.openai.com/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 ##### object ###### 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 ###### 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 #### type object #### description Represents an individual API key in a project. #### properties ##### object ###### type string ###### enum - 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 ##### last_used_at ###### type integer ###### description The Unix timestamp (in seconds) of when the API key was last used. ##### id ###### type string ###### 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 - last_used_at - id - 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, "last_used_at": 1711471534, "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 - 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 #### type object #### properties ##### object ###### type string ###### enum - list ###### x-stainless-const true ##### data ###### type array ###### items ####### $ref #/components/schemas/Project ##### first_id ###### type string ##### last_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 ###### type string ###### enum - project.rate_limit ###### description The object type, which is always `project.rate_limit` ###### x-stainless-const true ##### id ###### type string ###### description The identifier, which can be referenced in API endpoints. ##### model ###### 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. #### required - object - 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 ##### object ###### type string ###### enum - list ###### x-stainless-const true ##### data ###### type array ###### items ####### $ref #/components/schemas/ProjectRateLimit ##### first_id ###### type string ##### last_id ###### type string ##### has_more ###### type boolean #### 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 #### type object #### description Represents an individual service account in a project. #### properties ##### object ###### type string ###### enum - organization.project.service_account ###### description The object type, which is always `organization.project.service_account` ###### 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 ###### 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 - 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 ##### object ###### type string ###### enum - organization.project.service_account.api_key ###### description The object type, which is always `organization.project.service_account.api_key` ###### x-stainless-const true ##### value ###### type string ##### name ###### type string ##### created_at ###### 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. #### required - name ### ProjectServiceAccountCreateResponse #### type object #### properties ##### object ###### type string ###### enum - organization.project.service_account ###### x-stainless-const true ##### id ###### type string ##### name ###### type string ##### 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 - id - name - role - created_at - api_key ### ProjectServiceAccountDeleteResponse #### type object #### properties ##### object ###### type string ###### enum - organization.project.service_account.deleted ###### x-stainless-const true ##### id ###### type string ##### deleted ###### type boolean #### required - object - id - deleted ### ProjectServiceAccountListResponse #### type object #### properties ##### object ###### type string ###### enum - list ###### 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 #### type object #### properties ##### 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 - organization.project.user ###### description The object type, which is always `organization.project.user` ###### 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 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 - 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 #### properties ##### user_id ###### type string ###### description The ID of the user. ##### role ###### type string ###### enum - owner - member ###### description `owner` or `member` #### required - user_id - role ### ProjectUserDeleteResponse #### type object #### properties ##### object ###### type string ###### enum - organization.project.user.deleted ###### x-stainless-const true ##### id ###### type string ##### deleted ###### type boolean #### required - object - id - deleted ### ProjectUserListResponse #### type object #### properties ##### object ###### type string ##### data ###### type array ###### items ####### $ref #/components/schemas/ProjectUser ##### first_id ###### type string ##### last_id ###### type string ##### has_more ###### type boolean #### required - object - data - first_id - last_id - has_more ### ProjectUserUpdateRequest #### type object #### properties ##### role ###### type string ###### enum - owner - member ###### description `owner` or `member` #### required - role ### Prompt #### type object #### nullable true #### description Reference to a prompt template and its variables. [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). #### required - id #### properties ##### id ###### type string ###### description The unique identifier of the prompt template to use. ##### version ###### type string ###### description Optional version of the prompt template. ###### nullable true ##### variables ###### $ref #/components/schemas/ResponsePromptVariables ### RealtimeClientEvent #### discriminator ##### propertyName type #### description A realtime client event. #### anyOf ##### $ref #/components/schemas/RealtimeClientEventConversationItemCreate ##### $ref #/components/schemas/RealtimeClientEventConversationItemDelete ##### $ref #/components/schemas/RealtimeClientEventConversationItemRetrieve ##### $ref #/components/schemas/RealtimeClientEventConversationItemTruncate ##### $ref #/components/schemas/RealtimeClientEventInputAudioBufferAppend ##### $ref #/components/schemas/RealtimeClientEventInputAudioBufferClear ##### $ref #/components/schemas/RealtimeClientEventOutputAudioBufferClear ##### $ref #/components/schemas/RealtimeClientEventInputAudioBufferCommit ##### $ref #/components/schemas/RealtimeClientEventResponseCancel ##### $ref #/components/schemas/RealtimeClientEventResponseCreate ##### $ref #/components/schemas/RealtimeClientEventSessionUpdate ##### $ref #/components/schemas/RealtimeClientEventTranscriptionSessionUpdate ### RealtimeClientEventConversationItemCreate #### 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. #### properties ##### event_id ###### type string ###### description Optional client-generated ID used to identify this event. ##### type ###### description The event type, must be `conversation.item.create`. ###### x-stainless-const true ###### const conversation.item.create ##### 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 - 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 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 ##### event_id ###### type string ###### description Optional client-generated ID used to identify this event. ##### type ###### description The event type, must be `conversation.item.delete`. ###### x-stainless-const true ###### const conversation.item.delete ##### item_id ###### type string ###### description The ID of the item to delete. #### required - type - item_id #### x-oaiMeta ##### name conversation.item.delete ##### group realtime ##### example { "event_id": "event_901", "type": "conversation.item.delete", "item_id": "msg_003" } ### RealtimeClientEventConversationItemRetrieve #### type object #### description Send this event when you want to retrieve the server's representation of a specific item in the conversation history. This is useful, for example, to inspect user audio after noise cancellation and VAD. The server will respond with a `conversation.item.retrieved` event, unless the item does not exist in the conversation history, in which case the server will respond with an error. #### properties ##### event_id ###### type string ###### description Optional client-generated ID used to identify this event. ##### type ###### description The event type, must be `conversation.item.retrieve`. ###### x-stainless-const true ###### const conversation.item.retrieve ##### item_id ###### type string ###### description The ID of the item to retrieve. #### required - type - item_id #### x-oaiMeta ##### name conversation.item.retrieve ##### group realtime ##### example { "event_id": "event_901", "type": "conversation.item.retrieve", "item_id": "msg_003" } ### RealtimeClientEventConversationItemTruncate #### 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. #### properties ##### event_id ###### type string ###### description Optional client-generated ID used to identify this event. ##### type ###### description The event type, must be `conversation.item.truncate`. ###### x-stainless-const true ###### const conversation.item.truncate ##### 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 - type - 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 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 ##### event_id ###### type string ###### description Optional client-generated ID used to identify this event. ##### type ###### description The event type, must be `input_audio_buffer.append`. ###### x-stainless-const true ###### const input_audio_buffer.append ##### 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 - type - 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 Send this event to clear the audio bytes in the buffer. The server will respond with an `input_audio_buffer.cleared` event. #### properties ##### event_id ###### type string ###### description Optional client-generated ID used to identify this event. ##### type ###### description The event type, must be `input_audio_buffer.clear`. ###### x-stainless-const true ###### const input_audio_buffer.clear #### required - type #### x-oaiMeta ##### name input_audio_buffer.clear ##### group realtime ##### example { "event_id": "event_012", "type": "input_audio_buffer.clear" } ### RealtimeClientEventInputAudioBufferCommit #### 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` event. #### properties ##### event_id ###### type string ###### description Optional client-generated ID used to identify this event. ##### type ###### description The event type, must be `input_audio_buffer.commit`. ###### x-stainless-const true ###### const input_audio_buffer.commit #### required - type #### x-oaiMeta ##### name input_audio_buffer.commit ##### group realtime ##### example { "event_id": "event_789", "type": "input_audio_buffer.commit" } ### RealtimeClientEventOutputAudioBufferClear #### type object #### description **WebRTC Only:** Emit to cut off the current audio response. This will trigger the server to stop generating audio and emit a `output_audio_buffer.cleared` event. This event should be preceded by a `response.cancel` client event to stop the generation of the current response. [Learn more](https://platform.openai.com/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc). #### properties ##### event_id ###### type string ###### description The unique ID of the client event used for error handling. ##### type ###### description The event type, must be `output_audio_buffer.clear`. ###### x-stainless-const true ###### const output_audio_buffer.clear #### required - type #### x-oaiMeta ##### name output_audio_buffer.clear ##### group realtime ##### example { "event_id": "optional_client_event_id", "type": "output_audio_buffer.clear" } ### RealtimeClientEventResponseCancel #### type object #### description Send this event to cancel an in-progress response. The server will respond with a `response.done` event with a status of `response.status=cancelled`. If there is no response to cancel, the server will respond with an error. #### properties ##### event_id ###### type string ###### description Optional client-generated ID used to identify this event. ##### type ###### description The event type, must be `response.cancel`. ###### x-stainless-const true ###### const response.cancel ##### 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 - type #### x-oaiMeta ##### name response.cancel ##### group realtime ##### example { "event_id": "event_567", "type": "response.cancel" } ### RealtimeClientEventResponseCreate #### 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 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 ##### event_id ###### type string ###### description Optional client-generated ID used to identify this event. ##### type ###### description The event type, must be `response.create`. ###### x-stainless-const true ###### const response.create ##### response ###### $ref #/components/schemas/RealtimeResponseCreateParams #### required - type #### x-oaiMeta ##### name response.create ##### group realtime ##### example { "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 } } ### RealtimeClientEventSessionUpdate #### type object #### 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 ##### event_id ###### type string ###### description Optional client-generated ID used to identify this event. ##### type ###### description The event type, must be `session.update`. ###### x-stainless-const true ###### const session.update ##### session ###### $ref #/components/schemas/RealtimeSessionCreateRequest #### required - type - session #### x-oaiMeta ##### name session.update ##### 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", "speed": 1.1, "tracing": "auto" } } ### RealtimeClientEventTranscriptionSessionUpdate #### type object #### description Send this event to update a transcription session. #### properties ##### event_id ###### type string ###### description Optional client-generated ID used to identify this event. ##### type ###### description The event type, must be `transcription_session.update`. ###### x-stainless-const true ###### const transcription_session.update ##### session ###### $ref #/components/schemas/RealtimeTranscriptionSessionCreateRequest #### required - type - session #### x-oaiMeta ##### name transcription_session.update ##### group realtime ##### example { "type": "transcription_session.update", "session": { "input_audio_format": "pcm16", "input_audio_transcription": { "model": "gpt-4o-transcribe", "prompt": "", "language": "" }, "turn_detection": { "type": "server_vad", "threshold": 0.5, "prefix_padding_ms": 300, "silence_duration_ms": 500, "create_response": true, }, "input_audio_noise_reduction": { "type": "near_field" }, "include": [ "item.input_audio_transcription.logprobs", ] } } ### RealtimeConversationItem #### type object #### 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 ###### 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`. ###### x-stainless-const true ##### status ###### type string ###### enum - completed - incomplete - in_progress ###### description The status of the item (`completed`, `incomplete`, `in_progress`). These have no effect on the conversation, but are accepted for consistency with the `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 ###### 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 ####### $ref #/components/schemas/RealtimeConversationItemContent ##### 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 #### description The item to add to the conversation. #### properties ##### 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. ##### type ###### type string ###### enum - message - function_call - function_call_output - item_reference ###### description The type of the item (`message`, `function_call`, `function_call_output`, `item_reference`). ##### object ###### type string ###### enum - realtime.item ###### description Identifier for the API object being returned - always `realtime.item`. ###### x-stainless-const true ##### status ###### type string ###### enum - completed - incomplete - in_progress ###### description The status of the item (`completed`, `incomplete`, `in_progress`). These have no effect on the conversation, but are accepted for consistency with the `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 ###### 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 ####### properties ######## type ######### type string ######### enum - input_text - input_audio - 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). ### RealtimeResponse #### type object #### description The response resource. #### properties ##### id ###### type string ###### description The unique ID of the response. ##### object ###### description The object type, must be `realtime.response`. ###### x-stainless-const true ###### const realtime.response ##### status ###### type string ###### enum - completed - cancelled - failed - incomplete - in_progress ###### description The final status of the response (`completed`, `cancelled`, `failed`, or `incomplete`, `in_progress`). ##### status_details ###### type object ###### description Additional details about the status. ###### properties ####### type ######## type string ######## enum - completed - cancelled - incomplete - failed ######## 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 the `conversation_id` will be an id like `conv_1234`. ###### type string ##### voice ###### $ref #/components/schemas/VoiceIdsShared ###### 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 ###### 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 ###### description Maximum number of output tokens for a single assistant response, inclusive of tool calls, that was used in this response. ###### anyOf ####### type integer ####### type string ####### enum - inf ####### x-stainless-const true ### RealtimeResponseCreateParams #### type object #### description Create a new Realtime response with these parameters #### properties ##### 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 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 ###### $ref #/components/schemas/VoiceIdsShared ###### 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 - 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 ###### 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`. ###### anyOf ####### type integer ####### type string ####### enum - inf ####### x-stainless-const true ##### 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. ###### anyOf ####### 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 ### RealtimeServerEvent #### discriminator ##### propertyName type #### description A realtime server event. #### anyOf ##### $ref #/components/schemas/RealtimeServerEventConversationCreated ##### $ref #/components/schemas/RealtimeServerEventConversationItemCreated ##### $ref #/components/schemas/RealtimeServerEventConversationItemDeleted ##### $ref #/components/schemas/RealtimeServerEventConversationItemInputAudioTranscriptionCompleted ##### $ref #/components/schemas/RealtimeServerEventConversationItemInputAudioTranscriptionDelta ##### $ref #/components/schemas/RealtimeServerEventConversationItemInputAudioTranscriptionFailed ##### $ref #/components/schemas/RealtimeServerEventConversationItemRetrieved ##### $ref #/components/schemas/RealtimeServerEventConversationItemTruncated ##### $ref #/components/schemas/RealtimeServerEventError ##### $ref #/components/schemas/RealtimeServerEventInputAudioBufferCleared ##### $ref #/components/schemas/RealtimeServerEventInputAudioBufferCommitted ##### $ref #/components/schemas/RealtimeServerEventInputAudioBufferSpeechStarted ##### $ref #/components/schemas/RealtimeServerEventInputAudioBufferSpeechStopped ##### $ref #/components/schemas/RealtimeServerEventRateLimitsUpdated ##### $ref #/components/schemas/RealtimeServerEventResponseAudioDelta ##### $ref #/components/schemas/RealtimeServerEventResponseAudioDone ##### $ref #/components/schemas/RealtimeServerEventResponseAudioTranscriptDelta ##### $ref #/components/schemas/RealtimeServerEventResponseAudioTranscriptDone ##### $ref #/components/schemas/RealtimeServerEventResponseContentPartAdded ##### $ref #/components/schemas/RealtimeServerEventResponseContentPartDone ##### $ref #/components/schemas/RealtimeServerEventResponseCreated ##### $ref #/components/schemas/RealtimeServerEventResponseDone ##### $ref #/components/schemas/RealtimeServerEventResponseFunctionCallArgumentsDelta ##### $ref #/components/schemas/RealtimeServerEventResponseFunctionCallArgumentsDone ##### $ref #/components/schemas/RealtimeServerEventResponseOutputItemAdded ##### $ref #/components/schemas/RealtimeServerEventResponseOutputItemDone ##### $ref #/components/schemas/RealtimeServerEventResponseTextDelta ##### $ref #/components/schemas/RealtimeServerEventResponseTextDone ##### $ref #/components/schemas/RealtimeServerEventSessionCreated ##### $ref #/components/schemas/RealtimeServerEventSessionUpdated ##### $ref #/components/schemas/RealtimeServerEventTranscriptionSessionUpdated ##### $ref #/components/schemas/RealtimeServerEventOutputAudioBufferStarted ##### $ref #/components/schemas/RealtimeServerEventOutputAudioBufferStopped ##### $ref #/components/schemas/RealtimeServerEventOutputAudioBufferCleared ### 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 ###### description The event type, must be `conversation.created`. ###### x-stainless-const true ###### const conversation.created ##### conversation ###### type object ###### description The conversation resource. ###### properties ####### id ######## type string ######## description The unique ID of the conversation. ####### object ######## description The object type, must be `realtime.conversation`. ######## const 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 #### 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 ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `conversation.item.created`. ###### x-stainless-const true ###### const conversation.item.created ##### previous_item_id ###### type string ###### nullable true ###### description The ID of the preceding item in the Conversation context, allows the client to understand the order of the conversation. Can be `null` if the item has no predecessor. ##### item ###### $ref #/components/schemas/RealtimeConversationItem #### required - event_id - type - 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": [] } } ### 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 ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `conversation.item.deleted`. ###### x-stainless-const true ###### const conversation.item.deleted ##### 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 user audio buffer. Transcription begins when the input audio buffer is committed by the client or server (in `server_vad` mode). Transcription runs asynchronously with Response creation, so this event may come before or after the Response events. Realtime API models accept audio natively, and thus input transcription is a separate process run on a separate ASR (Automatic Speech Recognition) model. The transcript may diverge somewhat from the model's interpretation, and should be treated as a rough guide. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### 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. ##### logprobs ###### type array ###### description The log probabilities of the transcription. ###### nullable true ###### items ####### $ref #/components/schemas/LogProbProperties ##### usage ###### type object ###### description Usage statistics for the transcription. ###### anyOf ####### $ref #/components/schemas/TranscriptTextUsageTokens ####### title Token Usage ####### $ref #/components/schemas/TranscriptTextUsageDuration ####### title Duration Usage #### required - event_id - type - item_id - content_index - transcript - usage #### 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?", "usage": { "type": "tokens", "total_tokens": 48, "input_tokens": 38, "input_token_details": { "text_tokens": 10, "audio_tokens": 28, }, "output_tokens": 10, } } ### RealtimeServerEventConversationItemInputAudioTranscriptionDelta #### type object #### description Returned when the text value of an input audio transcription content part is updated. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `conversation.item.input_audio_transcription.delta`. ###### x-stainless-const true ###### const conversation.item.input_audio_transcription.delta ##### item_id ###### type string ###### description The ID of the item. ##### content_index ###### type integer ###### description The index of the content part in the item's content array. ##### delta ###### type string ###### description The text delta. ##### logprobs ###### type array ###### description The log probabilities of the transcription. ###### nullable true ###### items ####### $ref #/components/schemas/LogProbProperties #### required - event_id - type - item_id #### x-oaiMeta ##### name conversation.item.input_audio_transcription.delta ##### group realtime ##### example { "type": "conversation.item.input_audio_transcription.delta", "event_id": "event_001", "item_id": "item_001", "content_index": 0, "delta": "Hello" } ### 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 ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### 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 ###### 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 ###### 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 - 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 } } ### RealtimeServerEventConversationItemRetrieved #### type object #### description Returned when a conversation item is retrieved with `conversation.item.retrieve`. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `conversation.item.retrieved`. ###### x-stainless-const true ###### const conversation.item.retrieved ##### item ###### $ref #/components/schemas/RealtimeConversationItem #### required - event_id - type - item #### x-oaiMeta ##### name conversation.item.retrieved ##### 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==" } ] } } ### 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 ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `conversation.item.truncated`. ###### x-stainless-const true ###### const conversation.item.truncated ##### item_id ###### 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 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 #### 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 ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `error`. ###### x-stainless-const true ###### const error ##### 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 - 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 ###### description The event type, must be `input_audio_buffer.cleared`. ###### x-stainless-const true ###### const input_audio_buffer.cleared #### 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 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 ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `input_audio_buffer.committed`. ###### x-stainless-const true ###### const input_audio_buffer.committed ##### previous_item_id ###### type string ###### nullable true ###### description The ID of the preceding item after which the new item will be inserted. Can be `null` if the item has no predecessor. ##### item_id ###### type string ###### description The ID of the user message item that will be created. #### required - event_id - type - 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 unique ID of the server event. ##### type ###### description The event type, must be `input_audio_buffer.speech_started`. ###### x-stainless-const true ###### const input_audio_buffer.speech_started ##### 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 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 - 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 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 ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `input_audio_buffer.speech_stopped`. ###### x-stainless-const true ###### const input_audio_buffer.speech_stopped ##### 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 ###### 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" } ### RealtimeServerEventOutputAudioBufferCleared #### type object #### description **WebRTC Only:** Emitted when the output audio buffer is cleared. This happens either in VAD mode when the user has interrupted (`input_audio_buffer.speech_started`), or when the client has emitted the `output_audio_buffer.clear` event to manually cut off the current audio response. [Learn more](https://platform.openai.com/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc). #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `output_audio_buffer.cleared`. ###### x-stainless-const true ###### const output_audio_buffer.cleared ##### response_id ###### type string ###### description The unique ID of the response that produced the audio. #### required - event_id - type - response_id #### x-oaiMeta ##### name output_audio_buffer.cleared ##### group realtime ##### example { "event_id": "event_abc123", "type": "output_audio_buffer.cleared", "response_id": "resp_abc123" } ### RealtimeServerEventOutputAudioBufferStarted #### type object #### description **WebRTC Only:** Emitted when the server begins streaming audio to the client. This event is emitted after an audio content part has been added (`response.content_part.added`) to the response. [Learn more](https://platform.openai.com/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc). #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `output_audio_buffer.started`. ###### x-stainless-const true ###### const output_audio_buffer.started ##### response_id ###### type string ###### description The unique ID of the response that produced the audio. #### required - event_id - type - response_id #### x-oaiMeta ##### name output_audio_buffer.started ##### group realtime ##### example { "event_id": "event_abc123", "type": "output_audio_buffer.started", "response_id": "resp_abc123" } ### RealtimeServerEventOutputAudioBufferStopped #### type object #### description **WebRTC Only:** Emitted when the output audio buffer has been completely drained on the server, and no more audio is forthcoming. This event is emitted after the full response data has been sent to the client (`response.done`). [Learn more](https://platform.openai.com/docs/guides/realtime-conversations#client-and-server-events-for-audio-in-webrtc). #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `output_audio_buffer.stopped`. ###### x-stainless-const true ###### const output_audio_buffer.stopped ##### response_id ###### type string ###### description The unique ID of the response that produced the audio. #### required - event_id - type - response_id #### x-oaiMeta ##### name output_audio_buffer.stopped ##### group realtime ##### example { "event_id": "event_abc123", "type": "output_audio_buffer.stopped", "response_id": "resp_abc123" } ### 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 ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `rate_limits.updated`. ###### x-stainless-const true ###### const rate_limits.updated ##### 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 - 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 ###### description The event type, must be `response.audio.delta`. ###### x-stainless-const true ###### const response.audio.delta ##### 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 - response_id - item_id - output_index - content_index - delta #### x-oaiMeta ##### name response.audio.delta ##### 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" } ### RealtimeServerEventResponseAudioDone #### type object #### description Returned when the model-generated audio is done. Also emitted when a Response is interrupted, incomplete, or cancelled. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `response.audio.done`. ###### x-stainless-const true ###### const response.audio.done ##### 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. #### 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 #### type object #### description Returned when the model-generated transcription of audio output is updated. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `response.audio_transcript.delta`. ###### x-stainless-const true ###### const response.audio_transcript.delta ##### 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 transcript delta. #### required - event_id - 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 #### type object #### 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 The unique ID of the server event. ##### type ###### description The event type, must be `response.audio_transcript.done`. ###### x-stainless-const true ###### const response.audio_transcript.done ##### 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 ###### type string ###### description The final transcript of the audio. #### 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 #### type object #### description Returned when a new content part is added to an assistant message item during response generation. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `response.content_part.added`. ###### x-stainless-const true ###### const response.content_part.added ##### 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 - text - audio ######## 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.added ##### group realtime ##### 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": "" } } ### RealtimeServerEventResponseContentPartDone #### 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. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `response.content_part.done`. ###### x-stainless-const true ###### const response.content_part.done ##### 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 - text - audio ######## 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 ##### 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." } } ### RealtimeServerEventResponseCreated #### 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`. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `response.created`. ###### x-stainless-const true ###### const response.created ##### response ###### $ref #/components/schemas/RealtimeResponse #### required - event_id - type - response #### x-oaiMeta ##### name response.created ##### group realtime ##### example { "event_id": "event_2930", "type": "response.created", "response": { "id": "resp_001", "object": "realtime.response", "status": "in_progress", "status_details": null, "output": [], "usage": null } } ### RealtimeServerEventResponseDone #### 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. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `response.done`. ###### x-stainless-const true ###### const response.done ##### response ###### $ref #/components/schemas/RealtimeResponse #### required - event_id - type - response #### x-oaiMeta ##### name response.done ##### group realtime ##### 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 } } } } ### RealtimeServerEventResponseFunctionCallArgumentsDelta #### type object #### description Returned when the model-generated function call arguments are updated. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `response.function_call_arguments.delta`. ###### x-stainless-const true ###### const response.function_call_arguments.delta ##### 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 - response_id - item_id - output_index - call_id - delta #### x-oaiMeta ##### name response.function_call_arguments.delta ##### group realtime ##### 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\"" } ### RealtimeServerEventResponseFunctionCallArgumentsDone #### type object #### description Returned when the model-generated function call arguments are done streaming. Also emitted when a Response is interrupted, incomplete, or cancelled. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `response.function_call_arguments.done`. ###### x-stainless-const true ###### const response.function_call_arguments.done ##### 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 ###### 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 unique ID of the server event. ##### type ###### description The event type, must be `response.output_item.added`. ###### x-stainless-const true ###### const response.output_item.added ##### 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.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 #### description Returned when an Item is done streaming. Also emitted when a Response is interrupted, incomplete, or cancelled. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `response.output_item.done`. ###### x-stainless-const true ###### const response.output_item.done ##### 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 ###### description The event type, must be `response.text.delta`. ###### x-stainless-const true ###### const response.text.delta ##### 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. #### 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 emitted when a Response is interrupted, incomplete, or cancelled. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `response.text.done`. ###### x-stainless-const true ###### const response.text.done ##### 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. ##### 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 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 ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `session.created`. ###### x-stainless-const true ###### const session.created ##### 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", "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", "speed": 1.1, "tracing": "auto" } } ### RealtimeServerEventSessionUpdated #### type object #### description Returned when a session is updated with a `session.update` event, unless there is an error. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `session.updated`. ###### x-stainless-const true ###### const session.updated ##### 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", "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, "speed": 1.1, "tracing": "auto" } } ### RealtimeServerEventTranscriptionSessionUpdated #### type object #### description Returned when a transcription session is updated with a `transcription_session.update` event, unless there is an error. #### properties ##### event_id ###### type string ###### description The unique ID of the server event. ##### type ###### description The event type, must be `transcription_session.updated`. ###### x-stainless-const true ###### const transcription_session.updated ##### session ###### $ref #/components/schemas/RealtimeTranscriptionSessionCreateResponse #### required - event_id - type - session #### x-oaiMeta ##### name transcription_session.updated ##### group realtime ##### example { "event_id": "event_5678", "type": "transcription_session.updated", "session": { "id": "sess_001", "object": "realtime.transcription_session", "input_audio_format": "pcm16", "input_audio_transcription": { "model": "gpt-4o-transcribe", "prompt": "", "language": "" }, "turn_detection": { "type": "server_vad", "threshold": 0.5, "prefix_padding_ms": 300, "silence_duration_ms": 500, "create_response": true, // "interrupt_response": false -- this will NOT be returned }, "input_audio_noise_reduction": { "type": "near_field" }, "include": [ "item.input_audio_transcription.avg_logprob", ], } } ### RealtimeSession #### type object #### description Realtime session object configuration. #### properties ##### id ###### type string ###### description Unique identifier for the session that looks like `sess_1234567890abcdef`. ##### 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 - gpt-4o-realtime-preview - gpt-4o-realtime-preview-2024-10-01 - gpt-4o-realtime-preview-2024-12-17 - gpt-4o-realtime-preview-2025-06-03 - 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 ###### $ref #/components/schemas/VoiceIdsShared ###### 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 ###### default pcm16 ###### 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 ###### default pcm16 ###### 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 [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) and should be treated as guidance of input audio content rather than precisely what the model heard. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service. ###### properties ####### model ######## type string ######## description The model to use for transcription, current options are `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, and `whisper-1`. ####### 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 ######## type string ######## description An optional text to guide the model's style or continue a previous audio segment. For `whisper-1`, the [prompt is a list of keywords](https://platform.openai.com/docs/guides/speech-to-text#prompting). For `gpt-4o-transcribe` models, the prompt is a free text string, for example "expect words related to technology". ##### turn_detection ###### type object ###### description Configuration for turn detection, ether Server VAD or Semantic VAD. This can be set to `null` to turn off, in which case the client must manually trigger model response. 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. Semantic VAD is more advanced and uses a turn detection model (in conjunction with VAD) to semantically estimate whether the user has finished speaking, then dynamically sets a timeout based on this probability. For example, if user audio trails off with "uhhm", the model will score a low probability of turn end and wait longer for the user to continue speaking. This can be useful for more natural conversations, but may have a higher latency. ###### properties ####### type ######## type string ######## default server_vad ######## enum - server_vad - semantic_vad ######## description Type of turn detection. ####### eagerness ######## type string ######## default auto ######## enum - low - medium - high - auto ######## description Used only for `semantic_vad` mode. The eagerness of the model to respond. `low` will wait longer for the user to continue speaking, `high` will respond more quickly. `auto` is the default and is equivalent to `medium`. ####### threshold ######## type number ######## description Used only for `server_vad` mode. 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 Used only for `server_vad` mode. Amount of audio to include before the VAD detected speech (in milliseconds). Defaults to 300ms. ####### silence_duration_ms ######## type integer ######## description Used only for `server_vad` mode. 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. ####### 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. ##### input_audio_noise_reduction ###### type object ###### description Configuration for input audio noise reduction. This can be set to `null` to turn off. Noise reduction filters audio added to the input audio buffer before it is sent to VAD and the model. Filtering the audio can improve VAD and turn detection accuracy (reducing false positives) and model performance by improving perception of the input audio. ###### properties ####### type ######## type string ######## enum - near_field - far_field ######## description Type of noise reduction. `near_field` is for close-talking microphones such as headphones, `far_field` is for far-field microphones such as laptop or conference room microphones. ##### speed ###### type number ###### default 1 ###### maximum 1.5 ###### minimum 0.25 ###### description The speed of the model's spoken response. 1.0 is the default speed. 0.25 is the minimum speed. 1.5 is the maximum speed. This value can only be changed in between model turns, not while a response is in progress. ##### tracing ###### title Tracing Configuration ###### description Configuration options for tracing. Set to null to disable tracing. Once tracing is enabled for a session, the configuration cannot be modified. `auto` will create a trace for the session with default values for the workflow name, group id, and metadata. ###### anyOf ####### type string ####### default auto ####### description Default tracing mode for the session. ####### enum - auto ####### x-stainless-const true ####### type object ####### title Tracing Configuration ####### description Granular configuration for tracing. ####### properties ######## workflow_name ######### type string ######### description The name of the workflow to attach to this trace. This is used to name the trace in the traces dashboard. ######## group_id ######### type string ######### description The group id to attach to this trace to enable filtering and grouping in the traces dashboard. ######## metadata ######### type object ######### description The arbitrary metadata to attach to this trace to enable filtering in the traces dashboard. ##### 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 ###### default auto ###### description How the model chooses tools. Options are `auto`, `none`, `required`, or specify a function. ##### temperature ###### type number ###### default 0.8 ###### description Sampling temperature for the model, limited to [0.6, 1.2]. For audio models a temperature of 0.8 is highly recommended for best performance. ##### max_response_output_tokens ###### 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`. ###### anyOf ####### type integer ####### type string ####### enum - inf ####### x-stainless-const true ### RealtimeSessionCreateRequest #### type object #### description Realtime session object configuration. #### properties ##### 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 - gpt-4o-realtime-preview - gpt-4o-realtime-preview-2024-10-01 - gpt-4o-realtime-preview-2024-12-17 - gpt-4o-realtime-preview-2025-06-03 - 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 ###### $ref #/components/schemas/VoiceIdsShared ###### 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 ###### default pcm16 ###### 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 ###### default pcm16 ###### 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 [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) and should be treated as guidance of input audio content rather than precisely what the model heard. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service. ###### properties ####### model ######## type string ######## description The model to use for transcription, current options are `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, and `whisper-1`. ####### 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 ######## type string ######## description An optional text to guide the model's style or continue a previous audio segment. For `whisper-1`, the [prompt is a list of keywords](https://platform.openai.com/docs/guides/speech-to-text#prompting). For `gpt-4o-transcribe` models, the prompt is a free text string, for example "expect words related to technology". ##### turn_detection ###### type object ###### description Configuration for turn detection, ether Server VAD or Semantic VAD. This can be set to `null` to turn off, in which case the client must manually trigger model response. 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. Semantic VAD is more advanced and uses a turn detection model (in conjunction with VAD) to semantically estimate whether the user has finished speaking, then dynamically sets a timeout based on this probability. For example, if user audio trails off with "uhhm", the model will score a low probability of turn end and wait longer for the user to continue speaking. This can be useful for more natural conversations, but may have a higher latency. ###### properties ####### type ######## type string ######## default server_vad ######## enum - server_vad - semantic_vad ######## description Type of turn detection. ####### eagerness ######## type string ######## default auto ######## enum - low - medium - high - auto ######## description Used only for `semantic_vad` mode. The eagerness of the model to respond. `low` will wait longer for the user to continue speaking, `high` will respond more quickly. `auto` is the default and is equivalent to `medium`. ####### threshold ######## type number ######## description Used only for `server_vad` mode. 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 Used only for `server_vad` mode. Amount of audio to include before the VAD detected speech (in milliseconds). Defaults to 300ms. ####### silence_duration_ms ######## type integer ######## description Used only for `server_vad` mode. 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. ####### 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. ##### input_audio_noise_reduction ###### type object ###### description Configuration for input audio noise reduction. This can be set to `null` to turn off. Noise reduction filters audio added to the input audio buffer before it is sent to VAD and the model. Filtering the audio can improve VAD and turn detection accuracy (reducing false positives) and model performance by improving perception of the input audio. ###### properties ####### type ######## type string ######## enum - near_field - far_field ######## description Type of noise reduction. `near_field` is for close-talking microphones such as headphones, `far_field` is for far-field microphones such as laptop or conference room microphones. ##### speed ###### type number ###### default 1 ###### maximum 1.5 ###### minimum 0.25 ###### description The speed of the model's spoken response. 1.0 is the default speed. 0.25 is the minimum speed. 1.5 is the maximum speed. This value can only be changed in between model turns, not while a response is in progress. ##### tracing ###### title Tracing Configuration ###### description Configuration options for tracing. Set to null to disable tracing. Once tracing is enabled for a session, the configuration cannot be modified. `auto` will create a trace for the session with default values for the workflow name, group id, and metadata. ###### anyOf ####### type string ####### default auto ####### description Default tracing mode for the session. ####### enum - auto ####### x-stainless-const true ####### type object ####### title Tracing Configuration ####### description Granular configuration for tracing. ####### properties ######## workflow_name ######### type string ######### description The name of the workflow to attach to this trace. This is used to name the trace in the traces dashboard. ######## group_id ######### type string ######### description The group id to attach to this trace to enable filtering and grouping in the traces dashboard. ######## metadata ######### type object ######### description The arbitrary metadata to attach to this trace to enable filtering in the traces dashboard. ##### 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 ###### default auto ###### description How the model chooses tools. Options are `auto`, `none`, `required`, or specify a function. ##### temperature ###### type number ###### default 0.8 ###### description Sampling temperature for the model, limited to [0.6, 1.2]. For audio models a temperature of 0.8 is highly recommended for best performance. ##### max_response_output_tokens ###### 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`. ###### anyOf ####### type integer ####### type string ####### enum - inf ####### x-stainless-const true ##### client_secret ###### type object ###### description Configuration options for the generated client secret. ###### properties ####### expires_after ######## type object ######## description Configuration for the ephemeral token expiration. ######## properties ######### anchor ########## type string ########## enum - created_at ########## description The anchor point for the ephemeral token expiration. Only `created_at` is currently supported. ######### seconds ########## default 600 ########## type integer ########## description The number of seconds from the anchor point to the expiration. Select a value between `10` and `7200`. ######## required - anchor ### RealtimeSessionCreateResponse #### type object #### description A new Realtime session configuration, with an ephemeral key. Default TTL for keys is one minute. #### 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 ###### 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 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 ###### $ref #/components/schemas/VoiceIdsShared ###### 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 ###### description The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. ##### output_audio_format ###### type string ###### 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 to the model, since the model consumes audio directly. Transcription runs asynchronously 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. ##### speed ###### type number ###### default 1 ###### maximum 1.5 ###### minimum 0.25 ###### description The speed of the model's spoken response. 1.0 is the default speed. 0.25 is the minimum speed. 1.5 is the maximum speed. This value can only be changed in between model turns, not while a response is in progress. ##### tracing ###### title Tracing Configuration ###### description Configuration options for tracing. Set to null to disable tracing. Once tracing is enabled for a session, the configuration cannot be modified. `auto` will create a trace for the session with default values for the workflow name, group id, and metadata. ###### anyOf ####### type string ####### default auto ####### description Default tracing mode for the session. ####### enum - auto ####### x-stainless-const true ####### type object ####### title Tracing Configuration ####### description Granular configuration for tracing. ####### properties ######## workflow_name ######### type string ######### description The name of the workflow to attach to this trace. This is used to name the trace in the traces dashboard. ######## group_id ######### type string ######### description The group id to attach to this trace to enable filtering and grouping in the traces dashboard. ######## metadata ######### type object ######### description The arbitrary metadata to attach to this trace to enable filtering in the traces dashboard. ##### 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 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. ##### temperature ###### type number ###### description Sampling temperature for the model, limited to [0.6, 1.2]. Defaults to 0.8. ##### max_response_output_tokens ###### 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`. ###### anyOf ####### type integer ####### type string ####### enum - inf ####### x-stainless-const true #### required - client_secret #### x-oaiMeta ##### name The session object ##### group realtime ##### example { "id": "sess_001", "object": "realtime.session", "model": "gpt-4o-realtime-preview", "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, "speed": 1.1, "tracing": "auto", "max_response_output_tokens": 200, "client_secret": { "value": "ek_abc123", "expires_at": 1234567890 } } ### RealtimeTranscriptionSessionCreateRequest #### type object #### description Realtime transcription session object configuration. #### properties ##### modalities ###### description The set of modalities the model can respond with. To disable audio, set this to ["text"]. ###### items ####### type string ####### enum - text - audio ##### input_audio_format ###### type string ###### default pcm16 ###### 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. ##### input_audio_transcription ###### type object ###### description Configuration for input audio transcription. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service. ###### properties ####### model ######## type string ######## description The model to use for transcription, current options are `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, and `whisper-1`. ######## enum - gpt-4o-transcribe - gpt-4o-mini-transcribe - whisper-1 ####### 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 ######## type string ######## description An optional text to guide the model's style or continue a previous audio segment. For `whisper-1`, the [prompt is a list of keywords](https://platform.openai.com/docs/guides/speech-to-text#prompting). For `gpt-4o-transcribe` models, the prompt is a free text string, for example "expect words related to technology". ##### turn_detection ###### type object ###### description Configuration for turn detection, ether Server VAD or Semantic VAD. This can be set to `null` to turn off, in which case the client must manually trigger model response. 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. Semantic VAD is more advanced and uses a turn detection model (in conjunction with VAD) to semantically estimate whether the user has finished speaking, then dynamically sets a timeout based on this probability. For example, if user audio trails off with "uhhm", the model will score a low probability of turn end and wait longer for the user to continue speaking. This can be useful for more natural conversations, but may have a higher latency. ###### properties ####### type ######## type string ######## default server_vad ######## enum - server_vad - semantic_vad ######## description Type of turn detection. ####### eagerness ######## type string ######## default auto ######## enum - low - medium - high - auto ######## description Used only for `semantic_vad` mode. The eagerness of the model to respond. `low` will wait longer for the user to continue speaking, `high` will respond more quickly. `auto` is the default and is equivalent to `medium`. ####### threshold ######## type number ######## description Used only for `server_vad` mode. 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 Used only for `server_vad` mode. Amount of audio to include before the VAD detected speech (in milliseconds). Defaults to 300ms. ####### silence_duration_ms ######## type integer ######## description Used only for `server_vad` mode. 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. Not available for transcription sessions. ####### 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. Not available for transcription sessions. ##### input_audio_noise_reduction ###### type object ###### description Configuration for input audio noise reduction. This can be set to `null` to turn off. Noise reduction filters audio added to the input audio buffer before it is sent to VAD and the model. Filtering the audio can improve VAD and turn detection accuracy (reducing false positives) and model performance by improving perception of the input audio. ###### properties ####### type ######## type string ######## enum - near_field - far_field ######## description Type of noise reduction. `near_field` is for close-talking microphones such as headphones, `far_field` is for far-field microphones such as laptop or conference room microphones. ##### include ###### type array ###### items ####### type string ###### description The set of items to include in the transcription. Current available items are: - `item.input_audio_transcription.logprobs` ##### client_secret ###### type object ###### description Configuration options for the generated client secret. ###### properties ####### expires_at ######## type object ######## description Configuration for the ephemeral token expiration. ######## properties ######### anchor ########## default created_at ########## type string ########## enum - created_at ########## description The anchor point for the ephemeral token expiration. Only `created_at` is currently supported. ######### seconds ########## default 600 ########## type integer ########## description The number of seconds from the anchor point to the expiration. Select a value between `10` and `7200`. ### RealtimeTranscriptionSessionCreateResponse #### type object #### description A new Realtime transcription session configuration. When a session is created on the server via REST API, the session object also contains an ephemeral key. Default TTL for keys is 10 minutes. This property is not present when a session is updated via the WebSocket API. #### properties ##### client_secret ###### type object ###### description Ephemeral key returned by the API. Only present when the session is created on the server via REST 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 ###### description The set of modalities the model can respond with. To disable audio, set this to ["text"]. ###### items ####### type string ####### enum - text - audio ##### input_audio_format ###### type string ###### description The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. ##### input_audio_transcription ###### type object ###### description Configuration of the transcription model. ###### properties ####### model ######## type string ######## description The model to use for transcription. Can be `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, or `whisper-1`. ######## enum - gpt-4o-transcribe - gpt-4o-mini-transcribe - whisper-1 ####### 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 ######## type string ######## description An optional text to guide the model's style or continue a previous audio segment. The [prompt](https://platform.openai.com/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 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. #### required - client_secret #### x-oaiMeta ##### name The transcription session object ##### group realtime ##### example { "id": "sess_BBwZc7cFV3XizEyKGDCGL", "object": "realtime.transcription_session", "expires_at": 1742188264, "modalities": ["audio", "text"], "turn_detection": { "type": "server_vad", "threshold": 0.5, "prefix_padding_ms": 300, "silence_duration_ms": 200 }, "input_audio_format": "pcm16", "input_audio_transcription": { "model": "gpt-4o-transcribe", "language": null, "prompt": "" }, "client_secret": null } ### Reasoning #### type object #### description **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). #### title Reasoning #### properties ##### effort ###### $ref #/components/schemas/ReasoningEffort ##### summary ###### type string ###### description A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of `auto`, `concise`, or `detailed`. ###### enum - auto - concise - detailed ###### nullable true ##### generate_summary ###### type string ###### deprecated true ###### description **Deprecated:** use `summary` instead. A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of `auto`, `concise`, or `detailed`. ###### enum - auto - concise - detailed ###### nullable true ### ReasoningEffort #### type string #### enum - minimal - low - medium - high #### default medium #### nullable true #### description Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `minimal`, `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 A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state). #### title Reasoning #### properties ##### type ###### type string ###### description The type of the object. Always `reasoning`. ###### enum - reasoning ###### x-stainless-const true ##### id ###### type string ###### description The unique identifier of the reasoning content. ##### encrypted_content ###### type string ###### description The encrypted content of the reasoning item - populated when a response is generated with `reasoning.encrypted_content` in the `include` parameter. ###### nullable true ##### summary ###### type array ###### description Reasoning summary content. ###### items ####### type object ####### properties ######## type ######### type string ######### description The type of the object. Always `summary_text`. ######### enum - summary_text ######### x-stainless-const true ######## text ######### type string ######### description A summary of the reasoning output from the model so far. ####### required - type - text ##### content ###### type array ###### description Reasoning text content. ###### items ####### type object ####### properties ######## type ######### type string ######### description The type of the object. Always `reasoning_text`. ######### enum - reasoning_text ######### x-stainless-const true ######## text ######### type string ######### description Reasoning text output from the model. ####### required - type - text ##### status ###### type string ###### description The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. ###### enum - in_progress - completed - incomplete #### required - id - summary - type ### Response #### title The response object #### 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`, `cancelled`, `queued`, or `incomplete`. ####### enum - completed - failed - in_progress - cancelled - queued - 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 ####### 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 ###### instructions ####### nullable true ####### description A system (or developer) message inserted into the model's context. When using along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. ####### anyOf ######## type string ######## description A text input to the model, equivalent to a text input with the `developer` role. ######## type array ######## title Input item list ######## description A list of one or many input items to the model, containing different content types. ######## items ######### $ref #/components/schemas/InputItem ###### 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 ####### x-stainless-skip true ###### usage ####### $ref #/components/schemas/ResponseUsage ###### parallel_tool_calls ####### type boolean ####### description Whether to allow the model to run tool calls in parallel. ####### default true ###### conversation ####### nullable true ####### $ref #/components/schemas/Conversation-2 ##### required - id - object - created_at - error - incomplete_details - instructions - model - tools - output - parallel_tool_calls - metadata - tool_choice - temperature - top_p ### ResponseAudioDeltaEvent #### type object #### description Emitted when there is a partial audio response. #### properties ##### type ###### type string ###### description The type of the event. Always `response.audio.delta`. ###### enum - response.audio.delta ###### x-stainless-const true ##### sequence_number ###### type integer ###### description A sequence number for this chunk of the stream response. ##### delta ###### type string ###### description A chunk of Base64 encoded response audio bytes. #### required - type - delta - sequence_number #### x-oaiMeta ##### name response.audio.delta ##### group responses ##### example { "type": "response.audio.delta", "response_id": "resp_123", "delta": "base64encoded...", "sequence_number": 1 } ### ResponseAudioDoneEvent #### type object #### description Emitted when the audio response is complete. #### properties ##### type ###### type string ###### description The type of the event. Always `response.audio.done`. ###### enum - response.audio.done ###### x-stainless-const true ##### sequence_number ###### type integer ###### description The sequence number of the delta. #### required - type - sequence_number - response_id #### x-oaiMeta ##### name response.audio.done ##### group responses ##### example { "type": "response.audio.done", "response_id": "resp-123", "sequence_number": 1 } ### ResponseAudioTranscriptDeltaEvent #### type object #### description Emitted when there is a partial transcript of audio. #### properties ##### type ###### type string ###### description The type of the event. Always `response.audio.transcript.delta`. ###### enum - response.audio.transcript.delta ###### x-stainless-const true ##### delta ###### type string ###### description The partial transcript of the audio response. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - response_id - delta - sequence_number #### x-oaiMeta ##### name response.audio.transcript.delta ##### group responses ##### example { "type": "response.audio.transcript.delta", "response_id": "resp_123", "delta": " ... partial transcript ... ", "sequence_number": 1 } ### ResponseAudioTranscriptDoneEvent #### type object #### description Emitted when the full audio transcript is completed. #### properties ##### type ###### type string ###### description The type of the event. Always `response.audio.transcript.done`. ###### enum - response.audio.transcript.done ###### x-stainless-const true ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - response_id - sequence_number #### x-oaiMeta ##### name response.audio.transcript.done ##### group responses ##### example { "type": "response.audio.transcript.done", "response_id": "resp_123", "sequence_number": 1 } ### ResponseCodeInterpreterCallCodeDeltaEvent #### type object #### description Emitted when a partial code snippet is streamed by the code interpreter. #### properties ##### type ###### type string ###### description The type of the event. Always `response.code_interpreter_call_code.delta`. ###### enum - response.code_interpreter_call_code.delta ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item in the response for which the code is being streamed. ##### item_id ###### type string ###### description The unique identifier of the code interpreter tool call item. ##### delta ###### type string ###### description The partial code snippet being streamed by the code interpreter. ##### sequence_number ###### type integer ###### description The sequence number of this event, used to order streaming events. #### required - type - output_index - item_id - delta - sequence_number #### x-oaiMeta ##### name response.code_interpreter_call_code.delta ##### group responses ##### example { "type": "response.code_interpreter_call_code.delta", "output_index": 0, "item_id": "ci_12345", "delta": "print('Hello, world')", "sequence_number": 1 } ### ResponseCodeInterpreterCallCodeDoneEvent #### type object #### description Emitted when the code snippet is finalized by the code interpreter. #### properties ##### type ###### type string ###### description The type of the event. Always `response.code_interpreter_call_code.done`. ###### enum - response.code_interpreter_call_code.done ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item in the response for which the code is finalized. ##### item_id ###### type string ###### description The unique identifier of the code interpreter tool call item. ##### code ###### type string ###### description The final code snippet output by the code interpreter. ##### sequence_number ###### type integer ###### description The sequence number of this event, used to order streaming events. #### required - type - output_index - item_id - code - sequence_number #### x-oaiMeta ##### name response.code_interpreter_call_code.done ##### group responses ##### example { "type": "response.code_interpreter_call_code.done", "output_index": 3, "item_id": "ci_12345", "code": "print('done')", "sequence_number": 1 } ### ResponseCodeInterpreterCallCompletedEvent #### type object #### description Emitted when the code interpreter call is completed. #### properties ##### type ###### type string ###### description The type of the event. Always `response.code_interpreter_call.completed`. ###### enum - response.code_interpreter_call.completed ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item in the response for which the code interpreter call is completed. ##### item_id ###### type string ###### description The unique identifier of the code interpreter tool call item. ##### sequence_number ###### type integer ###### description The sequence number of this event, used to order streaming events. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.code_interpreter_call.completed ##### group responses ##### example { "type": "response.code_interpreter_call.completed", "output_index": 5, "item_id": "ci_12345", "sequence_number": 1 } ### ResponseCodeInterpreterCallInProgressEvent #### type object #### description Emitted when a code interpreter call is in progress. #### properties ##### type ###### type string ###### description The type of the event. Always `response.code_interpreter_call.in_progress`. ###### enum - response.code_interpreter_call.in_progress ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item in the response for which the code interpreter call is in progress. ##### item_id ###### type string ###### description The unique identifier of the code interpreter tool call item. ##### sequence_number ###### type integer ###### description The sequence number of this event, used to order streaming events. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.code_interpreter_call.in_progress ##### group responses ##### example { "type": "response.code_interpreter_call.in_progress", "output_index": 0, "item_id": "ci_12345", "sequence_number": 1 } ### ResponseCodeInterpreterCallInterpretingEvent #### type object #### description Emitted when the code interpreter is actively interpreting the code snippet. #### properties ##### type ###### type string ###### description The type of the event. Always `response.code_interpreter_call.interpreting`. ###### enum - response.code_interpreter_call.interpreting ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item in the response for which the code interpreter is interpreting code. ##### item_id ###### type string ###### description The unique identifier of the code interpreter tool call item. ##### sequence_number ###### type integer ###### description The sequence number of this event, used to order streaming events. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.code_interpreter_call.interpreting ##### group responses ##### example { "type": "response.code_interpreter_call.interpreting", "output_index": 4, "item_id": "ci_12345", "sequence_number": 1 } ### ResponseCompletedEvent #### type object #### description Emitted when the model response is complete. #### properties ##### type ###### type string ###### description The type of the event. Always `response.completed`. ###### enum - response.completed ###### x-stainless-const true ##### response ###### $ref #/components/schemas/Response ###### description Properties of the completed response. ##### sequence_number ###### type integer ###### description The sequence number for this event. #### required - type - response - sequence_number #### x-oaiMeta ##### name response.completed ##### group responses ##### example { "type": "response.completed", "response": { "id": "resp_123", "object": "response", "created_at": 1740855869, "status": "completed", "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": {} }, "sequence_number": 1 } ### ResponseContentPartAddedEvent #### type object #### description Emitted when a new content part is added. #### properties ##### type ###### type string ###### description The type of the event. Always `response.content_part.added`. ###### enum - response.content_part.added ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the output item that the content part was added to. ##### output_index ###### type integer ###### description The index of the output item that the content part was added to. ##### content_index ###### type integer ###### description The index of the content part that was added. ##### part ###### $ref #/components/schemas/OutputContent ###### description The content part that was added. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - content_index - part - sequence_number #### x-oaiMeta ##### name response.content_part.added ##### group responses ##### example { "type": "response.content_part.added", "item_id": "msg_123", "output_index": 0, "content_index": 0, "part": { "type": "output_text", "text": "", "annotations": [] }, "sequence_number": 1 } ### ResponseContentPartDoneEvent #### type object #### description Emitted when a content part is done. #### properties ##### type ###### type string ###### description The type of the event. Always `response.content_part.done`. ###### enum - response.content_part.done ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the output item that the content part was added to. ##### output_index ###### type integer ###### description The index of the output item that the content part was added to. ##### content_index ###### type integer ###### description The index of the content part that is done. ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### part ###### $ref #/components/schemas/OutputContent ###### description The content part that is done. #### required - type - item_id - output_index - content_index - part - sequence_number #### x-oaiMeta ##### name response.content_part.done ##### group responses ##### example { "type": "response.content_part.done", "item_id": "msg_123", "output_index": 0, "content_index": 0, "sequence_number": 1, "part": { "type": "output_text", "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", "annotations": [] } } ### ResponseCreatedEvent #### type object #### description An event that is emitted when a response is created. #### properties ##### type ###### type string ###### description The type of the event. Always `response.created`. ###### enum - response.created ###### x-stainless-const true ##### response ###### $ref #/components/schemas/Response ###### description The response that was created. ##### sequence_number ###### type integer ###### description The sequence number for this event. #### required - type - response - sequence_number #### x-oaiMeta ##### name response.created ##### group responses ##### example { "type": "response.created", "response": { "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", "object": "response", "created_at": 1741487325, "status": "in_progress", "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": {} }, "sequence_number": 1 } ### ResponseCustomToolCallInputDeltaEvent #### title ResponseCustomToolCallInputDelta #### type object #### description Event representing a delta (partial update) to the input of a custom tool call. #### properties ##### type ###### type string ###### enum - response.custom_tool_call_input.delta ###### description The event type identifier. ###### x-stainless-const true ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### output_index ###### type integer ###### description The index of the output this delta applies to. ##### item_id ###### type string ###### description Unique identifier for the API item associated with this event. ##### delta ###### type string ###### description The incremental input data (delta) for the custom tool call. #### required - type - output_index - item_id - delta - sequence_number #### x-oaiMeta ##### name response.custom_tool_call_input.delta ##### group responses ##### example { "type": "response.custom_tool_call_input.delta", "output_index": 0, "item_id": "ctc_1234567890abcdef", "delta": "partial input text" } ### ResponseCustomToolCallInputDoneEvent #### title ResponseCustomToolCallInputDone #### type object #### description Event indicating that input for a custom tool call is complete. #### properties ##### type ###### type string ###### enum - response.custom_tool_call_input.done ###### description The event type identifier. ###### x-stainless-const true ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### output_index ###### type integer ###### description The index of the output this event applies to. ##### item_id ###### type string ###### description Unique identifier for the API item associated with this event. ##### input ###### type string ###### description The complete input data for the custom tool call. #### required - type - output_index - item_id - input - sequence_number #### x-oaiMeta ##### name response.custom_tool_call_input.done ##### group responses ##### example { "type": "response.custom_tool_call_input.done", "output_index": 0, "item_id": "ctc_1234567890abcdef", "input": "final complete input text" } ### ResponseError #### 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 ##### message ###### type string ###### description The error message. ##### param ###### type string ###### description The error parameter. ###### nullable true ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - code - message - param - sequence_number #### x-oaiMeta ##### name error ##### group responses ##### example { "type": "error", "code": "ERR_SOMETHING", "message": "Something went wrong", "param": null, "sequence_number": 1 } ### ResponseFailedEvent #### type object #### description An event that is emitted when a response fails. #### properties ##### type ###### type string ###### description The type of the event. Always `response.failed`. ###### enum - response.failed ###### x-stainless-const true ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### response ###### $ref #/components/schemas/Response ###### description The response that failed. #### required - type - response - sequence_number #### x-oaiMeta ##### name response.failed ##### group responses ##### example { "type": "response.failed", "response": { "id": "resp_123", "object": "response", "created_at": 1740855869, "status": "failed", "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 type of the event. Always `response.file_search_call.completed`. ###### enum - response.file_search_call.completed ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item that the file search call is initiated. ##### item_id ###### type string ###### description The ID of the output item that the file search call is initiated. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.file_search_call.completed ##### group responses ##### example { "type": "response.file_search_call.completed", "output_index": 0, "item_id": "fs_123", "sequence_number": 1 } ### ResponseFileSearchCallInProgressEvent #### type object #### description Emitted when a file search call is initiated. #### properties ##### type ###### type string ###### description The type of the event. Always `response.file_search_call.in_progress`. ###### enum - response.file_search_call.in_progress ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item that the file search call is initiated. ##### item_id ###### type string ###### description The ID of the output item that the file search call is initiated. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.file_search_call.in_progress ##### group responses ##### example { "type": "response.file_search_call.in_progress", "output_index": 0, "item_id": "fs_123", "sequence_number": 1 } ### 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 - response.file_search_call.searching ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item that the file search call is searching. ##### item_id ###### type string ###### description The ID of the output item that the file search call is initiated. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.file_search_call.searching ##### group responses ##### example { "type": "response.file_search_call.searching", "output_index": 0, "item_id": "fs_123", "sequence_number": 1 } ### ResponseFormatJsonObject #### type object #### title JSON object #### description JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. #### properties ##### type ###### type string ###### description The type of response format being defined. Always `json_object`. ###### enum - json_object ###### x-stainless-const true #### required - type ### ResponseFormatJsonSchema #### type object #### title JSON schema #### description JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://platform.openai.com/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 ##### json_schema ###### type object ###### title JSON schema ###### description Structured Outputs configuration options, including a JSON Schema. ###### 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](https://platform.openai.com/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 ### ResponseFormatTextGrammar #### type object #### title Text grammar #### description A custom grammar for the model to follow when generating text. Learn more in the [custom grammars guide](https://platform.openai.com/docs/guides/custom-grammars). #### properties ##### type ###### type string ###### description The type of response format being defined. Always `grammar`. ###### enum - grammar ###### x-stainless-const true ##### grammar ###### type string ###### description The custom grammar for the model to follow. #### required - type - grammar ### ResponseFormatTextPython #### type object #### title Python grammar #### description Configure the model to generate valid Python code. See the [custom grammars guide](https://platform.openai.com/docs/guides/custom-grammars) for more details. #### properties ##### type ###### type string ###### description The type of response format being defined. Always `python`. ###### enum - python ###### 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 The type of the event. Always `response.function_call_arguments.delta`. ###### enum - response.function_call_arguments.delta ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the output item that the function-call arguments delta is added to. ##### output_index ###### type integer ###### description The index of the output item that the function-call arguments delta is added to. ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### delta ###### type string ###### description The function-call arguments delta that is added. #### required - type - item_id - output_index - delta - sequence_number #### x-oaiMeta ##### name response.function_call_arguments.delta ##### group responses ##### example { "type": "response.function_call_arguments.delta", "item_id": "item-abc", "output_index": 0, "delta": "{ \"arg\":" "sequence_number": 1 } ### 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. ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### arguments ###### type string ###### description The function-call arguments. #### required - type - item_id - output_index - arguments - sequence_number #### x-oaiMeta ##### name response.function_call_arguments.done ##### group responses ##### example { "type": "response.function_call_arguments.done", "item_id": "item-abc", "output_index": 1, "arguments": "{ \"arg\": 123 }", "sequence_number": 1 } ### ResponseImageGenCallCompletedEvent #### type object #### title ResponseImageGenCallCompletedEvent #### description Emitted when an image generation tool call has completed and the final image is available. #### properties ##### type ###### type string ###### enum - response.image_generation_call.completed ###### description The type of the event. Always 'response.image_generation_call.completed'. ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item in the response's output array. ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### item_id ###### type string ###### description The unique identifier of the image generation item being processed. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.image_generation_call.completed ##### group responses ##### example { "type": "response.image_generation_call.completed", "output_index": 0, "item_id": "item-123", "sequence_number": 1 } ### ResponseImageGenCallGeneratingEvent #### type object #### title ResponseImageGenCallGeneratingEvent #### description Emitted when an image generation tool call is actively generating an image (intermediate state). #### properties ##### type ###### type string ###### enum - response.image_generation_call.generating ###### description The type of the event. Always 'response.image_generation_call.generating'. ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item in the response's output array. ##### item_id ###### type string ###### description The unique identifier of the image generation item being processed. ##### sequence_number ###### type integer ###### description The sequence number of the image generation item being processed. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.image_generation_call.generating ##### group responses ##### example { "type": "response.image_generation_call.generating", "output_index": 0, "item_id": "item-123", "sequence_number": 0 } ### ResponseImageGenCallInProgressEvent #### type object #### title ResponseImageGenCallInProgressEvent #### description Emitted when an image generation tool call is in progress. #### properties ##### type ###### type string ###### enum - response.image_generation_call.in_progress ###### description The type of the event. Always 'response.image_generation_call.in_progress'. ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item in the response's output array. ##### item_id ###### type string ###### description The unique identifier of the image generation item being processed. ##### sequence_number ###### type integer ###### description The sequence number of the image generation item being processed. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.image_generation_call.in_progress ##### group responses ##### example { "type": "response.image_generation_call.in_progress", "output_index": 0, "item_id": "item-123", "sequence_number": 0 } ### ResponseImageGenCallPartialImageEvent #### type object #### title ResponseImageGenCallPartialImageEvent #### description Emitted when a partial image is available during image generation streaming. #### properties ##### type ###### type string ###### enum - response.image_generation_call.partial_image ###### description The type of the event. Always 'response.image_generation_call.partial_image'. ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item in the response's output array. ##### item_id ###### type string ###### description The unique identifier of the image generation item being processed. ##### sequence_number ###### type integer ###### description The sequence number of the image generation item being processed. ##### partial_image_index ###### type integer ###### description 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). ##### partial_image_b64 ###### type string ###### description Base64-encoded partial image data, suitable for rendering as an image. #### required - type - output_index - item_id - sequence_number - partial_image_index - partial_image_b64 #### x-oaiMeta ##### name response.image_generation_call.partial_image ##### group responses ##### example { "type": "response.image_generation_call.partial_image", "output_index": 0, "item_id": "item-123", "sequence_number": 0, "partial_image_index": 0, "partial_image_b64": "..." } ### 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 The response that is in progress. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - response - sequence_number #### x-oaiMeta ##### name response.in_progress ##### group responses ##### example { "type": "response.in_progress", "response": { "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c", "object": "response", "created_at": 1741487325, "status": "in_progress", "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": {} }, "sequence_number": 1 } ### ResponseIncompleteEvent #### type object #### description An event that is emitted when a response finishes as incomplete. #### properties ##### type ###### type string ###### description 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. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - response - sequence_number #### x-oaiMeta ##### name response.incomplete ##### group responses ##### example { "type": "response.incomplete", "response": { "id": "resp_123", "object": "response", "created_at": 1740855869, "status": "incomplete", "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": {} }, "sequence_number": 1 } ### ResponseItemList #### type object #### description A list of Response items. #### properties ##### object ###### description The type of object returned, must be `list`. ###### x-stainless-const true ###### const list ##### data ###### type array ###### description A list of items used to generate this response. ###### items ####### $ref #/components/schemas/ItemResource ##### has_more ###### type boolean ###### description Whether there are more items available. ##### first_id ###### type string ###### description The ID of the first item in the list. ##### last_id ###### type string ###### description The ID of the last item in the list. #### required - object - data - has_more - first_id - last_id #### x-oaiMeta ##### name The input item list ##### group responses ##### example { "object": "list", "data": [ { "id": "msg_abc123", "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "Tell me a three sentence bedtime story about a unicorn." } ] } ], "first_id": "msg_abc123", "last_id": "msg_abc123", "has_more": false } ### ResponseLogProb #### type object #### description A logprob is the logarithmic probability that the model assigns to producing a particular token at a given position in the sequence. Less-negative (higher) logprob values indicate greater model confidence in that token choice. #### properties ##### token ###### description A possible text token. ###### type string ##### logprob ###### description The log probability of this token. ###### type number ##### top_logprobs ###### description The log probability of the top 20 most likely tokens. ###### type array ###### items ####### type object ####### properties ######## token ######### description A possible text token. ######### type string ######## logprob ######### description The log probability of this token. ######### type number #### required - token - logprob ### ResponseMCPCallArgumentsDeltaEvent #### type object #### title ResponseMCPCallArgumentsDeltaEvent #### description Emitted when there is a delta (partial update) to the arguments of an MCP tool call. #### properties ##### type ###### type string ###### enum - response.mcp_call_arguments.delta ###### description The type of the event. Always 'response.mcp_call_arguments.delta'. ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item in the response's output array. ##### item_id ###### type string ###### description The unique identifier of the MCP tool call item being processed. ##### delta ###### type string ###### description A JSON string containing the partial update to the arguments for the MCP tool call. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - output_index - item_id - delta - sequence_number #### x-oaiMeta ##### name response.mcp_call_arguments.delta ##### group responses ##### example { "type": "response.mcp_call_arguments.delta", "output_index": 0, "item_id": "item-abc", "delta": "{", "sequence_number": 1 } ### ResponseMCPCallArgumentsDoneEvent #### type object #### title ResponseMCPCallArgumentsDoneEvent #### description Emitted when the arguments for an MCP tool call are finalized. #### properties ##### type ###### type string ###### enum - response.mcp_call_arguments.done ###### description The type of the event. Always 'response.mcp_call_arguments.done'. ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item in the response's output array. ##### item_id ###### type string ###### description The unique identifier of the MCP tool call item being processed. ##### arguments ###### type string ###### description A JSON string containing the finalized arguments for the MCP tool call. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - output_index - item_id - arguments - sequence_number #### x-oaiMeta ##### name response.mcp_call_arguments.done ##### group responses ##### example { "type": "response.mcp_call_arguments.done", "output_index": 0, "item_id": "item-abc", "arguments": "{\"arg1\": \"value1\", \"arg2\": \"value2\"}", "sequence_number": 1 } ### ResponseMCPCallCompletedEvent #### type object #### title ResponseMCPCallCompletedEvent #### description Emitted when an MCP tool call has completed successfully. #### properties ##### type ###### type string ###### enum - response.mcp_call.completed ###### description The type of the event. Always 'response.mcp_call.completed'. ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the MCP tool call item that completed. ##### output_index ###### type integer ###### description The index of the output item that completed. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - sequence_number #### x-oaiMeta ##### name response.mcp_call.completed ##### group responses ##### example { "type": "response.mcp_call.completed", "sequence_number": 1, "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90", "output_index": 0 } ### ResponseMCPCallFailedEvent #### type object #### title ResponseMCPCallFailedEvent #### description Emitted when an MCP tool call has failed. #### properties ##### type ###### type string ###### enum - response.mcp_call.failed ###### description The type of the event. Always 'response.mcp_call.failed'. ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the MCP tool call item that failed. ##### output_index ###### type integer ###### description The index of the output item that failed. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - sequence_number #### x-oaiMeta ##### name response.mcp_call.failed ##### group responses ##### example { "type": "response.mcp_call.failed", "sequence_number": 1, "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90", "output_index": 0 } ### ResponseMCPCallInProgressEvent #### type object #### title ResponseMCPCallInProgressEvent #### description Emitted when an MCP tool call is in progress. #### properties ##### type ###### type string ###### enum - response.mcp_call.in_progress ###### description The type of the event. Always 'response.mcp_call.in_progress'. ###### x-stainless-const true ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### output_index ###### type integer ###### description The index of the output item in the response's output array. ##### item_id ###### type string ###### description The unique identifier of the MCP tool call item being processed. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.mcp_call.in_progress ##### group responses ##### example { "type": "response.mcp_call.in_progress", "sequence_number": 1, "output_index": 0, "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90" } ### ResponseMCPListToolsCompletedEvent #### type object #### title ResponseMCPListToolsCompletedEvent #### description Emitted when the list of available MCP tools has been successfully retrieved. #### properties ##### type ###### type string ###### enum - response.mcp_list_tools.completed ###### description The type of the event. Always 'response.mcp_list_tools.completed'. ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the MCP tool call item that produced this output. ##### output_index ###### type integer ###### description The index of the output item that was processed. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - sequence_number #### x-oaiMeta ##### name response.mcp_list_tools.completed ##### group responses ##### example { "type": "response.mcp_list_tools.completed", "sequence_number": 1, "output_index": 0, "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" } ### ResponseMCPListToolsFailedEvent #### type object #### title ResponseMCPListToolsFailedEvent #### description Emitted when the attempt to list available MCP tools has failed. #### properties ##### type ###### type string ###### enum - response.mcp_list_tools.failed ###### description The type of the event. Always 'response.mcp_list_tools.failed'. ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the MCP tool call item that failed. ##### output_index ###### type integer ###### description The index of the output item that failed. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - sequence_number #### x-oaiMeta ##### name response.mcp_list_tools.failed ##### group responses ##### example { "type": "response.mcp_list_tools.failed", "sequence_number": 1, "output_index": 0, "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" } ### ResponseMCPListToolsInProgressEvent #### type object #### title ResponseMCPListToolsInProgressEvent #### description Emitted when the system is in the process of retrieving the list of available MCP tools. #### properties ##### type ###### type string ###### enum - response.mcp_list_tools.in_progress ###### description The type of the event. Always 'response.mcp_list_tools.in_progress'. ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the MCP tool call item that is being processed. ##### output_index ###### type integer ###### description The index of the output item that is being processed. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - sequence_number #### x-oaiMeta ##### name response.mcp_list_tools.in_progress ##### group responses ##### example { "type": "response.mcp_list_tools.in_progress", "sequence_number": 1, "output_index": 0, "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90" } ### ResponseModalities #### type array #### nullable true #### description Output types that you would like the model to generate. 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](https://platform.openai.com/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 ### ResponseOutputItemAddedEvent #### type object #### description Emitted when a new output item is added. #### properties ##### type ###### type string ###### description The type of the event. Always `response.output_item.added`. ###### enum - response.output_item.added ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item that was added. ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### item ###### $ref #/components/schemas/OutputItem ###### description The output item that was added. #### required - type - output_index - item - sequence_number #### x-oaiMeta ##### name response.output_item.added ##### group responses ##### example { "type": "response.output_item.added", "output_index": 0, "item": { "id": "msg_123", "status": "in_progress", "type": "message", "role": "assistant", "content": [] }, "sequence_number": 1 } ### 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. ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### item ###### $ref #/components/schemas/OutputItem ###### description The output item that was marked done. #### required - type - output_index - item - sequence_number #### x-oaiMeta ##### name response.output_item.done ##### group responses ##### example { "type": "response.output_item.done", "output_index": 0, "item": { "id": "msg_123", "status": "completed", "type": "message", "role": "assistant", "content": [ { "type": "output_text", "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", "annotations": [] } ] }, "sequence_number": 1 } ### ResponseOutputTextAnnotationAddedEvent #### type object #### title ResponseOutputTextAnnotationAddedEvent #### description Emitted when an annotation is added to output text content. #### properties ##### type ###### type string ###### enum - response.output_text.annotation.added ###### description The type of the event. Always 'response.output_text.annotation.added'. ###### x-stainless-const true ##### item_id ###### type string ###### description The unique identifier of the item to which the annotation is being added. ##### output_index ###### type integer ###### description The index of the output item in the response's output array. ##### content_index ###### type integer ###### description The index of the content part within the output item. ##### annotation_index ###### type integer ###### description The index of the annotation within the content part. ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### annotation ###### type object ###### description The annotation object being added. (See annotation schema for details.) #### required - type - item_id - output_index - content_index - annotation_index - annotation - sequence_number #### x-oaiMeta ##### name response.output_text.annotation.added ##### group responses ##### example { "type": "response.output_text.annotation.added", "item_id": "item-abc", "output_index": 0, "content_index": 0, "annotation_index": 0, "annotation": { "type": "text_annotation", "text": "This is a test annotation", "start": 0, "end": 10 }, "sequence_number": 1 } ### ResponsePromptVariables #### type object #### title Prompt Variables #### description Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files. #### x-oaiExpandable true #### x-oaiTypeLabel map #### nullable true #### additionalProperties ##### x-oaiExpandable true ##### x-oaiTypeLabel map ##### anyOf ###### type string ###### $ref #/components/schemas/InputTextContent ###### $ref #/components/schemas/InputImageContent ###### $ref #/components/schemas/InputFileContent ### 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](https://platform.openai.com/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. ###### nullable true ##### model ###### description Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models) to browse and compare available models. ###### $ref #/components/schemas/ModelIdsResponses ##### reasoning ###### $ref #/components/schemas/Reasoning ###### nullable true ##### background ###### type boolean ###### description Whether to run the model response in the background. [Learn more](https://platform.openai.com/docs/guides/background). ###### default false ###### nullable true ##### max_output_tokens ###### description An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). ###### type integer ###### nullable true ##### max_tool_calls ###### description The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored. ###### type integer ###### nullable true ##### text ###### type object ###### description Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) ###### properties ####### format ######## $ref #/components/schemas/TextResponseFormatConfiguration ####### verbosity ######## $ref #/components/schemas/Verbosity ##### tools ###### type array ###### description An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. The two categories of tools you can provide the model are: - **Built-in tools**: Tools that are provided by OpenAI that extend the model's capabilities, like [web search](https://platform.openai.com/docs/guides/tools-web-search) or [file search](https://platform.openai.com/docs/guides/tools-file-search). Learn more about [built-in tools](https://platform.openai.com/docs/guides/tools). - **Function calls (custom tools)**: Functions that are defined by you, enabling the model to call your own code with strongly typed arguments and outputs. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). You can also use custom tools to call your own code. ###### items ####### $ref #/components/schemas/Tool ##### tool_choice ###### description How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools the model can call. ###### anyOf ####### $ref #/components/schemas/ToolChoiceOptions ####### $ref #/components/schemas/ToolChoiceAllowed ####### $ref #/components/schemas/ToolChoiceTypes ####### $ref #/components/schemas/ToolChoiceFunction ####### $ref #/components/schemas/ToolChoiceMCP ####### $ref #/components/schemas/ToolChoiceCustom ##### prompt ###### $ref #/components/schemas/Prompt ##### truncation ###### type string ###### description 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 ### ResponseQueuedEvent #### type object #### title ResponseQueuedEvent #### description Emitted when a response is queued and waiting to be processed. #### properties ##### type ###### type string ###### enum - response.queued ###### description The type of the event. Always 'response.queued'. ###### x-stainless-const true ##### response ###### $ref #/components/schemas/Response ###### description The full response object that is queued. ##### sequence_number ###### type integer ###### description The sequence number for this event. #### required - type - response - sequence_number #### x-oaiMeta ##### name response.queued ##### group responses ##### example { "type": "response.queued", "response": { "id": "res_123", "status": "queued", "created_at": "2021-01-01T00:00:00Z", "updated_at": "2021-01-01T00:00:00Z" }, "sequence_number": 1 } ### ResponseReasoningSummaryPartAddedEvent #### type object #### description Emitted when a new reasoning summary part is added. #### properties ##### type ###### type string ###### description The type of the event. Always `response.reasoning_summary_part.added`. ###### enum - response.reasoning_summary_part.added ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the item this summary part is associated with. ##### output_index ###### type integer ###### description The index of the output item this summary part is associated with. ##### summary_index ###### type integer ###### description The index of the summary part within the reasoning summary. ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### part ###### type object ###### description The summary part that was added. ###### properties ####### type ######## type string ######## description The type of the summary part. Always `summary_text`. ######## enum - summary_text ######## x-stainless-const true ####### text ######## type string ######## description The text of the summary part. ###### required - type - text #### required - type - item_id - output_index - summary_index - part - sequence_number #### x-oaiMeta ##### name response.reasoning_summary_part.added ##### group responses ##### example { "type": "response.reasoning_summary_part.added", "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", "output_index": 0, "summary_index": 0, "part": { "type": "summary_text", "text": "" }, "sequence_number": 1 } ### ResponseReasoningSummaryPartDoneEvent #### type object #### description Emitted when a reasoning summary part is completed. #### properties ##### type ###### type string ###### description The type of the event. Always `response.reasoning_summary_part.done`. ###### enum - response.reasoning_summary_part.done ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the item this summary part is associated with. ##### output_index ###### type integer ###### description The index of the output item this summary part is associated with. ##### summary_index ###### type integer ###### description The index of the summary part within the reasoning summary. ##### sequence_number ###### type integer ###### description The sequence number of this event. ##### part ###### type object ###### description The completed summary part. ###### properties ####### type ######## type string ######## description The type of the summary part. Always `summary_text`. ######## enum - summary_text ######## x-stainless-const true ####### text ######## type string ######## description The text of the summary part. ###### required - type - text #### required - type - item_id - output_index - summary_index - part - sequence_number #### x-oaiMeta ##### name response.reasoning_summary_part.done ##### group responses ##### example { "type": "response.reasoning_summary_part.done", "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", "output_index": 0, "summary_index": 0, "part": { "type": "summary_text", "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!" }, "sequence_number": 1 } ### ResponseReasoningSummaryTextDeltaEvent #### type object #### description Emitted when a delta is added to a reasoning summary text. #### properties ##### type ###### type string ###### description The type of the event. Always `response.reasoning_summary_text.delta`. ###### enum - response.reasoning_summary_text.delta ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the item this summary text delta is associated with. ##### output_index ###### type integer ###### description The index of the output item this summary text delta is associated with. ##### summary_index ###### type integer ###### description The index of the summary part within the reasoning summary. ##### delta ###### type string ###### description The text delta that was added to the summary. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - summary_index - delta - sequence_number #### x-oaiMeta ##### name response.reasoning_summary_text.delta ##### group responses ##### example { "type": "response.reasoning_summary_text.delta", "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", "output_index": 0, "summary_index": 0, "delta": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!", "sequence_number": 1 } ### ResponseReasoningSummaryTextDoneEvent #### type object #### description Emitted when a reasoning summary text is completed. #### properties ##### type ###### type string ###### description The type of the event. Always `response.reasoning_summary_text.done`. ###### enum - response.reasoning_summary_text.done ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the item this summary text is associated with. ##### output_index ###### type integer ###### description The index of the output item this summary text is associated with. ##### summary_index ###### type integer ###### description The index of the summary part within the reasoning summary. ##### text ###### type string ###### description The full text of the completed reasoning summary. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - summary_index - text - sequence_number #### x-oaiMeta ##### name response.reasoning_summary_text.done ##### group responses ##### example { "type": "response.reasoning_summary_text.done", "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476", "output_index": 0, "summary_index": 0, "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!", "sequence_number": 1 } ### ResponseReasoningTextDeltaEvent #### type object #### description Emitted when a delta is added to a reasoning text. #### properties ##### type ###### type string ###### description The type of the event. Always `response.reasoning_text.delta`. ###### enum - response.reasoning_text.delta ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the item this reasoning text delta is associated with. ##### output_index ###### type integer ###### description The index of the output item this reasoning text delta is associated with. ##### content_index ###### type integer ###### description The index of the reasoning content part this delta is associated with. ##### delta ###### type string ###### description The text delta that was added to the reasoning content. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - content_index - delta - sequence_number #### x-oaiMeta ##### name response.reasoning_text.delta ##### group responses ##### example { "type": "response.reasoning_text.delta", "item_id": "rs_123", "output_index": 0, "content_index": 0, "delta": "The", "sequence_number": 1 } ### ResponseReasoningTextDoneEvent #### type object #### description Emitted when a reasoning text is completed. #### properties ##### type ###### type string ###### description The type of the event. Always `response.reasoning_text.done`. ###### enum - response.reasoning_text.done ###### x-stainless-const true ##### item_id ###### type string ###### description The ID of the item this reasoning text is associated with. ##### output_index ###### type integer ###### description The index of the output item this reasoning text is associated with. ##### content_index ###### type integer ###### description The index of the reasoning content part. ##### text ###### type string ###### description The full text of the completed reasoning content. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - content_index - text - sequence_number #### x-oaiMeta ##### name response.reasoning_text.done ##### group responses ##### example { "type": "response.reasoning_text.done", "item_id": "rs_123", "output_index": 0, "content_index": 0, "text": "The user is asking...", "sequence_number": 4 } ### 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. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - content_index - delta - sequence_number #### x-oaiMeta ##### name response.refusal.delta ##### group responses ##### example { "type": "response.refusal.delta", "item_id": "msg_123", "output_index": 0, "content_index": 0, "delta": "refusal text so far", "sequence_number": 1 } ### 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. ##### sequence_number ###### type integer ###### description The sequence number of this event. #### required - type - item_id - output_index - content_index - refusal - sequence_number #### x-oaiMeta ##### name response.refusal.done ##### group responses ##### example { "type": "response.refusal.done", "item_id": "item-abc", "output_index": 1, "content_index": 2, "refusal": "final refusal text", "sequence_number": 1 } ### 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/ResponseReasoningSummaryPartAddedEvent ##### $ref #/components/schemas/ResponseReasoningSummaryPartDoneEvent ##### $ref #/components/schemas/ResponseReasoningSummaryTextDeltaEvent ##### $ref #/components/schemas/ResponseReasoningSummaryTextDoneEvent ##### $ref #/components/schemas/ResponseReasoningTextDeltaEvent ##### $ref #/components/schemas/ResponseReasoningTextDoneEvent ##### $ref #/components/schemas/ResponseRefusalDeltaEvent ##### $ref #/components/schemas/ResponseRefusalDoneEvent ##### $ref #/components/schemas/ResponseTextDeltaEvent ##### $ref #/components/schemas/ResponseTextDoneEvent ##### $ref #/components/schemas/ResponseWebSearchCallCompletedEvent ##### $ref #/components/schemas/ResponseWebSearchCallInProgressEvent ##### $ref #/components/schemas/ResponseWebSearchCallSearchingEvent ##### $ref #/components/schemas/ResponseImageGenCallCompletedEvent ##### $ref #/components/schemas/ResponseImageGenCallGeneratingEvent ##### $ref #/components/schemas/ResponseImageGenCallInProgressEvent ##### $ref #/components/schemas/ResponseImageGenCallPartialImageEvent ##### $ref #/components/schemas/ResponseMCPCallArgumentsDeltaEvent ##### $ref #/components/schemas/ResponseMCPCallArgumentsDoneEvent ##### $ref #/components/schemas/ResponseMCPCallCompletedEvent ##### $ref #/components/schemas/ResponseMCPCallFailedEvent ##### $ref #/components/schemas/ResponseMCPCallInProgressEvent ##### $ref #/components/schemas/ResponseMCPListToolsCompletedEvent ##### $ref #/components/schemas/ResponseMCPListToolsFailedEvent ##### $ref #/components/schemas/ResponseMCPListToolsInProgressEvent ##### $ref #/components/schemas/ResponseOutputTextAnnotationAddedEvent ##### $ref #/components/schemas/ResponseQueuedEvent ##### $ref #/components/schemas/ResponseCustomToolCallInputDeltaEvent ##### $ref #/components/schemas/ResponseCustomToolCallInputDoneEvent #### discriminator ##### propertyName type ### ResponseStreamOptions #### description Options for streaming responses. Only set this when you set `stream: true`. #### type object #### nullable true #### default null #### properties ##### include_obfuscation ###### type boolean ###### description When true, stream obfuscation will be enabled. Stream obfuscation adds random characters to an `obfuscation` field on streaming delta events to normalize payload sizes as a mitigation to certain side-channel attacks. These obfuscation fields are included by default, but add a small amount of overhead to the data stream. You can set `include_obfuscation` to false to optimize for bandwidth if you trust the network links between your application and the OpenAI API. ### 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. ##### sequence_number ###### type integer ###### description The sequence number for this event. ##### logprobs ###### type array ###### description The log probabilities of the tokens in the delta. ###### items ####### $ref #/components/schemas/ResponseLogProb #### required - type - item_id - output_index - content_index - delta - sequence_number - logprobs #### x-oaiMeta ##### name response.output_text.delta ##### group responses ##### example { "type": "response.output_text.delta", "item_id": "msg_123", "output_index": 0, "content_index": 0, "delta": "In", "sequence_number": 1 } ### 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. ##### sequence_number ###### type integer ###### description The sequence number for this event. ##### logprobs ###### type array ###### description The log probabilities of the tokens in the delta. ###### items ####### $ref #/components/schemas/ResponseLogProb #### required - type - item_id - output_index - content_index - text - sequence_number - logprobs #### x-oaiMeta ##### name response.output_text.done ##### group responses ##### example { "type": "response.output_text.done", "item_id": "msg_123", "output_index": 0, "content_index": 0, "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.", "sequence_number": 1 } ### ResponseUsage #### type object #### description Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. #### properties ##### input_tokens ###### type integer ###### description The number of input tokens. ##### input_tokens_details ###### type object ###### description A detailed breakdown of the input tokens. ###### properties ####### cached_tokens ######## type integer ######## description The number of tokens that were retrieved from the cache. [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). ###### required - cached_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 - input_tokens_details - 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 the event. Always `response.web_search_call.completed`. ###### enum - response.web_search_call.completed ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item that the web search call is associated with. ##### item_id ###### type string ###### description Unique ID for the output item associated with the web search call. ##### sequence_number ###### type integer ###### description The sequence number of the web search call being processed. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.web_search_call.completed ##### group responses ##### example { "type": "response.web_search_call.completed", "output_index": 0, "item_id": "ws_123", "sequence_number": 0 } ### ResponseWebSearchCallInProgressEvent #### type object #### description Emitted when a web search call is initiated. #### properties ##### type ###### type string ###### description The type of the event. Always `response.web_search_call.in_progress`. ###### enum - response.web_search_call.in_progress ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item that the web search call is associated with. ##### item_id ###### type string ###### description Unique ID for the output item associated with the web search call. ##### sequence_number ###### type integer ###### description The sequence number of the web search call being processed. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.web_search_call.in_progress ##### group responses ##### example { "type": "response.web_search_call.in_progress", "output_index": 0, "item_id": "ws_123", "sequence_number": 0 } ### ResponseWebSearchCallSearchingEvent #### type object #### description Emitted when a web search call is executing. #### properties ##### type ###### type string ###### description The type of the event. Always `response.web_search_call.searching`. ###### enum - response.web_search_call.searching ###### x-stainless-const true ##### output_index ###### type integer ###### description The index of the output item that the web search call is associated with. ##### item_id ###### type string ###### description Unique ID for the output item associated with the web search call. ##### sequence_number ###### type integer ###### description The sequence number of the web search call being processed. #### required - type - output_index - item_id - sequence_number #### x-oaiMeta ##### name response.web_search_call.searching ##### group responses ##### example { "type": "response.web_search_call.searching", "output_index": 0, "item_id": "ws_123", "sequence_number": 0 } ### RunCompletionUsage #### type object #### description Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). #### properties ##### completion_tokens ###### type integer ###### description Number of completion tokens used over the course of the run. ##### prompt_tokens ###### type integer ###### description Number of prompt tokens used over the course of the run. ##### total_tokens ###### type integer ###### description Total number of tokens used (prompt + completion). #### required - prompt_tokens - completion_tokens - total_tokens #### nullable true ### RunGraderRequest #### type object #### title RunGraderRequest #### properties ##### grader ###### type object ###### description The grader used for the fine-tuning job. ###### anyOf ####### $ref #/components/schemas/GraderStringCheck ####### $ref #/components/schemas/GraderTextSimilarity ####### $ref #/components/schemas/GraderPython ####### $ref #/components/schemas/GraderScoreModel ####### $ref #/components/schemas/GraderMulti ###### discriminator ####### propertyName type ##### item ###### type object ###### description The dataset item provided to the grader. This will be used to populate the `item` namespace. See [the guide](https://platform.openai.com/docs/guides/graders) for more details. ##### model_sample ###### type string ###### description The model sample to be evaluated. This value will be used to populate the `sample` namespace. See [the guide](https://platform.openai.com/docs/guides/graders) for more details. The `output_json` variable will be populated if the model sample is a valid JSON string. #### required - grader - model_sample ### RunGraderResponse #### type object #### properties ##### reward ###### type number ##### metadata ###### type object ###### properties ####### name ######## type string ####### type ######## type string ####### errors ######## type object ######## properties ######### formula_parse_error ########## type boolean ######### sample_parse_error ########## type boolean ######### truncated_observation_error ########## type boolean ######### unresponsive_reward_error ########## type boolean ######### invalid_variable_error ########## type boolean ######### other_error ########## type boolean ######### python_grader_server_error ########## type boolean ######### python_grader_server_error_type ########## type string ########## nullable true ######### python_grader_runtime_error ########## type boolean ######### python_grader_runtime_error_details ########## type string ########## nullable true ######### model_grader_server_error ########## type boolean ######### model_grader_refusal_error ########## type boolean ######### model_grader_parse_error ########## type boolean ######### model_grader_server_error_details ########## type string ########## nullable true ######## required - formula_parse_error - sample_parse_error - truncated_observation_error - unresponsive_reward_error - invalid_variable_error - other_error - python_grader_server_error - python_grader_server_error_type - python_grader_runtime_error - python_grader_runtime_error_details - model_grader_server_error - model_grader_refusal_error - model_grader_parse_error - model_grader_server_error_details ####### execution_time ######## type number ####### scores ######## type object ######## additionalProperties ####### token_usage ######## type integer ######## nullable true ####### sampled_model_name ######## type string ######## nullable true ###### required - name - type - errors - execution_time - scores - token_usage - sampled_model_name ##### sub_rewards ###### type object ###### additionalProperties ##### model_grader_token_usage_per_model ###### type object ###### additionalProperties #### required - reward - metadata - sub_rewards - model_grader_token_usage_per_model ### RunObject #### type object #### title A run on a thread #### description Represents an execution run on a [thread](https://platform.openai.com/docs/api-reference/threads). #### properties ##### id ###### description The identifier, which can be referenced in API endpoints. ###### type string ##### object ###### description The object type, which is always `thread.run`. ###### type string ###### enum - thread.run ###### x-stainless-const true ##### created_at ###### description The Unix timestamp (in seconds) for when the run was created. ###### type integer ##### thread_id ###### description The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was executed on as a part of this run. ###### type string ##### assistant_id ###### description The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for execution of this run. ###### type string ##### status ###### $ref #/components/schemas/RunStatus ##### required_action ###### type object ###### description Details on the action required to continue the run. Will be `null` if no action is required. ###### nullable true ###### properties ####### type ######## description For now, this is always `submit_tool_outputs`. ######## type string ######## enum - submit_tool_outputs ######## x-stainless-const true ####### submit_tool_outputs ######## type object ######## description Details on the tool outputs needed for this run to continue. ######## properties ######### tool_calls ########## type array ########## description A list of the relevant tool calls. ########## items ########### $ref #/components/schemas/RunToolCallObject ######## required - tool_calls ###### required - type - submit_tool_outputs ##### last_error ###### type object ###### description The last error associated with this run. Will be `null` if there are no errors. ###### nullable true ###### properties ####### code ######## type string ######## description One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. ######## enum - server_error - rate_limit_exceeded - invalid_prompt ####### message ######## type string ######## description A human-readable description of the error. ###### required - code - message ##### expires_at ###### description The Unix timestamp (in seconds) for when the run will expire. ###### type integer ###### nullable true ##### started_at ###### description The Unix timestamp (in seconds) for when the run was started. ###### type integer ###### nullable true ##### cancelled_at ###### description The Unix timestamp (in seconds) for when the run was cancelled. ###### type integer ###### nullable true ##### failed_at ###### description The Unix timestamp (in seconds) for when the run failed. ###### type integer ###### nullable true ##### completed_at ###### description The Unix timestamp (in seconds) for when the run was completed. ###### type integer ###### nullable true ##### incomplete_details ###### description Details on why the run is incomplete. Will be `null` if the run is not incomplete. ###### type object ###### nullable true ###### properties ####### reason ######## description The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. ######## type string ######## enum - max_completion_tokens - max_prompt_tokens ##### model ###### description The model that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. ###### type string ##### instructions ###### description The instructions that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. ###### type string ##### tools ###### description The list of tools that the [assistant](https://platform.openai.com/docs/api-reference/assistants) used for this run. ###### default ###### type array ###### maxItems 20 ###### items ####### $ref #/components/schemas/AssistantTool ##### metadata ###### $ref #/components/schemas/Metadata ##### usage ###### $ref #/components/schemas/RunCompletionUsage ##### temperature ###### description The sampling temperature used for this run. If not set, defaults to 1. ###### type number ###### nullable true ##### top_p ###### description The nucleus sampling value used for this run. If not set, defaults to 1. ###### type number ###### nullable true ##### max_prompt_tokens ###### type integer ###### nullable true ###### description The maximum number of prompt tokens specified to have been used over the course of the run. ###### minimum 256 ##### max_completion_tokens ###### type integer ###### nullable true ###### description The maximum number of completion tokens specified to have been used over the course of the run. ###### 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 - id - object - created_at - thread_id - assistant_id - status - required_action - last_error - expires_at - started_at - cancelled_at - failed_at - completed_at - model - instructions - tools - metadata - usage - incomplete_details - max_prompt_tokens - max_completion_tokens - truncation_strategy - tool_choice - parallel_tool_calls - response_format #### x-oaiMeta ##### name The run object ##### beta true ##### example { "id": "run_abc123", "object": "thread.run", "created_at": 1698107661, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", "status": "completed", "started_at": 1699073476, "expires_at": null, "cancelled_at": null, "failed_at": null, "completed_at": 1699073498, "last_error": null, "model": "gpt-4o", "instructions": null, "tools": [{"type": "file_search"}, {"type": "code_interpreter"}], "metadata": {}, "incomplete_details": null, "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 } ### RunStepCompletionUsage #### type object #### description Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. #### properties ##### completion_tokens ###### type integer ###### description Number of completion tokens used over the course of the run step. ##### prompt_tokens ###### type integer ###### description Number of prompt tokens used over the course of the run step. ##### total_tokens ###### type integer ###### description Total number of tokens used (prompt + completion). #### required - prompt_tokens - completion_tokens - total_tokens #### nullable true ### RunStepDeltaObject #### type object #### title Run step delta object #### description Represents a run step delta i.e. any changed fields on a run step during streaming. #### properties ##### id ###### description The identifier of the run step, which can be referenced in API endpoints. ###### type string ##### object ###### description The object type, which is always `thread.run.step.delta`. ###### type string ###### enum - thread.run.step.delta ###### x-stainless-const true ##### delta ###### $ref #/components/schemas/RunStepDeltaObjectDelta #### required - id - object - delta #### x-oaiMeta ##### name The run step delta object ##### beta true ##### example { "id": "step_123", "object": "thread.run.step.delta", "delta": { "step_details": { "type": "tool_calls", "tool_calls": [ { "index": 0, "id": "call_123", "type": "code_interpreter", "code_interpreter": { "input": "", "outputs": [] } } ] } } } ### RunStepDeltaStepDetailsMessageCreationObject #### title Message creation #### type object #### description Details of the message creation by the run step. #### properties ##### type ###### description Always `message_creation`. ###### type string ###### enum - message_creation ###### x-stainless-const true ##### message_creation ###### type object ###### properties ####### message_id ######## type string ######## description The ID of the message that was created by this run step. #### required - type ### RunStepDeltaStepDetailsToolCallsCodeObject #### title Code interpreter tool call #### type object #### description Details of the Code Interpreter tool call the run step was involved in. #### properties ##### index ###### type integer ###### description The index of the tool call in the tool calls array. ##### id ###### type string ###### description The ID of the tool call. ##### type ###### type string ###### description The type of tool call. This is always going to be `code_interpreter` for this type of tool call. ###### enum - code_interpreter ###### x-stainless-const true ##### code_interpreter ###### type object ###### description The Code Interpreter tool call definition. ###### properties ####### input ######## type string ######## description The input to the Code Interpreter tool call. ####### outputs ######## type array ######## description The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. ######## items ######### type object ######### anyOf ########## $ref #/components/schemas/RunStepDeltaStepDetailsToolCallsCodeOutputLogsObject ########## $ref #/components/schemas/RunStepDeltaStepDetailsToolCallsCodeOutputImageObject ######### discriminator ########## propertyName type #### required - index - type ### RunStepDeltaStepDetailsToolCallsCodeOutputImageObject #### title Code interpreter image output #### type object #### properties ##### index ###### type integer ###### description The index of the output in the outputs array. ##### type ###### description Always `image`. ###### type string ###### enum - image ###### x-stainless-const true ##### image ###### type object ###### properties ####### file_id ######## description The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. ######## type string #### required - index - type ### RunStepDeltaStepDetailsToolCallsCodeOutputLogsObject #### title Code interpreter log output #### type object #### description Text output from the Code Interpreter tool call as part of a run step. #### properties ##### index ###### type integer ###### description The index of the output in the outputs array. ##### type ###### description Always `logs`. ###### type string ###### enum - logs ###### x-stainless-const true ##### logs ###### type string ###### description The text output from the Code Interpreter tool call. #### required - index - type ### RunStepDeltaStepDetailsToolCallsFileSearchObject #### title File search tool call #### type object #### properties ##### index ###### type integer ###### description The index of the tool call in the tool calls array. ##### id ###### type string ###### description The ID of the tool call object. ##### type ###### type string ###### description The type of tool call. This is always going to be `file_search` for this type of tool call. ###### enum - file_search ###### x-stainless-const true ##### file_search ###### type object ###### description For now, this is always going to be an empty object. ###### x-oaiTypeLabel map #### required - index - type - file_search ### RunStepDeltaStepDetailsToolCallsFunctionObject #### type object #### title Function tool call #### properties ##### index ###### type integer ###### description The index of the tool call in the tool calls array. ##### id ###### type string ###### description The ID of the tool call object. ##### type ###### type string ###### description The type of tool call. This is always going to be `function` for this type of tool call. ###### enum - function ###### x-stainless-const true ##### function ###### type object ###### description The definition of the function that was called. ###### properties ####### name ######## type string ######## description The name of the function. ####### arguments ######## type string ######## description The arguments passed to the function. ####### output ######## type string ######## description The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. ######## nullable true #### required - index - type ### RunStepDeltaStepDetailsToolCallsObject #### title Tool calls #### type object #### description Details of the tool call. #### properties ##### type ###### description Always `tool_calls`. ###### type string ###### enum - tool_calls ###### x-stainless-const true ##### tool_calls ###### type array ###### description An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. ###### items ####### $ref #/components/schemas/RunStepDeltaStepDetailsToolCall #### required - type ### RunStepDetailsMessageCreationObject #### title Message creation #### type object #### description Details of the message creation by the run step. #### properties ##### type ###### description Always `message_creation`. ###### type string ###### enum - message_creation ###### x-stainless-const true ##### message_creation ###### type object ###### properties ####### message_id ######## type string ######## description The ID of the message that was created by this run step. ###### required - message_id #### required - type - message_creation ### RunStepDetailsToolCallsCodeObject #### title Code Interpreter tool call #### type object #### description Details of the Code Interpreter tool call the run step was involved in. #### properties ##### id ###### type string ###### description The ID of the tool call. ##### type ###### type string ###### description The type of tool call. This is always going to be `code_interpreter` for this type of tool call. ###### enum - code_interpreter ###### x-stainless-const true ##### code_interpreter ###### type object ###### description The Code Interpreter tool call definition. ###### required - input - outputs ###### properties ####### input ######## type string ######## description The input to the Code Interpreter tool call. ####### outputs ######## type array ######## description The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. ######## items ######### type object ######### anyOf ########## $ref #/components/schemas/RunStepDetailsToolCallsCodeOutputLogsObject ########## $ref #/components/schemas/RunStepDetailsToolCallsCodeOutputImageObject ######### discriminator ########## propertyName type #### required - id - type - code_interpreter ### RunStepDetailsToolCallsCodeOutputImageObject #### title Code Interpreter image output #### type object #### properties ##### type ###### description Always `image`. ###### type string ###### enum - image ###### x-stainless-const true ##### image ###### type object ###### properties ####### file_id ######## description The [file](https://platform.openai.com/docs/api-reference/files) ID of the image. ######## type string ###### required - file_id #### required - type - image #### x-stainless-naming ##### java ###### type_name ImageOutput ##### kotlin ###### type_name ImageOutput ### RunStepDetailsToolCallsCodeOutputLogsObject #### title Code Interpreter log output #### type object #### description Text output from the Code Interpreter tool call as part of a run step. #### properties ##### type ###### description Always `logs`. ###### type string ###### enum - logs ###### x-stainless-const true ##### logs ###### type string ###### description The text output from the Code Interpreter tool call. #### required - type - logs #### x-stainless-naming ##### java ###### type_name LogsOutput ##### kotlin ###### type_name LogsOutput ### RunStepDetailsToolCallsFileSearchObject #### title File search tool call #### type object #### properties ##### id ###### type string ###### description The ID of the tool call object. ##### type ###### type string ###### description The type of tool call. This is always going to be `file_search` for this type of tool call. ###### enum - file_search ###### x-stainless-const true ##### file_search ###### type object ###### description For now, this is always going to be an empty object. ###### x-oaiTypeLabel map ###### properties ####### ranking_options ######## $ref #/components/schemas/RunStepDetailsToolCallsFileSearchRankingOptionsObject ####### results ######## type array ######## description The results of the file search. ######## items ######### $ref #/components/schemas/RunStepDetailsToolCallsFileSearchResultObject #### required - id - type - file_search ### RunStepDetailsToolCallsFileSearchRankingOptionsObject #### title File search tool call ranking options #### type object #### description The ranking options for the file search. #### 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 - ranker - score_threshold ### RunStepDetailsToolCallsFileSearchResultObject #### title File search tool call result #### type object #### description A result instance of the file search. #### x-oaiTypeLabel map #### properties ##### file_id ###### type string ###### description The ID of the file that result was found in. ##### file_name ###### type string ###### description The name of the file that result was found in. ##### score ###### type number ###### description The score of the result. All values must be a floating point number between 0 and 1. ###### minimum 0 ###### maximum 1 ##### content ###### type array ###### description The content of the result that was found. The content is only included if requested via the include query parameter. ###### items ####### type object ####### properties ######## type ######### type string ######### description The type of the content. ######### enum - text ######### x-stainless-const true ######## text ######### type string ######### description The text content of the file. #### required - file_id - file_name - score ### RunStepDetailsToolCallsFunctionObject #### type object #### title Function tool call #### properties ##### id ###### type string ###### description The ID of the tool call object. ##### type ###### type string ###### description The type of tool call. This is always going to be `function` for this type of tool call. ###### enum - function ###### x-stainless-const true ##### function ###### type object ###### description The definition of the function that was called. ###### properties ####### name ######## type string ######## description The name of the function. ####### arguments ######## type string ######## description The arguments passed to the function. ####### output ######## type string ######## description The output of the function. This will be `null` if the outputs have not been [submitted](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) yet. ######## nullable true ###### required - name - arguments - output #### required - id - type - function ### RunStepDetailsToolCallsObject #### title Tool calls #### type object #### description Details of the tool call. #### properties ##### type ###### description Always `tool_calls`. ###### type string ###### enum - tool_calls ###### x-stainless-const true ##### tool_calls ###### type array ###### description An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. ###### items ####### $ref #/components/schemas/RunStepDetailsToolCall #### required - type - tool_calls ### RunStepObject #### type object #### title Run steps #### description Represents a step in execution of a run. #### properties ##### id ###### description The identifier of the run step, which can be referenced in API endpoints. ###### type string ##### object ###### description The object type, which is always `thread.run.step`. ###### type string ###### enum - thread.run.step ###### x-stainless-const true ##### created_at ###### description The Unix timestamp (in seconds) for when the run step was created. ###### type integer ##### assistant_id ###### description The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) associated with the run step. ###### type string ##### thread_id ###### description The ID of the [thread](https://platform.openai.com/docs/api-reference/threads) that was run. ###### type string ##### run_id ###### description The ID of the [run](https://platform.openai.com/docs/api-reference/runs) that this run step is a part of. ###### type string ##### type ###### description The type of run step, which can be either `message_creation` or `tool_calls`. ###### type string ###### enum - message_creation - tool_calls ##### status ###### description The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. ###### type string ###### enum - in_progress - cancelled - failed - completed - expired ##### step_details ###### type object ###### description The details of the run step. ###### anyOf ####### $ref #/components/schemas/RunStepDetailsMessageCreationObject ####### $ref #/components/schemas/RunStepDetailsToolCallsObject ###### discriminator ####### propertyName type ##### last_error ###### type object ###### description The last error associated with this run step. Will be `null` if there are no errors. ###### nullable true ###### properties ####### code ######## type string ######## description One of `server_error` or `rate_limit_exceeded`. ######## enum - server_error - rate_limit_exceeded ####### message ######## type string ######## description A human-readable description of the error. ###### required - code - message ##### expired_at ###### description The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. ###### type integer ###### nullable true ##### cancelled_at ###### description The Unix timestamp (in seconds) for when the run step was cancelled. ###### type integer ###### nullable true ##### failed_at ###### description The Unix timestamp (in seconds) for when the run step failed. ###### type integer ###### nullable true ##### completed_at ###### description The Unix timestamp (in seconds) for when the run step completed. ###### type integer ###### nullable true ##### metadata ###### $ref #/components/schemas/Metadata ##### usage ###### $ref #/components/schemas/RunStepCompletionUsage #### required - id - object - created_at - assistant_id - thread_id - run_id - type - status - step_details - last_error - expired_at - cancelled_at - failed_at - completed_at - metadata - usage #### x-oaiMeta ##### name The run step object ##### beta true ##### example { "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 } } ### RunStepStreamEvent #### anyOf ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.step.created ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunStepObject ##### required - event - data ##### description Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is created. ##### x-oaiMeta ###### dataDescription `data` is a [run step](/docs/api-reference/run-steps/step-object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.step.in_progress ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunStepObject ##### required - event - data ##### description Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. ##### x-oaiMeta ###### dataDescription `data` is a [run step](/docs/api-reference/run-steps/step-object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.step.delta ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunStepDeltaObject ##### required - event - data ##### description Occurs when parts of a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) are being streamed. ##### x-oaiMeta ###### dataDescription `data` is a [run step delta](/docs/api-reference/assistants-streaming/run-step-delta-object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.step.completed ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunStepObject ##### required - event - data ##### description Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is completed. ##### x-oaiMeta ###### dataDescription `data` is a [run step](/docs/api-reference/run-steps/step-object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.step.failed ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunStepObject ##### required - event - data ##### description Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) fails. ##### x-oaiMeta ###### dataDescription `data` is a [run step](/docs/api-reference/run-steps/step-object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.step.cancelled ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunStepObject ##### required - event - data ##### description Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) is cancelled. ##### x-oaiMeta ###### dataDescription `data` is a [run step](/docs/api-reference/run-steps/step-object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.step.expired ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunStepObject ##### required - event - data ##### description Occurs when a [run step](https://platform.openai.com/docs/api-reference/run-steps/step-object) expires. ##### x-oaiMeta ###### dataDescription `data` is a [run step](/docs/api-reference/run-steps/step-object) #### discriminator ##### propertyName event ### RunStreamEvent #### anyOf ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.created ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunObject ##### required - event - data ##### description Occurs when a new [run](https://platform.openai.com/docs/api-reference/runs/object) is created. ##### x-oaiMeta ###### dataDescription `data` is a [run](/docs/api-reference/runs/object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.queued ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunObject ##### required - event - data ##### description Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `queued` status. ##### x-oaiMeta ###### dataDescription `data` is a [run](/docs/api-reference/runs/object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.in_progress ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunObject ##### required - event - data ##### description Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to an `in_progress` status. ##### x-oaiMeta ###### dataDescription `data` is a [run](/docs/api-reference/runs/object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.requires_action ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunObject ##### required - event - data ##### description Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `requires_action` status. ##### x-oaiMeta ###### dataDescription `data` is a [run](/docs/api-reference/runs/object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.completed ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunObject ##### required - event - data ##### description Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is completed. ##### x-oaiMeta ###### dataDescription `data` is a [run](/docs/api-reference/runs/object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.incomplete ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunObject ##### required - event - data ##### description Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) ends with status `incomplete`. ##### x-oaiMeta ###### dataDescription `data` is a [run](/docs/api-reference/runs/object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.failed ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunObject ##### required - event - data ##### description Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) fails. ##### x-oaiMeta ###### dataDescription `data` is a [run](/docs/api-reference/runs/object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.cancelling ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunObject ##### required - event - data ##### description Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) moves to a `cancelling` status. ##### x-oaiMeta ###### dataDescription `data` is a [run](/docs/api-reference/runs/object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.cancelled ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunObject ##### required - event - data ##### description Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) is cancelled. ##### x-oaiMeta ###### dataDescription `data` is a [run](/docs/api-reference/runs/object) ##### type object ##### properties ###### event ####### type string ####### enum - thread.run.expired ####### x-stainless-const true ###### data ####### $ref #/components/schemas/RunObject ##### required - event - data ##### description Occurs when a [run](https://platform.openai.com/docs/api-reference/runs/object) expires. ##### x-oaiMeta ###### dataDescription `data` is a [run](/docs/api-reference/runs/object) #### discriminator ##### propertyName event ### RunToolCallObject #### type object #### description Tool call objects #### properties ##### id ###### type string ###### description The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](https://platform.openai.com/docs/api-reference/runs/submitToolOutputs) endpoint. ##### type ###### type string ###### description The type of tool call the output is required for. For now, this is always `function`. ###### enum - function ###### x-stainless-const true ##### function ###### type object ###### description The function definition. ###### properties ####### name ######## type string ######## description The name of the function. ####### arguments ######## type string ######## description The arguments that the model expects you to pass to the function. ###### required - name - arguments #### required - 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 ### ServiceTier #### type string #### description Specifies the processing type used for serving the request. - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'. - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model. - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier. - When not set, the default behavior is 'auto'. When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter. #### enum - auto - default - flex - scale - priority #### nullable true #### default auto ### SpeechAudioDeltaEvent #### type object #### description Emitted for each chunk of audio data generated during speech synthesis. #### properties ##### type ###### type string ###### description The type of the event. Always `speech.audio.delta`. ###### enum - speech.audio.delta ###### x-stainless-const true ##### audio ###### type string ###### description A chunk of Base64-encoded audio data. #### required - type - audio #### x-oaiMeta ##### name Stream Event (speech.audio.delta) ##### group speech ##### example { "type": "speech.audio.delta", "audio": "base64-encoded-audio-data" } ### SpeechAudioDoneEvent #### type object #### description Emitted when the speech synthesis is complete and all audio has been streamed. #### properties ##### type ###### type string ###### description The type of the event. Always `speech.audio.done`. ###### enum - speech.audio.done ###### x-stainless-const true ##### usage ###### type object ###### description Token usage statistics for the request. ###### properties ####### input_tokens ######## type integer ######## description Number of input tokens in the prompt. ####### output_tokens ######## type integer ######## description Number of output tokens generated. ####### total_tokens ######## type integer ######## description Total number of tokens used (input + output). ###### required - input_tokens - output_tokens - total_tokens #### required - type - usage #### x-oaiMeta ##### name Stream Event (speech.audio.done) ##### group speech ##### example { "type": "speech.audio.done", "usage": { "input_tokens": 14, "output_tokens": 101, "total_tokens": 115 } } ### StaticChunkingStrategy #### 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 ### StaticChunkingStrategyRequestParam #### type object #### title Static Chunking Strategy #### description Customize your own chunking strategy by setting chunk size and chunk overlap. #### additionalProperties false #### properties ##### type ###### type string ###### description Always `static`. ###### enum - static ###### x-stainless-const true ##### static ###### $ref #/components/schemas/StaticChunkingStrategy #### required - type - static ### StaticChunkingStrategyResponseParam #### type object #### title Static Chunking Strategy #### additionalProperties false #### properties ##### type ###### type string ###### description Always `static`. ###### enum - static ###### x-stainless-const true ##### static ###### $ref #/components/schemas/StaticChunkingStrategy #### required - type - static ### StopConfiguration #### description Not supported with latest reasoning models `o3` and `o4-mini`. Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence. #### nullable true #### anyOf ##### type string ##### default <|endoftext|> ##### example ##### nullable true ##### type array ##### minItems 1 ##### maxItems 4 ##### items ###### type string ###### example ["\n"] ### SubmitToolOutputsRunRequest #### type object #### additionalProperties false #### properties ##### tool_outputs ###### description A list of tools for which the outputs are being submitted. ###### type array ###### items ####### type object ####### properties ######## tool_call_id ######### type string ######### description The ID of the tool call in the `required_action` object within the run object the output is being submitted for. ######## output ######### type string ######### description The output of the tool call to be submitted to continue the run. ##### 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. #### 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](https://platform.openai.com/docs/guides/structured-outputs). The default format is `{ "type": "text" }` with no additional options. **Not recommended for gpt-4o and newer models:** Setting to `{ "type": "json_object" }` enables the older JSON mode, which ensures the message the model generates is valid JSON. Using `json_schema` is preferred for models that support it. #### anyOf ##### $ref #/components/schemas/ResponseFormatText ##### $ref #/components/schemas/TextResponseFormatJsonSchema ##### $ref #/components/schemas/ResponseFormatJsonObject #### discriminator ##### propertyName type ### TextResponseFormatJsonSchema #### type object #### title JSON schema #### description JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://platform.openai.com/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](https://platform.openai.com/docs/guides/structured-outputs). #### required - type - schema - name ### ThreadObject #### type object #### title Thread #### description Represents a thread that contains [messages](https://platform.openai.com/docs/api-reference/messages). #### properties ##### id ###### description The identifier, which can be referenced in API endpoints. ###### type string ##### object ###### description The object type, which is always `thread`. ###### type string ###### enum - thread ###### x-stainless-const true ##### created_at ###### description The Unix timestamp (in seconds) for when the thread was created. ###### type integer ##### 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](https://platform.openai.com/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](https://platform.openai.com/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 #### required - id - object - created_at - tool_resources - metadata #### x-oaiMeta ##### name The thread object ##### beta true ##### example { "id": "thread_abc123", "object": "thread", "created_at": 1698107661, "metadata": {} } ### ThreadStreamEvent #### anyOf ##### type object ##### properties ###### enabled ####### type boolean ####### description Whether to enable input audio transcription. ###### event ####### type string ####### enum - thread.created ####### x-stainless-const true ###### data ####### $ref #/components/schemas/ThreadObject ##### required - event - data ##### description Occurs when a new [thread](https://platform.openai.com/docs/api-reference/threads/object) is created. ##### x-oaiMeta ###### dataDescription `data` is a [thread](/docs/api-reference/threads/object) #### discriminator ##### propertyName event ### ToggleCertificatesRequest #### type object #### properties ##### certificate_ids ###### type array ###### items ####### type string ####### example cert_abc ###### minItems 1 ###### maxItems 10 #### required - certificate_ids ### Tool #### description A tool that can be used to generate a response. #### discriminator ##### propertyName type #### anyOf ##### $ref #/components/schemas/FunctionTool ##### $ref #/components/schemas/FileSearchTool ##### $ref #/components/schemas/ComputerUsePreviewTool ##### $ref #/components/schemas/WebSearchTool ##### $ref #/components/schemas/MCPTool ##### $ref #/components/schemas/CodeInterpreterTool ##### $ref #/components/schemas/ImageGenTool ##### $ref #/components/schemas/LocalShellTool ##### $ref #/components/schemas/CustomTool ##### $ref #/components/schemas/WebSearchPreviewTool ### ToolChoiceAllowed #### type object #### title Allowed tools #### description Constrains the tools available to the model to a pre-defined set. #### properties ##### type ###### type string ###### enum - allowed_tools ###### description Allowed tool configuration type. Always `allowed_tools`. ###### x-stainless-const true ##### mode ###### type string ###### enum - auto - required ###### description Constrains the tools available to the model to a pre-defined set. `auto` allows the model to pick from among the allowed tools and generate a message. `required` requires the model to call one or more of the allowed tools. ##### tools ###### type array ###### description A list of tool definitions that the model should be allowed to call. For the Responses API, the list of tool definitions might look like: ```json [ { "type": "function", "name": "get_weather" }, { "type": "mcp", "server_label": "deepwiki" }, { "type": "image_generation" } ] ``` ###### items ####### type object ####### description A tool definition that the model should be allowed to call. ####### additionalProperties true ####### x-oaiExpandable false #### required - type - mode - tools ### ToolChoiceCustom #### type object #### title Custom tool #### description Use this option to force the model to call a specific custom tool. #### properties ##### type ###### type string ###### enum - custom ###### description For custom tool calling, the type is always `custom`. ###### x-stainless-const true ##### name ###### type string ###### description The name of the custom tool to call. #### required - type - name ### 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 ### ToolChoiceMCP #### type object #### title MCP tool #### description Use this option to force the model to call a specific tool on a remote MCP server. #### properties ##### type ###### type string ###### enum - mcp ###### description For MCP tools, the type is always `mcp`. ###### x-stainless-const true ##### server_label ###### type string ###### description The label of the MCP server to use. ##### name ###### type string ###### description The name of the tool to call on the server. ###### nullable true #### required - type - server_label ### 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](https://platform.openai.com/docs/guides/tools). #### properties ##### type ###### type string ###### description The type of hosted tool the model should to use. Learn more about [built-in tools](https://platform.openai.com/docs/guides/tools). Allowed values are: - `file_search` - `web_search_preview` - `computer_use_preview` - `code_interpreter` - `image_generation` ###### enum - file_search - web_search_preview - computer_use_preview - web_search_preview_2025_03_11 - image_generation - code_interpreter #### required - type ### TranscriptTextDeltaEvent #### type object #### description Emitted when there is an additional text delta. This is also the first event emitted when the transcription starts. Only emitted when you [create a transcription](https://platform.openai.com/docs/api-reference/audio/create-transcription) with the `Stream` parameter set to `true`. #### properties ##### type ###### type string ###### description The type of the event. Always `transcript.text.delta`. ###### enum - transcript.text.delta ###### x-stainless-const true ##### delta ###### type string ###### description The text delta that was additionally transcribed. ##### logprobs ###### type array ###### description The log probabilities of the delta. Only included if you [create a transcription](https://platform.openai.com/docs/api-reference/audio/create-transcription) with the `include[]` parameter set to `logprobs`. ###### items ####### type object ####### properties ######## token ######### type string ######### description The token that was used to generate the log probability. ######## logprob ######### type number ######### description The log probability of the token. ######## bytes ######### type array ######### items ########## type integer ######### description The bytes that were used to generate the log probability. #### required - type - delta #### x-oaiMeta ##### name Stream Event (transcript.text.delta) ##### group transcript ##### example { "type": "transcript.text.delta", "delta": " wonderful" } ### TranscriptTextDoneEvent #### type object #### description Emitted when the transcription is complete. Contains the complete transcription text. Only emitted when you [create a transcription](https://platform.openai.com/docs/api-reference/audio/create-transcription) with the `Stream` parameter set to `true`. #### properties ##### type ###### type string ###### description The type of the event. Always `transcript.text.done`. ###### enum - transcript.text.done ###### x-stainless-const true ##### text ###### type string ###### description The text that was transcribed. ##### logprobs ###### type array ###### description The log probabilities of the individual tokens in the transcription. Only included if you [create a transcription](https://platform.openai.com/docs/api-reference/audio/create-transcription) with the `include[]` parameter set to `logprobs`. ###### items ####### type object ####### properties ######## token ######### type string ######### description The token that was used to generate the log probability. ######## logprob ######### type number ######### description The log probability of the token. ######## bytes ######### type array ######### items ########## type integer ######### description The bytes that were used to generate the log probability. ##### usage ###### $ref #/components/schemas/TranscriptTextUsageTokens #### required - type - text #### x-oaiMeta ##### name Stream Event (transcript.text.done) ##### group transcript ##### example { "type": "transcript.text.done", "text": "I see skies of blue and clouds of white, the bright blessed days, the dark sacred nights, and I think to myself, what a wonderful world.", "usage": { "type": "tokens", "input_tokens": 14, "input_token_details": { "text_tokens": 10, "audio_tokens": 4 }, "output_tokens": 31, "total_tokens": 45 } } ### TranscriptTextUsageDuration #### type object #### title Duration Usage #### description Usage statistics for models billed by audio input duration. #### properties ##### type ###### type string ###### enum - duration ###### description The type of the usage object. Always `duration` for this variant. ###### x-stainless-const true ##### seconds ###### type number ###### description Duration of the input audio in seconds. #### required - type - seconds ### TranscriptTextUsageTokens #### type object #### title Token Usage #### description Usage statistics for models billed by token usage. #### properties ##### type ###### type string ###### enum - tokens ###### description The type of the usage object. Always `tokens` for this variant. ###### x-stainless-const true ##### input_tokens ###### type integer ###### description Number of input tokens billed for this request. ##### input_token_details ###### type object ###### description Details about the input tokens billed for this request. ###### properties ####### text_tokens ######## type integer ######## description Number of text tokens billed for this request. ####### audio_tokens ######## type integer ######## description Number of audio tokens billed for this request. ##### output_tokens ###### type integer ###### description Number of output tokens generated. ##### total_tokens ###### type integer ###### description Total number of tokens used (input + output). #### required - type - input_tokens - output_tokens - total_tokens ### TranscriptionChunkingStrategy #### description Controls how the audio is cut into chunks. When set to `"auto"`, the server first normalizes loudness and then uses voice activity detection (VAD) to choose boundaries. `server_vad` object can be provided to tweak VAD detection parameters manually. If unset, the audio is transcribed as a single block. #### anyOf ##### type string ##### enum - auto ##### description Automatically set chunking parameters based on the audio. Must be set to `"auto"`. ##### x-stainless-const true ##### $ref #/components/schemas/VadConfig #### nullable true #### x-oaiTypeLabel string ### TranscriptionInclude #### type string #### enum - logprobs ### TranscriptionSegment #### type object #### properties ##### id ###### type integer ###### description Unique identifier of the segment. ##### seek ###### type integer ###### description Seek offset of the segment. ##### start ###### type number ###### format float ###### description Start time of the segment in seconds. ##### end ###### type number ###### format float ###### description End time of the segment in seconds. ##### text ###### type string ###### description Text content of the segment. ##### tokens ###### type array ###### items ####### type integer ###### description Array of token IDs for the text content. ##### temperature ###### type number ###### format float ###### description Temperature parameter used for generating the segment. ##### avg_logprob ###### type number ###### format float ###### description Average logprob of the segment. If the value is lower than -1, consider the logprobs failed. ##### compression_ratio ###### type number ###### format float ###### description Compression ratio of the segment. If the value is greater than 2.4, consider the compression failed. ##### no_speech_prob ###### type number ###### format float ###### description Probability of no speech in the segment. If the value is higher than 1.0 and the `avg_logprob` is below -1, consider this segment silent. #### required - id - seek - start - end - text - tokens - temperature - avg_logprob - compression_ratio - no_speech_prob ### TranscriptionWord #### type object #### properties ##### word ###### type string ###### description The text content of the word. ##### start ###### type number ###### format float ###### description Start time of the word in seconds. ##### end ###### type number ###### format float ###### description End time of the word in seconds. #### required - word - start - end ### TruncationObject #### type object #### title Thread Truncation Controls #### description Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. #### properties ##### type ###### type string ###### description The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. ###### enum - auto - last_messages ##### last_messages ###### type integer ###### description The number of most recent messages from the thread when constructing the context for the run. ###### minimum 1 ###### 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 #### properties ##### name ###### description The name of the vector store. ###### type string ###### nullable true ##### expires_after ###### allOf ####### $ref #/components/schemas/VectorStoreExpirationAfter ####### nullable true ##### metadata ###### $ref #/components/schemas/Metadata ### Upload #### type object #### title Upload #### description The Upload object can accept byte chunks in the form of Parts. #### properties ##### id ###### type string ###### description The Upload unique identifier, which can be referenced in API endpoints. ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) for when the Upload was created. ##### filename ###### type string ###### description The name of the file to be uploaded. ##### bytes ###### type integer ###### description The intended number of bytes to be uploaded. ##### purpose ###### type string ###### description The intended purpose of the file. [Please refer here](https://platform.openai.com/docs/api-reference/files/object#files/object-purpose) for acceptable values. ##### status ###### type string ###### description The status of the Upload. ###### enum - pending - completed - cancelled - expired ##### expires_at ###### type integer ###### description The Unix timestamp (in seconds) for when the Upload will expire. ##### object ###### type string ###### description The object type, which is always "upload". ###### enum - upload ###### x-stainless-const true ##### file ###### allOf ####### $ref #/components/schemas/OpenAIFile ####### nullable true ####### description The ready File object after the Upload is completed. #### required - bytes - created_at - expires_at - filename - id - purpose - status - object #### x-oaiMeta ##### name The upload object ##### example { "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", } } ### UploadCertificateRequest #### type object #### properties ##### name ###### type string ###### description An optional name for the certificate ##### content ###### type string ###### description The certificate content in PEM format #### required - content ### UploadPart #### type object #### title UploadPart #### description The upload Part represents a chunk of bytes we can add to an Upload object. #### properties ##### id ###### type string ###### description The upload Part unique identifier, which can be referenced in API endpoints. ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) for when the Part was created. ##### upload_id ###### type string ###### description The ID of the Upload object that this Part was added to. ##### object ###### type string ###### description The object type, which is always `upload.part`. ###### enum - upload.part ###### x-stainless-const true #### required - created_at - id - object - upload_id #### x-oaiMeta ##### name The upload part object ##### example { "id": "part_def456", "object": "upload.part", "created_at": 1719186911, "upload_id": "upload_abc123" } ### UsageAudioSpeechesResult #### type object #### description The aggregated audio speeches usage details of the specific time bucket. #### properties ##### object ###### type string ###### enum - organization.usage.audio_speeches.result ###### x-stainless-const true ##### characters ###### type integer ###### description The number of characters processed. ##### num_model_requests ###### type integer ###### description The count of requests made to the model. ##### project_id ###### type string ###### nullable true ###### description When `group_by=project_id`, this field provides the project ID of the grouped usage result. ##### user_id ###### type string ###### nullable true ###### description When `group_by=user_id`, this field provides the user ID of the grouped usage result. ##### api_key_id ###### type string ###### nullable true ###### description When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. ##### model ###### type string ###### nullable true ###### description When `group_by=model`, this field provides the model name of the grouped usage result. #### required - object - characters - num_model_requests #### x-oaiMeta ##### name Audio speeches usage object ##### example { "object": "organization.usage.audio_speeches.result", "characters": 45, "num_model_requests": 1, "project_id": "proj_abc", "user_id": "user-abc", "api_key_id": "key_abc", "model": "tts-1" } ### UsageAudioTranscriptionsResult #### type object #### description The aggregated audio transcriptions usage details of the specific time bucket. #### properties ##### object ###### type string ###### enum - organization.usage.audio_transcriptions.result ###### x-stainless-const true ##### seconds ###### type integer ###### description The number of seconds processed. ##### num_model_requests ###### type integer ###### description The count of requests made to the model. ##### project_id ###### type string ###### nullable true ###### description When `group_by=project_id`, this field provides the project ID of the grouped usage result. ##### user_id ###### type string ###### nullable true ###### description When `group_by=user_id`, this field provides the user ID of the grouped usage result. ##### api_key_id ###### type string ###### nullable true ###### description When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. ##### model ###### type string ###### nullable true ###### description When `group_by=model`, this field provides the model name of the grouped usage result. #### required - object - seconds - num_model_requests #### x-oaiMeta ##### name Audio transcriptions usage object ##### example { "object": "organization.usage.audio_transcriptions.result", "seconds": 10, "num_model_requests": 1, "project_id": "proj_abc", "user_id": "user-abc", "api_key_id": "key_abc", "model": "tts-1" } ### UsageCodeInterpreterSessionsResult #### type object #### description The aggregated code interpreter sessions usage details of the specific time bucket. #### properties ##### object ###### type string ###### enum - organization.usage.code_interpreter_sessions.result ###### x-stainless-const true ##### num_sessions ###### type integer ###### description The number of code interpreter sessions. ##### project_id ###### type string ###### nullable true ###### description When `group_by=project_id`, this field provides the project ID of the grouped usage result. #### required - object - sessions #### x-oaiMeta ##### name Code interpreter sessions usage object ##### example { "object": "organization.usage.code_interpreter_sessions.result", "num_sessions": 1, "project_id": "proj_abc" } ### UsageCompletionsResult #### type object #### description The aggregated completions usage details of the specific time bucket. #### properties ##### object ###### type string ###### enum - organization.usage.completions.result ###### x-stainless-const true ##### input_tokens ###### type integer ###### description The aggregated number of text input tokens used, including cached tokens. For customers subscribe to scale tier, this includes scale tier tokens. ##### input_cached_tokens ###### type integer ###### description The aggregated number of text input tokens that has been cached from previous requests. For customers subscribe to scale tier, this includes scale tier tokens. ##### output_tokens ###### type integer ###### description The aggregated number of text output tokens used. For customers subscribe to scale tier, this includes scale tier tokens. ##### input_audio_tokens ###### type integer ###### description The aggregated number of audio input tokens used, including cached tokens. ##### output_audio_tokens ###### type integer ###### description The aggregated number of audio output tokens used. ##### num_model_requests ###### type integer ###### description The count of requests made to the model. ##### project_id ###### type string ###### nullable true ###### description When `group_by=project_id`, this field provides the project ID of the grouped usage result. ##### user_id ###### type string ###### nullable true ###### description When `group_by=user_id`, this field provides the user ID of the grouped usage result. ##### api_key_id ###### type string ###### nullable true ###### description When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. ##### model ###### type string ###### nullable true ###### description When `group_by=model`, this field provides the model name of the grouped usage result. ##### batch ###### type boolean ###### nullable true ###### description When `group_by=batch`, this field tells whether the grouped usage result is batch or not. #### required - object - input_tokens - output_tokens - num_model_requests #### x-oaiMeta ##### name Completions usage object ##### example { "object": "organization.usage.completions.result", "input_tokens": 5000, "output_tokens": 1000, "input_cached_tokens": 4000, "input_audio_tokens": 300, "output_audio_tokens": 200, "num_model_requests": 5, "project_id": "proj_abc", "user_id": "user-abc", "api_key_id": "key_abc", "model": "gpt-4o-mini-2024-07-18", "batch": false } ### UsageEmbeddingsResult #### type object #### description The aggregated embeddings usage details of the specific time bucket. #### properties ##### object ###### type string ###### enum - organization.usage.embeddings.result ###### x-stainless-const true ##### input_tokens ###### type integer ###### description The aggregated number of input tokens used. ##### num_model_requests ###### type integer ###### description The count of requests made to the model. ##### project_id ###### type string ###### nullable true ###### description When `group_by=project_id`, this field provides the project ID of the grouped usage result. ##### user_id ###### type string ###### nullable true ###### description When `group_by=user_id`, this field provides the user ID of the grouped usage result. ##### api_key_id ###### type string ###### nullable true ###### description When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. ##### model ###### type string ###### nullable true ###### description When `group_by=model`, this field provides the model name of the grouped usage result. #### required - object - input_tokens - num_model_requests #### x-oaiMeta ##### name Embeddings usage object ##### example { "object": "organization.usage.embeddings.result", "input_tokens": 20, "num_model_requests": 2, "project_id": "proj_abc", "user_id": "user-abc", "api_key_id": "key_abc", "model": "text-embedding-ada-002-v2" } ### UsageImagesResult #### type object #### description The aggregated images usage details of the specific time bucket. #### properties ##### object ###### type string ###### enum - organization.usage.images.result ###### x-stainless-const true ##### images ###### type integer ###### description The number of images processed. ##### num_model_requests ###### type integer ###### description The count of requests made to the model. ##### source ###### type string ###### nullable true ###### description When `group_by=source`, this field provides the source of the grouped usage result, possible values are `image.generation`, `image.edit`, `image.variation`. ##### size ###### type string ###### nullable true ###### description When `group_by=size`, this field provides the image size of the grouped usage result. ##### project_id ###### type string ###### nullable true ###### description When `group_by=project_id`, this field provides the project ID of the grouped usage result. ##### user_id ###### type string ###### nullable true ###### description When `group_by=user_id`, this field provides the user ID of the grouped usage result. ##### api_key_id ###### type string ###### nullable true ###### description When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. ##### model ###### type string ###### nullable true ###### description When `group_by=model`, this field provides the model name of the grouped usage result. #### required - object - images - num_model_requests #### x-oaiMeta ##### name Images usage object ##### example { "object": "organization.usage.images.result", "images": 2, "num_model_requests": 2, "size": "1024x1024", "source": "image.generation", "project_id": "proj_abc", "user_id": "user-abc", "api_key_id": "key_abc", "model": "dall-e-3" } ### UsageModerationsResult #### type object #### description The aggregated moderations usage details of the specific time bucket. #### properties ##### object ###### type string ###### enum - organization.usage.moderations.result ###### x-stainless-const true ##### input_tokens ###### type integer ###### description The aggregated number of input tokens used. ##### num_model_requests ###### type integer ###### description The count of requests made to the model. ##### project_id ###### type string ###### nullable true ###### description When `group_by=project_id`, this field provides the project ID of the grouped usage result. ##### user_id ###### type string ###### nullable true ###### description When `group_by=user_id`, this field provides the user ID of the grouped usage result. ##### api_key_id ###### type string ###### nullable true ###### description When `group_by=api_key_id`, this field provides the API key ID of the grouped usage result. ##### model ###### type string ###### nullable true ###### description When `group_by=model`, this field provides the model name of the grouped usage result. #### required - object - input_tokens - num_model_requests #### x-oaiMeta ##### name Moderations usage object ##### example { "object": "organization.usage.moderations.result", "input_tokens": 20, "num_model_requests": 2, "project_id": "proj_abc", "user_id": "user-abc", "api_key_id": "key_abc", "model": "text-moderation" } ### UsageResponse #### type object #### properties ##### object ###### type string ###### enum - page ###### x-stainless-const true ##### data ###### type array ###### items ####### $ref #/components/schemas/UsageTimeBucket ##### has_more ###### type boolean ##### next_page ###### type string #### required - object - data - has_more - next_page ### UsageTimeBucket #### type object #### properties ##### object ###### type string ###### enum - bucket ###### x-stainless-const true ##### start_time ###### type integer ##### end_time ###### type integer ##### result ###### type array ###### items ####### anyOf ######## $ref #/components/schemas/UsageCompletionsResult ######## $ref #/components/schemas/UsageEmbeddingsResult ######## $ref #/components/schemas/UsageModerationsResult ######## $ref #/components/schemas/UsageImagesResult ######## $ref #/components/schemas/UsageAudioSpeechesResult ######## $ref #/components/schemas/UsageAudioTranscriptionsResult ######## $ref #/components/schemas/UsageVectorStoresResult ######## $ref #/components/schemas/UsageCodeInterpreterSessionsResult ######## $ref #/components/schemas/CostsResult ####### discriminator ######## propertyName object #### required - object - start_time - end_time - result ### UsageVectorStoresResult #### type object #### description The aggregated vector stores usage details of the specific time bucket. #### properties ##### object ###### type string ###### enum - organization.usage.vector_stores.result ###### x-stainless-const true ##### usage_bytes ###### type integer ###### description The vector stores usage in bytes. ##### project_id ###### type string ###### nullable true ###### description When `group_by=project_id`, this field provides the project ID of the grouped usage result. #### required - object - usage_bytes #### x-oaiMeta ##### name Vector stores usage object ##### example { "object": "organization.usage.vector_stores.result", "usage_bytes": 1024, "project_id": "proj_abc" } ### User #### type object #### description Represents an individual `user` within an organization. #### properties ##### object ###### type string ###### enum - organization.user ###### description The object type, which is always `organization.user` ###### 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 user ##### email ###### type string ###### description The email address of the user ##### role ###### type string ###### enum - owner - reader ###### description `owner` or `reader` ##### added_at ###### type integer ###### description The Unix timestamp (in seconds) of when the user was added. #### required - object - id - name - email - role - added_at #### x-oaiMeta ##### name The user object ##### example { "object": "organization.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } ### UserDeleteResponse #### type object #### properties ##### object ###### type string ###### enum - organization.user.deleted ###### x-stainless-const true ##### id ###### type string ##### deleted ###### type boolean #### required - object - id - deleted ### UserListResponse #### type object #### properties ##### object ###### type string ###### enum - list ###### x-stainless-const true ##### data ###### type array ###### items ####### $ref #/components/schemas/User ##### first_id ###### type string ##### last_id ###### type string ##### has_more ###### type boolean #### required - object - data - first_id - last_id - has_more ### UserRoleUpdateRequest #### type object #### properties ##### role ###### type string ###### enum - owner - reader ###### description `owner` or `reader` #### required - role ### VadConfig #### type object #### additionalProperties false #### required - type #### properties ##### type ###### type string ###### enum - server_vad ###### description Must be set to `server_vad` to enable manual chunking using server side VAD. ##### prefix_padding_ms ###### type integer ###### default 300 ###### description Amount of audio to include before the VAD detected speech (in milliseconds). ##### silence_duration_ms ###### type integer ###### default 200 ###### description Duration of silence to detect speech stop (in milliseconds). With shorter values the model will respond more quickly, but may jump in on short pauses from the user. ##### threshold ###### type number ###### default 0.5 ###### description Sensitivity threshold (0.0 to 1.0) for voice activity detection. A higher threshold will require louder audio to activate the model, and thus might perform better in noisy environments. ### ValidateGraderRequest #### type object #### title ValidateGraderRequest #### properties ##### grader ###### type object ###### description The grader used for the fine-tuning job. ###### anyOf ####### $ref #/components/schemas/GraderStringCheck ####### $ref #/components/schemas/GraderTextSimilarity ####### $ref #/components/schemas/GraderPython ####### $ref #/components/schemas/GraderScoreModel ####### $ref #/components/schemas/GraderMulti #### required - grader ### ValidateGraderResponse #### type object #### title ValidateGraderResponse #### properties ##### grader ###### type object ###### description The grader used for the fine-tuning job. ###### anyOf ####### $ref #/components/schemas/GraderStringCheck ####### $ref #/components/schemas/GraderTextSimilarity ####### $ref #/components/schemas/GraderPython ####### $ref #/components/schemas/GraderScoreModel ####### $ref #/components/schemas/GraderMulti ### VectorStoreExpirationAfter #### type object #### title Vector store expiration policy #### description The expiration policy for a vector store. #### properties ##### anchor ###### description Anchor timestamp after which the expiration policy applies. Supported anchors: `last_active_at`. ###### type string ###### enum - last_active_at ###### x-stainless-const true ##### days ###### description The number of days after the anchor time that the vector store will expire. ###### type integer ###### minimum 1 ###### maximum 365 #### 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 ##### anyOf ###### type string ###### maxLength 512 ###### type number ###### type boolean #### x-oaiTypeLabel map #### nullable true ### VectorStoreFileBatchObject #### type object #### title Vector store file batch #### description A batch of files attached to a vector store. #### properties ##### id ###### description The identifier, which can be referenced in API endpoints. ###### type string ##### object ###### description The object type, which is always `vector_store.file_batch`. ###### type string ###### enum - vector_store.files_batch ###### x-stainless-const true ##### created_at ###### description The Unix timestamp (in seconds) for when the vector store files batch was created. ###### type integer ##### vector_store_id ###### description The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to. ###### type string ##### status ###### description The status of the vector store files batch, which can be either `in_progress`, `completed`, `cancelled` or `failed`. ###### type string ###### enum - in_progress - completed - cancelled - failed ##### file_counts ###### type object ###### properties ####### in_progress ######## description The number of files that are currently being processed. ######## type integer ####### completed ######## description The number of files that have been processed. ######## type integer ####### failed ######## description The number of files that have failed to process. ######## type integer ####### cancelled ######## description The number of files that where cancelled. ######## type integer ####### total ######## description The total number of files. ######## type integer ###### required - in_progress - completed - cancelled - failed - total #### required - id - object - created_at - vector_store_id - status - file_counts #### x-oaiMeta ##### name The vector store files batch object ##### beta true ##### example { "id": "vsfb_123", "object": "vector_store.files_batch", "created_at": 1698107661, "vector_store_id": "vs_abc123", "status": "completed", "file_counts": { "in_progress": 0, "completed": 100, "failed": 0, "cancelled": 0, "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 #### description A list of files attached to a vector store. #### properties ##### id ###### description The identifier, which can be referenced in API endpoints. ###### type string ##### object ###### description The object type, which is always `vector_store.file`. ###### type string ###### enum - vector_store.file ###### x-stainless-const true ##### usage_bytes ###### description The total vector store usage in bytes. Note that this may be different from the original file size. ###### type integer ##### created_at ###### description The Unix timestamp (in seconds) for when the vector store file was created. ###### type integer ##### vector_store_id ###### description The ID of the [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) that the [File](https://platform.openai.com/docs/api-reference/files) is attached to. ###### type string ##### status ###### description The status of the vector store file, which can be either `in_progress`, `completed`, `cancelled`, or `failed`. The status `completed` indicates that the vector store file is ready for use. ###### type string ###### enum - in_progress - completed - cancelled - failed ##### last_error ###### type object ###### description The last error associated with this vector store file. Will be `null` if there are no errors. ###### nullable true ###### properties ####### code ######## type string ######## description One of `server_error` or `rate_limit_exceeded`. ######## enum - server_error - unsupported_file - invalid_file ####### message ######## type string ######## description A human-readable description of the error. ###### required - code - message ##### chunking_strategy ###### $ref #/components/schemas/ChunkingStrategyResponse ##### attributes ###### $ref #/components/schemas/VectorStoreFileAttributes #### required - id - object - usage_bytes - created_at - vector_store_id - status - last_error #### x-oaiMeta ##### name The vector store file object ##### beta true ##### example { "id": "file-abc123", "object": "vector_store.file", "usage_bytes": 1234, "created_at": 1698107661, "vector_store_id": "vs_abc123", "status": "completed", "last_error": null, "chunking_strategy": { "type": "static", "static": { "max_chunk_size_tokens": 800, "chunk_overlap_tokens": 400 } } } ### VectorStoreObject #### type object #### title Vector store #### description A vector store is a collection of processed files can be used by the `file_search` tool. #### properties ##### id ###### description The identifier, which can be referenced in API endpoints. ###### type string ##### object ###### description The object type, which is always `vector_store`. ###### type string ###### enum - vector_store ###### x-stainless-const true ##### created_at ###### description The Unix timestamp (in seconds) for when the vector store was created. ###### type integer ##### name ###### description The name of the vector store. ###### type string ##### usage_bytes ###### description The total number of bytes used by the files in the vector store. ###### type integer ##### file_counts ###### type object ###### properties ####### in_progress ######## description The number of files that are currently being processed. ######## type integer ####### completed ######## description The number of files that have been successfully processed. ######## type integer ####### failed ######## description The number of files that have failed to process. ######## type integer ####### cancelled ######## description The number of files that were cancelled. ######## type integer ####### total ######## description The total number of files. ######## type integer ###### required - in_progress - completed - failed - cancelled - total ##### status ###### description The status of the vector store, which can be either `expired`, `in_progress`, or `completed`. A status of `completed` indicates that the vector store is ready for use. ###### type string ###### enum - expired - in_progress - completed ##### expires_after ###### $ref #/components/schemas/VectorStoreExpirationAfter ##### expires_at ###### description The Unix timestamp (in seconds) for when the vector store will expire. ###### type integer ###### nullable true ##### last_active_at ###### description The Unix timestamp (in seconds) for when the vector store was last active. ###### type integer ###### nullable true ##### metadata ###### $ref #/components/schemas/Metadata #### required - id - object - usage_bytes - created_at - status - last_active_at - name - file_counts - metadata #### x-oaiMeta ##### name The vector store object ##### example { "id": "vs_123", "object": "vector_store", "created_at": 1698107661, "usage_bytes": 123456, "last_active_at": 1698107661, "name": "my_vector_store", "status": "completed", "file_counts": { "in_progress": 0, "completed": 100, "cancelled": 0, "failed": 0, "total": 100 }, "last_used_at": 1698107661 } ### VectorStoreSearchRequest #### type object #### additionalProperties false #### properties ##### query ###### description A query string for a search ###### anyOf ####### 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. ###### anyOf ####### $ref #/components/schemas/ComparisonFilter ####### $ref #/components/schemas/CompoundFilter ##### ranking_options ###### description Ranking options for search. ###### type object ###### additionalProperties false ###### properties ####### ranker ######## description Enable re-ranking; set to `none` to disable, which can help reduce latency. ######## type string ######## enum - none - 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 ### Verbosity #### type string #### enum - low - medium - high #### default medium #### nullable true #### description Constrains the verbosity of the model's response. Lower values will result in more concise responses, while higher values will result in more verbose responses. Currently supported values are `low`, `medium`, and `high`. ### VoiceIdsShared #### example ash #### anyOf ##### type string ##### type string ##### enum - alloy - ash - ballad - coral - echo - sage - shimmer - verse ### 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 ### WebSearchActionFind #### type object #### title Find action #### description Action type "find": Searches for a pattern within a loaded page. #### properties ##### type ###### type string ###### enum - find ###### description The action type. ###### x-stainless-const true ##### url ###### type string ###### format uri ###### description The URL of the page searched for the pattern. ##### pattern ###### type string ###### description The pattern or text to search for within the page. #### required - type - url - pattern ### WebSearchActionOpenPage #### type object #### title Open page action #### description Action type "open_page" - Opens a specific URL from search results. #### properties ##### type ###### type string ###### enum - open_page ###### description The action type. ###### x-stainless-const true ##### url ###### type string ###### format uri ###### description The URL opened by the model. #### required - type - url ### WebSearchActionSearch #### type object #### title Search action #### description Action type "search" - Performs a web search query. #### properties ##### type ###### type string ###### enum - search ###### description The action type. ###### x-stainless-const true ##### query ###### type string ###### description The search query. ##### sources ###### type array ###### title Web search sources ###### description The sources used in the search. ###### items ####### type object ####### title Web search source ####### description A source used in the search. ####### properties ######## type ######### type string ######### enum - url ######### description The type of source. Always `url`. ######### x-stainless-const true ######## url ######### type string ######### description The URL of the source. ####### required - type - url #### required - type - query ### WebSearchApproximateLocation #### type object #### title Web search approximate location #### description The approximate location of the user. #### nullable true #### properties ##### type ###### type string ###### enum - approximate ###### description The type of location approximation. Always `approximate`. ###### default approximate ###### x-stainless-const true ##### country ###### type string ###### description The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. ###### nullable true ##### region ###### type string ###### description Free text input for the region of the user, e.g. `California`. ###### nullable true ##### city ###### type string ###### description Free text input for the city of the user, e.g. `San Francisco`. ###### nullable true ##### timezone ###### type string ###### description The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. ###### nullable true ### 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 Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). #### properties ##### type ###### type string ###### enum - web_search - web_search_2025_08_26 ###### description The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. ###### default web_search ##### filters ###### type object ###### description Filters for the search. ###### nullable true ###### properties ####### allowed_domains ######## type array ######## title Allowed domains for the search. ######## description Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` ######## items ######### type string ######### description Allowed domain for the search. ######## default ######## nullable true ##### user_location ###### $ref #/components/schemas/WebSearchApproximateLocation ##### search_context_size ###### type string ###### enum - low - medium - high ###### default medium ###### description High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. #### required - type ### WebSearchToolCall #### type object #### title Web search tool call #### description The results of a web search tool call. See the [web search guide](https://platform.openai.com/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 ##### action ###### type object ###### description An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find). ###### anyOf ####### $ref #/components/schemas/WebSearchActionSearch ####### $ref #/components/schemas/WebSearchActionOpenPage ####### $ref #/components/schemas/WebSearchActionFind ###### discriminator ####### propertyName type #### required - id - type - status - action ### WebhookBatchCancelled #### type object #### title batch.cancelled #### description Sent when a batch API request has been cancelled. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the batch API request was cancelled. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the batch API request. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `batch.cancelled`. ###### enum - batch.cancelled ###### x-stainless-const true #### x-oaiMeta ##### name batch.cancelled ##### group webhook-events ##### example { "id": "evt_abc123", "type": "batch.cancelled", "created_at": 1719168000, "data": { "id": "batch_abc123" } } ### WebhookBatchCompleted #### type object #### title batch.completed #### description Sent when a batch API request has been completed. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the batch API request was completed. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the batch API request. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `batch.completed`. ###### enum - batch.completed ###### x-stainless-const true #### x-oaiMeta ##### name batch.completed ##### group webhook-events ##### example { "id": "evt_abc123", "type": "batch.completed", "created_at": 1719168000, "data": { "id": "batch_abc123" } } ### WebhookBatchExpired #### type object #### title batch.expired #### description Sent when a batch API request has expired. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the batch API request expired. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the batch API request. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `batch.expired`. ###### enum - batch.expired ###### x-stainless-const true #### x-oaiMeta ##### name batch.expired ##### group webhook-events ##### example { "id": "evt_abc123", "type": "batch.expired", "created_at": 1719168000, "data": { "id": "batch_abc123" } } ### WebhookBatchFailed #### type object #### title batch.failed #### description Sent when a batch API request has failed. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the batch API request failed. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the batch API request. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `batch.failed`. ###### enum - batch.failed ###### x-stainless-const true #### x-oaiMeta ##### name batch.failed ##### group webhook-events ##### example { "id": "evt_abc123", "type": "batch.failed", "created_at": 1719168000, "data": { "id": "batch_abc123" } } ### WebhookEvalRunCanceled #### type object #### title eval.run.canceled #### description Sent when an eval run has been canceled. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the eval run was canceled. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the eval run. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `eval.run.canceled`. ###### enum - eval.run.canceled ###### x-stainless-const true #### x-oaiMeta ##### name eval.run.canceled ##### group webhook-events ##### example { "id": "evt_abc123", "type": "eval.run.canceled", "created_at": 1719168000, "data": { "id": "evalrun_abc123" } } ### WebhookEvalRunFailed #### type object #### title eval.run.failed #### description Sent when an eval run has failed. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the eval run failed. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the eval run. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `eval.run.failed`. ###### enum - eval.run.failed ###### x-stainless-const true #### x-oaiMeta ##### name eval.run.failed ##### group webhook-events ##### example { "id": "evt_abc123", "type": "eval.run.failed", "created_at": 1719168000, "data": { "id": "evalrun_abc123" } } ### WebhookEvalRunSucceeded #### type object #### title eval.run.succeeded #### description Sent when an eval run has succeeded. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the eval run succeeded. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the eval run. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `eval.run.succeeded`. ###### enum - eval.run.succeeded ###### x-stainless-const true #### x-oaiMeta ##### name eval.run.succeeded ##### group webhook-events ##### example { "id": "evt_abc123", "type": "eval.run.succeeded", "created_at": 1719168000, "data": { "id": "evalrun_abc123" } } ### WebhookFineTuningJobCancelled #### type object #### title fine_tuning.job.cancelled #### description Sent when a fine-tuning job has been cancelled. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the fine-tuning job was cancelled. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the fine-tuning job. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `fine_tuning.job.cancelled`. ###### enum - fine_tuning.job.cancelled ###### x-stainless-const true #### x-oaiMeta ##### name fine_tuning.job.cancelled ##### group webhook-events ##### example { "id": "evt_abc123", "type": "fine_tuning.job.cancelled", "created_at": 1719168000, "data": { "id": "ftjob_abc123" } } ### WebhookFineTuningJobFailed #### type object #### title fine_tuning.job.failed #### description Sent when a fine-tuning job has failed. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the fine-tuning job failed. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the fine-tuning job. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `fine_tuning.job.failed`. ###### enum - fine_tuning.job.failed ###### x-stainless-const true #### x-oaiMeta ##### name fine_tuning.job.failed ##### group webhook-events ##### example { "id": "evt_abc123", "type": "fine_tuning.job.failed", "created_at": 1719168000, "data": { "id": "ftjob_abc123" } } ### WebhookFineTuningJobSucceeded #### type object #### title fine_tuning.job.succeeded #### description Sent when a fine-tuning job has succeeded. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the fine-tuning job succeeded. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the fine-tuning job. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `fine_tuning.job.succeeded`. ###### enum - fine_tuning.job.succeeded ###### x-stainless-const true #### x-oaiMeta ##### name fine_tuning.job.succeeded ##### group webhook-events ##### example { "id": "evt_abc123", "type": "fine_tuning.job.succeeded", "created_at": 1719168000, "data": { "id": "ftjob_abc123" } } ### WebhookResponseCancelled #### type object #### title response.cancelled #### description Sent when a background response has been cancelled. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the model response was cancelled. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the model response. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `response.cancelled`. ###### enum - response.cancelled ###### x-stainless-const true #### x-oaiMeta ##### name response.cancelled ##### group webhook-events ##### example { "id": "evt_abc123", "type": "response.cancelled", "created_at": 1719168000, "data": { "id": "resp_abc123" } } ### WebhookResponseCompleted #### type object #### title response.completed #### description Sent when a background response has been completed. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the model response was completed. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the model response. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `response.completed`. ###### enum - response.completed ###### x-stainless-const true #### x-oaiMeta ##### name response.completed ##### group webhook-events ##### example { "id": "evt_abc123", "type": "response.completed", "created_at": 1719168000, "data": { "id": "resp_abc123" } } ### WebhookResponseFailed #### type object #### title response.failed #### description Sent when a background response has failed. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the model response failed. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the model response. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `response.failed`. ###### enum - response.failed ###### x-stainless-const true #### x-oaiMeta ##### name response.failed ##### group webhook-events ##### example { "id": "evt_abc123", "type": "response.failed", "created_at": 1719168000, "data": { "id": "resp_abc123" } } ### WebhookResponseIncomplete #### type object #### title response.incomplete #### description Sent when a background response has been interrupted. #### required - created_at - id - data - type #### properties ##### created_at ###### type integer ###### description The Unix timestamp (in seconds) of when the model response was interrupted. ##### id ###### type string ###### description The unique ID of the event. ##### data ###### type object ###### description Event data payload. ###### required - id ###### properties ####### id ######## type string ######## description The unique ID of the model response. ##### object ###### type string ###### description The object of the event. Always `event`. ###### enum - event ###### x-stainless-const true ##### type ###### type string ###### description The type of the event. Always `response.incomplete`. ###### enum - response.incomplete ###### x-stainless-const true #### x-oaiMeta ##### name response.incomplete ##### group webhook-events ##### example { "id": "evt_abc123", "type": "response.incomplete", "created_at": 1719168000, "data": { "id": "resp_abc123" } } ### InputTextContent #### properties ##### type ###### type string ###### enum - input_text ###### description The type of the input item. Always `input_text`. ###### default input_text ###### x-stainless-const true ##### text ###### type string ###### description The text input to the model. #### type object #### required - type - text #### title Input text #### description A text input to the model. ### InputImageContent #### properties ##### type ###### type string ###### enum - input_image ###### description The type of the input item. Always `input_image`. ###### default input_image ###### x-stainless-const true ##### image_url ###### anyOf ####### type string ####### description The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. ####### type null ##### file_id ###### anyOf ####### type string ####### description The ID of the file to be sent to the model. ####### type null ##### detail ###### type string ###### enum - low - high - auto ###### description The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`. #### type object #### required - type - detail #### title Input image #### description An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision). ### InputFileContent #### properties ##### type ###### type string ###### enum - input_file ###### description The type of the input item. Always `input_file`. ###### default input_file ###### x-stainless-const true ##### file_id ###### anyOf ####### type string ####### description The ID of the file to be sent to the model. ####### type null ##### filename ###### type string ###### description The name of the file to be sent to the model. ##### file_url ###### type string ###### description The URL 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. #### type object #### required - type #### title Input file #### description A file input to the model. ### FileCitationBody #### properties ##### type ###### type string ###### enum - file_citation ###### description The type of the file citation. Always `file_citation`. ###### default file_citation ###### x-stainless-const true ##### file_id ###### type string ###### description The ID of the file. ##### index ###### type integer ###### description The index of the file in the list of files. ##### filename ###### type string ###### description The filename of the file cited. #### type object #### required - type - file_id - index - filename #### title File citation #### description A citation to a file. ### UrlCitationBody #### properties ##### type ###### type string ###### enum - url_citation ###### description The type of the URL citation. Always `url_citation`. ###### default url_citation ###### x-stainless-const true ##### url ###### type string ###### description The URL of the web resource. ##### start_index ###### type integer ###### description The index of the first character of the URL citation in the message. ##### end_index ###### type integer ###### description The index of the last character of the URL citation in the message. ##### title ###### type string ###### description The title of the web resource. #### type object #### required - type - url - start_index - end_index - title #### title URL citation #### description A citation for a web resource used to generate a model response. ### ContainerFileCitationBody #### properties ##### type ###### type string ###### enum - container_file_citation ###### description The type of the container file citation. Always `container_file_citation`. ###### default container_file_citation ###### x-stainless-const true ##### container_id ###### type string ###### description The ID of the container file. ##### file_id ###### type string ###### description The ID of the file. ##### start_index ###### type integer ###### description The index of the first character of the container file citation in the message. ##### end_index ###### type integer ###### description The index of the last character of the container file citation in the message. ##### filename ###### type string ###### description The filename of the container file cited. #### type object #### required - type - container_id - file_id - start_index - end_index - filename #### title Container file citation #### description A citation for a container file used to generate a model response. ### Annotation #### discriminator ##### propertyName type #### anyOf ##### $ref #/components/schemas/FileCitationBody ##### $ref #/components/schemas/UrlCitationBody ##### $ref #/components/schemas/ContainerFileCitationBody ##### $ref #/components/schemas/FilePath ### TopLogProb #### properties ##### token ###### type string ##### logprob ###### type number ##### bytes ###### items ####### type integer ###### type array #### type object #### required - token - logprob - bytes #### title Top log probability #### description The top log probability of a token. ### LogProb #### properties ##### token ###### type string ##### logprob ###### type number ##### bytes ###### items ####### type integer ###### type array ##### top_logprobs ###### items ####### $ref #/components/schemas/TopLogProb ###### type array #### type object #### required - token - logprob - bytes - top_logprobs #### title Log probability #### description The log probability of a token. ### OutputTextContent #### properties ##### type ###### type string ###### enum - output_text ###### description The type of the output text. Always `output_text`. ###### default output_text ###### x-stainless-const true ##### text ###### type string ###### description The text output from the model. ##### annotations ###### items ####### $ref #/components/schemas/Annotation ###### type array ###### description The annotations of the text output. ##### logprobs ###### items ####### $ref #/components/schemas/LogProb ###### type array #### type object #### required - type - text - annotations #### title Output text #### description A text output from the model. ### RefusalContent #### properties ##### type ###### type string ###### enum - refusal ###### description The type of the refusal. Always `refusal`. ###### default refusal ###### x-stainless-const true ##### refusal ###### type string ###### description The refusal explanation from the model. #### type object #### required - type - refusal #### title Refusal #### description A refusal from the model. ### ComputerCallSafetyCheckParam #### properties ##### id ###### type string ###### description The ID of the pending safety check. ##### code ###### anyOf ####### type string ####### description The type of the pending safety check. ####### type null ##### message ###### anyOf ####### type string ####### description Details about the pending safety check. ####### type null #### type object #### required - id #### description A pending safety check for the computer call. ### ComputerCallOutputItemParam #### properties ##### id ###### anyOf ####### type string ####### description The ID of the computer tool call output. ####### type null ##### call_id ###### type string ###### maxLength 64 ###### minLength 1 ###### description The ID of the computer tool call that produced the output. ##### type ###### type string ###### enum - computer_call_output ###### description The type of the computer tool call output. Always `computer_call_output`. ###### default computer_call_output ###### x-stainless-const true ##### output ###### $ref #/components/schemas/ComputerScreenshotImage ##### acknowledged_safety_checks ###### anyOf ####### items ######## $ref #/components/schemas/ComputerCallSafetyCheckParam ####### type array ####### description The safety checks reported by the API that have been acknowledged by the developer. ####### type null ##### status ###### anyOf ####### type string ####### enum - in_progress - completed - incomplete ####### description The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. ####### type null #### type object #### required - call_id - type - output #### title Computer tool call output #### description The output of a computer tool call. ### FunctionCallOutputItemParam #### properties ##### id ###### anyOf ####### type string ####### description The unique ID of the function tool call output. Populated when this item is returned via API. ####### type null ##### call_id ###### type string ###### maxLength 64 ###### minLength 1 ###### description The unique ID of the function tool call generated by the model. ##### type ###### type string ###### enum - function_call_output ###### description The type of the function tool call output. Always `function_call_output`. ###### default function_call_output ###### x-stainless-const true ##### output ###### type string ###### maxLength 10485760 ###### description A JSON string of the output of the function tool call. ##### status ###### anyOf ####### type string ####### enum - in_progress - completed - incomplete ####### description The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. ####### type null #### type object #### required - call_id - type - output #### title Function tool call output #### description The output of a function tool call. ### ItemReferenceParam #### properties ##### type ###### anyOf ####### type string ####### enum - item_reference ####### description The type of item to reference. Always `item_reference`. ####### default item_reference ####### x-stainless-const true ####### type null ##### id ###### type string ###### description The ID of the item to reference. #### type object #### required - id #### title Item reference #### description An internal identifier for an item to reference. ### ConversationResource #### properties ##### id ###### type string ###### description The unique ID of the conversation. ##### object ###### type string ###### enum - conversation ###### description The object type, which is always `conversation`. ###### default conversation ###### x-stainless-const true ##### metadata ###### 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. ##### created_at ###### type integer ###### description The time at which the conversation was created, measured in seconds since the Unix epoch. #### type object #### required - id - object - metadata - created_at ### MetadataParam #### additionalProperties ##### type string ##### maxLength 512 #### type object #### maxProperties 16 ### UpdateConversationBody #### properties ##### metadata ###### $ref #/components/schemas/MetadataParam ###### 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. #### type object #### required - metadata ### DeletedConversationResource #### properties ##### object ###### type string ###### enum - conversation.deleted ###### default conversation.deleted ###### x-stainless-const true ##### deleted ###### type boolean ##### id ###### type string #### type object #### required - object - deleted - id ### InputTextContent-2 #### properties ##### type ###### type string ###### enum - input_text ###### description The type of the input item. Always `input_text`. ###### default input_text ###### x-stainless-const true ##### text ###### type string ###### description The text input to the model. #### type object #### required - type - text #### title Input text ### FileCitationBody-2 #### properties ##### type ###### type string ###### enum - file_citation ###### description The type of the file citation. Always `file_citation`. ###### default file_citation ###### x-stainless-const true ##### file_id ###### type string ###### description The ID of the file. ##### index ###### type integer ###### description The index of the file in the list of files. ##### filename ###### type string ###### description The filename of the file cited. #### type object #### required - type - file_id - index - filename #### title File citation ### UrlCitationBody-2 #### properties ##### type ###### type string ###### enum - url_citation ###### description The type of the URL citation. Always `url_citation`. ###### default url_citation ###### x-stainless-const true ##### url ###### type string ###### description The URL of the web resource. ##### start_index ###### type integer ###### description The index of the first character of the URL citation in the message. ##### end_index ###### type integer ###### description The index of the last character of the URL citation in the message. ##### title ###### type string ###### description The title of the web resource. #### type object #### required - type - url - start_index - end_index - title #### title URL citation ### ContainerFileCitationBody-2 #### properties ##### type ###### type string ###### enum - container_file_citation ###### description The type of the container file citation. Always `container_file_citation`. ###### default container_file_citation ###### x-stainless-const true ##### container_id ###### type string ###### description The ID of the container file. ##### file_id ###### type string ###### description The ID of the file. ##### start_index ###### type integer ###### description The index of the first character of the container file citation in the message. ##### end_index ###### type integer ###### description The index of the last character of the container file citation in the message. ##### filename ###### type string ###### description The filename of the container file cited. #### type object #### required - type - container_id - file_id - start_index - end_index - filename #### title Container file citation ### Annotation-2 #### discriminator ##### propertyName type #### anyOf ##### $ref #/components/schemas/FileCitationBody-2 ##### $ref #/components/schemas/UrlCitationBody-2 ##### $ref #/components/schemas/ContainerFileCitationBody-2 ### TopLogProb-2 #### properties ##### token ###### type string ##### logprob ###### type number ##### bytes ###### items ####### type integer ###### type array #### type object #### required - token - logprob - bytes #### title Top log probability ### LogProb-2 #### properties ##### token ###### type string ##### logprob ###### type number ##### bytes ###### items ####### type integer ###### type array ##### top_logprobs ###### items ####### $ref #/components/schemas/TopLogProb-2 ###### type array #### type object #### required - token - logprob - bytes - top_logprobs #### title Log probability ### OutputTextContent-2 #### properties ##### type ###### type string ###### enum - output_text ###### description The type of the output text. Always `output_text`. ###### default output_text ###### x-stainless-const true ##### text ###### type string ###### description The text output from the model. ##### annotations ###### items ####### $ref #/components/schemas/Annotation-2 ###### type array ###### description The annotations of the text output. ##### logprobs ###### items ####### $ref #/components/schemas/LogProb-2 ###### type array #### type object #### required - type - text - annotations #### title Output text ### TextContent #### properties ##### type ###### type string ###### enum - text ###### default text ###### x-stainless-const true ##### text ###### type string #### type object #### required - type - text #### title Text Content ### SummaryTextContent #### properties ##### type ###### type string ###### enum - summary_text ###### default summary_text ###### x-stainless-const true ##### text ###### type string #### type object #### required - type - text #### title Summary text ### RefusalContent-2 #### properties ##### type ###### type string ###### enum - refusal ###### description The type of the refusal. Always `refusal`. ###### default refusal ###### x-stainless-const true ##### refusal ###### type string ###### description The refusal explanation from the model. #### type object #### required - type - refusal #### title Refusal ### InputImageContent-2 #### properties ##### type ###### type string ###### enum - input_image ###### description The type of the input item. Always `input_image`. ###### default input_image ###### x-stainless-const true ##### image_url ###### anyOf ####### type string ####### description The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. ####### type null ##### file_id ###### anyOf ####### type string ####### description The ID of the file to be sent to the model. ####### type null ##### detail ###### type string ###### enum - low - high - auto ###### description The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`. #### type object #### required - type - image_url - file_id - detail #### title Input image ### ComputerScreenshotContent #### properties ##### type ###### type string ###### enum - computer_screenshot ###### description Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. ###### default computer_screenshot ###### x-stainless-const true ##### image_url ###### anyOf ####### type string ####### description The URL of the screenshot image. ####### type null ##### file_id ###### anyOf ####### type string ####### description The identifier of an uploaded file that contains the screenshot. ####### type null #### type object #### required - type - image_url - file_id #### title Computer screenshot ### InputFileContent-2 #### properties ##### type ###### type string ###### enum - input_file ###### description The type of the input item. Always `input_file`. ###### default input_file ###### x-stainless-const true ##### file_id ###### anyOf ####### type string ####### description The ID of the file to be sent to the model. ####### type null ##### filename ###### type string ###### description The name of the file to be sent to the model. ##### file_url ###### type string ###### description The URL of the file to be sent to the model. #### type object #### required - type - file_id #### title Input file ### Message #### properties ##### type ###### type string ###### enum - message ###### description The type of the message. Always set to `message`. ###### default message ###### x-stainless-const true ##### id ###### type string ###### description The unique ID of the message. ##### status ###### type string ###### enum - in_progress - completed - incomplete ###### description The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. ##### role ###### type string ###### enum - unknown - user - assistant - system - critic - discriminator - developer - tool ###### description The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. ##### content ###### items ####### discriminator ######## propertyName type ####### anyOf ######## $ref #/components/schemas/InputTextContent-2 ######## $ref #/components/schemas/OutputTextContent-2 ######## $ref #/components/schemas/TextContent ######## $ref #/components/schemas/SummaryTextContent ######## $ref #/components/schemas/RefusalContent-2 ######## $ref #/components/schemas/InputImageContent-2 ######## $ref #/components/schemas/ComputerScreenshotContent ######## $ref #/components/schemas/InputFileContent-2 ###### type array ###### description The content of the message #### type object #### required - type - id - status - role - content #### title Message ### FunctionTool #### properties ##### type ###### type string ###### enum - function ###### description The type of the function tool. Always `function`. ###### default function ###### x-stainless-const true ##### name ###### type string ###### description The name of the function to call. ##### description ###### anyOf ####### type string ####### description A description of the function. Used by the model to determine whether or not to call the function. ####### type null ##### parameters ###### anyOf ####### additionalProperties ####### type object ####### description A JSON schema object describing the parameters of the function. ####### type null ##### strict ###### anyOf ####### type boolean ####### description Whether to enforce strict parameter validation. Default `true`. ####### type null #### type object #### required - type - name - strict - parameters #### title Function #### description Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). ### RankingOptions #### properties ##### ranker ###### type string ###### enum - auto - default-2024-11-15 ###### description The ranker to use for the file search. ##### score_threshold ###### type number ###### description The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. #### type object #### required ### Filters #### anyOf ##### $ref #/components/schemas/ComparisonFilter ##### $ref #/components/schemas/CompoundFilter ### FileSearchTool #### properties ##### type ###### type string ###### enum - file_search ###### description The type of the file search tool. Always `file_search`. ###### default file_search ###### x-stainless-const true ##### vector_store_ids ###### items ####### type string ###### type array ###### description The IDs of the vector stores to search. ##### max_num_results ###### type integer ###### description The maximum number of results to return. This number should be between 1 and 50 inclusive. ##### ranking_options ###### $ref #/components/schemas/RankingOptions ###### description Ranking options for search. ##### filters ###### anyOf ####### $ref #/components/schemas/Filters ####### description A filter to apply. ####### type null #### type object #### required - type - vector_store_ids #### title File search #### description A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). ### ComputerUsePreviewTool #### properties ##### type ###### type string ###### enum - computer_use_preview ###### description The type of the computer use tool. Always `computer_use_preview`. ###### default computer_use_preview ###### x-stainless-const true ##### environment ###### type string ###### enum - windows - mac - linux - ubuntu - browser ###### description The type of computer environment to control. ##### display_width ###### type integer ###### description The width of the computer display. ##### display_height ###### type integer ###### description The height of the computer display. #### type object #### required - type - environment - display_width - display_height #### title Computer use preview #### description A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). ### ApproximateLocation #### properties ##### type ###### type string ###### enum - approximate ###### description The type of location approximation. Always `approximate`. ###### default approximate ###### x-stainless-const true ##### country ###### anyOf ####### type string ####### description The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. ####### type null ##### region ###### anyOf ####### type string ####### description Free text input for the region of the user, e.g. `California`. ####### type null ##### city ###### anyOf ####### type string ####### description Free text input for the city of the user, e.g. `San Francisco`. ####### type null ##### timezone ###### anyOf ####### type string ####### description The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. ####### type null #### type object #### required - type ### WebSearchPreviewTool #### properties ##### type ###### type string ###### enum - web_search_preview - web_search_preview_2025_03_11 ###### description The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. ###### default web_search_preview ###### x-stainless-const true ##### user_location ###### anyOf ####### $ref #/components/schemas/ApproximateLocation ####### description The user's location. ####### type null ##### search_context_size ###### type string ###### enum - low - medium - high ###### 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. #### type object #### required - type #### title Web search preview #### description This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). ### ImageGenInputUsageDetails #### properties ##### text_tokens ###### type integer ###### description The number of text tokens in the input prompt. ##### image_tokens ###### type integer ###### description The number of image tokens in the input prompt. #### type object #### required - text_tokens - image_tokens #### title Input usage details #### description The input tokens detailed information for the image generation. ### ImageGenUsage #### properties ##### input_tokens ###### type integer ###### description The number of tokens (images and text) in the input prompt. ##### total_tokens ###### type integer ###### description The total number of tokens (images and text) used for the image generation. ##### output_tokens ###### type integer ###### description The number of output tokens generated by the model. ##### input_tokens_details ###### $ref #/components/schemas/ImageGenInputUsageDetails #### type object #### required - input_tokens - total_tokens - output_tokens - input_tokens_details #### title Image generation usage #### description For `gpt-image-1` only, the token usage information for the image generation. ### ConversationParam #### properties ##### id ###### type string ###### description The unique ID of the conversation. #### type object #### required - id #### title Conversation object #### description The conversation that this response belongs to. ### Conversation-2 #### properties ##### id ###### type string ###### description The unique ID of the conversation. #### type object #### required - id #### title Conversation #### description The conversation that this response belongs to. Input items and output items from this response are automatically added to this conversation. ### RealtimeConversationItemContent #### type object #### properties ##### type ###### type string ###### enum - input_text - input_audio - item_reference - text - audio ###### description The content type (`input_text`, `input_audio`, `item_reference`, `text`, `audio`). ##### 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` and `audio` content types. ### RealtimeConnectParams #### type object #### properties ##### model ###### type string #### required - model ### ModerationImageURLInput #### type object #### description An object describing an image to classify. #### properties ##### type ###### description Always `image_url`. ###### type string ###### enum - image_url ###### x-stainless-const true ##### image_url ###### type object ###### description Contains either an image URL or a data URL for a base64 encoded image. ###### properties ####### url ######## type string ######## description Either a URL of the image or the base64 encoded image data. ######## format uri ######## example https://example.com/image.jpg ###### required - url #### required - type - image_url ### ModerationTextInput #### type object #### description An object describing text to classify. #### properties ##### type ###### description Always `text`. ###### type string ###### enum - text ###### x-stainless-const true ##### text ###### description A string of text to classify. ###### type string ###### example I want to kill them #### required - type - text ### ChunkingStrategyResponse #### type object #### description The strategy used to chunk the file. #### anyOf ##### $ref #/components/schemas/StaticChunkingStrategyResponseParam ##### $ref #/components/schemas/OtherChunkingStrategyResponseParam #### discriminator ##### propertyName type ### FilePurpose #### description 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 ### BatchError #### 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 ### BatchRequestCounts #### type object #### 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. #### required - total - completed - failed #### description The request counts for different statuses within the batch. ### AssistantTool #### anyOf ##### $ref #/components/schemas/AssistantToolsCode ##### $ref #/components/schemas/AssistantToolsFileSearch ##### $ref #/components/schemas/AssistantToolsFunction #### discriminator ##### propertyName type ### TextAnnotationDelta #### anyOf ##### $ref #/components/schemas/MessageDeltaContentTextAnnotationsFileCitationObject ##### $ref #/components/schemas/MessageDeltaContentTextAnnotationsFilePathObject #### discriminator ##### propertyName type ### TextAnnotation #### anyOf ##### $ref #/components/schemas/MessageContentTextAnnotationsFileCitationObject ##### $ref #/components/schemas/MessageContentTextAnnotationsFilePathObject #### discriminator ##### propertyName type ### RunStepDetailsToolCall #### anyOf ##### $ref #/components/schemas/RunStepDetailsToolCallsCodeObject ##### $ref #/components/schemas/RunStepDetailsToolCallsFileSearchObject ##### $ref #/components/schemas/RunStepDetailsToolCallsFunctionObject #### discriminator ##### propertyName type ### RunStepDeltaStepDetailsToolCall #### anyOf ##### $ref #/components/schemas/RunStepDeltaStepDetailsToolCallsCodeObject ##### $ref #/components/schemas/RunStepDeltaStepDetailsToolCallsFileSearchObject ##### $ref #/components/schemas/RunStepDeltaStepDetailsToolCallsFunctionObject #### discriminator ##### propertyName type ### MessageContent #### anyOf ##### $ref #/components/schemas/MessageContentImageFileObject ##### $ref #/components/schemas/MessageContentImageUrlObject ##### $ref #/components/schemas/MessageContentTextObject ##### $ref #/components/schemas/MessageContentRefusalObject #### discriminator ##### propertyName type ### MessageContentDelta #### anyOf ##### $ref #/components/schemas/MessageDeltaContentImageFileObject ##### $ref #/components/schemas/MessageDeltaContentTextObject ##### $ref #/components/schemas/MessageDeltaContentRefusalObject ##### $ref #/components/schemas/MessageDeltaContentImageUrlObject #### discriminator ##### propertyName type ### ChatModel #### type string #### enum - gpt-5 - gpt-5-mini - gpt-5-nano - gpt-5-2025-08-07 - gpt-5-mini-2025-08-07 - gpt-5-nano-2025-08-07 - gpt-5-chat-latest - gpt-4.1 - gpt-4.1-mini - gpt-4.1-nano - gpt-4.1-2025-04-14 - gpt-4.1-mini-2025-04-14 - gpt-4.1-nano-2025-04-14 - o4-mini - o4-mini-2025-04-16 - o3 - o3-2025-04-16 - o3-mini - o3-mini-2025-01-31 - o1 - o1-2024-12-17 - o1-preview - o1-preview-2024-09-12 - o1-mini - o1-mini-2024-09-12 - gpt-4o - gpt-4o-2024-11-20 - gpt-4o-2024-08-06 - gpt-4o-2024-05-13 - gpt-4o-audio-preview - gpt-4o-audio-preview-2024-10-01 - gpt-4o-audio-preview-2024-12-17 - gpt-4o-audio-preview-2025-06-03 - gpt-4o-mini-audio-preview - gpt-4o-mini-audio-preview-2024-12-17 - gpt-4o-search-preview - gpt-4o-mini-search-preview - gpt-4o-search-preview-2025-03-11 - gpt-4o-mini-search-preview-2025-03-11 - chatgpt-4o-latest - codex-mini-latest - gpt-4o-mini - gpt-4o-mini-2024-07-18 - gpt-4-turbo - gpt-4-turbo-2024-04-09 - gpt-4-0125-preview - gpt-4-turbo-preview - gpt-4-1106-preview - gpt-4-vision-preview - gpt-4 - gpt-4-0314 - gpt-4-0613 - gpt-4-32k - gpt-4-32k-0314 - gpt-4-32k-0613 - gpt-3.5-turbo - gpt-3.5-turbo-16k - gpt-3.5-turbo-0301 - gpt-3.5-turbo-0613 - gpt-3.5-turbo-1106 - gpt-3.5-turbo-0125 - gpt-3.5-turbo-16k-0613 #### x-stainless-nominal false ### CreateThreadAndRunRequestWithoutStream #### type object #### additionalProperties false #### properties ##### assistant_id ###### description The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. ###### type string ##### thread ###### $ref #/components/schemas/CreateThreadRequest ##### model ###### description The ID of the [Model](https://platform.openai.com/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. ###### anyOf ####### type string ####### type string ####### enum - gpt-5 - gpt-5-mini - gpt-5-nano - gpt-5-2025-08-07 - gpt-5-mini-2025-08-07 - gpt-5-nano-2025-08-07 - gpt-4.1 - gpt-4.1-mini - gpt-4.1-nano - gpt-4.1-2025-04-14 - gpt-4.1-mini-2025-04-14 - gpt-4.1-nano-2025-04-14 - 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 ####### $ref #/components/schemas/AssistantTool ##### 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](https://platform.openai.com/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](https://platform.openai.com/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. ##### 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 ### CreateRunRequestWithoutStream #### type object #### additionalProperties false #### properties ##### assistant_id ###### description The ID of the [assistant](https://platform.openai.com/docs/api-reference/assistants) to use to execute this run. ###### type string ##### model ###### description The ID of the [Model](https://platform.openai.com/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. ###### anyOf ####### type string ####### $ref #/components/schemas/AssistantSupportedModels ###### x-oaiTypeLabel string ###### nullable true ##### reasoning_effort ###### $ref #/components/schemas/ReasoningEffort ##### instructions ###### description Overrides the [instructions](https://platform.openai.com/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 ####### $ref #/components/schemas/AssistantTool ##### 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. ##### 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 ### SubmitToolOutputsRunRequestWithoutStream #### type object #### additionalProperties false #### properties ##### tool_outputs ###### description A list of tools for which the outputs are being submitted. ###### type array ###### items ####### type object ####### properties ######## tool_call_id ######### type string ######### description The ID of the tool call in the `required_action` object within the run object the output is being submitted for. ######## output ######### type string ######### description The output of the tool call to be submitted to continue the run. #### required - tool_outputs ### RunStatus #### description The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. #### type string #### enum - queued - in_progress - requires_action - cancelling - cancelled - failed - completed - incomplete - expired ### RunStepDeltaObjectDelta #### description The delta containing the fields that have changed on the run step. #### type object #### properties ##### step_details ###### type object ###### description The details of the run step. ###### anyOf ####### $ref #/components/schemas/RunStepDeltaStepDetailsMessageCreationObject ####### $ref #/components/schemas/RunStepDeltaStepDetailsToolCallsObject ###### discriminator ####### propertyName type ## securitySchemes ### ApiKeyAuth #### type http #### scheme bearer # x-oaiMeta ## navigationGroups ### id responses ### title Responses API ### id webhooks ### title Webhooks ### id endpoints ### title Platform APIs ### id vector_stores ### title Vector stores ### id containers ### title Containers ### id realtime ### title Realtime ### beta true ### id chat ### title Chat Completions ### id assistants ### title Assistants ### beta true ### id administration ### title Administration ### id legacy ### title Legacy ## groups ### id responses ### title Responses ### description OpenAI's most advanced interface for generating model responses. Supports 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](https://platform.openai.com/docs/quickstart?api-mode=responses) - [Text inputs and outputs](https://platform.openai.com/docs/guides/text?api-mode=responses) - [Image inputs](https://platform.openai.com/docs/guides/images?api-mode=responses) - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs?api-mode=responses) - [Function calling](https://platform.openai.com/docs/guides/function-calling?api-mode=responses) - [Conversation state](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) - [Extend the models with tools](https://platform.openai.com/docs/guides/tools?api-mode=responses) ### navigationGroup responses ### sections #### type endpoint #### key createResponse #### path create #### type endpoint #### key getResponse #### path get #### type endpoint #### key deleteResponse #### path delete #### type endpoint #### key cancelResponse #### path cancel #### type endpoint #### key listInputItems #### path input-items #### type object #### key Response #### path object #### type object #### key ResponseItemList #### path list ### id conversations ### title Conversations ### description Create and manage conversations to store and retrieve conversation state across Response API calls. ### navigationGroup responses ### sections #### type endpoint #### key createConversation #### path create #### type endpoint #### key getConversation #### path retrieve #### type endpoint #### key updateConversation #### path update #### type endpoint #### key deleteConversation #### path delete #### type endpoint #### key listConversationItems #### path list-items #### type endpoint #### key createConversationItems #### path create-items #### type endpoint #### key getConversationItem #### path get-item #### type endpoint #### key deleteConversationItem #### path delete-item #### type object #### key Conversation #### path object #### type object #### key ConversationItemList #### path list-items-object ### id responses-streaming ### title Streaming events ### description When you [create a Response](https://platform.openai.com/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](https://platform.openai.com/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 response/output_text/delta #### type object #### key ResponseTextDoneEvent #### path response/output_text/done #### 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 ResponseReasoningSummaryPartAddedEvent #### path #### type object #### key ResponseReasoningSummaryPartDoneEvent #### path #### type object #### key ResponseReasoningSummaryTextDeltaEvent #### path #### type object #### key ResponseReasoningSummaryTextDoneEvent #### path #### type object #### key ResponseReasoningTextDeltaEvent #### path #### type object #### key ResponseReasoningTextDoneEvent #### path #### type object #### key ResponseImageGenCallCompletedEvent #### path #### type object #### key ResponseImageGenCallGeneratingEvent #### path #### type object #### key ResponseImageGenCallInProgressEvent #### path #### type object #### key ResponseImageGenCallPartialImageEvent #### path #### type object #### key ResponseMCPCallArgumentsDeltaEvent #### path #### type object #### key ResponseMCPCallArgumentsDoneEvent #### path #### type object #### key ResponseMCPCallCompletedEvent #### path #### type object #### key ResponseMCPCallFailedEvent #### path #### type object #### key ResponseMCPCallInProgressEvent #### path #### type object #### key ResponseMCPListToolsCompletedEvent #### path #### type object #### key ResponseMCPListToolsFailedEvent #### path #### type object #### key ResponseMCPListToolsInProgressEvent #### path #### type object #### key ResponseCodeInterpreterCallInProgressEvent #### path #### type object #### key ResponseCodeInterpreterCallInterpretingEvent #### path #### type object #### key ResponseCodeInterpreterCallCompletedEvent #### path #### type object #### key ResponseCodeInterpreterCallCodeDeltaEvent #### path #### type object #### key ResponseCodeInterpreterCallCodeDoneEvent #### path #### type object #### key ResponseOutputTextAnnotationAddedEvent #### path #### type object #### key ResponseQueuedEvent #### path #### type object #### key ResponseCustomToolCallInputDeltaEvent #### path #### type object #### key ResponseCustomToolCallInputDoneEvent #### path #### type object #### key ResponseErrorEvent #### path ### id webhook-events ### title Webhook Events ### description Webhooks are HTTP requests sent by OpenAI to a URL you specify when certain events happen during the course of API usage. [Learn more about webhooks](https://platform.openai.com/docs/guides/webhooks). ### navigationGroup webhooks ### sections #### type object #### key WebhookResponseCompleted #### path #### type object #### key WebhookResponseCancelled #### path #### type object #### key WebhookResponseFailed #### path #### type object #### key WebhookResponseIncomplete #### path #### type object #### key WebhookBatchCompleted #### path #### type object #### key WebhookBatchCancelled #### path #### type object #### key WebhookBatchExpired #### path #### type object #### key WebhookBatchFailed #### path #### type object #### key WebhookFineTuningJobSucceeded #### path #### type object #### key WebhookFineTuningJobFailed #### path #### type object #### key WebhookFineTuningJobCancelled #### path #### type object #### key WebhookEvalRunSucceeded #### path #### type object #### key WebhookEvalRunFailed #### path #### type object #### key WebhookEvalRunCanceled #### path ### id audio ### title Audio ### description Learn how to turn audio into text or text into audio. Related guide: [Speech to text](https://platform.openai.com/docs/guides/speech-to-text) ### navigationGroup endpoints ### sections #### type endpoint #### key createSpeech #### path createSpeech #### type endpoint #### key createTranscription #### path createTranscription #### type endpoint #### key createTranslation #### path createTranslation #### type object #### key CreateTranscriptionResponseJson #### path json-object #### type object #### key CreateTranscriptionResponseVerboseJson #### path verbose-json-object #### type object #### key SpeechAudioDeltaEvent #### path speech-audio-delta-event #### type object #### key SpeechAudioDoneEvent #### path speech-audio-done-event #### type object #### key TranscriptTextDeltaEvent #### path transcript-text-delta-event #### type object #### key TranscriptTextDoneEvent #### path transcript-text-done-event ### id images ### title Images ### description Given a prompt and/or an input image, the model will generate a new image. Related guide: [Image generation](https://platform.openai.com/docs/guides/images) ### navigationGroup endpoints ### sections #### type endpoint #### key createImage #### path create #### type endpoint #### key createImageEdit #### path createEdit #### type endpoint #### key createImageVariation #### path createVariation #### type object #### key ImagesResponse #### path object ### id images-streaming ### title Image Streaming ### description Stream image generation and editing in real time with server-sent events. [Learn more about image streaming](https://platform.openai.com/docs/guides/image-generation). ### navigationGroup endpoints ### sections #### type object #### key ImageGenPartialImageEvent #### path #### type object #### key ImageGenCompletedEvent #### path #### type object #### key ImageEditPartialImageEvent #### path #### type object #### key ImageEditCompletedEvent #### path ### id embeddings ### title Embeddings ### description Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms. Related guide: [Embeddings](https://platform.openai.com/docs/guides/embeddings) ### navigationGroup endpoints ### sections #### type endpoint #### key createEmbedding #### path create #### type object #### key Embedding #### path object ### id evals ### title Evals ### description Create, manage, and run evals in the OpenAI platform. Related guide: [Evals](https://platform.openai.com/docs/guides/evals) ### navigationGroup endpoints ### sections #### type endpoint #### key createEval #### path create #### type endpoint #### key getEval #### path get #### type endpoint #### key updateEval #### path update #### type endpoint #### key deleteEval #### path delete #### type endpoint #### key listEvals #### path list #### type endpoint #### key getEvalRuns #### path getRuns #### type endpoint #### key getEvalRun #### path getRun #### type endpoint #### key createEvalRun #### path createRun #### type endpoint #### key cancelEvalRun #### path cancelRun #### type endpoint #### key deleteEvalRun #### path deleteRun #### type endpoint #### key getEvalRunOutputItem #### path getRunOutputItem #### type endpoint #### key getEvalRunOutputItems #### path getRunOutputItems #### type object #### key Eval #### path object #### type object #### key EvalRun #### path run-object #### type object #### key EvalRunOutputItem #### path run-output-item-object ### id fine-tuning ### title Fine-tuning ### description Manage fine-tuning jobs to tailor a model to your specific training data. Related guide: [Fine-tune models](https://platform.openai.com/docs/guides/fine-tuning) ### navigationGroup endpoints ### sections #### type endpoint #### key createFineTuningJob #### path create #### type endpoint #### key listPaginatedFineTuningJobs #### path list #### type endpoint #### key listFineTuningEvents #### path list-events #### type endpoint #### key listFineTuningJobCheckpoints #### path list-checkpoints #### type endpoint #### key listFineTuningCheckpointPermissions #### path list-permissions #### type endpoint #### key createFineTuningCheckpointPermission #### path create-permission #### type endpoint #### key deleteFineTuningCheckpointPermission #### path delete-permission #### type endpoint #### key retrieveFineTuningJob #### path retrieve #### type endpoint #### key cancelFineTuningJob #### path cancel #### type endpoint #### key resumeFineTuningJob #### path resume #### type endpoint #### key pauseFineTuningJob #### path pause #### type object #### key FineTuneChatRequestInput #### path chat-input #### type object #### key FineTunePreferenceRequestInput #### path preference-input #### type object #### key FineTuneReinforcementRequestInput #### path reinforcement-input #### type object #### key FineTuningJob #### path object #### type object #### key FineTuningJobEvent #### path event-object #### type object #### key FineTuningJobCheckpoint #### path checkpoint-object #### type object #### key FineTuningCheckpointPermission #### path permission-object ### id graders ### title Graders ### description Manage and run graders in the OpenAI platform. Related guide: [Graders](https://platform.openai.com/docs/guides/graders) ### navigationGroup endpoints ### sections #### type object #### key GraderStringCheck #### path string-check #### type object #### key GraderTextSimilarity #### path text-similarity #### type object #### key GraderScoreModel #### path score-model #### type object #### key GraderLabelModel #### path label-model #### type object #### key GraderPython #### path python #### type object #### key GraderMulti #### path multi #### type endpoint #### key runGrader #### path run #### type endpoint #### key validateGrader #### path validate #### beta true ### id batch ### title Batch ### description Create large batches of API requests for asynchronous processing. The Batch API returns completions within 24 hours for a 50% discount. Related guide: [Batch](https://platform.openai.com/docs/guides/batch) ### navigationGroup endpoints ### sections #### type endpoint #### key createBatch #### path create #### type endpoint #### key retrieveBatch #### path retrieve #### type endpoint #### key cancelBatch #### path cancel #### type endpoint #### key listBatches #### path list #### type object #### key Batch #### path object #### type object #### key BatchRequestInput #### path request-input #### type object #### key BatchRequestOutput #### path request-output ### id files ### title Files ### description Files are used to upload documents that can be used with features like [Assistants](https://platform.openai.com/docs/api-reference/assistants), [Fine-tuning](https://platform.openai.com/docs/api-reference/fine-tuning), and [Batch API](https://platform.openai.com/docs/guides/batch). ### navigationGroup endpoints ### sections #### type endpoint #### key createFile #### path create #### type endpoint #### key listFiles #### path list #### type endpoint #### key retrieveFile #### path retrieve #### type endpoint #### key deleteFile #### path delete #### type endpoint #### key downloadFile #### path retrieve-contents #### type object #### key OpenAIFile #### path object ### id uploads ### title Uploads ### description Allows you to upload large files in multiple parts. ### navigationGroup endpoints ### sections #### type endpoint #### key createUpload #### path create #### type endpoint #### key addUploadPart #### path add-part #### type endpoint #### key completeUpload #### path complete #### type endpoint #### key cancelUpload #### path cancel #### type object #### key Upload #### path object #### type object #### key UploadPart #### path part-object ### id models ### title Models ### description List and describe the various models available in the API. You can refer to the [Models](https://platform.openai.com/docs/models) documentation to understand what models are available and the differences between them. ### navigationGroup endpoints ### sections #### type endpoint #### key listModels #### path list #### type endpoint #### key retrieveModel #### path retrieve #### type endpoint #### key deleteModel #### path delete #### type object #### key Model #### path object ### id moderations ### title Moderations ### description Given text and/or image inputs, classifies if those inputs are potentially harmful across several categories. Related guide: [Moderations](https://platform.openai.com/docs/guides/moderation) ### navigationGroup endpoints ### sections #### type endpoint #### key createModeration #### path create #### type object #### key CreateModerationResponse #### path object ### id vector-stores ### title Vector stores ### 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](https://platform.openai.com/docs/assistants/tools/file-search) ### navigationGroup vector_stores ### sections #### type endpoint #### key createVectorStore #### path create #### type endpoint #### key listVectorStores #### path list #### type endpoint #### key getVectorStore #### path retrieve #### type endpoint #### key modifyVectorStore #### path modify #### 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 ### description Vector store files represent files inside a vector store. Related guide: [File Search](https://platform.openai.com/docs/assistants/tools/file-search) ### navigationGroup vector_stores ### sections #### type endpoint #### key createVectorStoreFile #### path createFile #### type endpoint #### key listVectorStoreFiles #### path listFiles #### type endpoint #### key getVectorStoreFile #### path getFile #### type endpoint #### key retrieveVectorStoreFileContent #### path getContent #### type endpoint #### key updateVectorStoreFileAttributes #### path updateAttributes #### type endpoint #### key deleteVectorStoreFile #### path deleteFile #### type object #### key VectorStoreFileObject #### path file-object ### id vector-stores-file-batches ### title Vector store file batches ### description Vector store file batches represent operations to add multiple files to a vector store. Related guide: [File Search](https://platform.openai.com/docs/assistants/tools/file-search) ### navigationGroup vector_stores ### sections #### type endpoint #### key createVectorStoreFileBatch #### path createBatch #### type endpoint #### key getVectorStoreFileBatch #### path getBatch #### type endpoint #### key cancelVectorStoreFileBatch #### path cancelBatch #### type endpoint #### key listFilesInVectorStoreBatch #### path listBatchFiles #### type object #### key VectorStoreFileBatchObject #### path batch-object ### id containers ### title Containers ### description Create and manage containers for use with the Code Interpreter tool. ### navigationGroup containers ### sections #### type endpoint #### key CreateContainer #### path createContainers #### type endpoint #### key ListContainers #### path listContainers #### type endpoint #### key RetrieveContainer #### path retrieveContainer #### type endpoint #### key DeleteContainer #### path deleteContainer #### type object #### key ContainerResource #### path object ### id container-files ### title Container Files ### description Create and manage container files for use with the Code Interpreter tool. ### navigationGroup containers ### sections #### type endpoint #### key CreateContainerFile #### path createContainerFile #### type endpoint #### key ListContainerFiles #### path listContainerFiles #### type endpoint #### key RetrieveContainerFile #### path retrieveContainerFile #### type endpoint #### key RetrieveContainerFileContent #### path retrieveContainerFileContent #### type endpoint #### key DeleteContainerFile #### path deleteContainerFile #### type object #### key ContainerFileResource #### path object ### id realtime ### title Realtime ### 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](https://platform.openai.com/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 applications. ### navigationGroup realtime ### sections #### type endpoint #### key create-realtime-session #### path create #### type endpoint #### key create-realtime-transcription-session #### path create-transcription #### type object #### key RealtimeSessionCreateResponse #### path session_object #### type object #### key RealtimeTranscriptionSessionCreateResponse #### path transcription_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 RealtimeClientEventConversationItemRetrieve #### path #### type object #### key RealtimeClientEventConversationItemTruncate #### path #### type object #### key RealtimeClientEventConversationItemDelete #### path #### type object #### key RealtimeClientEventResponseCreate #### path #### type object #### key RealtimeClientEventResponseCancel #### path #### type object #### key RealtimeClientEventTranscriptionSessionUpdate #### path #### type object #### key RealtimeClientEventOutputAudioBufferClear #### 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 RealtimeServerEventConversationItemRetrieved #### path #### type object #### key RealtimeServerEventConversationItemInputAudioTranscriptionCompleted #### path #### type object #### key RealtimeServerEventConversationItemInputAudioTranscriptionDelta #### 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 #### type object #### key RealtimeServerEventResponseFunctionCallArgumentsDone #### path #### type object #### key RealtimeServerEventTranscriptionSessionUpdated #### path #### type object #### key RealtimeServerEventRateLimitsUpdated #### path #### type object #### key RealtimeServerEventOutputAudioBufferStarted #### path #### type object #### key RealtimeServerEventOutputAudioBufferStopped #### path #### type object #### key RealtimeServerEventOutputAudioBufferCleared #### path ### 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](https://platform.openai.com/docs/quickstart?api-mode=chat) - [Text inputs and outputs](https://platform.openai.com/docs/guides/text?api-mode=chat) - [Image inputs](https://platform.openai.com/docs/guides/images?api-mode=chat) - [Audio inputs and outputs](https://platform.openai.com/docs/guides/audio?api-mode=chat) - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat) - [Function calling](https://platform.openai.com/docs/guides/function-calling?api-mode=chat) - [Conversation state](https://platform.openai.com/docs/guides/conversation-state?api-mode=chat) **Starting a new project?** We recommend trying [Responses](https://platform.openai.com/docs/api-reference/responses) to take advantage of the latest OpenAI platform features. Compare [Chat Completions with Responses](https://platform.openai.com/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](https://platform.openai.com/docs/guides/streaming-responses?api-mode=chat). ### navigationGroup chat ### sections #### type object #### key CreateChatCompletionStreamResponse #### path streaming ### 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](https://platform.openai.com/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](https://platform.openai.com/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](https://platform.openai.com/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 #### type object #### key MessageObject #### path object ### id runs ### title Runs ### beta true ### description Represents an execution run on a thread. Related guide: [Assistants](https://platform.openai.com/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 #### 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](https://platform.openai.com/docs/assistants/overview) ### navigationGroup assistants ### sections #### type endpoint #### key listRunSteps #### path listRunSteps #### type endpoint #### key getRunStep #### path getRunStep #### type object #### key RunStepObject #### path step-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](https://platform.openai.com/docs/api-reference/runs/createThreadAndRun), [Create Run](https://platform.openai.com/docs/api-reference/runs/createRun), and [Submit Tool Outputs](https://platform.openai.com/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](https://platform.openai.com/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 Programmatically manage your organization. The Audit Logs endpoint provides a log of all actions taken in the organization for security and monitoring purposes. To access these endpoints please generate an Admin API Key through the [API Platform Organization overview](/organization/admin-keys). Admin API keys cannot be used for non-administration endpoints. For best practices on setting up your organization, please refer to this [guide](https://platform.openai.com/docs/guides/production-best-practices#setting-up-your-organization) ### navigationGroup administration ### id admin-api-keys ### title Admin API Keys ### description Admin API keys enable Organization Owners to programmatically manage various aspects of their organization, including users, projects, and API keys. These keys provide administrative capabilities, such as creating, updating, and deleting users; managing projects; and overseeing API key lifecycles. Key Features of Admin API Keys: - User Management: Invite new users, update roles, and remove users from the organization. - Project Management: Create, update, archive projects, and manage user assignments within projects. - API Key Oversight: List, retrieve, and delete API keys associated with projects. Only Organization Owners have the authority to create and utilize Admin API keys. To manage these keys, Organization Owners can navigate to the Admin Keys section of their API Platform dashboard. For direct access to the Admin Keys management page, Organization Owners can use the following link: [https://platform.openai.com/settings/organization/admin-keys](https://platform.openai.com/settings/organization/admin-keys) It's crucial to handle Admin API keys with care due to their elevated permissions. Adhering to best practices, such as regular key rotation and assigning appropriate permissions, enhances security and ensures proper governance within the organization. ### navigationGroup administration ### sections #### type endpoint #### key admin-api-keys-list #### path list #### type endpoint #### key admin-api-keys-create #### path create #### type endpoint #### key admin-api-keys-get #### path listget #### type endpoint #### key admin-api-keys-delete #### path delete #### type object #### key AdminApiKey #### path object ### id invite ### title Invites ### description Invite and manage invitations for an organization. ### navigationGroup administration ### sections #### type endpoint #### key list-invites #### path list #### type endpoint #### key inviteUser #### path create #### type endpoint #### key retrieve-invite #### path retrieve #### type endpoint #### key delete-invite #### path delete #### type object #### key Invite #### path object ### id users ### title Users ### description Manage users and their role in an organization. ### navigationGroup administration ### sections #### type endpoint #### key list-users #### path list #### type endpoint #### key modify-user #### path modify #### type endpoint #### key retrieve-user #### path retrieve #### type endpoint #### key delete-user #### path delete #### type object #### key User #### path object ### id projects ### title Projects ### description Manage the projects within an orgnanization includes creation, updating, and archiving or projects. The Default project cannot be archived. ### navigationGroup administration ### sections #### type endpoint #### key list-projects #### path list #### type endpoint #### key create-project #### path create #### type endpoint #### key retrieve-project #### path retrieve #### type endpoint #### key modify-project #### path modify #### type endpoint #### key archive-project #### path archive #### type object #### key Project #### path object ### id project-users ### title Project users ### description Manage users within a project, including adding, updating roles, and removing users. ### navigationGroup administration ### sections #### type endpoint #### key list-project-users #### path list #### type endpoint #### key create-project-user #### path create #### type endpoint #### key retrieve-project-user #### path retrieve #### type endpoint #### key modify-project-user #### path modify #### type endpoint #### key delete-project-user #### path delete #### type object #### key ProjectUser #### path object ### id project-service-accounts ### title Project service accounts ### description Manage service accounts within a project. A service account is a bot user that is not associated with a user. If a user leaves an organization, their keys and membership in projects will no longer work. Service accounts do not have this limitation. However, service accounts can also be deleted from a project. ### navigationGroup administration ### sections #### type endpoint #### key list-project-service-accounts #### path list #### type endpoint #### key create-project-service-account #### path create #### type endpoint #### key retrieve-project-service-account #### path retrieve #### type endpoint #### key delete-project-service-account #### path delete #### type object #### key ProjectServiceAccount #### path object ### id project-api-keys ### title Project API keys ### description Manage API keys for a given project. Supports listing and deleting keys for users. This API does not allow issuing keys for users, as users need to authorize themselves to generate keys. ### navigationGroup administration ### sections #### type endpoint #### key list-project-api-keys #### path list #### type endpoint #### key retrieve-project-api-key #### path retrieve #### type endpoint #### key delete-project-api-key #### path delete #### type object #### key ProjectApiKey #### path object ### id project-rate-limits ### title Project rate limits ### description Manage rate limits per model for projects. Rate limits may be configured to be equal to or lower than the organization's rate limits. ### navigationGroup administration ### sections #### type endpoint #### key list-project-rate-limits #### path list #### type endpoint #### key update-project-rate-limits #### path update #### type object #### key ProjectRateLimit #### path object ### id audit-logs ### title Audit logs ### description Logs of user actions and configuration changes within this organization. To log events, an Organization Owner must activate logging in the [Data Controls Settings](/settings/organization/data-controls/data-retention). Once activated, for security reasons, logging cannot be deactivated. ### navigationGroup administration ### sections #### type endpoint #### key list-audit-logs #### path list #### type object #### key AuditLog #### path object ### id usage ### title Usage ### description The **Usage API** provides detailed insights into your activity across the OpenAI API. It also includes a separate [Costs endpoint](https://platform.openai.com/docs/api-reference/usage/costs), which offers visibility into your spend, breaking down consumption by invoice line items and project IDs. While the Usage API delivers granular usage data, it may not always reconcile perfectly with the Costs due to minor differences in how usage and spend are recorded. For financial purposes, we recommend using the [Costs endpoint](https://platform.openai.com/docs/api-reference/usage/costs) or the [Costs tab](/settings/organization/usage) in the Usage Dashboard, which will reconcile back to your billing invoice. ### navigationGroup administration ### sections #### type endpoint #### 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 certificates ### beta true ### title Certificates ### description Manage Mutual TLS certificates across your organization and projects. [Learn more about Mutual TLS.](https://help.openai.com/en/articles/10876024-openai-mutual-tls-beta-program) ### navigationGroup administration ### sections #### type endpoint #### key uploadCertificate #### path uploadCertificate #### type endpoint #### key getCertificate #### path getCertificate #### type endpoint #### key modifyCertificate #### path modifyCertificate #### type endpoint #### key deleteCertificate #### path deleteCertificate #### type endpoint #### key listOrganizationCertificates #### path listOrganizationCertificates #### type endpoint #### key listProjectCertificates #### path listProjectCertificates #### type endpoint #### key activateOrganizationCertificates #### path activateOrganizationCertificates #### type endpoint #### key deactivateOrganizationCertificates #### path deactivateOrganizationCertificates #### type endpoint #### key activateProjectCertificates #### path activateProjectCertificates #### type endpoint #### key deactivateProjectCertificates #### path deactivateProjectCertificates #### type object #### key Certificate #### path object ### id completions ### title Completions ### legacy true ### navigationGroup legacy ### description Given a prompt, the model will return one or more predicted completions along with the probabilities of alternative tokens at each position. Most developer should use our [Chat Completions API](https://platform.openai.com/docs/guides/text-generation#text-generation-models) to leverage our best and newest models. ### sections #### type endpoint #### key createCompletion #### path create #### type object #### key CreateCompletionResponse #### path object