Gemini-Modelle sind von Grund auf multimodal, sodass sie leistungsstarke, integrierte Funktionen zur Bilderkennung bieten. So können Sie Aufgaben wie Bildunterschriften, Klassifizierung, visuelle Fragen und Antworten, Objekterkennung und Segmentierung ausführen, ohne spezielle ML-Modelle zu trainieren.
In diesem Leitfaden werden Bildeingaben und gängige Aufgaben zum Erfassen von Bildern behandelt. Informationen zu anderen Modalitäten finden Sie in den Anleitungen für Videos und Audio.
Bilder an Gemini übergeben
Sie haben zwei Möglichkeiten, Bilder als Eingabe für Gemini bereitzustellen:
- Inline-Bilddaten übergeben: Ideal für kleinere Dateien (Gesamtgröße der Anfrage unter 20 MB, einschließlich Prompts).
- Bilder mit der File API hochladen: Empfohlen für größere Dateien oder für die Wiederverwendung von Bildern in mehreren Anfragen.
Inline-Bilddaten übergeben
Sie können Inline-Bilddaten in der Anfrage an generateContent
übergeben. Sie können Bilddaten als Base64-codierte Strings oder durch direktes Lesen lokaler Dateien bereitstellen (je nach Sprache).
Im folgenden Beispiel wird gezeigt, wie ein Bild aus einer lokalen Datei gelesen und zur Verarbeitung an die generateContent
API übergeben wird.
Python
from google.genai import types
with open('path/to/small-sample.jpg', 'rb') as f:
image_bytes = f.read()
response = client.models.generate_content(
model='gemini-2.0-flash',
contents=[
types.Part.from_bytes(
data=image_bytes,
mime_type='image/jpeg',
),
'Caption this image.'
]
)
print(response.text)
JavaScript
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
const base64ImageFile = fs.readFileSync("path/to/small-sample.jpg", {
encoding: "base64",
});
const contents = [
{
inlineData: {
mimeType: "image/jpeg",
data: base64ImageFile,
},
},
{ text: "Caption this image." },
];
const response = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: contents,
});
console.log(response.text);
Ok
bytes, _ := os.ReadFile("path/to/small-sample.jpg")
parts := []*genai.Part{
genai.NewPartFromBytes(bytes, "image/jpeg"),
genai.NewPartFromText("Caption this image."),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
ctx,
"gemini-2.0-flash",
contents,
nil,
)
fmt.Println(result.Text())
REST
IMG_PATH="/path/to/your/image1.jpg"
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{
"inline_data": {
"mime_type":"image/jpeg",
"data": "'"$(base64 $B64FLAGS $IMG_PATH)"'"
}
},
{"text": "Caption this image."},
]
}]
}' 2> /dev/null
Sie können auch ein Bild von einer URL abrufen, in Bytes konvertieren und an generateContent
übergeben, wie in den folgenden Beispielen gezeigt.
Python
from google import genai
from google.genai import types
import requests
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"
)
client = genai.Client(api_key="GOOGLE_API_KEY")
response = client.models.generate_content(
model="gemini-2.0-flash-exp",
contents=["What is this image?", image],
)
print(response.text)
JavaScript
import { GoogleGenAI } from "@google/genai";
async function main() {
const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY });
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 result = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: [
{
inlineData: {
mimeType: 'image/jpeg',
data: base64ImageData,
},
},
{ text: "Caption this image." }
],
});
console.log(result.text);
}
main();
Ok
package main
import (
"context"
"fmt"
"os"
"io"
"net/http"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, _ := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GOOGLE_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
// Download the image.
imageResp, _ := http.Get("https://goo.gle/instrument-img")
imageBytes, _ := io.ReadAll(imageResp.Body)
parts := []*genai.Part{
genai.NewPartFromBytes(imageBytes, "image/jpeg"),
genai.NewPartFromText("Caption this image."),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
ctx,
"gemini-2.0-flash",
contents,
nil,
)
fmt.Println(result.Text())
}
REST
IMG_URL="https://goo.gle/instrument-img"
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
# Check for macOS
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/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{
"inline_data": {
"mime_type":"'"$MIME_TYPE"'",
"data": "'"$IMAGE_B64"'"
}
},
{"text": "Caption this image."}
]
}]
}' 2> /dev/null
Bilder mit der File API hochladen
Verwenden Sie die Files API für große Dateien oder wenn Sie dieselbe Bilddatei mehrmals verwenden möchten. Im folgenden Code wird eine Bilddatei hochgeladen und dann in einem Aufruf von generateContent
verwendet. Weitere Informationen und Beispiele finden Sie im Leitfaden zur Files API.
Python
from google import genai
client = genai.Client(api_key="GOOGLE_API_KEY")
my_file = client.files.upload(file="path/to/sample.jpg")
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=[my_file, "Caption this image."],
)
print(response.text)
JavaScript
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
async function main() {
const myfile = await ai.files.upload({
file: "path/to/sample.jpg",
config: { mimeType: "image/jpeg" },
});
const response = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: createUserContent([
createPartFromUri(myfile.uri, myfile.mimeType),
"Caption this image.",
]),
});
console.log(response.text);
}
await main();
Ok
package main
import (
"context"
"fmt"
"os"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, _ := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: os.Getenv("GOOGLE_API_KEY"),
Backend: genai.BackendGeminiAPI,
})
uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/sample.jpg", nil)
parts := []*genai.Part{
genai.NewPartFromText("Caption this image."),
genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
ctx,
"gemini-2.0-flash",
contents,
nil,
)
fmt.Println(result.Text())
}
REST
IMAGE_PATH="path/to/sample.jpg"
MIME_TYPE=$(file -b --mime-type "${IMAGE_PATH}")
NUM_BYTES=$(wc -c < "${IMAGE_PATH}")
DISPLAY_NAME=IMAGE
tmp_header_file=upload-header.tmp
# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
-D upload-header.tmp \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null
upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"
# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${IMAGE_PATH}" 2> /dev/null > file_info.json
file_uri=$(jq -r ".file.uri" file_info.json)
echo file_uri=$file_uri
# Now generate content using that file
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"file_data":{"mime_type": "'"${MIME_TYPE}"'", "file_uri": "'"${file_uri}"'"}},
{"text": "Caption this image."}]
}]
}' 2> /dev/null > response.json
cat response.json
echo
jq ".candidates[].content.parts[].text" response.json
Prompts mit mehreren Bildern
Sie können mehrere Bilder in einem einzigen Prompt angeben, indem Sie mehrere BildPart
-Objekte in das contents
-Array einfügen. Das können Inline-Daten (lokale Dateien oder URLs) und File API-Referenzen sein.
Python
from google import genai
from google.genai import types
client = genai.Client(api_key="GOOGLE_API_KEY")
# Upload the first image
image1_path = "path/to/image1.jpg"
uploaded_file = client.files.upload(file=image1_path)
# Prepare the second image as inline data
image2_path = "path/to/image2.png"
with open(image2_path, 'rb') as f:
img2_bytes = f.read()
# Create the prompt with text and multiple images
response = client.models.generate_content(
model="gemini-2.0-flash",
contents=[
"What is different between these two images?",
uploaded_file, # Use the uploaded file reference
types.Part.from_bytes(
data=img2_bytes,
mime_type='image/png'
)
]
)
print(response.text)
JavaScript
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
import * as fs from "node:fs";
const ai = new GoogleGenAI({ apiKey: "GOOGLE_API_KEY" });
async function main() {
// Upload the first image
const image1_path = "path/to/image1.jpg";
const uploadedFile = await ai.files.upload({
file: image1_path,
config: { mimeType: "image/jpeg" },
});
// Prepare the second image as inline data
const image2_path = "path/to/image2.png";
const base64Image2File = fs.readFileSync(image2_path, {
encoding: "base64",
});
// Create the prompt with text and multiple images
const response = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: createUserContent([
"What is different between these two images?",
createPartFromUri(uploadedFile.uri, uploadedFile.mimeType),
{
inlineData: {
mimeType: "image/png",
data: base64Image2File,
},
},
]),
});
console.log(response.text);
}
await main();
Ok
// Upload the first image
image1Path := "path/to/image1.jpg"
uploadedFile, _ := client.Files.UploadFromPath(ctx, image1Path, nil)
// Prepare the second image as inline data
image2Path := "path/to/image2.jpeg"
imgBytes, _ := os.ReadFile(image2Path)
parts := []*genai.Part{
genai.NewPartFromText("What is different between these two images?"),
genai.NewPartFromBytes(imgBytes, "image/jpeg"),
genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
ctx,
"gemini-2.0-flash",
contents,
nil,
)
fmt.Println(result.Text())
REST
# Upload the first image
IMAGE1_PATH="path/to/image1.jpg"
MIME1_TYPE=$(file -b --mime-type "${IMAGE1_PATH}")
NUM1_BYTES=$(wc -c < "${IMAGE1_PATH}")
DISPLAY_NAME1=IMAGE1
tmp_header_file1=upload-header1.tmp
curl "https://generativelanguage.googleapis.com/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
-D upload-header1.tmp \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM1_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME1_TYPE}" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME1}'}}" 2> /dev/null
upload_url1=$(grep -i "x-goog-upload-url: " "${tmp_header_file1}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file1}"
curl "${upload_url1}" \
-H "Content-Length: ${NUM1_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${IMAGE1_PATH}" 2> /dev/null > file_info1.json
file1_uri=$(jq ".file.uri" file_info1.json)
echo file1_uri=$file1_uri
# Prepare the second image (inline)
IMAGE2_PATH="path/to/image2.png"
MIME2_TYPE=$(file -b --mime-type "${IMAGE2_PATH}")
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
IMAGE2_BASE64=$(base64 $B64FLAGS $IMAGE2_PATH)
# Now generate content using both images
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"text": "What is different between these two images?"},
{"file_data":{"mime_type": "'"${MIME1_TYPE}"'", "file_uri": '$file1_uri'}},
{
"inline_data": {
"mime_type":"'"${MIME2_TYPE}"'",
"data": "'"$IMAGE2_BASE64"'"
}
}
]
}]
}' 2> /dev/null > response.json
cat response.json
echo
jq ".candidates[].content.parts[].text" response.json
Objekterkennung
Ab Gemini 2.0 werden die Modelle weiter trainiert, um Objekte in einem Bild zu erkennen und ihre Begrenzungsrahmenkoordinaten zu erhalten. Die Koordinaten werden im Verhältnis zu den Bildabmessungen auf [0, 1000] skaliert. Sie müssen diese Koordinaten auf die Größe des Originalbilds skalieren.
Python
from google import genai
from google.genai import types
from PIL import Image
import json
client = genai.Client(api_key="GOOGLE_API_KEY")
prompt = "Detect the all of the prominent items in the image. The box_2d should be [ymin, xmin, ymax, xmax] normalized to 0-1000."
image = Image.open("/path/to/image.png")
config = types.GenerateContentConfig(response_mime_type="application/json")
response = client.models.generate_content(model="gemini-2.0-flash",
contents=[image, prompt],
config=config)
width, height = image.size
bounding_boxes = json.loads(response.text)
converted_bounding_boxes = []
for bounding_box in bounding_boxes:
abs_y1 = int(bounding_box["box_2d"][0]/1000 * height)
abs_x1 = int(bounding_box["box_2d"][1]/1000 * width)
abs_y2 = int(bounding_box["box_2d"][2]/1000 * height)
abs_x2 = int(bounding_box["box_2d"][3]/1000 * width)
converted_bounding_boxes.append([abs_x1, abs_y1, abs_x2, abs_y2])
print("Image size: ", width, height)
print("Bounding boxes:", converted_bounding_boxes)
Weitere Beispiele finden Sie in den folgenden Rezeptbüchern:
Bildsegmentierung
Ab Gemini 2.5 erkennen Modelle nicht nur Artikel, sondern segmentieren sie auch und stellen ihre Konturmasken bereit.
Das Modell prognostiziert eine JSON-Liste, wobei jedes Element eine Segmentierungsmaske darstellt.
Jeder Artikel hat einen Begrenzungsrahmen („box_2d
“) im Format [y0, x0, y1, x1]
mit normalisierten Koordinaten zwischen 0 und 1.000, ein Label („label
“), das das Objekt identifiziert, und schließlich die Segmentierungsmaske innerhalb des Begrenzungsrahmens als Base64-codierte PNG-Datei, die eine Wahrscheinlichkeitskarte mit Werten zwischen 0 und 255 ist.
Die Maske muss so angepasst werden, dass sie den Abmessungen des Begrenzungsrahmens entspricht. Anschließend muss sie mit dem von Ihnen festgelegten Konfidenzgrenzwert binär codiert werden (127 für die Mitte).
Python
from google import genai
from PIL import Image
import io
import os
import requests
from io import BytesIO
import dataclasses
import numpy as np
import base64
# Mask data type
@dataclasses.dataclass(frozen=True)
class SegmentationMask:
# bounding box pixel coordinates (not normalized)
y0: int # in [0..height - 1]
x0: int # in [0..width - 1]
y1: int # in [0..height - 1]
x1: int # in [0..width - 1]
mask: np.array # [img_height, img_width] with values 0..255
label: str
# Parsing JSON output
def parse_json(json_output: str):
# Parsing out the markdown fencing
lines = json_output.splitlines()
for i, line in enumerate(lines):
if line == "```json":
json_output = "\n".join(lines[i+1:]) # Remove everything before "```json"
json_output = json_output.split("```")[0] # Remove everything after the closing "```"
break # Exit the loop once "```json" is found
return json_output
# Generates a list of segmentation masks from the model output
def parse_segmentation_masks(
predicted_str: str, *, img_height: int, img_width: int
) -> list[SegmentationMask]:
items = json.loads(parse_json(predicted_str))
masks = []
for item in items:
raw_box = item["box_2d"]
abs_y0 = int(item["box_2d"][0] / 1000 * img_height)
abs_x0 = int(item["box_2d"][1] / 1000 * img_width)
abs_y1 = int(item["box_2d"][2] / 1000 * img_height)
abs_x1 = int(item["box_2d"][3] / 1000 * img_width)
if abs_y0 >= abs_y1 or abs_x0 >= abs_x1:
print("Invalid bounding box", item["box_2d"])
continue
label = item["label"]
png_str = item["mask"]
if not png_str.startswith("data:image/png;base64,"):
print("Invalid mask")
continue
png_str = png_str.removeprefix("data:image/png;base64,")
png_str = base64.b64decode(png_str)
mask = Image.open(io.BytesIO(png_str))
bbox_height = abs_y1 - abs_y0
bbox_width = abs_x1 - abs_x0
if bbox_height < 1 or bbox_width < 1:
print("Invalid bounding box")
continue
mask = mask.resize((bbox_width, bbox_height), resample=Image.Resampling.BILINEAR)
np_mask = np.zeros((img_height, img_width), dtype=np.uint8)
np_mask[abs_y0:abs_y1, abs_x0:abs_x1] = mask
masks.append(SegmentationMask(abs_y0, abs_x0, abs_y1, abs_x1, np_mask, label))
return masks
prompt = """
Give the segmentation masks for the wooden and glass items.
Output a JSON list of segmentation masks where each entry contains the 2D
bounding box in the key "box_2d", the segmentation mask in key "mask", and
the text label in the key "label". Use descriptive labels.
"""
model = "gemini-2.5-pro-preview-06-05"
image ="path/to/image.png"
# Load and resize image
im = Image.open(BytesIO(open(image, "rb").read()))
im.thumbnail([1024,1024], Image.Resampling.LANCZOS)
# Run model to find segmentation masks
response = client.models.generate_content(
model=model,
contents=[prompt, im],
config = types.GenerateContentConfig(
temperature=0.5,
)
)
# Check output
print(response.text)
# Get segmentation masks
print(parse_segmentation_masks(response.text, img_height=im.size[1], img_width=im.size[0]))
Ein detaillierteres Beispiel finden Sie im Leitfaden im Segmentierungsbeispiel.
Unterstützte Bildformate
Gemini unterstützt die folgenden MIME-Typen für Bildformate:
- PNG -
image/png
- JPEG -
image/jpeg
- WEBP –
image/webp
- HEIC –
image/heic
- HEIF –
image/heif
Einschränkungen und wichtige technische Informationen
- Dateieinschränkung: Gemini 2.5 Pro, 2.0 Flash, 1.5 Pro und 1.5 Flash unterstützen maximal 3.600 Bilddateien pro Anfrage.
- Tokenberechnung:
- Gemini 1.5 Flash und Gemini 1.5 Pro: 258 Tokens, wenn beide Abmessungen <= 384 Pixel sind. Größere Bilder werden in Kacheln unterteilt (min. 256 × 256 Pixel, max. 768 × 768 Pixel, Größe wird auf 768 × 768 Pixel geändert). Jede Kachel kostet 258 Tokens.
- Gemini 2.0 Flash und Gemini 2.5 Flash/Pro: 258 Tokens, wenn beide Abmessungen <= 384 Pixel sind. Größere Bilder werden in Kacheln mit einer Größe von 768 × 768 Pixeln unterteilt, die jeweils 258 Tokens kosten.
Tipps und Best Practices
- Prüfen Sie, ob die Bilder richtig gedreht sind.
- Verwenden Sie klare, nicht verschwommene Bilder.
- Wenn Sie ein einzelnes Bild mit Text verwenden, platzieren Sie den Textprompt nach dem Bildteil im
contents
-Array.
Nächste Schritte
In dieser Anleitung erfahren Sie, wie Sie Bilddateien hochladen und Textausgaben aus Bildinputs generieren. Weitere Informationen finden Sie in den folgenden Ressourcen:
- Files API: Hier finden Sie weitere Informationen zum Hochladen und Verwalten von Dateien für die Verwendung mit Gemini.
- Systemanweisungen: Mit Systemanweisungen können Sie das Verhalten des Modells basierend auf Ihren spezifischen Anforderungen und Anwendungsfällen steuern.
- Strategien für Prompts aus Dateien: Die Gemini API unterstützt Prompts mit Text-, Bild-, Audio- und Videodaten, auch als multimodale Prompts bezeichnet.
- Sicherheitshinweise: Manchmal liefern generative KI-Modelle unerwartete Ausgaben, z. B. ungenaue, voreingenommene oder anstößige Ausgaben. Eine Nachbearbeitung und eine menschliche Bewertung sind unerlässlich, um das Risiko von Schäden durch solche Ausgaben zu begrenzen.