Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Openai Audio API
license:
name: MIT
url: https://github.com/openai/openai-openapi/blob/master/LICENSE
termsOfService: https://openai.com/policies/terms-of-use
version: '1.0'
description: 'Operations tagged Audio across 3 of this provider''s published API definitions: audio-openapi-original.yml, openai-audio-openapi.yml, openai-openapi-master.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.openai.com/v1
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"
security:
- ApiKeyAuth: []
servers:
- url: https://api.openai.com/v1
/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"
security:
- ApiKeyAuth: []
servers:
- url: https://api.openai.com/v1
/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"
security:
- ApiKeyAuth: []
servers:
- url: https://api.openai.com/v1
/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: ''
security:
- ApiKeyAuth: []
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: ''
security:
- ApiKeyAuth: []
servers:
- url: https://api.openai.com/v1
/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: ''
security:
- ApiKeyAuth: []
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: ''
security:
- ApiKeyAuth: []
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: ''
security:
- ApiKeyAuth: []
servers:
- url: https://api.openai.com/v1
/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: ''
security:
- ApiKeyAuth: []
servers:
- url: https://api.openai.com/v1
components:
schemas:
CreateTranscriptionResponse:
type: object
properties:
text:
type: string
required:
- text
CreateTranslationResponse:
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
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: []
TranscriptionResponse:
type: object
required:
- text
properties:
text:
type: string
description: The transcribed text.
example: example_value
task:
type: string
enum:
- transcribe
description: The task performed, always transcribe.
example: transcribe
language:
type: string
description: The detected or specified language of the audio.
example: example_value
duration:
type: number
format: float
description: The duration of the input audio in seconds.
example: 42.5
words:
type: array
description: Extracted words and their corresponding timestamps. Only present when timestamp_granularities includes word.
items:
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.
example: []
segments:
type: array
description: Segments of the transcribed text and their corresponding details. Only present when timestamp_granularities includes segment or response_format is verbose_json.
items:
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 segment as potentially unreliable.
compression_ratio:
type: number
format: float
description: Compression ratio of the segment.
no_speech_prob:
type: number
format: float
description: Probability of no speech in the segment. If the value is higher than 1.0 and avg_logprob is below -1, consider the segment as silent.
example: []
TranslationResponse:
type: object
required:
- text
properties:
text:
type: string
description: The translated text in English.
example: example_value
task:
type: string
enum:
- translate
description: The task performed, always translate.
example: translate
language:
type: string
description: The detected language of the input audio.
example: example_value
duration:
type: number
format: float
description: The duration of the input audio in seconds.
example: 42.5
segments:
type: array
description: Segments of the translated text with timestamps.
items:
type: object
properties:
id:
type: integer
seek:
type: integer
start:
type: number
format: float
end:
type: number
format: float
text:
type: string
tokens:
type: array
items:
type: integer
temperature:
type: number
format: float
avg_logprob:
type: number
format: float
compression_ratio:
type: number
format: float
no_speech_prob:
type: number
format: float
example: []
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
CreateTranslationResponseJson:
type: object
properties:
text:
type: string
required:
- text
VoiceIdsShared:
example: ash
anyOf:
- type: string
- type: string
enum:
- alloy
- ash
- ballad
- coral
- echo
- sage
- shimmer
- verse
- marin
- cedar
CreateTranscriptionRequest_2:
type: object
additionalProperties: false
properties:
file:
description: 'The audio file object (not file name) to transcribe, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
'
type: string
x-oaiTypeLabel: file
format: binary
model:
description: 'ID of the model to use. The options are `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `whisper-1` (which is powered by our open source Whisper V2 model), and `gpt-4o-transcribe-diarize`.
'
example: gpt-4o-transcribe
anyOf:
- type: string
- type: string
enum:
- whisper-1
- gpt-4o-transcribe
- gpt-4o-mini-transcribe
- gpt-4o-mini-transcribe-2025-12-15
- gpt-4o-transcribe-diarize
x-stainless-const: true
x-oaiTypeLabel: string
language:
description: 'The language of the input audio. Supplying the input language in [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format will improve accuracy and latency.
'
type: string
prompt:
description: 'An optional text to guide the model''s style or continue a previous audio segment. The [prompt](/docs/guides/speech-to-text#prompting) should match the audio language. This field is not supported when using `gpt-4o-transcribe-diarize`.
'
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
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`, `gpt-4o-mini-transcribe`, and `gpt-4o-mini-transcribe-2025-12-15`. This field is not supported when using `gpt-4o-transcribe-diarize`.
'
type: array
items:
$ref: '#/components/schemas/TranscriptionInclude'
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.
This option is not available for `gpt-4o-transcribe-diarize`.
'
type: array
items:
type: string
enum:
- word
- segment
default:
- segment
stream:
anyOf:
- description: 'If set to true, the model response data will be streamed to the client
as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).
See the [Streaming section of the Speech-to-Text guide](/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
default: false
- type: 'null'
chunking_strategy:
anyOf:
- 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. Required when using `gpt-4o-transcribe-diarize` for inputs longer than 30 seconds. '
anyOf:
- type: string
enum:
- auto
default: auto
description: 'Automatically set chunking parameters based on the audio. Must be set to `"auto"`.
'
x-stainless-const: true
- $ref: '#/components/schemas/VadConfig'
x-oaiTypeLabel: string
- type: 'null'
known_speaker_names:
description: 'Optional list of speaker names that correspond to the audio samples provided in `known_speaker_references[]`. Each entry should be a short identifier (for example `customer` or `agent`). Up to 4 speakers are supported.
'
type: array
maxItems: 4
items:
type: string
known_speaker_references:
description: 'Optional list of audio samples (as [data URLs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs)) that contain known speaker references matching `known_speaker_names[]`. Each sample must be between 2 and 10 seconds, and can use any of the same input audio formats supported by `file`.
'
type: array
maxItems: 4
items:
type: string
required:
- file
- model
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: "{\n \"type\": \"speech.audio.done\",\n \"usage\": {\n \"input_tokens\": 14,\n \"output_tokens\": 101,\n \"total_tokens\": 115\n }\n}\n"
CreateTranscriptionResponseDiarizedJson:
type: object
description: 'Represents a diarized transcription response returned by the model, including the combined transcript and speaker-segment annotations.
'
properties:
task:
type: string
description: The type of task that was run. Always `transcribe`.
enum:
- transcribe
x-stainless-const: true
duration:
type: number
format: double
description: Duration of the input audio in seconds.
text:
type: string
description: The concatenated transcript text for the entire audio input.
segments:
type: array
description: Segments of the transcript annotated with timestamps and speaker labels.
items:
$ref: '#/components/schemas/TranscriptionDiarizedSegment'
usage:
ty
# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/openai-audio-api-openapi.yml