Gemini

Visão geral

O Google Gemini é uma família de modelos de IA multimodal do Google com suporte a geração de texto, imagem, vídeo, áudio e embeddings. Com a integração Gemini no SquadOS, seus agentes podem gerar conteúdo com os modelos Gemini Flash e Pro, criar imagens e vídeos via Veo, calcular embeddings para busca semântica e muito mais — tudo diretamente nos seus fluxos de trabalho.

• Documentação na Composio: docs.composio.dev/toolkits/gemini

Autenticação

Esta ferramenta não requer autenticação (NO_AUTH).

Campo	Obrigatório	Descrição
N/A	N/A	Nenhuma credencial necessária.

Como conectar no SquadOS

1. Acesse Ferramentas no menu lateral (/admin/tools).
2. Abra a aba Disponíveis e procure por Gemini.
3. Clique no card para abrir o modal de detalhes e em Ativar — a ferramenta vai direto para a lista de ativas, sem etapa de login. (Detalhes do fluxo em Ferramentas da Organização.)

Ações disponíveis

Contar tokens (Gemini)

GEMINI_COUNT_TOKENS

Conta o número de tokens em um texto usando a tokenização do Gemini. Útil para estimar custos, verificar limites de entrada e otimizar prompts antes de fazer chamadas de API.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
text	string	Sim	Texto para contar os tokens.
model	string	Não	Modelo a usar para contagem de tokens. Deve ser um modelo que suporte o método countTokens. Use a ação ListModels para ver os modelos disponíveis e seus métodos suportados.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Gerar embeddings (Gemini)

GEMINI_EMBED_CONTENT

Gera embeddings de texto usando os modelos de embedding do Gemini. Converte texto em vetores numéricos para busca semântica, comparação de similaridade, agrupamento e tarefas de classificação.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
text	string	Sim	Conteúdo de texto para gerar os embeddings.
model	string	Não	Modelo de embedding a usar. Opções: text-embedding-004 (768 dimensões, padrão), gemini-embedding-001 (3072 dimensões, mais recente).
title	string	Não	Título opcional para o conteúdo. Use com task_type='RETRIEVAL_DOCUMENT' para melhorar a qualidade do embedding em busca de documentos.
task_type	string	Não	Especifica o caso de uso pretendido para otimizar o embedding. Opções: RETRIEVAL_QUERY (consultas de busca), RETRIEVAL_DOCUMENT (documentos a serem buscados), SEMANTIC_SIMILARITY (similaridade de texto), CLASSIFICATION (categorização), CLUSTERING (agrupamento), QUESTION_ANSWERING (correspondência pergunta-documento). Nota: alguns tipos de tarefa como CODE_RETRIEVAL_QUERY podem ser suportados apenas por certos modelos.
output_dimensionality	integer	Não	Trunca o embedding para este número de dimensões. Suportado apenas pelo modelo gemini-embedding-001. Valores recomendados: 768, 1536 ou 3072. Dimensões menores reduzem o armazenamento, mas podem afetar a qualidade.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Gerar conteúdo (Gemini)

GEMINI_GENERATE_CONTENT

Gera conteúdo de texto ou áudio de fala a partir de prompts usando os modelos Gemini. Suporta modelos de geração de texto (Gemini Flash, Pro) e modelos de texto-para-fala com parâmetros configuráveis. O texto gerado fica aninhado em results[i].response.data.text. A saída pode estar envolvida em blocos de markdown (ex.: ```html...```) ou precedida de prosa explicativa; remova esses elementos antes de gravar em arquivo ou renderizar.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
model	string	Não	Modelo a usar para geração. Modelos de texto: gemini-2.5-flash (padrão, rápido e eficiente), gemini-2.5-pro (raciocínio avançado), gemini-2.0-flash (geração anterior), gemini-2.0-flash-lite (otimizado para custo). Modelos de texto-para-fala: gemini-2.5-flash-preview-tts (baixa latência), gemini-2.5-pro-preview-tts (alta qualidade). Nota: modelos TTS exigem o parâmetro voice_name e retornam dados de áudio em vez de texto.
top_k	integer	Não	Parâmetro de amostragem top-k.
top_p	number	Não	Parâmetro de amostragem por núcleo (0.0 a 1.0).
prompt	string	Sim	OBRIGATÓRIO. O prompt de texto para geração de conteúdo. Este campo deve ser fornecido. Exemplo: Write a short poem about the ocean ou Explain quantum computing in simple terms. Para modelos TTS, inclua instruções de estilo no prompt (ex.: Say cheerfully: Hello!).
voice_name	string	Não	Vozes pré-construídas disponíveis para geração de texto-para-fala. Lista completa de 30 vozes oficiais do Gemini TTS disponível em: https://ai.google.dev/gemini-api/docs/speech-generation
temperature	number	Não	Controla a aleatoriedade (0.0 a 2.0).
stop_sequences	array	Não	Sequências onde a geração deve parar.
safety_settings	array	Não	Configurações de filtro de segurança.
max_output_tokens	integer	Não	Número máximo de tokens a gerar. Se o finishReason da resposta for MAX_TOKENS, a saída foi truncada; reduza o escopo do prompt ou aumente este valor e gere novamente.
system_instruction	string	Não	Instrução de sistema para guiar o comportamento do modelo.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Gerar imagem (Nano Banana)

GEMINI_GENERATE_IMAGE

Gera imagens a partir de prompts de texto usando os modelos Gemini (Nano Banana). Suporta os modelos: gemini-2.5-flash-image (estável e rápido), gemini-3-pro-image-preview (Nano Banana Pro — avançado com resolução 4K, modo de raciocínio, até 14 imagens de referência) e gemini-2.0-flash-exp-image-generation (Flash 2.0 experimental). Retorna uma imagem por chamada; as imagens são enviadas ao S3. Analise a resposta em data.image.s3url ou na entrada de tipo texto em data.content — prefira a URL para evitar blobs base64. Sempre valide o s3url antes de considerar a chamada bem-sucedida; uma resposta 200 pode conter apenas texto sem imagem. Armazene o s3url imediatamente, pois as URLs podem expirar. Os formatos de saída são apenas raster (JPG/PNG/WebP); solicite PNG para transparência. O uso concorrente pode disparar HTTP 429/RESOURCE_EXHAUSTED — mantenha a concorrência em no máximo 3 e use backoff exponencial (1s→2s→4s, ~5 tentativas).

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
model	string	Não	Modelo a usar para geração de imagens. Opções: gemini-2.5-flash-image (estável e rápido), gemini-3-pro-image-preview (avançado com 4K e modo de raciocínio), gemini-2.0-flash-exp-image-generation (Flash 2.0 experimental).
top_k	integer	Não	Parâmetro de amostragem top-k.
top_p	number	Não	Parâmetro de amostragem por núcleo (0.0 a 1.0).
prompt	string	Sim	Prompt de texto para geração de imagem. Conteúdo sensível, com marcas registradas ou explícito dispara HTTP 400 (PROHIBITED_CONTENT ou IMAGE_RECITATION) sem imagem retornada — reformule para linguagem neutra e compatível com as políticas em vez de retentar prompts idênticos.
timeout	number	Não	Tempo limite da requisição em segundos. Padrão: 300 segundos (5 minutos). Aumente para prompts complexos ou imagens de alta resolução. Mínimo: 120 segundos, máximo: 600 segundos.
image_size	string	Não	Resolução de saída (apenas para gemini-3-pro-image-preview). Opções: 1K, 2K, 4K.
temperature	number	Não	Controla a aleatoriedade (0.0 a 2.0).
aspect_ratio	string	Não	Proporção da imagem gerada. Valores aceitos: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9. Não suportado pelo modelo gemini-2.0-flash-exp-image-generation. Strings não suportadas falharão ou assumirão 1:1 silenciosamente.
safety_settings	array	Não	Configurações de filtro de segurança. Lista de objetos especificando categorias de conteúdo e níveis de limite. Cada configuração requer category (HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT ou HARM_CATEGORY_DANGEROUS_CONTENT) e threshold (BLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE ou BLOCK_ONLY_HIGH).
max_output_tokens	integer	Não	Número máximo de tokens a gerar (máx. 32.768). Para geração de imagens, as imagens consomem tokens com base na resolução: 1K/2K consomem 1.120 tokens, 4K consome 2.000 tokens. Se definido muito baixo, a API pode retornar MAX_TOKENS sem imagem. Se não especificado, a API usa seu padrão, que é suficiente para geração de imagens.
system_instruction	string	Não	Instrução de sistema para guiar o comportamento de geração de imagens.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Gerar vídeos (Veo)

GEMINI_GENERATE_VIDEOS

Gera vídeos a partir de prompts de texto usando os modelos Veo do Google. Retorna um operation_name para rastreamento; passe-o exatamente como retornado (sem edições) para GEMINI_WAIT_FOR_VIDEO ou GEMINI_GET_VIDEOS_OPERATION. Os jobs levam de 30 a 180+ segundos; aguarde 10s antes da primeira consulta e depois consulte a cada 10–30s (permitindo até 12 min). Resultados bem-sucedidos incluem data.video_file.s3url — a ausência do s3url indica falha. Se done=true mas sem video_file, verifique raiMediaFilteredReasons (bloqueio de segurança); revise o prompt e gere novamente. Apenas texto; não aceita imagens como entrada. Máx. 3–5 jobs simultâneos; 429 RESOURCE_EXHAUSTED requer backoff exponencial. Para novas tentativas, sempre inicie uma nova chamada — nunca reutilize um operation_name de job com falha.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
seed	integer	Não	Valor de semente para reprodutibilidade. IMPORTANTE: suportado apenas pelos modelos Veo 3/3.1 (VEO_3, VEO_3_FAST, VEO_3_1, VEO_3_1_FAST). O VEO_2 NÃO suporta semente — usar com VEO_2 resultará em erro de validação.
model	string	Não	Modelo Veo para geração de vídeo. Valores disponíveis: VEO_3 (padrão, recomendado), VEO_2, VEO_3_FAST, VEO_3_1 (mais recente), VEO_3_1_FAST (mais recente). Evite variantes de modelo preview (ex.: *generate-preview*) — elas falham ao produzir URIs para download. Use apenas IDs estáveis: veo-2.0-generate-001 ou veo-3.0-generate-001.
prompt	string	Sim	Prompt de texto para geração de vídeo com o Veo. Deve ser uma string não vazia descrevendo o vídeo a gerar.
resolution	string	Não	Resoluções suportadas para geração de vídeo: 720p ou 1080p.
aspect_ratio	string	Não	Proporções suportadas para geração de vídeo: 16:9 ou 9:16.
negative_prompt	string	Não	Texto descrevendo o conteúdo a evitar no vídeo gerado (ex.: cartoon, drawing, low quality).
duration_seconds	integer	Não	Durações de vídeo suportadas em segundos. Restrições por modelo: Veo 2 suporta 5, 6, 7 ou 8 segundos (4 segundos NÃO suportado); modelos Veo 3/3.1 suportam 4, 6 ou 8 segundos (5 e 7 segundos NÃO suportados).
person_generation	string	Não	Configurações de segurança para geração de pessoas. Restrições por modelo: Veo 2 suporta DONT_ALLOW, ALLOW_ADULT e ALLOW_ALL; modelos Veo 3/3.1 suportam apenas ALLOW_ALL (requer acesso à lista de permissões).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Verificar operação de vídeo (Veo) (Descontinuado)

GEMINI_GET_VIDEOS_OPERATION

DESCONTINUADO: use WaitForVideo no lugar. Verifica o status de uma operação de geração de vídeo com o Veo. Use o operation_name de GenerateVideos para acompanhar o progresso. Aguarde alguns segundos após iniciar GenerateVideos antes da primeira chamada para evitar OPERATION_NOT_FOUND. Consulte em intervalos de 10–30s; use backoff exponencial em HTTP 429 RESOURCE_EXHAUSTED; limite o polling total a ~15 minutos. Considere completo quando done=true E um URI de vídeo válido estiver presente; done=true sem video_file indica que o filtro de segurança bloqueou a saída — inspecione raiMediaFilteredReasons e reformule o prompt. A URL do vídeo fica em generatedSamples[].video.uri — persista imediatamente, pois as URLs têm tempo limitado. Mantenha o polling paralelo em 3–5 chamadas para evitar limites de taxa. Se WaitForVideo expirar, continue o polling aqui com o mesmo operation_name em vez de iniciar um novo job GenerateVideos.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
operation_name	string	Sim	Nome do recurso da operação retornado por GEMINI_GENERATE_VIDEOS. Aceita o nome completo models/{model}/operations/{operation_id} ou apenas o ID da operação. Se apenas o ID for fornecido, será expandido para usar o modelo padrão veo-3.0-generate-001. Passe exatamente como retornado — não truncar nem editar. Nunca reutilize um operation_name de um job com falha; inicie uma nova chamada GenerateVideos.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar modelos (Gemini API)

GEMINI_LIST_MODELS

Lista os modelos Gemini e Veo disponíveis com suas capacidades e limites. Útil para descobrir modelos suportados e suas funcionalidades antes de fazer requisições de geração. Antes de chamar ferramentas de geração de vídeo, verifique a disponibilidade do modelo aqui — modelos Veo preview (ex.: veo-3.0-generate-preview) podem estar indisponíveis ou retornar URIs de vídeo ausentes; prefira modelos estáveis como veo-2.0-generate-001.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
page_size	integer	Não	Número máximo de modelos a retornar por página (padrão: 50, máx.: 1000).
page_token	string	Não	Token da resposta anterior (nextPageToken) para recuperar a próxima página.
filter_prefix	string	Não	Filtra modelos por prefixo de nome (lado do cliente). Deixe vazio para obter todos os modelos.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Aguardar e baixar vídeo (Veo)

GEMINI_WAIT_FOR_VIDEO

Consulta uma operação de geração de vídeo Veo até a conclusão e então baixa e retorna o vídeo como um FileDownloadable. A geração leva de 30 a 120+ segundos (até ~10–12 min); esperas longas são normais, não indicam falha. Após a conclusão, a URL fica aninhada em data.video_file.s3url — valide que não está vazia antes do uso downstream. Uma resposta done=true sem um s3url válido indica rejeição pelo filtro de segurança (verifique raiMediaFilteredReasons) ou esgotamento de cota — ajuste o prompt e gere novamente. Em caso de timeout, use GEMINI_GET_VIDEOS_OPERATION com backoff incremental antes de iniciar um novo job. Mantenha jobs paralelos em 3–5 para evitar erros 429 RESOURCE_EXHAUSTED.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
operation_name	string	Sim	Nome completo da operação retornado por GEMINI_GENERATE_VIDEOS. Formato: models/<model-id>/operations/<operation-id> onde <operation-id> é uma string alfanumérica (ex.: models/veo-3.0-generate-001/operations/m8dl4dtqqzg8). IMPORTANTE: NÃO use valores de placeholder como ... — use a string exata do operation_name da resposta de geração de vídeos. CRÍTICO: deve ser de uma operação generate-video (modelos VEO_2, VEO_3, VEO_3_FAST), NÃO de operações generate-preview (modelos VEO_3_1, VEO_3_1_FAST). Não reutilize operation_name de um job GEMINI_GENERATE_VIDEOS com falha — sempre inicie uma nova chamada GEMINI_GENERATE_VIDEOS para novas tentativas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.