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 PDF 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 PDF 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éversé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 une génération multimodale
- Pour télécharger des documents à analyser
- Pour la préparation par lots de fichiers
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 |
Résultat : Nom du fichier, URI et informations de statut
Workflows
Workflow 1 : Téléchargement de base
python scripts/upload.py image.jpg
- Idéal pour : Téléchargements rapides, fichiers simples
- Résultat : Nom du fichier et URI pour l'API
- État : PROCESSING ou ACTIVE
Workflow 2 : Téléchargement avec nom personnalisé
python scripts/upload.py document.pdf --name "Rapport trimestriel Q4 2026"
- Idéal pour : Organiser les fichiers, suivre les téléversements
- Quand l'utiliser : Lorsque le nom de fichier d'origine n'est pas assez descriptif
- Le nom d'affichage apparaît dans la liste des 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 à l'état ACTIVE
- Quand l'utiliser : Lorsque vous devez utiliser le fichier immédiatement après le téléversement
Workflow 4 : Téléchargement d'image pour analyse
# 1. Télécharger l'image
python scripts/upload.py photo.png --name "photo-produit"
# 2. Utiliser avec gemini-text pour 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
- Se combine avec : gemini-text pour le traitement multimodal
Workflow 5 : Téléchargement de PDF pour extraction de contenu
# 1. Télécharger le PDF
python scripts/upload.py article-recherche.pdf --name "Article-IA" --wait
# 2. Extraire le contenu avec gemini-text
python skills/gemini-text/scripts/generate.py "Extrais les principales conclusions de ce document" --image article-recherche.pdf
- Idéal pour : Traitement de documents, extraction de contenu
- Se combine avec : gemini-text pour l'analyse
Workflow 6 : Téléchargement multiple pour lot
# 1. Télécharger plusieurs fichiers
for file in *.jpg; do
python scripts/upload.py "$file"
done
# 2. Créer un job par lots en utilisant les fichiers uploadés (compétence gemini-batch)
- Idéal pour : Préparer des fichiers pour un traitement par lots
- Se combine avec : gemini-batch pour les opérations groupées
Workflow 7 : Téléchargement 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
- Se combine avec : gemini-text pour l'analyse audio
Workflow 8 : Téléchargement 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
- Note : 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 résultats
Réponse de téléchargement
Téléversement de photo.png...
Téléversé : files/abc123...
URI : gs://generation-tmp/abc123...
État : PROCESSING
- Nom du fichier : Utiliser dans les appels API
- URI : Référence interne Google Cloud Storage
- État : PROCESSING = attendre, ACTIVE = prêt
Avec le drapeau --wait
Téléversement de video.mp4...
Téléversé : files/xyz789...
URI : gs://generation-tmp/xyz789...
État : PROCESSING
Attente du traitement...
Toujours en traitement...
Fichier prêt !
- Le script interroge jusqu'à ce que l'état soit ACTIVE
- Utiliser pour les fichiers volumineux nécessitant un traitement
- Peut prendre plusieurs minutes pour les vidéos
Utilisation des fichiers téléversés
Une fois téléversé, référencez le fichier par son nom :
# Avec gemini-text
python skills/gemini-text/scripts/generate.py "Analyse" --image <chemin-du-fichier-uploadé>
Problèmes courants
« google-genai n'est pas installé »
pip install google-genai
« Fichier introuvable »
- Vérifiez que le chemin du fichier est correct
- Utilisez des chemins absolus si les chemins relatifs échouent
- Vérifiez que l'extension 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 téléverser à nouveau le fichier
- Vérifiez que le format du fichier est valide
- Vérifiez les limites de quota de l'API
« Le fichier est 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 (surtout 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éversements par lots afin de gagner du temps - Utilisez un
--namedescriptif 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 performances
- 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éversement
- Réessayez les téléversements échoués
- Vérifiez l'intégrité du fichier avant le téléversement
- 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éversée
- gemini-batch : Utiliser les fichiers téléversés dans les jobs par lots
- gemini-embeddings : Créer des embeddings à partir du contenu du fichier
Cycle de vie d'un fichier
- Téléversement → 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 associées
- gemini-text : Analyser les fichiers téléversés avec génération de texte
- gemini-image : Créer des images basées sur des références téléversées
- gemini-batch : Utiliser les fichiers téléversé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 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érences
- 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 le tableau ci-dessus)