Gemini 3 Pro API Integration

Overview

gemini-3-pro-preview

Key Capabilities

• Massive Context: 1M token input, 64k token output
• Dynamic Thinking: Adaptive reasoning with high/low modes
• Streaming: Real-time token delivery
• Chat: Multi-turn conversations with history
• Production-Ready: Error handling, retry logic, cost optimization

When to Use This Skill

• Setting up Gemini 3 Pro API access
• Building text generation applications
• Implementing chat applications with reasoning
• Configuring advanced thinking modes
• Deploying production Gemini applications
• Optimizing API usage and costs

Quick Start

Prerequisites

• API Key: Get from Google AI Studio
• Python 3.9+ or Node.js 18+

Python Quick Start

# Install SDK
pip install google-genai

# Basic usage
import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel("gemini-3-pro-preview")

response = model.generate_content("Explain quantum computing")
print(response.text)

Node.js Quick Start

// Install SDK
npm install @google/generative-ai

// Basic usage
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("YOUR_API_KEY");
const model = genAI.getGenerativeModel({ model: "gemini-3-pro-preview" });

const result = await model.generateContent("Explain quantum computing");
console.log(result.response.text());

Core Workflows

Workflow 1: Quick Start Setup

1. Get API Key
   • Visit Google AI Studio
   • Create or select project
   • Generate API key
   • Copy key securely
2. Install SDK
   bash

   # Python
   pip install google-genai
   
   # Node.js
   npm install @google/generative-ai

3. Configure Authentication
   python

   # Python - using environment variable (recommended)
   import os
   import google.generativeai as genai
   
   genai.configure(api_key=os.getenv("GEMINI_API_KEY"))

   typescript

   // Node.js - using environment variable (recommended)
   const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

4. Make First API Call
   python

   # Python
   model = genai.GenerativeModel("gemini-3-pro-preview")
   response = model.generate_content("Write a haiku about coding")
   print(response.text)

5. Verify Success
   • Check response received
   • Verify text output
   • Note token usage
   • Confirm API key working

Workflow 2: Chat Application Development

1. Initialize Chat Model
   python

   # Python
   model = genai.GenerativeModel(
       "gemini-3-pro-preview",
       generation_config={
           "thinking_level": "high",  # Dynamic reasoning
           "temperature": 1.0,  # Keep at 1.0 for best results
           "max_output_tokens": 8192
       }
   )

2. Start Chat Session
   python

   chat = model.start_chat(history=[])

3. Send Message with Streaming
   python

   response = chat.send_message(
       "Explain how neural networks learn",
       stream=True
   )
   
   # Stream tokens in real-time
   for chunk in response:
       print(chunk.text, end="", flush=True)

4. Manage Conversation History
   python

   # History is automatically maintained
   # Access it anytime
   print(f"Conversation turns: {len(chat.history)}")
   
   # Continue conversation
   response = chat.send_message("Can you give an example?")

5. Handle Thought Signatures
   • SDKs handle automatically in standard chat flows
   • No manual intervention needed for basic use
   • See

     references/thought-signatures.md

     for advanced cases
6. Implement Error Handling
   python

   import time
   from google.api_core import retry, exceptions
   
   @retry.Retry(predicate=retry.if_exception_type(
       exceptions.ResourceExhausted,
       exceptions.ServiceUnavailable
   ))
   def send_with_retry(chat, message):
       return chat.send_message(message)
   
   try:
       response = send_with_retry(chat, user_input)
   except exceptions.GoogleAPIError as e:
       print(f"API error: {e}")

Workflow 3: Production Deployment

1. Setup Authentication (Production)
   python

   # Use environment variables (never hardcode keys)
   import os
   from pathlib import Path
   
   # Option 1: Environment variable
   api_key = os.getenv("GEMINI_API_KEY")
   
   # Option 2: Secrets manager (recommended for production)
   # Use Google Secret Manager, AWS Secrets Manager, etc.

2. Configure Production Settings
   python

   model = genai.GenerativeModel(
       "gemini-3-pro-preview",
       generation_config={
           "thinking_level": "high",  # or "low" for simple tasks
           "temperature": 1.0,  # CRITICAL: Keep at 1.0
           "max_output_tokens": 4096,
           "top_p": 0.95,
           "top_k": 40
       },
       safety_settings={
           # Configure content filtering as needed
       }
   )

3. Implement Comprehensive Error Handling
   python

   from google.api_core import exceptions, retry
   import logging
   
   logging.basicConfig(level=logging.INFO)
   logger = logging.getLogger(__name__)
   
   def generate_with_fallback(prompt, max_retries=3):
       @retry.Retry(
           predicate=retry.if_exception_type(
               exceptions.ResourceExhausted,
               exceptions.ServiceUnavailable,
               exceptions.DeadlineExceeded
           ),
           initial=1.0,
           maximum=10.0,
           multiplier=2.0,
           deadline=60.0
       )
       def _generate():
           return model.generate_content(prompt)
   
       try:
           return _generate()
       except exceptions.InvalidArgument as e:
           logger.error(f"Invalid argument: {e}")
           raise
       except exceptions.PermissionDenied as e:
           logger.error(f"Permission denied: {e}")
           raise
       except Exception as e:
           logger.error(f"Unexpected error: {e}")
           # Fallback to simpler model or cached response
           return None

4. Monitor Usage and Costs
   python

   def log_usage(response):
       usage = response.usage_metadata
       logger.info(f"Tokens - Input: {usage.prompt_token_count}, "
                   f"Output: {usage.candidates_token_count}, "
                   f"Total: {usage.total_token_count}")
   
       # Estimate cost (for prompts ≤200k tokens)
       input_cost = (usage.prompt_token_count / 1_000_000) * 2.00
       output_cost = (usage.candidates_token_count / 1_000_000) * 12.00
       total_cost = input_cost + output_cost
   
       logger.info(f"Estimated cost: ${total_cost:.6f}")
   
   response = model.generate_content(prompt)
   log_usage(response)

5. Implement Rate Limiting
   python

   import time
   from collections import deque
   
   class RateLimiter:
       def __init__(self, max_requests_per_minute=60):
           self.max_rpm = max_requests_per_minute
           self.requests = deque()
   
       def wait_if_needed(self):
           now = time.time()
           # Remove requests older than 1 minute
           while self.requests and self.requests[0] < now - 60:
               self.requests.popleft()
   
           # Check if at limit
           if len(self.requests) >= self.max_rpm:
               sleep_time = 60 - (now - self.requests[0])
               if sleep_time > 0:
                   time.sleep(sleep_time)
   
           self.requests.append(now)
   
   limiter = RateLimiter(max_requests_per_minute=60)
   
   def generate_with_rate_limit(prompt):
       limiter.wait_if_needed()
       return model.generate_content(prompt)

6. Setup Logging and Monitoring
   python

   import logging
   from datetime import datetime
   
   # Configure logging
   logging.basicConfig(
       level=logging.INFO,
       format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
       handlers=[
           logging.FileHandler('gemini_api.log'),
           logging.StreamHandler()
       ]
   )
   
   logger = logging.getLogger(__name__)
   
   def monitored_generate(prompt):
       start_time = datetime.now()
       try:
           response = model.generate_content(prompt)
           duration = (datetime.now() - start_time).total_seconds()
   
           logger.info(f"Success - Duration: {duration}s, "
                       f"Tokens: {response.usage_metadata.total_token_count}")
           return response
       except Exception as e:
           duration = (datetime.now() - start_time).total_seconds()
           logger.error(f"Failed - Duration: {duration}s, Error: {e}")
           raise

Thinking Levels

Dynamic Thinking System

thinking_level

thinking_level: "high"

• Maximum reasoning depth
• Best quality for complex tasks
• Slower first-token response
• Higher cost
• Use for: Complex reasoning, coding, analysis, research

thinking_level: "low"

• Minimal reasoning overhead
• Faster response
• Lower cost
• Simpler output
• Use for: Simple questions, factual answers, quick queries

Configuration

# Python
model = genai.GenerativeModel(
    "gemini-3-pro-preview",
    generation_config={
        "thinking_level": "high"  # or "low"
    }
)

// Node.js
const model = genAI.getGenerativeModel({
  model: "gemini-3-pro-preview",
  generationConfig: {
    thinking_level: "high"  // or "low"
  }
});

Critical Notes

thinking_level

thinking_budget

references/thinking-levels.md

Streaming Responses

Python Streaming

response = model.generate_content(
    "Write a long article about AI",
    stream=True
)

for chunk in response:
    print(chunk.text, end="", flush=True)

Node.js Streaming

const result = await model.generateContentStream("Write a long article about AI");

for await (const chunk of result.stream) {
    process.stdout.write(chunk.text());
}

Benefits

• Lower perceived latency
• Real-time user feedback
• Better UX for long responses
• Can process tokens as they arrive

references/streaming.md

Cost Optimization

Pricing (Gemini 3 Pro)

Optimization Strategies

1. Keep prompts under 200k tokens (50% cheaper)
2. Use

   thinking_level: "low"

   for simple tasks (faster, lower cost)
3. Implement context caching for reusable contexts (see

   gemini-3-advanced

   skill)
4. Monitor token usage and set budgets
5. Use Gemini 1.5 Flash for simple tasks (20x cheaper)

references/best-practices.md

Model Selection

Gemini 3 Pro vs Other Models

When to Use Gemini 3 Pro

When to Use Alternatives

• Gemini 1.5 Flash: Simple tasks, cost-sensitive applications
• Gemini 1.5 Pro: Multimodal tasks, general use
• Gemini 2.5 models: Experimental features, specific capabilities

Error Handling

Common Errors

ResourceExhausted

InvalidArgument

PermissionDenied

DeadlineExceeded

Production Error Handling

from google.api_core import exceptions, retry

@retry.Retry(
    predicate=retry.if_exception_type(
        exceptions.ResourceExhausted,
        exceptions.ServiceUnavailable
    ),
    initial=1.0,
    maximum=60.0,
    multiplier=2.0
)
def safe_generate(prompt):
    try:
        return model.generate_content(prompt)
    except exceptions.InvalidArgument as e:
        logger.error(f"Invalid argument: {e}")
        raise
    except exceptions.PermissionDenied as e:
        logger.error(f"Permission denied - check API key: {e}")
        raise
    except Exception as e:
        logger.error(f"Unexpected error: {e}")
        raise

references/error-handling.md

References

• Setup Guide - Installation, authentication, configuration
• Best Practices - Optimization, cost control, tips

• Text Generation - Detailed text generation patterns
• Chat Patterns - Chat conversation management
• Thinking Levels - Dynamic thinking system guide
• Streaming - Streaming response patterns

• Error Handling - Error handling and retry strategies

• Gemini 3 Documentation
• Python SDK Docs
• Node.js SDK Docs
• API Reference
• Pricing

Next Steps

After Basic Setup

1. Explore chat applications - Build conversational interfaces
2. Add multimodal capabilities - Use

   gemini-3-multimodal

   skill
3. Add image generation - Use

   gemini-3-image-generation

   skill
4. Add advanced features - Use

   gemini-3-advanced

   skill (caching, tools, batch)

Common Integration Patterns

• Simple Chatbot: This skill only
• Multimodal Assistant: This skill +

  gemini-3-multimodal

• Creative Bot: This skill +

  gemini-3-image-generation

• Production App: All 4 Gemini 3 skills

Troubleshooting

Issue: API key not working

Issue: Rate limit errors

Issue: Slow responses

thinking_level: "low"

Issue: High costs

Issue: Temperature warnings

Summary