Gemini API는 모델이 Python 코드를 생성하고 실행할 수 있도록 하는 코드 실행 도구를 제공합니다. 그러면 모델은 최종 출력을 도출할 때까지 코드 실행 결과를 반복적으로 학습할 수 있습니다. 코드 실행을 사용하여 코드 기반 추론의 이점을 활용하는 애플리케이션을 빌드할 수 있습니다. 예를 들어 코드 실행을 사용하여 방정식을 풀거나 텍스트를 처리할 수 있습니다. 코드 실행 환경에 포함된 라이브러리를 사용하여 더 전문화된 작업을 실행할 수도 있습니다.
Gemini는 Python에서만 코드를 실행할 수 있습니다. 다른 언어로 코드를 생성하도록 Gemini에 요청할 수는 있지만 모델은 코드 실행 도구를 사용하여 코드를 실행할 수 없습니다.
코드 실행 사용 설정
코드 실행을 사용 설정하려면 모델에서 코드 실행 도구를 구성합니다. 이렇게 하면 모델이 코드를 생성하고 실행할 수 있습니다.
Python
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="What is the sum of the first 50 prime numbers? "
"Generate and run code for the calculation, and make sure you get all 50.",
config=types.GenerateContentConfig(
tools=[types.Tool(code_execution=types.ToolCodeExecution)]
),
)
for part in response.candidates[0].content.parts:
if part.text is not None:
print(part.text)
if part.executable_code is not None:
print(part.executable_code.code)
if part.code_execution_result is not None:
print(part.code_execution_result.output)
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
let response = await ai.models.generateContent({
model: "gemini-3.5-flash",
contents: [
"What is the sum of the first 50 prime numbers? " +
"Generate and run code for the calculation, and make sure you get all 50.",
],
config: {
tools: [{ codeExecution: {} }],
},
});
const parts = response?.candidates?.[0]?.content?.parts || [];
parts.forEach((part) => {
if (part.text) {
console.log(part.text);
}
if (part.executableCode && part.executableCode.code) {
console.log(part.executableCode.code);
}
if (part.codeExecutionResult && part.codeExecutionResult.output) {
console.log(part.codeExecutionResult.output);
}
});
Go
package main
import (
"context"
"fmt"
"os"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
config := &genai.GenerateContentConfig{
Tools: []*genai.Tool{
{CodeExecution: &genai.ToolCodeExecution{}},
},
}
result, _ := client.Models.GenerateContent(
ctx,
"gemini-3.5-flash",
genai.Text("What is the sum of the first 50 prime numbers? " +
"Generate and run code for the calculation, and make sure you get all 50."),
config,
)
fmt.Println(result.Text())
fmt.Println(result.ExecutableCode())
fmt.Println(result.CodeExecutionResult())
}
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d ' {"tools": [{"code_execution": {}}],
"contents": {
"parts":
{
"text": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50."
}
},
}'
출력은 가독성을 위해 형식이 지정된 다음과 같은 모습일 수 있습니다.
Okay, I need to calculate the sum of the first 50 prime numbers. Here's how I'll
approach this:
1. **Generate Prime Numbers:** I'll use an iterative method to find prime
numbers. I'll start with 2 and check if each subsequent number is divisible
by any number between 2 and its square root. If not, it's a prime.
2. **Store Primes:** I'll store the prime numbers in a list until I have 50 of
them.
3. **Calculate the Sum:** Finally, I'll sum the prime numbers in the list.
Here's the Python code to do this:
def is_prime(n):
"""Efficiently checks if a number is prime."""
if n <= 1:
return False
if n <= 3:
return True
if n % 2 == 0 or n % 3 == 0:
return False
i = 5
while i * i <= n:
if n % i == 0 or n % (i + 2) == 0:
return False
i += 6
return True
primes = []
num = 2
while len(primes) < 50:
if is_prime(num):
primes.append(num)
num += 1
sum_of_primes = sum(primes)
print(f'{primes=}')
print(f'{sum_of_primes=}')
primes=[2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67,
71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151,
157, 163, 167, 173, 179, 181, 191, 193, 197, 199, 211, 223, 227, 229]
sum_of_primes=5117
The sum of the first 50 prime numbers is 5117.
이 출력은 모델이 코드 실행을 사용할 때 반환하는 여러 콘텐츠 부분을 결합합니다.
text: 모델에서 생성한 인라인 텍스트executableCode: 실행 목적으로 모델에서 생성된 코드codeExecutionResult: 실행 가능한 코드의 결과
이러한 부분의 이름 지정 규칙은 프로그래밍 언어에 따라 다릅니다.
이미지를 사용한 코드 실행 (Gemini 3)
이제 Gemini 3 Flash 모델은 Python 코드를 작성하고 실행하여 이미지를 적극적으로 조작하고 검사할 수 있습니다.
사용 사례
- 확대/축소 및 검사: 모델은 세부정보가 너무 작을 때 (예: 멀리 있는 게이지 읽기)를 암시적으로 감지하고 코드를 작성하여 영역을 자르고 더 높은 해상도로 다시 검사합니다.
- 시각적 수학: 모델은 코드를 사용하여 여러 단계 계산을 실행할 수 있습니다 (예: 영수증의 품목 합계).
- 이미지 주석: 모델은 화살표를 그려 관계를 표시하는 등 이미지에 주석을 달아 질문에 답변할 수 있습니다.
이미지를 사용한 코드 실행 사용 설정
이미지를 사용한 코드 실행은 Gemini 3 Flash에서 공식적으로 지원됩니다. 도구로서의 코드 실행과 사고를 모두 사용 설정하면 이 동작을 활성화할 수 있습니다.
Python
from google import genai
from google.genai import types
import requests
from PIL import Image
import io
image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content
image = types.Part.from_bytes(
data=image_bytes, mime_type="image/jpeg"
)
# Ensure you have your API key set
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.5-flash",
contents=[image, "Zoom into the expression pedals and tell me how many pedals are there?"],
config=types.GenerateContentConfig(
tools=[types.Tool(code_execution=types.ToolCodeExecution)]
),
)
for part in response.candidates[0].content.parts:
if part.text is not None:
print(part.text)
if part.executable_code is not None:
print(part.executable_code.code)
if part.code_execution_result is not None:
print(part.code_execution_result.output)
if part.as_image() is not None:
# display() is a standard function in Jupyter/Colab notebooks
display(Image.open(io.BytesIO(part.as_image().image_bytes)))
JavaScript
async function main() {
const ai = new GoogleGenAI({ });
// 1. Prepare Image Data
const imageUrl = "https://goo.gle/instrument-img";
const response = await fetch(imageUrl);
const imageArrayBuffer = await response.arrayBuffer();
const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');
// 2. Call the API with Code Execution enabled
const result = await ai.models.generateContent({
model: "gemini-3.5-flash",
contents: [
{
inlineData: {
mimeType: 'image/jpeg',
data: base64ImageData,
},
},
{ text: "Zoom into the expression pedals and tell me how many pedals are there?" }
],
config: {
tools: [{ codeExecution: {} }],
},
});
// 3. Process the response (Text, Code, and Execution Results)
const candidates = result.candidates;
if (candidates && candidates[0].content.parts) {
for (const part of candidates[0].content.parts) {
if (part.text) {
console.log("Text:", part.text);
}
if (part.executableCode) {
console.log(`\nGenerated Code (${part.executableCode.language}):\n`, part.executableCode.code);
}
if (part.codeExecutionResult) {
console.log(`\nExecution Output (${part.codeExecutionResult.outcome}):\n`, part.codeExecutionResult.output);
}
}
}
}
main();
Go
package main
import (
"context"
"fmt"
"io"
"log"
"net/http"
"os"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
// Initialize Client (Reads GEMINI_API_KEY from env)
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
// 1. Download the image
imageResp, err := http.Get("https://goo.gle/instrument-img")
if err != nil {
log.Fatal(err)
}
defer imageResp.Body.Close()
imageBytes, err := io.ReadAll(imageResp.Body)
if err != nil {
log.Fatal(err)
}
// 2. Configure Code Execution Tool
config := &genai.GenerateContentConfig{
Tools: []*genai.Tool{
{CodeExecution: &genai.ToolCodeExecution{}},
},
}
// 3. Generate Content
result, err := client.Models.GenerateContent(
ctx,
"gemini-3.5-flash",
[]*genai.Content{
{
Parts: []*genai.Part{
{InlineData: &genai.Blob{MIMEType: "image/jpeg", Data: imageBytes}},
{Text: "Zoom into the expression pedals and tell me how many pedals are there?"},
},
Role: "user",
},
},
config,
)
if err != nil {
log.Fatal(err)
}
// 4. Parse Response (Text, Code, Output)
for _, cand := range result.Candidates {
for _, part := range cand.Content.Parts {
if part.Text != "" {
fmt.Println("Text:", part.Text)
}
if part.ExecutableCode != nil {
fmt.Printf("\nGenerated Code (%s):\n%s\n",
part.ExecutableCode.Language,
part.ExecutableCode.Code)
}
if part.CodeExecutionResult != nil {
fmt.Printf("\nExecution Output (%s):\n%s\n",
part.CodeExecutionResult.Outcome,
part.CodeExecutionResult.Output)
}
}
}
}
REST
IMG_URL="https://goo.gle/instrument-img"
MODEL="gemini-3.5-flash"
MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)
if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then
MIME_TYPE="image/jpeg"
fi
if [[ "$(uname)" == "Darwin" ]]; then
IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)
elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
IMAGE_B64=$(curl -sL "$IMG_URL" | base64)
else
IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)
fi
curl "https://generativelanguage.googleapis.com/v1beta/models/$MODEL:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{
"inline_data": {
"mime_type":"'"$MIME_TYPE"'",
"data": "'"$IMAGE_B64"'"
}
},
{"text": "Zoom into the expression pedals and tell me how many pedals are there?"}
]
}],
"tools": [
{
"code_execution": {}
}
]
}'
채팅에서 코드 실행 사용
채팅의 일부로 코드 실행을 사용할 수 있습니다.
Python
from google import genai
from google.genai import types
client = genai.Client()
chat = client.chats.create(
model="gemini-3.5-flash",
config=types.GenerateContentConfig(
tools=[types.Tool(code_execution=types.ToolCodeExecution)]
),
)
response = chat.send_message("I have a math question for you.")
print(response.text)
response = chat.send_message(
"What is the sum of the first 50 prime numbers? "
"Generate and run code for the calculation, and make sure you get all 50."
)
for part in response.candidates[0].content.parts:
if part.text is not None:
print(part.text)
if part.executable_code is not None:
print(part.executable_code.code)
if part.code_execution_result is not None:
print(part.code_execution_result.output)
JavaScript
import {GoogleGenAI} from "@google/genai";
const ai = new GoogleGenAI({});
const chat = ai.chats.create({
model: "gemini-3.5-flash",
history: [
{
role: "user",
parts: [{ text: "I have a math question for you:" }],
},
{
role: "model",
parts: [{ text: "Great! I'm ready for your math question. Please ask away." }],
},
],
config: {
tools: [{codeExecution:{}}],
}
});
const response = await chat.sendMessage({
message: "What is the sum of the first 50 prime numbers? " +
"Generate and run code for the calculation, and make sure you get all 50."
});
console.log("Chat response:", response.text);
Go
package main
import (
"context"
"fmt"
"os"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
config := &genai.GenerateContentConfig{
Tools: []*genai.Tool{
{CodeExecution: &genai.ToolCodeExecution{}},
},
}
chat, _ := client.Chats.Create(
ctx,
"gemini-3.5-flash",
config,
nil,
)
result, _ := chat.SendMessage(
ctx,
genai.Part{Text: "What is the sum of the first 50 prime numbers? " +
"Generate and run code for the calculation, and " +
"make sure you get all 50.",
},
)
fmt.Println(result.Text())
fmt.Println(result.ExecutableCode())
fmt.Println(result.CodeExecutionResult())
}
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"tools": [{"code_execution": {}}],
"contents": [
{
"role": "user",
"parts": [{
"text": "Write code to print \"Hello world!\" and execute it"
}]
},{
"role": "model",
"parts": [
{
"executable_code": {
"id": "a1b2c3d4",
"language": "PYTHON",
"code": "\nprint(\"hello world!\")\n"
}
"thought_signature": "..."
},
{
"code_execution_result": {
"id": "a1b2c3d4",
"outcome": "OUTCOME_OK",
"output": "hello world!\n"
}
},
{
"text": "I have printed \"hello world!\" using the provided python code block. \n",
"thought_signature": "..."
}
],
},{
"role": "user",
"parts": [{
"text": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50."
}]
}
]
}'
입력/출력 (I/O)
코드 실행은 파일 입력과 그래프 출력을 지원합니다. 이러한 입력 및 출력 기능을 사용하면 CSV 파일과 텍스트 파일을 업로드하고 파일에 대해 질문하고 응답의 일부로 Matplotlib 그래프를 생성할 수 있습니다. 출력 파일은 응답에 인라인 이미지로 반환됩니다.
I/O 가격 책정
코드 실행 I/O를 사용하는 경우 입력 토큰과 출력 토큰에 대해 요금이 청구됩니다.
입력 토큰:
- 사용자 프롬프트
출력 토큰:
- 모델에서 생성된 코드
- 코드 환경의 코드 실행 출력
- 사고 토큰
- 모델에서 생성된 요약
I/O 세부정보
코드 실행 I/O를 사용할 때는 다음 기술 세부정보에 유의하세요.
- 코드 환경의 최대 런타임은 30초입니다.
- 코드 환경에서 오류가 발생하면 모델이 코드 출력을 다시 생성할 수 있습니다. 이 작업은 최대 5번까지 실행될 수 있습니다.
- 최대 파일 입력 크기는 모델 토큰 창에 의해 제한됩니다. AI Studio에서 최대 입력 파일 크기는 100만 토큰입니다 (지원되는 입력 유형의 텍스트 파일의 경우 약 2MB). 너무 큰 파일을 업로드하면 AI Studio에서 파일을 전송할 수 없습니다.
- 코드 실행은 텍스트 파일 및 CSV 파일에서 가장 잘 작동합니다.
- 입력 파일은
part.inlineData또는part.fileData(Files API를 통해 업로드됨)로 전달될 수 있으며 출력 파일은 항상part.inlineData로 반환됩니다.
결제
Gemini API에서 코드 실행을 사용 설정하는 데에는 추가 비용이 발생하지 않습니다. 사용 중인 Gemini 모델에 따라 입력 및 출력 토큰의 현재 요율로 비용이 청구됩니다.
코드 실행의 청구에 대해 몇 가지 중요한 사항은 다음과 같습니다.
- 모델에 전달하는 입력 토큰에 대해서는 비용이 한 번만 청구되며 모델에서 사용자에게 반환된 최종 출력 토큰에 대해서는 비용이 청구됩니다.
- 생성된 코드를 나타내는 토큰은 출력 토큰으로 집계됩니다. 생성된 코드에는 텍스트 및 멀티모달 출력(예: 이미지)이 포함될 수 있습니다.
- 코드 실행 결과도 출력 토큰으로 집계됩니다.
결제 모델은 다음 다이어그램에 나와 있습니다.
- 사용 중인 Gemini 모델에 따라 입력 및 출력 토큰의 현재 요율로 비용이 청구됩니다.
- 응답을 생성할 때 Gemini에 코드 실행이 사용되는 경우 원본 프롬프트, 생성된 코드, 실행된 코드 결과가 중간 토큰 라벨로 표시되고 입력 토큰 으로 청구됩니다.
- 그러면 Gemini는 요약을 생성하고 생성된 코드, 실행된 코드의 결과, 최종 요약을 반환합니다. 이러한 항목은 출력 토큰 으로 청구됩니다.
- Gemini API에는 API 응답에 중간 토큰 수가 포함되어 있으므로 초기 프롬프트 외에 추가 입력 토큰이 표시되는 이유를 알 수 있습니다.
제한사항
- 모델은 코드를 생성 및 실행할 수만 있습니다. 미디어 파일과 같은 다른 아티팩트는 반환할 수 없습니다.
- 일부 경우에 코드 실행을 사용 설정하면 모델 출력의 다른 영역 (예: 스토리 작성)에서 성능이 저하될 수 있습니다.
- 코드 실행을 성공적으로 사용하는 기능은 모델마다 약간 다릅니다.
지원되는 도구 조합
코드 실행 도구를 Google 검색을 사용한 그라운딩과 결합하여 더 복잡한 사용 사례를 지원할 수 있습니다.
Gemini 3 모델은 기본 제공 도구 (예: 코드 실행)와 커스텀 도구 (함수 호출)의 결합을 지원합니다. 도구 조합이 작동하려면 id 및 thought_signature 필드를 다시 전달해야 합니다. 도구 조합
페이지에서 자세히 알아보세요.
지원되는 라이브러리
코드 실행 환경에는 다음 라이브러리가 포함됩니다.
- attrs
- 체스
- contourpy
- fpdf
- geopandas
- imageio
- jinja2
- joblib
- jsonschema
- jsonschema-specifications
- lxml
- matplotlib
- mpmath
- numpy
- opencv-python
- openpyxl
- 패키징
- pandas
- pillow
- protobuf
- pylatex
- pyparsing
- PyPDF2
- python-dateutil
- python-docx
- python-pptx
- reportlab
- scikit-learn
- scipy
- seaborn
- 육
- striprtf
- sympy
- tabulate
- tensorflow
- toolz
- xlrd
사용자의 고유 라이브러리는 설치할 수 없습니다.
다음 단계
- 코드 실행 Colab을 사용해 보세요.
- 다른 Gemini API 도구에 대해 알아보세요.