API de Arquivos Gemini
Faça upload e gerencie arquivos para uso com modelos Gemini através de scripts executáveis, suportando imagens, áudio, vídeo, PDFs e outros tipos de arquivo.
Quando Usar Esta Habilidade
Use esta habilidade quando precisar:
- Enviar imagens para análise multimodal
- Enviar vídeos para processamento de conteúdo
- Enviar PDFs para análise de documentos
- Enviar áudio para transcrição ou processamento
- Pré-enviar arquivos para operações em lote
- Verificar status de processamento de arquivos
- Listar e gerenciar arquivos enviados
- Usar arquivos com outras habilidades Gemini (texto, imagem, etc.)
Scripts Disponíveis
scripts/upload.py
Finalidade: Enviar arquivos para a API de Arquivos Gemini
Quando usar:
- Enviar qualquer arquivo para processamento Gemini
- Preparar arquivos para geração multimodal
- Enviar documentos para análise
- Preparação de arquivos em lote
Principais parâmetros:
| Parâmetro | Descrição | Exemplo |
|---|---|---|
path | Caminho do arquivo (obrigatório) | image.jpg |
--name, -n | Nome de exibição | "meu-documento" |
--wait, -w | Aguardar processamento | Flag |
Saída: Nome do arquivo, URI e informações de status
Fluxos de Trabalho
Fluxo 1: Upload Básico de Arquivo
python scripts/upload.py image.jpg
- Melhor para: Uploads rápidos, arquivos simples
- Saída: Nome do arquivo e URI para uso na API
- Estado: PROCESSING ou ACTIVE
Fluxo 2: Upload com Nome Personalizado
python scripts/upload.py document.pdf --name "Relatório Trimestral Q4 2026"
- Melhor para: Organizar arquivos, rastrear uploads
- Use quando: O nome original do arquivo não for descritivo o suficiente
- O nome de exibição aparece nas listagens de arquivos
Fluxo 3: Upload e Aguardar Processamento
python scripts/upload.py video.mp4 --wait
- Melhor para: Arquivos grandes, vídeos, áudio
- Aguarda até que o arquivo esteja no estado ACTIVE
- Use quando: Você precisa usar o arquivo imediatamente após o upload
Fluxo 4: Upload de Imagem para Análise
# 1. Fazer upload da imagem
python scripts/upload.py photo.png --name "foto-do-produto"
# 2. Usar com gemini-text para análise
python skills/gemini-text/scripts/generate.py "Descreva esta imagem" --image photo.png
- Melhor para: Análise de imagem, legendagem, perguntas e respostas visuais
- Combina com: gemini-text para processamento multimodal
Fluxo 5: Upload de PDF para Extração de Conteúdo
# 1. Fazer upload do PDF
python scripts/upload.py artigo-cientifico.pdf --name "Artigo-Pesquisa-IA" --wait
# 2. Extrair conteúdo com gemini-text
python skills/gemini-text/scripts/generate.py "Extraia as principais conclusões deste documento" --image artigo-cientifico.pdf
- Melhor para: Processamento de documentos, extração de conteúdo
- Combina com: gemini-text para análise
Fluxo 6: Upload de Múltiplos Arquivos para Lote
# 1. Enviar múltiplos arquivos
for file in *.jpg; do
python scripts/upload.py "$file"
done
# 2. Criar job em lote usando os arquivos enviados (habilidade gemini-batch)
- Melhor para: Preparar arquivos para processamento em lote
- Combina com: gemini-batch para operações em massa
Fluxo 7: Upload de Áudio para Transcrição
# 1. Fazer upload do áudio
python scripts/upload.py entrevista.mp3 --name "entrevista-001" --wait
# 2. Processar com gemini-text (se a transcrição estiver disponível)
python skills/gemini-text/scripts/generate.py "Transcreva e resuma este áudio" --image entrevista.mp3
- Melhor para: Processamento de áudio, transcrição, análise de podcasts
- Combina com: gemini-text para análise de áudio
Fluxo 8: Upload de Vídeo para Análise de Conteúdo
# 1. Fazer upload do vídeo (pode levar tempo)
python scripts/upload.py demonstracao-produto.mp4 --name "video-demonstracao" --wait
# 2. Analisar com gemini-text
python skills/gemini-text/scripts/generate.py "Analise este vídeo de demonstração do produto" --image demonstracao-produto.mp4
- Melhor para: Análise de vídeo, sumarização de conteúdo
- Nota: Vídeos podem exigir tempo significativo de processamento
Referência de Parâmetros
Tipos de Arquivo Suportados
| Tipo | Extensões | Tamanho Máximo | Tempo de Processamento |
|---|---|---|---|
| Imagens | jpg, jpeg, png, gif, webp | 20MB | Segundos |
| Áudio | mp3, wav, aac, flac | 25MB | Segundos-minutos |
| Vídeo | mp4, mov, avi, webm | 2GB | Minutos-horas |
| Documentos | pdf, txt | 50MB | Segundos-minutos |
Tipos MIME
O script detecta automaticamente com base na extensão:
- Imagens: image/jpeg, image/png, image/gif, image/webp
- Áudio: audio/mpeg, audio/wav
- Vídeo: video/mp4, video/quicktime, video/webm
- Documentos: application/pdf, text/plain
Estados do Arquivo
| Estado | Descrição | Pronto para Uso |
|---|---|---|
PROCESSING | O arquivo está sendo analisado | Não |
ACTIVE | O arquivo está pronto | Sim |
FAILED | O processamento falhou | Não |
Interpretação da Saída
Resposta de Upload
Enviando photo.png...
Enviado: files/abc123...
URI: gs://generation-tmp/abc123...
Estado: PROCESSING
- Nome do arquivo: Use em chamadas de API
- URI: Referência interna do Google Cloud Storage
- Estado: PROCESSING = aguarde, ACTIVE = pronto
Com Flag --wait
Enviando video.mp4...
Enviado: files/xyz789...
URI: gs://generation-tmp/xyz789...
Estado: PROCESSING
Aguardando processamento...
Ainda processando...
Arquivo pronto!
- O script faz polling até que o estado seja ACTIVE
- Use para arquivos grandes que requerem processamento
- Pode levar minutos para vídeos
Usando Arquivos Enviados
Após o upload, faça referência ao arquivo pelo nome:
# Com gemini-text
python skills/gemini-text/scripts/generate.py "Analisar" --image <caminho-do-arquivo-enviado>
Problemas Comuns
"google-genai não instalado"
pip install google-genai
"Arquivo não encontrado"
- Verifique se o caminho do arquivo está correto
- Use caminhos absolutos se os relativos falharem
- Verifique se a extensão do arquivo corresponde aos tipos suportados
"Arquivo muito grande"
- Verifique os limites de tamanho para o tipo de arquivo
- Comprima imagens/vídeos, se possível
- Divida arquivos grandes em partes menores
"Tipo de arquivo não suportado"
- Verifique as extensões suportadas
- Converta para um formato suportado, se possível
- Imagens: jpg, png, gif, webp
- Vídeos: mp4, mov, avi, webm
"Falha no processamento"
- Verifique se o arquivo não está corrompido
- Tente reenviar o arquivo
- Verifique se o formato do arquivo é válido
- Verifique os limites de cota da API
"Arquivo ainda processando" (sem --wait)
- O estado do arquivo é PROCESSING, não ACTIVE
- Use a flag
--waitou verifique o status mais tarde - Arquivos grandes (especialmente vídeos) levam tempo
- O processamento pode levar de minutos a horas
Melhores Práticas
Estratégia de Upload
- Use
--waitpara arquivos que usará imediatamente - Pule
--waitpara uploads em lote para economizar tempo - Use
--namedescritivo para organização - Mantenha o controle dos nomes de arquivo para uso posterior
Organização de Arquivos
- Use convenções de nomenclatura consistentes
- Inclua datas ou versões nos nomes
- Agrupe arquivos relacionados
- Documente os nomes de arquivo no seu código
Dicas de Desempenho
- Faça upload de múltiplos arquivos em paralelo (processos separados)
- Pré-envie arquivos para operações em lote
- Verifique o estado do arquivo antes de usar em chamadas de API
- Exclua arquivos antigos para gerenciar armazenamento
Tratamento de Erros
- Verifique o estado de retorno após o upload
- Repita uploads com falha
- Verifique a integridade do arquivo antes do upload
- Registre nomes de arquivo para trilhas de auditoria
Integração com Outras Habilidades
- gemini-text: Análise multimodal, processamento de documentos
- gemini-image: Gerar imagens com base em referência enviada
- gemini-batch: Usar arquivos enviados em jobs em lote
- gemini-embeddings: Criar embeddings a partir do conteúdo de arquivos
Ciclo de Vida do Arquivo
- Upload → PROCESSING → ACTIVE → Use na API
- Exclua arquivos antigos para liberar armazenamento
- Arquivos podem expirar após um determinado período
- Baixe arquivos importantes para backup
Habilidades Relacionadas
- gemini-text: Analisar arquivos enviados com geração de texto
- gemini-image: Criar imagens com base em referências enviadas
- gemini-batch: Usar arquivos enviados em processamento em lote
- gemini-embeddings: Gerar embeddings a partir do conteúdo de arquivos
Referência Rápida
# Upload básico
python scripts/upload.py image.jpg
# Com nome personalizado
python scripts/upload.py document.pdf --name "Meu Documento"
# Aguardar processamento
python scripts/upload.py video.mp4 --wait
# Múltiplos arquivos
for file in *.jpg; do python scripts/upload.py "$file"; done
API de Gerenciamento de Arquivos
Embora não esteja nos scripts, você também pode gerenciar arquivos via Python:
from google import genai
client = genai.Client()
# Listar todos os arquivos
for file in client.files.list():
print(f"{file.name}: {file.display_name} ({file.state})")
# Obter informações do arquivo
file = client.files.get(name="files/abc123...")
print(f"Estado: {file.state}")
# Excluir arquivo
client.files.delete(name="files/abc123...")
Referência
- Obter chave de API: https://aistudio.google.com/apikey
- Documentação: https://ai.google.dev/gemini-api/docs/file-upload
- API de Arquivos: https://ai.google.dev/gemini-api/docs/files
- Formatos suportados: Imagens, áudio, vídeo, documentos (veja tabela acima)