Compreensão de imagens

Pode adicionar imagens a pedidos do Gemini para realizar tarefas que envolvam a compreensão dos conteúdos das imagens incluídas. Esta página mostra como adicionar imagens aos seus pedidos ao Gemini no Vertex AI através daGoogle Cloud consola e da API Vertex AI.

Modelos suportados

A tabela seguinte apresenta os modelos que suportam a compreensão de imagens:

Modelo Detalhes de multimédia Tipos MIME
Gemini 2.5 Flash (pré-visualização)
  • Número máximo de imagens por comando: 3000
  • Tamanho máximo da imagem: 7 MB
  • image/png
  • image/jpeg
  • image/webp
Gemini 2.5 Flash-Lite (Pré-visualização)
  • Número máximo de imagens por comando: 3000
  • Tamanho máximo da imagem: 7 MB
  • Número máximo de imagens de saída por comando: 10
  • image/png
  • image/jpeg
  • image/webp
Gemini 2.5 Flash Image
  • Número máximo de imagens por comando: 3
  • Tamanho máximo da imagem: 7 MB
  • Número máximo de imagens de saída por comando: 10
  • Formatos suportados: 1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9 e 21:9
  • image/png
  • image/jpeg
  • image/webp
Gemini 2.5 Flash-Lite
  • Número máximo de imagens por comando: 3000
  • Tamanho máximo da imagem: 7 MB
  • Número máximo de imagens de saída por comando: 10
  • image/png
  • image/jpeg
  • image/webp
Gemini 2.0 Flash com geração de imagens (Pré-visualização)
  • Número máximo de imagens por comando: 3000
  • Tamanho máximo da imagem: 7 MB
  • Número máximo de imagens de saída por comando: 10
  • Máximo de tokens por minuto (TPM) por projeto:
    • Resolução de multimédia alta/média/predefinida:
      • US/Asia: 40 M
      • UE: 10 M
    • Resolução de multimédia baixa:
      • US/Asia: 10 M
      • EU: 3 M
  • image/png
  • image/jpeg
  • image/webp
Gemini 2.5 Pro
  • Número máximo de imagens por comando: 3000
  • Tamanho máximo da imagem: 7 MB
  • image/png
  • image/jpeg
  • image/webp
Gemini 2.5 Flash
  • Número máximo de imagens por comando: 3000
  • Tamanho máximo da imagem: 7 MB
  • image/png
  • image/jpeg
  • image/webp
Gemini 2.0 Flash
  • Número máximo de imagens por comando: 3000
  • Tamanho máximo da imagem: 7 MB
  • Máximo de tokens por minuto (TPM) por projeto:
    • Resolução de multimédia alta/média/predefinida:
      • US/Asia: 40 M
      • UE: 10 M
    • Resolução de multimédia baixa:
      • US/Asia: 10 M
      • UE: 2,6 M
  • image/png
  • image/jpeg
  • image/webp
Gemini 2.0 Flash-Lite
  • Número máximo de imagens por comando: 3000
  • Tamanho máximo da imagem: 7 MB
  • Máximo de tokens por minuto (TPM):
    • Resolução de multimédia alta/média/predefinida:
      • US/Asia: 6,7 M
      • UE: 2,6 M
    • Resolução de multimédia baixa:
      • US/Asia: 2,6 M
      • UE: 2,6 M
  • image/png
  • image/jpeg
  • image/webp

A métrica de quota é generate_content_video_input_per_base_model_id_and_resolution.

Para ver uma lista de idiomas compatíveis com os modelos do Gemini, consulte as informações do modelo Modelos Google. Para saber mais sobre como criar comandos multimodais, consulte o artigo Crie comandos multimodais. Se procura uma forma de usar o Gemini diretamente a partir das suas apps para dispositivos móveis e Web, consulte os SDKs do cliente da Firebase AI Logic para apps Swift, Android, Web, Flutter e Unity.

Adicione imagens a um pedido

Pode adicionar uma única imagem ou várias imagens no seu pedido ao Gemini.

Imagem única

O código de exemplo em cada um dos separadores seguintes mostra uma forma diferente de identificar o que está numa imagem. Este exemplo funciona com todos os modelos multimodais do Gemini.

Consola

Para enviar um comando multimodal através da Google Cloud consola, faça o seguinte:

  1. Na secção Vertex AI da Google Cloud consola, aceda à página Vertex AI Studio.

    Aceda ao Vertex AI Studio

  2. Clique em Abrir forma livre.

  3. Opcional: configure o modelo e os parâmetros:

    • Modelo: selecione um modelo.
    • Região: selecione a região que quer usar.

    • Temperatura: use o controlo de deslize ou a caixa de texto para introduzir um valor para a temperatura.

      A temperatura é usada para a amostragem durante a geração de respostas, que ocorre quando topP e topK são aplicados. A temperatura controla o grau de aleatoriedade na seleção de tokens. As temperaturas mais baixas são adequadas para comandos que requerem uma resposta menos aberta ou criativa, enquanto as temperaturas mais altas podem gerar resultados mais diversos ou criativos. Uma temperatura de 0 significa que os tokens de probabilidade mais elevada são sempre selecionados. Neste caso, as respostas para um determinado comando são maioritariamente determinísticas, mas ainda é possível uma pequena variação.

      Se o modelo devolver uma resposta demasiado genérica, demasiado curta ou uma resposta alternativa, experimente aumentar a temperatura.

    • Limite de tokens de saída: use o controlo de deslize ou a caixa de texto para introduzir um valor para o limite máximo de saída.

      Número máximo de tokens que podem ser gerados na resposta. Um token tem aproximadamente quatro carateres. 100 tokens correspondem a aproximadamente 60 a 80 palavras.

      Especifique um valor inferior para respostas mais curtas e um valor superior para respostas potencialmente mais longas.

    • Adicione a sequência de paragens: opcional. Introduza uma sequência de paragem, que é uma série de carateres que inclui espaços. Se o modelo encontrar uma sequência de paragem, a geração de respostas é interrompida. A sequência de paragens não está incluída na resposta, e pode adicionar até cinco sequências de paragens.

  4. Opcional: para configurar parâmetros avançados, clique em Avançadas e configure da seguinte forma:

    Clique para expandir as configurações avançadas

    • Top-K: use o controlo de deslize ou a caixa de texto para introduzir um valor para o top-K. (não suportado para o Gemini 1.5).

      O Top-K altera a forma como o modelo seleciona tokens para a saída. Um top-K de 1 significa que o token selecionado seguinte é o mais provável entre todos os tokens no vocabulário do modelo (também denominado descodificação gananciosa), enquanto um top-K de 3 significa que o token seguinte é selecionado entre os três tokens mais prováveis através da temperatura.

      Para cada passo de seleção de tokens, são amostrados os K principais tokens com as probabilidades mais elevadas. Em seguida, os tokens são filtrados com base no top-P, com o token final selecionado através da amostragem de temperatura.

      Especifique um valor inferior para respostas menos aleatórias e um valor superior para respostas mais aleatórias.

    • Top-P: use o controlo de deslize ou a caixa de texto para introduzir um valor para o top-P. Os tokens são selecionados do mais provável para o menos provável até que a soma das respetivas probabilidades seja igual ao valor de top-P. Para obter os resultados menos variáveis, defina o top-P como 0.
    • Respostas máximas: use o controlo de deslize ou a caixa de texto para introduzir um valor para o número de respostas a gerar.
    • Respostas graduais: ative esta opção para imprimir as respostas à medida que são geradas.
    • Limite do filtro de segurança: selecione o limite da probabilidade de ver respostas que possam ser prejudiciais.
    • Ativar fundamentação: a fundamentação não é suportada para comandos multimodais.

  5. Clique em Inserir multimédia e selecione uma origem para o ficheiro.

    Carregar

    Selecione o ficheiro que quer carregar e clique em Abrir.

    Por URL

    Introduza o URL do ficheiro que quer usar e clique em Inserir.

    Cloud Storage

    Selecione o contentor e, de seguida, o ficheiro do contentor que quer importar e clique em Selecionar.

    Google Drive

    1. Escolha uma conta e dê o seu consentimento ao Vertex AI Studio para aceder à sua conta na primeira vez que selecionar esta opção. Pode carregar vários ficheiros com um tamanho total de até 10 MB. Um único ficheiro não pode exceder os 7 MB.
    2. Clique no ficheiro que quer adicionar.

    3. Clique em Selecionar.

      A miniatura do ficheiro é apresentada no painel Comando. Também é apresentado o número total de tokens. Se os dados dos comandos excederem o limite de tokens, os tokens são truncados e não são incluídos no processamento dos seus dados.

  6. Introduza o comando de texto no painel Comando.

  7. Opcional: para ver o ID do token para texto e os IDs dos tokens, clique na contagem de tokens no painel Comando.

  8. Clique em Enviar.

  9. Opcional: para guardar o comando em Os meus comandos, clique em Guardar.

  10. Opcional: para obter o código Python ou um comando curl para o seu comando, clique em Obter código.

Python

Instalação

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import HttpOptions, Part

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        "What is shown in this image?",
        Part.from_uri(
            file_uri="gs://cloud-samples-data/generative-ai/image/scones.jpg",
            mime_type="image/jpeg",
        ),
    ],
)
print(response.text)
# Example response:
# The image shows a flat lay of blueberry scones arranged on parchment paper. There are ...

Go

Saiba como instalar ou atualizar o Go.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithTextImage shows how to generate text using both text and image input
func generateWithTextImage(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "What is shown in this image?"},
			{FileData: &genai.FileData{
				// Image source: https://storage.googleapis.com/cloud-samples-data/generative-ai/image/scones.jpg
				FileURI:  "gs://cloud-samples-data/generative-ai/image/scones.jpg",
				MIMEType: "image/jpeg",
			}},
		},
			Role: "user"},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, nil)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The image shows an overhead shot of a rustic, artistic arrangement on a surface that ...

	return nil
}

Node.js

Instalação

npm install @google/genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateContent(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const image = {
    fileData: {
      fileUri: 'gs://cloud-samples-data/generative-ai/image/scones.jpg',
      mimeType: 'image/jpeg',
    },
  };

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: [image, 'What is shown in this image?'],
  });

  console.log(response.text);

  return response.text;
}

Java

Saiba como instalar ou atualizar o Java.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 


import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Part;

public class TextGenerationWithTextAndImage {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates text with text and image input
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      GenerateContentResponse response =
          client.models.generateContent(
              modelId,
              Content.fromParts(
                  Part.fromText("What is shown in this image?"),
                  Part.fromUri(
                      "gs://cloud-samples-data/generative-ai/image/scones.jpg", "image/jpeg")),
              null);

      System.out.print(response.text());
      // Example response:
      // The image shows a flat lay of blueberry scones arranged on parchment paper. There are ...
      return response.text();
    }
  }
}

REST

Depois de configurar o seu ambiente, pode usar a API REST para testar um comando de texto. O exemplo seguinte envia um pedido para o ponto final do modelo do publicador.

Pode incluir imagens armazenadas no Cloud Storage ou usar dados de imagens codificados em base64.

Imagem no Cloud Storage

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o seu ID do projeto.
  • FILE_URI: O URI ou o URL do ficheiro a incluir no comando. Os valores aceitáveis incluem o seguinte:
    • URI do contentor do Cloud Storage: o objeto tem de ser legível publicamente ou residir no mesmo projeto Google Cloud que está a enviar o pedido. Para gemini-2.0-flash e gemini-2.0-flash-lite, o limite de tamanho é de 2 GB.
    • URL HTTP: o URL do ficheiro tem de ser legível publicamente. Pode especificar um ficheiro de vídeo, um ficheiro de áudio e até 10 ficheiros de imagem por pedido. Os ficheiros de áudio, os ficheiros de vídeo e os documentos não podem exceder os 15 MB.
    • URL do vídeo do YouTube: o vídeo do YouTube tem de ser propriedade da conta que usou para iniciar sessão na Google Cloud consola ou ser público. Apenas é suportado um URL de vídeo do YouTube por pedido.

    Quando especifica um fileURI, também tem de especificar o tipo de suporte (mimeType) do ficheiro. Se o VPC Service Controls estiver ativado, a especificação de um URL de ficheiro multimédia para fileURI não é suportada.

    Se não tiver um ficheiro de imagem no Cloud Storage, pode usar o seguinte ficheiro disponível publicamente: gs://cloud-samples-data/generative-ai/image/scones.jpg com um tipo MIME de image/jpeg. Para ver esta imagem, abra o ficheiro de imagem de exemplo.

  • MIME_TYPE: o tipo de suporte do ficheiro especificado nos campos data ou fileUri Os valores aceitáveis incluem o seguinte:

    Clique para expandir os tipos MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
  • TEXT: As instruções de texto a incluir no comando. Por exemplo, What is shown in this image?

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

cat > request.json << 'EOF'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
EOF

Em seguida, execute o seguinte comando para enviar o seu pedido REST: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-1.5-flash:generateContent"

PowerShell

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

@'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Em seguida, execute o seguinte comando para enviar o seu pedido REST: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-1.5-flash:generateContent" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte.

Dados de imagem Base64

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • LOCATION: a região para processar o pedido. Introduza uma região compatível. Para ver a lista completa de regiões suportadas, consulte o artigo Localizações disponíveis.

    Clique para expandir uma lista parcial das regiões disponíveis

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID: o seu ID do projeto.
  • B64_BASE_IMAGE
     A codificação base64 da imagem, do PDF ou do vídeo a incluir inline no comando. Quando inclui conteúdo multimédia inline, também tem de especificar o tipo de conteúdo multimédia (mimeType) dos dados.
  • MIME_TYPE: o tipo de suporte do ficheiro especificado nos campos data ou fileUri Os valores aceitáveis incluem o seguinte:

    Clique para expandir os tipos MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
  • TEXT: As instruções de texto a incluir no comando. Por exemplo, What is shown in this image?.

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

cat > request.json << 'EOF'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "inlineData": {
          "data": "B64_BASE_IMAGE",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
EOF

Em seguida, execute o seguinte comando para enviar o seu pedido REST: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-1.5-flash:generateContent"

PowerShell

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

@'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "inlineData": {
          "data": "B64_BASE_IMAGE",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Em seguida, execute o seguinte comando para enviar o seu pedido REST: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-1.5-flash:generateContent" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte.
Tenha em atenção o seguinte no URL deste exemplo:
  • Use o método generateContent para pedir que a resposta seja devolvida após a geração completa. Para reduzir a perceção de latência para um público humano, transmita a resposta à medida que está a ser gerada através do método streamGenerateContent.
  • O ID do modelo multimodal encontra-se no final do URL antes do método (por exemplo, gemini-2.0-flash). Este exemplo também pode suportar outros modelos.

Várias imagens

Cada um dos seguintes separadores mostra uma forma diferente de incluir várias imagens num pedido de comando. Cada exemplo recebe dois conjuntos das seguintes entradas:

  • Uma imagem de um ponto de referência popular da cidade
  • O tipo de suporte da imagem
  • Texto que indica a cidade e o ponto de referência na imagem

A amostra também inclui uma terceira imagem e um tipo de suporte, mas não inclui texto. O exemplo devolve uma resposta de texto que indica a cidade e o ponto de referência na terceira imagem.

Estas amostras de imagens funcionam com todos os modelos multimodais do Gemini.

Consola

Para enviar um comando multimodal através da Google Cloud consola, faça o seguinte:

  1. Na secção Vertex AI da Google Cloud consola, aceda à página Vertex AI Studio.

    Aceda ao Vertex AI Studio

  2. Clique em Abrir forma livre.

  3. Opcional: configure o modelo e os parâmetros:

    • Modelo: selecione um modelo.
    • Região: selecione a região que quer usar.

    • Temperatura: use o controlo de deslize ou a caixa de texto para introduzir um valor para a temperatura.

      A temperatura é usada para a amostragem durante a geração de respostas, que ocorre quando topP e topK são aplicados. A temperatura controla o grau de aleatoriedade na seleção de tokens. As temperaturas mais baixas são adequadas para comandos que requerem uma resposta menos aberta ou criativa, enquanto as temperaturas mais altas podem gerar resultados mais diversos ou criativos. Uma temperatura de 0 significa que os tokens de probabilidade mais elevada são sempre selecionados. Neste caso, as respostas para um determinado comando são maioritariamente determinísticas, mas ainda é possível uma pequena variação.

      Se o modelo devolver uma resposta demasiado genérica, demasiado curta ou uma resposta alternativa, experimente aumentar a temperatura.

    • Limite de tokens de saída: use o controlo de deslize ou a caixa de texto para introduzir um valor para o limite máximo de saída.

      Número máximo de tokens que podem ser gerados na resposta. Um token tem aproximadamente quatro carateres. 100 tokens correspondem a aproximadamente 60 a 80 palavras.

      Especifique um valor inferior para respostas mais curtas e um valor superior para respostas potencialmente mais longas.

    • Adicione a sequência de paragens: opcional. Introduza uma sequência de paragem, que é uma série de carateres que inclui espaços. Se o modelo encontrar uma sequência de paragem, a geração de respostas é interrompida. A sequência de paragens não está incluída na resposta, e pode adicionar até cinco sequências de paragens.

  4. Opcional: para configurar parâmetros avançados, clique em Avançadas e configure da seguinte forma:

    Clique para expandir as configurações avançadas

    • Top-K: use o controlo de deslize ou a caixa de texto para introduzir um valor para o top-K. (não suportado para o Gemini 1.5).

      O Top-K altera a forma como o modelo seleciona tokens para a saída. Um top-K de 1 significa que o token selecionado seguinte é o mais provável entre todos os tokens no vocabulário do modelo (também denominado descodificação gananciosa), enquanto um top-K de 3 significa que o token seguinte é selecionado entre os três tokens mais prováveis através da temperatura.

      Para cada passo de seleção de tokens, são amostrados os K principais tokens com as probabilidades mais elevadas. Em seguida, os tokens são filtrados com base no top-P, com o token final selecionado através da amostragem de temperatura.

      Especifique um valor inferior para respostas menos aleatórias e um valor superior para respostas mais aleatórias.

    • Top-P: use o controlo de deslize ou a caixa de texto para introduzir um valor para o top-P. Os tokens são selecionados do mais provável para o menos provável até que a soma das respetivas probabilidades seja igual ao valor de top-P. Para obter os resultados menos variáveis, defina o top-P como 0.
    • Respostas máximas: use o controlo de deslize ou a caixa de texto para introduzir um valor para o número de respostas a gerar.
    • Respostas graduais: ative esta opção para imprimir as respostas à medida que são geradas.
    • Limite do filtro de segurança: selecione o limite da probabilidade de ver respostas que possam ser prejudiciais.
    • Ativar fundamentação: a fundamentação não é suportada para comandos multimodais.

  5. Clique em Inserir multimédia e selecione uma origem para o ficheiro.

    Carregar

    Selecione o ficheiro que quer carregar e clique em Abrir.

    Por URL

    Introduza o URL do ficheiro que quer usar e clique em Inserir.

    Cloud Storage

    Selecione o contentor e, de seguida, o ficheiro do contentor que quer importar e clique em Selecionar.

    Google Drive

    1. Escolha uma conta e dê o seu consentimento ao Vertex AI Studio para aceder à sua conta na primeira vez que selecionar esta opção. Pode carregar vários ficheiros com um tamanho total de até 10 MB. Um único ficheiro não pode exceder os 7 MB.
    2. Clique no ficheiro que quer adicionar.

    3. Clique em Selecionar.

      A miniatura do ficheiro é apresentada no painel Comando. Também é apresentado o número total de tokens. Se os dados dos comandos excederem o limite de tokens, os tokens são truncados e não são incluídos no processamento dos seus dados.

  6. Introduza o comando de texto no painel Comando.

  7. Opcional: para ver o ID do token para texto e os IDs dos tokens, clique na contagem de tokens no painel Comando.

  8. Clique em Enviar.

  9. Opcional: para guardar o comando em Os meus comandos, clique em Guardar.

  10. Opcional: para obter o código Python ou um comando curl para o seu comando, clique em Obter código.

Python

Instalação

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

from google import genai
from google.genai.types import HttpOptions, Part

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# Read content from GCS
gcs_file_img_path = "gs://cloud-samples-data/generative-ai/image/scones.jpg"

# Read content from a local file
with open("test_data/latte.jpg", "rb") as f:
    local_file_img_bytes = f.read()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        "Generate a list of all the objects contained in both images.",
        Part.from_uri(file_uri=gcs_file_img_path, mime_type="image/jpeg"),
        Part.from_bytes(data=local_file_img_bytes, mime_type="image/jpeg"),
    ],
)
print(response.text)
# Example response:
# Okay, here's the list of objects present in both images:
# ...

Go

Saiba como instalar ou atualizar o Go.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

import (
	"context"
	"fmt"
	"io"
	"os"

	genai "google.golang.org/genai"
)

// generateWithMultiImg shows how to generate text using multiple image inputs.
func generateWithMultiImg(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	// TODO(Developer): Update the path to file (image source:
	//   https://storage.googleapis.com/cloud-samples-data/generative-ai/image/latte.jpg )
	imageBytes, err := os.ReadFile("./latte.jpg")
	if err != nil {
		return fmt.Errorf("failed to read image: %w", err)
	}

	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "Write an advertising jingle based on the items in both images."},
			{FileData: &genai.FileData{
				// Image source: https://storage.googleapis.com/cloud-samples-data/generative-ai/image/scones.jpg
				FileURI:  "gs://cloud-samples-data/generative-ai/image/scones.jpg",
				MIMEType: "image/jpeg",
			}},
			{InlineData: &genai.Blob{
				Data:     imageBytes,
				MIMEType: "image/jpeg",
			}},
		}},
	}
	modelName := "gemini-2.5-flash"

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, nil)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// Okay, here's an advertising jingle inspired by the blueberry scones, coffee, flowers, chocolate cake, and latte:
	//
	// (Upbeat, jazzy music)
	// ...

	return nil
}

Node.js

Instalação

npm install @google/genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateContent(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const image1 = {
    fileData: {
      fileUri: 'gs://cloud-samples-data/generative-ai/image/scones.jpg',
      mimeType: 'image/jpeg',
    },
  };

  const image2 = {
    fileData: {
      fileUri: 'gs://cloud-samples-data/generative-ai/image/fruit.png',
      mimeType: 'image/png',
    },
  };

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: [
      image1,
      image2,
      'Generate a list of all the objects contained in both images.',
    ],
  });

  console.log(response.text);

  return response.text;
}

Java

Saiba como instalar ou atualizar o Java.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o Vertex AI: 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 


import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Part;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;

public class TextGenerationWithMultiImage {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    // Content from Google Cloud Storage
    String gcsFileImagePath = "gs://cloud-samples-data/generative-ai/image/scones.jpg";
    String localImageFilePath = "resources/latte.jpg";
    generateContent(modelId, gcsFileImagePath, localImageFilePath);
  }

  // Generates text with multiple images
  public static String generateContent(
      String modelId, String gcsFileImagePath, String localImageFilePath) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Read content from a local file.
      byte[] localFileImgBytes = Files.readAllBytes(Paths.get(localImageFilePath));

      GenerateContentResponse response =
          client.models.generateContent(
              modelId,
              Content.fromParts(
                  Part.fromText("Generate a list of all the objects contained in both images"),
                  Part.fromBytes(localFileImgBytes, "image/jpeg"),
                  Part.fromUri(gcsFileImagePath, "image/jpeg")),
              null);

      System.out.print(response.text());
      // Example response:
      // Okay, here's the list of objects present in both images:
      //
      // **Image 1 (Scones):**
      //
      // *   Scones
      // *   Plate
      // *   Jam/Preserve
      // *   Cream/Butter
      // *   Table/Surface
      // *   Napkin/Cloth (possibly)
      //
      // **Image 2 (Latte):**
      //
      // *   Latte/Coffee cup
      // *   Saucer
      // *   Spoon
      // *   Table/Surface
      // *   Foam/Latte art
      //
      // **Objects potentially in both (depending on interpretation and specific items):**
      //
      // *   Plate/Saucer (both are serving dishes)
      // *   Table/Surface
      return response.text();
    }
  }
}

REST

Depois de configurar o seu ambiente, pode usar a API REST para testar um comando de texto. O exemplo seguinte envia um pedido para o ponto final do modelo do publicador.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: .
  • FILE_URI1: O URI ou o URL do ficheiro a incluir no comando. Os valores aceitáveis incluem o seguinte:
    • URI do contentor do Cloud Storage: o objeto tem de ser legível publicamente ou residir no mesmo projeto Google Cloud que está a enviar o pedido. Para gemini-2.0-flash e gemini-2.0-flash-lite, o limite de tamanho é de 2 GB.
    • URL HTTP: o URL do ficheiro tem de ser legível publicamente. Pode especificar um ficheiro de vídeo, um ficheiro de áudio e até 10 ficheiros de imagem por pedido. Os ficheiros de áudio, os ficheiros de vídeo e os documentos não podem exceder os 15 MB.
    • URL do vídeo do YouTube: o vídeo do YouTube tem de ser propriedade da conta que usou para iniciar sessão na Google Cloud consola ou ser público. Apenas é suportado um URL de vídeo do YouTube por pedido.

    Quando especifica um fileURI, também tem de especificar o tipo de suporte (mimeType) do ficheiro. Se o VPC Service Controls estiver ativado, a especificação de um URL de ficheiro multimédia para fileURI não é suportada.

    Se não tiver um ficheiro de imagem no Cloud Storage, pode usar o seguinte ficheiro disponível publicamente: gs://cloud-samples-data/vertex-ai/llm/prompts/landmark1.png com um tipo MIME de image/png. Para ver esta imagem, abra o ficheiro de imagem de exemplo.

  • MIME_TYPE: o tipo de suporte do ficheiro especificado nos campos data ou fileUri Os valores aceitáveis incluem o seguinte:

    Clique para expandir os tipos MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
     Para simplificar, este exemplo usa o mesmo tipo de suporte para todas as três imagens de entrada.
  • TEXT1: As instruções de texto a incluir no comando. Por exemplo, city: Rome, Landmark: the Colosseum
  • FILE_URI2: O URI ou o URL do ficheiro a incluir no comando. Os valores aceitáveis incluem o seguinte:
    • URI do contentor do Cloud Storage: o objeto tem de ser legível publicamente ou residir no mesmo projeto Google Cloud que está a enviar o pedido. Para gemini-2.0-flash e gemini-2.0-flash-lite, o limite de tamanho é de 2 GB.
    • URL HTTP: o URL do ficheiro tem de ser legível publicamente. Pode especificar um ficheiro de vídeo, um ficheiro de áudio e até 10 ficheiros de imagem por pedido. Os ficheiros de áudio, os ficheiros de vídeo e os documentos não podem exceder os 15 MB.
    • URL do vídeo do YouTube: o vídeo do YouTube tem de ser propriedade da conta que usou para iniciar sessão na Google Cloud consola ou ser público. Apenas é suportado um URL de vídeo do YouTube por pedido.

    Quando especifica um fileURI, também tem de especificar o tipo de suporte (mimeType) do ficheiro. Se o VPC Service Controls estiver ativado, a especificação de um URL de ficheiro multimédia para fileURI não é suportada.

    Se não tiver um ficheiro de imagem no Cloud Storage, pode usar o seguinte ficheiro disponível publicamente: gs://cloud-samples-data/vertex-ai/llm/prompts/landmark2.png com um tipo MIME de image/png. Para ver esta imagem, abra o ficheiro de imagem de exemplo.

  • TEXT2: As instruções de texto a incluir no comando. Por exemplo, city: Beijing, Landmark: Forbidden City
  • FILE_URI3: O URI ou o URL do ficheiro a incluir no comando. Os valores aceitáveis incluem o seguinte:
    • URI do contentor do Cloud Storage: o objeto tem de ser legível publicamente ou residir no mesmo projeto Google Cloud que está a enviar o pedido. Para gemini-2.0-flash e gemini-2.0-flash-lite, o limite de tamanho é de 2 GB.
    • URL HTTP: o URL do ficheiro tem de ser legível publicamente. Pode especificar um ficheiro de vídeo, um ficheiro de áudio e até 10 ficheiros de imagem por pedido. Os ficheiros de áudio, os ficheiros de vídeo e os documentos não podem exceder os 15 MB.
    • URL do vídeo do YouTube: o vídeo do YouTube tem de ser propriedade da conta que usou para iniciar sessão na Google Cloud consola ou ser público. Apenas é suportado um URL de vídeo do YouTube por pedido.

    Quando especifica um fileURI, também tem de especificar o tipo de suporte (mimeType) do ficheiro. Se o VPC Service Controls estiver ativado, a especificação de um URL de ficheiro multimédia para fileURI não é suportada.

    Se não tiver um ficheiro de imagem no Cloud Storage, pode usar o seguinte ficheiro disponível publicamente: gs://cloud-samples-data/vertex-ai/llm/prompts/landmark3.png com um tipo MIME de image/png. Para ver esta imagem, abra o ficheiro de imagem de exemplo.

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

cat > request.json << 'EOF'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI1",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT1"
      },
      {
        "fileData": {
          "fileUri": "FILE_URI2",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT2"
      },
      {
        "fileData": {
          "fileUri": "FILE_URI3",
          "mimeType": "MIME_TYPE"
        }
      }
    ]
  }
}
EOF

Em seguida, execute o seguinte comando para enviar o seu pedido REST: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent"

PowerShell

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

@'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI1",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT1"
      },
      {
        "fileData": {
          "fileUri": "FILE_URI2",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT2"
      },
      {
        "fileData": {
          "fileUri": "FILE_URI3",
          "mimeType": "MIME_TYPE"
        }
      }
    ]
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Em seguida, execute o seguinte comando para enviar o seu pedido REST: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte.

Tenha em atenção o seguinte no URL deste exemplo:
  • Use o método generateContent para pedir que a resposta seja devolvida após a geração completa. Para reduzir a perceção de latência para um público humano, transmita a resposta à medida que está a ser gerada através do método streamGenerateContent.
  • O ID do modelo multimodal encontra-se no final do URL antes do método (por exemplo, gemini-2.0-flash). Este exemplo também pode suportar outros modelos.

Defina parâmetros do modelo opcionais

Cada modelo tem um conjunto de parâmetros opcionais que pode definir. Para mais informações, consulte o artigo Parâmetros de geração de conteúdo.

Tokenização de imagens

Veja como são calculados os tokens para imagens:

  • Se ambas as dimensões de uma imagem forem inferiores ou iguais a 384 píxeis, são usados 258 tokens.
  • Se uma dimensão de uma imagem for superior a 384 píxeis, a imagem é recortada em mosaicos. O tamanho de cada mosaico é predefinido para a menor dimensão (largura ou altura) dividida por 1,5. Se necessário, cada mosaico é ajustado para que não tenha menos de 256 píxeis nem mais de 768 píxeis. Em seguida, cada mosaico é redimensionado para 768 x 768 e usa 258 tokens.

Práticas recomendadas

Quando usar imagens, siga as práticas recomendadas e as informações abaixo para obter os melhores resultados:

  • Se quiser detetar texto numa imagem, use comandos com uma única imagem para produzir melhores resultados do que comandos com várias imagens.
  • Se o comando contiver uma única imagem, coloque-a antes do comando de texto no seu pedido.
  • Se o seu comando contiver várias imagens e quiser referir-se a elas mais tarde no comando ou que o modelo se refira a elas na resposta do modelo, pode ser útil atribuir um índice a cada imagem antes da imagem. Use a b c ou image 1 image 2 image 3 para o seu índice. Segue-se um exemplo de utilização de imagens indexadas num comando: 
    image 1 
image 2 
image 3 

Write a blogpost about my day using image 1 and image 2. Then, give me ideas
for tomorrow based on image 3.
  • Use imagens com uma resolução mais elevada, pois produzem melhores resultados.
  • Inclua alguns exemplos no comando.
  • Rode as imagens para a orientação adequada antes de as adicionar ao comando.
  • Evite imagens esbatidas.

Limitações

Embora os modelos multimodais do Gemini sejam poderosos em muitos exemplos de utilização multimodal, é importante compreender as limitações dos modelos:

  • Moderação de conteúdo: os modelos recusam-se a fornecer respostas em imagens que violam as nossas políticas de segurança.
  • Raciocínio espacial: os modelos não são precisos na localização de texto ou objetos em imagens. Podem devolver apenas as contagens aproximadas de objetos.
  • Usos médicos: os modelos não são adequados para interpretar imagens médicas (por exemplo, radiografias e tomografias computorizadas) nem fornecer aconselhamento médico.
  • Reconhecimento de pessoas: os modelos não se destinam a ser usados para identificar pessoas que não sejam celebridades em imagens.
  • Precisão: os modelos podem ter alucinações ou cometer erros ao interpretar imagens de baixa qualidade, rodadas ou de resolução extremamente baixa. Os modelos também podem ter alucinações ao interpretar texto manuscrito em documentos de imagens.

O que se segue?