Repository Public
1# Code execution23> [!NOTE]4> **Note** : This version of the page covers the new [Interactions API](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview), which is currently in Beta. 5> For stable production deployments, we recommend you continue to use the `generateContent` API. You can use the toggle on this page to switch between the versions.67The Gemini API provides a code execution tool that enables the model to8generate and run Python code. The model can then learn iteratively from the9code execution results until it arrives at a final output. You can use code10execution to build applications that benefit from code-based reasoning. For11example, you can use code execution to solve equations or process text. You can12also use the [libraries](https://ai.google.dev/gemini-api/docs/interactions/code-execution#supported-libraries) included in the code execution13environment to perform more specialized tasks.1415Gemini is only able to execute code in Python. You can still ask Gemini to16generate code in another language, but the model can't use the code execution17tool to run it.1819> [!NOTE]20> **Important:** If you are using the Interactions API in \*\*stateless mode\*\* (by setting \`store=false\` or managing conversation history manually), you must pass back the `id` and `signature` fields returned by the API in subsequent requests to ensure context is preserved for tool combination to work. If you are using stateful mode (the default with `store=true` or by referencing `previous_interaction_id`), this is handled automatically by the server.2122## Enable code execution2324To enable code execution, configure the code execution tool on the model. This25allows the model to generate and run code.2627### Python2829 from google import genai3031 client = genai.Client()3233 interaction = client.interactions.create(34 model="gemini-3.5-flash",35 input="What is the sum of the first 50 prime numbers? "36 "Generate and run code for the calculation, and make sure you get all 50.",37 tools=[{"type": "code_execution"}]38 )3940 for step in interaction.steps:41 if step.type == "model_output":42 for content_block in step.content:43 if content_block.type == "text":44 print(content_block.text)45 elif step.type == "code_execution_call":46 print(step.arguments.code)47 elif step.type == "code_execution_result":48 print(step.result)4950### JavaScript5152 import { GoogleGenAI } from "@google/genai";5354 const client = new GoogleGenAI({});5556 const interaction = await client.interactions.create({57 model: "gemini-3.5-flash",58 input: "What is the sum of the first 50 prime numbers? " +59 "Generate and run code for the calculation, and make sure you get all 50.",60 tools: [{ type: "code_execution" }]61 });6263 for (const step of interaction.steps) {64 if (step.type === "model_output") {65 for (const contentBlock of step.content) {66 if (contentBlock.type === "text") {67 console.log(contentBlock.text);68 }69 }70 } else if (step.type === "code_execution_call") {71 console.log(step.arguments.code);72 } else if (step.type === "code_execution_result") {73 console.log(step.result);74 }75 }7677### REST7879 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \80 -H "x-goog-api-key: $GEMINI_API_KEY" \81 -H 'Content-Type: application/json' \82 -H "Api-Revision: 2026-05-20" \83 -d '{84 "model": "gemini-3.5-flash",85 "input": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50.",86 "tools": [{"type": "code_execution"}]87 }'8889The output might look something like the following, which has been formatted for90readability:9192 Okay, I need to calculate the sum of the first 50 prime numbers. Here's how I'll93 approach this:9495 1. **Generate Prime Numbers:** I'll use an iterative method to find prime96 numbers. I'll start with 2 and check if each subsequent number is divisible97 by any number between 2 and its square root. If not, it's a prime.98 2. **Store Primes:** I'll store the prime numbers in a list until I have 50 of99 them.100 3. **Calculate the Sum:** Finally, I'll sum the prime numbers in the list.101102 Here's the Python code to do this:103104 def is_prime(n):105 """Efficiently checks if a number is prime."""106 if n <= 1:107 return False108 if n <= 3:109 return True110 if n % 2 == 0 or n % 3 == 0:111 return False112 i = 5113 while i * i <= n:114 if n % i == 0 or n % (i + 2) == 0:115 return False116 i += 6117 return True118119 primes = []120 num = 2121 while len(primes) < 50:122 if is_prime(num):123 primes.append(num)124 num += 1125126 sum_of_primes = sum(primes)127 print(f'{primes=}')128 print(f'{sum_of_primes=}')129130 primes=[2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67,131 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151,132 157, 163, 167, 173, 179, 181, 191, 193, 197, 199, 211, 223, 227, 229]133 sum_of_primes=5117134135 The sum of the first 50 prime numbers is 5117.136137This output combines several content parts that the model returns when using138code execution:139140- `text`: Inline text generated by the model141- `code_execution_call`: Code generated by the model that is meant to be executed142- `code_execution_result`: Result of the executable code143144## Code Execution with images (Gemini 3)145146The Gemini 3 Flash model can now write and execute Python code to actively147manipulate and inspect images.148149**Use cases**150151- **Zoom and inspect**: The model implicitly detects when details are too small (e.g., reading a distant gauge) and writes code to crop and re-examine the area at higher resolution.152- **Visual math**: The model can run multi-step calculations using code (e.g., summing line items on a receipt).153- **Image annotation**: The model can annotate images to answer questions, such as drawing arrows to show relationships.154155> [!NOTE]156> **Note:** While the model automatically handles zooming for small details, you should prompt it explicitly to use code for other tasks, such as "Write code to count the number of gears" or "Rotate this image to make it upright".157158## Enable Code Execution with images159160Code Execution with images is officially supported in Gemini 3 Flash. You can161activate this behavior by enabling both Code Execution as a tool and Thinking.162163### Python164165 from google import genai166 import requests167 import base64168 from PIL import Image169 import io170171 image_path = "https://goo.gle/instrument-img"172 image_bytes = requests.get(image_path).content173174 client = genai.Client()175176 interaction = client.interactions.create(177 model="gemini-3.5-flash",178 input=[179 {"type": "image", "data": base64.b64encode(image_bytes).decode('\utf-8'), "mime_type": "image/jpeg"},180 {"type": "text", "text": "Zoom into the expression pedals and tell me how many pedals are there?"}181 ],182 tools=[{"type": "code_execution"}]183 )184185 for step in interaction.steps:186 if step.type == "model_output":187 for content_block in step.content:188 if content_block.type == "text":189 print(content_block.text)190 elif content_block.type == "image":191 display(Image.open(io.BytesIO(base64.b64decode(content_block.data))))192 elif step.type == "code_execution_call":193 print(step.arguments.code)194 elif step.type == "code_execution_result":195 print(step.result)196197### JavaScript198199 import { GoogleGenAI } from "@google/genai";200201 async function main() {202 const client = new GoogleGenAI({});203204 const imageUrl = "https://goo.gle/instrument-img";205 const response = await fetch(imageUrl);206 const imageArrayBuffer = await response.arrayBuffer();207 const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');208209 const interaction = await client.interactions.create({210 model: "gemini-3.5-flash",211 input: [212 {213 type: "image",214 data: base64ImageData,215 mime_type: "image/jpeg"216 },217 { type: "text", text: "Zoom into the expression pedals and tell me how many pedals are there?" }218 ],219 tools: [{ type: "code_execution" }]220 });221222 for (const step of interaction.steps) {223 if (step.type === "model_output") {224 for (const contentBlock of step.content) {225 if (contentBlock.type === "text") {226 console.log("Text:", contentBlock.text);227 }228 }229 } else if (step.type === "code_execution_call") {230 console.log(`\nGenerated Code:\n`, step.arguments.code);231 } else if (step.type === "code_execution_result") {232 console.log(`\nExecution Output:\n`, step.result);233 }234 }235 }236237 main();238239### REST240241 IMG_URL="https://goo.gle/instrument-img"242 MODEL="gemini-3.5-flash"243244 MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)245 if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then246 MIME_TYPE="image/jpeg"247 fi248249 if [[ "$(uname)" == "Darwin" ]]; then250 IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)251 elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then252 IMAGE_B64=$(curl -sL "$IMG_URL" | base64)253 else254 IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)255 fi256257 # Use jq to create the JSON payload to avoid "Argument list too long" error with large base64 strings258 echo -n "$IMAGE_B64" > image_b64.txt259 jq -n \260 --rawfile b64 image_b64.txt \261 --arg mime "$MIME_TYPE" \262 '{263 model: "gemini-3.5-flash",264 input: [265 {type: "image", data: $b64, mime_type: $mime},266 {type: "text", text: "Zoom into the expression pedals and tell me how many pedals are there?"}267 ],268 tools: [{type: "code_execution"}]269 }' > payload.json270271 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \272 -H "x-goog-api-key: $GEMINI_API_KEY" \273 -H 'Content-Type: application/json' \274 -H "Api-Revision: 2026-05-20" \275 -d @payload.json276277## Use code execution in multi-turn interactions278279You can also use code execution as part of a multi-turn conversation using280`previous_interaction_id`.281282### Python283284 from google import genai285286 client = genai.Client()287288 interaction1 = client.interactions.create(289 model="gemini-3.5-flash",290 input="I have a math question for you.",291 tools=[{"type": "code_execution"}]292 )293 print(interaction1.output_text)294295 interaction2 = client.interactions.create(296 model="gemini-3.5-flash",297 previous_interaction_id=interaction1.id,298 input="What is the sum of the first 50 prime numbers? "299 "Generate and run code for the calculation, and make sure you get all 50.",300 tools=[{"type": "code_execution"}]301 )302303 for step in interaction2.steps:304 if step.type == "model_output":305 for content_block in step.content:306 if content_block.type == "text":307 print(content_block.text)308 elif step.type == "code_execution_call":309 print(step.arguments.code)310 elif step.type == "code_execution_result":311 print(step.result)312313### JavaScript314315 import { GoogleGenAI } from "@google/genai";316317 const client = new GoogleGenAI({});318319 const interaction1 = await client.interactions.create({320 model: "gemini-3.5-flash",321 input: "I have a math question for you.",322 tools: [{ type: "code_execution" }]323 });324 console.log(interaction1.output_text);325326 const interaction2 = await client.interactions.create({327 model: "gemini-3.5-flash",328 previous_interaction_id: interaction1.id,329 input: "What is the sum of the first 50 prime numbers? " +330 "Generate and run code for the calculation, and make sure you get all 50.",331 tools: [{ type: "code_execution" }]332 });333334 for (const step of interaction2.steps) {335 if (step.type === "model_output") {336 for (const contentBlock of step.content) {337 if (contentBlock.type === "text") {338 console.log(contentBlock.text);339 }340 }341 } else if (step.type === "code_execution_call") {342 console.log(step.arguments.code);343 } else if (step.type === "code_execution_result") {344 console.log(step.result);345 }346 }347348### REST349350 # First turn351 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \352 -H "x-goog-api-key: $GEMINI_API_KEY" \353 -H 'Content-Type: application/json' \354 -H "Api-Revision: 2026-05-20" \355 -d '{356 "model": "gemini-3.5-flash",357 "input": "I have a math question for you.",358 "tools": [{"type": "code_execution"}]359 }')360361 INTERACTION_ID=$(echo $RESPONSE1 | jq -r '.id')362363 # Second turn with previous_interaction_id364 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \365 -H "x-goog-api-key: $GEMINI_API_KEY" \366 -H 'Content-Type: application/json' \367 -H "Api-Revision: 2026-05-20" \368 -d '{369 "model": "gemini-3.5-flash",370 "previous_interaction_id": "'"$INTERACTION_ID"'",371 "input": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50.",372 "tools": [{"type": "code_execution"}]373 }'374375## Input/output (I/O)376377Starting with378[Gemini 2.0 Flash](https://ai.google.dev/gemini-api/docs/models/gemini#gemini-2.0-flash), code379execution supports file input and graph output. Using these input and output380capabilities, you can upload CSV and text files, ask questions about the381files, and have [Matplotlib](https://matplotlib.org/) graphs generated as part382of the response. The output files are returned as inline images in the response.383384### I/O pricing385386When using code execution I/O, you're charged for input tokens and output387tokens:388389**Input tokens:**390391- User prompt392393**Output tokens:**394395- Code generated by the model396- Code execution output in the code environment397- Thinking tokens398- Summary generated by the model399400### I/O details401402When you're working with code execution I/O, be aware of the following technical403details:404405- The maximum runtime of the code environment is 30 seconds.406- If the code environment generates an error, the model may decide to regenerate the code output. This can happen up to 5 times.407- The maximum file input size is limited by the model token window. In AI Studio, using Gemini Flash 2.0, the maximum input file size is 1 million tokens (roughly 2MB for text files of the supported input types). If you upload a file that's too large, AI Studio won't let you send it.408- Code execution works best with text and CSV files.409- The input file can be passed as inline data or uploaded using the [Files API](https://ai.google.dev/gemini-api/docs/interactions/files), and the output file is always returned as inline data.410411## Billing412413There's no additional charge for enabling code execution from the Gemini API.414You'll be billed at the current rate of input and output tokens based on the415Gemini model you're using.416417Here are a few other things to know about billing for code execution:418419- You're only billed once for the input tokens you pass to the model, and you're billed for the final output tokens returned to you by the model.420- Tokens representing generated code are counted as output tokens. Generated code can include text and multimodal output like images.421- Code execution results are also counted as output tokens.422423The billing model is shown in the following diagram:424425426427- You're billed at the current rate of input and output tokens based on the Gemini model you're using.428- If Gemini uses code execution when generating your response, the original prompt, the generated code, and the result of the executed code are labeled *intermediate tokens* and are billed as *input tokens*.429- Gemini then generates a summary and returns the generated code, the result of the executed code, and the final summary. These are billed as *output tokens*.430- The Gemini API includes an intermediate token count in the API response, so you know why you're getting additional input tokens beyond your initial prompt.431432## Limitations433434- The model can only generate and execute code. It can't return other artifacts like media files.435- In some cases, enabling code execution can lead to regressions in other areas of model output (for example, writing a story).436- There is some variation in the ability of the different models to use code execution successfully.437438## Supported tools combinations439440Code execution tool can be combined with441[Grounding with Google Search](https://ai.google.dev/gemini-api/docs/interactions/google-search) to442power more complex use cases.443444Gemini 3 models support combining built-in tools (like Code Execution) with445custom tools (function calling).446447## Supported libraries448449The code execution environment includes the following libraries:450451- attrs452- chess453- contourpy454- fpdf455- geopandas456- imageio457- jinja2458- joblib459- jsonschema460- jsonschema-specifications461- lxml462- matplotlib463- mpmath464- numpy465- opencv-python466- openpyxl467- packaging468- pandas469- pillow470- protobuf471- pylatex472- pyparsing473- PyPDF2474- python-dateutil475- python-docx476- python-pptx477- reportlab478- scikit-learn479- scipy480- seaborn481- six482- striprtf483- sympy484- tabulate485- tensorflow486- toolz487- xlrd488489You can't install your own libraries.490491> [!NOTE]492> **Note:** Only `matplotlib` is supported for graph rendering using code execution.493494## What's next495496- Try the497- Learn about other Gemini API tools:498 - [Function calling](https://ai.google.dev/gemini-api/docs/interactions/function-calling)499 - [Grounding with Google Search](https://ai.google.dev/gemini-api/docs/interactions/google-search)