API Gemini File
Téléchargez et gérez des fichiers destinés aux modèles Gemini via des scripts exécutables, prenant en charge les images, l'audio, les vidéos, les PDFs et d'autres types de fichiers.
Quand utiliser cette compétence
Utilisez cette compétence lorsque vous devez :
- Télécharger des images pour une analyse multimodale
- Télécharger des vidéos pour le traitement de contenu
- Télécharger des PDFs pour l'analyse de documents
- Télécharger de l'audio pour la transcription ou le traitement
- Pré-télécharger des fichiers pour des opérations par lots
- Vérifier le statut de traitement des fichiers
- Lister et gérer les fichiers téléchargés
- Utiliser des fichiers avec d'autres compétences Gemini (texte, image, etc.)
Scripts disponibles
scripts/upload.py
Objectif : Télécharger des fichiers vers l'API Gemini File
Quand l'utiliser :
- Pour télécharger un fichier destiné au traitement Gemini
- Pour préparer des fichiers pour la génération multimodale
- Pour télécharger des documents en vue d'une analyse
- Pour la préparation de fichiers par lots
Paramètres clés :
| Paramètre | Description | Exemple |
|---|---|---|
path | Chemin du fichier (obligatoire) | image.jpg |
--name, -n | Nom d'affichage | "mon-document" |
--wait, -w | Attendre le traitement | Drapeau |
Sortie : Nom du fichier, URI et informations sur le statut
Workflows
Workflow 1 : Téléchargement de base d'un fichier
python scripts/upload.py image.jpg
- Idéal pour : Téléchargements rapides, fichiers simples
- Sortie : Nom du fichier et URI pour une utilisation avec l'API
- État : PROCESSING ou ACTIVE
Workflow 2 : Téléchargement avec un nom personnalisé
python scripts/upload.py document.pdf --name "Rapport trimestriel T4 2026"
- Idéal pour : Organiser les fichiers, suivre les téléchargements
- Quand l'utiliser : Lorsque le nom de fichier original n'est pas assez descriptif
- Le nom d'affichage apparaît dans les listes de fichiers
Workflow 3 : Téléchargement et attente du traitement
python scripts/upload.py video.mp4 --wait
- Idéal pour : Fichiers volumineux, vidéos, audio
- Attend que le fichier soit dans l'état ACTIVE
- Quand l'utiliser : Lorsque vous devez utiliser le fichier immédiatement après le téléchargement
Workflow 4 : Téléchargement d'une image pour analyse
# 1. Télécharger l'image
python scripts/upload.py photo.png --name "photo-produit"
# 2. Utiliser avec gemini-text pour l'analyse
python skills/gemini-text/scripts/generate.py "Décris cette image" --image photo.png
- Idéal pour : Analyse d'image, légendage, Q&A visuel
- Combine avec : gemini-text pour le traitement multimodal
Workflow 5 : Téléchargement d'un PDF pour extraction de contenu
# 1. Télécharger le PDF
python scripts/upload.py article-recherche.pdf --name "Article-Recherche-IA" --wait
# 2. Extraire le contenu avec gemini-text
python skills/gemini-text/scripts/generate.py "Extrais les conclusions clés de ce document" --image article-recherche.pdf
- Idéal pour : Traitement de documents, extraction de contenu
- Combine avec : gemini-text pour l'analyse
Workflow 6 : Téléchargement de plusieurs fichiers pour un lot
# 1. Télécharger plusieurs fichiers
for file in *.jpg; do
python scripts/upload.py "$file"
done
# 2. Créer un job par lot en utilisant les fichiers téléchargés (compétence gemini-batch)
- Idéal pour : Préparer des fichiers pour un traitement par lots
- Combine avec : gemini-batch pour les opérations en masse
Workflow 7 : Téléchargement d'un fichier audio pour transcription
# 1. Télécharger l'audio
python scripts/upload.py interview.mp3 --name "interview-001" --wait
# 2. Traiter avec gemini-text (si la transcription est disponible)
python skills/gemini-text/scripts/generate.py "Transcris et résume cet audio" --image interview.mp3
- Idéal pour : Traitement audio, transcription, analyse de podcast
- Combine avec : gemini-text pour l'analyse audio
Workflow 8 : Téléchargement d'une vidéo pour analyse de contenu
# 1. Télécharger la vidéo (peut prendre du temps)
python scripts/upload.py demo-produit.mp4 --name "video-demo" --wait
# 2. Analyser avec gemini-text
python skills/gemini-text/scripts/generate.py "Analyse cette vidéo de démonstration produit" --image demo-produit.mp4
- Idéal pour : Analyse vidéo, résumé de contenu
- Remarque : Les vidéos peuvent nécessiter un temps de traitement important
Référence des paramètres
Types de fichiers pris en charge
| Type | Extensions | Taille max | Temps de traitement |
|---|---|---|---|
| Images | jpg, jpeg, png, gif, webp | 20 Mo | Secondes |
| Audio | mp3, wav, aac, flac | 25 Mo | Secondes à minutes |
| Vidéo | mp4, mov, avi, webm | 2 Go | Minutes à heures |
| Documents | pdf, txt | 50 Mo | Secondes à minutes |
Types MIME
Le script détecte automatiquement en fonction de l'extension :
- Images : image/jpeg, image/png, image/gif, image/webp
- Audio : audio/mpeg, audio/wav
- Vidéo : video/mp4, video/quicktime, video/webm
- Documents : application/pdf, text/plain
États des fichiers
| État | Description | Prêt à l'emploi |
|---|---|---|
PROCESSING | Le fichier est en cours d'analyse | Non |
ACTIVE | Le fichier est prêt | Oui |
FAILED | Le traitement a échoué | Non |
Interprétation des sorties
Réponse de téléchargement
Téléchargement de photo.png...
Téléchargé : files/abc123...
URI : gs://generation-tmp/abc123...
État : PROCESSING
- Nom du fichier : Utilisé dans les appels API
- URI : Référence interne Google Cloud Storage
- État : PROCESSING = attendre, ACTIVE = prêt
Avec le drapeau --wait
Téléchargement de video.mp4...
Téléchargé : files/xyz789...
URI : gs://generation-tmp/xyz789...
État : PROCESSING
Attente du traitement...
Toujours en cours de traitement...
Fichier prêt !
- Le script interroge l'état jusqu'à ce qu'il soit ACTIVE
- À utiliser pour les fichiers volumineux nécessitant un traitement
- Peut prendre plusieurs minutes pour les vidéos
Utilisation des fichiers téléchargés
Une fois téléchargé, référencez le fichier par son nom :
# Avec gemini-text
python skills/gemini-text/scripts/generate.py "Analyser" --image <chemin-du-fichier-telecharge>
Problèmes courants
"google-genai non installé"
pip install google-genai
"Fichier non trouvé"
- Vérifiez que le chemin du fichier est correct
- Utilisez des chemins absolus si les chemins relatifs échouent
- Vérifiez que l'extension du fichier correspond aux types pris en charge
"Fichier trop volumineux"
- Vérifiez les limites de taille pour le type de fichier
- Compressez les images/vidéos si possible
- Divisez les fichiers volumineux en parties plus petites
"Type de fichier non pris en charge"
- Vérifiez les extensions prises en charge
- Convertissez dans un format pris en charge si possible
- Images : jpg, png, gif, webp
- Vidéos : mp4, mov, avi, webm
"Le traitement a échoué"
- Vérifiez que le fichier n'est pas corrompu
- Essayez de retélécharger le fichier
- Vérifiez que le format du fichier est valide
- Vérifiez les limites de quota de l'API
"Fichier toujours en cours de traitement" (sans --wait)
- L'état du fichier est PROCESSING, pas ACTIVE
- Utilisez le drapeau
--waitou vérifiez le statut plus tard - Les fichiers volumineux (notamment les vidéos) prennent du temps
- Le traitement peut prendre de quelques minutes à plusieurs heures
Bonnes pratiques
Stratégie de téléchargement
- Utilisez
--waitpour les fichiers que vous utiliserez immédiatement - Ignorez
--waitpour les téléchargements par lots afin de gagner du temps - Utilisez des
--namedescriptifs pour l'organisation - Gardez une trace des noms de fichiers pour une utilisation ultérieure
Organisation des fichiers
- Utilisez des conventions de nommage cohérentes
- Incluez des dates ou des versions dans les noms
- Regroupez les fichiers connexes ensemble
- Documentez les noms de fichiers dans votre code
Conseils de performance
- Téléchargez plusieurs fichiers en parallèle (processus séparés)
- Pré-téléchargez les fichiers pour les opérations par lots
- Vérifiez l'état du fichier avant de l'utiliser dans les appels API
- Supprimez les anciens fichiers pour gérer le stockage
Gestion des erreurs
- Vérifiez l'état de retour après le téléchargement
- Réessayez les téléchargements échoués
- Vérifiez l'intégrité du fichier avant le téléchargement
- Enregistrez les noms de fichiers pour les pistes d'audit
Intégration avec d'autres compétences
- gemini-text : Analyse multimodale, traitement de documents
- gemini-image : Générer des images basées sur une référence téléchargée
- gemini-batch : Utiliser les fichiers téléchargés dans des jobs par lots
- gemini-embeddings : Créer des embeddings à partir du contenu des fichiers
Cycle de vie des fichiers
- Téléchargement → PROCESSING → ACTIVE → Utilisation dans l'API
- Supprimez les anciens fichiers pour libérer du stockage
- Les fichiers peuvent expirer après une certaine période
- Téléchargez les fichiers importants pour sauvegarde
Compétences connexes
- gemini-text : Analyser les fichiers téléchargés avec la génération de texte
- gemini-image : Créer des images basées sur des références téléchargées
- gemini-batch : Utiliser les fichiers téléchargés dans le traitement par lots
- gemini-embeddings : Générer des embeddings à partir du contenu des fichiers
Référence rapide
# Téléchargement de base
python scripts/upload.py image.jpg
# Avec un nom personnalisé
python scripts/upload.py document.pdf --name "Mon document"
# Attendre le traitement
python scripts/upload.py video.mp4 --wait
# Plusieurs fichiers
for file in *.jpg; do python scripts/upload.py "$file"; done
API de gestion des fichiers
Bien que non inclus dans les scripts, vous pouvez également gérer les fichiers via Python :
from google import genai
client = genai.Client()
# Lister tous les fichiers
for file in client.files.list():
print(f"{file.name}: {file.display_name} ({file.state})")
# Obtenir les informations d'un fichier
file = client.files.get(name="files/abc123...")
print(f"État : {file.state}")
# Supprimer un fichier
client.files.delete(name="files/abc123...")
Référence
- Obtenir une clé API : https://aistudio.google.com/apikey
- Documentation : https://ai.google.dev/gemini-api/docs/file-upload
- API Fichier : https://ai.google.dev/gemini-api/docs/files
- Formats pris en charge : Images, audio, vidéo, documents (voir tableau ci-dessus)