Caching

Com o armazenamento em cache de contexto, é possível salvar e reutilizar tokens de entrada pré-computados que você quer usar várias vezes, por exemplo, ao fazer perguntas diferentes sobre o mesmo arquivo de mídia. Isso pode gerar economia de custo e velocidade, dependendo do uso. Para uma introdução detalhada, consulte o guia Armazenamento em cache de contexto.

Método: cachedContents.create

Cria um recurso CachedContent.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/cachedContents

Corpo da solicitação

O corpo da solicitação contém uma instância de CachedContent.

Campos
contents[] object (Content)

Opcional. Somente entrada. Imutável. O conteúdo a ser armazenado em cache.

tools[] object (Tool)

Opcional. Somente entrada. Imutável. Uma lista de Tools que o modelo pode usar para gerar a próxima resposta

expiration Union type
Especifica quando este recurso vai expirar. expiration pode ser apenas de um dos tipos a seguir:
expireTime string (Timestamp format)

Carimbo de data/hora em UTC de quando o recurso será considerado expirado. Isso é sempre fornecido na saída, independente do que foi enviado na entrada.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

ttl string (Duration format)

Somente entrada. Novo TTL para este recurso, somente entrada.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

displayName string

Opcional. Imutável. O nome de exibição significativo gerado pelo usuário do conteúdo armazenado em cache. Máximo de 128 caracteres Unicode.

model string

Obrigatório. Imutável. O nome do Model a ser usado para conteúdo armazenado em cache. Formato: models/{model}

systemInstruction object (Content)

Opcional. Somente entrada. Imutável. Instrução do sistema definida pelo desenvolvedor. No momento, somente texto.

toolConfig object (ToolConfig)

Opcional. Somente entrada. Imutável. Configuração da ferramenta. Essa configuração é compartilhada com todas as ferramentas.

Exemplo de solicitação

Básico

Python

from google import genai
from google.genai import types

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-1.5-flash-001"

cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
        contents=[document],
        system_instruction="You are an expert analyzing transcripts.",
    ),
)
print(cache)

response = client.models.generate_content(
    model=model_name,
    contents="Please summarize this transcript",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)
cache.py

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-1.5-flash-001";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});
console.log("Cache created:", cache);

const response = await ai.models.generateContent({
  model: modelName,
  contents: "Please summarize this transcript",
  config: { cachedContent: cache.name },
});
console.log("Response text:", response.text);
cache.js

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"), 
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents: contents,
	SystemInstruction: genai.NewContentFromText(
		"You are an expert analyzing transcripts.", genai.RoleUser,
	),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println("Cache created:")
fmt.Println(cache)

// Use the cache for generating content.
response, err := client.Models.GenerateContent(
	ctx,
	modelName,
	genai.Text("Please summarize this transcript"),
	&genai.GenerateContentConfig{
		CachedContent: cache.Name,
	},
)
if err != nil {
	log.Fatal(err)
}
printResponse(response)
cache.go

Shell

wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-1.5-flash-001",
  "contents":[
    {
      "parts":[
        {
          "inline_data": {
            "mime_type":"text/plain",
            "data": "'$(base64 $B64FLAGS a11.txt)'"
          }
        }
      ],
    "role": "user"
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are an expert at analyzing transcripts."
      }
    ]
  },
  "ttl": "300s"
}' > request.json

curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d @request.json \
 > cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-001:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'
cache.sh

Nome do remetente

Python

from google import genai
from google.genai import types

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-1.5-flash-001"

cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
        contents=[document],
        system_instruction="You are an expert analyzing transcripts.",
    ),
)
cache_name = cache.name  # Save the name for later

# Later retrieve the cache
cache = client.caches.get(name=cache_name)
response = client.models.generate_content(
    model=model_name,
    contents="Find a lighthearted moment from this transcript",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)
cache.py

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-1.5-flash-001";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});
const cacheName = cache.name; // Save the name for later

// Later retrieve the cache
const retrievedCache = await ai.caches.get({ name: cacheName });
const response = await ai.models.generateContent({
  model: modelName,
  contents: "Find a lighthearted moment from this transcript",
  config: { cachedContent: retrievedCache.name },
});
console.log("Response text:", response.text);
cache.js

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents:          contents,
	SystemInstruction: genai.NewContentFromText(
		"You are an expert analyzing transcripts.", genai.RoleUser,
	),
})
if err != nil {
	log.Fatal(err)
}
cacheName := cache.Name

// Later retrieve the cache.
cache, err = client.Caches.Get(ctx, cacheName, &genai.GetCachedContentConfig{})
if err != nil {
	log.Fatal(err)
}

response, err := client.Models.GenerateContent(
	ctx,
	modelName,
	genai.Text("Find a lighthearted moment from this transcript"),
	&genai.GenerateContentConfig{
		CachedContent: cache.Name,
	},
)
if err != nil {
	log.Fatal(err)
}
fmt.Println("Response from cache (create from name):")
printResponse(response)
cache.go

No Chat

Python

from google import genai
from google.genai import types

client = genai.Client()
model_name = "gemini-1.5-flash-001"
system_instruction = "You are an expert analyzing transcripts."

# Create a chat session with the given system instruction.
chat = client.chats.create(
    model=model_name,
    config=types.GenerateContentConfig(system_instruction=system_instruction),
)
document = client.files.upload(file=media / "a11.txt")

response = chat.send_message(
    message=["Hi, could you summarize this transcript?", document]
)
print("\n\nmodel:  ", response.text)
response = chat.send_message(
    message=["Okay, could you tell me more about the trans-lunar injection"]
)
print("\n\nmodel:  ", response.text)

# To cache the conversation so far, pass the chat history as the list of contents.
cache = client.caches.create(
    model=model_name,
    config={
        "contents": chat.get_history(),
        "system_instruction": system_instruction,
    },
)
# Continue the conversation using the cached content.
chat = client.chats.create(
    model=model_name,
    config=types.GenerateContentConfig(cached_content=cache.name),
)
response = chat.send_message(
    message="I didn't understand that last part, could you explain it in simpler language?"
)
print("\n\nmodel:  ", response.text)
cache.py

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const modelName = "gemini-1.5-flash-001";
const systemInstruction = "You are an expert analyzing transcripts.";

// Create a chat session with the system instruction.
const chat = ai.chats.create({
  model: modelName,
  config: { systemInstruction: systemInstruction },
});
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);

let response = await chat.sendMessage({
  message: createUserContent([
    "Hi, could you summarize this transcript?",
    createPartFromUri(document.uri, document.mimeType),
  ]),
});
console.log("\n\nmodel:", response.text);

response = await chat.sendMessage({
  message: "Okay, could you tell me more about the trans-lunar injection",
});
console.log("\n\nmodel:", response.text);

// To cache the conversation so far, pass the chat history as the list of contents.
const chatHistory = chat.getHistory();
const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: chatHistory,
    systemInstruction: systemInstruction,
  },
});

// Continue the conversation using the cached content.
const chatWithCache = ai.chats.create({
  model: modelName,
  config: { cachedContent: cache.name },
});
response = await chatWithCache.sendMessage({
  message:
    "I didn't understand that last part, could you explain it in simpler language?",
});
console.log("\n\nmodel:", response.text);
cache.js

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
systemInstruction := "You are an expert analyzing transcripts."

// Create initial chat with a system instruction.
chat, err := client.Chats.Create(ctx, modelName, &genai.GenerateContentConfig{
	SystemInstruction: genai.NewContentFromText(systemInstruction, genai.RoleUser),
}, nil)
if err != nil {
	log.Fatal(err)
}

document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}

// Send first message with the transcript.
parts := make([]genai.Part, 2)
parts[0] = genai.Part{Text: "Hi, could you summarize this transcript?"}
parts[1] = genai.Part{
	FileData: &genai.FileData{
		FileURI :      document.URI,
		MIMEType: document.MIMEType,
	},
}

// Send chat message.
resp, err := chat.SendMessage(ctx, parts...)
if err != nil {
	log.Fatal(err)
}
fmt.Println("\n\nmodel: ", resp.Text())

resp, err = chat.SendMessage(
	ctx, 
	genai.Part{
		Text: "Okay, could you tell me more about the trans-lunar injection",
	},
)
if err != nil {
	log.Fatal(err)
}
fmt.Println("\n\nmodel: ", resp.Text())

// To cache the conversation so far, pass the chat history as the list of contents.
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents:          chat.History(false),
	SystemInstruction: genai.NewContentFromText(systemInstruction, genai.RoleUser),
})
if err != nil {
	log.Fatal(err)
}

// Continue the conversation using the cached history.
chat, err = client.Chats.Create(ctx, modelName, &genai.GenerateContentConfig{
	CachedContent: cache.Name,
}, nil)
if err != nil {
	log.Fatal(err)
}

resp, err = chat.SendMessage(
	ctx, 
	genai.Part{
		Text: "I didn't understand that last part, could you explain it in simpler language?",
	},
)
if err != nil {
	log.Fatal(err)
}
fmt.Println("\n\nmodel: ", resp.Text())
cache.go

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta incluirá uma instância de CachedContent.

Método: cachedContents.list

Lista CachedContents.

Endpoint

get https://generativelanguage.googleapis.com/v1beta/cachedContents

Parâmetros de consulta

pageSize integer

Opcional. O número máximo de conteúdos armazenados em cache a serem retornados. O serviço pode retornar um valor inferior a este. Se não for especificado, um número padrão (abaixo do máximo) de itens será retornado. O valor máximo é 1.000. Valores maiores serão convertidos para 1.000.

pageToken string

Opcional. Um token de página recebido de uma chamada cachedContents.list anterior. Forneça isso para recuperar a página subsequente.

Ao paginar, todos os outros parâmetros fornecidos para cachedContents.list precisam corresponder à chamada que forneceu o token da página.

Corpo da solicitação

O corpo da solicitação precisa estar vazio.

Corpo da resposta

Resposta com a lista CachedContents.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Campos
cachedContents[] object (CachedContent)

Lista de conteúdo armazenado em cache.

nextPageToken string

Um token, que pode ser enviado como pageToken para recuperar a próxima página. Se esse campo for omitido, não haverá páginas subsequentes.

Representação JSON 
{
  "cachedContents": [
    {
      object (CachedContent)
    }
  ],
  "nextPageToken": string
}

Método: cachedContents.get

Lê o recurso CachedContent.

Endpoint

get https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}

Parâmetros de caminho

name string

Obrigatório. O nome do recurso que se refere à entrada do cache de conteúdo. Formato: cachedContents/{id}. Ele tem o formato cachedContents/{cachedcontent}.

Corpo da solicitação

O corpo da solicitação precisa estar vazio.

Exemplo de solicitação

Python

from google import genai

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-1.5-flash-001"

cache = client.caches.create(
    model=model_name,
    config={
        "contents": [document],
        "system_instruction": "You are an expert analyzing transcripts.",
    },
)
print(client.caches.get(name=cache.name))
cache.py

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-1.5-flash-001";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});
const retrievedCache = await ai.caches.get({ name: cache.name });
console.log("Retrieved Cache:", retrievedCache);
cache.js

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents:          contents,
	SystemInstruction: genai.NewContentFromText(
		"You are an expert analyzing transcripts.", genai.RoleUser,
	),
})
if err != nil {
	log.Fatal(err)
}

cache, err = client.Caches.Get(ctx, cache.Name, &genai.GetCachedContentConfig{})
if err != nil {
	log.Fatal(err)
}
fmt.Println("Retrieved cache:")
fmt.Println(cache)
cache.go

Shell

curl "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"
cache.sh

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de CachedContent.

Método: cachedContents.patch

Atualiza o recurso "CachedContent". Somente o vencimento pode ser atualizado.

Endpoint

patch https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}

PATCH https://generativelanguage.googleapis.com/v1beta/{cachedContent.name=cachedContents/*}

Parâmetros de caminho

cachedContent.name string

Apenas saída. Identificador. O nome do recurso que se refere ao conteúdo armazenado em cache. Formato: cachedContents/{id}. Ele tem o formato cachedContents/{cachedcontent}.

Parâmetros de consulta

updateMask string (FieldMask format)

Lista de campos a serem atualizados.

É uma lista separada por vírgulas de nomes de campos totalmente qualificados. Exemplo: "user.displayName,photo".

Corpo da solicitação

O corpo da solicitação contém uma instância de CachedContent.

Campos
expiration Union type
Especifica quando este recurso vai expirar. expiration pode ser apenas de um dos tipos a seguir:
expireTime string (Timestamp format)

Carimbo de data/hora em UTC de quando o recurso será considerado expirado. Isso é sempre fornecido na saída, independente do que foi enviado na entrada.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

ttl string (Duration format)

Somente entrada. Novo TTL para este recurso, somente entrada.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

Exemplo de solicitação

Python

from google import genai
from google.genai import types
import datetime

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-1.5-flash-001"

cache = client.caches.create(
    model=model_name,
    config={
        "contents": [document],
        "system_instruction": "You are an expert analyzing transcripts.",
    },
)

# Update the cache's time-to-live (ttl)
ttl = f"{int(datetime.timedelta(hours=2).total_seconds())}s"
client.caches.update(
    name=cache.name, config=types.UpdateCachedContentConfig(ttl=ttl)
)
print(f"After update:\n {cache}")

# Alternatively, update the expire_time directly
# Update the expire_time directly in valid RFC 3339 format (UTC with a "Z" suffix)
expire_time = (
    (
        datetime.datetime.now(datetime.timezone.utc)
        + datetime.timedelta(minutes=15)
    )
    .isoformat()
    .replace("+00:00", "Z")
)
client.caches.update(
    name=cache.name,
    config=types.UpdateCachedContentConfig(expire_time=expire_time),
)
cache.py

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-1.5-flash-001";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

let cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});

// Update the cache's time-to-live (ttl)
const ttl = `${2 * 3600}s`; // 2 hours in seconds
cache = await ai.caches.update({
  name: cache.name,
  config: { ttl },
});
console.log("After update (TTL):", cache);

// Alternatively, update the expire_time directly (in RFC 3339 format with a "Z" suffix)
const expireTime = new Date(Date.now() + 15 * 60000)
  .toISOString()
  .replace(/\.\d{3}Z$/, "Z");
cache = await ai.caches.update({
  name: cache.name,
  config: { expireTime: expireTime },
});
console.log("After update (expire_time):", cache);
cache.js

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents:          contents,
	SystemInstruction: genai.NewContentFromText(
		"You are an expert analyzing transcripts.", genai.RoleUser,
	),
})
if err != nil {
	log.Fatal(err)
}

_, err = client.Caches.Delete(ctx, cache.Name, &genai.DeleteCachedContentConfig{})
if err != nil {
	log.Fatal(err)
}
fmt.Println("Cache deleted:", cache.Name)
cache.go

Shell

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'
cache.sh

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de CachedContent.

Método: cachedContents.delete

Exclui o recurso CachedContent.

Endpoint

delete https://generativelanguage.googleapis.com/v1beta/{name=cachedContents/*}

Parâmetros de caminho

name string

Obrigatório. O nome do recurso referente à entrada de cache de conteúdo. Formato: cachedContents/{id}. Ele tem o formato cachedContents/{cachedcontent}.

Corpo da solicitação

O corpo da solicitação precisa estar vazio.

Exemplo de solicitação

Python

from google import genai

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-1.5-flash-001"

cache = client.caches.create(
    model=model_name,
    config={
        "contents": [document],
        "system_instruction": "You are an expert analyzing transcripts.",
    },
)
client.caches.delete(name=cache.name)
cache.py

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const filePath = path.join(media, "a11.txt");
const document = await ai.files.upload({
  file: filePath,
  config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", document.name);
const modelName = "gemini-1.5-flash-001";

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: "You are an expert analyzing transcripts.",
  },
});
await ai.caches.delete({ name: cache.name });
console.log("Cache deleted:", cache.name);
cache.js

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-1.5-flash-001"
document, err := client.Files.UploadFromPath(
	ctx, 
	filepath.Join(getMedia(), "a11.txt"), 
	&genai.UploadFileConfig{
		MIMEType : "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents:          contents,
	SystemInstruction: genai.NewContentFromText(
		"You are an expert analyzing transcripts.", genai.RoleUser,
	),
})
if err != nil {
	log.Fatal(err)
}

_, err = client.Caches.Delete(ctx, cache.Name, &genai.DeleteCachedContentConfig{})
if err != nil {
	log.Fatal(err)
}
fmt.Println("Cache deleted:", cache.Name)
cache.go

Shell

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"
cache.sh

Corpo da resposta

Se não houver nenhum problema, o corpo da resposta será um objeto JSON vazio.

Recurso REST: cachedContents

Recurso: CachedContent

Conteúdo que foi pré-processado e pode ser usado em solicitações subsequentes para GenerativeService.

O conteúdo armazenado em cache só pode ser usado com o modelo para o qual foi criado.

Campos
contents[] object (Content)

Opcional. Somente entrada. Imutável. O conteúdo a ser armazenado em cache.

tools[] object (Tool)

Opcional. Somente entrada. Imutável. Uma lista de Tools que o modelo pode usar para gerar a próxima resposta

createTime string (Timestamp format)

Apenas saída. Hora de criação da entrada de cache.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

Apenas saída. Quando a entrada de cache foi atualizada pela última vez em UTC.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

usageMetadata object (UsageMetadata)

Apenas saída. Metadados sobre o uso do conteúdo armazenado em cache.

expiration Union type
Especifica quando este recurso vai expirar. expiration pode ser apenas de um dos tipos a seguir:
expireTime string (Timestamp format)

Carimbo de data/hora em UTC de quando o recurso será considerado expirado. Isso é sempre fornecido na saída, independente do que foi enviado na entrada.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

ttl string (Duration format)

Somente entrada. Novo TTL para este recurso, somente entrada.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

name string

Apenas saída. Identificador. O nome do recurso que se refere ao conteúdo armazenado em cache. Formato: cachedContents/{id}

displayName string

Opcional. Imutável. O nome de exibição significativo gerado pelo usuário do conteúdo armazenado em cache. Máximo de 128 caracteres Unicode.

model string

Obrigatório. Imutável. O nome do Model a ser usado para conteúdo armazenado em cache. Formato: models/{model}

systemInstruction object (Content)

Opcional. Somente entrada. Imutável. Instrução do sistema definida pelo desenvolvedor. No momento, somente texto.

toolConfig object (ToolConfig)

Opcional. Somente entrada. Imutável. Configuração da ferramenta. Essa configuração é compartilhada com todas as ferramentas.

Representação JSON 
{
  "contents": [
    {
      object (Content)
    }
  ],
  "tools": [
    {
      object (Tool)
    }
  ],
  "createTime": string,
  "updateTime": string,
  "usageMetadata": {
    object (UsageMetadata)
  },

  // expiration
  "expireTime": string,
  "ttl": string
  // Union type
  "name": string,
  "displayName": string,
  "model": string,
  "systemInstruction": {
    object (Content)
  },
  "toolConfig": {
    object (ToolConfig)
  }
}

Conteúdo

O tipo de dados estruturados de base que contém várias partes de uma mensagem.

Um Content inclui um campo role que designa o produtor do Content e um campo parts que contém dados de várias partes com o conteúdo da troca de mensagens.

Campos
parts[] object (Part)

Parts ordenados que constituem uma única mensagem. As partes podem ter diferentes tipos MIME.

role string

Opcional. O produtor do conteúdo. Precisa ser "user" ou "model".

Útil para definir conversas com vários turnos. Caso contrário, pode ser deixado em branco ou sem definição.

Representação JSON 
{
  "parts": [
    {
      object (Part)
    }
  ],
  "role": string
}

Parte

Um tipo de dados que contém mídia que faz parte de uma mensagem Content de várias partes.

Um Part consiste em dados que têm um tipo de dados associado. Um Part só pode conter um dos tipos aceitos em Part.data.

Um Part precisa ter um tipo MIME IANA fixo que identifique o tipo e o subtipo da mídia se o campo inlineData for preenchido com bytes brutos.

Campos
thought boolean

Opcional. Indica se a parte foi gerada pelo modelo.

thoughtSignature string (bytes format)

Opcional. Uma assinatura opaca para o pensamento, para que ele possa ser reutilizado em solicitações subsequentes.

Uma string codificada em base64.

partMetadata object (Struct format)

Metadados personalizados associados à parte. Os agentes que usam genai.Part como representação de conteúdo podem precisar acompanhar as informações adicionais. Por exemplo, pode ser o nome de um arquivo/fonte de onde a parte se origina ou uma maneira de multiplexar vários fluxos de partes.

mediaResolution object (MediaResolution)

Opcional. Resolução da mídia de entrada.

data Union type
data pode ser apenas de um dos tipos a seguir:
text string

Texto inline.

inlineData object (Blob)

Bytes de mídia inline.

functionCall object (FunctionCall)

Um FunctionCall previsto retornado do modelo que contém uma string que representa o FunctionDeclaration.name com os argumentos e os valores deles.

functionResponse object (FunctionResponse)

A saída resultante de uma FunctionCall que contém uma string que representa o FunctionDeclaration.name e um objeto JSON estruturado com qualquer saída da função é usada como contexto para o modelo.

fileData object (FileData)

Dados baseados em URI.

executableCode object (ExecutableCode)

Código gerado pelo modelo para ser executado.

codeExecutionResult object (CodeExecutionResult)

Resultado da execução do ExecutableCode.

toolCall object (ToolCall)

Chamada de ferramenta do lado do servidor. Esse campo é preenchido quando o modelo prevê uma invocação de ferramenta que precisa ser executada no servidor. O cliente deve repetir essa mensagem para a API.

toolResponse object (ToolResponse)

A saída de uma execução de ToolCall do lado do servidor. Esse campo é preenchido pelo cliente com os resultados da execução do ToolCall correspondente.

metadata Union type
Controla o pré-processamento extra de dados. metadata pode ser apenas de um dos tipos a seguir:
videoMetadata object (VideoMetadata)

Opcional. Metadados do vídeo. Os metadados só devem ser especificados enquanto os dados do vídeo estiverem apresentados em inlineData ou fileData.

Representação JSON 
{
  "thought": boolean,
  "thoughtSignature": string,
  "partMetadata": {
    object
  },
  "mediaResolution": {
    object (MediaResolution)
  },

  // data
  "text": string,
  "inlineData": {
    object (Blob)
  },
  "functionCall": {
    object (FunctionCall)
  },
  "functionResponse": {
    object (FunctionResponse)
  },
  "fileData": {
    object (FileData)
  },
  "executableCode": {
    object (ExecutableCode)
  },
  "codeExecutionResult": {
    object (CodeExecutionResult)
  },
  "toolCall": {
    object (ToolCall)
  },
  "toolResponse": {
    object (ToolResponse)
  }
  // Union type

  // metadata
  "videoMetadata": {
    object (VideoMetadata)
  }
  // Union type
}

Blob

Bytes de mídia brutos.

O texto não pode ser enviado como bytes brutos. Use o campo "text".

Campos
mimeType string

O tipo MIME padrão da IANA dos dados de origem. Exemplos: - image/png - image/jpeg Se um tipo MIME sem suporte for fornecido, um erro será retornado. Para uma lista completa de tipos compatíveis, consulte Formatos de arquivo compatíveis.

data string (bytes format)

Bytes brutos para formatos de mídia.

Uma string codificada em base64.

Representação JSON 
{
  "mimeType": string,
  "data": string
}

FunctionCall

Um FunctionCall previsto retornado do modelo que contém uma string que representa o FunctionDeclaration.name com os argumentos e os valores deles.

Campos
id string

Opcional. Identificador exclusivo da chamada de função. Se preenchido, o cliente vai executar o functionCall e retornar a resposta com o id correspondente.

name string

Obrigatório. O nome da função a ser chamada. Precisa ser az, AZ, 0-9 ou conter sublinhados e traços, com um tamanho máximo de 128.

args object (Struct format)

Opcional. Os parâmetros e valores da função no formato de objeto JSON.

Representação JSON 
{
  "id": string,
  "name": string,
  "args": {
    object
  }
}

FunctionResponse

A saída resultante de uma FunctionCall que contém uma string que representa o FunctionDeclaration.name e um objeto JSON estruturado com qualquer saída da função é usada como contexto para o modelo. Ela precisa conter o resultado de umaFunctionCall feita com base na previsão do modelo.

Campos
id string

Opcional. O identificador da chamada de função a que esta resposta se refere. Preenchido pelo cliente para corresponder à chamada de função id.

name string

Obrigatório. O nome da função a ser chamada. Precisa ser az, AZ, 0-9 ou conter sublinhados e traços, com um tamanho máximo de 128.

response object (Struct format)

Obrigatório. A resposta da função no formato de objeto JSON. Os chamadores podem usar qualquer chave que se ajuste à sintaxe da função para retornar a saída dela, por exemplo, "output", "result" etc. Em particular, se a chamada de função não for executada, a resposta poderá ter uma chave "error" para retornar detalhes do erro ao modelo.

parts[] object (FunctionResponsePart)

Opcional. Parts ordenados que constituem uma resposta de função. As partes podem ter diferentes tipos MIME IANA.

willContinue boolean

Opcional. Sinaliza que a chamada de função continua e mais respostas serão retornadas, transformando a chamada de função em um gerador. É aplicável apenas a chamadas de função NON_BLOCKING. Caso contrário, é ignorado. Se for definido como "false", as respostas futuras não serão consideradas. É permitido retornar response vazio com willContinue=False para sinalizar que a chamada de função foi concluída. Isso ainda pode acionar a geração de modelos. Para evitar acionar a geração e concluir a chamada de função, defina scheduling como SILENT.

scheduling enum (Scheduling)

Opcional. Especifica como a resposta deve ser programada na conversa. Aplicável apenas a chamadas de função NON_BLOCKING. Caso contrário, é ignorado. O padrão é WHEN_IDLE.

Representação JSON 
{
  "id": string,
  "name": string,
  "response": {
    object
  },
  "parts": [
    {
      object (FunctionResponsePart)
    }
  ],
  "willContinue": boolean,
  "scheduling": enum (Scheduling)
}

FunctionResponsePart

Um tipo de dados que contém mídia que faz parte de uma mensagem FunctionResponse.

Um FunctionResponsePart consiste em dados que têm um tipo de dados associado. Um FunctionResponsePart só pode conter um dos tipos aceitos em FunctionResponsePart.data.

Um FunctionResponsePart precisa ter um tipo MIME IANA fixo que identifique o tipo e o subtipo da mídia se o campo inlineData for preenchido com bytes brutos.

Campos
data Union type
Os dados da parte de resposta da função. data pode ser apenas de um dos tipos a seguir:
inlineData object (FunctionResponseBlob)

Bytes de mídia inline.

Representação JSON 
{

  // data
  "inlineData": {
    object (FunctionResponseBlob)
  }
  // Union type
}

FunctionResponseBlob

Bytes de mídia brutos para resposta da função.

O texto não deve ser enviado como bytes brutos. Use o campo "FunctionResponse.response".

Campos
mimeType string

O tipo MIME padrão da IANA dos dados de origem. Exemplos: - image/png - image/jpeg Se um tipo MIME sem suporte for fornecido, um erro será retornado. Para uma lista completa de tipos compatíveis, consulte Formatos de arquivo compatíveis.

data string (bytes format)

Bytes brutos para formatos de mídia.

Uma string codificada em base64.

Representação JSON 
{
  "mimeType": string,
  "data": string
}

Programação

Especifica como a resposta deve ser programada na conversa.

Tipos enumerados
SCHEDULING_UNSPECIFIED Esse valor não é usado.
SILENT Adicione apenas o resultado ao contexto da conversa, sem interromper ou acionar a geração.
WHEN_IDLE Adicione o resultado ao contexto da conversa e peça para gerar a saída sem interromper a geração em andamento.
INTERRUPT Adicione o resultado ao contexto da conversa, interrompa a geração em andamento e peça para gerar a saída.

FileData

Dados baseados em URI.

Campos
mimeType string

Opcional. O tipo MIME padrão da IANA dos dados de origem.

fileUri string

Obrigatório. URI.

Representação JSON 
{
  "mimeType": string,
  "fileUri": string
}

ExecutableCode

Código gerado pelo modelo para ser executado e o resultado retornado ao modelo.

Gerado apenas ao usar a ferramenta CodeExecution, em que o código é executado automaticamente e um CodeExecutionResult correspondente também é gerado.

Campos
id string

Opcional. Identificador exclusivo da parte ExecutableCode. O servidor retorna o CodeExecutionResult com o id correspondente.

language enum (Language)

Obrigatório. Linguagem de programação do code.

code string

Obrigatório. O código a ser executado.

Representação JSON 
{
  "id": string,
  "language": enum (Language),
  "code": string
}

Idioma

Linguagens de programação compatíveis com o código gerado.

Tipos enumerados
LANGUAGE_UNSPECIFIED Idioma não especificado. Esse valor não deve ser usado.
PYTHON Python >= 3.10, com numpy e simpy disponíveis. O Python é o idioma padrão.

CodeExecutionResult

Resultado da execução do ExecutableCode.

Gerado somente quando a ferramenta CodeExecution é usada.

Campos
id string

Opcional. O identificador da parte ExecutableCode a que este resultado se refere. Preenchido apenas se o ExecutableCode correspondente tiver um ID.

outcome enum (Outcome)

Obrigatório. Resultado da execução do código.

output string

Opcional. Contém stdout quando a execução do código é bem-sucedida, stderr ou outra descrição.

Representação JSON 
{
  "id": string,
  "outcome": enum (Outcome),
  "output": string
}

Resultado

Enumeração dos possíveis resultados da execução do código.

Tipos enumerados
OUTCOME_UNSPECIFIED Status não especificado. Esse valor não deve ser usado.
OUTCOME_OK A execução do código foi concluída. output contém o stdout, se houver.
OUTCOME_FAILED Falha na execução do código. output contém stderr e stdout, se houver.
OUTCOME_DEADLINE_EXCEEDED A execução do código durou muito tempo e foi cancelada. Pode ou não haver um output parcial.

ToolCall

Um ToolCall previsto do lado do servidor retornado pelo modelo. Essa mensagem contém informações sobre uma ferramenta que o modelo quer invocar. Não é esperado que o cliente execute esse ToolCall. Em vez disso, o cliente precisa transmitir esse ToolCall de volta para a API em uma próxima vez em uma mensagem Content, junto com o ToolResponse correspondente.

Campos
id string

Opcional. Identificador exclusivo da chamada de função. O servidor retorna a resposta da ferramenta com o id correspondente.

toolType enum (ToolType)

Obrigatório. O tipo de ferramenta que foi chamada.

args object (Struct format)

Opcional. Os argumentos da chamada de ferramenta. Exemplo: {"arg1" : "value1", "arg2" : "value2" , ...}

Representação JSON 
{
  "id": string,
  "toolType": enum (ToolType),
  "args": {
    object
  }
}

ToolType

O tipo de ferramenta na chamada de função.

Tipos enumerados
TOOL_TYPE_UNSPECIFIED Tipo de ferramenta não especificado.
GOOGLE_SEARCH_WEB Ferramenta de pesquisa do Google, mapeada para Tool.google_search.search_types.web_search.
GOOGLE_SEARCH_IMAGE Ferramenta de pesquisa por imagens, mapeada para Tool.google_search.search_types.image_search.
URL_CONTEXT Ferramenta de contexto de URL, mapeada para Tool.url_context.
GOOGLE_MAPS Ferramenta do Google Maps, mapeada para Tool.google_maps.

ToolResponse

A saída de uma execução de ToolCall do lado do servidor. Essa mensagem contém os resultados de uma invocação de ferramenta iniciada por um ToolCall do modelo. O cliente precisa transmitir esse ToolResponse de volta para a API em uma próxima vez em uma mensagem Content, junto com o ToolCall correspondente.

Campos
id string

Opcional. O identificador da chamada de função a que esta resposta se refere.

toolType enum (ToolType)

Obrigatório. O tipo de ferramenta que foi chamada, correspondente ao toolType no ToolCall correspondente.

response object (Struct format)

Opcional. A resposta da ferramenta.

Representação JSON 
{
  "id": string,
  "toolType": enum (ToolType),
  "response": {
    object
  }
}

VideoMetadata

Descontinuado: use GenerateContentRequest.processing_options. Os metadados descrevem o conteúdo do vídeo de entrada.

Campos
startOffset string (Duration format)

Opcional. O deslocamento inicial do vídeo.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

endOffset string (Duration format)

Opcional. O deslocamento final do vídeo.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

fps number

Opcional. A taxa de frames do vídeo enviado ao modelo. Se não for especificado, o valor padrão será 1,0. O intervalo de fps é (0,0, 24,0].

Representação JSON 
{
  "startOffset": string,
  "endOffset": string,
  "fps": number
}

MediaResolution

Resolução de mídia para tokenização.

Campos
value Union type
O nível de resolução da mídia. value pode ser apenas de um dos tipos a seguir:
level enum (Level)

A qualidade da tokenização usada para determinada mídia. para suporte da API Gemini .

Representação JSON 
{

  // value
  "level": enum (Level)
  // Union type
}

Nível

O nível de resolução da mídia.

Tipos enumerados
MEDIA_RESOLUTION_UNSPECIFIED A resolução da mídia não foi definida.
MEDIA_RESOLUTION_LOW A resolução da mídia está definida como baixa.
MEDIA_RESOLUTION_MEDIUM A resolução da mídia foi definida como média.
MEDIA_RESOLUTION_HIGH A resolução da mídia está definida como alta.
MEDIA_RESOLUTION_ULTRA_HIGH A resolução da mídia está definida como ultra alta.

Ferramenta

Detalhes da ferramenta que o modelo pode usar para gerar uma resposta.

Uma Tool é uma parte do código que permite ao sistema interagir com sistemas externos para realizar uma ação ou conjunto de ações fora do conhecimento e do escopo do modelo.

Próximo ID: 15

Campos
functionDeclarations[] object (FunctionDeclaration)

Opcional. Uma lista de FunctionDeclarations disponíveis para o modelo que podem ser usados para chamada de função.

O modelo ou sistema não executa a função. Em vez disso, a função definida pode ser retornada como um FunctionCall com argumentos para o lado do cliente para execução. O modelo pode decidir chamar um subconjunto dessas funções preenchendo FunctionCall na resposta. A próxima vez que você falar pode conter um FunctionResponse com o contexto de geração Content.role "function" para a próxima vez que o modelo falar.

googleSearchRetrieval object (GoogleSearchRetrieval)

Opcional. Ferramenta de recuperação com tecnologia da Pesquisa Google.

codeExecution object (CodeExecution)

Opcional. Permite que o modelo execute código como parte da geração.

computerUse object (ComputerUse)

Opcional. Ferramenta para ajudar o modelo a interagir diretamente com o computador. Se ativado, ele preenche automaticamente declarações de função específicas para uso do computador.

urlContext object (UrlContext)

Opcional. Ferramenta para oferecer suporte à recuperação de contexto de URL.

mcpServers[] object (McpServer)

Opcional. Servidores MCP a serem conectados.

googleMaps object (GoogleMaps)

Opcional. Ferramenta que permite o embasamento da resposta do modelo com contexto geoespacial relacionado à consulta do usuário.

Representação JSON 
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "codeExecution": {
    object (CodeExecution)
  },
  "googleSearch": {
    object (GoogleSearch)
  },
  "computerUse": {
    object (ComputerUse)
  },
  "urlContext": {
    object (UrlContext)
  },
  "fileSearch": {
    object (FileSearch)
  },
  "mcpServers": [
    {
      object (McpServer)
    }
  ],
  "googleMaps": {
    object (GoogleMaps)
  }
}

FunctionDeclaration

Representação estruturada de uma declaração de função, conforme definido pela especificação OpenAPI 3.03. O nome e os parâmetros da função estão incluídos nessa declaração. Essa FunctionDeclaration é uma representação de um bloco de código que pode ser usado como uma Tool pelo modelo e executado pelo cliente.

Campos
name string

Obrigatório. O nome da função. Precisa ser az, AZ, 0-9 ou conter sublinhados, dois-pontos, pontos e traços, com um tamanho máximo de 128.

description string

Obrigatório. Uma breve descrição da função.

behavior enum (Behavior)

Opcional. Especifica o comportamento da função. No momento, só é compatível com o método BidiGenerateContent.

parameters object (Schema)

Opcional. Descreve os parâmetros dessa função. Reflete a chave de string do objeto de parâmetro da API aberta 3.03: o nome do parâmetro. Os nomes de parâmetros diferenciam maiúsculas de minúsculas. Valor do esquema: o esquema que define o tipo usado para o parâmetro.

parametersJsonSchema value (Value format)

Opcional. Descreve os parâmetros da função no formato de esquema JSON. O esquema precisa descrever um objeto em que as propriedades são os parâmetros da função. Exemplo:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "additionalProperties": false,
  "required": ["name", "age"],
  "propertyOrdering": ["name", "age"]
}

Esse campo é mutuamente exclusivo com parameters.

response object (Schema)

Opcional. Descreve a saída dessa função no formato de esquema JSON. Reflete o objeto de resposta da API aberta 3.03. O esquema define o tipo usado para o valor da resposta da função.

responseJsonSchema value (Value format)

Opcional. Descreve a saída dessa função no formato de esquema JSON. O valor especificado pelo esquema é o valor da resposta da função.

Esse campo é mutuamente exclusivo com response.

Representação JSON 
{
  "name": string,
  "description": string,
  "behavior": enum (Behavior),
  "parameters": {
    object (Schema)
  },
  "parametersJsonSchema": value,
  "response": {
    object (Schema)
  },
  "responseJsonSchema": value
}

Esquema

O objeto Schema permite a definição de tipos de dados de entrada e saída. Esses tipos podem ser objetos, mas também primitivos e matrizes. Representa um subconjunto selecionado de um objeto de esquema da OpenAPI 3.0.

Campos
type enum (Type)

Obrigatório. Tipo de dados.

format string

Opcional. O formato dos dados. Qualquer valor é permitido, mas a maioria não aciona nenhuma funcionalidade especial.

title string

Opcional. O título do esquema.

description string

Opcional. Uma breve descrição do parâmetro. Isso pode conter exemplos de uso. A descrição do parâmetro pode ser formatada como Markdown.

nullable boolean

Opcional. Indica se o valor pode ser nulo.

enum[] string

Opcional. Valores possíveis do elemento de Type.STRING com formato de enumeração. Por exemplo, podemos definir uma direção de tipo enumerado como : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

maxItems string (int64 format)

Opcional. Número máximo de elementos para Type.ARRAY.

minItems string (int64 format)

Opcional. Número mínimo de elementos para Type.ARRAY.

properties map (key: string, value: object (Schema))

Opcional. Propriedades de Type.OBJECT.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

required[] string

Opcional. Propriedades obrigatórias de Type.OBJECT.

minProperties string (int64 format)

Opcional. Número mínimo de propriedades para Type.OBJECT.

maxProperties string (int64 format)

Opcional. Número máximo de propriedades para Type.OBJECT.

minLength string (int64 format)

Opcional. CAMPOS DE ESQUEMA PARA O TIPO STRING Comprimento mínimo do Type.STRING

maxLength string (int64 format)

Opcional. Comprimento máximo de Type.STRING

pattern string

Opcional. Padrão do Type.STRING para restringir uma string a uma expressão regular.

example value (Value format)

Opcional. Exemplo do objeto. Só será preenchido quando o objeto for a raiz.

anyOf[] object (Schema)

Opcional. O valor precisa ser validado em relação a qualquer um (um ou mais) dos subesquemas na lista.

propertyOrdering[] string

Opcional. A ordem das propriedades. Não é um campo padrão na especificação OpenAPI. Usado para determinar a ordem das propriedades na resposta.

default value (Value format)

Opcional. Valor padrão do campo. De acordo com o esquema JSON, esse campo é destinado a geradores de documentação e não afeta a validação. Assim, ele é incluído aqui e ignorado para que os desenvolvedores que enviam esquemas com um campo default não recebam erros de campo desconhecido.

items object (Schema)

Opcional. Esquema dos elementos de Type.ARRAY.

minimum number

Opcional. CAMPOS DE ESQUEMA PARA TIPO INTEGER e NUMBER Valor mínimo de Type.INTEGER e Type.NUMBER

maximum number

Opcional. Valor máximo de Type.INTEGER e Type.NUMBER

Representação JSON 
{
  "type": enum (Type),
  "format": string,
  "title": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "minProperties": string,
  "maxProperties": string,
  "minLength": string,
  "maxLength": string,
  "pattern": string,
  "example": value,
  "anyOf": [
    {
      object (Schema)
    }
  ],
  "propertyOrdering": [
    string
  ],
  "default": value,
  "items": {
    object (Schema)
  },
  "minimum": number,
  "maximum": number
}

Tipo

O tipo contém a lista de tipos de dados da OpenAPI, conforme definido em https://spec.openapis.org/oas/v3.0.3#data-types

Tipos enumerados
TYPE_UNSPECIFIED Não especificado, não deve ser usado.
STRING Tipo de string.
NUMBER Tipo de número.
INTEGER Tipo inteiro.
BOOLEAN Tipo booleano.
ARRAY Tipo de matriz.
OBJECT Tipo de objeto.
NULL Tipo nulo.

Comportamento

Define o comportamento da função. O valor padrão é BLOCKING.

Tipos enumerados
UNSPECIFIED Esse valor não é usado.
BLOCKING Se definido, o sistema vai esperar receber a resposta da função antes de continuar a conversa.
NON_BLOCKING Se definido, o sistema não vai esperar para receber a resposta da função. Em vez disso, ele vai tentar processar as respostas de função à medida que elas ficarem disponíveis, mantendo a conversa entre o usuário e o modelo.

GoogleSearchRetrieval

Ferramenta para recuperar dados públicos da Web para embasamento, desenvolvida pelo Google.

Campos
dynamicRetrievalConfig object (DynamicRetrievalConfig)

Especifica a configuração de recuperação dinâmica para a origem especificada.

Representação JSON 
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfig)
  }
}

DynamicRetrievalConfig

Descreve as opções para personalizar a recuperação dinâmica.

Campos
mode enum (Mode)

O modo do preditor a ser usado na recuperação dinâmica.

dynamicThreshold number

O limite a ser usado na recuperação dinâmica. Se não for definido, um valor padrão do sistema será usado.

Representação JSON 
{
  "mode": enum (Mode),
  "dynamicThreshold": number
}

Modo

O modo do preditor a ser usado na recuperação dinâmica.

Tipos enumerados
MODE_UNSPECIFIED Sempre acionar a recuperação.
MODE_DYNAMIC Executar a recuperação somente quando o sistema decidir que é necessário.

CodeExecution

Esse tipo não tem campos.

Ferramenta que executa o código gerado pelo modelo e retorna automaticamente o resultado para ele.

Consulte também ExecutableCode e CodeExecutionResult, que só são gerados ao usar essa ferramenta.

GoogleSearch

Tipo de ferramenta GoogleSearch. Ferramenta para oferecer suporte à Pesquisa Google no modelo. Tecnologia do Google.

Campos
timeRangeFilter object (Interval)

Opcional. Filtre os resultados da pesquisa para um período específico. Se os clientes definirem um horário de início, eles também precisarão definir um horário de término (e vice-versa).

searchTypes object (SearchTypes)

Opcional. O conjunto de tipos de pesquisa a serem ativados. Se não for definida, a pesquisa na Web será ativada por padrão.

Representação JSON 
{
  "timeRangeFilter": {
    object (Interval)
  },
  "searchTypes": {
    object (SearchTypes)
  }
}

Intervalo

Representa um intervalo de tempo, codificado como um início de carimbo de data/hora (incluído) e um fim de carimbo de data/hora (não incluído).

O início precisa ser menor ou igual ao fim. Quando o início é igual ao fim, o intervalo fica vazio (não corresponde a nenhum horário). Quando o início e o fim não são especificados, o intervalo corresponde a qualquer momento.

Campos
startTime string (Timestamp format)

Opcional. Início inclusivo do intervalo.

Se especificado, um carimbo de data/hora correspondente a esse intervalo precisará ser igual ou posterior ao início.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

endTime string (Timestamp format)

Opcional. Fim exclusivo do intervalo.

Se especificado, um carimbo de data/hora correspondente a esse intervalo precisará ser anterior ao fim.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

Representação JSON 
{
  "startTime": string,
  "endTime": string
}

SearchTypes

Diferentes tipos de pesquisa que podem ser ativados na ferramenta GoogleSearch.

Campos
Representação JSON 
{
  "webSearch": {
    object (WebSearch)
  },
  "imageSearch": {
    object (ImageSearch)
  }
}

WebSearch

Esse tipo não tem campos.

Pesquisa na Web padrão para embasamento e configurações relacionadas.

ImageSearch

Esse tipo não tem campos.

Pesquisa por imagens para embasamento e configurações relacionadas.

ComputerUse

Tipo de ferramenta "Uso do computador".

Campos
environment enum (Environment)

Obrigatório. O ambiente em operação.

excludedPredefinedFunctions[] string

Opcional. Por padrão, as funções predefinidas são incluídas na chamada do modelo final. Alguns deles podem ser excluídos explicitamente da inclusão automática. Isso pode ter duas finalidades: 1. Usar um espaço de ação mais restrito / diferente. 2. Melhorar as definições / instruções de funções predefinidas.

Representação JSON 
{
  "environment": enum (Environment),
  "excludedPredefinedFunctions": [
    string
  ]
}

Ambiente

Representa o ambiente em que a operação está sendo realizada, como um navegador da Web.

Tipos enumerados
ENVIRONMENT_UNSPECIFIED O padrão é "browser".
ENVIRONMENT_BROWSER Funciona em um navegador da Web.

UrlContext

Esse tipo não tem campos.

Ferramenta para oferecer suporte à recuperação de contexto de URL.

FileSearch

A ferramenta FileSearch que recupera conhecimento de corpora de recuperação semântica. Os arquivos são importados para os corpus da recuperação semântica usando a API ImportFile.

Campos
fileSearchStoreNames[] string

Obrigatório. Os nomes dos fileSearchStores a serem recuperados. Exemplo: fileSearchStores/my-file-search-store-123

metadataFilter string

Opcional. Filtro de metadados a ser aplicado aos documentos e partes da recuperação semântica.

topK integer

Opcional. O número de partes da recuperação semântica a serem recuperadas.

Representação JSON 
{
  "fileSearchStoreNames": [
    string
  ],
  "metadataFilter": string,
  "topK": integer
}

McpServer

Um MCPServer é um servidor que pode ser chamado pelo modelo para realizar ações. É um servidor que implementa o protocolo MCP. Próximo ID: 5

Campos
name string

O nome do MCPServer.

transport Union type
O transporte usado para se conectar ao MCPServer. transport pode ser apenas de um dos tipos a seguir:
streamableHttpTransport object (StreamableHttpTransport)

Um transporte que pode transmitir solicitações e respostas HTTP.

Representação JSON 
{
  "name": string,

  // transport
  "streamableHttpTransport": {
    object (StreamableHttpTransport)
  }
  // Union type
}

StreamableHttpTransport

Um transporte que pode transmitir solicitações e respostas HTTP. Próximo código: 4

Campos
url string

O URL completo do endpoint MCPServer. Exemplo: "https://api.example.com/mcp"

headers map (key: string, value: string)

Opcional: campos para cabeçalhos de autenticação, tempos limite etc., se necessário.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

timeout string (Duration format)

Tempo limite de HTTP para operações regulares.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

sseReadTimeout string (Duration format)

Tempo limite para operações de leitura de SSE.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

terminateOnClose boolean

Define se a sessão do cliente será fechada quando o transporte for fechado.

Representação JSON 
{
  "url": string,
  "headers": {
    string: string,
    ...
  },
  "timeout": string,
  "sseReadTimeout": string,
  "terminateOnClose": boolean
}

GoogleMaps

A ferramenta do Google Maps que fornece contexto geoespacial para a consulta do usuário.

Campos
enableWidget boolean

Opcional. Se um token de contexto de widget vai ser retornado no GroundingMetadata da resposta. Os desenvolvedores podem usar o token de contexto do widget para renderizar um widget do Google Maps com contexto geoespacial relacionado aos lugares que o modelo referencia na resposta.

Representação JSON 
{
  "enableWidget": boolean
}

ToolConfig

A configuração da ferramenta que contém parâmetros para especificar o uso de Tool na solicitação.

Campos
functionCallingConfig object (FunctionCallingConfig)

Opcional. Configuração de chamada de função.

retrievalConfig object (RetrievalConfig)

Opcional. Configuração de recuperação.

includeServerSideToolInvocations boolean

Opcional. Se for verdadeiro, a resposta da API vai incluir as chamadas e respostas de ferramentas do lado do servidor na mensagem Content. Isso permite que os clientes observem as interações de ferramentas do servidor.

Representação JSON 
{
  "functionCallingConfig": {
    object (FunctionCallingConfig)
  },
  "retrievalConfig": {
    object (RetrievalConfig)
  },
  "includeServerSideToolInvocations": boolean
}

FunctionCallingConfig

Configuração para especificar o comportamento da chamada de função.

Campos
mode enum (Mode)

Opcional. Especifica o modo em que a chamada de função será executada. Se não for especificado, o valor padrão será AUTO.

allowedFunctionNames[] string

Opcional. Um conjunto de nomes de funções que, quando fornecidos, limitam as funções que o modelo vai chamar.

Isso só deve ser definido quando o modo é "ANY" ou "VALIDATED". Os nomes das funções precisam corresponder a [FunctionDeclaration.name]. Quando definido, o modelo prevê uma chamada de função apenas com nomes de função permitidos.

Representação JSON 
{
  "mode": enum (Mode),
  "allowedFunctionNames": [
    string
  ]
}

Modo

Define o comportamento de execução para chamadas de função definindo o modo de execução.

Tipos enumerados
MODE_UNSPECIFIED Modo de chamada de função não especificado. Esse valor não deve ser usado.
AUTO Comportamento padrão do modelo, em que ele decide prever uma chamada de função ou uma resposta de linguagem natural.
ANY O modelo é restrito a sempre prever apenas uma chamada de função. Se "allowedFunctionNames" estiver definido, a chamada de função prevista será limitada a qualquer um dos "allowedFunctionNames". Caso contrário, a chamada de função prevista será qualquer uma das "functionDeclarations" fornecidas.
NONE O modelo não vai prever nenhuma chamada de função. O comportamento do modelo é o mesmo que ocorre quando nenhuma declaração de função é transmitida.
VALIDATED O modelo decide prever uma chamada de função ou uma resposta de linguagem natural, mas valida as chamadas de função com decodificação restrita. Se "allowedFunctionNames" estiver definido, a chamada de função prevista será limitada a qualquer um dos "allowedFunctionNames". Caso contrário, a chamada de função prevista será qualquer uma das "functionDeclarations" fornecidas.

RetrievalConfig

Configuração de recuperação.

Campos
latLng object (LatLng)

Opcional. O local do usuário.

languageCode string

Opcional. O código de idioma do usuário. Código do idioma do conteúdo. Use tags de idioma definidas pelo BCP47 (em inglês).

Representação JSON 
{
  "latLng": {
    object (LatLng)
  },
  "languageCode": string
}

LatLng

Um objeto que representa um par de latitude/longitude. Ele é expresso como um par de valores duplos para representar graus de latitude e longitude. A menos que especificado de outra forma, esse objeto precisa seguir o padrão WGS84. Os valores precisam estar dentro de intervalos normalizados.

Campos
latitude number

A latitude em graus. Precisa estar no intervalo [-90,0, +90,0].

longitude number

A longitude em graus. Precisa estar no intervalo [-180,0, +180,0].

Representação JSON 
{
  "latitude": number,
  "longitude": number
}

UsageMetadata

Metadados sobre o uso do conteúdo armazenado em cache.

Campos
totalTokenCount integer

Número total de tokens consumidos pelo conteúdo armazenado em cache.

Representação JSON 
{
  "totalTokenCount": integer
}