✨ feat: add support for audio input with input_audio format

[Karavil]

🎵 Native Audio Input Support for OpenRouter

This PR introduces first-class support for audio file inputs through OpenRouter's input_audio format, enabling AI models to process audio content seamlessly alongside text, images, and documents.

✨ Key Features

🎯 Smart Format Detection & Normalization

The implementation intelligently handles various audio MIME types that developers commonly use:

• MP3 Support: audio/mpeg, audio/mp3 → mp3
• WAV Support: audio/wav, audio/x-wav, audio/wave → wav

This means developers can use the MIME types they're familiar with from the Web Audio API, file uploads, or various audio libraries without worrying about OpenRouter's specific format requirements.

📚 Developer-Friendly Error Messages

When things go wrong, developers get clear, actionable guidance instead of cryptic errors:

For unsupported formats:

Unsupported audio format: "audio/ogg"

OpenRouter only supports MP3 and WAV audio formats.
• For MP3: use "audio/mpeg" or "audio/mp3"
• For WAV: use "audio/wav" or "audio/x-wav"

Learn more: https://openrouter.ai/docs/features/multimodal/audio

For URL-based audio (not yet supported):

Audio files cannot be provided as URLs.

OpenRouter requires audio to be base64-encoded. Please:
1. Download the audio file locally
2. Read it as a Buffer or Uint8Array
3. Pass it as the data parameter

The AI SDK will automatically handle base64 encoding.

Learn more: https://openrouter.ai/docs/features/multimodal/audio

🏗️ Implementation Details

The audio handler integrates seamlessly into the existing multimodal content pipeline:

1. Detection: Checks for audio/* media types on file parts
2. Conversion: Transforms audio data into OpenRouter's input_audio structure
3. Encoding: Handles base64 encoding from Uint8Array or extracts from data URLs
4. Validation: Ensures only supported formats reach the API

Generated structure:

{
  type: 'input_audio',
  input_audio: {
    data: '<base64-encoded-audio>',
    format: 'mp3' | 'wav'
  },
  cache_control?: { type: 'ephemeral' }  // Optional caching support
}

🧪 Comprehensive Test Coverage

Added 9 new test cases covering:

• ✅ Uint8Array to base64 conversion for MP3 and WAV
• ✅ Format normalization (audio/mpeg → mp3, audio/x-wav → wav, audio/mp3 → mp3)
• ✅ Base64 data URL extraction
• ✅ Raw base64 string handling
• ✅ Cache control support for audio parts
• ✅ Proper error handling for unsupported formats
• ✅ Helpful error for external URLs

All 26 tests in convert-to-openrouter-chat-messages.test.ts pass successfully.

🔧 Technical Improvements

• Type Safety: Added ChatCompletionContentPartInputAudio interface with proper TypeScript types
• Code Quality: Fixed pre-existing TypeScript errors by adding const assertions to Set literals
• Maintainability: Used regex matching in tests for more flexible error message validation
• Documentation: All error messages link directly to OpenRouter's audio documentation

📖 Usage Example

import { openrouter } from '@openrouter/ai-sdk-provider';
import { generateText } from 'ai';
import fs from 'fs';

const audioFile = fs.readFileSync('speech.mp3');

const result = await generateText({
  model: openrouter('openai/gpt-4o-audio-preview'),
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'What is being said in this audio?' },
      { 
        type: 'file',
        data: audioFile,  // Uint8Array
        mediaType: 'audio/mpeg'  // or 'audio/mp3'
      }
    ]
  }]
});

🚀 Impact

This enhancement makes OpenRouter's audio capabilities immediately accessible to all AI SDK users, enabling new use cases like:

• Voice message analysis
• Audio transcription workflows
• Multimodal applications combining audio with text and images
• Accessibility features for audio content

📝 Notes

• External audio URLs are not currently supported by OpenRouter's API - the error message provides clear migration guidance
• Only MP3 and WAV formats are supported per OpenRouter's specification
• The implementation follows the same patterns as existing image and document handling for consistency

---

This PR maintains backward compatibility and requires no changes to existing code. Audio support is purely additive and opt-in through the file content type.

[louisgv]

nit: this section should be moved into its own function, so we can reuse it. The logic looks very self-contained

[louisgv]

Thanks for the PR! LGTM beside the nits!

[Karavil]

@louisgv Pulled out into a utility while keeping it composable for other audio utils in the future.