Soniox Provider

Soniox provider integrates Soniox transcription models with the Vercel AI SDK. For more information, see the Soniox Documentation.

Installation 

pnpm add @soniox/vercel-ai-sdk-provider

Authentication

Set SONIOX_API_KEY in your environment or pass apiKey when creating the provider. Get your API key from the Soniox Console.

Example 

import { soniox } from '@soniox/vercel-ai-sdk-provider';
import { experimental_transcribe as transcribe } from 'ai';


const { text } = await transcribe({
  model: soniox.transcription('stt-async-v3'),
  audio: new URL('https://soniox.com/media/examples/coffee_shop.mp3'),
});

Provider options

Use createSoniox to customize the provider instance:

import { createSoniox } from '@soniox/vercel-ai-sdk-provider';


const soniox = createSoniox({
  apiKey: process.env.SONIOX_API_KEY,
  apiBaseUrl: 'https://api.soniox.com',
});

Options:

  • apiKey: override SONIOX_API_KEY.
  • apiBaseUrl: custom API base URL. See list of regional API endpoints here.
  • headers: additional request headers.
  • fetch: custom fetch implementation.
  • pollingIntervalMs: transcription polling interval in milliseconds. Default is 1000ms.

Transcription options

Per-request options are passed via providerOptions:

const { text } = await transcribe({
  model: soniox.transcription('stt-async-v3'),
  audio,
  providerOptions: {
    soniox: {
      languageHints: ['en', 'es'],
      enableLanguageIdentification: true,
      enableSpeakerDiarization: true,
      context: {
        terms: ['Soniox', 'Vercel'],
      },
    },
  },
});

Available options:

  • languageHints - Array of ISO language codes to bias recognition
  • languageHintsStrict - When true, rely more heavily on language hints (note: not supported by all models)
  • enableLanguageIdentification - Automatically detect spoken language
  • enableSpeakerDiarization - Identify and separate different speakers
  • context - Additional context to improve accuracy
  • clientReferenceId - Optional client-defined reference ID
  • webhookUrl - Webhook URL for transcription completion notifications
  • webhookAuthHeaderName - Webhook authentication header name
  • webhookAuthHeaderValue - Webhook authentication header value
  • translation - Translation configuration

Check the Soniox API reference for more details.

Language hints

Soniox automatically detects and transcribes speech in 60+ languages. When you know which languages are likely to appear in your audio, provide languageHints to improve accuracy by biasing recognition toward those languages.

Language hints do not restrict recognition — they only bias the model toward the specified languages, while still allowing other languages to be detected if present.

const { text } = await transcribe({
  model: soniox.transcription('stt-async-v3'),
  audio,
  providerOptions: {
    soniox: {
      languageHints: ['en', 'es'], // ISO language codes
    },
  },
});

For more details, see the Soniox language hints documentation.

Context

Provide custom context to improve transcription and translation accuracy. Context helps the model understand your domain, recognize important terms, and apply custom vocabulary.

The context object supports four optional sections:

const { text } = await transcribe({
  model: soniox.transcription('stt-async-v3'),
  audio,
  providerOptions: {
    soniox: {
      context: {
        // Structured key-value information (domain, topic, intent, etc.)
        general: [
          { key: 'domain', value: 'Healthcare' },
          { key: 'topic', value: 'Diabetes management consultation' },
          { key: 'doctor', value: 'Dr. Martha Smith' },
        ],
        // Longer free-form background text or related documents
        text: 'The patient has a history of...',
        // Domain-specific or uncommon words
        terms: ['Celebrex', 'Zyrtec', 'Xanax'],
        // Custom translations for ambiguous terms
        translationTerms: [
          { source: 'Mr. Smith', target: 'Sr. Smith' },
          { source: 'MRI', target: 'RM' },
        ],
      },
    },
  },
});

For more details, see the Soniox context documentation.