Flex-Inferenz

Die Gemini Flex API ist eine Inferenzebene, die im Vergleich zu Standardraten eine Kostenreduzierung von 50% bietet. Im Gegenzug werden variable Latenz und Best-Effort-Verfügbarkeit geboten. Sie ist für latenztolerante Arbeitslasten konzipiert, die eine synchrone Verarbeitung erfordern, aber nicht die Echtzeitleistung der Standard-API benötigen.

Flex verwenden

Wenn Sie das Flex-Modell verwenden möchten, geben Sie im Anfragetext service_tier als flex an. Standardmäßig wird für Anfragen die Standardstufe verwendet, wenn dieses Feld ausgelassen wird.

Python

from google import genai

client = genai.Client()

try:
    response = client.models.generate_content(
        model="gemini-3.5-flash",
        contents="Analyze this dataset for trends...",
        config={"service_tier": "flex"},
    )
    print(response.text)
except Exception as e:
    print(f"Flex request failed: {e}")

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  try {
    const response = await ai.models.generateContent({
      model: "gemini-3.5-flash",
      contents: "Analyze this dataset for trends...",
      config: { serviceTier: "flex" },
    });
    console.log(response.text);
  } catch (e) {
    console.log(`Flex request failed: ${e}`);
  }
}

await main();

Ok

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
)

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

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.5-flash",
        genai.Text("Analyze this dataset for trends..."),
        &genai.GenerateContentConfig{
            ServiceTier: "flex",
        },
    )
    if err != nil {
        log.Printf("Flex request failed: %v", err)
        return
    }
    fmt.Println(result.Text())
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "contents": [{
    "parts":[{"text": "Summarize the latest research on quantum computing."}]
  }],
  "service_tier": "flex"
}'

So funktioniert die Flex-Inferenz

Die Gemini Flex-Inferenz schließt die Lücke zwischen der Standard-API und der Bearbeitungszeit von 24 Stunden der Batch API. Dabei wird Rechenleistung außerhalb der Spitzenzeiten genutzt, die bei Bedarf reduziert werden kann. So wird eine kostengünstige Lösung für Hintergrundaufgaben und sequenzielle Workflows geboten.

Funktion Flex Priorität Standard Batch
Preise 50% Rabatt 75–100% mehr als bei Standard Standardpreis 50% Rabatt
Latenz Minuten (Ziel: 1–15 Minuten) Niedrig (Sekunden) Sekunden bis Minuten Bis zu 24 Stunden
Zuverlässigkeit Best-Effort-Ansatz (reduzierbar) Hoch (nicht löschbar) Hoch / Mittel bis hoch Hoch (für Durchsatz)
Schnittstelle Synchron Synchron Synchron Asynchron

Hauptvorteile

  • Kosteneffizienz: Erhebliche Einsparungen bei Evaluierungen, Hintergrund-Agents und Datenanreicherung, die nicht für die Produktion bestimmt sind.
  • Geringer Aufwand: Sie müssen keine Batch-Objekte, Job-IDs oder Polling verwalten. Fügen Sie Ihren vorhandenen Anfragen einfach einen einzelnen Parameter hinzu.
  • Synchrone Workflows: Ideal für sequenzielle API-Ketten, bei denen die nächste Anfrage von der Ausgabe der vorherigen abhängt. Dadurch sind sie flexibler als Batch-Workflows für agentische Workflows.

Anwendungsfälle

  • Offline-Bewertungen: Regressions- oder Leaderboard-Tests mit „LLM-as-a-Judge“ durchführen.
  • Hintergrund-Agents: Sequenzielle Aufgaben wie CRM-Aktualisierungen, Profilerstellung oder Inhaltsmoderation, bei denen eine Verzögerung von einigen Minuten akzeptabel ist.
  • Forschung mit beschränktem Budget: Akademische Experimente, für die ein hohes Tokenvolumen bei beschränktem Budget erforderlich ist.

Ratenlimits

Flex-Inferenz-Traffic wird auf Ihre allgemeinen Ratenbegrenzungen angerechnet. Es gelten keine erweiterten Ratenbegrenzungen wie bei der Batch API.

Abschaltbare Kapazität

Flex-Traffic wird mit niedrigerer Priorität behandelt. Bei einem Anstieg des Standard-Traffics können Flex-Anfragen unterbrochen oder beendet werden, um Kapazität für Nutzer mit hoher Priorität zu schaffen. Wenn Sie eine Prioritätsinferenz durchführen möchten, lesen Sie den Abschnitt Prioritätsinferenz.

Fehlercodes

Wenn Flex-Kapazität nicht verfügbar ist oder das System überlastet ist, gibt die API Standardfehlercodes zurück:

  • 503 Service Unavailable: Das System ist derzeit ausgelastet.
  • 429 Too Many Requests (429 Zu viele Anfragen): Ratenbegrenzungen oder Ressourcenerschöpfung.

Verantwortung des Kunden

  • Kein serverseitiges Fallback: Um unerwartete Gebühren zu vermeiden, wird eine Flex-Anfrage nicht automatisch auf die Standard-Stufe aktualisiert, wenn die Flex-Kapazität ausgeschöpft ist.
  • Wiederholungsversuche: Sie müssen Ihre eigene clientseitige Wiederholungslogik mit exponentiellem Backoff implementieren.
  • Zeitüberschreitungen: Da Flex-Anfragen in einer Warteschlange stehen können, empfehlen wir, clientseitige Zeitüberschreitungen auf mindestens 10 Minuten zu erhöhen, um einen vorzeitigen Verbindungsabbruch zu vermeiden.

Zeitüberschreitungszeiträume anpassen

Sie können Zeitüberschreitungen pro Anfrage für die REST API und Clientbibliotheken konfigurieren und globale Zeitüberschreitungen nur bei Verwendung der Clientbibliotheken.

Achten Sie immer darauf, dass das clientseitige Zeitlimit das vorgesehene Server-Patience-Fenster abdeckt (z.B. 600 Sekunden und mehr für Flex-Warteschlangen). Die SDKs erwarten Zeitlimitwerte in Millisekunden.

Zeitlimits für Anfragen

Python

from google import genai

client = genai.Client()

try:
    response = client.models.generate_content(
        model="gemini-3.5-flash",
        contents="why is the sky blue?",
        config={
            "service_tier": "flex",
            "http_options": {"timeout": 900000}
        },
    )
except Exception as e:
    print(f"Flex request failed: {e}")

# Example with streaming
try:
    response = client.models.generate_content_stream(
        model="gemini-3.5-flash",
        contents=["List 5 ideas for a sci-fi movie."],
        config={
            "service_tier": "flex",
            "http_options": {"timeout": 60000}
        }
        # Per-request timeout for the streaming operation
    )
    for chunk in response:
        print(chunk.text, end="")

except Exception as e:
    print(f"An error occurred during streaming: {e}")

JavaScript

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

 const client = new GoogleGenAI({});

 async function main() {
     try {
         const response = await client.models.generateContent({
             model: "gemini-3.5-flash",
             contents: "why is the sky blue?",
             config: {
               serviceTier: "flex",
               httpOptions: {timeout: 900000}
             },
         });
     } catch (e) {
         console.log(`Flex request failed: ${e}`);
     }

     // Example with streaming
     try {
         const response = await client.models.generateContentStream({
             model: "gemini-3.5-flash",
             contents: ["List 5 ideas for a sci-fi movie."],
             config: {
                 serviceTier: "flex",
                 httpOptions: {timeout: 60000}
             },
         });
         for await (const chunk of response.stream) {
             process.stdout.write(chunk.text());
         }
     } catch (e) {
         console.log(`An error occurred during streaming: ${e}`);
     }
 }

 await main();

Ok

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/api/iterator"
    "google.golang.org/genai"
)

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

    timeoutCtx, cancel := context.WithTimeout(ctx, 900*time.Second)
    defer cancel()

    _, err = client.Models.GenerateContent(
        timeoutCtx,
        "gemini-3.5-flash",
        genai.Text("why is the sky blue?"),
        &genai.GenerateContentConfig{
            ServiceTier: "flex",
        },
    )
    if err != nil {
        fmt.Printf("Flex request failed: %v\n", err)
    }

    // Example with streaming
    streamTimeoutCtx, streamCancel := context.WithTimeout(ctx, 60*time.Second)
    defer streamCancel()

    iter := client.Models.GenerateContentStream(
        streamTimeoutCtx,
        "gemini-3.5-flash",
        genai.Text("List 5 ideas for a sci-fi movie."),
        &genai.GenerateContentConfig{
            ServiceTier: "flex",
        },
    )
    for {
        response, err := iter.Next()
        if err == iterator.Done {
            break
        }
        if err != nil {
            fmt.Printf("An error occurred during streaming: %v\n", err)
            break
        }
        fmt.Print(response.Candidates[0].Content.Parts[0])
    }
}

REST

Bei REST-Aufrufen können Sie Zeitüberschreitungen mit einer Kombination aus HTTP-Headern und curl-Optionen steuern:

  • X-Server-Timeout-Header (serverseitiges Zeitlimit): Dieser Header gibt ein bevorzugtes Zeitlimit (Standard: 600 Sekunden) für den Gemini API-Server an. Der Server versucht, dies zu berücksichtigen, aber es kann nicht garantiert werden. Der Wert sollte in Sekunden angegeben werden.

  • --max-time in curl (Client-Side Timeout): Mit der Option curl --max-time <seconds> wird ein hartes Limit für die Gesamtzeit (in Sekunden) festgelegt, die curl für den Abschluss des gesamten Vorgangs wartet. Dies ist eine clientseitige Sicherheitsmaßnahme.

 # Set a server timeout hint of 120 seconds and a client-side curl timeout of 125 seconds.
 curl --max-time 125 \
   -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent?key=$GEMINI_API_KEY" \
   -H "Content-Type: application/json" \
   -H "X-Server-Timeout: 120" \
   -d '{
   "contents": [{
     "parts":[{"text": "Summarize the latest research on quantum computing."}]
   }],
   "service_tier": "flex"
 }'

Globale Zeitlimits

Wenn Sie für alle API-Aufrufe, die über eine bestimmte genai.Client-Instanz (nur Clientbibliotheken) erfolgen, ein Standard-Timeout festlegen möchten, können Sie dies beim Initialisieren des Clients mit http_options und genai.types.HttpOptions konfigurieren.

Python

from google import genai
from google.genai import types

global_timeout_ms = 120000

client_with_global_timeout = genai.Client(
    http_options=types.HttpOptions(timeout=global_timeout_ms)
)

try:
    # Calling generate_content using global timeout...
    response = client_with_global_timeout.models.generate_content(
        model="gemini-3.5-flash",
        contents="Summarize the history of AI development since 2000.",
        config={"service_tier": "flex"},
    )
    print(response.text)

    # A per-request timeout will *override* the global timeout for that specific call.
    shorter_timeout = 30000
    response = client_with_global_timeout.models.generate_content(
        model="gemini-3.5-flash",
        contents="Provide a very brief definition of machine learning.",
        config={
            "service_tier": "flex",
            "http_options":{"timeout": shorter_timeout}
        }  # Overrides the global timeout
    )

    print(response.text)

except TimeoutError:
    print(
        f"A GenerateContent call timed out. Check if the global or per-request timeout was exceeded."
    )
except Exception as e:
    print(f"An error occurred: {e}")

JavaScript

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

const globalTimeoutMs = 120000;

const clientWithGlobalTimeout = new GoogleGenAI({httpOptions: {timeout: globalTimeoutMs}});

async function main() {
    try {
        // Calling generate_content using global timeout...
        const response1 = await clientWithGlobalTimeout.models.generateContent({
            model: "gemini-3.5-flash",
            contents: "Summarize the history of AI development since 2000.",
            config: { serviceTier: "flex" },
        });
        console.log(response1.text());

        // A per-request timeout will *override* the global timeout for that specific call.
        const shorterTimeout = 30000;
        const response2 = await clientWithGlobalTimeout.models.generateContent({
            model: "gemini-3.5-flash",
            contents: "Provide a very brief definition of machine learning.",
            config: {
                serviceTier: "flex",
                httpOptions: {timeout: shorterTimeout}
            }  // Overrides the global timeout
        });

        console.log(response2.text());

    } catch (e) {
        if (e.name === 'TimeoutError' || e.message?.includes('timeout')) {
            console.log(
                "A GenerateContent call timed out. Check if the global or per-request timeout was exceeded."
            );
        } else {
            console.log(`An error occurred: ${e}`);
        }
    }
}

await main();

Ok

 package main

 import (
     "context"
     "fmt"
     "log"
     "time"

     "google.golang.org/genai"
 )

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

     model := client.GenerativeModel("gemini-3.5-flash")

     // Go uses context for timeouts, not client options.
     // Set a default timeout for requests.
     globalTimeout := 120 * time.Second
     fmt.Printf("Using default timeout of %v seconds.\n", globalTimeout.Seconds())

     fmt.Println("Calling generate_content (using default timeout)...")
     ctx1, cancel1 := context.WithTimeout(ctx, globalTimeout)
     defer cancel1()
     resp1, err := model.GenerateContent(ctx1, genai.Text("Summarize the history of AI development since 2000."), &genai.GenerateContentConfig{ServiceTier: "flex"})
     if err != nil {
         log.Printf("Request 1 failed: %v", err)
     } else {
         fmt.Println("GenerateContent 1 successful.")
         fmt.Println(resp1.Text())
     }

     // A different timeout can be used for other requests.
     shorterTimeout := 30 * time.Second
     fmt.Printf("\nCalling generate_content with a shorter timeout of %v seconds...\n", shorterTimeout.Seconds())
     ctx2, cancel2 := context.WithTimeout(ctx, shorterTimeout)
     defer cancel2()
     resp2, err := model.GenerateContent(ctx2, genai.Text("Provide a very brief definition of machine learning."), &genai.GenerateContentConfig{
         ServiceTier: "flex",
     })
     if err != nil {
         log.Printf("Request 2 failed: %v", err)
     } else {
         fmt.Println("GenerateContent 2 successful.")
         fmt.Println(resp2.Text())
     }
 }

Wiederholungsversuche implementieren

Da Flex abwerfbar ist und mit 503-Fehlern fehlschlägt, finden Sie hier ein Beispiel für die optionale Implementierung einer Wiederholungslogik, um mit fehlgeschlagenen Anfragen fortzufahren:

Python

import time
from google import genai

client = genai.Client()

def call_with_retry(max_retries=3, base_delay=5):
    for attempt in range(max_retries):
        try:
            return client.models.generate_content(
                model="gemini-3.5-flash",
                contents="Analyze this batch statement.",
                config={"service_tier": "flex"},
            )
        except Exception as e:
            # Check for 503 Service Unavailable or 429 Rate Limits
            print(e.code)
            if attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt) # Exponential Backoff
                print(f"Flex busy, retrying in {delay}s...")
                time.sleep(delay)
            else:
                # Fallback to standard on last strike (Optional)
                print("Flex exhausted, falling back to Standard...")
                return client.models.generate_content(
                    model="gemini-3.5-flash",
                    contents="Analyze this batch statement."
                )

# Usage
response = call_with_retry()
print(response.text)

JavaScript

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

 const ai = new GoogleGenAI({});

 async function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }

 async function callWithRetry(maxRetries = 3, baseDelay = 5) {
   for (let attempt = 0; attempt < maxRetries; attempt++) {
     try {
       console.log(`Attempt ${attempt + 1}: Calling Flex tier...`);
       const response = await ai.models.generateContent({
         model: "gemini-3.5-flash",
         contents: "Analyze this batch statement.",
         config: { serviceTier: 'flex' },
       });
       return response;
     } catch (e) {
       if (attempt < maxRetries - 1) {
         const delay = baseDelay * (2 ** attempt);
         console.log(`Flex busy, retrying in ${delay}s...`);
         await sleep(delay * 1000);
       } else {
         console.log("Flex exhausted, falling back to Standard...");
         return await ai.models.generateContent({
           model: "gemini-3.5-flash",
           contents: "Analyze this batch statement.",
         });
       }
     }
   }
 }

 async function main() {
     const response = await callWithRetry();
     console.log(response.text);
 }

 await main();

Ok

 package main

 import (
     "context"
     "fmt"
     "log"
     "math"
     "time"

     "google.golang.org/genai"
 )

 func callWithRetry(ctx context.Context, client *genai.Client, maxRetries int, baseDelay time.Duration) (*genai.GenerateContentResponse, error) {
     modelName := "gemini-3.5-flash"
     content := genai.Text("Analyze this batch statement.")
     flexConfig := &genai.GenerateContentConfig{
         ServiceTier: "flex",
     }

     for attempt := 0; attempt < maxRetries; attempt++ {
         log.Printf("Attempt %d: Calling Flex tier...", attempt+1)
         resp, err := client.Models.GenerateContent(ctx, modelName, content, flexConfig)
         if err == nil {
             return resp, nil
         }

         log.Printf("Attempt %d failed: %v", attempt+1, err)

         if attempt < maxRetries-1 {
             delay := time.Duration(float64(baseDelay) * math.Pow(2, float64(attempt)))
             log.Printf("Flex busy, retrying in %v...", delay)
             time.Sleep(delay)
         } else {
             log.Println("Flex exhausted, falling back to Standard...")
             return client.Models.GenerateContent(ctx, modelName, content)
         }
     }
     return nil, fmt.Errorf("retries exhausted") // Should not be reached
 }

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

     resp, err := callWithRetry(ctx, client, 3, 5*time.Second)
     if err != nil {
         log.Fatalf("Failed after retries: %v", err)
     }
     fmt.Println(resp.Text())
 }

Preise

Die Flex-Inferenz kostet 50% der Standard-API und wird pro Token abgerechnet.

Unterstützte Modelle

Die folgenden Modelle unterstützen die Flex-Inferenz:

Modell Flex-Inferenz
Gemini 3.5 Flash ✔️
Gemini 3.1 Flash Lite ✔️
Gemini 3.1 Flash Lite (Vorschau) ✔️
Gemini 3.1 Pro (Vorabversion) ✔️
Gemini 3 Flash (Vorabversion) ✔️
Gemini 3 Pro Image (Vorabversion) ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash Image ✔️
Gemini 2.5 Flash Lite ✔️

Nächste Schritte

Weitere Informationen zu den anderen Inferenz- und Optimierungsoptionen von Gemini: