Gemini File 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 diese Fertigkeit verwendet werden sollte

Verwende diese Fertigkeit, wenn du Folgendes benötigst:

Bilder für multimodale Analysen hochladen
Videos zur Inhaltsverarbeitung hochladen
PDFs zur Dokumentenanalyse hochladen
Audio für Transkription oder Verarbeitung hochladen
Dateien für Batch-Operationen vorab hochladen
Dateiverarbeitungsstatus prüfen
Hochgeladene Dateien auflisten und verwalten
Dateien mit anderen Gemini-Fertigkeiten (Text, Bild usw.) verwenden

Verfügbare Skripte

scripts/upload.js

Zweck: Dateien an die Gemini File API hochladen

Wann verwenden:

Hochladen einer beliebigen Datei für die Gemini-Verarbeitung
Vorbereiten von Dateien für die multimodale Generierung
Dokumente für die Analyse hochladen
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

node scripts/upload.js 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

node scripts/upload.js document.pdf --name "Quartalsbericht Q4 2026"

Am besten geeignet für: Dateiorganisation, Nachverfolgung von Uploads
Verwenden, wenn: Der ursprüngliche Dateiname nicht aussagekräftig genug ist
Der Anzeigename erscheint in Dateilisten

Workflow 3: Hochladen und auf Verarbeitung warten

node scripts/upload.js video.mp4 --wait

Am besten geeignet für: Große Dateien, Videos, Audio
Wartet, bis die Datei den Status ACTIVE erreicht
Verwenden, wenn: Die Datei sofort nach dem Upload verwendet werden soll

Workflow 4: Bild für Analyse hochladen

# 1. Bild hochladen
node scripts/upload.js photo.png --name "produktfoto"

# 2. Mit gemini-text zur Analyse verwenden
node skills/gemini-text/scripts/generate.js "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 Inhalts Extraktion hochladen

# 1. PDF hochladen
node scripts/upload.js forschungsarbeit.pdf --name "KI-Forschungsarbeit" --wait

# 2. Inhalt mit gemini-text extrahieren
node skills/gemini-text/scripts/generate.js "Extrahiere die wichtigsten Erkenntnisse aus diesem Dokument" --image forschungsarbeit.pdf

Am besten geeignet für: Dokumentenverarbeitung, Inhalts Extraktion
Kombiniert mit: gemini-text für Analysen

Workflow 6: Mehrere Dateien für Batch-Operationen hochladen

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

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

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
node scripts/upload.js interview.mp3 --name "interview-001" --wait

# 2. Mit gemini-text verarbeiten (falls Transkription verfügbar)
node skills/gemini-text/scripts/generate.js "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)
node scripts/upload.js produkt-demo.mp4 --name "demo-video" --wait

# 2. Mit gemini-text analysieren
node skills/gemini-text/scripts/generate.js "Analysiere dieses Produkt-Demo-Video" --image produkt-demo.mp4

Am besten geeignet für: Videoanalyse, Inhaltszusammenfassung
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	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 Verwendung
`PROCESSING`	Datei wird analysiert	Nein
`ACTIVE`	Datei ist bereit	Ja
`FAILED`	Verarbeitung fehlgeschlagen	Nein

Ausgabe-Interpretation

Upload-Antwort

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

Dateiname: In API-Aufrufen verwenden
URI: Interner Google Cloud Storage Verweis
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 der Status ACTIVE ist
Für große Dateien verwenden, die Verarbeitung benötigen
Kann bei Videos Minuten dauern

Verwendung hochgeladener Dateien

Nach dem Upload die Datei mit Namen referenzieren:

# Mit gemini-text
node skills/gemini-text/scripts/generate.js "Analysieren" --image <hochgeladener-dateipfad>

Häufige Probleme

"google-genai nicht installiert"

npm install @google/genai@latest dotenv@latest

"Datei nicht gefunden"

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

"Datei zu groß"

Überprüfe die Größenbeschränkungen für den Dateityp
Komprimiere Bilder/Videos wenn möglich
Teile große Dateien in kleinere Teile auf

"Nicht unterstützter Dateityp"

Überprüfe die unterstützten Erweiterungen
Konvertiere in ein unterstütztes Format, falls möglich
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 das Dateiformat auf Gültigkeit
Prüfe die API-Kontingentlimits

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

Dateistatus ist PROCESSING, nicht ACTIVE
Verwende das --wait Flag oder prü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 sofort verwendet werden sollen
Überspringe --wait für Batch-Uploads, um Zeit zu sparen
Verwende beschreibende --name für die Organisation
Behalte Dateinamen für die spätere Verwendung im Auge

Dateiorganisation

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

Leistungstipps

Lade mehrere Dateien parallel hoch (getrennte 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 Fertigkeiten

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

Datei-Lebenszyklus

Upload → PROCESSING → ACTIVE → Verwendung in API
Lösche alte Dateien, um Speicher freizugeben
Dateien können nach einer bestimmten Zeit ablaufen
Wichtige Dateien zur Sicherung herunterladen

Kurzreferenz

# Einfacher Upload
node scripts/upload.js image.jpg

# Mit benutzerdefiniertem Namen
node scripts/upload.js document.pdf --name "Mein Dokument"

# Auf Verarbeitung warten
node scripts/upload.js video.mp4 --wait

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

Dateiverwaltungs-API

Obwohl nicht in Skripten enthalten, kannst du Dateien auch über JavaScript verwalten:

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Alle Dateien auflisten
for await (const file of client.files.list()) {
  console.log(`${file.name}: ${file.displayName} (${file.state})`);
}

// Dateiinfo abrufen
const file = await client.files.get({ name: "files/abc123..." });
console.log(`Status: ${file.state}`);

// Datei löschen
await 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)

In Ihrer bevorzugten KI fragen

Dokumentation