vercel/ai · error · Error

Google Generative AI API key is required for streaming trans

Error message

Google Generative AI API key is required for streaming translation.

What it means

The speech-translation doStream scans the configured headers for 'x-goog-api-key' (case-insensitive) to authenticate the WebSocket connection; browsers cannot send custom headers on WebSocket, so the key is moved out of headers and the connection relies on it being extracted. If no key is found in the config headers it throws before connecting. Like error 363, this reflects a provider configured without an API key.

Source

Thrown at packages/google/src/speech-translation/google-speech-translation-model.ts:165

      warnings.push({
        type: 'unsupported',
        feature: 'outputAudioFormat',
        details:
          'The Gemini Live API always outputs 24kHz 16-bit PCM audio and does not accept an output audio format.',
      });
    }

    const headers = combineHeaders(this.config.headers(), options.headers);
    // last case-variant wins: combineHeaders keeps case-distinct keys and
    // spreads per-call headers after configuration headers
    let apiKey: string | undefined;
    for (const [key, value] of Object.entries(headers)) {
      if (key.toLowerCase() === 'x-goog-api-key' && value != null) {
        apiKey = value;
      }
    }
    if (apiKey == null) {
      throw new Error(
        'Google Generative AI API key is required for streaming translation.',
      );
    }
    const webSocketHeaders = Object.fromEntries(
      Object.entries(headers).filter(
        ([key]) => key.toLowerCase() !== 'x-goog-api-key',
      ),
    );

    const setup = buildGoogleLiveSpeechTranslationSetup({
      modelId: this.modelId,
      targetLanguage: options.targetLanguage,
      providerOptions: googleOptions,
    });

    return {
      request: { body: setup },
      response: {

View on GitHub (pinned to 69428b1f8b)

Solutions

Set GOOGLE_GENERATIVE_AI_API_KEY or pass apiKey to createGoogleGenerativeAI({ apiKey }).
Confirm the header name is exactly 'x-goog-api-key' when using custom headers.
Check that headers() is not filtering the key out (e.g. a whitelist of header names).
Verify env loading at startup in the runtime where streaming executes.

Example fix

// before
const google = createGoogleGenerativeAI(); // env var not set in this env
// after
const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY,
});

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.GOOGLE_GENERATIVE_AI_API_KEY) {
  throw new Error('GOOGLE_GENERATIVE_AI_API_KEY must be set for streaming translation');
}

Try / catch

try {
  await model.doStream(options);
} catch (error) {
  if (error instanceof Error && error.message.includes('API key is required')) {
    // report missing-provider-config to operators
  } else { throw error; }
}

Prevention

Configure the key via createGoogleGenerativeAI({ apiKey }) or the standard env var.
Keep the header name exactly 'x-goog-api-key' when supplying custom headers.
Check env presence at process start, not on first request.
Remember the key is extracted from headers for WebSocket auth — don't strip it in header filters.

When it happens

Trigger: Streaming speech translation when the provider config's headers() contains no x-goog-api-key entry — apiKey env var unset, apiKey undefined passed to createGoogleGenerativeAI, or custom headers that omit the key.

Common situations: Missing GOOGLE_GENERATIVE_AI_API_KEY in the deployment environment; header set under a wrong name (e.g. 'x-goog-key'); custom headers() returning a record without the key.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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