gemini-api

# Gemini API Build applications with the Google Gemini API and SDKs. ## When to Use - Building applications that call the Gemini API - Code imports `google.generativeai` (Python) or `@google/generative-ai` (TypeScript) - User asks about Gemini API patterns, function calling, streaming, or vision - Implementing agent workflows with the Gemini API - Optimizing API costs, token usage, or latency ## Model Selection | Model | ID | Best For | |-------|-----|----------| | Pro 2.5 | `gemini-2.5-pro` | Complex reasoning, architecture, research | | Flash 2.5 | `gemini-2.5-flash` | Balanced coding, most development tasks | | Flash Lite 2.5 | `gemini-2.5-flash-lite` | Fast responses, high-volume, cost-sensitive | Default to Flash 2.5 unless the task requires deep reasoning (Pro) or speed/cost optimization (Flash Lite). For production, prefer pinned snapshot IDs over aliases. ## Python SDK ### Installation ```bash pip install google-generativeai ``` ### Basic Message ```python import os import google.generativeai as genai genai.configure(api_key=os.environ["GEMINI_API_KEY"]) model = genai.GenerativeModel("gemini-2.5-flash") response = model.generate_content("Explain async/await in Python") print(response.text) ``` ### Streaming ```python model = genai.GenerativeModel("gemini-2.5-flash") response = model.generate_content( "Write a haiku about coding", stream=True, ) for chunk in response: print(chunk.text, end="", flush=True) ``` ### System Instruction ```python model = genai.GenerativeModel( "gemini-2.5-flash", system_instruction="You are a senior Python developer. Be concise.", ) response = model.generate_content("Review this function") ``` ## TypeScript SDK ### Installation ```bash npm install @google/generative-ai ``` ### Basic Message ```typescript import { GoogleGenerativeAI } from "@google/generative-ai"; const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!); const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" }); const result = await model.generateContent("Explain async/await in TypeScript"); console.log(result.response.text()); ``` ### Streaming ```typescript const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" }); const result = await model.generateContentStream("Write a haiku"); for await (const chunk of result.stream) { const text = chunk.text(); process.stdout.write(text); } ``` ## Function Calling (Tool Use) Define tools and let Gemini call them: ```python def get_weather(location: str, unit: str = "celsius") -> dict: """Get current weather for a location.""" # Your implementation here return {"temp": 18, "unit": unit, "location": location} model = genai.GenerativeModel( "gemini-2.5-flash", tools=[get_weather], ) chat = model.start_chat(enable_automatic_function_calling=True) response = chat.send_message("What's the weather in SF?") print(response.text) ``` For manual function calling (more control): ```python import google.generativeai as genai from google.generativeai.types import FunctionDeclaration, Tool weather_func = FunctionDeclaration( name="get_weather", description="Get current weather for a location", parameters={ "type": "object", "properties": { "location": {"type": "string", "description": "City name"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, }, "required": ["location"], }, ) tool = Tool(function_declarations=[weather_func]) model = genai.GenerativeModel("gemini-2.5-flash", tools=[tool]) chat = model.start_chat() response = chat.send_message("What's the weather in SF?") # Check for function call in response for part in response.parts: if fn := part.function_call: # Execute the function with fn.args result = get_weather(**dict(fn.args)) # Send result back response = chat.send_message( genai.protos.Content( parts=[genai.protos.Part( function_response=genai.protos.FunctionResponse( name=fn.name, response={"result": result}, ) )] ) ) ``` ## Vision Send images for analysis: ```python import PIL.Image image = PIL.Image.open("diagram.png") model = genai.GenerativeModel("gemini-2.5-flash") response = model.generate_content( ["Describe this diagram", image] ) print(response.text) ``` Or from raw bytes: ```python with open("diagram.png", "rb") as f: image_data = f.read() response = model.generate_content([ "Describe this diagram", {"mime_type": "image/png", "data": image_data}, ]) ``` ## Thinking (Extended Reasoning) For complex reasoning tasks, enable thinking in the generation config: ```python model = genai.GenerativeModel("gemini-2.5-flash") response = model.generate_content( "Solve this math problem step by step...", generation_config=genai.GenerationConfig( thinking_config=genai.types.ThinkingConfig( thinking_budget=10000, ), ), ) for part in response.candidates[0].content.parts: if part.thought: print(f"Thinking: {part.text}") else: print(f"Answer: {part.text}") ``` ## Context Caching Cache large contexts to reduce costs on repeated requests: ```python from google.generativeai import caching import datetime cache = caching.CachedContent.create( model="gemini-2.5-flash", display_name="my-cached-context", system_instruction="You are an expert analyst.", contents=[large_context_text], ttl=datetime.timedelta(minutes=30), ) # Use the cached content with a model model = genai.GenerativeModel.from_cached_content(cache) response = model.generate_content("Question about the cached context") ``` ## Batch Requests Process multiple requests efficiently: ```python model = genai.GenerativeModel("gemini-2.5-flash") # Use asyncio for concurrent requests import asyncio async def process_batch(prompts: list[str]) -> list[str]: """Process multiple prompts concurrently.""" async_model = genai.GenerativeModel("gemini-2.5-flash") tasks = [ async_model.generate_content_async(prompt) for prompt in prompts ] responses = await asyncio.gather(*tasks) return [r.text for r in responses] # Run the batch results = asyncio.run(process_batch(prompts)) ``` ## Agent Loop Build multi-step agents with function calling: ```python import google.generativeai as genai # Define tools as function declarations tools = [ genai.protos.Tool(function_declarations=[ genai.protos.FunctionDeclaration( name="search_codebase", description="Search the codebase for relevant code", parameters={ "type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"], }, ) ]) ] model = genai.GenerativeModel("gemini-2.5-flash", tools=tools) chat = model.start_chat() response = chat.send_message("Review the auth module for security issues") # Agentic loop: keep processing function calls until the model stops while response.candidates[0].finish_reason.name == "STOP" and any( part.function_call for part in response.parts ): for part in response.parts: if fn := part.function_call: result = execute_tool(fn.name, dict(fn.args)) response = chat.send_message( genai.protos.Content( parts=[genai.protos.Part( function_response=genai.protos.FunctionResponse( name=fn.name, response={"result": result}, ) )] ) ) print(response.text) ``` ## Cost Optimization | Strategy | Savings | When to Use | |----------|---------|-------------| | Context caching | Up to 75% on cached tokens | Repeated system prompts or context | | Batch with async | Variable | Non-time-sensitive bulk processing | | Flash Lite instead of Flash | ~75% | Simple tasks, classification, extraction | | Shorter max_output_tokens | Variable | When you know output will be short | | Streaming | None (same cost) | Better UX, same price | ## Error Handling ```python import time from google.api_core.exceptions import ( ResourceExhausted, ServiceUnavailable, GoogleAPIError, ) try: response = model.generate_content(...) except ResourceExhausted: # Rate limited, back off and retry time.sleep(60) except ServiceUnavailable: # Service issue, retry with backoff pass except GoogleAPIError as e: print(f"API error: {e.message}") ``` ## Environment Setup ```bash # Required export GEMINI_API_KEY="your-api-key-here" # Optional: set default model export GEMINI_MODEL="gemini-2.5-flash" ``` Never hardcode API keys. Always use environment variables.