Google Generative AI Python SDK

google-generativeai was Google’s first official Python client for the Gemini API, wrapping the GenerativeModel and ChatSession primitives that let developers send text, image, and multi-turn prompts to Gemini models, stream responses, embed content, cache large context, upload files, and manage tuned models through a small, typed surface built on Google’s generativelanguage gRPC/REST backend.

As of December 2025 the package is deprecated: Google folded the feedback from this SDK into the unified google-genai package and set an end-of-life date of November 30, 2025 for this repository (now renamed google-gemini/deprecated-generative-ai-python on GitHub). Every import now raises a FutureWarning pointing at the migration guide. It remains installable and functional for existing integrations receiving critical bug fixes only — new projects should use google-genai instead.

What You Get

• GenerativeModel and ChatSession classes for single- and multi-turn text, image, and multimodal prompts to Gemini models
• embed_content / embed_content_async helpers for turning text into vector embeddings with configurable task types (retrieval, similarity, classification, clustering)
• File API bindings (upload_file, get_file, list_files, delete_file) for sending large media inputs to the Gemini API without inlining them in requests
• Context caching via CachedContent to reuse large system prompts or documents across calls without re-sending them
• Model management functions (list_models, create_tuned_model, get_tuned_model) for discovering base models and managing fine-tuned models

Common Use Cases

• Prototyping a Gemini-powered chatbot - a developer wires up ChatSession to prototype a multi-turn assistant against gemini-1.5-flash
• Maintaining a legacy integration - a team with an existing production integration keeps using google-generativeai for critical bug fixes while planning a migration window to google-genai
• Semantic search embeddings - a project calls embed_content with task_type=“retrieval_document” to generate embeddings for a document index
• Large-context reuse - an app uses CachedContent to cache a large reference document once and reference it across many generate_content calls without re-sending the tokens

Under The Hood

Architecture The package is organized as a flat set of feature modules under google/generativeai/ (generative_models.py, embedding.py, caching.py, files.py, models.py, retriever.py, permission.py, operations.py, answer.py, responder.py) that all funnel through a single client.py, which lazily constructs and caches synchronous and async gRPC client instances behind get_default_generative_client()/get_default_generative_async_client() so callers never touch transport details directly. GenerativeModel in generative_models.py is the central façade — its init stores model name, safety settings, generation config, tools, and system instruction, and _prepare_request() assembles a protos.GenerateContentRequest from those defaults plus per-call overrides, delegating the actual RPC to the cached client. The types/ subpackage (content_types.py, generation_types.py, safety_types.py, helper_types.py) coerces loosely-typed Python inputs — dicts, PIL images, plain strings — into the strict protobuf message types the generativelanguage API expects, keeping the public surface duck-typed while the internals stay strict. Removing generative_models.py would break the entire chat/generation surface, since caching.py, answer.py, and the notebook helpers all import GenerativeModel or its request-building helpers directly.

Tech Stack Built for Python 3.9–3.13 on top of google-ai-generativelanguage (the generated gRPC/REST client for the Gemini API), google-api-core, google-api-python-client (used specifically for the discovery-based resumable file-upload flow in client.py’s FileServiceClient), google-auth for credential handling — including a Colab-specific GCE credential patch — protobuf for the wire format, and pydantic plus typing-extensions for the public-facing config types; tqdm supports progress bars for batch operations. Distribution runs through a hand-written setup.py rather than a PEP 621 pyproject.toml, which here carries only black and pytype configuration, and filters PEP420 namespace packages under the google namespace. There’s no database or web framework in the graph — every dependency exists to talk to the generativelanguage.googleapis.com backend and Google’s auth infrastructure.

Code Quality Testing is extensive and conventional: tests/ contains 20+ test_*.py files covering nearly every module (test_generative_models.py and its _async twin, test_caching.py, test_embedding.py/_async, test_files.py, test_permission.py, test_retriever.py, test_protos.py), run with Python’s built-in unittest across a CI matrix of four Python versions (3.9–3.12). The same CI workflow runs pytype for static type checking and black —check for formatting, so both typing and style are enforced automatically rather than left aspirational. Code is thoroughly type-hinted, uses from future import annotations and TypeVar/overload patterns, and error messages are unusually specific — embedding.py’s batch-size ValueError spells out exactly what was passed and what’s valid — suggesting the API was designed to fail loudly for external developers rather than swallow bad input silently.

API Design As a now-deprecated SDK, the interesting design choices are historical rather than differentiating today: GenerativeModel bundles per-call defaults — safety settings, generation config, tools, system instruction — into a reusable object so callers don’t repeat boilerplate on every generate_content call, and the library accepts PIL Image objects directly inline with text in a content list, a genuinely low-friction multimodal API for its time. The most notable thing left in the repository now is init.py itself: importing the package raises a FutureWarning pointing at the successor google-genai package and its migration guide, and internal module aliases are explicitly deleted after import to keep the top-level namespace minimal. That self-deprecating warning-on-import is a clean, low-drama way to sunset a widely-installed package without breaking existing pins.