Google AI & Vertex AI Gemini API Dart Client

• Features
• Why choose this client?
• Quickstart
• Installation
• API Versions
• Vertex AI Support
• Advanced Configuration
• Usage
• Migrating from Google AI to Vertex AI
• Examples
• API Coverage
• Development
• License

import 'package:googleai_dart/googleai_dart.dart';

// Use stable v1
final client = GoogleAIClient(
  config: GoogleAIConfig.googleAI(
    apiVersion: ApiVersion.v1,
    authProvider: ApiKeyProvider('YOUR_API_KEY'),
  ),
);

// Use beta v1beta
final betaClient = GoogleAIClient(
  config: GoogleAIConfig.googleAI(
    apiVersion: ApiVersion.v1beta,
    authProvider: ApiKeyProvider('YOUR_API_KEY'),
  ),
);

import 'package:googleai_dart/googleai_dart.dart';

// Create an OAuth provider (implement token refresh logic)
class MyOAuthProvider implements AuthProvider {
  @override
  Future<AuthCredentials> getCredentials() async {
    // Your OAuth token refresh logic here
    final token = await getAccessToken(); // Implement this
    // You can use https://pub.dev/packages/googleapis_auth
    return BearerTokenCredentials(token);
  }
}

// Configure for Vertex AI
final vertexClient = GoogleAIClient(
  config: GoogleAIConfig.vertexAI(
    projectId: 'your-gcp-project-id',
    location: 'us-central1', // Or 'global', 'europe-west1', etc.
    apiVersion: ApiVersion.v1, // Stable version
    authProvider: MyOAuthProvider(),
  ),
);

// Use the same API as Google AI
final response = await vertexClient.models.generateContent(
  model: 'gemini-2.5-flash',
  request: GenerateContentRequest(
    contents: [
      Content(
        parts: [TextPart('Explain quantum computing')],
        role: 'user',
      ),
    ],
  ),
);

For advanced use cases, you can use the main GoogleAIConfig constructor with full control over all parameters:

import 'package:googleai_dart/googleai_dart.dart';

final client = GoogleAIClient(
  config: GoogleAIConfig(
    baseUrl: 'https://my-custom-proxy.example.com',
    apiMode: ApiMode.googleAI,
    apiVersion: ApiVersion.v1,
    authProvider: ApiKeyProvider('YOUR_API_KEY'),
    timeout: Duration(minutes: 5),
    retryPolicy: RetryPolicy(maxRetries: 5),
    // ... other parameters
  ),
);

Use cases for custom base URLs:

• Proxy servers: Route requests through a corporate proxy
• Testing: Point to a mock server for integration tests
• Regional endpoints: Use region-specific URLs if needed
• Custom deployments: Self-hosted or specialized endpoints

The factory constructors (GoogleAIConfig.googleAI() and GoogleAIConfig.vertexAI()) are convenience methods that set sensible defaults, but you can always use the main constructor for full control.

The client uses an AuthProvider pattern for flexible authentication:

import 'package:googleai_dart/googleai_dart.dart';

// API Key authentication (query parameter)
final client = GoogleAIClient(
  config: GoogleAIConfig(
    authProvider: ApiKeyProvider('YOUR_API_KEY'),
  ),
);

// API Key as header
final clientWithHeader = GoogleAIClient(
  config: GoogleAIConfig(
    authProvider: ApiKeyProvider(
      'YOUR_API_KEY',
      placement: AuthPlacement.header,
    ),
  ),
);

// Bearer token (for OAuth)
final clientWithBearer = GoogleAIClient(
  config: GoogleAIConfig(
    authProvider: BearerTokenProvider('YOUR_BEARER_TOKEN'),
  ),
);

// Custom OAuth with automatic token refresh
class CustomOAuthProvider implements AuthProvider {
  @override
  Future<AuthCredentials> getCredentials() async {
    // Your token refresh logic here
    // Called on each request, including retries
    return BearerTokenCredentials(await refreshToken());
  }
}

final oauthClient = GoogleAIClient(
  config: GoogleAIConfig(
    authProvider: CustomOAuthProvider(),
  ),
);

import 'package:googleai_dart/googleai_dart.dart';

final client = GoogleAIClient(
  config: GoogleAIConfig(
    authProvider: ApiKeyProvider('YOUR_API_KEY'),
  ),
);

final response = await client.models.generateContent(
  model: 'gemini-2.5-flash',
  request: GenerateContentRequest(
    contents: [
      Content(
        parts: [TextPart('Explain quantum computing')],
        role: 'user',
      ),
    ],
  ),
);

print(response.candidates?.first.content?.parts.first);
client.close();

import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
await for (final chunk in client.models.streamGenerateContent(
  model: 'gemini-2.5-flash',
  request: request,
)) {
  // Process each chunk as it arrives
  final text = chunk.candidates?.first.content?.parts.first;
  if (text is TextPart) print(text.text);
}

You can cancel long-running requests using an abort trigger:

import 'dart:async';
import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
final abortController = Completer<void>();

// Start request with abort capability
final requestFuture = client.models.generateContent(
  model: 'gemini-2.5-flash',
  request: request,
  abortTrigger: abortController.future,
);

// To cancel:
abortController.complete();

// Handle cancellation
try {
  final response = await requestFuture;
} on AbortedException {
  print('Request was canceled');
}

This works for both regular and streaming requests. You can also use it with timeouts:

// Auto-cancel after 30 seconds
final response = await client.models.generateContent(
  model: 'gemini-2.5-flash',
  request: request,
  abortTrigger: Future.delayed(Duration(seconds: 30)),
);

import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
final tools = [
  Tool(
    functionDeclarations: [
      FunctionDeclaration(
        name: 'get_weather',
        description: 'Get current weather',
        parameters: Schema(
          type: SchemaType.object,
          properties: {
            'location': Schema(type: SchemaType.string),
          },
          required: ['location'],
        ),
      ),
    ],
  ),
];

final response = await client.models.generateContent(
  model: 'gemini-2.5-flash',
  request: GenerateContentRequest(
    contents: [/* ... */],
    tools: tools,
  ),
);

import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
final response = await client.models.embedContent(
  model: 'gemini-embedding-001',
  request: EmbedContentRequest(
    content: Content(
      parts: [TextPart('Hello world')],
    ),
    taskType: TaskType.retrievalDocument,
  ),
);

print(response.embedding.values); // List<double>

Upload files for use in multimodal prompts:

import 'dart:io' as io;
import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
// Upload a file
final file = await client.files.upload(
  filePath: '/path/to/image.jpg',
  mimeType: 'image/jpeg',
  displayName: 'My Image',
);

print('File uploaded: ${file.name}');
print('State: ${file.state}');
print('URI: ${file.uri}');

// Wait for file to be processed (if needed)
while (file.state == FileState.processing) {
  await Future.delayed(Duration(seconds: 2));
  file = await client.files.get(name: file.name);
}

// Use the file in a prompt
final response = await client.models.generateContent(
  model: 'gemini-2.0-flash-exp',
  request: GenerateContentRequest(
    contents: [
      Content(
        parts: [
          TextPart('Describe this image'),
          FileData(
            fileUri: file.uri,
            mimeType: file.mimeType,
          ),
        ],
        role: 'user',
      ),
    ],
  ),
);

// List all files
final listResponse = await client.files.list(pageSize: 10);
for (final f in listResponse.files ?? []) {
  print('${f.displayName}: ${f.state}');
}

// Download file content (if needed)
final bytes = await client.files.download(name: file.name);
// Save to disk or process bytes
await io.File('downloaded_file.jpg').writeAsBytes(bytes);

// Delete the file when done
await client.files.delete(name: file.name);

Note: Files are automatically deleted after 48 hours.

Context caching allows you to save frequently used content and reuse it across requests, reducing latency and costs:

import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
// Create cached content with system instructions
final cachedContent = await client.cachedContents.create(
  cachedContent: const CachedContent(
    model: 'models/gemini-1.5-flash-8b',
    displayName: 'Math Expert Cache',
    systemInstruction: Content(
      parts: [TextPart('You are an expert mathematician...')],
    ),
    ttl: '3600s', // Cache for 1 hour
  ),
);

// Use cached content in requests (saves tokens!)
final response = await client.models.generateContent(
  model: 'gemini-1.5-flash-8b',
  request: GenerateContentRequest(
    cachedContent: cachedContent.name,
    contents: [
      Content(parts: [TextPart('Explain the Pythagorean theorem')], role: 'user'),
    ],
  ),
);

// Update cache TTL
await client.cachedContents.update(
  name: cachedContent.name!,
  cachedContent: const CachedContent(
    model: 'models/gemini-1.5-flash-8b',
    ttl: '7200s', // Extend to 2 hours
  ),
  updateMask: 'ttl',
);

// Clean up when done
await client.cachedContents.delete(name: cachedContent.name!);

Benefits:

• ✅ Reduced latency for requests with large contexts
• ✅ Lower costs by reusing cached content
• ✅ Consistent system instructions across requests

The generateAnswer API provides answers grounded in specific sources, ideal for Retrieval Augmented Generation (RAG):

import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
// Using inline passages (for small knowledge bases)
final response = await client.models.generateAnswer(
  model: 'aqa',
  request: const GenerateAnswerRequest(
    contents: [
      Content(
        parts: [TextPart('What is the capital of France?')],
        role: 'user',
      ),
    ],
    answerStyle: AnswerStyle.abstractive, // Or: extractive, verbose
    inlinePassages: GroundingPassages(
      passages: [
        GroundingPassage(
          id: 'passage-1',
          content: Content(
            parts: [TextPart('Paris is the capital of France.')],
          ),
        ),
      ],
    ),
    temperature: 0.2, // Low temperature for factual answers
  ),
);

// Check answerability
if (response.answerableProbability != null &&
    response.answerableProbability! < 0.5) {
  print('⚠️ Answer may not be grounded in sources');
}

// Using semantic retriever (for large corpora)
final ragResponse = await client.models.generateAnswer(
  model: 'aqa',
  request: const GenerateAnswerRequest(
    contents: [
      Content(
        parts: [TextPart('What are the key features of Dart?')],
        role: 'user',
      ),
    ],
    answerStyle: AnswerStyle.verbose,
    semanticRetriever: SemanticRetrieverConfig(
      source: 'corpora/my-corpus',
      query: Content(
        parts: [TextPart('Dart programming language features')],
      ),
      maxChunksCount: 5,
      minimumRelevanceScore: 0.5,
    ),
  ),
);

Features:

• ✅ Multiple answer styles (abstractive, extractive, verbose)
• ✅ Inline passages or semantic retriever grounding
• ✅ Answerability probability for quality control
• ✅ Safety settings support
• ✅ Input feedback for blocked content

import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
// Create a batch for processing multiple requests
final batch = await client.models.batchGenerateContent(
  model: 'gemini-2.0-flash-exp',
  batch: const GenerateContentBatch(
    displayName: 'My Batch Job',
    model: 'models/gemini-2.0-flash-exp',
    inputConfig: InputConfig(
      requests: InlinedRequests(
        requests: [
          InlinedRequest(
            request: GenerateContentRequest(
              contents: [
                Content(parts: [TextPart('What is 2+2?')], role: 'user'),
              ],
            ),
          ),
          InlinedRequest(
            request: GenerateContentRequest(
              contents: [
                Content(parts: [TextPart('What is 3+3?')], role: 'user'),
              ],
            ),
          ),
        ],
      ),
    ),
  ),
);

// Monitor batch status
final status = await client.batches.getGenerateContentBatch(name: batch.name!);
print('Batch state: ${status.state}');

⚠️ Important: Document, chunk, and RAG features are only available in Vertex AI. Google AI only supports basic corpus management.

import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured Google AI client
// Google AI supports basic corpus CRUD operations
final corpus = await client.corpora.create(
  corpus: const Corpus(displayName: 'My Knowledge Base'),
);

// List corpora
final corpora = await client.corpora.list(pageSize: 10);

// Get corpus
final retrieved = await client.corpora.get(name: corpus.name!);

// Update corpus
final updated = await client.corpora.update(
  name: corpus.name!,
  corpus: const Corpus(displayName: 'Updated Name'),
  updateMask: 'displayName',
);

// Delete corpus
await client.corpora.delete(name: corpus.name!);

For full RAG capabilities (documents, chunks, semantic search):

• Use Vertex AI with RAG Stores and Vector Search
• The Semantic Retriever API has been succeeded by Vertex AI Vector Search

import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
// Grant permissions to a resource
final permission = await client.tunedModels.permissions(parent: 'tunedModels/my-model').create(
  permission: const Permission(
    granteeType: GranteeType.user,
    emailAddress: 'user@example.com',
    role: PermissionRole.reader,
  ),
);

// List permissions
final permissions = await client.tunedModels.permissions(parent: 'tunedModels/my-model').list();

// Transfer ownership
await client.tunedModels.permissions(parent: 'tunedModels/my-model').transferOwnership(
  emailAddress: 'newowner@example.com',
);

import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
// List all tuned models
final tunedModels = await client.tunedModels.list(
  pageSize: 10,
  filter: 'owner:me', // Filter by ownership
);

for (final model in tunedModels.tunedModels) {
  print('Model: ${model.displayName} (${model.name})');
  print('State: ${model.state}');
  print('Base model: ${model.baseModel}');
}

// Get specific tuned model details
final myModel = await client.tunedModels.get(
  name: 'tunedModels/my-model-abc123',
);

print('Model: ${myModel.displayName}');
print('State: ${myModel.state}');
print('Training examples: ${myModel.tuningTask?.trainingData?.examples?.exampleCount}');

// List operations for a tuned model (monitor training progress)
final operations = await client.tunedModels.operations(parent: 'tunedModels/my-model-abc123').list();

for (final operation in operations.operations) {
  print('Operation: ${operation.name}');
  print('Done: ${operation.done}');
  if (operation.metadata != null) {
    print('Progress: ${operation.metadata}');
  }
}

Once you have a tuned model, you can use it for content generation just like base models:

import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
// Generate content with a tuned model
final response = await client.tunedModels.generateContent(
  tunedModel: 'my-model-abc123', // Your tuned model ID
  request: const GenerateContentRequest(
    contents: [
      Content(
        parts: [TextPart('Explain quantum computing')],
        role: 'user',
      ),
    ],
  ),
);

print(response.candidates?.first.content?.parts.first);

// Stream responses with a tuned model
await for (final chunk in client.tunedModels.streamGenerateContent(
  tunedModel: 'my-model-abc123',
  request: request,
)) {
  final text = chunk.candidates?.first.content?.parts.first;
  if (text is TextPart) print(text.text);
}

// Batch generation with a tuned model
final batch = await client.tunedModels.batchGenerateContent(
  tunedModel: 'my-model-abc123',
  batch: const GenerateContentBatch(
    model: 'models/placeholder',
    displayName: 'My Batch Job',
    inputConfig: InputConfig(
      requests: InlinedRequests(
        requests: [
          InlinedRequest(
            request: GenerateContentRequest(
              contents: [
                Content(parts: [TextPart('Question 1')], role: 'user'),
              ],
            ),
          ),
        ],
      ),
    ),
  ),
);

Benefits of tuned models:

• ✅ Customized behavior for your specific domain
• ✅ Improved accuracy for specialized tasks
• ✅ Consistent output style and format
• ✅ Reduced need for extensive prompting

import 'package:googleai_dart/googleai_dart.dart';

// Assumes you have a configured client instance
// Synchronous prediction
final response = await client.models.predict(
  model: 'veo-3.0-generate-001',
  instances: [
    {'prompt': 'A cat playing piano in a jazz club'},
  ],
);

print('Predictions: ${response.predictions}');

// Long-running prediction for video generation
final operation = await client.models.predictLongRunning(
  model: 'veo-3.0-generate-001',
  instances: [
    {'prompt': 'A golden retriever running on a beach at sunset'},
  ],
  parameters: {
    'aspectRatio': '16:9',
  },
);

print('Operation: ${operation.name}');
print('Done: ${operation.done}');

// Check for generated videos
if (operation.done == true && operation.response != null) {
  final videoResponse = operation.response!.generateVideoResponse;
  if (videoResponse?.generatedSamples != null) {
    for (final media in videoResponse!.generatedSamples!) {
      if (media.video?.uri != null) {
        print('Video URI: ${media.video!.uri}');
      }
    }
  }

  // Check for RAI filtering
  if (videoResponse?.raiMediaFilteredCount != null) {
    print('Filtered: ${videoResponse!.raiMediaFilteredCount} videos');
    print('Reasons: ${videoResponse.raiMediaFilteredReasons}');
  }
}

Before (Google AI):

import 'package:googleai_dart/googleai_dart.dart';

final client = GoogleAIClient(
  config: GoogleAIConfig.googleAI(
    authProvider: ApiKeyProvider('YOUR_API_KEY'),
  ),
);

After (Vertex AI):

import 'package:googleai_dart/googleai_dart.dart';

final client = GoogleAIClient(
  config: GoogleAIConfig.vertexAI(
    projectId: 'your-project-id',
    location: 'us-central1',
    authProvider: MyOAuthProvider(), // Implement OAuth
  ),
);