Explore as capacidades visuais com a API Gemini

A API Gemini pode processar imagens e vídeos, permitindo uma variedade de casos de uso interessantes para desenvolvedores. Alguns dos recursos de visão do Gemini incluem a capacidade de:

  • Adicionar legendas e responder a perguntas sobre imagens
  • Transcrever e analisar PDFs, incluindo documentos longos com uma janela de contexto de até 2 milhões de tokens
  • Descrever, segmentar e extrair informações de vídeos, incluindo frames visuais e áudio, com até 90 minutos de duração
  • Detectar objetos em uma imagem e retornar as coordenadas da caixa delimitadora

Este tutorial demonstra algumas maneiras possíveis de solicitar a API Gemini com entrada de imagens e vídeos, fornece exemplos de código e descreve as práticas recomendadas de solicitação com recursos de visão multimodal. Toda a saída é somente texto.

Antes de começar: configure o projeto e a chave de API

Antes de chamar a API Gemini, você precisa configurar seu projeto e sua chave de API.

Como usar imagens

Neste tutorial, você vai fazer upload de imagens usando a API File ou como dados inline e gerar conteúdo com base nessas imagens.

Detalhes técnicos (imagens)

O Gemini 1.5 Pro e o 1.5 Flash oferecem suporte a um máximo de 3.600 arquivos de imagem.

As imagens precisam estar em um dos seguintes tipos MIME de dados de imagem:

  • PNG - image/png
  • JPEG - image/jpeg
  • WEBP - image/webp
  • HEIC - image/heic
  • HEIF - image/heif

Cada imagem equivale a 258 tokens.

Embora não haja limites específicos para o número de pixels em uma imagem além da janela de contexto do modelo, imagens maiores são reduzidas para uma resolução máxima de 3072 x 3072, preservando a proporção original, enquanto imagens menores são aumentadas para 768 x 768 pixels. Não há redução de custo para imagens de tamanhos menores, exceto largura de banda, ou melhoria de desempenho para imagens de resolução mais alta.

Para os melhores resultados:

  • Gire as imagens para a orientação correta antes de fazer o upload.
  • Evite imagens desfocadas.
  • Se estiver usando uma única imagem, coloque o comando de texto depois dela.

Entrada de imagem

Para tamanhos de payload de imagem total de menos de 20 MB, recomendamos fazer o upload de imagens codificadas em base64 ou diretamente de arquivos de imagem armazenados localmente.

Imagens codificadas em Base64

Você pode fazer upload de URLs de imagens públicas codificando-os como payloads Base64. Recomendamos usar a biblioteca httpx para buscar os URLs de imagem. O exemplo de código abaixo mostra como fazer isso:

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const model = genAI.getGenerativeModel({ model: 'models/gemini-1.5-pro' });

const imageResp = await fetch(
    'https://upload.wikimedia.org/wikipedia/commons/thumb/8/87/Palace_of_Westminster_from_the_dome_on_Methodist_Central_Hall.jpg/2560px-Palace_of_Westminster_from_the_dome_on_Methodist_Central_Hall.jpg'
)
    .then((response) => response.arrayBuffer());

const result = await model.generateContent([
    {
        inlineData: {
            data: Buffer.from(imageResp).toString("base64"),
            mimeType: "image/jpeg",
        },
    },
    'Caption this image.',
]);
console.log(result.response.text());

Várias imagens

Para solicitar várias imagens no formato codificado em Base64, faça o seguinte:

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const model = genAI.getGenerativeModel({ model: 'models/gemini-1.5-pro' });

const imageResp1 = await fetch(IMAGE_PATH_1).then((response) => response.arrayBuffer());
const imageResp2 = await fetch(IMAGE_PATH_2).then((response) => response.arrayBuffer());

const result = await model.generateContent([
    {
        inlineData: {
            data: Buffer.from(imageResp1).toString("base64"),
            mimeType: "image/jpeg",
        },
    },
    {
        inlineData: {
            data: Buffer.from(imageResp2).toString("base64"),
            mimeType: "image/jpeg",
        },
    },
    'Generate a list of all the objects contained in both images.',
]);
console.log(result.response.text());

Fazer upload de uma imagem e gerar conteúdo

Quando a combinação de arquivos e instruções do sistema que você pretende enviar tiver mais de 20 MB, use a API File para fazer upload deles.

Use o método media.upload da API File para fazer upload de uma imagem de qualquer tamanho.

Depois de fazer o upload do arquivo, é possível fazer solicitações GenerateContent que fazem referência ao URI da API File. Selecione o modelo generativo e forneça um comando de texto e a imagem enviada.

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(
  `${mediaPath}/jetpack.jpg`,
  {
    mimeType: "image/jpeg",
    displayName: "Jetpack drawing",
  },
);
// View the response.
console.log(
  `Uploaded file ${uploadResult.file.displayName} as: ${uploadResult.file.uri}`,
);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const result = await model.generateContent([
  "Tell me about this image.",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(result.response.text());
files.js

Verificar o upload de arquivos de imagem e receber metadados

É possível verificar se a API armazenou o arquivo enviado e acessar os metadados dele chamando files.get. Somente o name (e, por extensão, o uri) são exclusivos.

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResponse = await fileManager.uploadFile(
  `${mediaPath}/jetpack.jpg`,
  {
    mimeType: "image/jpeg",
    displayName: "Jetpack drawing",
  },
);

// Get the previously uploaded file's metadata.
const getResponse = await fileManager.getFile(uploadResponse.file.name);

// View the response.
console.log(
  `Retrieved file ${getResponse.displayName} as ${getResponse.uri}`,
);
files.js

Chamar um ou mais arquivos de imagem armazenados localmente

Também é possível fazer upload dos seus próprios arquivos.

Quando a combinação de arquivos e instruções do sistema que você pretende enviar tiver mais de 20 MB, use a API File para fazer upload desses arquivos, como mostrado anteriormente. Arquivos menores podem ser chamados localmente na API Gemini:

import { GoogleGenerativeAI } from "@google/generative-ai";
import fs from "fs";

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// Converts local file information to a GoogleGenerativeAI.Part object.
function fileToGenerativePart(path, mimeType) {
  return {
    inlineData: {
      data: Buffer.from(fs.readFileSync(path)).toString("base64"),
      mimeType
    },
  };
}

// Turn images to Part objects
const filePart1 = fileToGenerativePart("jetpack.jpg", "image/jpeg")
const filePart2 = fileToGenerativePart("piranha.jpg", "image/jpeg")
const filePart3 = fileToGenerativePart("firefighter.jpg", "image/jpeg")

Essas chamadas de dados inline não incluem muitos dos recursos disponíveis na API File, como a extração de metadados de arquivos, a listagem ou a exclusão de arquivos.

Prompt com várias imagens

Você pode fornecer à API Gemini qualquer combinação de imagens e texto que se encaixe na janela de contexto do modelo. Este exemplo fornece uma solicitação de texto curta e as três imagens enviadas anteriormente.

async function run() {
  // Choose a Gemini model.
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro" });

  const prompt = "Write an advertising jingle showing how the product in the first image could solve the problems shown in the second two images.";

  const imageParts = [
    filePart1,
    filePart2,
    filePart3,
  ];

  const generatedContent = await model.generateContent([prompt, ...imageParts]);
  
  console.log(generatedContent.response.text());
}

run();

Compatibilidade com o OpenAI

É possível acessar os recursos de compreensão de imagem do Gemini usando as bibliotecas da OpenAI. Isso permite integrar o Gemini aos fluxos de trabalho atuais da OpenAI atualizando três linhas de código e usando sua chave de API Gemini. Consulte o exemplo de compreensão de imagem para ver o código que demonstra como enviar imagens codificadas como payloads Base64.

Recursos

Esta seção descreve os recursos de visão específicos do modelo Gemini, incluindo a detecção de objetos e as coordenadas da caixa delimitadora.

Extrair uma caixa delimitadora para um objeto

Os modelos do Gemini são treinados para retornar as coordenadas da caixa delimitadora como larguras ou alturas relativas no intervalo [0, 1]. Esses valores são dimensionados por 1.000 e convertidos em números inteiros. Na prática, as coordenadas representam a caixa delimitadora em uma versão de 1.000 x 1.000 pixels da imagem. Portanto, você precisará converter essas coordenadas de volta às dimensões da imagem original para mapear as caixas delimitadoras com precisão.

// filePart = ...
// filePart2 has the piranha.

async function findBox(filePart) {
  // Choose a Gemini model.
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro" });

  const prompt = "Return a bounding box for the piranha. \n [ymin, xmin, ymax, xmax]";

  const generatedContent = await model.generateContent([prompt, filePart]);
  
  console.log(generatedContent.response.text());
}

run(filePart);

O modelo retorna coordenadas da caixa delimitadora no formato [ymin, xmin, ymax, xmax]. Para converter essas coordenadas normalizadas nas coordenadas de pixel da imagem original, siga estas etapas:

  1. Divida cada coordenada de saída por 1.000.
  2. Multiplique as coordenadas x pela largura da imagem original.
  3. Multiplique as coordenadas y pela altura da imagem original.

Como usar vídeos para dar comandos

Neste tutorial, você vai fazer upload de um vídeo usando a API File e gerar conteúdo com base nessas imagens.

Detalhes técnicos (vídeo)

O Gemini 1.5 Pro e o Flash oferecem suporte a aproximadamente uma hora de dados de vídeo.

O vídeo precisa estar em um dos seguintes tipos MIME de formato de vídeo:

  • video/mp4
  • video/mpeg
  • video/mov
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

O serviço da API File extrai frames de imagens de vídeos a 1 frame por segundo (FPS) e áudio a 1 Kbps, canal único, adicionando carimbos de data/hora a cada segundo. Essas taxas estão sujeitas a mudanças no futuro para melhorias na inferência.

Os frames individuais são 258 tokens, e o áudio é de 32 tokens por segundo. Com metadados, cada segundo de vídeo se torna cerca de 300 tokens, o que significa que uma janela de contexto de 1 milhão pode caber em pouco menos de uma hora de vídeo.

Para fazer perguntas sobre locais com carimbo de data/hora, use o formato MM:SS, em que os dois primeiros dígitos representam minutos e os dois últimos dígitos representam segundos.

Para os melhores resultados:

  • Use um vídeo por comando.
  • Se você estiver usando um único vídeo, coloque o comando de texto depois dele.

Fazer upload de um arquivo de vídeo usando a API File

A API File aceita formatos de arquivo de vídeo diretamente. Este exemplo usa o curto-metragem da NASA "Jupiter's Great Red Spot Shrinks and Grows". Crédito: Centro de Voos Espaciais Goddard (GSFC)/David Ladd (2018).

"Jupiter's Great Red Spot Shrinks and Grows" está no domínio público e não mostra pessoas identificáveis. (Diretrizes de uso de imagens e mídia da NASA.)

Comece recuperando o vídeo curto:

wget https://storage.googleapis.com/generativeai-downloads/images/GreatRedSpot.mp4

Faça upload do vídeo usando a API File e imprima o URI.

// To use the File API, use this import path for GoogleAIFileManager.
// Note that this is a different import path than what you use for generating content.
// For versions lower than @google/generative-ai@0.13.0
// use "@google/generative-ai/files"
import { GoogleAIFileManager } from "@google/generative-ai/server";

// Initialize GoogleAIFileManager with your API_KEY.
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

// Upload the file and specify a display name.
const uploadResponse = await fileManager.uploadFile("GreatRedSpot.mp4", {
  mimeType: "video/mp4",
  displayName: "Jupiter's Great Red Spot",
});

// View the response.
console.log(`Uploaded file ${uploadResponse.file.displayName} as: ${uploadResponse.file.uri}`);

Verificar o upload de arquivos e o estado de verificação

Verifique se a API recebeu os arquivos chamando o método files.get.

// To use the File API, use this import path for GoogleAIFileManager.
// Note that this is a different import path than what you use for generating content.
// For versions lower than @google/generative-ai@0.13.0
// use "@google/generative-ai/files"
import { GoogleAIFileManager, FileState } from "@google/generative-ai/server";

// Initialize GoogleAIFileManager with your API_KEY.
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

// Upload the video file using the File API
// uploadResponse = ...
const name = uploadResponse.file.name;

// Poll getFile() on a set interval (10 seconds here) to check file state.
let file = await fileManager.getFile(name);
while (file.state === FileState.PROCESSING) {
  process.stdout.write(".")
  // Sleep for 10 seconds
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  // Fetch the file from the API again
  file = await fileManager.getFile(name)
}

if (file.state === FileState.FAILED) {
  throw new Error("Video processing failed.");
}

// When file.state is ACTIVE, the file is ready to be used for inference.
console.log(`File ${file.displayName} is ready for inference as ${file.uri}`);

Com um vídeo e texto

Quando o vídeo enviado estiver no estado ACTIVE, será possível fazer solicitações GenerateContent que especifiquem o URI da API File para esse vídeo. Selecione o modelo generativo e forneça o vídeo enviado e um comando de texto.

// To generate content, use this import path for GoogleGenerativeAI.
// Note that this is a different import path than what you use for the File API.
import { GoogleGenerativeAI } from "@google/generative-ai";

// Initialize GoogleGenerativeAI with your API_KEY.
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// Choose a Gemini model.
const model = genAI.getGenerativeModel({
  model: "gemini-1.5-pro",
});

// Upload the video file using the File API
// uploadResponse = ...

// Generate content using text and the URI reference for the uploaded file.
const result = await model.generateContent([
    {
      fileData: {
        mimeType: uploadResponse.file.mimeType,
        fileUri: uploadResponse.file.uri
      }
    },
    { text: "Summarize this video. Then create a quiz with answer key based on the information in the video." },
  ]);

// Handle the response of generated text
console.log(result.response.text())

Consulte as marcações de tempo no conteúdo

É possível usar carimbos de data/hora no formato MM:SS para se referir a momentos específicos no vídeo.

// To generate content, use this import path for GoogleGenerativeAI.
// Note that this is a different import path than what you use for the File API.
import { GoogleGenerativeAI } from "@google/generative-ai";

// Initialize GoogleGenerativeAI with your API_KEY.
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// Choose a Gemini model.
const model = genAI.getGenerativeModel({
  model: "gemini-1.5-pro",
});

// Upload the video file using the File API
// uploadResponse = ...

// Generate content using text and the URI reference for the uploaded file.
const result = await model.generateContent([
    {
      fileData: {
        mimeType: uploadResponse.file.mimeType,
        fileUri: uploadResponse.file.uri
      }
    },
    { text: "What are the examples given at 01:05 and 01:19 supposed to show us?" },
  ]);

// Handle the response of generated text
console.log(result.response.text())

Transcrever vídeos e fornecer descrições visuais

Se o vídeo não for acelerado (apenas um frame por segundo de vídeo é amostrado), é possível transcrever o vídeo com descrições visuais para cada cena.

// To generate content, use this import path for GoogleGenerativeAI.
// Note that this is a different import path than what you use for the File API.
import { GoogleGenerativeAI } from "@google/generative-ai";

// Initialize GoogleGenerativeAI with your API_KEY.
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// Choose a Gemini model.
const model = genAI.getGenerativeModel({
  model: "gemini-1.5-pro",
});

// Upload the video file using the File API
// uploadResponse = ...

// Generate content using text and the URI reference for the uploaded file.
const result = await model.generateContent([
    {
      fileData: {
        mimeType: uploadResponse.file.mimeType,
        fileUri: uploadResponse.file.uri
      }
    },
    { text: "Transcribe the audio, giving timestamps. Also provide visual descriptions." },
  ]);

// Handle the response of generated text
console.log(result.response.text())

Listar arquivos

É possível listar todos os arquivos enviados usando a API File e os URIs deles usando files.list.

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const listFilesResponse = await fileManager.listFiles();

// View the response.
for (const file of listFilesResponse.files) {
  console.log(`name: ${file.name} | display name: ${file.displayName}`);
}
files.js

Excluir arquivos

Os arquivos enviados usando a API File são excluídos automaticamente após dois dias. Também é possível excluí-las manualmente usando files.delete.

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(
  `${mediaPath}/jetpack.jpg`,
  {
    mimeType: "image/jpeg",
    displayName: "Jetpack drawing",
  },
);

// Delete the file.
await fileManager.deleteFile(uploadResult.file.name);

console.log(`Deleted ${uploadResult.file.displayName}`);
files.js

A seguir

Este guia mostra como fazer upload de arquivos de imagem e vídeo usando a API File e como gerar saídas de texto de entradas de imagem e vídeo. Para saber mais, confira estes recursos:

  • Estratégias de solicitação de arquivo: a API Gemini oferece suporte a solicitações com dados de texto, imagem, áudio e vídeo, também conhecidas como solicitações multimodais.
  • Instruções do sistema: as instruções do sistema permitem orientar o comportamento do modelo com base nas suas necessidades e casos de uso específicos.
  • Orientações de segurança: às vezes, os modelos de IA generativa produzem resultados inesperados, como respostas imprecisas, parciais ou ofensivas. O pós-processamento e a avaliação humana são essenciais para limitar o risco de danos causados por essas saídas.