Que fait API de fichiers Gemini ?
Téléversez et gérez des fichiers pour une utilisation avec les modèles Gemini via des scripts exécutables, prenant en charge les images, l'audio, la vidéo, les PDF et d'autres types de fichiers.
Quand utiliser cette compétence
Utilisez cette compétence lorsque vous avez besoin de :
- Téléverser des images pour une analyse multimodale
- Téléverser des vidéos pour un traitement de contenu
- Téléverser des PDF pour une analyse de documents
- Téléverser de l'audio pour une transcription ou un traitement
- Pré-téléverser 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éverser des fichiers vers l'API de fichiers Gemini
Quand l'utiliser :
- Téléverser un fichier pour un traitement Gemini
- Préparer des fichiers pour une génération multimodale
- Téléverser des documents pour analyse
- 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 de statut
Workflows
Workflow 1 : Téléversement de fichier de base
python scripts/upload.py image.jpg
- Idéal pour : Téléversements rapides, fichiers simples
- Sortie : Nom du fichier et URI pour utilisation via l'API
- État : PROCESSING ou ACTIVE
Workflow 2 : Téléversement 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
- Utiliser quand : Le nom de fichier d'origine n'est pas assez descriptif
- Le nom d'affichage apparaît dans les listes de fichiers
Workflow 3 : Téléversement 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
- Utiliser quand : Vous devez utiliser le fichier immédiatement après le téléversement
Workflow 4 : Téléversement d'image pour analyse
# 1. Téléverser 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, questions-réponses visuelles
- Se combine avec : gemini-text pour le traitement multimodal
Workflow 5 : Téléversement de PDF pour extraction de contenu
# 1. Téléverser le PDF
python scripts/upload.py article-recherche.pdf --name "Article-IA-Recherche" --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éversement de plusieurs fichiers pour traitement par lots
# 1. Téléverser plusieurs fichiers
for file in *.jpg; do
python scripts/upload.py "$file"
done
# 2. Créer un job par lots en utilisant les fichiers téléversé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 en masse
Workflow 7 : Téléversement audio pour transcription
# 1. Téléverser 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éversement vidéo pour analyse de contenu
# 1. Téléverser 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
Détection automatique par 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 de la sortie
Réponse de téléversement
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 cours de 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érencer le fichier par son nom :
# Avec gemini-text
python skills/gemini-text/scripts/generate.py "Analyser" --image <chemin-fichier-televerse>
Problèmes courants
"google-genai non 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 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
"Échec du traitement"
- Vérifiez que le fichier n'est pas corrompu
- Essayez de re-téléverser 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 (surtout les vidéos) prennent du temps
- Le traitement peut prendre de quelques minutes à plusieurs heures
Bonnes pratiques
Stratégie de téléversement
- Utilisez
--waitpour les fichiers que vous utiliserez immédiatement - Sautez
--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 performance
- Téléversez plusieurs fichiers en parallèle (processus séparés)
- Pré-téléversez les fichiers pour les opérations par lots
- Vérifiez l'état du fichier avant de l'utiliser dans des 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 qui ont échoué
- Vérifiez l'intégrité du fichier avant le téléversement
- Consignez 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 des jobs par lots
- gemini-embeddings : Créer des embeddings à partir du contenu du fichier
Cycle de vie des fichiers
- 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 connexes
- gemini-text : Analyser les fichiers téléversés avec la 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 un traitement par lots
- gemini-embeddings : Générer des embeddings à partir du contenu du fichier
Référence rapide
# Téléversement 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érence
- Obtenir une clé API : https://aistudio.google.com/apikey
- Documentation : https://ai.google.dev/gemini-api/docs/file-upload
- API de fichiers : https://ai.google.dev/gemini-api/docs/files
- Formats pris en charge : Images, audio, vidéo, documents (voir tableau ci-dessus)