Audio API

Synthesize speech from text, transcribe audio to text, and translate audio into English. Text-to-speech returns raw audio bytes (mp3, wav, and friends); transcription and translation upload an audio file and return text. OpenAI only.

Request Types

UniLM.SpeechRequest — Type

SpeechRequest(; input, voice="alloy", model="gpt-4o-mini-tts", service=OPENAIServiceEndpoint)

source

UniLM.TranscriptionRequest — Type

TranscriptionRequest(; file, model="gpt-transcribe", service=OPENAIServiceEndpoint)

An audio transcription/translation request. file is a path on disk; optional languages, keywords, prompt, response_format, and temperature refine decoding. For gpt-transcribe, a legacy singular language is translated to languages. Other models retain their singular language field. Never set both forms. Pass to transcribe or translate.

source

Result Types

UniLM.SpeechSuccess — Type

Successful speak result; audio holds the raw audio bytes, content_type the MIME type. Save with save_audio.

source

UniLM.TranscriptionSuccess — Type

Successful transcribe/translate result; text holds the transcript (via transcript_text), raw the parsed JSON when the API returns it.

source

UniLM.AudioFailure — Type

Audio API error result: HTTP status and the raw response body.

source

UniLM.AudioCallError — Type

Local/transport error from an Audio API call (the request never completed).

source

Functions

UniLM.speak — Function

speak(s::SpeechRequest) -> LLMRequestResponse
speak(input; voice="alloy", model="gpt-4o-mini-tts", service=OPENAIServiceEndpoint, kwargs...)

Synthesize speech. On success returns SpeechSuccess with raw audio bytes; otherwise AudioFailure/AudioCallError. Use save_audio to write the bytes to disk.

Pass config::Union{Nothing,RequestConfig} to override the timeout budget for this call (a single bounded attempt; max_attempts does not apply).

source

UniLM.transcribe — Function

transcribe(t::TranscriptionRequest) / transcribe(path; model="gpt-transcribe", kwargs...)

Transcribe audio to text in the source language. Returns TranscriptionSuccess (.text, via transcript_text), AudioFailure, or AudioCallError.

Pass config::Union{Nothing,RequestConfig} to override the timeout budget for this call (a single bounded attempt; max_attempts does not apply).

source

UniLM.translate — Function

translate(t::TranscriptionRequest) / translate(path; model="whisper-1", kwargs...)

Translate audio into English text.

Pass config::Union{Nothing,RequestConfig} to override the timeout budget for this call (a single bounded attempt; max_attempts does not apply).

source

Accessors

UniLM.transcript_text — Function

transcript_text(r::TranscriptionSuccess) -> String

The transcript text from a transcribe or translate result.

source

UniLM.save_audio — Function

save_audio(r::SpeechSuccess, path) -> path

source

Usage

# Text-to-speech: synthesize and save to disk
result = speak("Hello from UniLM.", voice="alloy")
result isa SpeechSuccess && save_audio(result, "hello.mp3")

# Transcribe audio to text in its source language
t = transcribe("hello.mp3"; languages=["en"], keywords=["UniLM", "Julia"])
t isa TranscriptionSuccess && println(transcript_text(t))

# Translate foreign-language audio into English
translate("bonjour.mp3")

Transcription defaults to gpt-transcribe. Its languages and keywords options are vectors of strings sent as repeated multipart fields. A singular language is translated to a one-element languages list for this model; older models keep their singular field. Setting both forms raises ArgumentError.

OpenAI deprecated gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize, and whisper-1 on August 26, 2026, with shutdown scheduled for February 26, 2027. Translation still defaults to whisper-1 because it remains the documented model for /audio/translations; gpt-transcribe is for transcription. OpenAI transcription guide, deprecation schedule.