Gemini Datei-API

Was macht Gemini Datei-API?

Lade Dateien für die Verwendung mit Gemini-Modellen über ausführbare Skripte hoch und verwalte sie. Unterstützt Bilder, Audio, Video, PDFs und andere Dateitypen.

Wann dieses Skill verwendet werden sollte

Verwende dieses Skill, wenn du:

• Bilder für multimodale Analysen hochladen möchtest
• Videos zur Inhaltsverarbeitung hochladen möchtest
• PDFs für die Dokumentenanalyse hochladen möchtest
• Audio für Transkription oder Verarbeitung hochladen möchtest
• Dateien für Batch-Operationen vorab hochladen möchtest
• Den Verarbeitungsstatus von Dateien überprüfen möchtest
• Hochgeladene Dateien auflisten und verwalten möchtest
• Dateien mit anderen Gemini-Skills (Text, Bild usw.) verwenden möchtest

Verfügbare Skripte

scripts/upload.py

Zweck: Dateien in die Gemini File API hochladen

Wann verwenden:

• Hochladen einer beliebigen Datei für die Gemini-Verarbeitung
• Vorbereiten von Dateien für die multimodale Generierung
• Hochladen von Dokumenten zur Analyse
• Batch-Dateivorbereitung

Wichtige Parameter:

Parameter	Beschreibung	Beispiel
path	Dateipfad (erforderlich)	image.jpg
--name, -n	Anzeigename	"mein-dokument"
--wait, -w	Auf Verarbeitung warten	Flag

Ausgabe: Dateiname, URI und Statusinformationen

Workflows

Workflow 1: Basisupload einer Datei

python scripts/upload.py image.jpg

• Am besten geeignet für: Schnelle Uploads, einfache Dateien
• Ausgabe: Dateiname und URI für die API-Nutzung
• Status: PROCESSING oder ACTIVE

Workflow 2: Upload mit benutzerdefiniertem Namen

python scripts/upload.py document.pdf --name "Quartalsbericht Q4 2026"

• Am besten geeignet für: Dateien organisieren, Uploads verfolgen
• Verwende, wenn: Der ursprüngliche Dateiname nicht aussagekräftig genug ist
• Der Anzeigename erscheint in Dateilisten

Workflow 3: Hochladen und auf Verarbeitung warten

python scripts/upload.py video.mp4 --wait

• Am besten geeignet für: Große Dateien, Videos, Audio
• Wartet, bis die Datei den Status ACTIVE erreicht
• Verwende, wenn: Du die Datei sofort nach dem Upload nutzen musst

Workflow 4: Bild für die Analyse hochladen

# 1. Bild hochladen
python scripts/upload.py photo.png --name "produktfoto"

# 2. Mit gemini-text zur Analyse verwenden
python skills/gemini-text/scripts/generate.py "Beschreibe dieses Bild" --image photo.png

• Am besten geeignet für: Bildanalyse, Beschriftung, visuelle Fragen & Antworten
• Kombiniert mit: gemini-text für multimodale Verarbeitung

Workflow 5: PDF zur Inhaltsanalyse hochladen

# 1. PDF hochladen
python scripts/upload.py research-paper.pdf --name "KI-Forschungspapier" --wait

# 2. Inhalt mit gemini-text extrahieren
python skills/gemini-text/scripts/generate.py "Extrahiere die wichtigsten Erkenntnisse aus diesem Dokument" --image research-paper.pdf

• Am besten geeignet für: Dokumentenverarbeitung, Inhaltsextraktion
• Kombiniert mit: gemini-text für Analyse

Workflow 6: Mehrere Dateien für Batch hochladen

# 1. Mehrere Dateien hochladen
for file in *.jpg; do
    python scripts/upload.py "$file"
done

# 2. Batch-Job mit hochgeladenen Dateien erstellen (gemini-batch Skill)

• Am besten geeignet für: Vorbereiten von Dateien für die Batch-Verarbeitung
• Kombiniert mit: gemini-batch für Bulk-Operationen

Workflow 7: Audio für Transkription hochladen

# 1. Audio hochladen
python scripts/upload.py interview.mp3 --name "interview-001" --wait

# 2. Mit gemini-text verarbeiten (falls Transkription verfügbar)
python skills/gemini-text/scripts/generate.py "Transkribiere und fasse dieses Audio zusammen" --image interview.mp3

• Am besten geeignet für: Audioverarbeitung, Transkription, Podcast-Analyse
• Kombiniert mit: gemini-text für Audio-Analyse

Workflow 8: Video für Inhaltsanalyse hochladen

# 1. Video hochladen (kann Zeit in Anspruch nehmen)
python scripts/upload.py product-demo.mp4 --name "demo-video" --wait

# 2. Mit gemini-text analysieren
python skills/gemini-text/scripts/generate.py "Analysiere dieses Produkt-Demo-Video" --image product-demo.mp4

• Am besten geeignet für: Videoanalyse, Zusammenfassung von Inhalten
• Hinweis: Videos können eine erhebliche Verarbeitungszeit erfordern

Parameter-Referenz

Unterstützte Dateitypen

Typ	Erweiterungen	Maximale Größe	Verarbeitungszeit
Bilder	jpg, jpeg, png, gif, webp	20MB	Sekunden
Audio	mp3, wav, aac, flac	25MB	Sekunden bis Minuten
Video	mp4, mov, avi, webm	2GB	Minuten bis Stunden
Dokumente	pdf, txt	50MB	Sekunden bis Minuten

MIME-Typen

Das Skript erkennt automatisch anhand der Erweiterung:

• Bilder: image/jpeg, image/png, image/gif, image/webp
• Audio: audio/mpeg, audio/wav
• Video: video/mp4, video/quicktime, video/webm
• Dokumente: application/pdf, text/plain

Dateistatus

Status	Beschreibung	Bereit zur Verwendung
PROCESSING	Datei wird analysiert	Nein
ACTIVE	Datei ist bereit	Ja
FAILED	Verarbeitung fehlgeschlagen	Nein

Ausgabeinterpretation

Upload-Antwort

Lade photo.png hoch...
Hochgeladen: files/abc123...
URI: gs://generation-tmp/abc123...
Status: PROCESSING

• Dateiname: In API-Aufrufen verwenden
• URI: Interne Google Cloud Storage-Referenz
• Status: PROCESSING = warten, ACTIVE = bereit

Mit --wait-Flag

Lade video.mp4 hoch...
Hochgeladen: files/xyz789...
URI: gs://generation-tmp/xyz789...
Status: PROCESSING
Warte auf Verarbeitung...
Wird noch verarbeitet...
Datei bereit!

• Das Skript fragt ab, bis der Status ACTIVE ist
• Für große Dateien mit Verarbeitungsbedarf verwenden
• Kann bei Videos Minuten dauern

Hochgeladene Dateien verwenden

Nach dem Hochladen kann die Datei über den Namen referenziert werden:

# Mit gemini-text
python skills/gemini-text/scripts/generate.py "Analysieren" --image <path-der-hochgeladenen-datei>

Häufige Probleme

„google-genai nicht installiert"

pip install google-genai

«Datei nicht gefunden"

• Überprüfe, ob der Dateipfad korrekt ist
• Verwende absolute Pfade, wenn relative Pfade fehlschlagen
• Überprüfe, ob die Dateierweiterung den unterstützten Typen entspricht

„Datei zu groß"

• Größenbeschränkungen für den Dateityp überprüfen
• Bilder/Videos nach Möglichkeit komprimieren
• Große Dateien in kleinere Teile aufteilen

„Nicht unterstützter Dateityp"

• Unterstützte Erweiterungen überprüfen
• Nach Möglichkeit in ein unterstütztes Format konvertieren
• Bilder: jpg, png, gif, webp
• Videos: mp4, mov, avi, webm

„Verarbeitung fehlgeschlagen"

• Überprüfe, ob die Datei nicht beschädigt ist
• Versuche, die Datei erneut hochzuladen
• Überprüfe, ob das Dateiformat gültig ist
• API-Kontingentlimits überprüfen

„Datei wird noch verarbeitet" (ohne --wait)

• Dateistatus ist PROCESSING, nicht ACTIVE
• Verwende das --wait-Flag oder überprüfe den Status später
• Große Dateien (insbesondere Videos) benötigen Zeit
• Die Verarbeitung kann Minuten bis Stunden dauern

Best Practices

Upload-Strategie

• Verwende --wait für Dateien, die du sofort nutzen möchtest
• Überspringe --wait für Batch-Uploads, um Zeit zu sparen
• Verwende aussagekräftige --name für die Organisation
• Behalte die Dateinamen für die spätere Verwendung im Auge

Dateiorganisation

• Verwende konsistente Namenskonventionen
• Füge Daten oder Versionen in Dateinamen ein
• Gruppiere zusammengehörige Dateien
• Dokumentiere Dateinamen in deinem Code

Leistungstipps

• Lade mehrere Dateien parallel hoch (separate Prozesse)
• Lade Dateien für Batch-Operationen vorab hoch
• Überprüfe den Dateistatus vor der Verwendung in API-Aufrufen
• Lösche alte Dateien, um Speicherplatz zu verwalten

Fehlerbehandlung

• Überprüfe den Rückgabestatus nach dem Upload
• Wiederhole fehlgeschlagene Uploads
• Überprüfe die Dateiintegrität vor dem Upload
• Protokolliere Dateinamen für Prüfpfade

Integration mit anderen Skills

• gemini-text: Multimodale Analyse, Dokumentenverarbeitung
• gemini-image: Bilder basierend auf hochgeladener Referenz generieren
• gemini-batch: Hochgeladene Dateien in Batch-Jobs verwenden
• gemini-embeddings: Einbettungen aus Dateiinhalten erstellen

Dateilebenszyklus

• Upload → PROCESSING → ACTIVE → Verwendung in der API
• Lösche alte Dateien, um Speicher freizugeben
• Dateien können nach einer bestimmten Zeit ablaufen
• Lade wichtige Dateien für die Sicherung herunter

Verwandte Skills

• gemini-text: Hochgeladene Dateien mit Textgenerierung analysieren
• gemini-image: Bilder basierend auf hochgeladenen Referenzen erstellen
• gemini-batch: Hochgeladene Dateien in der Batch-Verarbeitung verwenden
• gemini-embeddings: Einbettungen aus Dateiinhalten generieren

Kurzreferenz

# Basisupload
python scripts/upload.py image.jpg

# Mit benutzerdefiniertem Namen
python scripts/upload.py document.pdf --name "Mein Dokument"

# Auf Verarbeitung warten
python scripts/upload.py video.mp4 --wait

# Mehrere Dateien
for file in *.jpg; do python scripts/upload.py "$file"; done

Dateiverwaltungs-API

Auch wenn nicht in Skripten enthalten, kannst du Dateien auch über Python verwalten:

from google import genai

client = genai.Client()

# Alle Dateien auflisten
for file in client.files.list():
    print(f"{file.name}: {file.display_name} ({file.state})")

# Dateiinformationen abrufen
file = client.files.get(name="files/abc123...")
print(f"Status: {file.state}")

# Datei löschen
client.files.delete(name="files/abc123...")

Referenz

• API-Schlüssel abrufen: https://aistudio.google.com/apikey
• Dokumentation: https://ai.google.dev/gemini-api/docs/file-upload
• Datei-API: https://ai.google.dev/gemini-api/docs/files
• Unterstützte Formate: Bilder, Audio, Video, Dokumente (siehe Tabelle oben)