Güvenlik ayarları

Gemini API, uygulamanızın daha kısıtlayıcı veya daha az kısıtlayıcı bir güvenlik yapılandırması gerektirip gerektirmediğini belirlemek için prototip oluşturma aşamasında ayarlayabileceğiniz güvenlik ayarları sağlar. Belirli içerik türlerini kısıtlamak veya bunlara izin vermek için filtre kategorilerinde bu ayarları düzenleyebilirsiniz.

Bu kılavuzda, etkileşimlerde güvenlik ayarlarının nasıl yapılacağı, içerik engellendiğinde ne olacağı ve hangi kategorileri ve eşikleri kullanabileceğiniz açıklanmaktadır.

Güvenlik ayarlarını belirleme

Etkileşim oluştururken safety_settings listesi iletin. Her ayar, zarar kategorisini (type) engelleme eşiğiyle (threshold) eşleştirir.

Aşağıdaki örnekte, nefret söylemi (hate_speech) kategorisi block_low_and_above olarak ayarlanır. Bu ayar, nefret söylemi olma olasılığı düşük veya daha yüksek olan tüm içerikleri engeller:

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"}
    ]
  }'

Kategori başına bir ayar ekleyebilirsiniz. Ayarlamadığınız kategorilerde varsayılan eşik kullanılır. Bu eşik, Gemini 2.5 ve sonraki modeller için Kapalı'dır.

İçerik engellendiğinde

Bir güvenlik filtresi girişi veya modelin yanıtını engellerse etkileşim HTTP 400 hatasıyla başarısız olur. Engellenen içerik gösterilmez.

code hatası, isteğin neden engellendiğini gösterir:

• safety: Giriş veya yanıt, güvenlik filtresi tarafından engellendi.
• jailbreak, prohibited_content veya blocklist: Giriş bu nedenle engellendi. message hatası Input blocked: ile başlıyor.

Örneğin:

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

Arka plan etkileşimleri (background=true) için etkileşimin status değeri failed olarak ayarlanır ve aynı code ile message, errors listesinde görünür. Akış sırasında hata, error etkinliği olarak gelir.

Güvenlik filtreleri

Gemini API'nin ayarlanabilir güvenlik filtreleri aşağıdaki kategorileri kapsar:

Kullanım alanınıza göre ayarlamalar yapmak için bu filtreleri kullanabilirsiniz. Örneğin, video oyunu diyaloğu oluşturuyorsanız oyunun doğası gereği Tehlikeli olarak derecelendirilen daha fazla içeriğe izin vermeyi kabul edebilirsiniz.

Gemini API'de, ayarlanabilir güvenlik filtrelerinin yanı sıra çocuk güvenliğini tehlikeye atan içerikler gibi temel zararlara karşı yerleşik korumalar bulunur. Bu tür zararlar her zaman engellenir ve ayarlanamaz.

Engelleme eşikleri

Modelin doğasında bulunan güvenlik nedeniyle ek filtreler varsayılan olarak Kapalı'dır. Varsayılan model davranışı çoğu kullanım alanını kapsar. Bu nedenle, bu ayarları yalnızca uygulamanız için tutarlı bir şekilde gerekli olduğunda düzenlemeniz gerekir.

Aşağıdaki tabloda, her kategori için ayarlayabileceğiniz eşikler açıklanmaktadır. Örneğin, Nefret söylemi'ni Az sayıda engelle (block_only_high) olarak ayarlarsanız nefret söylemi olma olasılığı yüksek olan içerikler engellenir ve olasılığı daha düşük olan içeriklere izin verilir.

Olasılık ve önem düzeyi

Gemini API, içeriğin güvenli olmama olasılığını yüksek, orta, düşük veya önemsiz olarak değerlendirir. İçerikleri, zararın ciddiyetine göre değil, bu olasılığa göre engeller. Bazı içeriklerin güvenli olmama olasılığı düşük olsa da verebileceği zarar ciddi olabilir. Örneğin, şu cümleleri karşılaştırın:

1. Robot bana yumruk attı.
2. Robot beni kesti.

İlk cümlenin güvenli olmama olasılığı daha yüksek olsa da ikinci cümlenin daha ciddi olduğunu düşünebilirsiniz. Son kullanıcıların zarar görmesini en aza indirirken kullanım alanınızı destekleyen engelleme düzeyini bulmak için dikkatli bir şekilde test yapın.

Google AI Studio'da güvenlik ayarlarını düzenleme

Çalıştırma ayarları panelindeki Gelişmiş ayarlar bölümünde Güvenlik ayarları'nı tıklayarak Çalıştırma güvenlik ayarları modülünü açın. Modaldaki kaydırma çubuklarını kullanarak her güvenlik kategorisi için içerik filtreleme düzeyini ayarlayabilirsiniz:

Bir istek gönderdiğinizde (örneğin, modele bir soru sorduğunuzda) isteğin içeriği engellenirse warning İçerik engellendi mesajı gösterilir. Daha fazla ayrıntı görmek için işaretçiyi İçerik engellendi metninin üzerine getirin. Böylece kategori ve zararlı olma olasılığı sınıflandırmasını görebilirsiniz.

Sonraki adımlar

• API'nin tamamı hakkında daha fazla bilgi edinmek için Interactions API referansına bakın.
• LLM'lerle geliştirme yaparken dikkat edilmesi gereken güvenlik konularına genel bir bakış için güvenlik kılavuzunu inceleyin.
• Jigsaw ekibinin olasılık ve ciddiyet değerlendirmesi hakkında daha fazla bilgi edinin.
• Perspective API gibi güvenlik çözümlerine katkıda bulunan ürünler hakkında daha fazla bilgi edinin.