API versions explained

This document provides a high-level overview of the differences between the v1 and v1beta versions of the Gemini API.

  • v1: Stable version of the API. Features in the stable version are fully-supported over the lifetime of the major version. If there are any breaking changes, then the next major version of the API will be created and the existing version will be deprecated after a reasonable period of time. Non-breaking changes may be introduced to the API without changing the major version.
  • v1beta: This version includes early-access features that may be under development and is subject to rapid and breaking changes. There is also no guarantee that the features in the Beta version will move to the stable version. Due to this instability, you should consider not launching production applications with this version.
Feature v1 v1beta
Generate Content - Text-only input
Generate Content - Text-and-image input
Generate Content - Text output
Generate Content - Multi-turn conversations (chat)
Generate Content - Function calls
Generate Content - Streaming
Embed Content - Text-only input
Generate Answer
Semantic retriever
  • - Supported
  • - Will never be supported

Configure API version in an SDK

The Gemini API SDK's default to v1beta, but you can opt to use v1 instead by setting the api version as shown in the following code sample:

Python

The Python SDK, google.generativeai, uses v1beta and does not provide a method for switching the API version.

The low-level Python client library, google.ai.generativelanguage exposes other versions as separate modules: google.ai.generativelanguage_v1 and google.ai.generativelanguage_v1beta. The default is v1beta.

import google.ai.generativelanguage_v1 as glm

client = glm.GenerativeServiceClient(
    client_options=dict(api_key=YOUR_API_KEY))

response = client.generate_content({
  "model": "models/gemini-1.5-flash",
  "contents": [ {"parts": [ {"text": "Explain how AI works"}]}]
})

print(type(response).to_dict(response))

Node.js

const { GoogleGenerativeAI } = require("@google/generative-ai");

const genAI = new GoogleGenerativeAI("YOUR_API_KEY");
const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' }, { apiVersion: 'v1' });

const prompt = "Explain how AI works";

const result = await model.generateContent(prompt);
console.log(result.response.text());

REST

curl "https://generativelanguage.googleapis.com/v1/models/gemini-1.5-flash:generateContent?key=YOUR_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
  "contents": [{
    "parts":[{"text": "Write a story about a magic backpack."}]
    }]
   }'