Express mode provides simplified API key-only authentication without requiring a Google Cloud project ID or location. This mode automatically uses Vertex AI Express Mode endpoints .
Express mode only supports Google Gemini models. Partner model providers (Anthropic, Meta, Mistral, etc.) require Standard mode with project ID and location.
Configuration Add the following to your Prism configuration at config/prism.php:
'vertex' => [ 'api_key' => env ( 'VERTEX_API_KEY' ), // project_id and location omitted — triggers Express mode ],
Omit project_id and location
When both project_id and location are absent, the provider automatically uses Express mode endpoints.
Provide an API key
Set your Vertex AI API key using the api_key configuration option.
Use Google models only
Express mode restricts you to Google Gemini models. Attempting to use other providers will throw an exception.
Environment variables Set your API key in the .env file:
VERTEX_API_KEY = your-api-key-here
How Express mode works When you omit project_id and location, the provider detects Express mode via the isExpressMode() method:
public function isExpressMode () : bool { return ( $this -> projectId === null || $this -> projectId === '' ) && ( $this -> location === null || $this -> location === '' ); }
Express mode uses simplified endpoints that don’t require project or location in the URL:
https://aiplatform.googleapis.com/v1/publishers/{publisher}/models
Compare this to Standard mode endpoints:
https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/publishers/{publisher}/models
Supported models Express mode only works with Google Gemini models:
Text generation
Embeddings
Structured output
use Prism\Prism\ Prism ; use Prism\Vertex\Enums\ Vertex ; $response = Prism :: text () -> using ( Vertex :: Gemini , 'gemini-2.5-flash' ) -> withPrompt ( 'Explain quantum computing' ) -> asText (); echo $response -> text ;
use Prism\Prism\ Prism ; use Prism\Vertex\Enums\ Vertex ; $response = Prism :: embeddings () -> using ( Vertex :: Gemini , 'text-embedding-005' ) -> fromInput ( 'The sky is blue' ) -> asEmbeddings (); $embeddings = $response -> embeddings ;
use Prism\Prism\ Prism ; use Prism\Vertex\Enums\ Vertex ; use Prism\Prism\Schema\ ObjectSchema ; use Prism\Prism\Schema\ StringSchema ; $schema = new ObjectSchema ( name : 'person' , description : 'A person' , properties : [ new StringSchema ( 'name' , 'Person name' ), new StringSchema ( 'role' , 'Person role' ), ] ); $response = Prism :: structured () -> using ( Vertex :: Gemini , 'gemini-2.5-flash' ) -> withSchema ( $schema ) -> withPrompt ( 'Generate a fictional person' ) -> asStructured (); $data = $response -> structured ;
Error handling Attempting to use non-Google models in Express mode throws a PrismException:
use Prism\Prism\ Prism ; use Prism\Vertex\Enums\ Vertex ; // This will throw an exception in Express mode $response = Prism :: text () -> using ( Vertex :: Anthropic , 'claude-3-5-sonnet@20241022' ) -> withPrompt ( 'Hello' ) -> asText ();
Error message:
Vertex AI Express mode only supports Google models. The Anthropic apiSchema requires Standard mode with project_id and location.
When to use Express mode
Quick prototyping Get started quickly without setting up a full GCP project.
Simple applications Build apps that only need Google Gemini models.
Development Test Prism Vertex locally without complex authentication.
API key constraints When you can only use API key authentication.
When to use Standard mode instead You need Standard mode if you want to:
Use partner models (Anthropic, Meta, Mistral, DeepSeek, etc.)
Use service account authentication for production
Access region-specific endpoints
Use per-provider configuration overrides
Access features only available in Standard mode
You can start with Express mode and upgrade to Standard mode later by adding project_id and location to your configuration.
Switching from Express to Standard mode To switch from Express mode to Standard mode:
Add project_id
'project_id' => env ( 'VERTEX_PROJECT_ID' ),
Add location
'location' => env ( 'VERTEX_LOCATION' , 'us-central1' ),
Keep or replace authentication
Keep your api_key, or replace it with credentials for service account authentication.
Next steps
Standard mode Configure with project ID and location for full access
Authentication Learn about API key and service account authentication