vercel/ai · error · Error

Deepgram speech model "${this.modelId}" requires a `voice` t

Error message

Deepgram speech model "${this.modelId}" requires a `voice` to be set (e.g. voice: 'thalia').

What it means

Deepgram speech models identified only by a bare voice family ID (e.g. 'aura-2') do not encode an actual voice, so the SDK requires an explicit `voice` option to compose the upstream model ID (e.g. 'aura-2-thalia-en'). Full voice IDs like 'aura-2-thalia-en' pass through unchanged. The SDK throws this error in getArgs when a bare family ID is used but voice is missing or empty/whitespace.

Source

Thrown at packages/deepgram/src/deepgram-speech-model.ts:77

    instructions,
    providerOptions,
  }: Parameters<SpeechModelV4['doGenerate']>[0]) {
    const warnings: SharedV4Warning[] = [];

    // Parse provider options
    const deepgramOptions = await parseProviderOptions({
      provider: 'deepgram',
      providerOptions,
      schema: deepgramSpeechModelOptionsSchema,
    });

    // Compose the upstream model ID from voice/language when a bare voice
    // family ID is used; full voice IDs (e.g. `aura-2-thalia-en`) pass through.
    let upstreamModelId: string = this.modelId;
    if (VOICE_FAMILY_IDS.has(this.modelId)) {
      const trimmedVoice = voice?.trim();
      if (!trimmedVoice) {
        throw new Error(
          `Deepgram speech model "${this.modelId}" requires a \`voice\` to be set (e.g. voice: 'thalia').`,
        );
      }
      if (language === 'auto') {
        warnings.push({
          type: 'compatibility',
          feature: 'language',
          details: `Deepgram TTS models do not support automatic language detection. Language "en" was used instead.`,
        });
      }
      upstreamModelId = `${this.modelId}-${trimmedVoice}-${language && language !== 'auto' ? language : 'en'}`;
    }

    // Create request body
    const requestBody = {
      text,
    };

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Set the `voice` provider option, e.g. voice: 'thalia', when using a bare voice family ID
2. Or pass a full Deepgram voice ID as modelId, e.g. 'aura-2-thalia-en', which bypasses the voice requirement
3. Ensure the voice value is a non-empty, non-whitespace string

Example fix

// before
const model = deepgram.speech('aura-2');
// after
const model = deepgram.speech('aura-2', { voice: 'thalia' });
// or
const model = deepgram.speech('aura-2-thalia-en');

const VOICE_FAMILY_IDS = new Set(['aura-2']); // subset; check the package's VOICE_FAMILY_IDS
function assertDeepgramVoice(modelId, options) {
  if (VOICE_FAMILY_IDS.has(modelId) && !(options?.voice && options.voice.trim())) {
    throw new Error(`Deepgram model "${modelId}" requires a non-empty voice option`);
  }
}

function hasVoice(o): o is { voice: string } {
  return typeof (o as any)?.voice === 'string' && (o as any).voice.trim().length > 0;
}

null

When it happens

Trigger: Calling streamSpeech/generateSpeech with a Deepgram modelId that is in VOICE_FAMILY_IDS while omitting providerOptions voice, or passing an empty string or whitespace-only voice. E.g. createDeepgram({ modelId: 'aura-2' }) without voice.

Common situations: Copying a model family name from Deepgram docs instead of the full voice ID; refactoring code that previously used a full model ID; dynamically building the modelId and ending up with a family name; typo making voice an empty string after .trim().

Related errors

• Model could not be resolved
• Invalid argument for parameter model: model ${model.provider
• Unsupported output: ${_exhaustiveCheck}
• Invalid argument for parameter output: Invalid output type.
• Invalid argument for parameter enumValues: Enum values are r

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/ea058a5e4c3f7da8. Report an issue: GitHub.