How to Use the Audio Transcription API in aisuite: client.audio.transcriptions.create

The client.audio.transcriptions.create method provides a unified interface for speech-to-text transcription across OpenAI, Deepgram, Google, and other providers by routing requests through aisuite's Multi-Client Provider (MCP) architecture.

The aisuite library simplifies AI integration by exposing a single client interface for multiple providers. The client.audio.transcriptions.create method enables seamless speech-to-text conversion while automatically handling provider-specific request formatting and response normalization.

How aisuite Routes Audio Transcription Requests

The transcription workflow follows a three-tier architecture that abstracts provider complexity.

Client Layer – In aisuite/client.py, the high-level client object lazily loads the selected provider and exposes the audio attribute. This attribute groups audio capabilities, with transcriptions providing the create and create_stream_output methods.

Provider Dispatch – When invoked, the MCP client forwards the call to concrete implementations such as aisuite/providers/openai_provider.py for Whisper or aisuite/providers/google_provider.py for Speech-to-Text. Each provider implements private _parse_<provider>_response helpers to normalize provider-specific JSON into the common TranscriptionResult model.

Request Construction – The client automatically builds multipart/form-data requests when file paths or file-like objects are supplied. Optional keyword arguments including language, prompt, temperature, and response_format are forwarded as query-string or body parameters according to the provider's API specification.

Transcribing Audio Files with client.audio.transcriptions.create

The method accepts either file paths or file-like objects and supports provider-specific optional parameters.

Basic Usage with File Paths

Pass a string path to the audio file along with the model identifier. The following example uses OpenAI's Whisper model with optional accuracy hints:

from aisuite import client

result = client.audio.transcriptions.create(
    model="whisper-1",          # Provider-specific model identifier

    file="speech.mp3",          # Path to the audio file

    language="en",              # Optional: ISO-639-1 language code

    prompt="Meeting notes:",    # Optional: hint to improve accuracy

    temperature=0.0,            # Optional: creativity control (0-1)

)

print(result.text)   # Normalised transcription text

Using File-Like Objects

For in-memory processing or streaming workflows, pass any file-like object:

from aisuite import client

with open("lecture.wav", "rb") as f:
    result = client.audio.transcriptions.create(
        model="deepgram-v2",
        file=f,                # Any file-like object works

        language="en-US",
        diarize=True,          # Deepgram-specific option for speaker identification

    )

print(result.text)

Advanced Transcription Options

Streaming Output for Large Files

Process lengthy recordings without loading the entire response into memory using create_stream_output:

from aisuite import client

stream = client.audio.transcriptions.create_stream_output(
    model="whisper-1",
    file="large_recording.mp3",
)

for chunk in stream:
    print(chunk.text, end=" ")

Provider-Specific Parameters

aisuite forwards arbitrary keyword arguments to the underlying provider, enabling access to native features. This example uses Google Speech-to-Text with word-level timestamps:

from aisuite import client

result = client.audio.transcriptions.create(
    model="google_en_us",
    file="interview.flac",
    language="en-US",
    response_format="srt",          # Provider-specific format

    enable_word_time_offsets=True,  # Google-only flag

)

print(result.text)   # Returns SRT-formatted subtitles

Error Handling and Response Normalization

The MCP layer catches HTTP errors and retries transient failures automatically. Provider-specific error codes are translated into human-readable messages through the unified ProviderError exception. As implemented in aisuite/client.py, all provider responses are normalized to a consistent TranscriptionResult object containing the transcribed text and metadata, regardless of whether the underlying provider is OpenAI, Google, or Deepgram. The test suite in tests/providers/test_openai_provider.py demonstrates expected error scenarios and retry logic.

Summary

• Unified Interface: The client.audio.transcriptions.create method in aisuite/client.py provides a single entry point for speech-to-text across multiple providers.
• Flexible Input: Accepts both file paths and file-like objects, constructing proper multipart/form-data requests automatically.
• Streaming Support: Use create_stream_output for processing large files incrementally without memory overhead.
• Provider Passthrough: Arbitrary keyword arguments are forwarded to underlying APIs, enabling provider-specific features like diarization or timestamp generation.
• Normalized Responses: All providers return a standardized TranscriptionResult model, with errors unified under ProviderError.

Frequently Asked Questions

What audio file formats does aisuite support?

Format support depends on the underlying provider. OpenAI Whisper accepts MP3, WAV, and M4A, while Google Speech-to-Text supports FLAC and LINEAR16. The client.audio.transcriptions.create method accepts any format compatible with your selected provider's model.

How do I switch between transcription providers?

Change the model parameter to the provider-specific identifier (e.g., "whisper-1" for OpenAI, "deepgram-v2" for Deepgram, or "google_en_us" for Google). Ensure your environment contains the appropriate API keys for the target provider; aisuite's MCP client handles the rest.

Does aisuite support real-time streaming transcription?

The library provides create_stream_output for streaming large file responses incrementally, but it does not currently expose WebSocket-based real-time streaming. For live audio streams, you would need to implement chunking logic or use the provider's native SDK alongside aisuite.

How does aisuite handle transcription API failures?

The MCP layer catches HTTP errors, implements retry logic for transient failures, and raises a unified ProviderError exception with human-readable messages. This ensures consistent error handling across OpenAI, Google, and other providers without requiring provider-specific catch blocks in your application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}