Compreensão do vídeo

É possível adicionar vídeos às solicitações do Gemini para realizar tarefas que envolvem entender o conteúdo dos vídeos incluídos. Esta página mostra como adicionar vídeos às suas solicitações para o Gemini na Gemini Enterprise Agent Platform usando o console do Google Cloud e a API Agent Platform.

Modelos compatíveis

A tabela a seguir lista os modelos compatíveis com a compreensão de vídeo:

Modelos Detalhes da mídia Tipos MIME
  • Duração máxima do vídeo (com áudio): 10 segundos
  • Duração máxima do vídeo (sem áudio): 10 segundos
  • Número máximo de vídeos por comando: 3
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Duração máxima do vídeo (com áudio): 15 segundos
  • Duração máxima do vídeo (sem áudio): 15 segundos
  • Duração máxima do vídeo de entrada (compreensão de vídeo): 10 minutos
  • Duração máxima do vídeo de entrada (edição): 15 segundos
  • Duração máxima do vídeo de entrada (extensão): qualquer duração (usa até os últimos 10 segundos)
  • Duração máxima do vídeo de entrada (upscaling): 15 segundos
  • Duração do vídeo de saída (geração e edição): 3 a 15 segundos (3 a 10 segundos para o primeiro e o último frame)
  • Duração do vídeo de saída (extensão): 3 a 10 segundos (concatenados até os últimos 30 segundos do vídeo de entrada)
  • Número máximo de vídeos por comando: 3
  • Proporções compatíveis: 16:9, 9:16
  • Resoluções aceitas: 360p, 720p, 1080p, 4K
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Duração máxima do vídeo (com áudio): 10 segundos
  • Duração máxima do vídeo (sem áudio): 10 segundos
  • Número máximo de vídeos por comando: 3
  • Proporções compatíveis: 16:9, 9:16
  • Resoluções aceitas: 360p, 720p, 1080p, 4K
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Número máximo de arquivos de vídeo de entrada por comando: 10
  • Máximo de URLs do YouTube por comando: 1
  • Duração máxima do vídeo (sem áudio): conforme compatível com a janela de contexto de 128 mil tokens (aproximadamente 25 minutos).
  • Tamanho máximo da parte inline: 256 MB
  • Tamanho máximo por arquivo do Cloud Storage: 2 GiB menos 500 KiB
  • Tamanho máximo por arquivo de URLs HTTP ou HTTPS públicos: 15 MiB
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Duração máxima do vídeo (com áudio): aproximadamente 45 minutos
  • Duração máxima do vídeo (sem áudio): aproximadamente 1 hora
  • Número máximo de vídeos por comando: 10
  • Tamanho máximo da parte inline (API GenerateContent): 256 MB
  • Tamanho máximo por arquivo do Cloud Storage: 2 GiB menos 500 KiB
  • Tamanho máximo por arquivo de URLs HTTP ou HTTPS públicos: 15 MiB
  • Tokens de resolução padrão por frame: 70
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Resolução de entrada padrão: 768 x 768 (1 FPS)
  • Resolução mínima de saída do avatar em tempo real: 704 x 1280 (retrato) ou 1280 x 704 (paisagem) a 24 QPS
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Número máximo de arquivos de vídeo de entrada por comando: 10
  • Máximo de URLs do YouTube por comando: 1
  • Duração máxima do vídeo (sem áudio): conforme compatível com a janela de contexto de 65.536 tokens (aproximadamente 12 minutos).
  • Tamanho máximo da parte inline: 256 MB
  • Tamanho máximo por arquivo do Cloud Storage: 2 GiB menos 500 KiB
  • Tamanho máximo por arquivo de URLs HTTP ou HTTPS públicos: 15 MiB
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Duração máxima do vídeo (com áudio): aproximadamente 45 minutos
  • Duração máxima do vídeo (sem áudio): aproximadamente 1 hora
  • Número máximo de vídeos por comando: 10 (até 1 URL HTTP ou HTTPS em endpoints não migrados)
  • Tamanho máximo da parte inline: 256 MB
  • Tamanho máximo por arquivo do Cloud Storage: 2 GiB menos 500 KiB
  • Tamanho máximo por arquivo de URLs HTTP ou HTTPS públicos: 15 MiB
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Resolução padrão: 768 x 768
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp

Para uma lista de linguagens compatíveis com os modelos do Gemini, consulte as informações do modelo Modelos do Google. Para saber mais sobre como criar comandos multimodais, consulte Criar comandos multimodais. Se você está procurando uma maneira de usar o Gemini diretamente no seu dispositivo móvel e e apps da Web, consulte os SDKs de cliente do Firebase AI Logic para apps Swift, Android, Web, Flutter e Unity.

Limites de endpoint de API e janela de contexto

Os modelos padrão do Gemini 3 e versões mais recentes aceitam até 3.000 imagens e PDFs combinados, 1.000 arquivos de áudio ou 10 vídeos por solicitação no generateContent e na API Interactions (até 6.500 arquivos multimodais combinados quando arquivos de texto simples são incluídos). Os endpoints do Gemini 2.5 não migrados e o gemini-3.1-pro-preview-customtools aplicam limites legados de tamanho de arquivo, página de PDF (1.000) e contagem de URLs HTTP ou HTTPS. Os limites práticos de solicitação também dependem do endpoint de API, da origem do arquivo e da janela de contexto:

  • Limite de URIs da API Interactions para arquivos do Cloud Storage: as solicitações de API da API Interactions aceitam até 100 URIs distintos do Cloud Storage (gs://) por solicitação de interação do modelo, incluindo URIs transferidos de turnos de conversa anteriores usando previous_interaction_id. As solicitações generateContent aceitam URIs gs:// até o limite de itens do modelo.
  • Limites de origem de arquivo, parte inline e payload de solicitação: os arquivos individuais referenciados no Cloud Storage não podem exceder 2 GiB menos 500 KiB, e os arquivos referenciados em URLs HTTP ou HTTPS públicos não podem exceder 15 MiB. No generateContent e no streamGenerateContent, cada anexo inline (inline_data) não pode exceder 256 MB nos modelos padrão do Gemini 3 e versões mais recentes, e o payload total compactado da solicitação HTTP ou gRPC não pode exceder 500 MiB (a codificação base64 adiciona aproximadamente 33% de sobrecarga de tamanho). Na API Interactions, o payload da solicitação HTTP compactado não pode exceder 256 MiB para solicitações síncronas ou de streaming.Quando service_tier é definido como deferred (o que exige que background e store sejam true), a solicitação descompactada não pode exceder 9,75 MiB.
  • Janela de contexto: a contagem combinada de tokens de todas as entradas multimodais e textos em uma solicitação não pode exceder o limite de tokens de entrada do modelo (1.048.576 tokens nos modelos padrão do Gemini 3 e versões mais recentes).

Adicionar vídeos a uma solicitação

É possível adicionar um ou vários vídeos à sua solicitação ao Gemini e os vídeos podem incluir áudio.

Vídeo único

O exemplo de código em cada uma das guias a seguir mostra uma maneira diferente de identificar o conteúdo de um vídeo. Esta amostra funciona com todos os modelos multimodais do Gemini.

Console

Para enviar um comando multimodal usando o console do Google Cloud , faça o seguinte:

  1. Na seção "Plataforma de Agentes" do console do Google Cloud , acesse a página Agent Studio.

    Acessar o Agent Studio

  2. Clique em Criar prompt.

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

    • Modelo: selecione um modelo.
  4. Opcional: para configurar parâmetros avançados, clique em Avançado e faça a configuração da seguinte maneira:

    Clique para abrir as configurações avançadas

    • Top-K: use o controle deslizante ou a caixa de texto para inserir um valor para "top-K".

      O top-k muda a forma como o modelo seleciona tokens para saída. Um top-K de 1 significa que o próximo token selecionado é o mais provável entre todos os tokens no vocabulário do modelo (também chamado de decodificação gananciosa), enquanto um top-K de 3 significa que o próximo token está selecionado entre os três tokens mais prováveis usando a temperatura.

      Para cada etapa da seleção de tokens, são amostrados os tokens top-K com as maiores probabilidades. Em seguida, os tokens são filtrados com base no valor de top-P com o token final selecionado por meio da amostragem de temperatura.

      Especifique um valor mais baixo para respostas menos aleatórias e um valor mais alto para respostas mais aleatórias.

    • Top-P: use o controle deslizante ou a caixa de texto para inserir um valor para essa parte. Os tokens são selecionados do mais provável para o menos até que a soma das probabilidades seja igual ao valor do top-P. Para ter menos resultados de variáveis, defina top-P como 0.
    • Respostas máximas: use o controle deslizante ou a caixa de texto para inserir um valor para o número de respostas a serem geradas.
    • Respostas de streaming: ative para mostrar as respostas à medida que são geradas.
    • Limite do filtro de segurança: selecione o limite de probabilidade de mostrar respostas que podem ser prejudiciais.
    • Ativar embasamento: o embasamento não é compatível com solicitações multimodais.
    • Região: selecione a região que você quer usar.
    • Temperatura: use o controle deslizante ou a caixa de texto para inserir um valor para a temperatura.

          
      The temperature is used for sampling during response generation, which occurs when topP
      and topK are applied. Temperature controls the degree of randomness in token selection.
      Lower temperatures are good for prompts that require a less open-ended or creative response, while
      higher temperatures can lead to more diverse or creative results. A temperature of 0
      means that the highest probability tokens are always selected. In this case, responses for a given
      prompt are mostly deterministic, but a small amount of variation is still possible.
      
      

      If the model returns a response that's too generic, too short, or the model gives a fallback response, try increasing the temperature. If the model enters infinite generation, increasing the temperature to at least 0.1 may lead to improved results.

      1.0 is the recommended starting value for temperature. </li> <li>**Output token limit**: Use the slider or textbox to enter a value for the max output limit. Maximum number of tokens that can be generated in the response. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words.

      Specify a lower value for shorter responses and a higher value for potentially longer responses.

      </li> <li>**Add stop sequence**: Optional. Enter a stop sequence, which is a series of characters that includes spaces. If the model encounters a stop sequence, the response generation stops. The stop sequence isn't included in the response, and you can add up to five stop sequences.</li> </ul>

  5. Clique em Inserir mídia e selecione uma origem para o arquivo.

    Fazer upload

    Selecione o arquivo que você quer enviar e clique em Abrir.

    Por URL

    Insira o URL do arquivo que você quer usar e clique em Inserir.

    YouTube

    Insira o URL do vídeo do YouTube que você quer usar e clique em Inserir.

    Você pode usar qualquer vídeo público ou um vídeo que seja de propriedade da conta que você usou para fazer login no console do Google Cloud .

    Cloud Storage

    Selecione o bucket e o arquivo que você quer importar e clique em Selecionar.

    Google Drive

    1. Escolha uma conta e conceda consentimento ao Agent Studio para acessar sua conta na primeira vez que você selecionar essa opção. É possível fazer upload vários arquivos que tenham um tamanho total de até 10 MB. Um único arquivo não pode exceder 7 MB.
    2. Clique no arquivo que você quer adicionar.
    3. Clique em Selecionar.

      A miniatura do arquivo é mostrada no painel Comando. O número total de tokens também é exibido. Se os dados do comando excederem o limite de tokens, os tokens serão truncados e não serão incluídos no processamento dos dados.

  6. Digite o comando de texto no painel Prompt.

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

  8. Clique em Enviar.

  9. Opcional: para salvar o comando em Meus comandos, clique em Salvar.

  10. Opcional: para receber o código Python ou um comando curl para seu comando, clique em Criar com código > Receber código.

Python

Instalar

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 generativa do Google com a 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_ENTERPRISE=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-3.8-flash",
    contents=[
        Part.from_uri(
            file_uri="gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
            mime_type="video/mp4",
        ),
        "What is in the video?",
    ],
)
print(response.text)
# Example response:
# The video shows several people surfing in an ocean with a coastline in the background. The camera ...

Go

Saiba como instalar ou atualizar a Go.

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

Defina variáveis de ambiente para usar o SDK de IA generativa do Google com a 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_ENTERPRISE=True

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithMuteVideo shows how to generate text using a video with no sound as the input.
func generateWithMuteVideo(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 in the video?"},
			{FileData: &genai.FileData{
				FileURI:  "gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
				MIMEType: "video/mp4",
			}},
		},
			Role: genai.RoleUser},
	}

	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 video shows several surfers riding waves in an ocean setting. The waves are ...

	return nil
}

Java

Saiba como instalar ou atualizar a Java.

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

Defina variáveis de ambiente para usar o SDK de IA generativa do Google com a 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_ENTERPRISE=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 TextGenerationWithMuteVideo {

  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 mute video 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.fromUri(
                      "gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
                      "video/mp4"),
                  Part.fromText("What is in this video?")),
              null);

      System.out.print(response.text());
      // Example response:
      // This video features **surfers in the ocean**.
      //
      // The main focus is on **one individual who catches and rides a wave**, executing various
      // turns and maneuvers as the wave breaks and dissipates into whitewater...
      return response.text();
    }
  }
}

Node.js

Instalar

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 generativa do Google com a 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_ENTERPRISE=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 generateText(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash-lite',
    contents: [
      {
        role: 'user',
        parts: [
          {
            fileData: {
              mimeType: 'video/mp4',
              fileUri:
                'gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4',
            },
          },
          {
            text: 'What is in the video?',
          },
        ],
      },
    ],
    config: {
      mediaResolution: 'MEDIA_RESOLUTION_LOW',
    },
  });

  console.log(response.text);

  // Example response:
  // The video shows several people surfing in an ocean with a coastline in the background. The camera ...

  return response.text;
}

REST

Depois de configurar o ambiente, use REST para testar um comando de texto. O exemplo a seguir envia uma solicitação ao endpoint do modelo de editor.

API GenerateContent

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto;
  • FILE_URI: o URI ou URL do arquivo a ser incluído no comando. Os valores aceitáveis são os seguintes:
    • URI do bucket do Cloud Storage: o objeto precisa ser publicamente legível ou residir no mesmo projeto do Google Cloud que está enviando a solicitação.
    • URL HTTP: o URL do arquivo precisa ser legível publicamente e não pode exceder 15 MiB por arquivo. Os modelos padrão do Gemini 3 e versões mais recentes aceitam até 3.000 imagens e PDFs combinados, 1.000 arquivos de áudio ou 10 vídeos por solicitação (até 6.500 arquivos no total, incluindo arquivos de texto simples). Os endpoints do Gemini 2.5 não migrados e o gemini-3.1-pro-preview-customtools limitam os URLs HTTP ou HTTPS a 10 imagens, 1 arquivo de áudio ou 1 vídeo por solicitação.
    • URL do vídeo do YouTube: o vídeo do YouTube precisa ser de propriedade da conta que você usou para fazer login no console do Google Cloud ou ser público. Somente um URL de vídeo do YouTube é aceito por solicitação.

    Ao especificar um fileURI, você também precisa especificar o tipo de mídia (mimeType) do arquivo. Se o VPC Service Controls estiver ativado, não será possível especificar um URL de arquivo de mídia para fileURI.

    Se você não tiver um arquivo de vídeo no Cloud Storage, use o seguinte arquivo disponível publicamente: gs://cloud-samples-data/video/animals.mp4 com um tipo MIME de video/mp4. Para acessar este vídeo, abrir o MP4 de amostra .

  • MIME_TYPE: O tipo de mídia do arquivo especificado em data ou fileUri . Os valores aceitáveis são os seguintes:

    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 serem incluídas no comando. Por exemplo, What is in the video?

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

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

Depois execute o comando a seguir para enviar a solicitação 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-3.5-flash:generateContent"

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

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

Depois execute o comando a seguir para enviar a solicitação 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-3.5-flash:generateContent" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a seguinte.

API Interactions

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • FILE_URI: o URI ou URL do arquivo a ser incluído no comando. Os valores aceitáveis são os seguintes:
    • URI do bucket do Cloud Storage: o objeto precisa ser publicamente legível ou residir no mesmo projeto do Google Cloud que está enviando a solicitação.
    • URL HTTP: o URL do arquivo precisa ser legível publicamente e não pode exceder 15 MiB por arquivo. Os modelos padrão do Gemini 3 e versões mais recentes aceitam até 3.000 imagens e PDFs combinados, 1.000 arquivos de áudio ou 10 vídeos por solicitação (até 6.500 arquivos no total, incluindo arquivos de texto simples). Os endpoints do Gemini 2.5 não migrados e o gemini-3.1-pro-preview-customtools limitam os URLs HTTP ou HTTPS a 10 imagens, 1 arquivo de áudio ou 1 vídeo por solicitação.
    • URL do vídeo do YouTube: o vídeo do YouTube precisa ser de propriedade da conta que você usou para fazer login no console do Google Cloud ou ser público. Somente um URL de vídeo do YouTube é aceito por solicitação.

    Ao especificar um fileURI, você também precisa especificar o tipo de mídia (mimeType) do arquivo. Se o VPC Service Controls estiver ativado, não será possível especificar um URL de arquivo de mídia para fileURI.

    Se você não tiver um arquivo de vídeo no Cloud Storage, use o seguinte arquivo disponível publicamente: gs://cloud-samples-data/video/animals.mp4 com um tipo MIME de video/mp4. Para acessar este vídeo, abrir o MP4 de amostra .

  • MIME_TYPE: O tipo de mídia do arquivo especificado em data ou fileUri . Os valores aceitáveis são os seguintes:

    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 serem incluídas no comando. Por exemplo, What is in the video?

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
EOF

Depois execute o comando a seguir para enviar a solicitação 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/interactions"

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação 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/interactions" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a seguinte.

Observe o seguinte no URL deste exemplo:
  • Use o generateContent para solicitar que a resposta seja retornada depois de ser totalmente gerada. Para reduzir a percepção de latência ao público humano, transmita a resposta à medida que geradas usando o streamGenerateContent .
  • O ID do modelo multimodal está localizado no final do URL, antes do método (por exemplo, gemini-3.5-flash). Este exemplo pode oferecer suporte a outros modelos também.
  • Quando você usa um endpoint de API regional (por exemplo, us-central1), a região do URL do endpoint determina onde a solicitação é processada. Qualquer local conflitante no caminho do recurso é ignorado.

Vídeo com áudio

Confira a seguir como resumir um arquivo de vídeo com áudio e retornar capítulos com marcações de tempo. Este exemplo funciona com todos os modelos multimodais do Gemini que aceitam vídeo com áudio.

Python

Instalar

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 generativa do Google com a 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_ENTERPRISE=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-3.8-flash",
    contents=[
        Part.from_uri(
            file_uri="gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
            mime_type="video/mp4",
        ),
        "What is in the video?",
    ],
)
print(response.text)
# Example response:
# The video shows several people surfing in an ocean with a coastline in the background. The camera ...

REST

Depois de configurar o ambiente, use REST para testar um comando de texto. O exemplo a seguir envia uma solicitação ao endpoint do modelo de editor.

API GenerateContent

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto;
  • FILE_URI: o URI ou URL do arquivo a ser incluído no comando. Os valores aceitáveis são os seguintes:
    • URI do bucket do Cloud Storage: o objeto precisa ser publicamente legível ou residir no mesmo projeto do Google Cloud que está enviando a solicitação.
    • URL HTTP: o URL do arquivo precisa ser legível publicamente e não pode exceder 15 MiB por arquivo. Os modelos padrão do Gemini 3 e versões mais recentes aceitam até 3.000 imagens e PDFs combinados, 1.000 arquivos de áudio ou 10 vídeos por solicitação (até 6.500 arquivos no total, incluindo arquivos de texto simples). Os endpoints do Gemini 2.5 não migrados e o gemini-3.1-pro-preview-customtools limitam os URLs HTTP ou HTTPS a 10 imagens, 1 arquivo de áudio ou 1 vídeo por solicitação.
    • URL do vídeo do YouTube: o vídeo do YouTube precisa ser de propriedade da conta que você usou para fazer login no console do Google Cloud ou ser público. Somente um URL de vídeo do YouTube é aceito por solicitação.

    Ao especificar um fileURI, você também precisa especificar o tipo de mídia (mimeType) do arquivo. Se o VPC Service Controls estiver ativado, não será possível especificar um URL de arquivo de mídia para fileURI.

    Se você não tiver um arquivo de vídeo no Cloud Storage, use o seguinte arquivo disponível publicamente: gs://cloud-samples-data/generative-ai/video/pixel8.mp4 com um tipo MIME de video/mp4. Para acessar este vídeo, abrir o MP4 de amostra .

  • MIME_TYPE: O tipo de mídia do arquivo especificado em data ou fileUri . Os valores aceitáveis são os seguintes:

    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 serem incluídas no comando. Por exemplo, Provide a description of the video. The description should also contain anything important which people say in the video.

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

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

Depois execute o comando a seguir para enviar a solicitação 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

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

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

Depois execute o comando a seguir para enviar a solicitação 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

Você receberá uma resposta JSON semelhante a seguinte.

API Interactions

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • FILE_URI: o URI ou URL do arquivo a ser incluído no comando. Os valores aceitáveis são os seguintes:
    • URI do bucket do Cloud Storage: o objeto precisa ser publicamente legível ou residir no mesmo projeto do Google Cloud que está enviando a solicitação.
    • URL HTTP: o URL do arquivo precisa ser legível publicamente e não pode exceder 15 MiB por arquivo. Os modelos padrão do Gemini 3 e versões mais recentes aceitam até 3.000 imagens e PDFs combinados, 1.000 arquivos de áudio ou 10 vídeos por solicitação (até 6.500 arquivos no total, incluindo arquivos de texto simples). Os endpoints do Gemini 2.5 não migrados e o gemini-3.1-pro-preview-customtools limitam os URLs HTTP ou HTTPS a 10 imagens, 1 arquivo de áudio ou 1 vídeo por solicitação.
    • URL do vídeo do YouTube: o vídeo do YouTube precisa ser de propriedade da conta que você usou para fazer login no console do Google Cloud ou ser público. Somente um URL de vídeo do YouTube é aceito por solicitação.

    Ao especificar um fileURI, você também precisa especificar o tipo de mídia (mimeType) do arquivo. Se o VPC Service Controls estiver ativado, não será possível especificar um URL de arquivo de mídia para fileURI.

    Se você não tiver um arquivo de vídeo no Cloud Storage, use o seguinte arquivo disponível publicamente: gs://cloud-samples-data/generative-ai/video/pixel8.mp4 com um tipo MIME de video/mp4. Para acessar este vídeo, abrir o MP4 de amostra .

  • MIME_TYPE: O tipo de mídia do arquivo especificado em data ou fileUri . Os valores aceitáveis são os seguintes:

    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 serem incluídas no comando. Por exemplo, Provide a description of the video. The description should also contain anything important which people say in the video.

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
EOF

Depois execute o comando a seguir para enviar a solicitação 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/interactions"

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação 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/interactions" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a seguinte.

Observe o seguinte no URL deste exemplo:
  • Use o generateContent para solicitar que a resposta seja retornada depois de ser totalmente gerada. Para reduzir a percepção de latência ao público humano, transmita a resposta à medida que geradas usando o streamGenerateContent .
  • O ID do modelo multimodal está localizado no final do URL, antes do método (por exemplo, gemini-3.5-flash). Este exemplo pode oferecer suporte a outros modelos também.
  • Quando você usa um endpoint de API regional (por exemplo, us-central1), a região do URL do endpoint determina onde a solicitação é processada. Qualquer local conflitante no caminho do recurso é ignorado.

Console

Para enviar um comando multimodal usando o console do Google Cloud , faça o seguinte:

  1. Na seção "Plataforma de Agentes" do console do Google Cloud , acesse a página Agent Studio.

    Acessar o Agent Studio

  2. Clique em Criar prompt.

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

    • Modelo: selecione um modelo.
  4. Opcional: para configurar parâmetros avançados, clique em Avançado e faça a configuração da seguinte maneira:

    Clique para abrir as configurações avançadas

    • Top-K: use o controle deslizante ou a caixa de texto para inserir um valor para "top-K".

      O top-k muda a forma como o modelo seleciona tokens para saída. Um top-K de 1 significa que o próximo token selecionado é o mais provável entre todos os tokens no vocabulário do modelo (também chamado de decodificação gananciosa), enquanto um top-K de 3 significa que o próximo token está selecionado entre os três tokens mais prováveis usando a temperatura.

      Para cada etapa da seleção de tokens, são amostrados os tokens top-K com as maiores probabilidades. Em seguida, os tokens são filtrados com base no valor de top-P com o token final selecionado por meio da amostragem de temperatura.

      Especifique um valor mais baixo para respostas menos aleatórias e um valor mais alto para respostas mais aleatórias.

    • Top-P: use o controle deslizante ou a caixa de texto para inserir um valor para essa parte. Os tokens são selecionados do mais provável para o menos até que a soma das probabilidades seja igual ao valor do top-P. Para ter menos resultados de variáveis, defina top-P como 0.
    • Respostas máximas: use o controle deslizante ou a caixa de texto para inserir um valor para o número de respostas a serem geradas.
    • Respostas de streaming: ative para mostrar as respostas à medida que são geradas.
    • Limite do filtro de segurança: selecione o limite de probabilidade de mostrar respostas que podem ser prejudiciais.
    • Ativar embasamento: o embasamento não é compatível com solicitações multimodais.
    • Região: selecione a região que você quer usar.
    • Temperatura: use o controle deslizante ou a caixa de texto para inserir um valor para a temperatura.

          
      The temperature is used for sampling during response generation, which occurs when topP
      and topK are applied. Temperature controls the degree of randomness in token selection.
      Lower temperatures are good for prompts that require a less open-ended or creative response, while
      higher temperatures can lead to more diverse or creative results. A temperature of 0
      means that the highest probability tokens are always selected. In this case, responses for a given
      prompt are mostly deterministic, but a small amount of variation is still possible.
      
      

      If the model returns a response that's too generic, too short, or the model gives a fallback response, try increasing the temperature. If the model enters infinite generation, increasing the temperature to at least 0.1 may lead to improved results.

      1.0 is the recommended starting value for temperature. </li> <li>**Output token limit**: Use the slider or textbox to enter a value for the max output limit. Maximum number of tokens that can be generated in the response. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words.

      Specify a lower value for shorter responses and a higher value for potentially longer responses.

      </li> <li>**Add stop sequence**: Optional. Enter a stop sequence, which is a series of characters that includes spaces. If the model encounters a stop sequence, the response generation stops. The stop sequence isn't included in the response, and you can add up to five stop sequences.</li> </ul>

  5. Clique em Inserir mídia e selecione uma origem para o arquivo.

    Fazer upload

    Selecione o arquivo que você quer enviar e clique em Abrir.

    Por URL

    Insira o URL do arquivo que você quer usar e clique em Inserir.

    YouTube

    Insira o URL do vídeo do YouTube que você quer usar e clique em Inserir.

    Você pode usar qualquer vídeo público ou um vídeo que seja de propriedade da conta que você usou para fazer login no console do Google Cloud .

    Cloud Storage

    Selecione o bucket e o arquivo que você quer importar e clique em Selecionar.

    Google Drive

    1. Escolha uma conta e conceda consentimento ao Agent Studio para acessar sua conta na primeira vez que você selecionar essa opção. É possível fazer upload vários arquivos que tenham um tamanho total de até 10 MB. Um único arquivo não pode exceder 7 MB.
    2. Clique no arquivo que você quer adicionar.
    3. Clique em Selecionar.

      A miniatura do arquivo é mostrada no painel Comando. O número total de tokens também é exibido. Se os dados do comando excederem o limite de tokens, os tokens serão truncados e não serão incluídos no processamento dos dados.

  6. Digite o comando de texto no painel Prompt.

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

  8. Clique em Enviar.

  9. Opcional: para salvar o comando em Meus comandos, clique em Salvar.

  10. Opcional: para receber o código Python ou um comando curl para seu comando, clique em Criar com código > Receber código.

Personalizar o processamento de vídeos

É possível personalizar o processamento de vídeo na API Gemini para Google Cloud definindo intervalos de corte ou fornecendo amostragem de frame rate personalizada.

Definir intervalos de corte

É possível cortar vídeos especificando videoMetadata com deslocamentos de início e término.

Definir um frame rate personalizado

É possível definir uma amostragem de frame rate personalizada transmitindo um argumento fps para videoMetadata.

Por padrão, 1 quadro por segundo (QPS) é amostrado do vídeo. É recomendável definir um FPS baixo (< 1) para vídeos longos. Isso é útil principalmente para vídeos estáticos (por exemplo, palestras). Se você quiser capturar mais detalhes em imagens que mudam rapidamente, defina um valor de QPS mais alto.

Compreensão agêntica de vídeos

A compreensão agêntica de vídeos permite que o modelo navegue dinamicamente pelo conteúdo do vídeo, em vez de processar cada frame de forma estática. A compreensão de vídeo agêntica usa menos tokens do que o processamento estático e pode melhorar a qualidade da resposta. Isso pode resultar em custos mais baixos e respostas mais rápidas para cargas de trabalho de vídeos mais longos.

É possível usar a compreensão agêntica de vídeos e o processamento estático para vídeos diferentes na mesma solicitação. Por exemplo, se você tiver vídeos mais longos (como uma palestra de uma hora) e vídeos mais curtos (como o YouTube Shorts), use a compreensão de vídeo agêntica nos vídeos longos para segmentar informações contextualmente relevantes e o processamento estático no conteúdo de vídeo de curta duração para precisão no nível do frame.

O contexto do vídeo precisa ser preservado em todas as interações de uma conversa:

  • API Interactions: por padrão, as interações com estado preservam o contexto do vídeo automaticamente ao usar previous_interaction_id. Para solicitações sem estado (quando não estiver usando previous_interaction_id), a resposta inclui steps que codificam o contexto do vídeo. É necessário transmitir essas etapas para o próximo turno para preservar o contexto.
  • API GenerateContent: é necessário transmitir o histórico completo da conversa (todas as interações anteriores de contents) em cada solicitação subsequente para preservar o contexto.

Se o contexto do vídeo for omitido em uma rodada de acompanhamento, o modelo não poderá responder a perguntas sobre o vídeo sem reprocessá-lo.

Modelos e tipos de arquivo compatíveis

A compreensão agêntica de vídeos está disponível nos seguintes modelos:

Clique para abrir os modelos compatíveis

Você pode usar as seguintes fontes ao usar a compreensão agêntica de vídeos:

  • URLs do YouTube
  • URIs do Cloud Storage
  • Arquivos de vídeo codificados em Base64 inline

Quando usar a compreensão agêntica de vídeos

Use a compreensão agêntica de vídeos (media_processing = "AGENTIC") para as seguintes cargas de trabalho:

  • Perguntas e respostas e pesquisa em vídeos longos: faça perguntas específicas ou localize eventos específicos em palestras, reuniões, gravações ou tutoriais em vídeo de uma hora sem tokenizar cada frame em resolução máxima.
  • Inspeção visual detalhada: amplie carimbos de data/hora específicos ou detalhes visuais (como ler textos pequenos na tela, slides ou mudanças no placar) em um vídeo mais longo.
  • Comparação de vários vídeos: compare vários vídeos em uma única solicitação. É possível usar diferentes modos de processamento para cada vídeo na mesma solicitação.
  • Agentes com tecnologia de vídeo: crie agentes que analisam o conteúdo de vídeo com suporte a conversas em vários turnos. O contexto do vídeo é preservado entre as interações sem reprocessamento.
  • Otimização de custos para cargas de trabalho de vídeo longas: reduza o consumo de tokens para aplicativos de vídeo de formato longo em que apenas um subconjunto de segmentos é relevante para o comando.

Mantenha o processamento estático padrão (media_processing = "STATIC") quando:

  • Processamento de clipes curtos: para vídeos curtos, o processamento estático evita a sobrecarga de navegação em ferramentas de várias etapas e normalmente usa menos tokens com menor latência.
  • Processamento uniforme de vídeo completo: sua carga de trabalho requer uma análise uniforme frame a frame em todo o clipe, em vez de uma inspeção direcionada de segmentos específicos.

Usar a compreensão agêntica de vídeos

Para ativar a compreensão de vídeo agêntica, defina "processing": "agentic" na API Interactions ou media_processing = "AGENTIC" na API GenerateContent:

Python

API GenerateContent

from google import genai
from google.genai import types

client = genai.Client()

# Example: Controlling media_processing explicitly
video_part = types.Part(
  file_data=types.FileData(
      file_uri="gs://my-bucket-name/sports_clip.mp4",
      mime_type="video/mp4",
  ),
  media_processing="agentic" # Options: "agentic", "static"
)

response = client.models.generate_content(
  model="gemini-3.7-flash",
  contents=[
      video_part,
      "Analyze the player's footwork right before the shot."
  ]
)
print(response.text)

API Interactions

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Example: Controlling video processing explicitly
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": "gs://my-bucket-name/sports_clip.mp4",
            "mime_type": "video/mp4",
            "processing": "agentic",  # Options: "agentic", "static"
        },
        {
            "type": "text",
            "text": "Analyze the player's footwork right before the shot.",
        },
    ],
    generation_config={
        "thinking_level": "medium",
    },
)
print(interaction.output_text)

REST

API GenerateContent

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "contents": [
    {
      "role": "USER",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://my-bucket/lecture.mp4"
          },
          "mediaProcessing": "AGENTIC"
        },
        {
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingLevel": "MEDIUM"
  }
}
EOF

Depois execute o comando a seguir para enviar a solicitação 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/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.7-flash:generateContent"

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "contents": [
    {
      "role": "USER",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://my-bucket/lecture.mp4"
          },
          "mediaProcessing": "AGENTIC"
        },
        {
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingLevel": "MEDIUM"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação 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/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.7-flash:generateContent" | Select-Object -Expand Content

API Interactions

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "mime_type": "video/mp4",
          "uri": "gs://my-bucket/lecture.mp4",
          "processing": "agentic"
        },
        {
          "type": "text",
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generation_config": {
    "thinking_level": "medium"
  }
}
EOF

Depois execute o comando a seguir para enviar a solicitação 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/v1beta1/projects/PROJECT_ID/locations/global/interactions"

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "mime_type": "video/mp4",
          "uri": "gs://my-bucket/lecture.mp4",
          "processing": "agentic"
        },
        {
          "type": "text",
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generation_config": {
    "thinking_level": "medium"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação 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/v1beta1/projects/PROJECT_ID/locations/global/interactions" | Select-Object -Expand Content

A compreensão agêntica de vídeos é definida como STATIC ou desativada por padrão para todos os modelos compatíveis.

Ajustar a resolução de mídia

É possível ajustar MediaResolution para processar seus vídeos com menos tokens.

Definir parâmetros opcionais do modelo

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

Tokenização de vídeo

Com o Gemini 3, a tokenização de vídeo usa um comprimento de sequência variável, que substitui o método Pan and Scan usado em modelos anteriores para melhorar a qualidade e a latência.

É possível especificar uma resolução de mídia para entradas de vídeo, o que afeta como os vídeos são tokenizados e quantos tokens são usados para cada vídeo. É possível definir media_resolution em generationConfig para aplicar a todas as mídias na solicitação ou definir para trechos de áudio individuais, o que vai substituir a configuração de nível superior. A resolução padrão para vídeos é de 70 tokens por frame.

As seguintes resoluções estão disponíveis para os modelos do Gemini 3:

  • MEDIA_RESOLUTION_HIGH: 280 tokens por frame
  • MEDIA_RESOLUTION_MEDIUM: 70 tokens por frame
  • MEDIA_RESOLUTION_LOW: 70 tokens por frame
  • MEDIA_RESOLUTION_UNSPECIFIED: 70 tokens por frame (padrão)

Para modelos anteriores ao Gemini 3, cada frame é tokenizado em 258 tokens por frame para resolução padrão ou 66 tokens por frame para baixa resolução.

Este exemplo de código demonstra como ajustar media_resolution:

API GenerateContent

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3.1-pro-preview",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_HIGH
          ),
      ),
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4",
              mime_type="video/mp4",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_LOW
          ),
      ),
      "When does the image appear in the video? What is the context?",
  ],
)
print(response.text)

API Interactions

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "image",
            "uri": "gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
            "mime_type": "image/png",
            "resolution": "high",  # Options: "low", "medium", "high", "ultra_high"
        },
        {
            "type": "video",
            "uri": "gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4",
            "mime_type": "video/mp4",
            "resolution": "low",  # Options: "low", "medium", "high", "ultra_high"
        },
        {
            "type": "text",
            "text": "When does the image appear in the video? What is the context?",
        },
    ],
)
print(interaction.output_text)

Práticas recomendadas

Ao usar vídeos, siga as práticas recomendadas e informações abaixo para ter os melhores resultados:

  • Se o comando contiver um único vídeo, coloque o vídeo antes do comando de texto.
  • Se você precisar de localização de carimbo de data/hora em um vídeo com áudio, peça ao modelo para gerar carimbos de data/hora que sigam o formato descrito em "Formato de carimbo de data/hora".

Para os modelos do Gemini 3, considere também o seguinte:

  • Use uma taxa de amostragem de quadros por segundo (QPS) mais alta para vídeos que exigem análise temporal granular, como compreensão de ações rápidas ou rastreamento de movimento em alta velocidade.

Limitações

Embora os modelos multimodais do Gemini sejam eficientes em muitos casos de uso multimodais, é importante entender as limitações dos modelos:

  • Moderação de conteúdo: os modelos se recusam a fornecer respostas sobre vídeos que violam nossas políticas de segurança.
  • Reconhecimento de som sem fala: os modelos compatíveis com áudio podem cometer erros ao reconhecer sons que não são fala.

Detalhes técnicos sobre vídeos

  • Processamento da API File: ao usar a API File, os vídeos são amostrados a 1 quadro por segundo (QPS) e o áudio é processado a 1 Kbps (canal único). Os carimbos de data/hora são adicionados a cada segundo.

    • Essas taxas estão sujeitas a alterações no futuro para melhorias na inferência.
  • Formato de marcação de tempo: ao se referir a momentos específicos de um vídeo no comando, o formato de marcação de tempo depende da taxa de amostragem de quadros por segundo (FPS) do vídeo:

    • Para taxas de amostragem de 1 FPS ou menos: use o formato MM:SS, em que os dois primeiros dígitos representam minutos e os dois últimos dígitos representam segundos. Se você tiver deslocamentos maiores que 1 hora, use o formato H:MM:SS.

    • Para taxas de amostragem acima de 1 FPS: use o formato MM:SS.sss ou, se você tiver deslocamentos maiores que 1 hora, use o formato H:MM:SS.sss, descrito da seguinte maneira:

      • O primeiro dígito representa a hora.
      • Os dois dígitos seguintes representam os minutos.
      • Os dois dígitos seguintes representam os segundos.
      • Os últimos três dígitos representam os subsegundos.
  • Práticas recomendadas:

    • Para melhores resultados, use apenas um vídeo por comando.

    • Se você combinar texto e um único vídeo, coloque o comando de texto depois da parte do vídeo na matriz contents.

    • Sequências de ação rápida podem perder detalhes devido à taxa de amostragem de 1 FPS. Considere desacelerar esses clipes, se necessário.

A seguir