openapi: 3.0.0 info: title: OpenAI Assistants Audio API description: The Assistants API allows you to build AI assistants within your own applications. An Assistant has instructions and can leverage models, tools, and knowledge to respond to user queries. The Assistants API currently supports three types of tools - Code Interpreter, Retrieval, and Function calling. In the future, we plan to release more OpenAI-built tools, and allow you to provide your own tools on our platform. version: 2.0.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: Audio description: Learn how to turn audio into text or text into audio. paths: /audio/speech: post: operationId: createSpeech tags: - Audio summary: OpenAI Generates audio from the input text. 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 x-oaiMeta: name: Create speech group: audio returns: The audio file content. examples: request: curl: "curl https://api.openai.com/v1/audio/speech \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"tts-1\",\n \"input\": \"The quick brown fox jumped over the lazy dog.\",\n \"voice\": \"alloy\"\n }' \\\n --output speech.mp3\n" python: "from pathlib import Path\nimport openai\n\nspeech_file_path = Path(__file__).parent / \"speech.mp3\"\nresponse = openai.audio.speech.create(\n model=\"tts-1\",\n voice=\"alloy\",\n input=\"The quick brown fox jumped over the lazy dog.\"\n)\nresponse.stream_to_file(speech_file_path)\n" node: "import fs from \"fs\";\nimport path from \"path\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst speechFile = path.resolve(\"./speech.mp3\");\n\nasync function main() {\n const mp3 = await openai.audio.speech.create({\n model: \"tts-1\",\n voice: \"alloy\",\n input: \"Today is a wonderful day to build something people love!\",\n });\n console.log(speechFile);\n const buffer = Buffer.from(await mp3.arrayBuffer());\n await fs.promises.writeFile(speechFile, buffer);\n}\nmain();\n" /audio/transcriptions: post: operationId: createTranscription tags: - Audio summary: OpenAI Transcribes audio into the input language. requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/CreateTranscriptionRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateTranscriptionResponse' x-oaiMeta: name: Create transcription group: audio returns: The transcribed text. examples: request: curl: "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/audio.mp3\" \\\n -F model=\"whisper-1\"\n" python: "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.transcriptions.create(\n model=\"whisper-1\",\n file=audio_file\n)\n" node: "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const transcription = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"audio.mp3\"),\n model: \"whisper-1\",\n });\n\n console.log(transcription.text);\n}\nmain();\n" response: "{\n \"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.\"\n}\n" /audio/translations: post: operationId: createTranslation tags: - Audio summary: OpenAI Translates audio into English. requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/CreateTranslationRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateTranslationResponse' x-oaiMeta: name: Create translation group: audio returns: The translated text. examples: request: curl: "curl https://api.openai.com/v1/audio/translations \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/german.m4a\" \\\n -F model=\"whisper-1\"\n" python: "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.translations.create(\n model=\"whisper-1\",\n file=audio_file\n)\n" node: "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const translation = await openai.audio.translations.create({\n file: fs.createReadStream(\"speech.mp3\"),\n model: \"whisper-1\",\n });\n\n console.log(translation.text);\n}\nmain();\n" response: "{\n \"text\": \"Hello, my name is Wolfgang and I come from Germany. Where are you heading today?\"\n}\n" /audio/voice_consents: post: operationId: createVoiceConsent tags: - Audio summary: Upload a voice consent recording. description: 'Upload a consent recording that authorizes creation of a custom voice. See the [custom voices guide](/docs/guides/text-to-speech#custom-voices) for requirements and best practices. Custom voices are limited to eligible customers. ' requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/CreateVoiceConsentRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/VoiceConsentResource' x-oaiMeta: name: Create voice consent group: audio examples: request: curl: "curl https://api.openai.com/v1/audio/voice_consents \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"name=John Doe\" \\\n -F \"language=en-US\" \\\n -F \"recording=@$HOME/consent_recording.wav;type=audio/x-wav\"\n" response: '' get: operationId: listVoiceConsents tags: - Audio summary: Returns a list of voice consent recordings. description: 'List consent recordings available to your organization for creating custom voices. See the [custom voices guide](/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers. ' 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: OK content: application/json: schema: $ref: '#/components/schemas/VoiceConsentListResource' x-oaiMeta: name: List voice consents group: audio examples: request: curl: "curl https://api.openai.com/v1/audio/voice_consents?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" response: '' /audio/voice_consents/{consent_id}: get: operationId: getVoiceConsent tags: - Audio summary: Retrieves a voice consent recording. description: 'Retrieve consent recording metadata used for creating custom voices. See the [custom voices guide](/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers. ' parameters: - in: path name: consent_id required: true schema: type: string description: The ID of the consent recording to retrieve. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/VoiceConsentResource' x-oaiMeta: name: Retrieve voice consent group: audio examples: request: curl: "curl https://api.openai.com/v1/audio/voice_consents/cons_1234 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" response: '' post: operationId: updateVoiceConsent tags: - Audio summary: Updates a voice consent recording (metadata only). description: 'Update consent recording metadata used for creating custom voices. This endpoint updates metadata only and does not replace the underlying audio. See the [custom voices guide](/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers. ' parameters: - in: path name: consent_id required: true schema: type: string description: The ID of the consent recording to update. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateVoiceConsentRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/VoiceConsentResource' x-oaiMeta: name: Update voice consent group: audio examples: request: curl: "curl https://api.openai.com/v1/audio/voice_consents/cons_1234 \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"John Doe\"\n }'\n" response: '' delete: operationId: deleteVoiceConsent tags: - Audio summary: Deletes a voice consent recording. description: 'Delete a consent recording that was uploaded for creating custom voices. See the [custom voices guide](/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers. ' parameters: - in: path name: consent_id required: true schema: type: string description: The ID of the consent recording to delete. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/VoiceConsentDeletedResource' x-oaiMeta: name: Delete voice consent group: audio examples: request: curl: "curl https://api.openai.com/v1/audio/voice_consents/cons_1234 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" response: '' /audio/voices: post: operationId: createVoice tags: - Audio summary: Creates a custom voice. description: 'Create a custom voice you can use for audio output (for example, in Text-to-Speech and the Realtime API). This requires an audio sample and a previously uploaded consent recording. See the [custom voices guide](/docs/guides/text-to-speech#custom-voices) for requirements and best practices. Custom voices are limited to eligible customers. ' requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/CreateVoiceRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/VoiceResource' x-oaiMeta: name: Create voice group: audio examples: request: curl: "curl https://api.openai.com/v1/audio/voices \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"name=My new voice\" \\\n -F \"consent=cons_1234\" \\\n -F \"audio_sample=@$HOME/audio_sample.wav;type=audio/x-wav\"\n" response: '' components: schemas: CreateTranslationRequest: type: object required: - file - model properties: file: type: string format: binary description: 'The audio file to translate, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. File uploads are limited to 25 MB.' example: example_value model: type: string description: ID of the model to use. Only whisper-1 is currently available for translation. examples: - whisper-1 prompt: type: string description: An optional text to guide the model's style or continue a previous audio segment. The prompt should be in English. example: example_value response_format: type: string enum: - json - text - srt - verbose_json - vtt default: json description: The format of the transcript output. Defaults to json. example: json temperature: type: number minimum: 0 maximum: 1 default: 0 description: The sampling temperature, between 0 and 1. example: 42.5 CreateVoiceRequest: type: object additionalProperties: false properties: name: type: string description: The name of the new voice. audio_sample: type: string format: binary x-oaiTypeLabel: file description: 'The sample audio recording file. Maximum size is 10 MiB. Supported MIME types: `audio/mpeg`, `audio/wav`, `audio/x-wav`, `audio/ogg`, `audio/aac`, `audio/flac`, `audio/webm`, `audio/mp4`. ' consent: type: string description: The consent recording ID (for example, `cons_1234`). required: - name - audio_sample - consent VoiceConsentResource: type: object title: Voice consent description: A consent recording used to authorize creation of a custom voice. additionalProperties: false properties: object: type: string description: The object type, which is always `audio.voice_consent`. enum: - audio.voice_consent x-stainless-const: true id: type: string description: The consent recording identifier. example: cons_1234 name: type: string description: The label provided when the consent recording was uploaded. language: type: string description: The BCP 47 language tag for the consent phrase (for example, `en-US`). created_at: type: integer format: unixtime description: The Unix timestamp (in seconds) for when the consent recording was created. required: - object - id - name - language - created_at x-oaiMeta: name: The voice consent object example: "{\n \"object\": \"audio.voice_consent\",\n \"id\": \"cons_1234\",\n \"name\": \"John Doe\",\n \"language\": \"en-US\",\n \"created_at\": 1734220800\n}\n" CreateVoiceConsentRequest: type: object additionalProperties: false properties: name: type: string description: The label to use for this consent recording. recording: type: string format: binary x-oaiTypeLabel: file description: 'The consent audio recording file. Maximum size is 10 MiB. Supported MIME types: `audio/mpeg`, `audio/wav`, `audio/x-wav`, `audio/ogg`, `audio/aac`, `audio/flac`, `audio/webm`, `audio/mp4`. ' language: type: string description: The BCP 47 language tag for the consent phrase (for example, `en-US`). required: - name - recording - language CreateTranscriptionRequest: type: object required: - file - model properties: file: type: string format: binary description: 'The audio file object to transcribe, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. File uploads are limited to 25 MB.' example: example_value model: type: string description: ID of the model to use. Only whisper-1 and gpt-4o-transcribe are currently available. examples: - whisper-1 - gpt-4o-transcribe language: type: string description: The language of the input audio. Supplying the input language in ISO-639-1 format will improve accuracy and latency. example: example_value prompt: type: string description: An optional text to guide the model's style or continue a previous audio segment. The prompt should match the audio language. example: example_value response_format: type: string enum: - json - text - srt - verbose_json - vtt default: json description: The format of the transcript output. Defaults to json. verbose_json includes additional metadata like word-level timestamps. example: json temperature: type: number minimum: 0 maximum: 1 default: 0 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. example: 42.5 timestamp_granularities: type: array items: type: string enum: - word - segment description: The timestamp granularities to populate for this transcription. response_format must be set to verbose_json to use this parameter. example: [] CreateTranscriptionResponse: type: object properties: text: type: string required: - text CreateSpeechRequest: type: object required: - model - input - voice properties: model: type: string description: One of the available TTS models. tts-1 is optimized for speed, tts-1-hd is optimized for quality, and gpt-4o-mini-tts supports advanced voice instructions. examples: - tts-1 - tts-1-hd - gpt-4o-mini-tts input: type: string maxLength: 4096 description: The text to generate audio for. The maximum length is 4096 characters. example: example_value voice: type: string enum: - alloy - ash - ballad - coral - echo - fable - onyx - nova - sage - shimmer - verse description: The voice to use when generating the audio. Previews of the voices are available in the Text to Speech guide. example: alloy instructions: type: string description: Control the voice of your generated audio with additional instructions. Only supported with gpt-4o-mini-tts. example: example_value response_format: type: string enum: - mp3 - opus - aac - flac - wav - pcm default: mp3 description: The format to audio in. Supported formats are mp3, opus, aac, flac, wav, and pcm. Opus is recommended for internet streaming and communication, aac for digital audio compression, and flac for lossless audio compression. example: mp3 speed: type: number minimum: 0.25 maximum: 4.0 default: 1.0 description: The speed of the generated audio. Select a value from 0.25 to 4.0. 1.0 is the default. example: 42.5 VoiceConsentListResource: type: object additionalProperties: false properties: object: type: string enum: - list x-stainless-const: true data: type: array items: $ref: '#/components/schemas/VoiceConsentResource' first_id: anyOf: - type: string - type: 'null' last_id: anyOf: - type: string - type: 'null' has_more: type: boolean required: - object - data - has_more x-oaiMeta: name: The voice consent list object example: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"audio.voice_consent\",\n \"id\": \"cons_1234\",\n \"name\": \"John Doe\",\n \"language\": \"en-US\",\n \"created_at\": 1734220800\n }\n ],\n \"first_id\": \"cons_1234\",\n \"last_id\": \"cons_1234\",\n \"has_more\": false\n}\n" UpdateVoiceConsentRequest: type: object additionalProperties: false properties: name: type: string description: The updated label for this consent recording. required: - name VoiceConsentDeletedResource: type: object additionalProperties: false properties: id: type: string description: The consent recording identifier. example: cons_1234 object: type: string enum: - audio.voice_consent x-stainless-const: true deleted: type: boolean required: - id - object - deleted x-oaiMeta: name: The voice consent deletion object example: "{\n \"object\": \"audio.voice_consent\",\n \"id\": \"cons_1234\",\n \"deleted\": true\n}\n" VoiceResource: type: object title: Voice description: A custom voice that can be used for audio output. additionalProperties: false properties: object: type: string description: The object type, which is always `audio.voice`. enum: - audio.voice x-stainless-const: true id: type: string description: The voice identifier, which can be referenced in API endpoints. name: type: string description: The name of the voice. created_at: type: integer format: unixtime description: The Unix timestamp (in seconds) for when the voice was created. required: - object - id - name - created_at x-oaiMeta: name: The voice object example: "{\n \"object\": \"audio.voice\",\n \"id\": \"voice_123abc\",\n \"name\": \"My new voice\",\n \"created_at\": 1734220800\n}\n" CreateTranslationResponse: type: object properties: text: type: string required: - text securitySchemes: ApiKeyAuth: type: http scheme: bearer x-oaiMeta: groups: - id: audio title: Audio description: 'Learn how to turn audio into text or text into audio. Related guide: [Speech to text](/docs/guides/speech-to-text) ' sections: - type: endpoint key: createSpeech path: createSpeech - type: endpoint key: createTranscription path: createTranscription - type: endpoint key: createTranslation path: createTranslation - id: chat title: Chat description: 'Given a list of messages comprising a conversation, the model will return a response. Related guide: [Chat Completions](/docs/guides/text-generation) ' sections: - type: endpoint key: createChatCompletion path: create - type: object key: CreateChatCompletionResponse path: object - type: object key: CreateChatCompletionStreamResponse path: streaming - 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](/docs/guides/embeddings) ' sections: - type: endpoint key: createEmbedding path: create - type: object key: Embedding path: 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](/docs/guides/fine-tuning) ' sections: - type: endpoint key: createFineTuningJob path: create - type: endpoint key: listPaginatedFineTuningJobs path: list - type: endpoint key: listFineTuningEvents path: list-events - type: endpoint key: retrieveFineTuningJob path: retrieve - type: endpoint key: cancelFineTuningJob path: cancel - type: object key: FineTuningJob path: object - type: object key: FineTuningJobEvent path: event-object - id: files title: Files description: 'Files are used to upload documents that can be used with features like [Assistants](/docs/api-reference/assistants) and [Fine-tuning](/docs/api-reference/fine-tuning). ' 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: images title: Images description: 'Given a prompt and/or an input image, the model will generate a new image. Related guide: [Image generation](/docs/guides/images) ' sections: - type: endpoint key: createImage path: create - type: endpoint key: createImageEdit path: createEdit - type: endpoint key: createImageVariation path: createVariation - type: object key: Image path: object - id: models title: Models description: 'List and describe the various models available in the API. You can refer to the [Models](/docs/models) documentation to understand what models are available and the differences between them. ' 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 a input text, outputs if the model classifies it as violating OpenAI''s content policy. Related guide: [Moderations](/docs/guides/moderation) ' sections: - type: endpoint key: createModeration path: create - type: object key: CreateModerationResponse path: object - id: assistants title: Assistants beta: true description: 'Build assistants that can call models and use tools to perform tasks. [Get started with the Assistants API](/docs/assistants) ' sections: - type: endpoint key: createAssistant path: createAssistant - type: endpoint key: createAssistantFile path: createAssistantFile - type: endpoint key: listAssistants path: listAssistants - type: endpoint key: listAssistantFiles path: listAssistantFiles - type: endpoint key: getAssistant path: getAssistant - type: endpoint key: getAssistantFile path: getAssistantFile - type: endpoint key: modifyAssistant path: modifyAssistant - type: endpoint key: deleteAssistant path: deleteAssistant - type: endpoint key: deleteAssistantFile path: deleteAssistantFile - type: object key: AssistantObject path: object - type: object key: AssistantFileObject path: file-object - id: threads title: Threads beta: true description: 'Create threads that assistants can interact with. Related guide: [Assistants](/docs/assistants/overview) ' sections: - type: endpoint key: createThread path: createThread - type: endpoint key: getThread path: getThread - type: endpoint key: modifyThread path: modifyThread - type: endpoint key: deleteThread path: deleteThread - type: object key: ThreadObject path: object - id: messages title: Messages beta: true description: 'Create messages within threads Related guide: [Assistants](/docs/assistants/overview) ' sections: - type: endpoint key: createMessage path: createMessage - type: endpoint key: listMessages path: listMessages - type: endpoint key: listMessageFiles path: listMessageFiles - type: endpoint key: getMessage path: getMessage - type: endpoint key: getMessageFile path: getMessageFile - type: endpoint key: modifyMessage path: modifyMessage - type: object key: MessageObject path: object - type: object key: MessageFileObject path: file-object - id: runs title: Runs beta: true description: 'Represents an execution run on a thread. Related guide: [Assistants](/docs/assistants/overview) ' sections: - type: endpoint key: createRun path: createRun - type: endpoint key: createThreadAndRun path: createThreadAndRun - type: endpoint key: listRuns path: listRuns - type: endpoint key: listRunSteps path: listRunSteps - type: endpoint key: getRun path: getRun - type: endpoint key: getRunStep path: getRunStep - type: endpoint key: modifyRun path: modifyRun - type: endpoint key: submitToolOuputsToRun path: submitToolOutputs - type: endpoint key: cancelRun path: cancelRun - type: object key: RunObject path: object - type: object key: RunStepObject path: step-object - id: completions title: Completions legacy: true 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](/docs/guides/text-generation/text-generation-models) to leverage our best and newest models. Most models that support the legacy Completions endpoint [will be shut off on January 4th, 2024](/docs/deprecations/2023-07-06-gpt-and-embeddings). ' sections: - type: endpoint key: createCompletion path: create - type: object key: CreateCompletionResponse path: object