Communitygithub.com

API de Arquivos do Gemini

Faça upload e gerencie arquivos usando a API de Arquivos do Google Gemini via scripts. Suporta upload de imagens, áudio, vídeo, PDFs e outros tipos de arquivo para uso com modelos Gemini.

O que é API de Arquivos do Gemini?

Esta skill oferece uma interface prática para fazer upload e gerenciar arquivos na API de Arquivos do Google Gemini, permitindo que você prepare e envie diversos tipos de mídia para processamento por modelos Gemini. Ela é essencial para tarefas como análise multimodal de imagens, transcrição de áudio, extração de conteúdo de PDFs e processamento de vídeos, integrando-se perfeitamente com outras skills do ecossistema Gemini (como gemini-text, gemini-image e gemini-batch). A skill fornece scripts de linha de comando que aceitam parâmetros como caminho do arquivo, nome de exibição e uma flag `--wait` para aguardar o processamento, retornando o URI e o estado do arquivo. Suporta uma ampla gama de formatos, incluindo imagens, áudio, vídeo e documentos, com limites de tamanho variados. O fluxo de trabalho típico envolve o upload do arquivo, verificação do estado (PROCESSING, ACTIVE, FAILED) e, em seguida, o uso do arquivo em outras chamadas de API Gemini para análise ou geração de conteúdo.

Funciona com✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/data/gemini-files

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que API de Arquivos do Gemini faz?

Faça upload e gerencie arquivos para uso com 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 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 de Arquivos do 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âmetroDescriçãoExemplo
pathCaminho do arquivo (obrigatório)image.jpg
--name, -nNome de exibição"meu-documento"
--wait, -wAguardar processamentoFlag

Saída: Nome do arquivo, URI e informações de status

Fluxos de Trabalho

Fluxo de Trabalho 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 de Trabalho 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 de Trabalho 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ê precisar usar o arquivo imediatamente após o upload

Fluxo de Trabalho 4: Upload de Imagem para Análise

# 1. Fazer upload da 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 de Trabalho 5: Upload de PDF para Extração de Conteúdo

# 1. Fazer upload do PDF
python scripts/upload.py research-paper.pdf --name "Artigo-Pesquisa-IA" --wait

# 2. Extrair conteúdo com gemini-text
python skills/gemini-text/scripts/generate.py "Extraia as principais descobertas deste documento" --image research-paper.pdf
  • Melhor para: Processamento de documentos, extração de conteúdo
  • Combina com: gemini-text para análise

Fluxo de Trabalho 6: Upload de Múltiplos Arquivos para Lote

# 1. Fazer upload de vários arquivos
for file in *.jpg; do
    python scripts/upload.py "$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

Fluxo de Trabalho 7: Upload de Áudio para Transcrição

# 1. Fazer upload do áudio
python scripts/upload.py interview.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 interview.mp3
  • Melhor para: Processamento de áudio, transcrição, análise de podcasts
  • Combina com: gemini-text para análise de áudio

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

# 1. Fazer upload do vídeo (pode levar tempo)
python scripts/upload.py product-demo.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 product-demo.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

TipoExtensõesTamanho MáximoTempo de Processamento
Imagensjpg, jpeg, png, gif, webp20MBSegundos
Áudiomp3, wav, aac, flac25MBSegundos-minutos
Vídeomp4, mov, avi, webm2GBMinutos-horas
Documentospdf, txt50MBSegundos-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

EstadoDescriçãoPronto para Uso
PROCESSINGO arquivo está sendo analisadoNão
ACTIVEO arquivo está prontoSim
FAILEDO processamento falhouNão

Interpretação da Saída

Resposta do 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 faz polling até que o estado seja ACTIVE
  • Use para arquivos grandes que exigem processamento
  • Pode levar minutos para vídeos

Usando Arquivos Enviados

Depois de 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 os 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 da 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 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 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 usar em chamadas de API
  • Exclua arquivos antigos para gerenciar o 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 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 certo período
  • Faça download de 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

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry-data

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry-data

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry-data

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry-data

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry-data

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

Habilidades Relacionadas