microsoft/semantic-kernel · error · ServiceInvalidRequestError

Audio file is required for audio to text service

Error message

Audio file is required for audio to text service

What it means

Raised as ServiceInvalidRequestError in _send_audio_to_text_request when settings.filename is falsy. This is a pre-flight validation check — the handler refuses to open a file path it cannot resolve before attempting the API call.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/open_ai_handler.py:164

        Returns:
            ImagesResponse: The response from the image edit API.
        """
        try:
            response: ImagesResponse = await self.client.images.edit(
                image=image,
                mask=mask,  # type: ignore
                **settings.prepare_settings_dict(),
            )
            self.store_usage(response)
            return response
        except Exception as ex:
            raise ServiceResponseException(f"Failed to edit image: {ex}") from ex

    async def _send_audio_to_text_request(self, settings: OpenAIAudioToTextExecutionSettings) -> Transcription:
        """Send a request to the OpenAI audio to text endpoint."""
        if not settings.filename:
            raise ServiceInvalidRequestError("Audio file is required for audio to text service")

        try:
            with open(settings.filename, "rb") as audio_file:
                return await self.client.audio.transcriptions.create(
                    file=audio_file,
                    **settings.prepare_settings_dict(),
                )
        except Exception as ex:
            raise ServiceResponseException(
                f"{type(self)} service failed to transcribe audio",
                ex,
            ) from ex

    async def _send_text_to_audio_request(
        self, settings: OpenAITextToAudioExecutionSettings
    ) -> _legacy_response.HttpxBinaryResponseContent:
        """Send a request to the OpenAI text to audio endpoint.

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set settings.filename to a valid path to the audio file before calling the service
2. Validate that the audio file path is non-empty and the file exists before constructing settings
3. If building settings programmatically, default filename from user input or file-upload handling

Example fix

# before
settings = OpenAIAudioToTextExecutionSettings()  # no filename
# after
settings = OpenAIAudioToTextExecutionSettings(filename='/path/to/audio.mp3')

from pathlib import Path

if not settings.filename:
    raise ValueError('Filename is required for audio transcription')
if not Path(settings.filename).is_file():
    raise FileNotFoundError(f'Audio file not found: {settings.filename}')

from semantic_kernel.exceptions.service_exceptions import ServiceInvalidRequestError

try:
    result = await service._send_audio_to_text_request(settings)
except ServiceInvalidRequestError as e:
    if 'Audio file is required' in str(e):
        raise ValueError('Provide a valid audio file path') from e

When it happens

Trigger: Constructing OpenAIAudioToTextExecutionSettings without a filename, or with filename=None, and then calling the transcription path via the service handler.

Common situations: Building a transcription pipeline where the audio path is dynamically resolved but comes back empty; passing settings built for a different endpoint to the audio-to-text service; configuration key mismatch for the audio file path.

Related errors

• {type(self)} service failed to transcribe audio
• The input audio content is not readable.
• The audio transcription format '{responseFormat}' is not sup
• MaxTokens {maxTokens} is not valid, the value must be greate
• The voice '{voice}' is not supported.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/f53d9813b3537927. Report an issue: GitHub.