Was macht Gemini Datei-API?
Laden Sie Dateien für die Verwendung mit Gemini-Modellen über ausführbare Skripte hoch und verwalten Sie sie. Unterstützt Bilder, Audio, Video, PDFs und andere Dateitypen.
Wann dieses Skill verwenden
Verwenden Sie dieses Skill, wenn Sie:
- Bilder für multimodale Analysen hochladen möchten
- Videos zur Inhaltsverarbeitung hochladen möchten
- PDFs zur Dokumentenanalyse hochladen möchten
- Audio für Transkription oder Verarbeitung hochladen möchten
- Dateien für Stapeloperationen vorab hochladen möchten
- den Verarbeitungsstatus von Dateien prüfen möchten
- hochgeladene Dateien auflisten und verwalten möchten
- Dateien mit anderen Gemini-Fähigkeiten (Text, Bild, usw.) verwenden möchten
Verfügbare Skripte
scripts/upload.py
Zweck: Hochladen von Dateien an die Gemini File API
Verwendung:
- Hochladen beliebiger Dateien für die Gemini-Verarbeitung
- Vorbereiten von Dateien für die multimodale Generierung
- Hochladen von Dokumenten zur Analyse
- Vorbereiten von Dateien für die Stapelverarbeitung
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
Arbeitsabläufe
Arbeitsablauf 1: Einfaches Hochladen
python scripts/upload.py bild.jpg
- Optimal für: Schnelles Hochladen, einfache Dateien
- Ausgabe: Dateiname und URI zur API-Nutzung
- Status: PROCESSING oder ACTIVE
Arbeitsablauf 2: Hochladen mit benutzerdefiniertem Namen
python scripts/upload.py dokument.pdf --name "Quartalsbericht Q4 2026"
- Optimal für: Dateiorganisation, Upload-Verfolgung
- Verwenden Sie: wenn der ursprüngliche Dateiname nicht aussagekräftig genug ist
- Der Anzeigename erscheint in Dateilisten
Arbeitsablauf 3: Hochladen und auf Verarbeitung warten
python scripts/upload.py video.mp4 --wait
- Optimal für: Große Dateien, Videos, Audio
- Wartet, bis die Datei im ACTIVE-Status ist
- Verwenden Sie: wenn Sie die Datei sofort nach dem Hochladen benötigen
Arbeitsablauf 4: Bild zur Analyse hochladen
# 1. Bild hochladen
python scripts/upload.py foto.png --name "produktfoto"
# 2. Mit gemini-text zur Analyse verwenden
python skills/gemini-text/scripts/generate.py "Beschreibe dieses Bild" --image foto.png
- Optimal für: Bildanalyse, Bildunterschriften, visuelle Fragen & Antworten
- Kombiniert mit: gemini-text für multimodale Verarbeitung
Arbeitsablauf 5: PDF zur Inhaltsgewinnung hochladen
# 1. PDF hochladen
python scripts/upload.py forschungspapier.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 forschungspapier.pdf
- Optimal für: Dokumentenverarbeitung, Inhaltsgewinnung
- Kombiniert mit: gemini-text für Analysen
Arbeitsablauf 6: Mehrere Dateien für Stapelverarbeitung hochladen
# 1. Mehrere Dateien hochladen
for datei in *.jpg; do
python scripts/upload.py "$datei"
done
# 2. Stapelauftrag mit hochgeladenen Dateien erstellen (gemini-batch skill)
- Optimal für: Vorbereiten von Dateien für die Stapelverarbeitung
- Kombiniert mit: gemini-batch für Massenvorgänge
Arbeitsablauf 7: Audio zur 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
- Optimal für: Audioverarbeitung, Transkription, Podcast-Analyse
- Kombiniert mit: gemini-text für Audioanalysen
Arbeitsablauf 8: Video zur Inhaltsanalyse hochladen
# 1. Video hochladen (kann Zeit in Anspruch nehmen)
python scripts/upload.py produktdemo.mp4 --name "demo-video" --wait
# 2. Mit gemini-text analysieren
python skills/gemini-text/scripts/generate.py "Analysiere dieses Produkt-Demo-Video" --image produktdemo.mp4
- Optimal für: Videoanalyse, Inhaltszusammenfassung
- Hinweis: Videos können erhebliche Verarbeitungszeit benötigen
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–Minuten |
| Video | mp4, mov, avi, webm | 2GB | Minuten–Stunden |
| Dokumente | pdf, txt | 50MB | Sekunden–Minuten |
MIME-Typen
Das Skript erkennt automatisch anhand der Dateierweiterung:
- 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
Dateistati
| Status | Beschreibung | Bereit zur Nutzung |
|---|---|---|
PROCESSING | Datei wird analysiert | Nein |
ACTIVE | Datei ist bereit | Ja |
FAILED | Verarbeitung fehlgeschlagen | Nein |
Ausgabeinterpretation
Upload-Antwort
Lade foto.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!
- Skript fragt ab, bis Status ACTIVE ist
- Bei großen Dateien verwenden, die Verarbeitung erfordern
- Kann bei Videos Minuten dauern
Verwendung hochgeladener Dateien
Nach dem Hochladen kann die Datei über den Namen referenziert werden:
# Mit gemini-text
python skills/gemini-text/scripts/generate.py "Analysiere" --image <pfad-zur-hochgeladenen-datei>
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ß"
- Prü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 in ein unterstütztes Format, wenn möglich
- Bilder: jpg, png, gif, webp
- Videos: mp4, mov, avi, webm
"Verarbeitung fehlgeschlagen"
- Prüfen Sie, ob die Datei 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)
- Dateistatus ist PROCESSING, nicht ACTIVE
- Verwenden Sie das
--waitFlag oder prü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 nutzen möchten - Überspringen Sie
--waitbei Stapel-Uploads, um Zeit zu sparen - Verwenden Sie beschreibende
--namefür die Organisation - Behalten Sie Dateinamen für die spätere Verwendung im Auge
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 (separate Prozesse)
- Laden Sie Dateien für Stapeloperationen vorab hoch
- Prüfen Sie den Dateistatus vor der Verwendung in API-Aufrufen
- Löschen Sie alte Dateien, um Speicherplatz zu verwalten
Fehlerbehandlung
- Überprüfen Sie den Rückgabestatus nach dem Hochladen
- Wiederholen Sie fehlgeschlagene Uploads
- Verifizieren Sie die Dateiintegrität vor dem Hochladen
- 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 Stapelaufträgen verwenden
- gemini-embeddings: Einbettungen aus Dateiinhalten erstellen
Datei-Lebenszyklus
- Hochladen → PROCESSING → ACTIVE → In API verwenden
- Löschen Sie alte Dateien, um Speicher freizugeben
- Dateien können nach einem bestimmten Zeitraum ablaufen
- Laden Sie wichtige Dateien zur Sicherung herunter
Verwandte Skills
- gemini-text: Analysieren Sie hochgeladene Dateien mit Textgenerierung
- gemini-image: Erstellen Sie Bilder basierend auf hochgeladenen Referenzen
- gemini-batch: Verwenden Sie hochgeladene Dateien in der Stapelverarbeitung
- gemini-embeddings: Generieren Sie Einbettungen aus Dateiinhalten
Kurzreferenz
# Einfaches Hochladen
python scripts/upload.py bild.jpg
# Mit benutzerdefiniertem Namen
python scripts/upload.py dokument.pdf --name "Mein Dokument"
# Auf Verarbeitung warten
python scripts/upload.py video.mp4 --wait
# Mehrere Dateien
for datei in *.jpg; do python scripts/upload.py "$datei"; 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 datei in client.files.list():
print(f"{datei.name}: {datei.display_name} ({datei.state})")
# Dateiinformationen abrufen
datei = client.files.get(name="files/abc123...")
print(f"Status: {datei.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)