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, Videos, PDFs und andere Dateitypen.
Wann dieses Skill verwendet werden sollte
Verwenden Sie dieses Skill, wenn Sie Folgendes benötigen:
- Bilder für multimodale Analysen hochladen
- Videos zur Inhaltsverarbeitung hochladen
- PDFs zur Dokumentenanalyse hochladen
- Audio zum Transkribieren oder Verarbeiten hochladen
- Dateien für Stapeloperationen vorab hochladen
- Dateiverarbeitungsstatus prüfen
- Hochgeladene Dateien auflisten und verwalten
- Dateien mit anderen Gemini-Skills (Text, Bild usw.) verwenden
Verfügbare Skripte
scripts/upload.py
Zweck: Dateien in die Gemini File API hochladen
Wann verwenden:
- Hochladen beliebiger Dateien für die Gemini-Verarbeitung
- Vorbereiten von Dateien für 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: Einfaches 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: Hochladen mit benutzerdefiniertem Namen
python scripts/upload.py document.pdf --name "Quarterly Report Q4 2026"
- Am besten geeignet für: Dateiorganisation, Upload-Nachverfolgung
- Verwenden wenn: Dateiname nicht aussagekräftig genug ist
- 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 ACTIVE-Status erreicht hat
- Verwenden wenn: Datei sofort nach dem Upload verwendet werden soll
Workflow 4: Bild für Analyse hochladen
# 1. Bild hochladen
python scripts/upload.py photo.png --name "product-shot"
# 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 Q&A
- Kombiniert mit: gemini-text für multimodale Verarbeitung
Workflow 5: PDF für Inhaltsextraktion hochladen
# 1. PDF hochladen
python scripts/upload.py research-paper.pdf --name "AI-Research-Paper" --wait
# 2. Inhalt mit gemini-text extrahieren
python skills/gemini-text/scripts/generate.py "Extrahiere wichtige Erkenntnisse aus diesem Dokument" --image research-paper.pdf
- Am besten geeignet für: Dokumentenverarbeitung, Inhaltsextraktion
- Kombiniert mit: gemini-text zur 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: Vorbereitung von Dateien für die Stapelverarbeitung
- Kombiniert mit: gemini-batch für Bulk-Operationen
Workflow 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
- 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, Inhaltszusammenfassung
- Hinweis: Videos können eine erhebliche Verarbeitungszeit erfordern
Parameter-Referenz
Unterstützte Dateitypen
| Typ | Erweiterungen | Max. Größe | Verarbeitungszeit |
|---|---|---|---|
| Bilder | jpg, jpeg, png, gif, webp | 20 MB | Sekunden |
| Audio | mp3, wav, aac, flac | 25 MB | Sekunden bis Minuten |
| Video | mp4, mov, avi, webm | 2 GB | Minuten bis Stunden |
| Dokumente | pdf, txt | 50 MB | 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
Uploading photo.png...
Uploaded: files/abc123...
URI: gs://generation-tmp/abc123...
State: PROCESSING
- Dateiname: In API-Aufrufen verwenden
- URI: Interner Google Cloud Storage-Verweis
- 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!
- 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 Hochladen auf die Datei mit dem Dateinamen verweisen:
# Mit gemini-text
python skills/gemini-text/scripts/generate.py "Analysiere" --image <path-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
- Überprüfen Sie, ob die Dateierweiterung unterstützt wird
„Datei zu groß"
- Überprüfen Sie die Größenbeschränkungen für den Dateityp
- Komprimieren Sie Bilder/Videos nach Möglichkeit
- 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, falls möglich
- 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 noch in Verarbeitung" (ohne --wait)
- Dateistatus ist PROCESSING, nicht ACTIVE
- Verwenden Sie das
--wait-Flag oder überprüfen Sie den Status später - Große Dateien (insbesondere Videos) brauchen 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 aussagekräftige
--namezur Organisation - Behalten Sie die 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 verwandte Dateien zusammen
- Dokumentieren Sie Dateinamen in Ihrem Code
Leistungstipps
- Laden Sie mehrere Dateien parallel hoch (separate Prozesse)
- Laden Sie Dateien für Stapeloperationen vorab hoch
- Überprü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 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: Generieren von Bildern basierend auf hochgeladenen Referenzen
- gemini-batch: Hochgeladene Dateien in Stapelverarbeitungen verwenden
- gemini-embeddings: Erstellen von Embeddings aus Dateiinhalten
Dateilebenszyklus
- 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 zur 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 Stapelverarbeitung nutzen
- gemini-embeddings: Embeddings aus Dateiinhalten generieren
Kurzreferenz
# Einfacher 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 Skripten, 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-Key abrufen: https://aistudio.google.com/apikey
- Dokumentation: https://ai.google.dev/gemini-api/docs/file-upload
- File API: https://ai.google.dev/gemini-api/docs/files
- Unterstützte Formate: Bilder, Audio, Video, Dokumente (siehe Tabelle oben)