First Steps Using Python with the Gemini Python Library

Introduction

Welcome to your first practical steps in harnessing the power of Google’s Gemini models using Python. The Gemini API provides access to Google’s state-of-the-art large language models, enabling you to integrate generative AI capabilities into your applications. To facilitate this interaction within a Python environment, Google provides the google-generativeai library, often referred to as the Gemini Python SDK (Software Development Kit).

What is an SDK? An SDK is a collection of software development tools in one installable package. They ease the creation of applications by providing compilers, debuggers, and often a software framework. In our context, the Gemini Python SDK simplifies interaction with the Gemini API by handling the complexities of HTTP requests, responses, authentication, and data formatting, allowing you to focus on what you want to achieve with the model rather than the low-level communication details.

This chapter focuses on the crucial first step: setting up your environment, installing the necessary library, and authenticating your requests to the Gemini API. Authentication verifies your identity and authorizes your application to use the API, often tying usage to your Google Cloud project for billing and quota management.

Prerequisites

Before you begin coding, ensure you have the following:

  1. Python Installed: You’ll need a compatible version of Python installed on your system (typically Python 3.9 or newer is recommended for modern libraries). You can check your version using python --version or python3 --version in your terminal.
  2. Google API Key: You need an API key associated with a Google Cloud project where the “Generative Language API” (or potentially newer related APIs like Vertex AI) is enabled.
    • Navigate to the Google Cloud Console.
    • Create a new project or select an existing one.
    • Ensure the necessary API (e.g., Generative Language API) is enabled for your project.
    • Go to the “Credentials” section and create an API key.
    • Important: Treat your API key like a password. Keep it secure and do not embed it directly in your source code or commit it to version control.

Installation and the requirements.txt File

To use the Gemini Python SDK, you first need to install it. Python projects commonly manage dependencies using a file named requirements.txt.

What is requirements.txt? This file lists all the external Python packages that your project depends on, along with optional version specifiers. Using requirements.txt ensures that anyone working on the project (or any environment where the project is deployed) can install the exact same set of dependencies easily. This reproducibility is crucial for avoiding compatibility issues.

For basic Gemini API interaction, your requirements.txt file needs to contain at least the SDK library:

1 # requirements.txt
2 google-generativeai

Installation Steps:

  1. Create a file named requirements.txt in your project directory.
  2. Add the line google-generativeai to this file.
  3. It’s highly recommended to use a Python virtual environment (venv) to isolate your project’s dependencies. Create and activate one: 
    1 python -m venv myenv          # Create the virtual environment (e.g., named 'myenv')
2 source myenv/bin/activate   # Activate on Linux/macOS
3 # or
4 .\myenv\Scripts\activate    # Activate on Windows
  4. Install the dependencies listed in your requirements.txt file using pip, Python’s package installer: 
    1 pip install -r requirements.txt
    Pip will read the file and download/install the google-generativeai library and any packages it depends on.

Authentication: Connecting Securely

Authentication is how the Gemini API verifies that your request is legitimate and associated with your account. The primary method used by the SDK, especially for development and server-side applications, is an API key.

Best Practice: Secure API Key Management As mentioned, never hardcode your API key directly into your source code. This is a significant security risk. If your code is ever exposed (e.g., committed to a public repository), your key could be stolen and used maliciously, potentially incurring costs on your account.

The recommended approach is to store your API key in an environment variable. An environment variable is a variable stored outside your program, within the operating system’s environment. Your code can then read this variable at runtime.

Setting the Environment Variable:

  • Linux/macOS: 
    1 export GOOGLE_API_KEY='YOUR_API_KEY_HERE'
    (Add this line to your shell profile like ~/.bashrc or ~/.zshrc for persistence across sessions).
  • Windows (Command Prompt): 
    1 set GOOGLE_API_KEY=YOUR_API_KEY_HERE
  • Windows (PowerShell): 
    1 $env:GOOGLE_API_KEY='YOUR_API_KEY_HERE'
  • Using .env files: For project-specific variables, you can use a .env file in your project root and the python-dotenv library to load them. Install it (pip install python-dotenv) and load it at the start of your script.

Example 1: auth_test1.py - Basic Authentication & Setup

This script demonstrates the fundamental step of configuring the Gemini SDK with your API key retrieved from the environment.

 1 # --- Example 1: Basic Authentication & Setup ---
 2 # Purpose: Configure the Gemini API client using an API key
 3 #          stored securely in an environment variable.
 4 
 5 import google.generativeai as genai
 6 import os
 7 import sys # sys is imported but not used in this specific snippet
 8 
 9 # Best practice: Store your API key in an environment variable
10 # (e.g., GOOGLE_API_KEY) rather than hardcoding it.
11 # You can set this in your system or using a .env file with python-dotenv.
12 try:
13     # 1. Retrieve the API key from the environment variable
14     api_key = os.getenv('GOOGLE_API_KEY')
15     if not api_key:
16         # Raise KeyError if the variable is not set or is empty
17         raise KeyError("GOOGLE_API_KEY environment variable not found or is empty.")
18 
19     # 2. Configure the SDK with the retrieved API key
20     genai.configure(api_key=api_key)
21 
22     # 3. Verify configuration by listing available models (optional but recommended)
23     # This makes a simple API call to confirm authentication works.
24     print("\nAvailable models supporting content generation:")
25     for m in genai.list_models():
26         # Filter for models that can actually generate text/content
27         if 'generateContent' in m.supported_generation_methods:
28             print(m.name)
29 
30 # 4. Handle potential errors during configuration
31 except KeyError as e:
32     # Specific error for missing environment variable
33     print(f"Error: {e}")
34     print("Please set the GOOGLE_API_KEY environment variable with your API key.")
35     # Consider adding instructions here on *how* to set it based on OS
36 except Exception as e:
37     # Catch any other exceptions during the genai.configure() or list_models() calls
38     print(f"An error occurred during configuration or model listing: {e}")

Explanation:

  1. Import necessary libraries: google.generativeai (the SDK) and os (to access environment variables).
  2. Retrieve API Key: os.getenv('GOOGLE_API_KEY') attempts to read the value of the environment variable named GOOGLE_API_KEY. We add a check to ensure it’s not None or empty.
  3. Configure SDK: genai.configure(api_key=api_key) is the core function call. It initializes the SDK globally within your script’s context, setting up the necessary credentials for subsequent API calls.
  4. Verify Configuration (Optional but useful): genai.list_models() makes a lightweight call to the API to retrieve a list of available models. Successfully getting this list back confirms that your API key is valid and the SDK is configured correctly. We filter this list to show only models capable of content generation ('generateContent' in m.supported_generation_methods).
  5. Error Handling: The try...except block gracefully handles potential issues:
    • KeyError: Catches the specific error if the GOOGLE_API_KEY environment variable isn’t set.
    • Exception: Catches other potential errors during the configuration or the list_models call (e.g., network issues, invalid API key).

Running the Script: Save the code as auth_test1.py. Ensure your GOOGLE_API_KEY environment variable is set, then run the script from your terminal:

1 python auth_test1.py

If successful, you should see a list of model names printed to the console. If not, the error messages should guide you.

Making Your First API Call: Text Generation

Once the SDK is configured via genai.configure(), you can start using the models. Let’s look at a simple text generation example.

Example 2: text_generation.py

This script builds upon the authentication setup to send a prompt to a Gemini model and receive a generated response.

 1 # --- Example 2: Text Generation ---
 2 # Purpose: Use the configured Gemini client to generate text
 3 #          based on a given prompt.
 4 
 5 import google.generativeai as genai
 6 import os
 7 import sys # sys is imported but not used in this specific snippet
 8 
 9 # Best practice: Store your API key in an environment variable
10 # (e.g., GOOGLE_API_KEY) rather than hardcoding it.
11 try:
12     # 1. Configure the SDK (Required in every script/session using the API)
13     api_key = os.getenv('GOOGLE_API_KEY')
14     if not api_key:
15         raise KeyError("GOOGLE_API_KEY environment variable not found or is empty.")
16     genai.configure(api_key=api_key)
17 
18     # 2. Select the model
19     # Use a specific model name from the list obtained in Example 1.
20     # 'gemini-1.5-flash' is often a good balance of speed and capability.
21     # Note: The user example specified 'gemini-2.0-flash', ensure this model is available.
22     model = genai.GenerativeModel('gemini-1.5-flash') # Or 'gemini-pro', 'gemini-1.0-pro' etc.
23 
24     # 3. Define the prompt (Your instruction to the model)
25     prompt = "Brainstorm 5 blog post ideas about remote work productivity for solo knowledge workers."
26 
27     # 4. Generate content by calling the model
28     # This makes the actual API request to the Gemini service.
29     response = model.generate_content(prompt)
30 
31     # 5. Process and print the response
32     print("\n--- Blog Post Ideas ---")
33     # Check if the response contains parts (text content)
34     # Responses might be empty if blocked due to safety settings or other issues.
35     if response.parts:
36         print(response.text) # Access the generated text
37     else:
38         # Provide feedback if the response was empty or blocked
39         print("Response was empty or potentially blocked.")
40         # response.prompt_feedback often contains reasons for blocking (e.g., safety ratings)
41         print(f"Safety feedback: {response.prompt_feedback}")
42 
43 
44 # 6. Handle potential errors during generation
45 except KeyError as e:
46     # Handle missing API key specifically
47     print(f"Error: {e}")
48     print("Please set the GOOGLE_API_KEY environment variable.")
49 except AttributeError:
50     # This might occur if genai.configure was not called successfully before model usage
51     print("Error: Gemini API likely not configured. Ensure GOOGLE_API_KEY is set and valid.")
52 except Exception as e:
53     # Catch other errors during model instantiation or generation
54     print(f"An error occurred during text generation: {e}")
55     # This could include API errors, network issues, invalid model names, etc.

Explanation:

  1. Configure SDK: Notice that genai.configure() must be called again here. Configuration typically needs to happen once per script execution or application session that intends to use the API.
  2. Select Model: genai.GenerativeModel('model-name') creates an instance of the model you want to interact with. You should use one of the model names listed by the auth_test1.py script (e.g., gemini-1.5-flash, gemini-pro).
  3. Define Prompt: This is the input text you provide to the model.
  4. Generate Content: model.generate_content(prompt) sends the prompt to the specified Gemini model via the API and waits for the response.
  5. Process Response: The result is a GenerateContentResponse object.
    • response.text provides the primary generated text content if available.
    • It’s crucial to check if the response contains content (if response.parts:). Sometimes, a response might be blocked due to safety filters or other reasons.
    • response.prompt_feedback can provide information about why content might have been blocked (e.g., safety ratings).
  6. Error Handling: Includes checks for KeyError (missing API key), AttributeError (if genai wasn’t configured properly before trying to use GenerativeModel), and general Exceptions for API or network issues during the generation call.

Running the Script: Save the code as text_generation.py. Ensure your GOOGLE_API_KEY is set, then run:

1 python text_generation.py

You should see the brainstormed blog post ideas printed to your console.

Wrap Up

You have now successfully set up your Python environment, installed the Gemini SDK using pip and requirements.txt, and learned the fundamental process of authenticating with the Gemini API using an API key stored securely in an environment variable. You’ve also run your first text generation query.

Authentication is the gateway to using the API. By following best practices like using environment variables, you ensure your credentials remain secure while enabling your Python applications to leverage the power of Google’s Gemini models. In the following chapters, we will explore more advanced features of the API and the Python SDK.

Up next

Gemini Thinking Mode