Gemini 3 Pro API Integration

Comprehensive guide for integrating Google's Gemini 3 Pro API/SDK into your applications. Covers setup, authentication, text generation, advanced reasoning with dynamic thinking, chat applications, streaming responses, and production deployment patterns.

Overview

Gemini 3 Pro (gemini-3-pro-preview) is Google's most intelligent model designed for complex tasks requiring advanced reasoning and broad world knowledge. This skill provides complete workflows for API integration using Python or Node.js SDKs.

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

Goal: Get from zero to first successful API call in < 5 minutes.

Steps:

1. Get API Key

   • Visit Google AI Studio
   • Create or select project
   • Generate API key
   • Copy key securely

2. Install SDK

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

3. Configure Authentication

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

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

4. Make First API Call

   # 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

Expected Outcome: Working API integration in under 5 minutes.

---

Workflow 2: Chat Application Development

Goal: Build a production-ready chat application with conversation history and streaming.

Steps:

1. Initialize Chat Model

   # 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

   chat = model.start_chat(history=[])

3. Send Message with Streaming

   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

   # 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

   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}")

Expected Outcome: Production-ready chat application with streaming, history, and error handling.

---

Workflow 3: Production Deployment

Goal: Deploy Gemini 3 Pro integration with monitoring, cost control, and reliability.

Steps:

1. Setup Authentication (Production)

   # 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

   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

   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

   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

   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

   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

Expected Outcome: Production-ready deployment with monitoring, cost control, error handling, and rate limiting.

---

Thinking Levels

Dynamic Thinking System

Gemini 3 Pro introduces thinking_level to control reasoning depth:

thinking_level: "high" (default)

• 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

⚠️ Temperature MUST stay at 1.0 - Changing temperature can cause looping or degraded performance on complex reasoning tasks.

⚠️ Cannot combine thinking_level with legacy thinking_budget parameter.

See references/thinking-levels.md for detailed guide.

---

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

See references/streaming.md for advanced patterns.

---

Cost Optimization

Pricing (Gemini 3 Pro)

Context Size	Input	Output
≤ 200k tokens	$2/1M	$12/1M
> 200k tokens	$4/1M	$18/1M

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)

See references/best-practices.md for comprehensive cost optimization.

---

Model Selection

Gemini 3 Pro vs Other Models

Model	Context	Output	Input Price	Best For
gemini-3-pro-preview	1M	64k	$2-4/1M	Complex reasoning, coding
gemini-1.5-pro	1M	8k	$7-14/1M	General use, multimodal
gemini-1.5-flash	1M	8k	$0.35-0.70/1M	Simple tasks, cost-sensitive

When to Use Gemini 3 Pro

✅ Complex reasoning tasks ✅ Advanced coding problems ✅ Long-context analysis (up to 1M tokens) ✅ Large output requirements (up to 64k tokens) ✅ Tasks requiring dynamic thinking

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

Error	Cause	Solution
ResourceExhausted	Rate limit exceeded	Implement retry with backoff
InvalidArgument	Invalid parameters	Validate input, check docs
PermissionDenied	Invalid API key	Check authentication
DeadlineExceeded	Request timeout	Reduce context, retry

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

See references/error-handling.md for comprehensive patterns.

---

References

Setup & Configuration

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

Features

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

Production

• Error Handling - Error handling and retry strategies

Official Resources

• 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

Solution: Verify API key in Google AI Studio, check environment variable

Issue: Rate limit errors

Solution: Implement rate limiting, upgrade to paid tier, reduce request frequency

Issue: Slow responses

Solution: Use thinking_level: "low" for simple tasks, enable streaming, reduce context size

Issue: High costs

Solution: Keep prompts under 200k tokens, use appropriate thinking level, consider Gemini 1.5 Flash for simple tasks

Issue: Temperature warnings

Solution: Keep temperature at 1.0 (default) - do not modify for complex reasoning tasks

---

Summary

This skill provides everything needed to integrate Gemini 3 Pro API into your applications:

✅ Quick setup (< 5 minutes) ✅ Production-ready chat applications ✅ Dynamic thinking configuration ✅ Streaming responses ✅ Error handling and retry logic ✅ Cost optimization strategies ✅ Monitoring and logging patterns

For multimodal, image generation, and advanced features, see the companion skills.

Ready to build? Start with Workflow 1: Quick Start Setup above!