vercel/ai · error · Error

Google Vertex transcription models do not support Express Mo

Error message

Google Vertex transcription models do not support Express Mode API keys. Use standard Google Cloud credentials instead.

What it means

createTranscriptionModel throws this Error whenever any transcription model is created while Express Mode API-key auth is configured. Vertex Cloud Speech-to-Text reuses Vertex auth headers but targets the Speech-to-Text API, which does not support Express Mode keys, so the provider throws unconditionally when apiKey is set.

Source

Thrown at packages/google-vertex/src/google-vertex-provider-base.ts:365

      const config = createConfig('speech');
      return new GoogleVertexCloudTTSSpeechModel(modelId, {
        provider: config.provider,
        headers: config.headers,
        fetch: config.fetch,
      });
    }

    return new GoogleSpeechModel(modelId, createConfig('speech'));
  };

  // Cloud Speech-to-Text reuses the Vertex auth headers from createConfig, but
  // targets the Speech-to-Text API.
  const createTranscriptionModel = (
    modelId: GoogleVertexTranscriptionModelId,
  ) => {
    if (apiKey) {
      throw new Error(
        'Google Vertex transcription models do not support Express Mode API keys. Use standard Google Cloud credentials instead.',
      );
    }

    const config = createConfig('transcription');

    // Gemini transcription models (`gemini-3.5-transcribe[-live]`) use the
    // Vertex generateContent / Live API surfaces; everything else routes to
    // Cloud Speech-to-Text (Chirp, telephony).
    if (modelId.startsWith('gemini')) {
      return new GoogleVertexGeminiTranscriptionModel(modelId, {
        provider: config.provider,
        baseURL: loadBaseURL(),
        headers: config.headers,
        fetch: config.fetch,
        webSocket: options.webSocket,
        project: loadGoogleVertexProject(),
        location: loadGoogleVertexLocation(),

View on GitHub (pinned to 69428b1f8b)

Solutions

Remove the apiKey and authenticate via service account (GOOGLE_APPLICATION_CREDENTIALS) or workload identity.
Unset GOOGLE_VERTEX_API_KEY in the process environment.
Route transcription through a provider instance configured with standard GCP credentials.

Example fix

// before
const vertex = createGoogleVertex({ apiKey: key });
const stt = vertex.transcription('chirp-3');
// after
const vertex = createGoogleVertex({ project: 'my-project', location: 'us-central1' });
const stt = vertex.transcription('chirp-3');

Defensive patterns

Strategy: validation

Validate before calling

if (apiKey && wantsTranscription) {
  throw new Error('Vertex transcription requires standard Google Cloud credentials, not an API key.');
}

Try / catch

try {
  const model = vertex.transcription(modelId);
} catch (e) {
  if (e instanceof Error && e.message.includes('transcription models do not support Express Mode')) {
    // rebuild provider with ADC/service-account credentials
  } else throw e;
}

Prevention

Verify at app bootstrap that no GOOGLE_VERTEX_API_KEY is set when transcription is a feature.
Use GOOGLE_APPLICATION_CREDENTIALS / workload identity for Vertex Speech-to-Text.

When it happens

Trigger: vertex.transcription('<model>') while the provider was built with `apiKey` (createGoogleVertex({ apiKey }) or GOOGLE_VERTEX_API_KEY in env) — the unconditional `if (apiKey)` throws.

Common situations: Adding transcription to a prototype set up with an Express Mode key; environments where GOOGLE_VERTEX_API_KEY is set globally and also used by the transcription pipeline; migration from the plain Google Speech API where API keys are accepted.

Related errors

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