majiayu000/claude-skill-registry

Gemini File API

Faça upload e gerencie arquivos para uso com modelos Gemini através de scripts executáveis, suportando imagens, áudio, vídeos, PDFs e outros tipos de arquivo.

Quando Usar Esta Skill

Use esta skill 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 o status do processamento de arquivos
• Listar e gerenciar arquivos enviados
• Usar arquivos com outras skills Gemini (texto, imagem, etc.)

Scripts Disponíveis

scripts/upload.py

Propósito: Enviar arquivos para a API Gemini File

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

Parâmetros principais:

Parâmetro	Descrição	Exemplo
path	Caminho do arquivo (obrigatório)	image.jpg
--name, -n	Nome de exibição	"my-document"
--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 o arquivo ficar no estado ACTIVE
• Use quando: Precisar usar o arquivo imediatamente após o upload

Fluxo 4: Upload de Imagem para Análise

# 1. Enviar imagem
python scripts/upload.py photo.png --name "foto-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. Enviar PDF
python scripts/upload.py artigo-pesquisa.pdf --name "Artigo-IA-Pesquisa" --wait

# 2. Extrair conteúdo com gemini-text
python skills/gemini-text/scripts/generate.py "Extraia as principais conclusões deste documento" --image artigo-pesquisa.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 vários arquivos
for file in *.jpg; do
    python scripts/upload.py "$file"
done

# 2. Criar job em lote usando arquivos enviados (skill 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. Enviar áudio
python scripts/upload.py entrevista.mp3 --name "entrevista-001" --wait

# 2. Processar com gemini-text (se transcrição 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. Enviar vídeo (pode levar tempo)
python scripts/upload.py demo-produto.mp4 --name "video-demo" --wait

# 2. Analisar com gemini-text
python skills/gemini-text/scripts/generate.py "Analise este vídeo de demonstração do produto" --image demo-produto.mp4

• Melhor para: Análise de vídeo, sumarização de conteúdo
• Nota: Vídeos podem exigir tempo de processamento significativo

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 a minutos
Vídeo	mp4, mov, avi, webm	2GB	Minutos a horas
Documentos	pdf, txt	50MB	Segundos a 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 = aguardar, ACTIVE = pronto

Com a Flag --wait

Enviando video.mp4...
Enviado: files/xyz789...
URI: gs://generation-tmp/xyz789...
Estado: PROCESSING
Aguardando processamento...
Ainda processando...
Arquivo pronto!

• O script consulta até o estado ser ACTIVE
• Use para arquivos grandes que precisam de processamento
• Pode levar minutos para vídeos

Usando Arquivos Enviados

Uma vez enviado, referencie o arquivo pelo nome:

# Com gemini-text
python skills/gemini-text/scripts/generate.py "Analise" --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 caminhos 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 --wait ou 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 --wait para arquivos que usará imediatamente
• Pule --wait para uploads em lote para economizar tempo
• Use --name descritivo para organização
• Mantenha registro dos nomes dos arquivos 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 dos arquivos em seu código

Dicas de Performance

• Envie vários 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 retornado após o upload
• Repita uploads com falha
• Verifique a integridade do arquivo antes do upload
• Registre nomes de arquivos para trilhas de auditoria

Integração com Outras Skills

• 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 do arquivo

Ciclo de Vida do Arquivo

• Upload → PROCESSING → ACTIVE → Uso na API
• Exclua arquivos antigos para liberar armazenamento
• Arquivos podem expirar após determinado período
• Baixe arquivos importantes para backup

Skills 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 do arquivo

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

# Vários 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
• File API: https://ai.google.dev/gemini-api/docs/files
• Formatos suportados: Imagens, áudio, vídeo, documentos (veja tabela acima)