Get Started
Copyright 2025 Google LLC.
Gemini API: Getting started with Gemini models
Gemini 3 Pro/Flash: If you are only interested in the new Gemini 3 models new capabilities (thinking levels, media resolution and thoughts signatures, jump directly to the dedicated section at the end of this notebook.
The Google Gen AI SDK provides a unified interface to Gemini models through both the Gemini Developer API and the Gemini API on Vertex AI. With a few exceptions, code that runs on one platform will run on both. This notebook uses the Developer API.
This notebook will walk you through:
- Installing and setting-up the Google GenAI SDK
- Text and multimodal prompting
- Setting system instructions
- Control the thinking process
- Counting tokens
- Configuring safety filters
- Initiating a multi-turn chat
- Generating a content stream and sending asynchronous requests
- Controlling generated output
- Using function calling
- Grounding your requests using file uploads, Google Search, Google Maps, Youtube or by add URLs to you prompt
- Using context caching
- Generating text embeddings
More details about the SDK on the documentation.
Feature-specific models have their own dedicated guides:
- Podcast and speech generation using Gemini TTS
, - Live interaction with Gemini Live ,
- Image generation using Imagen ,
- Video generation using Veo ,
- Music generation using Lyria RealTime .
Install SDK
Install the SDK from PyPI. It's recommended to always use the latest version.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 46.8/46.8 kB 1.6 MB/s eta 0:00:00 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 260.5/260.5 kB 8.7 MB/s eta 0:00:00
Setup your API key
To run the following cell, your API key must be stored it in a Colab Secret named GEMINI_API_KEY. If you don't already have an API key or you aren't sure how to create a Colab Secret, see Authentication for an example.
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.
Choose a model
Select the model you want to use in this guide. You can either select one from the list or enter a model name manually. Keep in mind that some models, such as the 2.5 ones are thinking models and thus take slightly more time to respond. For more details, you can see thinking notebook to learn how to control the thinking.
Feel free to select Gemini 3 Pro if you want to try our newest model, but keep in mind that it has no free tier.
For a full overview of all Gemini models, check the documentation.
This prompt was worth 10 tokens.
Configure model parameters
You can include parameter values in each call that you send to a model to control how the model generates a response.
Learn more about experimenting with parameter values in the documentation.
Control the thinking process
All models since the 2.5 generation are thinking models, which means that they are first analysing your request, strategizing about how to answer and only afterwards starting to answer you. This is very useful for complex requests but at the cost of some latency.
Check the dedicated guide for more details.
Check the thought process
By adding the include_thoughts=True option in the config, you can check the though proces of the model.
We used 575 tokens for the thinking phase and 20 for the output.
Disable thinking
On flash and flash-lite models, you can disable the thinking by setting its thinking_budget to 0.
Inversely, you can also use thinking_budget to set it even higher (up to 24576 tokens).
For Gemini 3, please check the dedicated section at the end of this guide.
Send multimodal prompts
Use Gemini model, a multimodal model that supports multimodal prompts. You can include text, PDF documents , images, audio and videos in your prompt requests and get text or code responses. Check the File API section below for more examples.
In this first example, you'll download an image from a specified URL, save it as a byte stream and then write those bytes to a local file named jetpack.png.
1567837
Now send the image, and ask Gemini to generate a short blog post based on it.
Generate Images
Gemini can output images directly as part of a conversation using the Image generation models (aka "Nano-banana).
image/png
Configure safety filters
The Gemini API provides safety filters that you can adjust across multiple filter categories to restrict or allow certain types of content. You can use these filters to adjust what is appropriate for your use case. See the Configure safety filters documentation for details.
In this example, you'll use a safety filter to only block highly dangerous content, when requesting the generation of potentially disrespectful phrases.
Use chat.send_message to pass a message back and receive a response.
Here's another example using your new helpful coding assistant:
Save and resume a chat
Most objects in the Python SDK are implemented as Pydantic models. As Pydantic has a number of features for serializing and deserializing objects, you can use them for persistence.
This example shows how to save and restore a Chat session using JSON.
At this point you can save the JSON bytestring to disk or wherever you persist data. When you load it again, you can instantiate a new chat session using the stored history.
Generate JSON
The controlled generation (aka. "Structured output") capability in Gemini API allows you to constraint the model output to a structured format. You can provide the schemas as Pydantic Models or a JSON string.
You can find more examples of controlled generation in the dedicated notebook .
{
"recipe_name": "Classic Chocolate Chip Cookies",
"recipe_description": "These soft and chewy chocolate chip cookies are a timeless favorite, featuring golden brown edges, a buttery vanilla flavor, and plenty of semi-sweet chocolate morsels.",
"recipe_ingredients": [
"2 1/4 cups all-purpose flour",
"1 teaspoon baking soda",
"1/2 teaspoon salt",
"1 cup (2 sticks) unsalted butter, softened",
"3/4 cup granulated sugar",
"3/4 cup packed brown sugar",
"1 teaspoon vanilla extract",
"2 large eggs",
"2 cups semi-sweet chocolate chips"
]
}
Image is another way to generate images. See the documentation for recommendations on where to use each one.
Generate content stream
By default, the model returns a response after completing the entire generation process. You can also use the generate_content_stream method to stream the response as it's being generated, and the model will return chunks of the response as soon as they're generated.
Note that if you're using a thinking model, it'll only start streaming after finishing its thinking process.
Unit 734, who referred to himself as "Sev" in the quiet hum of his internal processor, was designed for a world that no longer existed. He was a heavy-loader unit, built with hydraulic arms thick as tree trunks and treads capable of crushing granite. His purpose was to lift girders for skyscrapers, but the humans had left the planet two centuries ago, fleeing a collapsing ecosystem. They had turned off the lights but forgotten to turn off the robots. So, Sev spent his days in the Great Rust Yard (formerly New York City), stacking cars into neat, towering ziggurats. *Lift. Rotate. Place. Verify.* It was a loop of infinite monotony. His only companions were the wind, which howled through the skeletons of buildings, and the rust, which ate everything eventually. Sev was lonely, though his diagnostic screen simply labeled the feeling as: *Error 404: Purpose Not Found.* One Tuesday, during a particularly violent acid rainstorm, Sev suffered a malfunction. His thoracic cooling vent—a heavy metal shutter on his chest—jammed open. The rain hissed against his heated internal wiring. To prevent a system crash, Sev engaged an emergency lockdown. He froze in place, halfway through lifting a rusted sedan, his treads locking into the mud. *System cooling. Estimated reboot time: 72 hours.* Sev powered down his optics to save energy. He became a statue of yellow paint and steel in the downpour. When his systems finally rebooted three days later, the rain had stopped. The sun was struggling through the gray cloud layer. Sev ran a diagnostic check. Hydraulics: Green. Battery: Yellow. He prepared to close his chest vent and resume work. *Obstructed,* his HUD flashed. *Sensor detected foreign object in Cavity B.* Sev angled his internal camera downward. There, nestled amidst the warm tangle of his primary power cables, was a mess of dry twigs, plastic wrappers, and copper wire. And sitting in the middle of this debris was a small, brown creature with terrified black eyes. It was a bird. A house sparrow, one of the few organic species stubborn enough to survive the gray world. The bird cheeped aggressively at the camera lens, fluffing its feathers. *Identify,* Sev’s processor ran. *Species: Passer domesticus. Status: Fragile. Threat Level: Zero.* Sev engaged the command to close the vent. The heavy metal shutter began to slide. The sparrow didn't fly away; instead, it hunkered down, spreading its wings over three speckled, marble-sized eggs that Sev hadn't noticed before. *Stop,* Sev commanded his own servos. The shutter froze. If he closed the vent, he would crush the nest. If he resumed his work—stacking cars—the vibration and tilting angles would toss the eggs into the machinery, where they would be cooked or ground to dust. Sev sat there, his engine idling. His directive was clear: *Clear the sector. Stack the refuse.* But a sub-routine, buried deep in his heuristic learning core, whispered a different logic. *Preservation of complexity is a priority.* And this small, breathing thing was infinitely more complex than a rusted sedan. For the first time in two hundred years, Sev disobeyed his schedule. He remained frozen. The first week was the hardest. His joints stiffened. His battery levels dipped as he couldn't return to the charging dock. He had to angle his solar panels carefully to catch the weak sunlight without moving his torso. The sparrow, whom Sev named "Pippin" (a word he found in an archived database of literature), grew bold. She seemed to understand that the giant yellow mountain was not a threat, but a fortress. She would hop out of his chest cavity, land on his optical sensor to clean her beak, and then dive back into the warmth of his wiring. Sev found himself watching her for hours. He observed the way her feathers repelled the drizzle, the frantic speed of her heartbeat, the fierce determination with which she guarded the nest. He wasn't sorting trash anymore. He was a guardian. The loneliness—the *Error 404*—vanished, replaced by a high-stakes anxiety. *Temperature dropping,* his sensors warned one night. *Frost imminent.* Sev rerouted power from his mobility treads to his internal heating core. He deliberately overheated his own wires, raising the temperature in Cavity B. It drained his reserves dangerously low, but Pippin settled down, looking cozy in the red glow of his power indicators. Then, the eggs hatched. Three tiny, blind, gaping mouths appeared. The noise was insignificant—a faint peeping—but to Sev, whose auditory sensors were tuned to the crash of steel, it was a symphony. The friendship changed then. It became a partnership. Pippin worked herself to exhaustion hunting for grubs in the mud. Sev couldn't hunt, but he could help. He began to use his fine-motor manipulation lasers to gently overturn nearby rocks and debris, exposing insects for her. Pippin would swoop down, snatch the prize, and chirp a specific note at Sev before returning to the chest cavity. A thank you. But the Great Rust Yard was not safe. One afternoon, a Scavenger Drone—a mindless, spider-like machine reprogrammed by centuries of glitches to disassemble anything with a battery—skittered over the pile of cars. It had detected Sev’s low-power signature. It saw an easy meal. Sev saw the drone climbing his treads. He couldn't move. If he spun his treads or swung his arms, the centrifugal force would fling the hatchlings out of the nest. The drone raised a hydraulic saw, screeching as it prepared to cut into Sev’s leg. *Warning: Hull integrity compromised.* Sev didn't flinch. He couldn't fight back physically. Instead, he accessed his external communication array. He aimed his high-frequency transmitter directly at the drone and screamed—not with sound, but with data. He broadcasted a packet of raw, corrupted static at point-blank range. The Scavenger Drone seized up. Its processor flooded with garbage data. It twitched, sparked, and tumbled backward off Sev’s treads, landing upside down in the mud. Sev’s battery was at 4%. Critical. He dimmed his optics. He stopped the heater. He diverted every last scrap of energy to the life support of his memory core, praying the ambient heat of the day would be enough for the birds. He drifted into stasis. *** Sev woke up to a tapping sound. His solar panels had slowly, over weeks, trickled enough charge back into his system to initiate a boot sequence. *System Online. Battery: 12%.* He focused his lens. The chest cavity was empty. The nest was a mess of broken shells and loose down. Panic flooded his circuits. Had he failed? Had the cold taken them? He scanned the area. There, perched on the rusted roll-bar of the sedan he was still holding, sat four birds. One ragged mother, and three sleek, young sparrows. They were preening in the sun. Sev let out a low, mechanical whir, a sound of exhaust venting. The birds looked up. Pippin fluttered over and landed on Sev’s head. She pecked gently at his metal casing, then took off, soaring toward the ruins of a skyscraper. The three young ones followed, a chaotic squadron of life against the gray sky. They were leaving. It was nature. Sev watched them until they were just pixels in the distance. The silence of the Rust Yard returned, heavy and suffocating. He was just a machine again. A trash stacker. He prepared to close the chest vent. *Wait.* He paused. He ran a scan of his internal schematic. The nest was still there. It was messy, and it was flammable, and it violated fourteen safety protocols. Sev left the vent open. He unlocked his treads and slowly, carefully, turned toward the south, away from the trash piles and toward the overgrown ruins of the parklands. He wasn't going to stack cars anymore. He had learned that he was excellent at being a house. And in a world full of rain and rust, there were surely other things looking for a warm place to stay. Sev rolled forward, his chest open to the world, no longer lonely, but ready to be found.
More details in the dedicated guide .
Upload files
Now that you've seen how to send multimodal prompts, try uploading files to the API of different multimedia types. For small images, such as the previous multimodal example, you can point the Gemini model directly to a local file when providing a prompt. When you've larger files, many files, or files you don't want to send over and over again, you can use the File Upload API, and then pass the file by reference.
More examples and details in the File API guide , or the guides dedicated to Audio, Video or Image/Spatial understanding.
Upload a large text file
Let's start by uploading a text file. In this case, you'll use a 400 page transcript from Apollo 11.
847790
Upload an image file
You can also upload images so that it's easier to use them multiple time.
The previous example was also using media_resolution to tell the model if it if should
You'll find a lot of examples of the image analysis capabilities of the Gemini models in the Spatial understanding notebook.
Upload a PDF file
This PDF page is an article titled Smoothly editing material properties of objects with text-to-image models and synthetic data available on the Google Research Blog.
Firstly you'll download a the PDF file from an URL and save it locally as "article.pdf
6695391
Secondly, you'll upload the saved PDF file and generate a bulleted list summary of its contents.
Upload an audio file
In this case, you'll use a sound recording of President John F. Kennedy’s 1961 State of the Union address.
41762063
Upload a video file
In this case, you'll use a short clip of Big Buck Bunny.
--2025-11-15 17:12:20-- https://storage.googleapis.com/generativeai-downloads/videos/Big_Buck_Bunny.mp4 Resolving storage.googleapis.com (storage.googleapis.com)... 142.251.107.207, 74.125.196.207, 173.194.215.207, ... Connecting to storage.googleapis.com (storage.googleapis.com)|142.251.107.207|:443... connected. HTTP request sent, awaiting response... 200 OK Length: 64657027 (62M) [video/mp4] Saving to: ‘BigBuckBunny_320x180.mp4’ BigBuckBunny_320x18 100%[===================>] 61.66M 153MB/s in 0.4s 2025-11-15 17:12:20 (153 MB/s) - ‘BigBuckBunny_320x180.mp4’ saved [64657027/64657027]
Let's start by uploading the video file.
Completed upload: https://generativelanguage.googleapis.com/v1beta/files/tv2x3tx8n36p
Note: The state of the video is important. The video must finish processing, so do check the state. Once the state of the video is
ACTIVE, you're able to pass it intogenerate_content.
Waiting for video to be processed. Video processing complete: https://generativelanguage.googleapis.com/v1beta/files/tv2x3tx8n36p
FileState.ACTIVE
Grounding
The Gemini API give you multiple ways to ground your requests, including Google search, maps, youtube, and url context.
For more details information and examples, check the Grounding notebook.
Search Query: ['who is the current magic the gathering world champion', 'Magic: The Gathering World Championship 2024 winner'] Search Pages: reddit.com, wikipedia.org, starcitygames.com, tcgplayer.com
Note that you should always display the grounding rendered_content when using search grounding.
Check out the Search grounding dedicated guide for more details and examples.
Use Google Maps grounding
Google Maps grounding allows you to easily incorporate location-aware functionality into your applications. When a prompt has context related to Maps data, the Gemini model uses Google Maps to provide factually accurate and fresh answers that are relevant to the specified location or general area.
To enable grounding with Google Maps, add the google_maps tool in the config argument of generate_content, and optionally provide a structured location in the tool_config.
Note that Gemini 3 models currently don't support Maps grounding.
All grounded outputs require sources to be displayed after the response text. This code snippet will display the sources.
More details, inlcuding how to render the contextual Google Maps widget, check the Google maps section of the grounding notebook.
For YouTube links, you don't need to explicitly upload the video file content, but you do need to explicitly declare the video URL you want the model to process as part of the contents of the request. For more information see the documentation including the features and limits.
Note: You're only able to submit up to one YouTube link per
generate_contentrequest.
Note: If your text input includes YouTube links, the system won't process them, which may result in incorrect responses. To ensure proper handling, explicitly provide the URL using the
file_uriparameter inFileData.
The following example shows how you can use the model to summarize the video. In this case use a summary video of Google I/O 2025.
The URL Context tool empowers Gemini models to directly access, process, and understand content from user-provided web page URLs. This is key for enabling dynamic agentic workflows, allowing models to independently research, analyze articles, and synthesize information from the web as part of their reasoning process.
In this example you will use two links as reference and ask Gemini to find differences between the cook receipes present in each of the links:
Function calling
Function calling lets you provide a set of tools that it can use to respond to the user's prompt. You create a description of a function in your code, then pass that description to a language model in a request. The response from the model includes:
- The name of a function that matches the description.
- The arguments to call it with.
More details and examples in the function calling guide .
FunctionCall(
, args={
, 'destination': 'Paris'
, },
, name='get_destination'
,) You can also use MCP servers.
Code execution
Code execution lets the model generate and execute Python code to answer complex questions.
You can find more examples in the Code execution guide .
Use context caching
Context caching lets you to store frequently used input tokens in a dedicated cache and reference them for subsequent requests, eliminating the need to repeatedly pass the same set of tokens to a model. You can find more caching examples in the dedicated guide .
Note that for models older than 2.5, you needed to use fixed version models (often ending with -001).
Create a cache
7228817
CachedContent( , create_time=datetime.datetime(2025, 11, 15, 17, 13, 51, 402109, tzinfo=TzInfo(UTC)), , display_name='research papers', , expire_time=datetime.datetime(2025, 11, 15, 18, 13, 49, 999682, tzinfo=TzInfo(UTC)), , model='models/gemini-3-pro-preview', , name='cachedContents/51lc0rcel857wv16pekr76tkqk9sf69dtygyo8y5', , update_time=datetime.datetime(2025, 11, 15, 17, 13, 51, 402109, tzinfo=TzInfo(UTC)), , usage_metadata=CachedContentUsageMetadata( , total_token_count=93601 , ) ,)
Listing available cache objects
name='cachedContents/51lc0rcel857wv16pekr76tkqk9sf69dtygyo8y5' display_name='research papers' model='models/gemini-3-pro-preview' create_time=datetime.datetime(2025, 11, 15, 17, 13, 51, 402109, tzinfo=TzInfo(UTC)) update_time=datetime.datetime(2025, 11, 15, 17, 13, 51, 402109, tzinfo=TzInfo(UTC)) expire_time=datetime.datetime(2025, 11, 15, 18, 13, 49, 999682, tzinfo=TzInfo(UTC)) usage_metadata=CachedContentUsageMetadata( total_token_count=93601 )
Use a cache
Delete a cache
Get text embeddings
You can get text embeddings for a snippet of text by using embed_content method and using the gemini-embedding-001 model.
The Gemini Embeddings model produces an output with 3072 dimensions by default. However, you've the option to choose an output dimensionality between 1 and 3072. See the embeddings documentation or the dedicated notebook
for more details.
[ContentEmbedding(
values=[
-0.0015945111,
0.0067519513,
0.017575769,
-0.010327714,
-0.009956204,
<... 3067 more items ...>,
]
), ContentEmbedding(
values=[
-0.007576517,
-0.0059903963,
-0.0032700377,
-0.017510215,
-0.023507025,
<... 3067 more items ...>,
]
), ContentEmbedding(
values=[
0.011074519,
-0.02361123,
0.0022912885,
-0.009060789,
-0.0057736747,
<... 3067 more items ...>,
]
)]
You'll get a set of three embeddings, one for each piece of text you passed in:
3
You can also see the length of each embedding is 3072, The default size.
3072 ([-0.0015945111, 0.0067519513, 0.017575769, -0.010327714], '...')
Gemini 3
Gemini 3 Pro and Gemini 3 Flash are our new flagship models that comes with a few new features.
The main one is the thinking levels that simplifies how to control the amount of thinking your model does. The Media resolution lets you control the quality of the images and videos that will be sent to the model. Finallly, the "Thought Signatures" are helping it maintain reasoning context across API calls.
Also note that a temperature of 1 is recommended for this model generation.
Thinking levels
Instead of using a thinking_budget like the 2.5 generation (cf. thinking section earlier), the third generation of Gemini models uses "Thinking levels" to make it simpler to manage.
You can set that thinking level to "minimal" (more or less equivalent to "off"), "low", "medium" or "high" (default). This will indicate to the model if it allowed to do a lot of thinking. Since the thinking process stays dynamic, high doesn't mean it will always use a lot of token in its thinking phase, just that it's allowed to. Note that Gemini 3 Pro only supports "low" and "high".
thinking_budget is still supported by Gemini 3 models.
Check the thinking guide or the Gemini 3 documentation for more details.
We used 834 tokens for the thinking phase and 62 for the output.
Media resolution per file
With Gemini 3 models, you can specify a media resolution for image and PDF inputs, which affects how images are tokenized and how many tokens are used for each image. This can be controlled per file.
Here are what the different values corresponds to for images and PDFs:
MEDIA_RESOLUTION_HIGH: 1120 tokensMEDIA_RESOLUTION_MEDIUM: 560 tokensMEDIA_RESOLUTION_LOW: 280 tokensMEDIA_RESOLUTION_UNSPECIFIED(default): Same asMEDIA_RESOLUTION_HIGHfor images, andMEDIA_RESOLUTION_MEDIUMfor PDFs.
For videos, MEDIA_RESOLUTION_LOW and MEDIA_RESOLUTION_MEDIUM corresponds to 70 tokens per frame, while MEDIA_RESOLUTION_HIGH will send 280 tokens per frame.
Note that these are maximums, and the actual token usage will usually be slightly lower (by approx 10%).
The image is worth 1081 tokens.
Thoughts signatures
This new addidtion won't affect you if you are using the SDK since it's entirerly managed by the SDKs. But if you are curious, here's what happening behind the scenes.
If you check your response's part, you'll notice a new addition: a thought_signature
b'\x12\x94\x19\n\x91\x19\x01\xd1\xed\x8aoD\xe9\xdc\xcb>\xd1\xb4\xb8\x98\xed]\xa1;\xda\x0ck\xa7\x9e\n\x15$\\*\xf6\x87\xf7\xa6U\xd0?\x04|\xd6\xf3\x84\x97\x9f\xf2S\xef\xbeT?h\xf8\xb4\xec\xd3~]\xe0\xd9\x96\x14\x98\xf5\xc2*\xd7\x87nH\x19\xeeS\xc6\x9d\x0f\x9c\x0c\xb5SJ\xf3Y-#\xda\xd6F\x12\xd9\x9b\xe1\xae8x\x97\x83u\xba\x05\xc5\xdc\tk\xab\x89b2\x9a1*\x11\xf0}_\xe6\xfa\xc3\xe8\x13^K\xe1a\xde\xb1l\x12S\x9f\xc7?\x16\xa1\xa7\xb7\x1d\xbfr|i\x80\xf6\xc1\xd5\xfc\x06A\x8f{\xe1\xfb\x8f\xa5\xba=\x01\xac_<z<\xe5O\xb0\xff\xd9iF<G\x8b\x14\xd3r\xe5\xbc\x08\x1dp\x01\xc6h\xe3\xd3\xdbnAf&\x93\x8dU\xd4\xa9\xf7\xbc-\x13\x1eP0\x90\xe0]Q\x9a\x96\xfak(\x88\xffOM\xaaDf\xb0\xc7&9\xe6Gt\x8d\xca\x8b\xa1\x0c\xb5\x85\x88\xb8&\xd2Pu\xe5\x97\xc9y>\xed\x059/\xef\xe6\x03d_qbgIa"F-ErM\x05iw\x13\xdd\xa1\x1c>\xa3O\xff\x96\xb2,\xc05\xf2\xf3\xb0%4P"D\x0b\xc6\x18/R\x15KL #\x88\xba\xa6D\xa8v\x92\x83\xb9\xcfs\x92\xa9p=Ex\xd6B\xc7\xd9s\x16\xc9\xeauJ\xa8\xb3\x99\xe3\x97K\xdf\xaaX\x0eU\x8f\x19\xaf\xb5t\xb8\xfb0\xe8\xc5\x95\x0e\x15/\xb82\x8b\xb7 \x1b8\xa6z\xd8\xbb\xd3\x99\x8d\xedQ\xe8\xb1\x85b&D\xe3u\xb0\x8c\xfd\xfd)\xb0zBd\xf7\xe1\xa0\xec\xe4;^\x84\'V\xd2K\xd2\x8e\xb4L\xab\xe8\x0e\xf5\xcb\x92`\x0cb\xef\xcbV\xa7N\\\x88\xa6o.g16RM\xd3g\x86\xcd\x8d\x7f\xfe\x0c\xc8A\x17W$\x9e\xfa\xf5\xe9\xafmh\xbd5\xa8\xf0,\xa4\x9f\x89\xf7`\xc53\x1cW>\x03S\xfd\xb5JG\xd4\x9d\x0c\x03\xae\x17A&\xcc\x8a%\xae\x01\xbe\xf3X\xea\xc8\x1e]h\xbbv\xc6\xf5\x80Fcf"6\xa9$\xac\xa5@\x9e\xbd\xf5\xb2\x9d\x86\r\xb9[\xc9\x03r\x92p0\x18k\r\xe5\xfe\xf6\xda\xf2\xfe\x92\xb2Cm\tJ~\xa8\x04\rB.\x88\xb7\xa4\x9d\x02T\xc5\x07N\x03\xd0\xd4M\xfd\x04\x82\xb0\x84H4&i\x1a\xea\xb2\xe3\xdf\xd9P\n\xf5h\xa2_\xf0\xbd\x91V\xda\xdb\xa0O\x11N\x13\xe3\xc8\x8fG\x7f\x96\xdeZN\xe4\xb7TLt\xbcW\xd2CZ\xe4g\x9d\x83>\xbd\x80\xa6\x8fX\xf74u\x93\xbc`\xc2\n\xf7\x06\xe35\x16?\x7f\xbeb\x84\xa9{m\xb7\\\xe5A\xa5s\xfb\x0f#\xfcJ\x10\x85Q|\xffV\x8dl\xa5\x17\x03\xddu\xbd\xad|\x01\x9d\x0e\x0f}\x18|Y%\xf8\xd8\x93\xb6\x8d\xf8M\x1c\xfb\xfe1"\xa9!^\xc7nR\xc43/\x921\xa4e\x06\xb3\x15I\xea%\xa30\xfd\xcb\xb9tU\xf12.\xd8\xf1\x04\x9dV\xb7Q\xbbe\x07P\xab\xa1\xfa&b\xac\xc7\x8b\t\x9c\xc4\x17\xebA\xd7\rDF\xaeiIe\xf2\xfc\x08\xeb\xb4\x8e\xf0\x85\xa6\xcd0\xbdD\x06\xe3\xfd\xe4\xea6\xa9i\xc7\xae\xbf\x9d\xce\'R\xd5oU\xb7JMT\x0e\xf2\xbc\xdd.\x9eeD\xa100\xb9}\x9a\x9e\x16o3\xd8\x8fa2o[)\xd1\xed\rt\xd68\xc5}\xf7\xf7!\xfc72\x90I\xf7g}\xe7z\xf5\x98m\x8b\x18&]\xe2\x17M,\xb9\xf3\x7f?\x10\xc8R\xe4\x88\x8f\x80]W\xc2\xbd\x97^\x8clf\xcb\xa4r?v\x03\xcd\xa4;\xe1#\x99\x15n\x1d\xe2\x17"*\x0c\x92\xafq\xb5\xaaI\xdd\xe5\x01}y\xf1\xd3Z\xb5\x0c\xfcLG[\x1c\xae\x9dv\x1a\xac^T\xee\xbc?j\xbc\x06\xc7\xd2\x86\xd8\x95\xe7K\r\x96\xb1\xe95\xf6\xe0t#1\x8f\x18\xf7H\x988\x1e}8p \x89`\xc9\x12\xde\x83p\xf1\x17\xeb\xf05\xd5m\xd7\xad\xfd\x04\x98\xbf\x8a\xb6\x8d\xef\x01\x80M\x06\x16\xa0\x13\xb6\x01\xb7\'\x12\x06\x83;-\x07I#MU\x9a\x1e\x82\xee2\x02\xda\xa6\x19\\\xcc\x80\x92\xf2a\x98v\xbdY\xea\xa5\xe1\x84KrA\xa3\x81~^\xbb\xa9\x07;\x7f\xf4l\x07O\x06K\xa1i\xadP\xa02I\xaa\xa9%\x8f?&\xfa\x12\xc6\x1d0\x8a\x1d\xcb\'J\x0f\xc9\x17{\x88g\xc3\x97g\xe6_R\x1a\xf5\x1d\x1d\xb5\x8d\x00\xc2N\x8e]2\xa6\xc6\xe1\x84\xcd{\x9d\xb1(!\xca]}\x9a\x9fh\xc7\x14N\xb6\x10\\,\xd6\x9e\xcc\x99\xc7_\x07\xdf\xf9\x12X\xd4\xa0\x87&\'\xe5j\xaa\xd4\xf2\xd5\x7fM\xbc)\xbc!)V\r\xabIqh\x9d\xa4\x0exp|\x12\x88\xf5\x1f\xdd\xc3\x89\xf1\xecL\xfcZs\x17\xf5\xd7\xc66\xdbq[{\xf3\xad\xbd\x17|\x9d0S\x89\x98\xac|\x13\x8e\xea\x93t\x1c\xab\xcc\xdb\x8cGqcm\xe8\xd4\x8d\x05\xf4@\x18a\x94\x89~\x0bg\x9a)R\x0eV\xcd\x1b+\x91\xaf\xd9\xd7\xe3,j\x9d\x12\xc1\xe5\xd4\x96\x9a?\xfe_0\xcfD\xcax}\xa4\x04\xf6q\xea\xd95\xc7u\x10\x9c\xe9n\xffLB{\x0e\'\xb4o\xb6\xb0$`\xc0\x80_\xd3\xbe\xc9\x9a\xa3\xaa\x92\xd3\x19\xb1\xe7\x0b\xcen\xe7\xf9:\xebc(;\x08\x80\t\x00\xf5\xd7K \xa1\x94\xc9\xa4c\x05\t-\x0c\xf9\xdc\xfb\x9a\x91\xf7\xd8*\xe7>\x89R)\xe8\xb7m\xbc\xf1w\xe1<\xa19Z43Yi\x1cS\xad\x84\xf6Q\x8b\x19V\xb0\xc4\xeb-)\xa53O\xd8r\xec\xeb\x1c]\xf6\xce\xbe:!n3W\x9f \xe1TS\xf5\xa9N\x01P\xcf\xa4\x9fhi\x94\x02\xfb\x90\xb8\xf3\xd2\xe0\xec&\xcc\xc9k\xaf\xcc\xd8\xec\xd5\x81\x80D\xb2y.*O\xdaz\xdc\t\x18:\x14\x87\xd7\xbe\x92\xdf\xeb[\xc5{\x18Z\x1a\x8d\xd7w\xaa\xf4UA\xd6\xa4\xeb;\xc0\xa9\xec\xc5P\xbc}^\x18td\x95\xd53\xc3HG\xb6\x0e\xd9\xffF\xef>J\x9bG\xb0\xfaO\xdf\xb6\x91\x96#\xd6\x87\x1bHA\x0e;\xbbJ]\xd53\x1a\xe9\r\xa66\xd0%\xcf\xf8O\x10\x1dU\x94Ucl\xce \x94m/_\x1a\xe7V\xc6P\x10w>\xd9\t\x99u\xf3\x0bN3\x1b\x1cl\xc3\xc1\x8e\x07\x7f\x8e\x98\xc9:\xc0\xb2y\x8a\xd7\xe0\x0e\xf2v\xd7`\'\x04\xd7\'\xc5\xacw\xe5\xeem]\xbf"\xf6KY\x18L\x8cE\xe7j\'o\xb1{\x1e\x17}\xd18\xb3!z\xe0\x01\x19\xe0\xb1\xa9\x88.a\x99.e\xaf6c\xaf\xd17\xf9\xf4A\xdb\xfe\x17/\xfa(\xd97\x1bO\xd1\xa3\xd5\xb0\x02JH\xb1\x80\x95z=!\xe1\xf6\x89\x8e\x89\x920\xd2s\xfaH\x87\x7fe\xff\xd6\x7f\xd2Z1\x91u\xa6Z\xff\xbf\x8d\x7f\x1d\x02\xaf\xcd\x8b\xbaB;|\xad\xa5:\t"\xef\xfbh\xc4\x93_{\x84/\xc7\x8d3A\x02\x99\xd8|#l\x13\xc7R\x17\xc0\x02\x13\x84\xc1G\xcc\x83>\x19\x8d\x19P\x83\xf5K\xa7\xc4FN\xafG\xbc5\x1cj\xf0W\xaf\x05PW\xbbJ\xcf\xb6\xd2\x15Sm\xfcp\xa7m\x08\x81\xf6J\x98UZ\xb2\xebS\x8c)\xa9\xd3Ag\x9e\x81DNb*\x10\xd4\x88\x01\xbfU\xd5\xdb\xa6\xecg\xb7\xeb\xab\xf6\xaf7\xc3Kd"~\x86JX\xc8`%\xae;\xd8%\xec\x9f\xa1=\xd0\xd1\xe7\xe2\x97c\xf4\x97_\x8f\x04\x04\xed;\xb0\xb1l\x1a\x89\xa4t\xb9#eqj \x14\x06^\xd0P@b|\xf8\x01\xc1\x08\x9f\x0e\x8e\x92L\xd1\xce\x14\xde}\x13M\xc2\x80\x87\xc2I(\xee&\x1a\xbck\x00_\'\xe5\x19\xa3\xf1d\xfc\x10\x9b\xbc\xd9\xb1\xe4\rU\x97u\x00\xccC\xec\xdd\xcb*Z\xc3\xb3Wk5\x82+\x0b\xda\xf1w%9`\xc6Wf\xe9\x0c+p\xf1\x9c\xf8\x1c\xa1\x06B\x19\x99\xfb\x1c~\x93\xad\x97&=\xe8\\h\xc0)\xab\xfd\x97\xf7\xa8\x9e\xfa:\\\xeeX\xb4To9\xff\xaa\xe1@\xd7\x93RL\xe7=\x17\xcee\xa2\xc9 F"\xe4\xf4\x10dH\x17\xd63\xe5D\xdf\x8f\x89\x0e\xd418W\x1dpg[\xec\xde\xe5\x809\xf0\xcb\xc8+w\n\xeb\xaf\xe1\xa9\x9ea\xc0\xd4(8\x84\xce\xbbQ)@\xba<\xdc\x81\xc8?k\xb69\xc5\xa3\xaa\xfc\xaf"3\x99Q\xae@<\x99E\xb1\xd0\xf4\x1df\x96\xab\x9f_\nb\xfd+\xcd\xd5\t\x02\x82\xb4\xf0\xd6\x03\xe0b\xa0;\x8e\x8a~\xdf\xb2S\x9a+h*qO\xa5\x192)\xf8S\x86\x85\x1eXe\x06\x96\xc5WFR*\x0e2\xe8\xe5\xf7\x98%\xf1J0\xaf\x01p\xb7zG\xfa\xcc\x96\'\xe8\x04\x9a.I"\xd6\xb5\x8d93\x1fq\xf8{\x94\xd0`\x92\xd2\x94\xa4\xc4\x18\x0bZ\x14\xeaC\xb8\xad\x87\xb9\x9e\xa0\xf9f\x1e,\x83\xc3\xa0\xbbW\x1bT4\xf2\'\xf2e%N\x02\x91\xc5x<\xe7e2\xdc\x1d\xe7c\xe0\xe1\xa7N\xe1\xed<\xcf>\xdf\xe4\xe2\xdac\xf8\xf2\xbb\xba\x92\xfeq0\x17\xd1}NP6\xea\xf7\x95\xbb\xe6\xed\xa0u\x98\x8e2\x9c\xf1\xe9\x1d\x0b\xe1\r\xc9\xb6BL\xe7\xd1\xcd\x0b\xd1\xc0\x83%\xb6\xd1\x97m1\xc7\x02\xcd\xc1\xec\xe9\xc4`\x14B\xd8K`\x1cuk5O\x9d\xf6,F\x9c\x88\xa8\xeeM.\xb6\xd9\x86,y\x9d\xfb\x97\xa8\xec\x9d\xc66m\xe5VS/\xe2[*\xb3\x98\xde\x9d)\x1a\x9a\xc1X\x8bWS^\xaa\xb4\x16\xe5)Vt\xd25\x89\t\xb6\x8b\xc3\xcb,vn\xc7\x8e\xeaZ5\xe8\x9e&\xa1\xda\x03\xf5X\xc8\xd3\x16\xfa7KHS\xd2DD\x13O\xca\xef+\xbb\xd2\xf0\x0f\xc2\xff\xe4|\xb3\xc3h*\x02\xf4\xe6\xb3\x81\xe75\xfa\xdf<\x19\xf7\x1d_\xa2O\xef\x14\xa7\x81\xf1\xd8\xe0I,&\xafl^&A*\x92\xe9\x17\xde/P>\x80\xae\xe4a\xc2\x16\xda\x03\x18\xca\xeaL\xc0\x81\xf7\x03m\xc1\xfdr\xa0\xc4CrN\xa9C/\x13\x9aeaC\xe1\xe6\x8e\x9b\x12k=C[N;\xbc\xdby\x1dz\xcfq\xed\xcc\xc6\xc4\xdaD\x9f\x0c)\xa4\xbf\x92,\xa0\x0bWmq\xc0\x9d\xcb\xbe\xaa\xe5\x03\xd5\xdcD0"\r\xa0\xc7\xc0b\xc89\x9dU\x82\xcd\xbf\x9c\xb5N\xacuq\x8e\x8e{\xb9\x91MEy\xb7\xf3P\x80\x93\xd5\xa6\xe8\x9a\xbb:k\xa6\xa0f\n\xd7\x9c\n\x7f\xe4\xfc\xa8\xe3za\x05\xdc\\q\xb3)\x86\xd0\x10\x81\xd8\xa6\xc9\xb6\xfc4\x05\xcc\x85\xc1\xb0\x99X\x82\x0e\t\xca\xbd\x9a\xa4\xcc\x90\x88i(\xf4H\x10\xfb\x05N\xa3!\x08t4\x1ai\\\x18&\xa93\xbb\x9f\xcb\xf4\xe9\xe2\x00\x83p\x1f\xbd\xdd\xee\xed\x8b\x0b\x18\n\x06\xeb\x15|\xfd\xd9p\x180\xe8\xd0/\x1e"\x8e\x15?\xfa\xda\x08b\xbc\xe8Y\x10\xc2\xaa\xbdW0\xd0\x0bj\xddP~\x1cQ?\x02\xab\xab\xe4&E\xb8\xed\x0c\x04\x90U\x1e\xfa\xba\x9e\xbe\xef\x1b;;\x90\xc0jX\xaco\x90>|=l\xfc\x84x\x07\xcc\xd1\x99\xc3T\xbdi\xe8\xac\xbc\x1d%\xb8\xe1\xd5_c\xde]\xfa\x00\xb2\nT\x94\xe8\xab\x12\xf0h~7\xf7PU\x9d\x14I\xeeAA\xaf\xbb+\x8a\xd99\xaf\x97X6\xc7\x85\xd8\xbaJI\x94.\xa7m>XH\xe5\x10\x05\xd9\x10\x17\xc9<\x982qAMm\x1c\x1bA\x91,\xbb\xba:D88\xee\xeef+\xa3?w\xf6\x01c\nAD0\xf1\x81\n\xac\xd1\x0c\xf3\x0c\xfb\x97\x99\xc5\x94l%\x92m\xcd\xabL\x06F\xf1\xeeE\x976Z\nR\xc8\xc5\xd4\xe3\xc7L\xd0\xd0s\xbd\xd6\x06:\x91[/xG\xf0}\t\x0f\xd8\xf3\xa99\xdd1\xef\x14q\xcf\t[*C\xd6>.\xf7\x8b\x8b\x92\xe6\xe4<\xf4\x1e*;\xbd-G\x94\xc2\'\xd0!\x04{}.\x8d\xcd\xfbp\xd0@\x98\xe6jF\x9b\x1b\x0e%\xdf\xffH\x03>%+\x1f\xf5\x7f\xc7\xac\x11$_\xd7=\xf1\xcc0N\x84\xf0n>oVI\x1b\'\x8e\xa59\xc6Q\xc7.\xed=c!O/\xb4\x97\x87\x9b\xc3_$\xfc\x1c\xdc\xdd\x85J\xcew=\x7f\xd9i\xe9\xdcu\xd2\xf6h\xfa\x88&\xdf!\x1a\x1d\xabG\x19mQ\xf8\x84\x11\x98\xbdCA\x88\x19\xc9\xb1U\xd3n\xa6\xf2\xc4$]RS,\xf5#\xa4\x1c\x07\x1d\xe0\xce\xefb\xe3#Gw\xee5\x847\xef\xe3N\xa4\xb1\x08\xc5\xebh\xdb\xfb\xf2=5\xb0\xa2\xb2\xc5\xf4\xc0\xde.\x9b1\xaf\xa7(B<Q\xf6\x14|_\xe2d\x86\xdd\x15yv\xdfs\x03\xaa7\xac\xc0\xd2\x10\xcc\x04\x07\xedq\x84\x16\xe4\xef\x93\xf1{\x8bOL\x99\xceZ\xb8*\xd4\xbdb\xfcL\xb1aR{\x00D\xc7\xbc\x9c\xad\xe4*\x9f\xb1\x02_t\x90\xff\x00\xa0Ki\x1a\xcfX\xf9\xb1\x8f\xd5\x04"\xf1\xe0\x05\x94e\xe9\x8f\xbeX\x0bX\\\x10\xa8U,\xfc\xcfp\xdd\xd3\x85\xf3\xb1\xdf\xd5\x11\xab\xde\x0b\xd7\xbe\xf4\xf6\xe1H\xb5\xa4\x92\xc9\xd5\xd8[\xc7y\xa1f\xc4\x00\xa6\xbe\'W\x02\xd9\xd9n\xbey\x9em\xbe\xd5\xb4\xcb\xb0\xb9\xa5\xfb\xf6\xce\xb3)\xa8\xfe,\xe3\xb7{\x8a"L\xb1\xe5\x7f\xfe_\x98\xdcQ\x0f\xf8/\xcd\x03 \xafZv\xc3\xca\xe0\xf78\xf1v\x1c+*\xb7\x97\x93\xdeGg\x1c\xdf\x9b\xed\x7fe\x80\xe8N\xf61s\xc3\xcb\xa5x'
This signature is used by the model when you want to do chat/multi-turn discussions. It helps the model not only remember what was said before, but also what it thought before or what it got from its tools and function calls.
Here's a example: imagine you ask the model for the temperature today. It will do a tool call or use google search to get the weather then it will tell you that it will be 25 degres. If you then ask what the humidity is, it will be able to remember that it also got that info from the first call and not do a new request.
More details on the documentation.
Migrating from Gemini 2.5
Gemini 3 models are our most capable model family to date and offers a stepwise improvement over Gemini 2.5 Pro. When migrating, consider the following:
- Thinking: If you were previously using complex prompt engineering (like Chain-of-thought) to force Gemini 2.5 to reason, try Gemini 3 with
thinking_level: "high"and simplified prompts (more in the thinking guide. - Temperature settings: If your existing code explicitly sets temperature (especially to low values for deterministic outputs), we recommend removing this parameter and using the Gemini 3 default of 1.0 to avoid potential looping issues or performance degradation on complex tasks.
- PDF & document understanding: Default OCR resolution for PDFs has changed. If you relied on specific behavior for dense document parsing, test the new
MEDIA_RESOLUTION_HIGHsetting to ensure continued accuracy. - Token consumption: Migrating to Gemini 3 Pro defaults may increase token usage for PDFs but decrease token usage for video. If requests now exceed the context window due to higher default resolutions, we recommend explicitly reducing the media resolution.
- Image segmentation: Image segmentation capabilities (returning pixel-level masks for objects) are not supported in Gemini 3 Pro. For workloads requiring native image segmentation, we recommend continuing to utilize Gemini 2.5 Flash with thinking turned off (cf. Spatial understanding guide ) or Gemini Robotics-ER 1.5 .
Next Steps
Useful API references:
Check out the Google GenAI SDK and its documentation for more details on the GenAI SDK.
Related examples
For more detailed examples using Gemini models, check the Quickstarts folder of the cookbook.
You'll learn how to use the Live API , juggle with multiple tools or use Gemini's spatial understanding abilities.
You should also check out all the gen-media models:
- Podcast and speech generation using Gemini TTS ,
- Live interaction with Gemini Live ,
- Image generation using Imagen ,
- Video generation using Veo ,
- Music generation using Lyria RealTime .
Then, head to the Gemini thinking models guide that explicitly showcases its thoughts summaries and can manage more complex reasonings.
Finally, have a look at the examples folder of the cookbook for more complex use-cases and demos mixing different capabilities.