Google’s Gemini API gives developers programmatic access to a family of multimodal language models at competitive prices. The free tier is accessible without a credit card, and the paid tier charges per million tokens with no monthly commitment. This guide covers the practical parts that the official documentation assumes you already know: how to get an API key in minutes, how to structure your first calls, what the rate limits actually feel like, and how to keep costs predictable at scale.
Getting Your API Key in Google AI Studio
The fastest path to a working key is Google AI Studio at aistudio.google.com. The free tier does not require a credit card — sign in with a Google account and you have a key immediately. This is the right path for prototyping, testing, and development. It is not suitable for production traffic without a paid plan, because the free tier has per-project rate limits that are not published publicly.
To get a key:
1. Go to aistudio.google.com and sign in with your Google account.
2. Click Get API Key in the left navigation.
3. Click Create API Key.
4. Copy the key and store it securely — it will not be shown again.
The key is a string starting with AIza.... Do not commit it to version control. Store it in an environment variable or a secrets manager. If you need to use the API in production at scale, the next step is linking a Google Cloud billing account, which switches you from the free tier to the pay-as-you-go model.
Your First API Call: Text Generation
The Google Generative Language API uses a simple REST structure. With the official Python SDK installed, a text generation call looks like this:
pip install google-generativeaiimport google.genai as genai
import os
genai.configure(api_key=os.environ["GEMINI_API_KEY"])
model = genai.GenerativeModel("gemini-2.5-flash")
response = model.generate_content("What are the main differences between Gemini 2.5 Flash and Gemini 2.5 Pro?")
print(response.text)
The gemini-2.5-flash model is the workhorse of the Gemini family for most developers. It offers a balance of speed, context window (up to 1M tokens), multimodal input (text, images, audio, video), and the lowest per-token cost in the current Gemini lineup. It generates output at up to 65,536 tokens per request.
The key parameter worth knowing: generation_config.max_output_tokens controls the maximum length of the response. The default is managed by the model, but setting it explicitly prevents runaway responses.
Rate Limits: What 429 Actually Feels Like
The free tier in AI Studio does not publish stable RPM/TPM numbers — limits vary by project and region and are shown in the AI Studio console. What you will encounter in practice:
When you exceed your quota, the API returns a 429 Too Many Requests response with the error RESOURCE_EXHAUSTED and the message: “You have exceeded your current quota, please check your plan and billing details.” The response also indicates which quota metric was exceeded (RPM or TPM).
This means your error handling strategy matters. A basic retry with exponential backoff handles most 429s gracefully:
import time
import random
def call_with_retry(model, prompt, max_retries=3, base_delay=1.0):
for attempt in range(max_retries):
try:
return model.generate_content(prompt)
except Exception as e:
if "RESOURCE_EXHAUSTED" in str(e) and attempt < max_retries - 1:
# Exponential backoff with jitter
delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
print(f"Rate limited. Retrying in {delay:.1f}s...")
time.sleep(delay)
else:
raise
return None
On the paid tier, you can view and adjust your quota in the Google Cloud console. The free tier does not offer quota management — your limits are project-specific and visible in AI Studio.
Token Counting and Context Windows
Every API call is metered by input and output tokens. The count_tokens() method tells you how many tokens a piece of text will cost before you send it:
result = model.count_tokens("Your long text here goes in this string")
print(f"Token count: {result.total_tokens}")For long documents, feed the text to count_tokens() before sending to avoid unexpected truncation. The 1M token context window is the maximum per request — you can send a full book, a large codebase, or a long conversation history in a single call.
Pricing is tiered by model. Gemini 2.5 Flash costs $0.30 per million input tokens and $2.50 per million output tokens, as listed on costgoat.com (last updated September 25, 2026). Gemini 2.5 Flash-Lite is cheaper at $0.10/$0.40 per million tokens. Gemini 2.5 Pro is the most capable but costs $1.25/$10.00 per million tokens. All models share the same 1M token context window.
Context Caching: The Cost-Saving Feature Nobody Talks About
If you are sending the same long context repeatedly — a system prompt, a reference document, a codebase — context caching lets you pay only for the cache read, not the full context cost every time. The cache read is billed at approximately $0.03 per million tokens, which is roughly 10% of the standard input rate. The cache write is billed at the standard input rate.
This is especially useful for agentic workflows where the same system instructions and reference material are sent with every call. An agent that makes 500 calls per day with the same 50,000-token system prompt saves significantly by caching that prompt once.
To use caching, pass contents as a cached content object. The exact API for this is in the Google AI Studio SDK documentation — the SDK interface has changed between versions, so check the documentation for your installed SDK version.
Multimodal Input: Images and Documents
Gemini 2.5 Flash accepts image inputs alongside text. This is useful for document processing, OCR, image captioning, and any workflow where you need to analyze visual content:
import google.genai as genai
from pathlib import Path
model = genai.GenerativeModel("gemini-2.5-flash")
# Load an image
image_path = Path("product_photo.jpg")
image_bytes = image_path.read_bytes()
response = model.generate_content([
"Describe this product photo for an e-commerce listing.",
{"image": image_bytes, "mime_type": "image/jpeg"}
])
print(response.text)
Supported image formats include JPEG, PNG, GIF, and WebP. Audio and video are also supported on Gemini 2.5 Flash, billed at 2–3.3× the text input rate. Audio input is particularly useful for transcription pipelines or processing voice memos.
Production Checklist: What to Set Up Before Going Live
Before moving past prototyping, these are the practical things that matter:
Error handling: Handle 429 (rate limit), 400 (bad request), 403 (permission/billing issue), and 500 (server error) cases explicitly. Only 429 warrants automatic retry. 400 and 403 indicate configuration problems that retries will not fix.
Billing alerts: Set a Google Cloud billing budget alert at a specific threshold (e.g., $50/month) to avoid surprise bills. The free tier is free, but once you link a billing account, you pay for every token above the free quota.
API key rotation: If a key is compromised, revoke it immediately from the Google Cloud console and generate a new one. Do not use a single key across multiple unrelated projects — create separate keys per project for access control.
SDK version pinning: The Google Generative AI SDK has changed its interface between versions. Pin your SDK version in your requirements.txt or pyproject.toml to avoid unexpected breakage when the SDK auto-updates.
FAQ
Q: What is the free tier limit for Gemini API?
The AI Studio free tier (no credit card required) provides access to Gemini 3 Flash at approximately 10 requests per minute, 1,500 requests per day, and a 1M token context window. The exact per-project limits are shown in the AI Studio console. Free tier data may be used by Google to improve model quality — do not use it for sensitive user data without a paid plan.
Q: How does Gemini 2.5 Flash compare to Claude Sonnet on price?
Gemini 2.5 Flash at $0.30/$2.50 per million input/output tokens is significantly cheaper than Claude 4 Sonnet at approximately $3.00/$15.00 per million tokens. For high-volume applications where model quality is adequate, Gemini 2.5 Flash offers better economics. For tasks requiring the strongest reasoning, Sonnet may be worth the higher cost.
Q: Can I use Gemini API inside an automation agent?
Yes. Gemini API is a standard REST API — it works in any context that can make HTTP calls: Python scripts, Node.js applications, serverless functions, n8n workflows, Make.com scenarios, and automation agents. The free tier is suitable for testing; the paid tier is necessary for production automation running continuously.
Q: What does the 429 error look like in practice?
A 429 response from the Gemini API looks like this:
{
"error": {
"code": 429,
"message": "Too Many Requests",
"status": "RESOURCE_EXHAUSTED",
"details": [{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "RATE_LIMIT_EXCEEDED",
"domain": "generativelanguage.googleapis.com"
}]
}
}Implement exponential backoff on this response. The Retry-After header is not always present, so backoff based on the error message rather than a header value.
Q: Is there a monthly cap on the paid tier?
No. The paid tier is pure pay-as-you-go — you pay for what you use, with no monthly minimum or cap. You can set a Google Cloud budget alert to cap spending, but the API itself does not enforce a cap. If you need hard cost controls, implement them in your application layer.
