Using Google Gemini API

I primarily choose Google Gemini when I use commercial LLM APIs (most of my work involves running local LLM models using Ollama).

Note: I updated this chapter in March 2026 adding a section at the end of this chapter on the new experimental Gemini Interactions APIs.

Overall, the Google Gemini APIs provide a powerful and easy-to-use tool for developers to integrate advanced language processing capabilities into their applications, and can be a game changer for developers looking to add natural language processing capabilities to their projects.

Google Gemini offers two features that set it apart from other commercial APIs:

  • Supports a one million token context size.
  • Very low cost.

We will look at two ways to access Gemini and we will look at examples for each technique:

  • Use the Python requests library to use Gemini’s REST style interface.
  • Use Google’s Python google-genai package (and we will look at tool use in the same example).
Google Gemini API integration architecture: REST and google-genai SDK

REST Interface

The following example calls the Gemini completion API and stores user chat in a persistent context.

You need a Gemini API key from Google AI Studio, set in the environment variable GOOGLE_API_KEY. Here is a listing of the source file google-gemini/chat.hy:

 1 (import os)
 2 (import requests)
 3 
 4 ;; Get the API key from an environment variable
 5 (setv api-key (os.getenv "GOOGLE_API_KEY"))
 6 
 7 ;; Gemini REST API endpoint. The API key is sent in a request header rather
 8 ;; than in the URL, so it does not end up in logs or error messages.
 9 (setv api-url "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent")
10 
11 (defn call-gemini [chat-history user-input]
12   "Call the Gemini REST API with the chat history plus the new user input
13   and return the parsed JSON response."
14   ;; Gemini uses the roles "user" and "model" for the two sides of a chat
15   (setv contents (+ chat-history [{"role" "user" "parts" [{"text" user-input}]}]))
16   (setv data {"contents" contents
17               "generationConfig" {"maxOutputTokens" 2000
18                                   "temperature" 1.2}})
19   (setv response (requests.post api-url
20                                 :headers {"x-goog-api-key" api-key}
21                                 :json data      ; requests encodes the dict as JSON
22                                 :timeout 60))
23   ;; Raise HTTPError for bad responses (4xx or 5xx)
24   (.raise-for-status response)
25   (.json response))
26 
27 (defn response-text [response-data]
28   "Return the text of the first candidate in a Gemini response, or an empty
29   string if the model returned no text (for example, if it was blocked)."
30   (setv candidates (.get response-data "candidates" []))
31   (setv parts (if candidates
32                   (.get (.get (get candidates 0) "content" {}) "parts" [])
33                   []))
34   (.join "" (gfor part parts (.get part "text" ""))))
35 
36 (defn main []
37   (setv chat-history [])
38   (print "Chat with Gemini. Type 'quit' (or press Ctrl-D) to exit.")
39   (while True
40     (try
41       (setv user-input (.strip (input "You: ")))
42       (except [[EOFError KeyboardInterrupt]]
43         (break)))
44     (when (in user-input ["quit" "exit"]) (break))
45     (when (not user-input) (continue))
46     (setv assistant-message (response-text (call-gemini chat-history user-input)))
47     (print "Assistant:" (or assistant-message "[no response from model]"))
48     ;; Append BOTH user and assistant messages so the model sees the context
49     (when assistant-message
50       (.append chat-history {"role" "user" "parts" [{"text" user-input}]})
51       (.append chat-history {"role" "model" "parts" [{"text" assistant-message}]}))))
52 
53 (when (= __name__ "__main__")
54   (main))

This example differs from the OpenAI API example in the previous chapter in two ways:

  • It implements a chat (multiple user input conversation) interface. The REST API is stateless, so on every turn we send the whole conversation so far: the list chat-history holds alternating “user” and “model” messages.
  • It uses the low level Python requests library to call Gemini’s REST interface directly, so you can see exactly what is sent and received. In the next section we use Google’s google-genai package instead.

A few details are worth pointing out. We send the API key in the x-goog-api-key request header rather than as a ?key= URL parameter, which keeps it out of server logs and error messages. The :json keyword argument tells requests to encode the Hy dictionary as JSON and set the content type header. The function response-text walks the nested JSON response defensively: if the model returns no text (for example when a response is blocked by a safety filter) it returns an empty string instead of raising an exception. The tests in test_gemini.hy replace requests.post with a fake so they run without an API key.

Here is a sample output showing how the chat history lets later questions refer to earlier ones:

 1 $ uv sync
 2 $ uv run hy chat.hy                    
 3 Chat with Gemini. Type 'quit' (or press Ctrl-D) to exit.
 4 You: set the value of the variable X to 1 + 7
 5 Assistant: python
 6 X = 1 + 7
 7 
 8 
 9 This code will:
10 
11 1. **Calculate:**  1 + 7, which results in 8.
12 2. **Assign:** Assign the value 8 to the variable named `X`.
13 
14 You: print the value of X + 3
15 Assistant: python
16 X = 1 + 7  # Make sure X is defined as 8
17 print(X + 3)
18 
19 
20 This code will:
21 
22 1. **Calculate:** Take the current value of X (which is 8) and add 3 to it, resulting in 11.
23 2. **Print:** Display the result (11) on the console.
24 
25 You: print the value of X + 3
26 Assistant: python
27 X = 1 + 7  # Make sure X is defined as 8
28 print(X + 3)
29 
30 This code will:
31 
32 1. **Calculate:** Take the current value of `X` (which is 8) and add 3 to it, resulting in 11.
33 2. **Print:** Display the result (11) on the console.
34 
35 You: quit

Using Google’s Python Package to Access Gemini

We use the package google-genai in the example context_url.hy:

 1 (import os)
 2 (import google [genai])
 3 (import pprint [pprint])
 4 
 5 ;; ======================================================================
 6 ;; context_url.hy - Demonstrates URL Context tool with Gemini API
 7 ;; ======================================================================
 8 ;; This script uses the url_context tool to allow Gemini to access and analyze
 9 ;; web page content directly from a URL.
10 ;;
11 ;; Prerequisites:
12 ;;   - Set the GOOGLE_API_KEY environment variable
13 ;;   - The google-genai SDK is a dependency in pyproject.toml (uv sync installs it)
14 ;;
15 ;; Usage:
16 ;;   hy context_url.hy
17 ;;   (or import and call context_qa() function)
18 ;;
19 ;; Example prompt format: "<URL> <question about the page>"
20 ;;
21 ;; ======================================================================
22 
23 ;; Set environment variable: GOOGLE_API_KEY must be set before running
24 
25 (setv client (genai.Client))  ;; Initialize the Google AI client
26       
27 (defn context_qa [prompt]
28   "Calls the Gemini API using the url_context tool.
29   
30   The prompt should contain both a URL and a question about its content.
31   
32   Args:
33     prompt - A string combining URL and question, e.g.,
34              \"https://example.com What is the main topic?\"
35   
36   Returns:
37     The text response from Gemini based on the URL content."
38 
39   (setv
40     response
41     (client.models.generate_content
42       :model "gemini-2.5-flash"
43       :contents prompt
44       :config {"tools" [{"url_context" {}}]}))
45 
46   (return response.text))
47 
48 (when (= __name__ "__main__")
49   (print
50     (context_qa
51       "https://markwatson.com What musical instruments does Mark Watson play?")))

The tool url_context is called automatically when a URI is present in a user prompt. A prompt can also contain multiple URIs and they are all used in generating text from the input prompt.

The output for this example is:

1 $ uv run hy context_url.hy                                    
2 Mark Watson plays the guitar, didgeridoo, and American Indian flute.

If you want to reuse this example without using tools, just remove the option :config {“tools” [{“url_context” {}}]}.

The GitHub repository for the this Google package also contains useful examples and documentation links: https://github.com/googleapis/python-genai.

New Experimental Gemini Interactions APIs

The following code listing demonstrates the powerful synergy between Google’s latest generative AI capabilities and the expressive, Lisp-like syntax of the Hy language. By leveraging the google.genai library, the script orchestrates a new experimental “Interaction” that bridges the gap between real-world web data and private, localized business logic. It begins by initializing a Gemini client and defining a structured schema for a custom tool, check_inventory, which simulates an internal database lookup. The core of the program lies in the client.interactions.create call, where a natural language prompt triggers a multi-step workflow: first, utilizing the built-in Google Search tool to identify current market trends, and subsequently, preparing to invoke the local inventory function for those specific items. This approach highlights how modern LLMs have evolved from simple text generators into central reasoning engines capable of coordinating complex tool-calling sequences across disparate data environments.

This listing of gemini_interactions_api.hy is edited for page width:

 1 (import google [genai])
 2 
 3 ;; Set environment variable: "GOOGLE_API_KEY"
 4 ;; More info:
 5 ;; https://ai.google.dev/gemini-api/docs/interactions
 6 
 7 (setv client (genai.Client))
 8 
 9 ;; Define a custom function tool that checks an internal inventory database
10 (setv check-inventory
11   {"type" "function"
12    "name" "check_inventory"
13    "description" "Checks the internal inventory database for a product model."
14    "parameters"
15      {"type" "object"
16       "properties"
17         {"product_name"
18            {"type" "string"
19             "description" "The name or model of the product to check"}}
20       "required" ["product_name"]}})
21 
22 ;; Create an interaction that combines a built-in Google Search tool with
23 ;; the custom check_inventory function tool
24 (setv interaction
25   (client.interactions.create
26     :model "gemini-3-flash-preview"
27     :input (+ "Search the web for top 3 trending noise-canceling headphones today, "
28               "and check if we have those models in our internal inventory.")
29     :tools [{"type" "google_search"}   ; built-in tool
30             check-inventory]))         ; custom function tool
31 
32 ;; Process each output from the interaction
33 (for [output interaction.outputs]
34   (cond
35     (= output.type "function_call")
36       (do
37         (print f"Tool ID: {output.id}")
38         (print f"Calling: {output.name} with args: {output.arguments}"))
39     (= output.type "text")
40       (print output.text)))

This code uses Hy’s interoperability with Python, allowing developers to define complex JSON-like tool schemas using native Hy dictionaries. This example was originally written in Python for the Gemini online documentation. By combining the Google Search built-in tool with the user defined check_inventory function, the code creates a unified execution context. The Gemini model intelligently determines when to use the live web versus when to request data from the local environment, returning a structured interaction object that contains both the model’s reasoning and the specific tool calls required to fulfill the request.

Processing the results is handled a for loop that iterates over the interaction’s outputs, using a cond macro to differentiate between raw text responses and pending function calls. This pattern is useful for production workflows because it allows an application to capture the specific arguments such as product names discovered via search and pass them into actual database queries or call local functions. This example effectively illustrates the “agentic” workflow where the AI doesn’t just provide an answer, but generates the necessary “Tool ID” and argument set to drive further programmatic action.

Here is example output:

1 $ uv run hy gemini_interactions_api.hy 
2 UserWarning: Interactions usage is experimental and may change in future versions.
3   (client.interactions.create
4 Tool ID: 4uu76c87
5 Calling: check_inventory with args: {'product_name': 'Sony WH-1000XM6'}
6 Tool ID: wk8lh5fn
7 Calling: check_inventory with args: {'product_name': 'Bose QuietComfort Ultra Headphones (2nd Gen)'}
8 Tool ID: 3gkrxgyc
9 Calling: check_inventory with args: {'product_name': 'Apple AirPods Pro 3'}

Dear reader, note that these APIs may change. Please check out the documentation https://ai.google.dev/gemini-api/docs/interactions for more use cases of the Interactions APIs.

Wrap Up for Using the Gemini APIs

There are many good commercial LLM APIs (and I have most of them) but I currently most frequently use Gemini for two reasons: supports a one million token context size and is very low cost.

I discuss Gemini in more detail in another book that you can read online: https://leanpub.com/solo-ai/read.

Optional Practice Problems

  • Persistent Conversation History: Modify the CLI chat script chat.hy to serialize the chat history to a JSON file when exiting, and load it when starting. This allows resuming chat sessions across restarts.
  • Inspect Grounding Citations: Modify the web_search.hy script to print the sources and URLs referenced by the google_search tool. You will need to inspect the model’s response metadata structure.
  • System Instructions in GUI: Add a system instruction text field in ui_chat.hy to allow specifying the behavior or persona of the model (such as a helpful programming tutor) via the API request configuration.