Gemini File API (Datei-API)
Laden Sie Dateien für die Verwendung mit Gemini-Modellen über ausführbare Skripte hoch und verwalten Sie diese. Unterstützt werden Bilder, Audio, Videos, PDFs und andere Dateitypen.
Wann dieses Skill verwendet werden sollte
Verwenden Sie dieses Skill, wenn Sie:
- Bilder für multimodale Analysen hochladen müssen
- Videos zur Inhaltsverarbeitung hochladen müssen
- PDFs zur Dokumentenanalyse hochladen müssen
- Audio für Transkription oder Verarbeitung hochladen müssen
- Dateien für Batch-Operationen vorab hochladen müssen
- Den Verarbeitungsstatus von Dateien überprüfen müssen
- Hochgeladene Dateien auflisten und verwalten müssen
- Dateien mit anderen Gemini-Skills (Text, Bild usw.) verwenden müssen
Verfügbare Skripte
scripts/upload.py
Zweck: Dateien in die Gemini File API hochladen
Wann verwenden:
- Zum Hochladen einer beliebigen Datei für die Gemini-Verarbeitung
- Zur Vorbereitung von Dateien für die multimodale Generierung
- Zum Hochladen von Dokumenten für die Analyse
- Zur 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: Einfacher Datei-Upload
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: Dateiorganisation, Upload-Nachverfolgung
- Verwenden, wenn: Der ursprüngliche Dateiname nicht aussagekräftig genug ist
- Der Anzeigename erscheint in Dateilisten
Workflow 3: Upload 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 ACTIVE-Status erreicht hat
- Verwenden, wenn: Sie die Datei sofort nach dem Upload verwenden müssen
Workflow 4: Bild zur 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, Bildunterschriften, visuelle Fragen & Antworten
- Kombiniert mit: gemini-text für multimodale Verarbeitung
Workflow 5: PDF zur Textextraktion 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, Textextraktion
- Kombiniert mit: gemini-text für Analysen
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 (Skill: gemini-batch)
- Am besten geeignet für: Dateivorbereitung für die Stapelverarbeitung
- 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 Audioanalyse
Workflow 8: Video zur 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 Produktdemonstrationsvideo" --image product-demo.mp4
- Am besten geeignet für: Videoanalyse, Zusammenfassung von Inhalten
- Hinweis: Videos können eine erhebliche Verarbeitungszeit erfordern
Parameterreferenz
Unterstützte Dateitypen
| Typ | Erweiterungen | Maximale Größe | Verarbeitungszeit |
|---|---|---|---|
| Bilder | jpg, jpeg, png, gif, webp | 20 MB | Sekunden |
| Audio | mp3, wav, aac, flac | 25 MB | Sekunden - Minuten |
| Video | mp4, mov, avi, webm | 2 GB | Minuten - Stunden |
| Dokumente | pdf, txt | 50 MB | Sekunden - 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 Nutzung |
|---|---|---|
PROCESSING | Datei wird analysiert | Nein |
ACTIVE | Datei ist bereit | Ja |
FAILED | Verarbeitung fehlgeschlagen | Nein |
Ausgabeinterpretation
Upload-Antwort
Uploading photo.png...
Uploaded: files/abc123...
URI: gs://generation-tmp/abc123...
State: PROCESSING
- Dateiname: In API-Aufrufen verwenden
- URI: Interne Google Cloud Storage-Referenz
- Status: PROCESSING = warten, ACTIVE = bereit
Mit --wait-Flag
Uploading video.mp4...
Uploaded: files/xyz789...
URI: gs://generation-tmp/xyz789...
State: PROCESSING
Waiting for processing...
Still processing...
File ready!
- Das Skript fragt ab, bis der Status ACTIVE ist
- Für große Dateien verwenden, die eine Verarbeitung erfordern
- Kann bei Videos Minuten dauern
Hochgeladene Dateien verwenden
Nach dem Upload kann die Datei über den Namen referenziert werden:
# Mit gemini-text
python skills/gemini-text/scripts/generate.py "Analysieren" --image <uploaded-file-path>
Häufige Probleme
"google-genai nicht installiert"
pip install google-genai
"Datei nicht gefunden"
- Überprüfen Sie, ob der Dateipfad korrekt ist
- Verwenden Sie absolute Pfade, wenn relative Pfade fehlschlagen
- Stellen Sie sicher, dass die Dateierweiterung den unterstützten Typen entspricht
"Datei zu groß"
- Überprüfen Sie die Größenbeschränkungen für den Dateityp
- Komprimieren Sie Bilder/Videos, wenn möglich
- Teilen Sie große Dateien in kleinere Teile auf
"Nicht unterstützter Dateityp"
- Überprüfen Sie die unterstützten Erweiterungen
- Konvertieren Sie die Datei bei Bedarf in ein unterstütztes Format
- Bilder: jpg, png, gif, webp
- Videos: mp4, mov, avi, webm
"Verarbeitung fehlgeschlagen"
- Überprüfen Sie, ob die Datei nicht beschädigt ist
- Versuchen Sie, die Datei erneut hochzuladen
- Stellen Sie sicher, dass das Dateiformat gültig ist
- Überprüfen Sie die API-Kontingentlimits
"Datei wird noch verarbeitet" (ohne --wait)
- Der Dateistatus ist PROCESSING, nicht ACTIVE
- Verwenden Sie das
--wait-Flag oder überprüfen Sie den Status später - Große Dateien (insbesondere Videos) benötigen Zeit
- Die Verarbeitung kann Minuten bis Stunden dauern
Best Practices
Upload-Strategie
- Verwenden Sie
--waitfür Dateien, die Sie sofort verwenden möchten - Überspringen Sie
--waitbei Batch-Uploads, um Zeit zu sparen - Verwenden Sie beschreibende
--name-Angaben für die Organisation - Notieren Sie sich die Dateinamen für die spätere Verwendung
Dateiorganisation
- Verwenden Sie konsistente Namenskonventionen
- Fügen Sie Daten oder Versionen in die Namen ein
- Gruppieren Sie zusammengehörige Dateien
- Dokumentieren Sie Dateinamen in Ihrem Code
Leistungstipps
- Laden Sie mehrere Dateien parallel hoch (getrennte Prozesse)
- Laden Sie Dateien für Batch-Operationen vorab hoch
- Überprüfen Sie den Dateistatus, bevor Sie sie in API-Aufrufen verwenden
- Löschen Sie alte Dateien, um Speicher zu verwalten
Fehlerbehandlung
- Überprüfen Sie den Rückgabestatus nach dem Upload
- Wiederholen Sie fehlgeschlagene Uploads
- Überprüfen Sie die Dateiintegrität vor dem Upload
- Protokollieren Sie Dateinamen für Prüfpfade
Integration mit anderen Skills
- gemini-text: Multimodale Analyse, Dokumentenverarbeitung
- gemini-image: Bilder basierend auf hochgeladenen Referenzen generieren
- gemini-batch: Hochgeladene Dateien in Batch-Jobs verwenden
- gemini-embeddings: Einbettungen aus Dateiinhalten erstellen
Datei-Lebenszyklus
- Hochladen → PROCESSING → ACTIVE → Verwendung in der API
- Löschen Sie alte Dateien, um Speicher freizugeben
- Dateien können nach einem bestimmten Zeitraum ablaufen
- Laden Sie wichtige Dateien für Sicherungszwecke herunter
Verwandte Skills
- gemini-text: Hochgeladene Dateien mit Textgenerierung analysieren
- gemini-image: Bilder basierend auf hochgeladenen Referenzen erstellen
- gemini-batch: Hochgeladene Dateien in der Stapelverarbeitung verwenden
- gemini-embeddings: Einbettungen aus Dateiinhalten generieren
Kurzreferenz
# Basis-Upload
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
Obwohl nicht in den Skripten enthalten, können Sie 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)