API Gemini File
Téléversez et gérez des fichiers destinés aux modèles Gemini à l'aide de 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éverser des images pour une analyse multimodale
- Téléverser des vidéos pour le traitement de contenu
- Téléverser des PDF pour l'analyse de documents
- Téléverser de l'audio pour la transcription ou le 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 Gemini File
Quand l'utiliser :
- Pour téléverser tout fichier destiné au traitement Gemini
- Pour préparer des fichiers pour la génération multimodale
- Pour téléverser des documents à analyser
- 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 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 l'utilisation 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 : Organisation des fichiers, suivi des 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 l'analyse
python skills/gemini-text/scripts/generate.py "Décris cette image" --image photo.png
- Idéal pour : Analyse d'images, légendes, questions-réponses visuelles
- 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-Recherche-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
- Combine avec : gemini-text pour l'analyse
Workflow 6 : Téléversement de plusieurs fichiers pour un lot
# 1. Téléverser 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éversés (compétence gemini-batch)
- Idéal pour : Préparer des fichiers pour le traitement par lots
- Combine avec : gemini-batch pour les opérations en masse
Workflow 7 : Téléversement d'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 podcasts
- Combine avec : gemini-text pour l'analyse audio
Workflow 8 : Téléversement de 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
- 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 sorties
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 = attendez, 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 quelques 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 "Analyse" --image <chemin-du-fichier-televerse>
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 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éverser le fichier
- Vérifiez que le format du fichier est valide
- Vérifiez les limites de quota 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 à quelques heures
Bonnes pratiques
Stratégie de téléversement
- Utilisez
--waitpour les fichiers que vous utiliserez immédiatement - Ignorez
--waitpour les téléversements par lots afin de gagner du temps - Utilisez des noms
--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éversez plusieurs fichiers en parallèle (processus séparés)
- Pré-téléversez des 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
- 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 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 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érences
- Obtenir une clé API : https://aistudio.google.com/apikey
- Documentation : https://ai.google.dev/gemini-api/docs/file-upload
- API File : https://ai.google.dev/gemini-api/docs/files
- Formats pris en charge : Images, audio, vidéo, documents (voir tableau ci-dessus)