Vercel AI SDK

Vercel AI SDK is a library for building AI applications. This provider integrates Soniox transcription models with the Vercel AI SDK.

Installation

npm install @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-v4'),
  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-v4'),
  audio,
  providerOptions: {
    soniox: {
      languageHints: ['en', 'es'],
      enableLanguageIdentification: true,
      enableSpeakerDiarization: true,
      context: {
        terms: ["Soniox", "Vercel"]
      },
    },
  },
});

Available options:

• languageHints
• languageHintsStrict
• enableLanguageIdentification
• enableSpeakerDiarization
• context
• clientReferenceId
• webhookUrl
• webhookAuthHeaderName
• webhookAuthHeaderValue
• translation

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-v4'),
  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-v4'),
  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.

Documentation

• Soniox API docs: https://soniox.com/docs
• AI SDK docs: https://ai-sdk.dev/docs