gemini-3-pro-api（Gemini 3 专业版 API）

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

1. Install SDK # Python pip install google-genai # Node.js npm install @google/generative-ai
2. 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);
3. Make First API Call # Python model = genai.GenerativeModel("gemini-3-pro-preview") response = model.generate_content("Write a haiku about coding") print(response.text)
4. 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

1. 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)

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

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

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!