Gemini API 코드 실행
Gemini API 코드 실행 (Code Execution)
Gemini API는 모델이 Python 코드를 생성·실행하게 하는 코드 실행 도구를 제공해요. 모델은 코드 실행 결과에서 반복적으로 학습해 최종 출력에 도달할 수 있습니다. 코드 기반 추론이 유리한 애플리케이션을 만들 때 코드 실행을 사용할 수 있어요. 예를 들어 방정식을 풀거나 텍스트를 처리할 수 있고, 코드 실행 환경에 포함된 라이브러리로 더 특화된 작업도 할 수 있어요.
출처: 문서
본문
Gemini는 Python에서만 코드를 실행할 수 있어요. 다른 언어로 코드를 생성하라고 요청할 수는 있지만, 모델이 코드 실행 도구로 그 코드를 실행할 수는 없어요.
코드 실행 활성화
코드 실행을 활성화하려면 모델에 코드 실행 도구를 구성하세요. 그러면 모델이 코드를 생성하고 실행할 수 있어요.
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.8-flash",
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.",
tools=[{"type": "code_execution"}]
)
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
elif step.type == "code_execution_call":
print(step.arguments.code)
elif step.type == "code_execution_result":
print(step.result)
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3.8-flash",
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.",
tools: [{ type: "code_execution" }]
});
for (const step of interaction.steps) {
if (step.type === "model_output") {
for (const contentBlock of step.content) {
if (contentBlock.type === "text") {
console.log(contentBlock.text);
}
}
} else if (step.type === "code_execution_call") {
console.log(step.arguments.code);
} else if (step.type === "code_execution_result") {
console.log(step.result);
}
}
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;
import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model("gemini-3.8-flash")
.input(
InteractionsInput.of(
"What is the sum of the first 50 prime numbers? "
+ "Generate and run code for the calculation, and make sure you get all 50."))
.tools(Arrays.asList(CodeExecution.builder().build()))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
for (Step step : interaction.steps().orElse(Collections.emptyList())) {
if (step instanceof ModelOutputStep) {
ModelOutputStep outputStep = (ModelOutputStep) step;
for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {
if (contentBlock instanceof TextContent) {
System.out.println(((TextContent) contentBlock).text().orElse(""));
}
}
} else if (step instanceof CodeExecutionCallStep) {
CodeExecutionCallStep callStep = (CodeExecutionCallStep) step;
callStep.arguments().ifPresent(args -> System.out.println(args.code().orElse("")));
} else if (step instanceof CodeExecutionResultStep) {
CodeExecutionResultStep resultStep = (CodeExecutionResultStep) step;
System.out.println(resultStep.result().orElse(""));
}
}
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
Input: interactions.NewInteractionsInput(
"What is the sum of the first 50 prime numbers? " +
"Generate and run code for the calculation, and make sure you get all 50.",
),
Tools: []interactions.Tool{
interactions.NewTool(interactions.CodeExecution{}),
},
}),
})
if err != nil {
log.Fatal(err)
}
for _, step := range res.Interaction.Steps {
if outStep := step.ModelOutputStep; outStep != nil {
for _, contentBlock := range outStep.Content {
if textContent := contentBlock.TextContent; textContent != nil {
fmt.Println(textContent.GetText())
}
}
} else if callStep := step.CodeExecutionCallStep; callStep != nil {
if code := callStep.Arguments.GetCode(); code != nil {
fmt.Println(*code)
}
} else if resultStep := step.CodeExecutionResultStep; resultStep != nil {
fmt.Println(resultStep.GetResult())
}
}
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.8-flash",
"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.",
"tools": [{"type": "code_execution"}]
}'
출력은 읽기 쉽게 서식이 정리된 다음 형태일 수 있어요.
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: 모델이 생성한 인라인 텍스트code_execution_call: 실행하도록 의도된 모델이 생성한 코드code_execution_result: 실행 가능한 코드의 결과
이미지가 있는 코드 실행 (Gemini 3)
Gemini 3 Flash 모델은 이제 Python 코드를 작성·실행해 이미지를 능동적으로 조작하고 검사할 수 있어요.
사용 사례
- 확대 및 검사 (Zoom and inspect): 모델은 세부 사항이 너무 작다고 암묵적으로 감지하고(예: 먼 계기판 읽기) 더 높은 해상도로 해당 영역을 자르고 다시 조사하는 코드를 작성해요.
- 시각적 수학 (Visual math): 모델은 코드로 다단계 계산을 실행할 수 있어요(예: 영수증의 라인 항목 합산).
- 이미지 주석 (Image annotation): 모델은 질문에 답하기 위해 이미지에 주석을 달 수 있어요(예: 관계를 보여주는 화살표 그리기).
참고: 모델은 작은 세부 사항에 대한 확대는 자동으로 처리하지만, "기어 개수를 세는 코드를 작성해줘"나 "이 이미지를 똑바로 세우도록 회전해줘" 같은 다른 작업에는 코드를 사용하도록 명시적으로 프롬프트해야 해요.
이미지가 있는 코드 실행 활성화
이미지가 있는 코드 실행은 Gemini 3 Flash에서 공식 지원돼요. 코드 실행을 도구로 활성화하고 Thinking도 켜면 이 동작을 활성화할 수 있어요.
from google import genai
import requests
import base64
from PIL import Image
import io
image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{"type": "image", "data": base64.b64encode(image_bytes).decode('utf-8'), "mime_type": "image/jpeg"},
{"type": "text", "text": "Zoom into the expression pedals and tell me how many pedals are there?"}
],
tools=[{"type": "code_execution"}]
)
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
elif content_block.type == "image":
img = Image.open(io.BytesIO(base64.b64decode(content_block.data)))
img.show() # or: img.save("output_image.jpg")
elif step.type == "code_execution_call":
print(step.arguments.code)
elif step.type == "code_execution_result":
print(step.result)
import { GoogleGenAI } from "@google/genai";
async function main() {
const client = new GoogleGenAI({});
const imageUrl = "https://goo.gle/instrument-img";
const response = await fetch(imageUrl);
const imageArrayBuffer = await response.arrayBuffer();
const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');
const interaction = await client.interactions.create({
model: "gemini-3.8-flash",
input: [
{
type: "image",
data: base64ImageData,
mime_type: "image/jpeg"
},
{ type: "text", text: "Zoom into the expression pedals and tell me how many pedals are there?" }
],
tools: [{ type: "code_execution" }]
});
for (const step of interaction.steps) {
if (step.type === "model_output") {
for (const contentBlock of step.content) {
if (contentBlock.type === "text") {
console.log("Text:", contentBlock.text);
}
}
} else if (step.type === "code_execution_call") {
console.log(`\nGenerated Code:\n`, step.arguments.code);
} else if (step.type === "code_execution_result") {
console.log(`\nExecution Output:\n`, step.result);
}
}
}
main();
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;
import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.io.InputStream;
import java.net.URI;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
String imageUrl = "https://goo.gle/instrument-img";
byte[] imageBytes;
try (InputStream in = URI.create(imageUrl).toURL().openStream()) {
imageBytes = in.readAllBytes();
}
String base64Image = Base64.getEncoder().encodeToString(imageBytes);
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model("gemini-3.8-flash")
.input(
InteractionsInput.ofContent(
Arrays.asList(
ImageContent.builder()
.data(base64Image)
.mimeType(ImageContentMimeType.IMAGE_JPEG)
.build(),
TextContent.builder()
.text(
"Zoom into the expression pedals and tell me how many pedals are there?")
.build())))
.tools(Arrays.asList(CodeExecution.builder().build()))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
for (Step step : interaction.steps().orElse(Collections.emptyList())) {
if (step instanceof ModelOutputStep) {
ModelOutputStep outputStep = (ModelOutputStep) step;
for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {
if (contentBlock instanceof TextContent) {
System.out.println(((TextContent) contentBlock).text().orElse(""));
} else if (contentBlock instanceof ImageContent) {
ImageContent imgContent = (ImageContent) contentBlock;
if (imgContent.data().isPresent()) {
byte[] decoded = Base64.getDecoder().decode(imgContent.data().get());
Files.write(Paths.get("output_image.jpg"), decoded);
}
}
}
} else if (step instanceof CodeExecutionCallStep) {
CodeExecutionCallStep callStep = (CodeExecutionCallStep) step;
callStep.arguments().ifPresent(args -> System.out.println(args.code().orElse("")));
} else if (step instanceof CodeExecutionResultStep) {
CodeExecutionResultStep resultStep = (CodeExecutionResultStep) step;
System.out.println(resultStep.result().orElse(""));
}
}
package main
import (
"context"
"encoding/base64"
"fmt"
"io"
"log"
"net/http"
"os"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
imageURL := "https://goo.gle/instrument-img"
httpResp, err := http.Get(imageURL)
if err != nil {
log.Fatal(err)
}
defer httpResp.Body.Close()
imageBytes, err := io.ReadAll(httpResp.Body)
if err != nil {
log.Fatal(err)
}
base64Image := base64.StdEncoding.EncodeToString(imageBytes)
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
Input: interactions.NewInteractionsInput([]interactions.Content{
interactions.NewContent(interactions.ImageContent{
Data: genai.Ptr(base64Image),
MimeType: interactions.ImageContentMimeType("image/jpeg").ToPointer(),
}),
interactions.NewContent(interactions.TextContent{
Text: "Zoom into the expression pedals and tell me how many pedals are there?",
}),
}),
Tools: []interactions.Tool{
interactions.NewTool(interactions.CodeExecution{}),
},
}),
})
if err != nil {
log.Fatal(err)
}
for _, step := range res.Interaction.Steps {
if outStep := step.ModelOutputStep; outStep != nil {
for _, contentBlock := range outStep.Content {
if textContent := contentBlock.TextContent; textContent != nil {
fmt.Println(textContent.GetText())
} else if imgContent := contentBlock.ImageContent; imgContent != nil && imgContent.Data != nil {
decoded, err := base64.StdEncoding.DecodeString(*imgContent.Data)
if err == nil {
_ = os.WriteFile("output_image.jpg", decoded, 0644)
}
}
}
} else if callStep := step.CodeExecutionCallStep; callStep != nil {
if code := callStep.Arguments.GetCode(); code != nil {
fmt.Println(*code)
}
} else if resultStep := step.CodeExecutionResultStep; resultStep != nil {
fmt.Println(resultStep.GetResult())
}
}
}
IMG_URL="https://goo.gle/instrument-img"
MODEL="gemini-3.8-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
# Use jq to create the JSON payload to avoid "Argument list too long" error with large base64 strings
echo -n "$IMAGE_B64" > image_b64.txt
jq -n \
--rawfile b64 image_b64.txt \
--arg mime "$MIME_TYPE" \
'{
model: "gemini-3.8-flash",
input: [
{type: "image", data: $b64, mime_type: $mime},
{type: "text", text: "Zoom into the expression pedals and tell me how many pedals are there?"}
],
tools: [{type: "code_execution"}]
}' > payload.json
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d @payload.json
다중 턴 상호작용에서 코드 실행 사용하기
previous_interaction_id를 사용해 다중 턴 대화의 일부로 코드 실행을 사용할 수도 있어요.
from google import genai
client = genai.Client()
interaction1 = client.interactions.create(
model="gemini-3.8-flash",
input="I have a math question for you.",
tools=[{"type": "code_execution"}]
)
print(interaction1.output_text)
interaction2 = client.interactions.create(
model="gemini-3.8-flash",
previous_interaction_id=interaction1.id,
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.",
tools=[{"type": "code_execution"}]
)
for step in interaction2.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
elif step.type == "code_execution_call":
print(step.arguments.code)
elif step.type == "code_execution_result":
print(step.result)
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const interaction1 = await client.interactions.create({
model: "gemini-3.8-flash",
input: "I have a math question for you.",
tools: [{ type: "code_execution" }]
});
console.log(interaction1.output_text);
const interaction2 = await client.interactions.create({
model: "gemini-3.8-flash",
previous_interaction_id: interaction1.id,
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.",
tools: [{ type: "code_execution" }]
});
for (const step of interaction2.steps) {
if (step.type === "model_output") {
for (const contentBlock of step.content) {
if (contentBlock.type === "text") {
console.log(contentBlock.text);
}
}
} else if (step.type === "code_execution_call") {
console.log(step.arguments.code);
} else if (step.type === "code_execution_result") {
console.log(step.result);
}
}
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CodeExecution;
import com.google.genai.gaos.models.interactions.CodeExecutionCallStep;
import com.google.genai.gaos.models.interactions.CodeExecutionResultStep;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.Collections;
Client client = new Client();
CreateModelInteraction params1 =
CreateModelInteraction.builder()
.model("gemini-3.8-flash")
.input(InteractionsInput.of("I have a math question for you."))
.tools(Arrays.asList(CodeExecution.builder().build()))
.build();
Interaction interaction1 =
client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();
System.out.println(interaction1.outputText().orElse(""));
CreateModelInteraction params2 =
CreateModelInteraction.builder()
.model("gemini-3.8-flash")
.previousInteractionId(interaction1.id().get())
.input(
InteractionsInput.of(
"What is the sum of the first 50 prime numbers? "
+ "Generate and run code for the calculation, and make sure you get all 50."))
.tools(Arrays.asList(CodeExecution.builder().build()))
.build();
Interaction interaction2 =
client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();
for (Step step : interaction2.steps().orElse(Collections.emptyList())) {
if (step instanceof ModelOutputStep) {
ModelOutputStep outputStep = (ModelOutputStep) step;
for (Content contentBlock : outputStep.content().orElse(Collections.emptyList())) {
if (contentBlock instanceof TextContent) {
System.out.println(((TextContent) contentBlock).text().orElse(""));
}
}
} else if (step instanceof CodeExecutionCallStep) {
CodeExecutionCallStep callStep = (CodeExecutionCallStep) step;
callStep.arguments().ifPresent(args -> System.out.println(args.code().orElse("")));
} else if (step instanceof CodeExecutionResultStep) {
CodeExecutionResultStep resultStep = (CodeExecutionResultStep) step;
System.out.println(resultStep.result().orElse(""));
}
}
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
Input: interactions.NewInteractionsInput("I have a math question for you."),
Tools: []interactions.Tool{
interactions.NewTool(interactions.CodeExecution{}),
},
}),
})
if err != nil {
log.Fatal(err)
}
if res1.Interaction.OutputText != nil {
fmt.Println(*res1.Interaction.OutputText)
}
res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
PreviousInteractionID: res1.Interaction.ID,
Input: interactions.NewInteractionsInput(
"What is the sum of the first 50 prime numbers? " +
"Generate and run code for the calculation, and make sure you get all 50.",
),
Tools: []interactions.Tool{
interactions.NewTool(interactions.CodeExecution{}),
},
}),
})
if err != nil {
log.Fatal(err)
}
for _, step := range res2.Interaction.Steps {
if outStep := step.ModelOutputStep; outStep != nil {
for _, contentBlock := range outStep.Content {
if textContent := contentBlock.TextContent; textContent != nil {
fmt.Println(textContent.GetText())
}
}
} else if callStep := step.CodeExecutionCallStep; callStep != nil {
if code := callStep.Arguments.GetCode(); code != nil {
fmt.Println(*code)
}
} else if resultStep := step.CodeExecutionResultStep; resultStep != nil {
fmt.Println(resultStep.GetResult())
}
}
}
# First turn
RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.8-flash",
"input": "I have a math question for you.",
"tools": [{"type": "code_execution"}]
}')
INTERACTION_ID=$(echo $RESPONSE1 | jq -r '.id')
# Second turn with previous_interaction_id
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.8-flash",
"previous_interaction_id": "'"$INTERACTION_ID"'",
"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.",
"tools": [{"type": "code_execution"}]
}'
입력/출력 (I/O)
Gemini 3.5 Flash 같은 현재 Gemini 모델에서 코드 실행은 파일 입력과 그래프 출력을 지원해요. 이러한 입력·출력 기능을 사용하면 CSV·텍스트 파일을 업로드하고, 파일에 대해 질문하고, 응답의 일부로 Matplotlib 그래프를 생성하게 할 수 있어요. 출력 파일은 응답에서 인라인 이미지로 반환됩니다.
I/O 가격
코드 실행 I/O를 사용할 때 입력 토큰과 출력 토큰 비용이 청구돼요.
입력 토큰:
- 사용자 프롬프트
출력 토큰:
- 모델이 생성한 코드
- 코드 환경에서의 코드 실행 출력
- Thinking 토큰
- 모델이 생성한 요약
I/O 세부 사항
코드 실행 I/O로 작업할 때 다음 기술적 세부 사항을 알아두세요.
- 코드 환경의 최대 실행 시간은 30초예요.
- 코드 환경이 오류를 생성하면 모델이 코드 출력을 재생성하기로 결정할 수 있어요. 이는 최대 5회까지 일어날 수 있어요.
- 최대 파일 입력 크기는 모델 토큰 윈도우에 의해 제한돼요. 모델의 최대 컨텍스트 윈도우를 초과하는 파일을 업로드하면 API가 오류를 반환해요.
- 코드 실행은 텍스트와 CSV 파일에서 가장 잘 동작해요.
- 입력 파일은 인라인 데이터로 전달하거나 Files API로 업로드할 수 있고, 출력 파일은 항상 인라인 데이터로 반환돼요.
과금 (Billing)
Gemini API에서 코드 실행을 활성화하는 데 추가 비용은 없어요. 사용 중인 Gemini 모델에 따라 현재 입력·출력 토큰 요율로 과금됩니다.
코드 실행 과금에 대해 알아둘 몇 가지가 더 있어요.
- 모델에 전달하는 입력 토큰에 대해 한 번만 과금되고, 모델이 반환하는 최종 출력 토큰에 대해 과금돼요.
- 생성된 코드를 나타내는 토큰은 출력 토큰으로 계산돼요. 생성된 코드는 이미지 같은 텍스트와 멀티모달 출력을 포함할 수 있어요.
- 코드 실행 결과도 출력 토큰으로 계산돼요.
다음 다이어그램이 과금 모델을 보여줘요.
- 사용 중인 Gemini 모델에 따라 현재 입력·출력 토큰 요율로 과금돼요.
- Gemini가 응답을 생성할 때 코드 실행을 사용하면, 원래 프롬프트·생성된 코드·실행된 코드 결과가 중간 토큰(intermediate tokens) 으로 표시되고 입력 토큰으로 과금돼요.
- 그런 다음 Gemini는 요약을 생성하고 생성된 코드·실행된 코드 결과·최종 요약을 반환해요. 이것들은 출력 토큰으로 과금돼요.
- Gemini API는 API 응답에 중간 토큰 수를 포함해, 초기 프롬프트를 넘어 추가 입력 토큰이 생기는 이유를 알려줘요.
제한 사항
- 모델은 코드를 생성·실행할 수만 있어요. 미디어 파일 같은 다른 산출물은 반환할 수 없어요.
- 어떤 경우에는 코드 실행을 활성화하면 모델 출력의 다른 영역(예: 이야기 쓰기)에서 성능이 저하될 수 있어요.
- 서로 다른 모델이 코드 실행을 성공적으로 사용하는 능력에는 차이가 있어요.
지원되는 도구 조합
코드 실행 도구는 Google Search 접지와 결합해 더 복잡한 사용 사례를 지원할 수 있어요.
Gemini 3 모델은 내장 도구(Code Execution 같은)와 커스텀 도구(함수 호출)를 결합하는 것을 지원해요.
지원 라이브러리
코드 실행 환경은 다음 라이브러리를 포함해요.
- attrs
- chess
- contourpy
- fpdf
- geopandas
- imageio
- jinja2
- joblib
- jsonschema
- jsonschema-specifications
- lxml
- matplotlib
- mpmath
- numpy
- opencv-python
- openpyxl
- packaging
- pandas
- pillow
- protobuf
- pylatex
- pyparsing
- PyPDF2
- python-dateutil
- python-docx
- python-pptx
- reportlab
- scikit-learn
- scipy
- seaborn
- six
- striprtf
- sympy
- tabulate
- tensorflow
- toolz
- xlrd
자신만의 라이브러리를 설치할 수는 없어요.
참고: 코드 실행으로 그래프를 렌더링할 때는 matplotlib만 지원돼요.
다음 단계
- Interactions API Quickstart 시도하기.
- 다른 Gemini API 도구 알아보기:
더 알아보기 (Learn more)
코드 실행 도구는 Gemini가 정확한 계산·산술·코드 기반 추론을 하게 하는 강력한 도구예요. 이미지를 다루려면 Thinking과 함께 활성화하면 확대·주석 같은 고급 동작이 가능해요. 함수 호출이나 Google Search 접지와 결합하는 방법은 각 문서를 이어서 보면 좋아요.