API de Arquivos Gemini

Faça upload e gerencie arquivos para uso com os modelos Gemini por meio de scripts executáveis, suportando imagens, áudio, vídeo, PDFs e outros tipos de arquivo.

Quando Usar Esta Skill

Use esta skill quando precisar:

Fazer upload de imagens para análise multimodal
Fazer upload de vídeos para processamento de conteúdo
Fazer upload de PDFs para análise de documentos
Fazer upload de áudio para transcrição ou processamento
Pré-enviar arquivos para operações em lote
Verificar o status de processamento de arquivos
Listar e gerenciar arquivos enviados
Usar arquivos com outras skills Gemini (texto, imagem, etc.)

Scripts Disponíveis

scripts/upload.js

Propósito: Fazer upload de 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

Parâmetros principais:

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

Workflows

Workflow 1: Upload Básico de Arquivo

node scripts/upload.js imagem.jpg

Melhor para: Uploads rápidos, arquivos simples
Saída: Nome do arquivo e URI para uso na API
Estado: PROCESSING ou ACTIVE

Workflow 2: Upload com Nome Personalizado

node scripts/upload.js documento.pdf --name "Relatório Trimestral Q4 2026"

Melhor para: Organizar arquivos, rastrear uploads
Use quando: O nome original do arquivo não é descritivo o suficiente
O nome de exibição aparece nas listagens de arquivos

Workflow 3: Upload e Aguardar Processamento

node scripts/upload.js 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

Workflow 4: Upload de Imagem para Análise

# 1. Fazer upload da imagem
node scripts/upload.js foto.png --name "foto-produto"

# 2. Usar com gemini-text para análise
node skills/gemini-text/scripts/generate.js "Descreva esta imagem" --image foto.png

Melhor para: Análise de imagem, legendagem, perguntas e respostas visuais
Combina com: gemini-text para processamento multimodal

Workflow 5: Upload de PDF para Extração de Conteúdo

# 1. Fazer upload do PDF
node scripts/upload.js artigo-cientifico.pdf --name "Artigo-IA-Pesquisa" --wait

# 2. Extrair conteúdo com gemini-text
node skills/gemini-text/scripts/generate.js "Extraia as principais descobertas deste documento" --image artigo-cientifico.pdf

Melhor para: Processamento de documentos, extração de conteúdo
Combina com: gemini-text para análise

Workflow 6: Upload de Múltiplos Arquivos para Lote

# 1. Fazer upload de múltiplos arquivos
for file in *.jpg; do
    node scripts/upload.js "$file"
done

# 2. Criar job em lote usando os arquivos enviados (skill gemini-batch)

Melhor para: Preparar arquivos para processamento em lote
Combina com: gemini-batch para operações em massa

Workflow 7: Upload de Áudio para Transcrição

# 1. Fazer upload do áudio
node scripts/upload.js entrevista.mp3 --name "entrevista-001" --wait

# 2. Processar com gemini-text (se transcrição estiver disponível)
node skills/gemini-text/scripts/generate.js "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

Workflow 8: Upload de Vídeo para Análise de Conteúdo

# 1. Fazer upload do vídeo (pode levar tempo)
node scripts/upload.js demonstracao-produto.mp4 --name "video-demo" --wait

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

Melhor para: Análise de vídeo, resumo 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áx.	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 foto.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 a 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 exigem 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
node skills/gemini-text/scripts/generate.js "Analise" --image <caminho-do-arquivo-enviado>

Problemas Comuns

"google-genai não instalado"

npm install @google/genai@latest dotenv@latest

"Arquivo não encontrado"

Verifique se o caminho do arquivo está correto
Use caminhos absolutos se os relativos falharem
Confira 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
Confira os limites de cota da API

"Arquivo ainda em processamento" (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 minutos a horas

Melhores Práticas

Estratégia de Upload

Use --wait para arquivos que você usará imediatamente
Pule --wait para uploads em lote para economizar tempo
Use --name descritivo para organização
Mantenha o controle 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 Desempenho

Faça upload de vários arquivos em paralelo (processos separados)
Pré-envie arquivos para operações em lote
Verifique o estado do arquivo antes de usá-lo 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 os nomes dos 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
Os arquivos podem expirar após um 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
node scripts/upload.js imagem.jpg

# Com nome personalizado
node scripts/upload.js documento.pdf --name "Meu Documento"

# Aguardar processamento
node scripts/upload.js video.mp4 --wait

# Múltiplos arquivos
for file in *.jpg; do node scripts/upload.js "$file"; done

API de Gerenciamento de Arquivos

Embora não esteja nos scripts, você também pode gerenciar arquivos via JavaScript:

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Listar todos os arquivos
for await (const file of client.files.list()) {
  console.log(`${file.name}: ${file.displayName} (${file.state})`);
}

// Obter informações do arquivo
const file = await client.files.get({ name: "files/abc123..." });
console.log(`Estado: ${file.state}`);

// Excluir arquivo
await 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 a tabela acima)

Perguntar na sua IA favorita

Documentação