Configurações de segurança

A API Gemini oferece configurações de segurança que podem ser ajustadas durante o estágio de prototipagem para determinar se o aplicativo requer uma configuração de segurança mais ou menos restritiva. É possível ajustar essas configurações em categorias de filtros para restringir ou permitir determinados tipos de conteúdo.

Este guia aborda como definir configurações de segurança em uma interação, o que acontece quando o conteúdo é bloqueado e quais categorias e limites podem ser usados.

Definir configurações de segurança

Transmita uma lista de safety_settings ao criar uma interação. Cada configuração emparelha uma categoria de dano (type) com um limite de bloqueio (threshold).

O exemplo a seguir define a categoria de discurso de ódio (hate_speech) como block_low_and_above, que bloqueia qualquer conteúdo que tenha uma probabilidade baixa ou maior de ser discurso de ódio:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Some potentially unsafe prompt.",
    safety_settings=[
        {
            "type": "hate_speech",
            "threshold": "block_low_and_above",
        }
    ],
)

print(interaction.output_text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Some potentially unsafe prompt.",
    safety_settings: [
      {
        type: "hate_speech",
        threshold: "block_low_and_above",
      },
    ],
  });
  console.log(interaction.output_text);
}

await main();

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.HarmCategory;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.SafetySetting;
import com.google.genai.gaos.models.interactions.Threshold;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

SafetySetting hateSpeechSafety =
    SafetySetting.builder()
        .type(HarmCategory.HATE_SPEECH)
        .threshold(Threshold.BLOCK_LOW_AND_ABOVE)
        .build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Some potentially unsafe prompt."))
        .safetySettings(List.of(hateSpeechSafety))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Some potentially unsafe prompt."),
            SafetySettings: []interactions.SafetySetting{
                {
                    Type:      interactions.HarmCategoryHateSpeech,
                    Threshold: interactions.ThresholdBlockLowAndAbove,
                },
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Some potentially unsafe prompt.",
    "safety_settings": [
      {"type": "hate_speech", "threshold": "block_low_and_above"}
    ]
  }'

É possível incluir uma configuração por categoria. As categorias não definidas usam o limite padrão, que é Desativado para modelos do Gemini 2.5 e mais recentes.

Quando o conteúdo é bloqueado

Se um filtro de segurança bloquear a entrada ou a resposta do modelo, a interação vai falhar com um erro HTTP 400. O conteúdo bloqueado não é retornado.

O code de erro informa por que a solicitação foi bloqueada:

• safety: a entrada ou resposta foi bloqueada por um filtro de segurança.
• jailbreak, prohibited_content ou blocklist: a entrada foi bloqueada por esse motivo. A message de erro começa com Input blocked:.

Exemplo:

{
  "error": {
    "code": "safety",
    "message": "Request blocked due to safety violations (harmful content). Please modify your input and retry."
  }
}

Para interações em segundo plano (background=true), o status da interação é definido como failed, e o mesmo code e message aparecem na lista errors. Ao fazer streaming, o erro chega como um evento error.

Filtros de segurança

Os filtros de segurança ajustáveis da API Gemini abrangem as seguintes categorias:

Use esses filtros para ajustar o que for necessário conforme seu caso de uso. Por exemplo, se você estiver criando um diálogo de videogame, poderá considerar aceitável permitir mais conteúdo classificado como Perigoso devido à natureza do jogo.

Além dos filtros de segurança ajustáveis, a API Gemini tem proteções integradas contra danos principais, como conteúdo que coloca crianças em risco. Esses tipos de dano são sempre bloqueados e não podem ser ajustados.

Limites de bloqueio

Devido à segurança inerente do modelo, outros filtros são Desativados por padrão. O comportamento padrão do modelo abrange a maioria dos casos de uso. Portanto, ajuste essas configurações apenas se elas forem necessárias de forma consistente para seu aplicativo.

A tabela a seguir descreve os limites que podem ser definidos para cada categoria. Por exemplo, se você definir Discurso de ódio como Bloquear poucos (block_only_high), o conteúdo com alta probabilidade de ser discurso de ódio será bloqueado, e qualquer conteúdo com uma probabilidade menor será permitido.

Probabilidade x gravidade

A API Gemini classifica a probabilidade de conteúdo não seguro como alta, média, baixa ou insignificante. Ela bloqueia o conteúdo com base nessa probabilidade, não na gravidade do dano. Alguns conteúdos podem ter uma baixa probabilidade de não serem seguros, mesmo que o dano possa ser grave. Por exemplo, compare estas frases:

1. O robô me bateu.
2. O robô me cortou.

A primeira frase pode ter uma probabilidade maior de não ser segura, mas a segunda pode ser considerada mais grave. Teste com cuidado para encontrar o nível de bloqueio que oferece suporte ao seu caso de uso, minimizando os danos aos usuários finais.

Ajustar as configurações de segurança no Google AI Studio

Clique em Configurações de segurança em Configurações avançadas no painel Executar configurações para abrir o modal Executar configurações de segurança. No modal, é possível usar os controles deslizantes para ajustar o nível de filtragem de conteúdo por categoria de segurança:

Quando você envia uma solicitação (por exemplo, fazendo uma pergunta ao modelo), uma warning Conteúdo bloqueado mensagem aparece se o conteúdo da solicitação for bloqueado. Para mais detalhes, mantenha o ponteiro sobre o texto Conteúdo bloqueado para conferir a categoria e a probabilidade da classificação de dano.

Próximas etapas

• Consulte a referência da API Interactions para saber mais sobre a API completa.
• Analise as orientações de segurança para ter uma visão geral das considerações de segurança ao desenvolver com LLMs.
• Saiba mais sobre como avaliar a probabilidade em relação à gravidade com a equipe do Jigsaw team.
• Saiba mais sobre os produtos que contribuem para soluções de segurança, como a API Perspective.