Gemini API: Prompting Quickstart

This notebook contains examples of how to write and run your first prompts with the Gemini API.

Setup

Install the Google GenAI SDK

Install the Google GenAI SDK from npm.

$ npm install @google/genai

Setup your API key

You can create your API key using Google AI Studio with a single click.

Remember to treat your API key like a password. Don’t accidentally save it in a notebook or source file you later commit to GitHub. In this notebook we will be storing the API key in a .env file. You can also set it as an environment variable or use a secret manager.

Here’s how to set it up in a .env file:

$ touch .env
$ echo "GEMINI_API_KEY=<YOUR_API_KEY>" >> .env
Tip

Another option is to set the API key as an environment variable. You can do this in your terminal with the following command:

$ export GEMINI_API_KEY="<YOUR_API_KEY>"

Load the API key

To load the API key from the .env file, we will use the dotenv package. This package loads environment variables from a .env file into process.env.

$ npm install dotenv

Then, we can load the API key in our code:

const dotenv = require("dotenv") as typeof import("dotenv");

dotenv.config({
  path: "../.env",
});

const GEMINI_API_KEY = process.env.GEMINI_API_KEY ?? "";
if (!GEMINI_API_KEY) {
  throw new Error("GEMINI_API_KEY is not set in the environment variables");
}
console.log("GEMINI_API_KEY is set in the environment variables");
GEMINI_API_KEY is set in the environment variables
Note

In our particular case the .env is is one directory up from the notebook, hence we need to use ../ to go up one directory. If the .env file is in the same directory as the notebook, you can omit it altogether.

│
├── .env
└── quickstarts
    └── Prompting.ipynb

Initialize SDK Client

With the new SDK, now you only need to initialize a client with you API key (or OAuth if using Vertex AI). The model is now set in each call.

const google = require("@google/genai") as typeof import("@google/genai");

const ai = new google.GoogleGenAI({ apiKey: GEMINI_API_KEY });

Select a model

Now select the model you want to use in this guide, either by selecting one in the list or writing it down. Keep in mind that some models, like the 2.5 ones are thinking models and thus take slightly more time to respond (cf. thinking notebook for more details and in particular learn how to switch the thiking off).

const tslab = require("tslab") as typeof import("tslab");

const MODEL_ID = "gemini-2.5-flash-preview-05-20";

Run your first prompt

Use the generateContent method to generate responses to your prompts. You can pass text directly to generate_content, and use the .text property to get the text content of the response.

const first_prompt_response = await ai.models.generateContent({
  model: MODEL_ID,
  contents: "Give me python code to sort a list",
});
tslab.display.markdown(first_prompt_response.text ?? "");

Python provides very powerful and convenient ways to sort lists. There are two primary methods:

  1. list.sort(): This method sorts the list in-place, meaning it modifies the original list directly and does not return a new list (it returns None).
  2. sorted(): This built-in function returns a new sorted list, leaving the original list unchanged. It can be used on any iterable (lists, tuples, sets, strings, etc.), not just lists.

Let’s look at examples for both, including common ways to customize the sorting.

1. list.sort() - Sorts in-place

Use this when you want to modify the original list and don’t need a new one.

# A simple list of numbers
numbers = [3, 1, 4, 1, 5, 9, 2, 6]
print(f"Original list: {numbers}")

# Sort the list in ascending order (default)
numbers.sort()
print(f"Sorted in-place (ascending): {numbers}")

# Sort the list in descending order
numbers.sort(reverse=True)
print(f"Sorted in-place (descending): {numbers}")

# Example with strings
fruits = ["banana", "apple", "cherry", "date"]
print(f"\nOriginal fruits: {fruits}")
fruits.sort()
print(f"Sorted fruits (ascending): {fruits}")
fruits.sort(reverse=True)
print(f"Sorted fruits (descending): {fruits}")

# Important: list.sort() returns None
# You should not do `new_list = old_list.sort()`
result = numbers.sort()
print(f"\nResult of numbers.sort(): {result} (it's None)")
print(f"Numbers after calling sort(): {numbers}") # The list itself is modified

2. sorted() - Returns a new sorted list

Use this when you want to keep the original list unchanged and get a new sorted one. This is also more versatile as it works on any iterable.

# A simple list of numbers
original_numbers = [3, 1, 4, 1, 5, 9, 2, 6]
print(f"Original list: {original_numbers}")

# Get a new list sorted in ascending order (default)
new_sorted_numbers_asc = sorted(original_numbers)
print(f"New sorted list (ascending): {new_sorted_numbers_asc}")
print(f"Original list after sorted(): {original_numbers} (unchanged)")

# Get a new list sorted in descending order
new_sorted_numbers_desc = sorted(original_numbers, reverse=True)
print(f"New sorted list (descending): {new_sorted_numbers_desc}")

# Example with a tuple (sorted() works on any iterable)
my_tuple = (5, 2, 8, 1)
sorted_tuple_as_list = sorted(my_tuple) # Returns a list
print(f"\nOriginal tuple: {my_tuple}")
print(f"Sorted tuple (as list): {sorted_tuple_as_list}")

3. Custom Sorting with key

Both list.sort() and sorted() accept a key argument. This key is a function that will be called on each item in the list to get a value, and that value will be used for comparison during sorting. This is incredibly powerful!

Example 1: Sorting strings by length

words = ["apple", "banana", "kiwi", "grapefruit", "date"]
print(f"\nOriginal words: {words}")

# Sort by the length of the string
words_by_length = sorted(words, key=len)
print(f"Sorted by length: {words_by_length}")

# Sort by length in descending order
words_by_length_desc = sorted(words, key=len, reverse=True)
print(f"Sorted by length (descending): {words_by_length_desc}")

Example 2: Sorting a list of tuples by a specific element

# List of students: (name, age, grade)
students = [
    ("Alice", 25, "A"),
    ("Bob", 20, "B"),
    ("Charlie", 30, "A"),
    ("David", 25, "C") # Alice and David have the same age
]
print(f"\nOriginal students: {students}")

# Sort by age (the second element, index 1)
# We use a lambda function as the key
sorted_by_age = sorted(students, key=lambda student: student[1])
print(f"Sorted by age: {sorted_by_age}")

# Sort by grade (index 2), then by age (index 1) for ties
# This shows multi-level sorting (Python's sort is stable!)
sorted_by_grade_then_age = sorted(students, key=lambda student: (student[2], student[1]))
print(f"Sorted by grade then age: {sorted_by_grade_then_age}")

Example 3: Sorting a list of dictionaries

# List of dictionaries (e.g., users)
users = [
    {"name": "John", "age": 30, "city": "New York"},
    {"name": "Jane", "age": 25, "city": "London"},
    {"name": "Mike", "age": 35, "city": "New York"},
    {"name": "Anna", "age": 25, "city": "Paris"}
]
print(f"\nOriginal users: {users}")

# Sort by 'age'
sorted_users_by_age = sorted(users, key=lambda user: user['age'])
print(f"Sorted users by age: {sorted_users_by_age}")

# Sort by 'city' then by 'age' (for users in the same city)
sorted_users_by_city_then_age = sorted(users, key=lambda user: (user['city'], user['age']))
print(f"Sorted users by city then age: {sorted_users_by_city_then_age}")

Example 4: Case-insensitive string sorting

names = ["Alice", "bob", "Charlie", "David"]
print(f"\nOriginal names: {names}")

# Sort case-insensitively
sorted_names_case_insensitive = sorted(names, key=str.lower)
print(f"Sorted names (case-insensitive): {sorted_names_case_insensitive}")

When to choose which:

  • list.sort():
    • When you don’t need the original order of the list.
    • When you are dealing with a very large list and want to save memory by avoiding the creation of a new list.
    • It’s slightly more performant for lists because it avoids the overhead of creating a new list.
  • sorted():
    • When you need to preserve the original list.
    • When you need to sort any iterable (tuple, set, dictionary items, etc.), not just a list.
    • When you want to get a new sorted list to work with, while the original remains untouched.

Both methods use Timsort, an efficient hybrid stable sorting algorithm.

Use images in your prompt

Here you will download an image from a URL and pass that image in our prompt.

const fs = require("fs") as typeof import("fs");
const path = require("path") as typeof import("path");

const IMG_URL = "https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg";

const downloadFile = async (url: string, filePath: string) => {
  if (!fs.existsSync(path.dirname(filePath))) {
    fs.mkdirSync(path.dirname(filePath), { recursive: true });
  }
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Failed to download file: ${response.statusText}`);
  }
  const buffer = await response.blob();
  const bufferData = Buffer.from(await buffer.arrayBuffer());
  fs.writeFileSync(filePath, bufferData);
};

const imagePath = path.join("../assets", "jetpack.png");
await downloadFile(IMG_URL, imagePath);
tslab.display.png(fs.readFileSync(imagePath));

const image_response = await ai.models.generateContent({
  model: MODEL_ID,
  contents: [
    `
    This image contains a sketch of a potential product along with some notes.
    Given the product sketch, describe the product as thoroughly as possible based on what you
    see in the image, making sure to note all of the product features. Return output in json format:
    {description: description, features: [feature1, feature2, feature3, etc]}
    `,
    google.createPartFromBase64(fs.readFileSync(imagePath).toString("base64"), "image/png"),
  ],
});
tslab.display.markdown(image_response.text ?? "");
{
  "description": "The \"JETPACK BACKPACK\" is an innovative personal mobility device designed to resemble a standard backpack. It is lightweight and features a discreet appearance, looking like a normal backpack when not in flight mode. Its primary function is personal aerial mobility, achieved via integrated retractable boosters. The propulsion system is steam-powered, highlighted as being 'green/clean'. The device offers a 15-minute battery life and supports convenient USB-C charging. Beyond its jetpack capabilities, it functions as a practical backpack, capable of accommodating an 18-inch laptop and featuring padded strap support for enhanced comfort during wear.",
  "features": [
    "Integrated Jetpack Functionality",
    "Retractable Boosters",
    "Steam-Powered Propulsion",
    "Green/Clean Operation",
    "Lightweight Design",
    "Normal Backpack Appearance (Discreet)",
    "Padded Strap Support",
    "Fits 18-inch Laptop",
    "USB-C Charging",
    "15-Minute Battery Life"
  ]
}

Have a chat

The Gemini API enables you to have freeform conversations across multiple turns.

const chat = ai.chats.create({
  model: MODEL_ID,
});
const chat_response_1 = await chat.sendMessage({
  message: "In one sentence, explain how a computer works to a young child.",
});
tslab.display.markdown(chat_response_1.text ?? "");

A computer is a super-fast helper that does what you tell it to do, remembers lots of information, and shows you things like games and videos.

You can see the chat history:

console.log(JSON.stringify(chat.getHistory(), null, 2));
[
  {
    "role": "user",
    "parts": [
      {
        "text": "In one sentence, explain how a computer works to a young child."
      }
    ]
  },
  {
    "parts": [
      {
        "text": "A computer is a super-fast helper that does what you tell it to do, remembers lots of information, and shows you things like games and videos."
      }
    ],
    "role": "model"
  }
]

You can keep sending messages to continue the conversation:

const chat_response_2 = await chat.sendMessage({
  message: "Okay, how about a more detailed explanation to a high schooler?",
});
tslab.display.markdown(chat_response_2.text ?? "");

Imagine a computer as a highly organized factory that specializes in processing information, all based on a very simple concept: electricity being either on or off.

Here’s how it generally works:

  1. The Foundation: Binary (0s and 1s): At its most fundamental level, a computer understands only two states: electricity flowing (on, represented as a ‘1’) or not flowing (off, represented as a ‘0’). Everything a computer does – every image, sound, text, or instruction – is broken down into these millions or billions of tiny electrical switches, called bits. Groups of bits form larger units like bytes.

  2. The Brain (CPU - Central Processing Unit): This is the “calculator” and “decision-maker.” It constantly fetches instructions (which are just sequences of 0s and 1s) from memory, performs arithmetic (addition, subtraction) and logical operations (comparing values, making decisions like “if X then Y”), and then stores the results back. The faster your CPU (measured in GHz and number of cores), the more instructions it can execute per second.

  3. Short-Term Memory (RAM - Random Access Memory): Think of RAM as the computer’s temporary workspace or workbench. When you open a program or file, a copy of it is loaded from long-term storage into RAM. This is because RAM is extremely fast, allowing the CPU to quickly access the data and instructions it needs right now. It’s “volatile,” meaning its contents disappear when the computer is turned off.

  4. Long-Term Storage (HDD/SSD - Hard Disk Drive/Solid State Drive): This is where all your files, programs, and the operating system itself are permanently stored. Unlike RAM, it’s “non-volatile,” meaning the data persists even when the power is off. HDDs store data magnetically on spinning platters, while faster SSDs use flash memory (similar to USB drives), with no moving parts.

  5. The Connectors (Buses): All these components need to talk to each other. Buses are the “data highways” – electrical pathways that allow data and instructions to travel between the CPU, RAM, storage, and other components.

  6. Input Devices: These convert human actions or real-world data into digital signals the computer can understand. Examples include keyboards (key presses become binary codes), mice (movement translates to coordinates), microphones (sound waves converted to digital audio), and cameras (light becomes pixel data).

  7. Output Devices: These convert the computer’s digital information back into a human-perceivable form. Examples include monitors (binary pixel data becomes images), speakers (digital audio becomes sound waves), and printers (digital documents become physical prints).

  8. The Orchestrator (Operating System - OS): This is a critical piece of software (like Windows, macOS, Linux) that manages all the hardware resources. It handles tasks like:

    • Loading programs into RAM.
    • Scheduling which tasks the CPU works on.
    • Managing files and folders on storage.
    • Interacting with input/output devices.
    • Providing the user interface you see and interact with.

  9. Software (Applications): These are sets of detailed instructions (written by programmers) that tell the computer how to perform specific tasks, like browsing the web, editing photos, or playing games. The OS loads these applications, and the CPU then executes their instructions, using RAM for temporary data and storage for permanent files, and communicating with I/O devices as needed.

In essence, when you click an icon, the OS tells the CPU to load that program’s instructions from storage into RAM. The CPU then continuously fetches these instructions, processes the data, uses RAM as its scratchpad, and sends results to your screen or other output devices, all through the coordinated dance of billions of tiny electrical switches.

Set the temperature

Every prompt you send to the model includes parameters that control how the model generates responses. Use a types.GenerateContentConfig to set these, or omit it to use the defaults.

Temperature controls the degree of randomness in token selection. Use higher values for more creative responses, and lower values for more deterministic responses.

Note

Although you can set the candidateCount in the generation_config, 2.0 and later models will only return a single candidate at the this time.

const temperature_response = await ai.models.generateContent({
  model: MODEL_ID,
  contents: "Give me a numbered list of cat facts.",
  config: {
    maxOutputTokens: 2000,
    temperature: 1.9,
    stopSequences: ["\n6."], // Stop after the 5th fact
  },
});
tslab.display.markdown(temperature_response.text ?? "");

Here is a numbered list of cat facts:

  1. Purring Mystery: While widely believed to indicate contentment, cats also purr when they are stressed, ill, or even giving birth. It’s thought to be a form of self-soothing or communication, with the vibrations potentially having healing properties.
  2. Unique Nose Prints: Just like human fingerprints, every cat has a unique nose pad pattern.
  3. Sleeping Superstars: Domestic cats spend about 70% of their lives sleeping. That’s a lot of napping!
  4. Masters of the Jump: Cats can jump up to six times their height.
  5. Sensitive Whiskers: A cat’s whiskers (vibrissae) are highly sensitive sensory organs embedded deeply with nerves and blood vessels. They are crucial for navigating, detecting changes in airflow, and understanding their environment. A cat should never have its whiskers cut.

Learn more

There’s lots more to learn!