Repository Public
1The Gemini API provides a code execution tool that enables the model to2generate and run Python code. The model can then learn iteratively from the3code execution results until it arrives at a final output. You can use code4execution to build applications that benefit from code-based reasoning. For5example, you can use code execution to solve equations or process text. You can6also use the [libraries](https://ai.google.dev/gemini-api/docs/code-execution#supported-libraries) included in the code execution7environment to perform more specialized tasks.89Gemini is only able to execute code in Python. You can still ask Gemini to10generate code in another language, but the model can't use the code execution11tool to run it.1213## Enable code execution1415To enable code execution, configure the code execution tool on the model. This16allows the model to generate and run code.1718### Python1920 from google import genai2122 client = genai.Client()2324 interaction = client.interactions.create(25 model="gemini-3.8-flash",26 input="What is the sum of the first 50 prime numbers? "27 "Generate and run code for the calculation, and make sure you get all 50.",28 tools=[{"type": "code_execution"}]29 )3031 for step in interaction.steps:32 if step.type == "model_output":33 for content_block in step.content:34 if content_block.type == "text":35 print(content_block.text)36 elif step.type == "code_execution_call":37 print(step.arguments.code)38 elif step.type == "code_execution_result":39 print(step.result)4041### JavaScript4243 import { GoogleGenAI } from "@google/genai";4445 const client = new GoogleGenAI({});4647 const interaction = await client.interactions.create({48 model: "gemini-3.8-flash",49 input: "What is the sum of the first 50 prime numbers? " +50 "Generate and run code for the calculation, and make sure you get all 50.",51 tools: [{ type: "code_execution" }]52 });5354 for (const step of interaction.steps) {55 if (step.type === "model_output") {56 for (const contentBlock of step.content) {57 if (contentBlock.type === "text") {58 console.log(contentBlock.text);59 }60 }61 } else if (step.type === "code_execution_call") {62 console.log(step.arguments.code);63 } else if (step.type === "code_execution_result") {64 console.log(step.result);65 }66 }6768### Java6970 import com.google.genai.Client;71 import com.google.genai.gaos.models.interactions.CodeExecution;72 import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;73 import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;74 import com.google.genai.gaos.models.interactions.Content;75 import com.google.genai.gaos.models.interactions.CreateModelInteraction;76 import com.google.genai.gaos.models.interactions.Interaction;77 import com.google.genai.gaos.models.interactions.InteractionsInput;78 import com.google.genai.gaos.models.interactions.ModelOutputStep;79 import com.google.genai.gaos.models.interactions.Step;80 import com.google.genai.gaos.models.interactions.TextContent;81 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;82 import java.util.Arrays;83 import java.util.Collections;8485 Client client = new Client();8687 CreateModelInteraction params =88 CreateModelInteraction.builder()89 .model("gemini-3.8-flash")90 .input(91 InteractionsInput.of(92 "What is the sum of the first 50 prime numbers? "93 + "Generate and run code for the calculation, and make sure you get all 50."))94 .tools(Arrays.asList(CodeExecution.builder().build()))95 .build();9697 Interaction interaction =98 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();99100 for (Step step : interaction.steps().orElse(Collections.emptyList())) {101 if (step instanceof ModelOutputStep) {102 ModelOutputStep outputStep = (ModelOutputStep) step;103 for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {104 if (contentBlock instanceof TextContent) {105 System.out.println(((TextContent) contentBlock).text().orElse(""));106 }107 }108 } else if (step instanceof CodeExecutionCallStep) {109 CodeExecutionCallStep callStep = (CodeExecutionCallStep) step;110 callStep.arguments().ifPresent(args -> System.out.println(args.code().orElse("")));111 } else if (step instanceof CodeExecutionResultStep) {112 CodeExecutionResultStep resultStep = (CodeExecutionResultStep) step;113 System.out.println(resultStep.result().orElse(""));114 }115 }116117### REST118119 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \120 -H "x-goog-api-key: $GEMINI_API_KEY" \121 -H 'Content-Type: application/json' \122 -d '{123 "model": "gemini-3.8-flash",124 "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.",125 "tools": [{"type": "code_execution"}]126 }'127128The output might look something like the following, which has been formatted for129readability:130131 Okay, I need to calculate the sum of the first 50 prime numbers. Here's how I'll132 approach this:133134 1. **Generate Prime Numbers:** I'll use an iterative method to find prime135 numbers. I'll start with 2 and check if each subsequent number is divisible136 by any number between 2 and its square root. If not, it's a prime.137 2. **Store Primes:** I'll store the prime numbers in a list until I have 50 of138 them.139 3. **Calculate the Sum:** Finally, I'll sum the prime numbers in the list.140141 Here's the Python code to do this:142143 def is_prime(n):144 """Efficiently checks if a number is prime."""145 if n <= 1:146 return False147 if n <= 3:148 return True149 if n % 2 == 0 or n % 3 == 0:150 return False151 i = 5152 while i * i <= n:153 if n % i == 0 or n % (i + 2) == 0:154 return False155 i += 6156 return True157158 primes = []159 num = 2160 while len(primes) < 50:161 if is_prime(num):162 primes.append(num)163 num += 1164165 sum_of_primes = sum(primes)166 print(f'{primes=}')167 print(f'{sum_of_primes=}')168169 primes=[2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67,170 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151,171 157, 163, 167, 173, 179, 181, 191, 193, 197, 199, 211, 223, 227, 229]172 sum_of_primes=5117173174 The sum of the first 50 prime numbers is 5117.175176This output combines several content parts that the model returns when using177code execution:178179- `text`: Inline text generated by the model180- `code_execution_call`: Code generated by the model that is meant to be executed181- `code_execution_result`: Result of the executable code182183## Code Execution with images (Gemini 3)184185The Gemini 3 Flash model can now write and execute Python code to actively186manipulate and inspect images.187188**Use cases**189190- **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.191- **Visual math**: The model can run multi-step calculations using code (e.g., summing line items on a receipt).192- **Image annotation**: The model can annotate images to answer questions, such as drawing arrows to show relationships.193194> [!NOTE]195> **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".196197## Enable Code Execution with images198199Code Execution with images is officially supported in Gemini 3 Flash. You can200activate this behavior by enabling both Code Execution as a tool and Thinking.201202### Python203204 from google import genai205 import requests206 import base64207 from PIL import Image208 import io209210 image_path = "https://goo.gle/instrument-img"211 image_bytes = requests.get(image_path).content212213 client = genai.Client()214215 interaction = client.interactions.create(216 model="gemini-3.8-flash",217 input=[218 {"type": "image", "data": base64.b64encode(image_bytes).decode('utf-8'), "mime_type": "image/jpeg"},219 {"type": "text", "text": "Zoom into the expression pedals and tell me how many pedals are there?"}220 ],221 tools=[{"type": "code_execution"}]222 )223224 for step in interaction.steps:225 if step.type == "model_output":226 for content_block in step.content:227 if content_block.type == "text":228 print(content_block.text)229 elif content_block.type == "image":230 img = Image.open(io.BytesIO(base64.b64decode(content_block.data)))231 img.show() # or: img.save("output_image.jpg")232 elif step.type == "code_execution_call":233 print(step.arguments.code)234 elif step.type == "code_execution_result":235 print(step.result)236237### JavaScript238239 import { GoogleGenAI } from "@google/genai";240241 async function main() {242 const client = new GoogleGenAI({});243244 const imageUrl = "https://goo.gle/instrument-img";245 const response = await fetch(imageUrl);246 const imageArrayBuffer = await response.arrayBuffer();247 const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');248249 const interaction = await client.interactions.create({250 model: "gemini-3.8-flash",251 input: [252 {253 type: "image",254 data: base64ImageData,255 mime_type: "image/jpeg"256 },257 { type: "text", text: "Zoom into the expression pedals and tell me how many pedals are there?" }258 ],259 tools: [{ type: "code_execution" }]260 });261262 for (const step of interaction.steps) {263 if (step.type === "model_output") {264 for (const contentBlock of step.content) {265 if (contentBlock.type === "text") {266 console.log("Text:", contentBlock.text);267 }268 }269 } else if (step.type === "code_execution_call") {270 console.log(`\nGenerated Code:\n`, step.arguments.code);271 } else if (step.type === "code_execution_result") {272 console.log(`\nExecution Output:\n`, step.result);273 }274 }275 }276277 main();278279### Java280281 import com.google.genai.Client;282 import com.google.genai.gaos.models.interactions.CodeExecution;283 import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;284 import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;285 import com.google.genai.gaos.models.interactions.Content;286 import com.google.genai.gaos.models.interactions.CreateModelInteraction;287 import com.google.genai.gaos.models.interactions.ImageContent;288 import com.google.genai.gaos.models.interactions.ImageContentMimeType;289 import com.google.genai.gaos.models.interactions.Interaction;290 import com.google.genai.gaos.models.interactions.InteractionsInput;291 import com.google.genai.gaos.models.interactions.ModelOutputStep;292 import com.google.genai.gaos.models.interactions.Step;293 import com.google.genai.gaos.models.interactions.TextContent;294 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;295 import java.io.InputStream;296 import java.net.URI;297 import java.nio.file.Files;298 import java.nio.file.Paths;299 import java.util.Arrays;300 import java.util.Base64;301 import java.util.Collections;302303 String imageUrl = "https://goo.gle/instrument-img";304 byte[] imageBytes;305 try (InputStream in = URI.create(imageUrl).toURL().openStream()) {306 imageBytes = in.readAllBytes();307 }308 String base64Image = Base64.getEncoder().encodeToString(imageBytes);309310 Client client = new Client();311312 CreateModelInteraction params =313 CreateModelInteraction.builder()314 .model("gemini-3.8-flash")315 .input(316 InteractionsInput.ofContent(317 Arrays.asList(318 ImageContent.builder()319 .data(base64Image)320 .mimeType(ImageContentMimeType.IMAGE_JPEG)321 .build(),322 TextContent.builder()323 .text(324 "Zoom into the expression pedals and tell me how many pedals are there?")325 .build())))326 .tools(Arrays.asList(CodeExecution.builder().build()))327 .build();328329 Interaction interaction =330 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();331332 for (Step step : interaction.steps().orElse(Collections.emptyList())) {333 if (step instanceof ModelOutputStep) {334 ModelOutputStep outputStep = (ModelOutputStep) step;335 for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {336 if (contentBlock instanceof TextContent) {337 System.out.println(((TextContent) contentBlock).text().orElse(""));338 } else if (contentBlock instanceof ImageContent) {339 ImageContent imgContent = (ImageContent) contentBlock;340 if (imgContent.data().isPresent()) {341 byte[] decoded = Base64.getDecoder().decode(imgContent.data().get());342 Files.write(Paths.get("output_image.jpg"), decoded);343 }344 }345 }346 } else if (step instanceof CodeExecutionCallStep) {347 CodeExecutionCallStep callStep = (CodeExecutionCallStep) step;348 callStep.arguments().ifPresent(args -> System.out.println(args.code().orElse("")));349 } else if (step instanceof CodeExecutionResultStep) {350 CodeExecutionResultStep resultStep = (CodeExecutionResultStep) step;351 System.out.println(resultStep.result().orElse(""));352 }353 }354355### REST356357 IMG_URL="https://goo.gle/instrument-img"358 MODEL="gemini-3.8-flash"359360 MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)361 if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then362 MIME_TYPE="image/jpeg"363 fi364365 if [[ "$(uname)" == "Darwin" ]]; then366 IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)367 elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then368 IMAGE_B64=$(curl -sL "$IMG_URL" | base64)369 else370 IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)371 fi372373 # Use jq to create the JSON payload to avoid "Argument list too long" error with large base64 strings374 echo -n "$IMAGE_B64" > image_b64.txt375 jq -n \376 --rawfile b64 image_b64.txt \377 --arg mime "$MIME_TYPE" \378 '{379 model: "gemini-3.8-flash",380 input: [381 {type: "image", data: $b64, mime_type: $mime},382 {type: "text", text: "Zoom into the expression pedals and tell me how many pedals are there?"}383 ],384 tools: [{type: "code_execution"}]385 }' > payload.json386387 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \388 -H "x-goog-api-key: $GEMINI_API_KEY" \389 -H 'Content-Type: application/json' \390 -d @payload.json391392## Use code execution in multi-turn interactions393394You can also use code execution as part of a multi-turn conversation using395`previous_interaction_id`.396397### Python398399 from google import genai400401 client = genai.Client()402403 interaction1 = client.interactions.create(404 model="gemini-3.8-flash",405 input="I have a math question for you.",406 tools=[{"type": "code_execution"}]407 )408 print(interaction1.output_text)409410 interaction2 = client.interactions.create(411 model="gemini-3.8-flash",412 previous_interaction_id=interaction1.id,413 input="What is the sum of the first 50 prime numbers? "414 "Generate and run code for the calculation, and make sure you get all 50.",415 tools=[{"type": "code_execution"}]416 )417418 for step in interaction2.steps:419 if step.type == "model_output":420 for content_block in step.content:421 if content_block.type == "text":422 print(content_block.text)423 elif step.type == "code_execution_call":424 print(step.arguments.code)425 elif step.type == "code_execution_result":426 print(step.result)427428### JavaScript429430 import { GoogleGenAI } from "@google/genai";431432 const client = new GoogleGenAI({});433434 const interaction1 = await client.interactions.create({435 model: "gemini-3.8-flash",436 input: "I have a math question for you.",437 tools: [{ type: "code_execution" }]438 });439 console.log(interaction1.output_text);440441 const interaction2 = await client.interactions.create({442 model: "gemini-3.8-flash",443 previous_interaction_id: interaction1.id,444 input: "What is the sum of the first 50 prime numbers? " +445 "Generate and run code for the calculation, and make sure you get all 50.",446 tools: [{ type: "code_execution" }]447 });448449 for (const step of interaction2.steps) {450 if (step.type === "model_output") {451 for (const contentBlock of step.content) {452 if (contentBlock.type === "text") {453 console.log(contentBlock.text);454 }455 }456 } else if (step.type === "code_execution_call") {457 console.log(step.arguments.code);458 } else if (step.type === "code_execution_result") {459 console.log(step.result);460 }461 }462463### Java464465 import com.google.genai.Client;466 import com.google.genai.gaos.models.interactions.CodeExecution;467 import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;468 import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;469 import com.google.genai.gaos.models.interactions.Content;470 import com.google.genai.gaos.models.interactions.CreateModelInteraction;471 import com.google.genai.gaos.models.interactions.Interaction;472 import com.google.genai.gaos.models.interactions.InteractionsInput;473 import com.google.genai.gaos.models.interactions.ModelOutputStep;474 import com.google.genai.gaos.models.interactions.Step;475 import com.google.genai.gaos.models.interactions.TextContent;476 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;477 import java.util.Arrays;478 import java.util.Collections;479480 Client client = new Client();481482 CreateModelInteraction params1 =483 CreateModelInteraction.builder()484 .model("gemini-3.8-flash")485 .input(InteractionsInput.of("I have a math question for you."))486 .tools(Arrays.asList(CodeExecution.builder().build()))487 .build();488489 Interaction interaction1 =490 client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();491 System.out.println(interaction1.outputText().orElse(""));492493 CreateModelInteraction params2 =494 CreateModelInteraction.builder()495 .model("gemini-3.8-flash")496 .previousInteractionId(interaction1.id().get())497 .input(498 InteractionsInput.of(499 "What is the sum of the first 50 prime numbers? "500 + "Generate and run code for the calculation, and make sure you get all 50."))501 .tools(Arrays.asList(CodeExecution.builder().build()))502 .build();503504 Interaction interaction2 =505 client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();506507 for (Step step : interaction2.steps().orElse(Collections.emptyList())) {508 if (step instanceof ModelOutputStep) {509 ModelOutputStep outputStep = (ModelOutputStep) step;510 for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {511 if (contentBlock instanceof TextContent) {512 System.out.println(((TextContent) contentBlock).text().orElse(""));513 }514 }515 } else if (step instanceof CodeExecutionCallStep) {516 CodeExecutionCallStep callStep = (CodeExecutionCallStep) step;517 callStep.arguments().ifPresent(args -> System.out.println(args.code().orElse("")));518 } else if (step instanceof CodeExecutionResultStep) {519 CodeExecutionResultStep resultStep = (CodeExecutionResultStep) step;520 System.out.println(resultStep.result().orElse(""));521 }522 }523524### REST525526 # First turn527 RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \528 -H "x-goog-api-key: $GEMINI_API_KEY" \529 -H 'Content-Type: application/json' \530 -d '{531 "model": "gemini-3.8-flash",532 "input": "I have a math question for you.",533 "tools": [{"type": "code_execution"}]534 }')535536 INTERACTION_ID=$(echo $RESPONSE1 | jq -r '.id')537538 # Second turn with previous_interaction_id539 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \540 -H "x-goog-api-key: $GEMINI_API_KEY" \541 -H 'Content-Type: application/json' \542 -d '{543 "model": "gemini-3.8-flash",544 "previous_interaction_id": "'"$INTERACTION_ID"'",545 "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.",546 "tools": [{"type": "code_execution"}]547 }'548549## Input/output (I/O)550551In current Gemini models such as552[Gemini 3.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini#gemini-3.5-flash), code553execution supports file input and graph output. Using these input and output554capabilities, you can upload CSV and text files, ask questions about the555files, and have [Matplotlib](https://matplotlib.org/) graphs generated as part556of the response. The output files are returned as inline images in the response.557558### I/O pricing559560When using code execution I/O, you're charged for input tokens and output561tokens:562563**Input tokens:**564565- User prompt566567**Output tokens:**568569- Code generated by the model570- Code execution output in the code environment571- Thinking tokens572- Summary generated by the model573574### I/O details575576When you're working with code execution I/O, be aware of the following technical577details:578579- The maximum runtime of the code environment is 30 seconds.580- If the code environment generates an error, the model may decide to regenerate the code output. This can happen up to 5 times.581- The maximum file input size is limited by the model token window. If you upload a file that exceeds the model's maximum context window, the API will return an error.582- Code execution works best with text and CSV files.583- The input file can be passed as inline data or uploaded using the [Files API](https://ai.google.dev/gemini-api/docs/files), and the output file is always returned as inline data.584585## Billing586587There's no additional charge for enabling code execution from the Gemini API.588You'll be billed at the current rate of input and output tokens based on the589Gemini model you're using.590591Here are a few other things to know about billing for code execution:592593- 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.594- Tokens representing generated code are counted as output tokens. Generated code can include text and multimodal output like images.595- Code execution results are also counted as output tokens.596597The billing model is shown in the following diagram:598599600601- You're billed at the current rate of input and output tokens based on the Gemini model you're using.602- 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*.603- 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*.604- 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.605606## Limitations607608- The model can only generate and execute code. It can't return other artifacts like media files.609- In some cases, enabling code execution can lead to regressions in other areas of model output (for example, writing a story).610- There is some variation in the ability of the different models to use code execution successfully.611612## Supported tools combinations613614Code execution tool can be combined with615[Grounding with Google Search](https://ai.google.dev/gemini-api/docs/google-search) to616power more complex use cases.617618Gemini 3 models support combining built-in tools (like Code Execution) with619custom tools (function calling).620621## Supported libraries622623The code execution environment includes the following libraries:624625- attrs626- chess627- contourpy628- fpdf629- geopandas630- imageio631- jinja2632- joblib633- jsonschema634- jsonschema-specifications635- lxml636- matplotlib637- mpmath638- numpy639- opencv-python640- openpyxl641- packaging642- pandas643- pillow644- protobuf645- pylatex646- pyparsing647- PyPDF2648- python-dateutil649- python-docx650- python-pptx651- reportlab652- scikit-learn653- scipy654- seaborn655- six656- striprtf657- sympy658- tabulate659- tensorflow660- toolz661- xlrd662663You can't install your own libraries.664665> [!NOTE]666> **Note:** Only `matplotlib` is supported for graph rendering using code execution.667668## What's next669670- Try the [Interactions API Quickstart](https://ai.google.dev/gemini-api/docs/quickstart).671- Learn about other Gemini API tools:672 - [Function calling](https://ai.google.dev/gemini-api/docs/function-calling)673 - [Grounding with Google Search](https://ai.google.dev/gemini-api/docs/google-search)