vercel/ai · error · Error

Google Generative AI API key is required for realtime token

Error message

Google Generative AI API key is required for realtime token creation.

What it means

doCreateClientSecret mints ephemeral auth tokens for Google realtime (Live API) WebSocket sessions by calling the v1alpha auth_tokens endpoint. That request authenticates with the provider API key read from the 'x-goog-api-key' header in the provider config; if no key is present it throws before making any network call. The Google provider always sets this header from createGoogleGenerativeAI({ apiKey }) or GOOGLE_GENERATIVE_AI_API_KEY.

Source

Thrown at packages/google/src/realtime/google-realtime-model.ts:61

  private readonly config: GoogleRealtimeModelConfig;
  private readonly mapper = new GoogleRealtimeEventMapper();

  constructor(modelId: string, config: GoogleRealtimeModelConfig) {
    this.modelId = modelId;
    this.provider = config.provider;
    this.config = config;
  }

  async doCreateClientSecret(
    options: RealtimeModelV4ClientSecretOptions,
  ): Promise<RealtimeModelV4ClientSecretResult> {
    const fetchFn = this.config.fetch ?? fetch;
    const headers = this.config.headers();
    const apiKey = headers['x-goog-api-key'];

    if (!apiKey) {
      throw new Error(
        'Google Generative AI API key is required for realtime token creation.',
      );
    }

    // `newSessionExpireTime` controls how long the token can be used to *open*
    // a session — the window callers actually care about — so map
    // `expiresAfterSeconds` to it (Google otherwise defaults it to ~60s).
    // `expireTime` is the overall token lifetime and must be >=
    // `newSessionExpireTime`, so extend it to leave room for the opened session
    // to run.
    const now = Date.now();
    const openWindowMs = (options.expiresAfterSeconds ?? 60) * 1000;
    const newSessionExpireTime = new Date(now + openWindowMs).toISOString();
    const expireTime = new Date(
      now + openWindowMs + 30 * 60 * 1000,
    ).toISOString();

    const setupPayload = buildGoogleSessionConfig(

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Set process.env.GOOGLE_GENERATIVE_AI_API_KEY or pass apiKey in createGoogleGenerativeAI({ apiKey }).
2. Verify the env var is actually loaded in the runtime (print presence, not value, at startup).
3. If using custom headers, ensure the headers() function includes 'x-goog-api-key'.
4. For browser apps, mint the secret server-side where the key exists, then hand the token to the client.

Example fix

// before
const google = createGoogleGenerativeAI({ apiKey: undefined });
// after
const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY,
});

const apiKey = process.env.GOOGLE_GENERATIVE_AI_API_KEY;
if (!apiKey) throw new Error('GOOGLE_GENERATIVE_AI_API_KEY must be set before creating realtime client secrets');

try {
  const secret = await model.createClientSecret(options);
} catch (error) {
  if (error instanceof Error && error.message.includes('API key is required')) {
    // surface a configuration error to the operator, not the end user
  } else { throw error; }
}

When it happens

Trigger: Invoking clientSecret creation on a realtime model (e.g. experimental_createClientSecret) while the provider was configured without an API key — apiKey env var unset, undefined passed explicitly, or headers overridden to drop x-goog-api-key.

Common situations: Missing GOOGLE_GENERATIVE_AI_API_KEY in the environment (serverless deploy, CI, .env not loaded); passing apiKey: undefined; using a custom headers() function that omits 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

• Google realtime auth token request failed: ${response.status
• Google Generative AI API key is required for streaming trans
• Cartesia realtime client secret request failed: ${response.s
• Cartesia realtime client secret response did not include a t
• Google Vertex tuned models do not support Express Mode API k

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