Gemini API: Enum Quickstart

The Gemini API allows you to supply a schema to define function arguments (for function calling), or to constrain its output in JSON or using an Enum. This tutorial gives some examples using enums.

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
    └── Get_started_TTS.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).

For more information about all Gemini models, check the documentation for extended information on each of them.

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

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

Enums

In the simplest case is you need the model to choose one option from a list of choices, use an enum class to define the schema. Ask it to identify this instrument:

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

const IMG_URL = "https://goo.gle/instrument-img";

const downloadFile = async (url: string, filePath: string) => {
  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 filePath = path.join("../assets", "organ.jpg");
await downloadFile(IMG_URL, filePath);
tslab.display.jpeg(fs.readFileSync(filePath));

The response should be one of the following options:

import { Schema, Type } from "@google/genai";

enum Instrument {
  PERCUSSION = "Percussion",
  STRING = "String",
  WOODWIND = "Woodwind",
  BRASS = "Brass",
  KEYBOARD = "Keyboard",
}

const InstrumentSchema: Schema = {
  type: Type.STRING,
  description: "The category of musical instrument",
  enum: Object.values(Instrument),
};

Pass the enum class as the responseSchema, and for this simplest case you can use the responseMimeType = "text/x.enum" option to get one of those enum members as the response.

const instrument_file = await ai.files.upload({
  file: filePath,
  config: {
    displayName: "instrument.jpg",
    mimeType: "image/jpeg",
  },
});

const instrument_response = await ai.models.generateContent({
  model: MODEL_ID,
  contents: [
    google.createPartFromUri(instrument_file.uri ?? "", instrument_file.mimeType ?? ""),
    "what is the category of this instrument?",
  ],
  config: {
    responseMimeType: "text/x.enum",
    responseSchema: InstrumentSchema,
  },
});
console.log("Instrument category:", instrument_response.text);
Instrument category: Keyboard

You can also use enums with responseMimeType = "application/json". In this simple case the response will be identical but in quotes.

const instrument_json_response = await ai.models.generateContent({
  model: MODEL_ID,
  contents: [
    google.createPartFromUri(instrument_file.uri ?? "", instrument_file.mimeType ?? ""),
    "what is the category of this instrument?",
  ],
  config: {
    responseMimeType: "application/json",
    responseSchema: InstrumentSchema,
  },
});
console.log("Instrument category (JSON):", instrument_json_response.text);
Instrument category (JSON): "Keyboard"

Outside of simple multiple choice problems, an enum can be used anywhere in the schema for JSON or function calling. For example, ask it for a list of recipe titles, and use a Grade enum to give each one a popularity-grade:

import { Schema, Type } from "@google/genai";

enum Grade {
  A_PLUS = "A+",
  A = "A",
  B = "B",
  C = "C",
  D = "D",
  F = "F",
}

const RecipeSchema: Schema = {
  type: Type.OBJECT,
  description: "A recipe for a dish",
  properties: {
    recipeName: {
      type: Type.STRING,
      description: "The name of the recipe",
    },
    grade: {
      type: Type.STRING,
      description: "The grade of the recipe",
      enum: Object.values(Grade),
    },
  },
  required: ["recipeName", "grade"],
};

const RecipeListSchema: Schema = {
  type: Type.ARRAY,
  description: "A list of recipes with their grades",
  items: RecipeSchema,
};

const recipe_response = await ai.models.generateContent({
  model: MODEL_ID,
  contents: ["List about 10 cookie recipes, grade them based on popularity"],
  config: {
    responseMimeType: "application/json",
    responseSchema: RecipeListSchema,
  },
});
console.log("Recipe response:");
console.log(JSON.stringify(JSON.parse(recipe_response.text ?? ""), null, 2));
Recipe response:
[
  {
    "grade": "A+",
    "recipeName": "Classic Chocolate Chip Cookies"
  },
  {
    "grade": "A",
    "recipeName": "Peanut Butter Cookies"
  },
  {
    "grade": "A",
    "recipeName": "Oatmeal Raisin Cookies"
  },
  {
    "grade": "B",
    "recipeName": "Sugar Cookies (Cut-Out)"
  },
  {
    "grade": "B",
    "recipeName": "Snickerdoodle Cookies"
  },
  {
    "grade": "B",
    "recipeName": "Gingerbread Cookies"
  },
  {
    "grade": "C",
    "recipeName": "Shortbread Cookies"
  },
  {
    "grade": "C",
    "recipeName": "Macadamia Nut White Chocolate Chip Cookies"
  },
  {
    "grade": "D",
    "recipeName": "No-Bake Cookies"
  },
  {
    "grade": "D",
    "recipeName": "Lemon Crinkle Cookies"
  }
]

Next Steps

Useful API references:

Check the structured ouput documentation or the GenerationConfig API reference for more details.

Continue your discovery of the Gemini API

An Enum is not the only way to constrain the output of the model, you can also use an JSON schema. Function calling and Code execution are other ways to enhance your model by either let him use your own functions or by letting it write and run them.